ic-cdk

Added

• Added msg_caller_info_data and msg_caller_info_signer to ic_cdk::api, exposing the caller's identity attribute data and the signing canister ID respectively.

Changed

• [BREAKING] Remove all items deprecated in v0.18.0: api::call, api::stable, api::management_canister modules and legacy functions (spawn, print, caller, id, canister_balance, set_certified_data, set_global_timer).
• [BREAKING] Move the bitcoin_canister module to a separate crate ic-cdk-bitcoin-canister. Users should depend on ic-cdk-bitcoin-canister directly.
• [BREAKING] Move the management_canister module to a separate crate ic-cdk-management-canister. Users should depend on ic-cdk-management-canister directly. The transform-closure feature is also moved to the new crate.

Added

• Support Canister Environment Variable. (#636)
  • Add binding for env_var_* API.
• New Management Canister methods:
  • canister_metadata
  • read_canister_snapshot_metadata
  • read_canister_snapshot_data
  • upload_canister_snapshot_metadata
  • upload_canister_snapshot_data

Changed

• [BREAKING] Updated to version 2.0 of the async executor. The spawn function now creates protected tasks that panic (or are canceled, with spawn_weak) if they outlive the canister method (with a new spawn_migratory function for tasks that are supposed to outlive the method). A trap will now cancel all protected tasks in the method it is part of. See the module docs for more information.

  • The async machinery that is primarily used from macros (i.e. in_*_context) has been moved to ic_cdk::futures::internals.

• [BREAKING] Upgrade ic-management-canister-types which contains the changes for:

  • Canister Environment Variable.
  • Non-replicated HTTP outcalls.

Added

• The macros annotate #[allow(clippy::disallowed_methods)] above the invocation of ic_cdk::futures::spawn.

The ic_cdk::futures::spawn method has a different poll order that can affect canister behavior. While some projects may wish to enforce a disallowed-methods lint rule to prevent its use, the invocations generated by our macros are a false positive. This annotation prevents the warning from being triggered for the macro-generated code, ensuring a clean linting experience for developers who adopt the new rule.

Added

• Restored the default skipping_quota to match the behavior of previous versions of the macros.

Fixed

• The macros now support 2024 edition.

Changed

• MSRV raised to 1.85.0.

Fixed

• Tasks which return after canceling futures are no longer marked as trapped

Changed

• Updated to ic0 v1.0.0

Added

• New ic_cdk::futures function spawn_017_compat. This has the code ordering behavior of 0.17, with spawned futures run immediately instead of waiting for the current code to suspend.

Added

• Support root_key API. (#619)

Changed

• Update bitcoin regtest cycles cost to be same as the bitcoin mainnet.

  fees = record {
        get_current_fee_percentiles = 10_000_000 : nat;
        get_utxos_maximum = 10_000_000_000 : nat;
        get_block_headers_cycles_per_ten_instructions = 10 : nat;
        get_current_fee_percentiles_maximum = 100_000_000 : nat;
        send_transaction_per_byte = 20_000_000 : nat;
        get_balance = 10_000_000 : nat;
        get_utxos_cycles_per_ten_instructions = 10 : nat;
        get_block_headers_base = 50_000_000 : nat;
        get_utxos_base = 50_000_000 : nat;
        get_balance_maximum = 100_000_000 : nat;
        send_transaction_base = 5_000_000_000 : nat;
        get_block_headers_maximum = 10_000_000_000 : nat;
      };
  

  You can get the fees by get_config API on the BTC Mainnet Canister.

Added

• New CDK library ic-cdk-executor containing the low-level async executor primitives previously in ic-cdk. Most users will never need to use this library and should continue using the interface from ic-cdk.

Changed

• Bump ic-error-types to v0.2.0 from which we re-export the RejectCode type.

chore: Release alpha versions of other crates matching ic-cdk@0.18.2-…

Added

• Support VetKD management canister API. (#597)
• Add Call::take_raw_args which owns the bytes. (#601)

Please check Version 0.18 Guide for more details.

Added

• New Call API.
  • Supports bounded-wait inter-canister calls.
  • Uses a builder pattern for optional call configuration.
  • Allows chaining .candid() decoding only when needed.
  • Provides ergonomic Rust error handling to encourage best practices.
• Support for Wasm64 module compilation.
  • Seamlessly handles 32-bit and 64-bit System APIs.
• Enhanced macros for flexible argument decoding and result encoding.
  • update/query/init macros now support custom argument decoders via decode_with.
  • update/query macros now support custom result encoders via encode_with.
• Simplified module hierarchy with one level under the crate root.
  • api module offers consistent System API bindings.
  • management_canister module for convenient Management Canister calls.
  • bitcoin_canister module for direct Bitcoin Canisters calls.
• Enhanced cycles cost calculation for Management Canister API calls:
  • New system APIs exposed through the api module:
    • cost_http_request, cost_sign_with_ecdsa, cost_sign_with_schnorr, cost_vetkd_derive_key.
  • High-level bindings in the management_canister module accept call arguments by reference.
  • All relevant Management Canister methods now automatically attach the required cycles to calls.

Changed

• Introduces a new task scheduler-based executor.
  • Capable of scheduling any async task, not limited to inter-canister calls.
  • The futures module is now public to expose functionalities related to the async executor.
  • The new implementation enables code to have (intended) surprising behavior - it is recommended to read the module docs

Deprecated

• Submodules in api are now deprecated in favor of root-level modules.
  • api/call -> call
  • api/management_canister -> management_canister & bitcoin_canister
  • api/stable -> stable

Added

• Add method bitcoin_get_block_headers.
• Support management canister method: subnet_info. (#532)
  • Add types: SubnetInfoArgs and SubnetInfoResult.

Fixed

• Fix update/query macro could not handle function arguments with the same name as the function itself. (#525)

Changed

• Add AllowedViewers variant to LogVisibility enum. (#512)

Added

• Attribute #[on_low_wasm_memory] for low-memory hook. (#528)
• Support Threshold Schnorr signing management canister API. (#518)

Changed

• BREAKING: Add the LoadSnapshot variant to CanisterChangeDetails. (#504)

Added

• Support Canister State Snapshots. (#504)
  • Add methods: take_canister_snapshot, load_canister_snapshot, list_canister_snapshots, delete_canister_snapshot
  • Add types: LoadSnapshotRecord, SnapshotId, Snapshot, TakeCanisterSnapshotArgs, LoadCanisterSnapshotArgs, DeleteCanisterSnapshotArgs

Changed

• BREAKING: Stable Memory always use 64-bit addresses and stable64_* system API. (#498)
• BREAKING: Add log_visibility to the management canister API types: (#497)
  • CanisterSettings
  • DefiniteCanisterSettings.

Added

• Provide safe wrapper of in_replicated_execution in ic-cdk. (#489)

Changed

• Upgrade ic0 to v0.23.0. (#489)
• BREAKING: Add wasm_memory_limit to the management canister API types: (#483)
  • CanisterSettings
  • DefiniteCanisterSettings.

Added

• Management canister methods for interacting with the chunk store. (#461)
• Provide safe wrapper of global_timer_set in ic-cdk. (#475)

Changed

• Upgrade ic-cdk-macros to v0.9.0.

Added

• Add is_recovering_from_trap function for implementing trap cleanup logic. (#456)
• Allow setting decoding quota for canister entry points and inter-canister calls. (#465)
  • When defining canister entry points, we add the following attributes: #[update(decoding_quota = 10000, skipping_quota = 100, debug = true)]
    • skipping_quota limits the amount of work allowed for skipping unneeded data on the wire. If this attributes is not present, we set a default quota of 10_000. This affects ALL existing canisters, and is mainly used to improve canister throughput. See docs on the Candid library to understand the skipping cost.
    • decoding_quota limits the total amount of work the deserializer can perform. See docs on the Candid library to understand the cost model.
    • debug = true prints the instruction count and the decoding/skipping cost to the replica log, after a successful deserialization. The decoding/skipping cost is logged only when you have already set a quota in the attributes. The debug mode is useful to determine the right quotas above. Developers can send a few large payloads to the debugging entry point and know the actual decoding cost.
  • When making inter-canister calls, we have a new function call_with_config to config the same decoding quotas described above. It's strongly recommended to use call_with_config when calling third-party untrusted canisters.

Changed

• ic_cdk::api::call::arg_data takes ArgDecoderConfig as argument. (#465)

Changed

• Add "reserved cycles" fields to the management canister API: (#449)
  • reserved_cycles to CanisterStatusResponse
  • reserved_cycles_limit to CanisterSettings and DefiniteCanisterSettings

Fixed

• The README file is now more informative and used as the front page of the doc site.
• The call* methods are documented with examples and notes.

Changed

• Upgrade candid to 0.10. (#448)

Added

• query_stats in canister_status response. (#432)

Added

• Another type of performance counter: "call context instruction counter". Can be fetched using either method below: (#435)
  • ic_cdk::api::performance_counter(1);
  • ic_cdk::api::call_context_instruction_counter() as a shorthand;

Changed

• Deprecate ic_cdk::api::call::performance_counter() in favor of ic_cdk::api::performance_counter(). (#435)

Added

• cycles_burn corresponding to system API ic0.cycles_burn128. (#434)

Changed

• Upgrade ic0 to 0.21.1. (#434)

Changed

• Upgrade ic0 to 0.21.0. (#433)

Changed

• Candid Export workflow is changed. (#424)
  • No need to compile for WASI separately.
  • Canisters should still invoke ic_cdk::export_candid!() to export candid.
  • Then use candid-extractor to extract candid from the canister WASM.

Changed

• Upgrade candid to 0.9. (#411)
• Remove export module. Please use candid directly in your project instead of using ic_cdk::export::candid.
• Remove ic_cdk_macro::import module. See below for a new way to import canisters.

Added

• Export Candid: (#386)

  • A wasi feature that builds the canister as a standalone WASI binary. Running the binary in wasmtime outputs the canister interface
  • Build step:

  cargo build --target wasm32-unknown-unknown \
      --release \
      --package "$package" --features "ic-cdk/wasi"
  
  wasmtime "target/wasm32-unknown-unknown/release/$package.wasm" > $did_file
  
  cargo build --target wasm32-unknown-unknown \
      --release \
      --package "$package"
  
  ic-wasm "target/wasm32-unknown-unknown/release/$package.wasm" \
      -o "target/wasm32-unknown-unknown/release/$package.wasm" \
      metadata candid:service -v public -f $did_file
  

  • In the canister code, users have to add ic_cdk::export_candid!() at the end of lib.rs. In the future we may lift this requirement to provide a better DX.

• Import Candid: (#390)

  • Canister project adds ic_cdk_bindgen as a build dependency to generate canister bindings
  • build.rs

  use ic_cdk_bindgen::{Builder, Config};
  fn main() {
      let counter = Config::new("counter");
      let mut builder = Builder::new();
      builder.add(counter);
      builder.build(None);  // default write to src/declarations
  }
  

  • In the canister code,

  mod declarations;
  use declarations::counter::counter;
  
  counter.inc().await?
  

Changed

• Hardcodes the fee for sign_with_ecdsa. (#407)

Changed

• Bitcoin API handles cycles cost under the hood. (#406)

Added

• Set caller's canister version in the field sender_canister_version of management canister call payloads. (#401)
• Add management canister types for canister_info management canister call (CanisterInfoRequest and CanisterInfoResponse). (#401)

Changed

• No hard-coded fees for management canister calls. (#404)