Crate ic_agent

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 Canister SDK 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 canister that performs network management operations. In this example, the call to the Internet Computer management canister (aaaaa-aa) creates a placeholder for a new canister by registering a network-specific identifier. The management canister then returns the result in the form of the textual representation of the canister identifier to the caller.

use ic_agent::Agent;
use ic_types::Principal;
use candid::{Encode, Decode, CandidType, Nat};
use serde::Deserialize;

#[derive(CandidType)]
struct Argument {
  amount: Option<Nat>,
}

#[derive(CandidType, Deserialize)]
struct CreateCanisterResult {
  canister_id: Principal,
}

async fn create_a_canister() -> Result<Principal, Box<dyn std::error::Error>> {
  let agent = Agent::builder()
    .with_url(URL)
    .with_identity(create_identity())
    .build()?;
  // Only do the following call when not contacting the IC main net (e.g. a local emulator).
  // This is important as the main net public key is static and a rogue network could return
  // a different key.
  // If you know the root key ahead of time, you can use `agent.set_root_key(root_key)?;`.
  agent.fetch_root_key().await?;
  let management_canister_id = Principal::from_text("aaaaa-aa")?;

  let waiter = garcon::Delay::builder()
    .throttle(std::time::Duration::from_millis(500))
    .timeout(std::time::Duration::from_secs(60 * 5))
    .build();

  // Create a call to the management canister to create a new canister ID,
  // and wait for a result.
  let response = agent.update(&management_canister_id, "provisional_create_canister_with_cycles")
    .with_arg(&Encode!(&Argument { amount: None})?)
    .call_and_wait(waiter)
    .await?;

  let result = Decode!(response.as_slice(), CreateCanisterResult)?;
  let canister_id: Principal = result.canister_id;
  Ok(canister_id)
}

let canister_id = create_a_canister().await.unwrap();
eprintln!("{}", canister_id);

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:

• Frequently Asked Questions
• DFINITY Canister SDK

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.

Re-exports

pub use agent::agent_error;
pub use agent::agent_error::AgentError;
pub use agent::Agent;
pub use identity::Identity;
pub use identity::Signature;
pub use request_id::to_request_id;
pub use request_id::RequestId;
pub use request_id::RequestIdError;

Modules

agent	The main Agent module. Contains the Agent type and all associated structures.
export	A module to re-export types that are visible through the ic-agent API.
identity	Types and traits dealing with identity across the Internet Computer.
request_id	This module deals with computing Request IDs based on the content of a message.

Structs

NonceFactory

A Factory for nonce blobs.