Struct ic_agent::agent::Agent

pub struct Agent { /* fields omitted */ }

A low level Agent to make calls to a Replica endpoint.

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

#[derive(CandidType, Deserialize)]
struct CreateCanisterResult {
  canister_id: candid::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()?;
  agent.fetch_root_key().await?;
  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 = Principal::from_text(&result.canister_id.to_text())?;
  Ok(canister_id)
}

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

This agent does not understand Candid, and only acts on byte buffers.

Implementations

impl Agent

pub fn builder() -> AgentBuilder

Create an instance of an AgentBuilder for building an Agent. This is simpler than using the AgentConfig and Agent::new().

pub fn new(config: AgentConfig) -> Result<Agent, AgentError>

Create an instance of an Agent.

pub async fn fetch_root_key(&self) -> Result<(), AgentError>

Fetch the root key of the replica using its status end point, and update the agent’s root key. This only uses the agent’s specific upstream replica, and does not ensure the root key validity. In order to prevent any MITM attack, developers should try to contact multiple replicas.

The root key is necessary for validating state and certificates sent by the replica. By default, it is set to None and validating methods will return an error.

pub async fn request_status_raw(
    &self,
    request_id: &RequestId
) -> Result<RequestStatusResponse, AgentError>

pub fn update<S: Into<String>>(
    &self,
    canister_id: &Principal,
    method_name: S
) -> UpdateBuilder<'_>

Returns an UpdateBuilder enabling the construction of an update call without passing all arguments.

pub async fn status(&self) -> Result<Status, AgentError>

Calls and returns the information returned by the status endpoint of a replica.

pub fn query<S: Into<String>>(
    &self,
    canister_id: &Principal,
    method_name: S
) -> QueryBuilder<'_>

Returns a QueryBuilder enabling the construction of a query call without passing all arguments.