Struct Agent

pub struct Agent { /* private fields */ }

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

use ic_agent::{Agent, export::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")?;

  // Create a call to the management canister to create a new canister ID,
  // and wait for a result.
  // The effective canister id must belong to the canister ranges of the subnet at which the canister is created.
  let effective_canister_id = Principal::from_text("rwlgt-iiaaa-aaaaa-aaaaa-cai").unwrap();
  let response = agent.update(&management_canister_id, "provisional_create_canister_with_cycles")
    .with_effective_canister_id(effective_canister_id)
    .with_arg(Encode!(&Argument { amount: None })?)
    .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.

Some methods return certificates. While there is a verify_certificate method, any certificate you receive from a method has already been verified and you do not need to manually verify it.

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_identity<I>(&mut self, identity: I)

where I: 'static + Identity,

Set the identity provider for signing messages.

NOTE: if you change the identity while having update calls in flight, you will not be able to Agent::request_status_raw the status of these messages.

pub fn set_arc_identity(&mut self, identity: Arc<dyn Identity>)

Set the arc identity provider for signing messages.

NOTE: if you change the identity while having update calls in flight, you will not be able to Agent::request_status_raw the status of these messages.

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>)

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 fn read_root_key(&self) -> Vec<u8>

Return the root key currently in use.

pub fn get_principal(&self) -> Result<Principal, String>

Return the principal of the identity.

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<CallResponse<Vec<u8>>, AgentError>

Send the signed update to the network. Will return a CallResponse<Vec<u8>>. 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 wait_signed( &self, request_id: &RequestId, effective_canister_id: Principal, signed_request_status: Vec<u8>, ) -> Result<(Vec<u8>, Certificate), AgentError>

Wait for request_status to return a Replied response and return the arg.

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

Call request_status on the RequestId in a loop and return the response as a byte vector.

pub async fn read_state_raw( &self, paths: Vec<Vec<Label>>, effective_canister_id: Principal, ) -> Result<Certificate, AgentError>

Request the raw state tree directly, under an effective canister ID. See the protocol docs for more information.

pub async fn read_subnet_state_raw( &self, paths: Vec<Vec<Label>>, subnet_id: Principal, ) -> Result<Certificate, AgentError>

Request the raw state tree directly, under a subnet ID. See the protocol docs for more information.

pub fn verify( &self, cert: &Certificate, effective_canister_id: Principal, ) -> Result<(), AgentError>

Verify a certificate, checking delegation if present. Only passes if the certificate also has authority over the canister.

pub fn verify_for_subnet( &self, cert: &Certificate, subnet_id: Principal, ) -> Result<(), AgentError>

Verify a certificate, checking delegation if present. Only passes if the certificate is for the specified subnet.

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

Request information about a particular canister for a single state subkey. See the protocol docs for more information.

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

Request the bytes of the canister’s custom section icp:public <path> or icp:private <path>.

pub async fn read_state_subnet_metrics( &self, subnet_id: Principal, ) -> Result<SubnetMetrics, AgentError>

Request a list of metrics about the subnet.

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

Fetches the status of a particular request by its ID.

pub async fn request_status_signed( &self, request_id: &RequestId, effective_canister_id: Principal, signed_request_status: Vec<u8>, ) -> Result<(RequestStatusResponse, Certificate), 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

pub async fn fetch_api_boundary_nodes_by_canister_id( &self, canister_id: Principal, ) -> Result<Vec<ApiBoundaryNode>, AgentError>

Retrieve all existing API boundary nodes from the state tree via endpoint /api/v2/canister/<effective_canister_id>/read_state

pub async fn fetch_api_boundary_nodes_by_subnet_id( &self, subnet_id: Principal, ) -> Result<Vec<ApiBoundaryNode>, AgentError>

Retrieve all existing API boundary nodes from the state tree via endpoint /api/v2/subnet/<subnet_id>/read_state

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.

impl Debug for Agent

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.