pub struct Agent { /* private fields */ }
Expand description
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("sehci-oaaaa-aaaaa-aaaaa-c").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 })?)
.call_and_wait()
.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§
source§impl Agent
impl Agent
sourcepub fn builder() -> AgentBuilder
pub fn builder() -> AgentBuilder
Create an instance of an AgentBuilder
for building an Agent
. This is simpler than
using the AgentConfig
and Agent::new()
.
sourcepub fn new(config: AgentConfig) -> Result<Agent, AgentError>
pub fn new(config: AgentConfig) -> Result<Agent, AgentError>
Create an instance of an Agent
.
sourcepub fn set_transport<F: 'static + ReplicaV2Transport>(&mut self, transport: F)
pub fn set_transport<F: 'static + ReplicaV2Transport>(&mut self, transport: F)
Set the transport of the Agent
.
sourcepub fn set_identity<I>(&mut self, identity: I)where
I: 'static + Identity,
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::poll the status of these messages.
sourcepub async fn fetch_root_key(&self) -> Result<(), AgentError>
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.
sourcepub fn set_root_key(&self, root_key: Vec<u8>) -> Result<(), AgentError>
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.
sourcepub fn get_principal(&self) -> Result<Principal, String>
pub fn get_principal(&self) -> Result<Principal, String>
Return the principal of the identity.
sourcepub async fn query_signed(
&self,
effective_canister_id: Principal,
signed_query: Vec<u8>
) -> Result<Vec<u8>, AgentError>
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.
sourcepub async fn update_signed(
&self,
effective_canister_id: Principal,
signed_update: Vec<u8>
) -> Result<RequestId, AgentError>
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.
sourcepub async fn poll(
&self,
request_id: &RequestId,
effective_canister_id: Principal
) -> Result<PollResult, AgentError>
pub async fn poll(
&self,
request_id: &RequestId,
effective_canister_id: Principal
) -> Result<PollResult, AgentError>
Call request_status on the RequestId once and classify the result
sourcepub async fn wait(
&self,
request_id: RequestId,
effective_canister_id: Principal
) -> Result<Vec<u8>, AgentError>
pub async fn wait(
&self,
request_id: RequestId,
effective_canister_id: Principal
) -> Result<Vec<u8>, AgentError>
Call request_status on the RequestId in a loop and return the response as a byte vector.
sourcepub async fn read_state_raw(
&self,
paths: Vec<Vec<Label>>,
effective_canister_id: Principal
) -> Result<Certificate<'_>, AgentError>
pub async fn read_state_raw(
&self,
paths: Vec<Vec<Label>>,
effective_canister_id: Principal
) -> Result<Certificate<'_>, AgentError>
Request the raw state tree directly. See the protocol docs for more information.
sourcepub fn verify(
&self,
cert: &Certificate<'_>,
effective_canister_id: Principal
) -> Result<(), AgentError>
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.
sourcepub async fn read_state_canister_info(
&self,
canister_id: Principal,
path: &str
) -> Result<Vec<u8>, AgentError>
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.
sourcepub async fn read_state_canister_metadata(
&self,
canister_id: Principal,
path: &str
) -> Result<Vec<u8>, AgentError>
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>
.
sourcepub async fn request_status_raw(
&self,
request_id: &RequestId,
effective_canister_id: Principal
) -> Result<RequestStatusResponse, AgentError>
pub async fn request_status_raw(
&self,
request_id: &RequestId,
effective_canister_id: Principal
) -> Result<RequestStatusResponse, AgentError>
Fetches the status of a particular request by its ID.
sourcepub async fn request_status_signed(
&self,
request_id: &RequestId,
effective_canister_id: Principal,
signed_request_status: Vec<u8>
) -> 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.
sourcepub fn update<S: Into<String>>(
&self,
canister_id: &Principal,
method_name: S
) -> UpdateBuilder<'_>
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.
sourcepub async fn status(&self) -> Result<Status, AgentError>
pub async fn status(&self) -> Result<Status, AgentError>
Calls and returns the information returned by the status endpoint of a replica.
sourcepub fn query<S: Into<String>>(
&self,
canister_id: &Principal,
method_name: S
) -> QueryBuilder<'_>
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.
sourcepub fn sign_request_status(
&self,
effective_canister_id: Principal,
request_id: RequestId
) -> Result<SignedRequestStatus, AgentError>
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