Rust Canister Development Kit (CDK)

The ic-cdk-management-canister crate provides functions and type definitions for making calls to the Internet Computer (IC) management canister. It simplifies interactions by handling argument types and automatically calculating required cycle costs for many entry points.

Key features include:

• Type Definitions: Provides argument and result types for management canister entry points. For types that include a sender_canister_version field, this crate provides reduced versions where that field is omitted because it is set automatically by the canister.
• Automated Cycle Calculation: Many functions automatically calculate and attach the necessary cycles required for the call. For HTTPS outcalls, use the HttpRequest or FlexibleHttpRequest builders.
• Wait Strategies: The crate uses different inter-canister call strategies based on the method being called:
  • Unbounded-wait: Used by default for most functions because the management canister is universally trusted.
  • Bounded-wait: Used for methods that only read state (typically with a default 300s timeout).

When calling the management canister, you can choose between two wait strategies. The crate selects a strategy by default, but you can override it using the ic_cdk::call::Call struct.

• Unbounded-wait: The default for most functions. Use this when the management canister is trusted and the operation is expected to complete.
• Bounded-wait: Used for state-reading methods. It includes a default timeout of 300s.

If the default behavior of a crate function (like sign_with_ecdsa) does not suit your needs, you can manually construct a Call object to specify the wait type.

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)?;
    // Manually using bounded_wait instead of the default unbounded-wait
    let res: SignWithEcdsaResult = Call::bounded_wait(callee, "sign_with_ecdsa")
        .with_arg(&arg)
        .with_cycles(cycles)
        .await?
        .candid()?;
    Ok(res)
}

When interacting with Bitcoin canisters, you can choose between two types of inter-canister calls:

1. Bounded-wait: Most functions in this crate use bounded-wait calls because they are primarily used for reading state. This is the default behavior for most helper functions.
2. Unbounded-wait: Required for functions that involve state changes or longer processing times. The bitcoin_send_transaction function is the only one in this crate that uses unbounded-wait by default.

If you need to override the default behavior (e.g., performing an unbounded-wait call for a read operation like bitcoin_get_utxos), you can use the ic_cdk::call::Call struct directly.

use ic_cdk_bitcoin_canister::{cost_get_utxos, get_bitcoin_canister_id, GetUtxosRequest, GetUtxosResponse, Network};
use ic_cdk::call::Call;

async fn example() -> ic_cdk::call::CallResult<GetUtxosResponse> {
    let arg = GetUtxosRequest {
        address: "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq".to_string(),
        network: Network::Mainnet.into(),
        filter: None,
    };
    let canister_id = get_bitcoin_canister_id(Network::from(arg.network));
    let cycles = cost_get_utxos(&arg);
    let res: GetUtxosResponse = Call::unbounded_wait(canister_id, "bitcoin_get_utxos")
        .with_arg(&arg)
        .with_cycles(cycles)
        .await?
        .candid()?;
    Ok(res)
}