Struct ic_utils::interfaces::wallet::WalletCanister

pub struct WalletCanister<'agent> { /* private fields */ }

A wallet canister interface, for the standard wallet provided by DFINITY. This interface implements most methods conveniently for the user.

Implementations

impl<'agent> WalletCanister<'agent>

pub async fn create(
    agent: &'agent Agent,
    canister_id: Principal
) -> Result<WalletCanister<'agent>, AgentError>

Create an instance of a WalletCanister interface pointing to the given Canister ID. Fails if it cannot learn the wallet’s version.

pub async fn from_canister(
    canister: Canister<'agent>
) -> Result<WalletCanister<'agent>, AgentError>

Create a WalletCanister interface from an existing canister object. Fails if it cannot learn the wallet’s version.

pub fn from_canister_with_version(
    canister: Canister<'agent>,
    version: Version
) -> Self

Create a WalletCanister interface from an existing canister object and a known wallet version.

This interface’s methods may raise errors if the provided version is newer than the wallet’s actual supported version.

impl<'agent> WalletCanister<'agent>

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

Re-fetch the API version string of the wallet.

pub fn wallet_api_version(&self) -> &Version

Get the (cached) API version of the wallet.

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

Get the friendly name of the wallet (if one exists).

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

Set the friendly name of the wallet.

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

Remove a user as a wallet controller.

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_balance64<'canister: 'agent>(
    &'canister self
) -> impl 'agent + SyncCall<(BalanceResult<u64>,)>

Get the balance with the 64-bit API.

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

Get the balance with the 128-bit API.

pub async fn wallet_balance<'canister: 'agent>(
    &'canister self
) -> Result<BalanceResult, AgentError>

Get the balance.

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

Send cycles to another canister using the 64-bit API.

pub fn wallet_send128<'canister: 'agent>(
    &'canister self,
    destination: Principal,
    amount: u128
) -> impl 'agent + AsyncCall<(Result<(), String>,)>

Send cycles to another canister using the 128-bit API.

pub async fn wallet_send<'canister: 'agent>(
    &'canister self,
    destination: Principal,
    amount: u128
) -> Result<(), AgentError>

Send cycles to another canister.

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

A function for sending cycles to, so that a memo can be passed along with them.

pub fn wallet_create_canister64_v1<'canister: 'agent>(
    &'canister self,
    cycles: u64,
    controller: Option<Principal>,
    compute_allocation: Option<ComputeAllocation>,
    memory_allocation: Option<MemoryAllocation>,
    freezing_threshold: Option<FreezingThreshold>
) -> impl 'agent + AsyncCall<(Result<CreateResult, String>,)>

Create a canister through the wallet, using the single-controller 64-bit API.

pub fn wallet_create_canister64_v2<'canister: 'agent>(
    &'canister self,
    cycles: u64,
    controllers: Option<Vec<Principal>>,
    compute_allocation: Option<ComputeAllocation>,
    memory_allocation: Option<MemoryAllocation>,
    freezing_threshold: Option<FreezingThreshold>
) -> impl 'agent + AsyncCall<(Result<CreateResult, String>,)>

Create a canister through the wallet, using the multi-controller 64-bit API.

pub fn wallet_create_canister128<'canister: 'agent>(
    &'canister self,
    cycles: u128,
    controllers: Option<Vec<Principal>>,
    compute_allocation: Option<ComputeAllocation>,
    memory_allocation: Option<MemoryAllocation>,
    freezing_threshold: Option<FreezingThreshold>
) -> impl 'agent + AsyncCall<(Result<CreateResult, String>,)>

Create a canister through the wallet, using the 128-bit API.

pub async fn wallet_create_canister<'canister: 'agent>(
    &'canister self,
    cycles: u128,
    controllers: Option<Vec<Principal>>,
    compute_allocation: Option<ComputeAllocation>,
    memory_allocation: Option<MemoryAllocation>,
    freezing_threshold: Option<FreezingThreshold>
) -> Result<CreateResult, AgentError>

Create a canister through the wallet.

pub fn wallet_create_wallet64_v1<'canister: 'agent>(
    &'canister self,
    cycles: u64,
    controller: Option<Principal>,
    compute_allocation: Option<ComputeAllocation>,
    memory_allocation: Option<MemoryAllocation>,
    freezing_threshold: Option<FreezingThreshold>
) -> impl 'agent + AsyncCall<(Result<CreateResult, String>,)>

Create a wallet canister with the single-controller 64-bit API.

