Struct ic_utils::canister::Canister

pub struct Canister<'agent, T = ()> { /* fields omitted */ }

Create an encapsulation of a Canister running on the Internet Computer. This supports making calls to methods, installing code if needed, and various utilities related to a canister.

This is the higher level construct for talking to a canister on the Internet Computer.

Implementations

impl<'agent, T> Canister<'agent, T>

pub fn canister_id_<'canister: 'agent>(&'canister self) -> &Principal

Get the canister ID of this canister.

pub fn interface_<'canister: 'agent>(&'canister self) -> &T

Get the interface object from this canister. Sometimes those interfaces might have custom methods that are useful.

pub fn update_<'canister: 'agent>(
    &'canister self,
    method_name: &str
) -> AsyncCallBuilder<'agent, 'canister, T>

Create an AsyncCallBuilder to do an update call.

pub fn query_<'canister: 'agent>(
    &'canister self,
    method_name: &str
) -> SyncCallBuilder<'agent, 'canister, T>

Create a SyncCallBuilder to do a query call.

impl<'agent, T> Canister<'agent, T> where
    T: Clone, 

pub fn clone_with_(&self, id: Principal) -> Self

impl<'agent> Canister<'agent, ()>

pub fn builder() -> CanisterBuilder<'agent, ()>

Create a CanisterBuilder instance to build a canister abstraction.

impl<'agent> Canister<'agent, HttpRequestCanister>

pub fn http_request<'canister: 'agent, M: Into<String>, U: Into<String>, B: AsRef<[u8]>>(
    &'canister self,
    method: M,
    url: U,
    headers: Vec<HeaderField>,
    body: B
) -> impl 'agent + SyncCall<(HttpResponse,)>

pub fn http_request_stream_callback<'canister: 'agent, M: Into<String>>(
    &'canister self,
    method: M,
    token: IDLValue
) -> impl 'agent + SyncCall<(StreamingCallbackHttpResponse,)>

impl<'agent> Canister<'agent, ManagementCanister>

pub fn canister_status<'canister: 'agent>(
    &'canister self,
    canister_id: &Principal
) -> impl 'agent + AsyncCall<(StatusCallResult,)>

Get the status of a canister.

pub fn create_canister<'canister: 'agent>(
    &'canister self
) -> impl 'agent + AsyncCall<(Principal,)>

Create a canister, returning a caller that returns a Canister Id.

pub fn deposit_cycles<'canister: 'agent>(
    &'canister self,
    canister_id: &Principal
) -> impl 'agent + AsyncCall<()>

This method deposits the cycles included in this call into the specified canister. Only the controller of the canister can deposit cycles.

pub fn delete_canister<'canister: 'agent>(
    &'canister self,
    canister_id: &Principal
) -> impl 'agent + AsyncCall<()>

Deletes a canister.

pub fn provisional_create_canister_with_cycles<'canister: 'agent>(
    &'canister self,
    amount: Option<u64>
) -> impl 'agent + AsyncCall<(Principal,)>

Until developers can convert real ICP tokens to provision a new canister with cycles, the system provides the provisional_create_canister_with_cycles method. It behaves as create_canister, but initializes the canister’s balance with amount fresh cycles (using MAX_CANISTER_BALANCE if amount = null, else capping the balance at MAX_CANISTER_BALANCE). Cycles added to this call via ic0.call_cycles_add are returned to the caller. This method is only available in local development instances, and will be removed in the future.

pub fn provisional_top_up_canister<'canister: 'agent>(
    &'canister self,
    canister_id: &Principal,
    amount: u64
) -> impl 'agent + AsyncCall<()>

Until developers can convert real ICP tokens to a top up an existing canister, the system provides the provisional_top_up_canister method. It adds amount cycles to the balance of canister identified by amount (implicitly capping it at MAX_CANISTER_BALANCE).

pub fn raw_rand<'canister: 'agent>(
    &'canister self
) -> impl 'agent + AsyncCall<(Vec<u8>,)>

This method takes no input and returns 32 pseudo-random bytes to the caller. The return value is unknown to any part of the IC at time of the submission of this call. A new return value is generated for each call to this method.

pub fn start_canister<'canister: 'agent>(
    &'canister self,
    canister_id: &Principal
) -> impl 'agent + AsyncCall<()>

Starts a canister.

pub fn stop_canister<'canister: 'agent>(
    &'canister self,
    canister_id: &Principal
) -> impl 'agent + AsyncCall<()>

Stop a canister.

pub fn install_code<'canister: 'agent>(
    &'canister self,
    canister_id: &Principal,
    wasm: &'canister [u8]
) -> InstallCodeBuilder<'agent, 'canister, ManagementCanister>

Install a canister, with all the arguments necessary for creating the canister.

pub fn set_controller<'canister: 'agent>(
    &'canister self,
    canister_id: &Principal,
    new_controller: &Principal
) -> impl 'agent + AsyncCall<()>

Set controller for a canister.

impl<'agent> Canister<'agent, Wallet>

pub fn name<'canister: 'agent>(
    &'canister self
) -> impl 'agent + SyncCall<(Option<String>,)>

pub fn set_name<'canister: 'agent>(
    &'canister self,
    name: String
) -> impl 'agent + AsyncCall<()>

pub fn get_controllers<'canister: 'agent>(
    &'canister self
) -> impl 'agent + SyncCall<(Vec<Principal>,)>

Get the current controller’s principal ID.

pub fn add_controller<'canister: 'agent>(
    &'canister self,
    principal: Principal
) -> impl 'agent + AsyncCall<()>

Transfer controller to another principal ID.

pub fn remove_controller<'canister: 'agent>(
    &'canister self,
    principal: Principal
) -> impl 'agent + AsyncCall<()>

pub fn get_custodians<'canister: 'agent>(
    &'canister self
) -> impl 'agent + SyncCall<(Vec<Principal>,)>

Get the list of custodians.

pub fn authorize<'canister: 'agent>(
    &'canister self,
    custodian: Principal
) -> impl 'agent + AsyncCall<()>

Authorize a new custodian.

pub fn deauthorize<'canister: 'agent>(
    &'canister self,
    custodian: Principal
) -> impl 'agent + AsyncCall<()>

Deauthorize a custodian.

pub fn wallet_balance<'canister: 'agent>(
    &'canister self
) -> impl 'agent + SyncCall<(BalanceResult,)>

Get the balance.

pub fn wallet_send<'canister: 'agent>(
    &'canister self,
    destination: &Canister<'agent, Wallet>,
    amount: u64
) -> impl 'agent + AsyncCall<(Result<(), String>,)>

Send cycles to another (hopefully Wallet) canister.

pub fn wallet_receive<'canister: 'agent>(
    &'canister self
) -> impl 'agent + AsyncCall<((),)>

Send cycles to another (hopefully Wallet) canister.

pub fn wallet_create_canister<'canister: 'agent>(
    &'canister self,
    cycles: u64,
    controller: Option<Principal>
) -> impl 'agent + AsyncCall<(Result<CreateResult, String>,)>

pub fn wallet_create_wallet<'canister: 'agent>(
    &'canister self,
    cycles: u64,
    controller: Option<Principal>
) -> impl 'agent + AsyncCall<(Result<CreateResult, String>,)>

Create a wallet canister

pub fn wallet_store_wallet_wasm<'canister: 'agent>(
    &'canister self,
    wasm_module: Vec<u8>
) -> impl 'agent + AsyncCall<()>

Store the wallet WASM inside the wallet canister. This is needed to enable wallet_create_wallet

pub fn add_address<'canister: 'agent>(
    &'canister self,
    address: AddressEntry
) -> impl 'agent + AsyncCall<()>

pub fn list_addresses<'canister: 'agent>(
    &'canister self
) -> impl 'agent + SyncCall<(Vec<AddressEntry>,)>

pub fn remove_address<'canister: 'agent>(
    &'canister self,
    principal: Principal
) -> impl 'agent + AsyncCall<()>

pub fn get_events<'canister: 'agent>(
    &'canister self,
    from: Option<u32>,
    to: Option<u32>
) -> impl 'agent + SyncCall<(Vec<Event>,)>

pub fn call<'canister: 'agent, Out, M: Into<String>>(
    &'canister self,
    destination: &'canister Canister<'canister>,
    method_name: M,
    arg: Argument,
    amount: u64
) -> CallForwarder<'agent, 'canister, Out> where
    Out: for<'de> ArgumentDecoder<'de> + Send + Sync, 

Forward a call to another canister, including an amount of cycles from the wallet.

pub fn call_forward<'canister: 'agent, Out: 'agent>(
    &'canister self,
    call: AsyncCaller<'agent, Out>,
    amount: u64
) -> Result<impl 'agent + AsyncCall<Out>, AgentError> where
    Out: for<'de> ArgumentDecoder<'de> + Send + Sync, 

Forward a call using another call’s builder. This takes an UpdateBuilder, marshalls it to a buffer, and sends it through the wallet canister, adding a separate amount.