Crate ic_agent

ic-agent is a simple to use library to interact with the Internet Computer in Rust. It is the backend for dfx.

About

ic-agent is a crate to talk directly to an ICP replica. It can handle multiple version of the Replica API, and exposes with both low level and high level APIs (like talking to canisters).

Example

The following examples show how to use the Agent low-level API to send a call to the management canister to create a new canister ID.

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

#[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()?;
  let management_canister_id = Principal::from_text("aaaaa-aa")?;

  let waiter = delay::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, "create_canister")
    .with_arg(&Encode!()?)  // Empty Candid.
    .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);

See the Documentation for more information.

References

The public specification of the Internet Computer is, at this moment, privately shared. When it is made public a reference to the version(s) supported will be available here.

Re-exports

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.

Enums

AgentError

Traits

PasswordManager

Implemented by the Agent environment to cache and update an HTTP Auth password. It returns a tuple of (username, password).