Crate ic_agent

Expand description

The ic-agent is a simple-to-use library that enables you to build applications and interact with the Internet Computer in Rust. It serves as a Rust-based low-level backend for the DFINITY Canister Software Development Kit (SDK) and the command-line execution environment dfx.

§Overview

The ic-agent is a Rust crate that can connect directly to the Internet Computer through the Internet Computer protocol (ICP). The key software components of the ICP are broadly referred to as the replica.

The agent is designed to be compatible with multiple versions of the replica API, and to expose both low-level APIs for communicating with Internet Computer protocol components like the replica and to provide higher-level APIs for communicating with software applications deployed as canisters.

§Example

The following example illustrates how to use the Agent interface to send a call to an Internet Computer’s Ledger Canister to check the total ICP tokens supply.

use anyhow::{Context, Result};
use candid::{Decode, Nat};
use ic_agent::{export::Principal, Agent};
use url::Url;

pub async fn create_agent(url: Url, use_mainnet: bool) -> Result<Agent> {
   let agent = Agent::builder().with_url(url).build()?;
   if !use_mainnet {
       agent.fetch_root_key().await?;
   }
   Ok(agent)
}

#[tokio::main]
async fn main() -> Result<()> {
   // IC HTTP Gateway URL
   let url = Url::parse("https://ic0.app").unwrap();
   let agent = create_agent(url, true).await?;

   // ICP Ledger Canister ID
   let canister_id = Principal::from_text("ryjl3-tyaaa-aaaaa-aaaba-cai")?;

   // Method: icrc1_total_supply (takes no arguments, returns nat)
   let method_name = "icrc1_total_supply";

   // Encode empty Candid arguments
   let args = candid::encode_args(())?;

   // Dispatch query call
   let response = agent
       .query(&canister_id, method_name)
       .with_arg(args)
       .call()
       .await
       .context("Failed to query icrc1_total_supply method.")?;

   // Decode the response as nat
   let total_supply_nat =
       Decode!(&response, Nat).context("Failed to decode total supply as nat.")?;

   println!("Total ICP Supply: {} ICP", total_supply_nat);

   Ok(())
}

For more information about the Agent interface used in this example, see the Agent documentation.

§References

For an introduction to the Internet Computer and the DFINITY Canister SDK, see the following resources:

The Internet Computer protocol and interface specifications are not publicly available yet. When these specifications are made public and generally available, additional details about the versions supported will be available here.

Modules§

agent: The main Agent module. Contains the Agent type and all associated structures.
agent_error: Errors that can occur when using the replica agent.
export: A module to re-export types that are visible through the ic-agent API.
hash_tree: cf https://internetcomputer.org/docs/current/references/ic-interface-spec/#certification-encoding
identity: Types and traits dealing with identity across the Internet Computer.

Structs§

Agent: A low level Agent to make calls to a Replica endpoint.
NonceFactory: A Factory for nonce blobs.
RequestId: A Request ID.
Signature: A cryptographic signature, signed by an Identity.

Enums§

AgentError: An error that occurred when using the agent.
RequestIdError: An error during the calculation of the RequestId.
TransportCallResponse: The parsed response from a request to the v3 call endpoint. A request to the call endpoint.

Traits§

Identity: An Identity produces Signatures for requests or delegations. It knows or represents the Principal of the sender.
NonceGenerator: An interface for generating nonces.

Functions§

lookup_value: Looks up a value in the certificate’s tree at the specified hash.
to_request_id: Derive the request ID from a serializable data structure. This does not include the ic-request domain prefix.

Type Aliases§

Certificate: A Certificate as defined in https://internetcomputer.org/docs/current/references/ic-interface-spec/#certificate

Crate ic_agentCopy item path