Struct ic_agent::agent::Agent [−][src]
pub struct Agent { /* fields omitted */ }
Expand description
A low level Agent to make calls to a Replica endpoint.
use ic_agent::{Agent, 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
Create an instance of an AgentBuilder
for building an Agent
. This is simpler than
using the AgentConfig
and Agent::new()
.
Create an instance of an Agent
.
Set the transport of the Agent
.
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.
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>
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>
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>
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.
Returns an UpdateBuilder enabling the construction of an update call without passing all arguments.
Calls and returns the information returned by the status endpoint of a replica.
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>
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
Auto Trait Implementations
impl !RefUnwindSafe for Agent
impl !UnwindSafe for Agent
Blanket Implementations
Mutably borrows from an owned value. Read more
Instruments this type with the provided Span
, returning an
Instrumented
wrapper. Read more
type Output = T
type Output = T
Should always be Self