Crate ic_cdk_management_canister

Expand description

§ic-cdk-management-canister

Functions and types for interacting with the IC management canister.

§Type Definitions

This crate defines the types of arguments and results for the management canister entry points. Most of these types are re-exported from the ic-management-canister-types crate.

The only exception is that for the argument types that has a sender_canister_version field, this module provides reduced versions instead. The reduced versions don’t need the sender_canister_version field as it is set automatically in the corresponding functions.

§Call

The majority of the functions in this module are for making calls to the management canister.

§Bounded-wait vs. Unbounded-wait

Interacting with the IC management canister involves making inter-canister calls, which can be either bounded-wait or unbounded-wait. This crate selects the appropriate type of wait call for each method based on the characteristics of the entry point.

The strategy for choosing the type of wait call is as follows:

Unbounded-wait call by default because the management canister is universally trusted.
Bounded-wait call (with the default 300s timeout) for methods that only read state.

Please check the documentation of each function for the type of wait call it uses.

If the default behavior is not suitable for a particular use case, the Call struct can be used directly to make the call.

For example, sign_with_ecdsa makes an unbounded-wait call. If a bounded-wait call is preferred, the call can be made as follows:

use ic_cdk_management_canister::{cost_sign_with_ecdsa, SignCallError, SignWithEcdsaArgs, SignWithEcdsaResult};
use ic_cdk::call::Call;
use candid::Principal;

async fn example() -> Result<SignWithEcdsaResult, SignCallError> {
    let callee = Principal::management_canister();
    let arg = SignWithEcdsaArgs::default();
    let cycles = cost_sign_with_ecdsa(&arg)?;
    let res: SignWithEcdsaResult = Call::bounded_wait(callee, "sign_with_ecdsa")
        .with_arg(&arg)
        .with_cycles(cycles)
        .await?
        .candid()?;
    Ok(res)
}

§Cycle Cost

Some management canister entry points require cycles to be attached to the call. The functions for calling management canister automatically calculate the required cycles and attach them to the call.

For completeness, this module also provides functions to calculate the cycle cost:

Structs§

Bip341: Bip341 variant of Schnorr Aux.
CanisterIdRecord: Canister ID Record
CanisterInfoArgs: Canister Info Args
CanisterInfoResult: Canister Info Result
CanisterMetadataArgs: Canister Metadata Args
CanisterMetadataResult: Canister Metadata Result
CanisterSettings: Canister Settings
CanisterStatusResult: Canister Status Result
Change: Change
ChunkHash: Chunk hash.
CodeDeploymentRecord: Code Deployment Record
ControllersChangeRecord: Controllers Change Record
CreateCanisterArgs: Argument type of create_canister and create_canister_with_extra_cycles.
CreationRecord: Creation Record
DefiniteCanisterSettings: Definite Canister Settings
DeleteCanisterSnapshotArgs: Delete Canister Snapshot Args.
EcdsaKeyId: ECDSA Key ID.
EcdsaPublicKeyArgs: ECDSA Public Key Args.
EcdsaPublicKeyResult: ECDSA Public Key Result.
EnvironmentVariable: Environment Variable.
FromCanisterRecord: From Canister Record
FromUserRecord: From User Record
HttpHeader: HTTP Header.
HttpRequestArgs: HTTP Request Args
HttpRequestResult: HTTP Request Result
InstallChunkedCodeArgs: Argument type of install_chunked_code.
InstallCodeArgs: Argument type of install_code.
LoadCanisterSnapshotArgs: Argument type of load_canister_snapshot.
LoadSnapshotRecord: Load Snapshot Record
MemoryMetrics: Memory Metrics
NodeMetrics: Node Metrics.
NodeMetricsHistoryArgs: Node Metrics History Args.
NodeMetricsHistoryRecord: Node Metrics History Record.
ProvisionalCreateCanisterWithCyclesArgs: Argument type of provisional_create_canister_with_cycles.
ProvisionalTopUpCanisterArgs: Provisional Top Up Canister Args.
QueryStats: Query Stats
ReadCanisterSnapshotDataArgs: Read Canister Snapshot Data Args.
ReadCanisterSnapshotDataResult: Read Canister Snapshot Data Result.
ReadCanisterSnapshotMetadataArgs: Read Canister Snapshot Metadata Args.
ReadCanisterSnapshotMetadataResult: Read Canister Snapshot Metadata Result.
SchnorrKeyId: Schnorr Key ID.
SchnorrPublicKeyArgs: Schnorr Public Key Args.
SchnorrPublicKeyResult: Schnorr Public Key Result.
SignWithEcdsaArgs: Sign With ECDSA Args.
SignWithEcdsaResult: Sign With ECDSA Result.
SignWithSchnorrArgs: Sign With Schnorr Args.
SignWithSchnorrResult: Sign With Schnorr Result.
Snapshot: Snapshot.
SubnetInfoArgs: Subnet Info Args.
SubnetInfoResult: Subnet Info Result.
TakeCanisterSnapshotArgs: Take Canister Snapshot Args.
TransformArgs: Transform Args.
TransformContext: Transform Context.
TransformFunc
UninstallCodeArgs: Argument type of uninstall_code.
UpdateSettingsArgs: Argument type of update_settings
UpgradeFlags: Upgrade Flags
UploadCanisterSnapshotDataArgs: Upload Canister Snapshot Data Args.
UploadCanisterSnapshotMetadataArgs: Upload Canister Snapshot Metadata Args.
UploadCanisterSnapshotMetadataResult: Upload Canister Snapshot Metadata Result.
UploadChunkArgs: Upload Chunk Args
VetKDDeriveKeyArgs: VetKD derive key request.
VetKDDeriveKeyResult: VetKD derive key reply.
VetKDKeyId
VetKDPublicKeyArgs: VetKD public key request.
VetKDPublicKeyResult: VetKD public key reply.

