ic-cdk

Changed

• Update, query, init, and post_upgrade canister entry points now interpret an empty input vector as the Candid encoding of (), making them more lenient when no arguments are provided. This does not apply to methods using decode_with, which still receive the raw (empty) bytes.

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 [email protected]…

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)

Added

• ic0.is_controller as a public function. (#383)

Changed

• TransformContext::new has been replaced with dedicated functions that accept closures. (#385)
• CallFuture only makes an inter-canister call if it is awaited. (#391)