pub fn wallet_create_wallet64_v2<'canister: 'agent>(
    &'canister self,
    cycles: u64,
    controllers: Option<Vec<Principal>>,
    compute_allocation: Option<ComputeAllocation>,
    memory_allocation: Option<MemoryAllocation>,
    freezing_threshold: Option<FreezingThreshold>
) -> impl 'agent + AsyncCall<(Result<CreateResult, String>,)>

Create a wallet canister with the multi-controller 64-bit API.

pub fn wallet_create_wallet128<'canister: 'agent>(
    &'canister self,
    cycles: u128,
    controllers: Option<Vec<Principal>>,
    compute_allocation: Option<ComputeAllocation>,
    memory_allocation: Option<MemoryAllocation>,
    freezing_threshold: Option<FreezingThreshold>
) -> impl 'agent + AsyncCall<(Result<CreateResult, String>,)>

Create a wallet canister with the 128-bit API.

pub async fn wallet_create_wallet<'canister: 'agent>(
    &'canister self,
    cycles: u128,
    controllers: Option<Vec<Principal>>,
    compute_allocation: Option<ComputeAllocation>,
    memory_allocation: Option<MemoryAllocation>,
    freezing_threshold: Option<FreezingThreshold>
) -> Result<CreateResult, AgentError>

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

Add a principal to the address book.

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

List the entries in the address book.

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

Remove a principal from the address book.

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

Get a list of all transaction events this wallet remembers, using the 64-bit API. Fails if any events are 128-bit.

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

Get a list of all transaction events this wallet remembers, using the 128-bit API.

pub async fn get_events<'canister: 'agent>(
    &'canister self,
    from: Option<u32>,
    to: Option<u32>
) -> Result<Vec<Event>, AgentError>

Get a list of all transaction events this wallet remembers.

pub fn call64<'canister: 'agent, Out, M: Into<String>>(
    &'canister self,
    destination: Principal,
    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, using the 64-bit API.

pub fn call128<'canister: 'agent, Out, M: Into<String>>(
    &'canister self,
    destination: Principal,
    method_name: M,
    arg: Argument,
    amount: u128
) -> 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, using the 128-bit API.

pub fn call<'canister: 'agent, Out, M: Into<String>>(
    &'canister self,
    destination: Principal,
    method_name: M,
    arg: Argument,
    amount: u128
) -> 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 list_managed_canisters<'canister: 'agent>(
    &'canister self,
    from: Option<u32>,
    to: Option<u32>
) -> impl 'agent + SyncCall<(Vec<ManagedCanisterInfo>, u32)>

Gets the managed canisters the wallet knows about.

pub fn get_managed_canister_events64<'canister: 'agent>(
    &'canister self,
    canister: Principal,
    from: Option<u32>,
    to: Option<u32>
) -> impl 'agent + SyncCall<(Option<Vec<ManagedCanisterEvent<u64>>>,)>

Gets the ManagedCanisterEvents for a particular canister, if the wallet knows about that canister, using the 64-bit API.

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

Gets the ManagedCanisterEvents for a particular canister, if the wallet knows about that canister, using the 128-bit API.

pub async fn get_managed_canister_events<'canister: 'agent>(
    &'canister self,
    canister: Principal,
    from: Option<u32>,
    to: Option<u32>
) -> Result<Option<Vec<ManagedCanisterEvent>>, AgentError>

Gets the ManagedCanisterEvents for a particular canister, if the wallet knows about that canister

pub fn version_supports_multiple_controllers(&self) -> bool

Gets whether the wallet version supports initializing a canister with multiple controllers (introduced in 0.2.0).

pub fn version_supports_u128_cycles(&self) -> bool

Gets whether the wallet version supports 128-bit cycle counts (introduced in 0.3.0).

Methods from Deref<Target = Canister<'agent>>

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

Get the canister ID of this canister.

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

Create an AsyncCallBuilder to do an update call.

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

Create a SyncCallBuilder to do a query call.

pub async fn wait<'canister: 'agent>(
    &'canister self,
    request_id: RequestId
) -> Result<Vec<u8>, AgentError>

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

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

Creates a copy of this canister, changing the canister ID to the provided principal.

Trait Implementations

impl<'agent> Clone for WalletCanister<'agent>

fn clone(&self) -> WalletCanister<'agent>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'agent> Debug for WalletCanister<'agent>

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

Formats the value using the given formatter.

impl<'agent> Deref for WalletCanister<'agent>

type Target = Canister<'agent>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.