Enums§

CanisterInstallMode: Canister Install Mode
CanisterStatusType: Canister Status Type
CanisterTimer: The status of a global timer.
ChangeDetails: Change Details
ChangeOrigin: Change Origin
CodeDeploymentMode: Code Deployment Mode
EcdsaCurve: ECDSA Curve.
HttpMethod: HTTP Method.
LogVisibility: Log Visibility.
OnLowWasmMemoryHookStatus: The status of a low wasm memory hook.
SchnorrAlgorithm: Schnorr Algorithm.
SchnorrAux: Schnorr Aux.
SignCallError: The error type for the sign_with_ecdsa and sign_with_schnorr functions.
SnapshotDataKind: Snapshot data kind.
SnapshotDataOffset: Snapshot data offset.
SnapshotMetadataGlobal: An exported global variable.
SnapshotSource: The source of a snapshot.
VetKDCurve: The curve used for key derivation.
WasmMemoryPersistence: Wasm Memory Persistence

Functions§

canister_info: Gets public information about the canister.
canister_metadata: Gets canister’s metadata contained in custom sections whose names have the form icp:public <name> or icp:private <name>
canister_status: Gets status information about the canister.
clear_chunk_store: Clears the chunk store of a canister.
cost_http_request: Calculates the cost of making an HTTP outcall with the given HttpRequestArgs.
cost_sign_with_ecdsa: Calculates the cost of ECDSA signanature with the given SignWithEcdsaArgs.
cost_sign_with_schnorr: Calculates the cost of Schnorr signanature with the given SignWithSchnorrArgs.
cost_vetkd_derive_key: Calculates the cost of VetKD key derivation with the given VetKDDeriveKeyArgs.
create_canister: Creates a new canister.
create_canister_with_extra_cycles: Creates a new canister with extra cycles.
delete_canister: Deletes a canister.
delete_canister_snapshot: Deletes a specified snapshot that belongs to an existing canister.
deposit_cycles: Deposits cycles to a canister.
ecdsa_public_key: Gets a SEC1 encoded ECDSA public key for the given canister using the given derivation path.
http_request: Makes an HTTP outcall.
http_request_with_closuretransform-closure: Makes an HTTP outcall and transforms the response using a closure.
install_chunked_code: Installs code into a canister where the code has previously been uploaded in chunks.
install_code: Installs code into a canister.
list_canister_snapshots: Lists the snapshots of the canister.
load_canister_snapshot: Loads a snapshot onto the canister.
node_metrics_history: Gets a time series of subnet’s node metrics.
provisional_create_canister_with_cycles: Creates a new canister with specified amount of cycles balance.
provisional_top_up_canister: Adds cycles to a canister.
raw_rand: Gets 32 pseudo-random bytes.
read_canister_snapshot_data: Reads data of a snapshot of a canister.
read_canister_snapshot_metadata: Reads metadata of a snapshot of a canister.
schnorr_public_key: Gets a SEC1 encoded Schnorr public key for the given canister using the given derivation path.
sign_with_ecdsa: Gets a new ECDSA signature of the given message_hash with a user-specified amount of cycles.
sign_with_schnorr: Gets a new Schnorr signature of the given message with a user-specified amount of cycles.
start_canister: Starts a canister if the canister status was stopped or stopping.
stop_canister: Stops a canister.
stored_chunks: Gets the hashes of all chunks stored in the chunk store of a canister.
subnet_info: Gets the metadata about a subnet.
take_canister_snapshot: Takes a snapshot of the specified canister.
transform_context_from_query: Constructs a TransformContext from a query method name and context.
uninstall_code: Removes a canister’s code and state, making the canister empty again.
update_settings: Updates the settings of a canister.
upload_canister_snapshot_data: Uploads data to a snapshot of that canister.
upload_canister_snapshot_metadata: Creates a snapshot of that canister by uploading the snapshot’s metadata.
upload_chunk: Uploads a chunk to the chunk store of a canister.
vetkd_derive_key: Derives a key from the given input.
vetkd_public_key: Gets a VetKD public key.

Type Aliases§

CanisterId: Canister ID.
CanisterStatusArgs: Canister Status Args
ClearChunkStoreArgs: Clear Chunk Store Args
CreateCanisterResult: Create Canister Result
DeleteCanisterArgs: Delete Canister Args
DepositCyclesArgs: Deposit Cycles Args
ListCanisterSnapshotsArgs: List Canister Snapshots Args.
ListCanisterSnapshotsResult: List Canister Snapshots Result.
NodeMetricsHistoryResult: Node Metrics History Result.
ProvisionalCreateCanisterWithCyclesResult: Provisional Create Canister With Cycles Result.
RawRandResult: Raw Rand Result
SnapshotId: Snapshot ID.
StartCanisterArgs: Start Canister Args
StopCanisterArgs: Stop Canister Args
StoredChunksArgs: Stored Chunks Args
StoredChunksResult: Stored Chunks Result
TakeCanisterSnapshotResult: Take Canister Snapshot Result.
UploadChunkResult: Upload Chunk Result
WasmModule: WASM Module