pub struct Agent { /* private fields */ }
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: 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
sourceimpl 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 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,
disable_range_check: bool
) -> Result<PollResult, AgentError>
pub async fn poll(
&self,
request_id: &RequestId,
effective_canister_id: Principal,
disable_range_check: bool
) -> Result<PollResult, AgentError>
Call request_status on the RequestId once and classify the result
sourcepub async fn wait<W: Waiter>(
&self,
request_id: RequestId,
effective_canister_id: Principal,
disable_range_check: bool,
waiter: W
) -> Result<Vec<u8>, AgentError>
pub async fn wait<W: Waiter>(
&self,
request_id: RequestId,
effective_canister_id: Principal,
disable_range_check: bool,
waiter: W
) -> 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,
disable_range_check: bool
) -> Result<Certificate<'_>, AgentError>
pub async fn read_state_raw(
&self,
paths: Vec<Vec<Label>>,
effective_canister_id: Principal,
disable_range_check: bool
) -> 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,
disable_range_check: bool
) -> Result<(), AgentError>
pub fn verify(
&self,
cert: &Certificate<'_>,
effective_canister_id: Principal,
disable_range_check: bool
) -> 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,
disable_range_check: bool
) -> Result<Vec<u8>, AgentError>
pub async fn read_state_canister_info(
&self,
canister_id: Principal,
path: &str,
disable_range_check: bool
) -> 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,
disable_range_check: bool
) -> Result<Vec<u8>, AgentError>
pub async fn read_state_canister_metadata(
&self,
canister_id: Principal,
path: &str,
disable_range_check: bool
) -> 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,
disable_range_check: bool
) -> Result<RequestStatusResponse, AgentError>
pub async fn request_status_raw(
&self,
request_id: &RequestId,
effective_canister_id: Principal,
disable_range_check: bool
) -> 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>,
disable_range_check: bool
) -> Result<RequestStatusResponse, AgentError>
pub async fn request_status_signed(
&self,
request_id: &RequestId,
effective_canister_id: Principal,
signed_request_status: Vec<u8>,
disable_range_check: bool
) -> 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
Trait Implementations
Auto Trait Implementations
impl !RefUnwindSafe for Agent
impl Send for Agent
impl Sync for Agent
impl Unpin for Agent
impl !UnwindSafe for Agent
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcefn clone_into(&self, target: &mut T)
fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
fn vzip(self) -> V
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more