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, Nat};
use serde::Deserialize;

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

#[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()?;

  // 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 = 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 fn set_transport<F: 'static + ReplicaV2Transport + Send + Sync>(
    &mut self,
    transport: F
)

Set the transport of the Agent.

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

By default, the agent is configured to talk to the main Internet Computer, and verifies responses using a hard-coded public key.

This function will instruct the agent to ask the endpoint for its public key, and use that instead. This is required when talking to a local test instance, for example.

Only use this when you are not talking to the main Internet Computer, otherwise you are prone to man-in-the-middle attacks! Do not call this function by default.

pub fn set_root_key(&self, root_key: Vec<u8>) -> Result<(), AgentError>

By default, the agent is configured to talk to the main Internet Computer, and verifies responses using a hard-coded public key.

Using this function you can set the root key to a known one if you know if beforehand.

pub async fn query_signed(
    &self,
    effective_canister_id: Principal,
    signed_query: Vec<u8>
) -> Result<Vec<u8>, AgentError>

Send the signed query to the network. Will return a byte vector. The bytes will be checked if it is a valid query. If you want to inspect the fields of the query call, use signed_query_inspect before calling this method.

pub async fn update_signed(
    &self,
    effective_canister_id: Principal,
    signed_update: Vec<u8>
) -> Result<RequestId, AgentError>

Send the signed update to the network. Will return a RequestId. The bytes will be checked to verify that it is a valid update. If you want to inspect the fields of the update, use signed_update_inspect before calling this method.

pub async fn poll(
    &self,
    request_id: &RequestId,
    effective_canister_id: &Principal
) -> Result<PollResult, AgentError>

pub async fn wait<W: Waiter>(
    &self,
    request_id: RequestId,
    effective_canister_id: &Principal,
    waiter: W
) -> Result<Vec<u8>, AgentError>

pub async fn read_state_canister_info(
    &self,
    canister_id: Principal,
    path: &str
) -> Result<Vec<u8>, AgentError>

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

pub async fn request_status_signed(
    &self,
    request_id: &RequestId,
    effective_canister_id: Principal,
    signed_request_status: Vec<u8>
) -> Result<RequestStatusResponse, AgentError>

Send the signed request_status to the network. Will return RequestStatusResponse. The bytes will be checked to verify that it is a valid request_status. If you want to inspect the fields of the request_status, use signed_request_status_inspect before calling this method.

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.

pub fn sign_request_status(
    &self,
    effective_canister_id: Principal,
    request_id: RequestId
) -> Result<SignedRequestStatus, AgentError>

Sign a request_status call. This will return a signed::SignedRequestStatus which contains all fields of the request_status and the signed request_status in CBOR encoding

Trait Implementations

impl Clone for Agent

fn clone(&self) -> Agent

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.