IC Management Canister

The IC management canister

The interfaces above provide the fundamental ability for external users and canisters to contact other canisters. But the Internet Computer provides additional functionality, such as canister and user management. This functionality is exposed to external users and canisters via the IC management canister.

Note

The IC management canister is just a facade; it does not actually exist as a canister (with isolated state, Wasm code, etc.).

The IC management canister address is aaaaa-aa (i.e. the empty blob).

It is possible to use the management canister via external requests (a.k.a. ingress messages). The cost of processing that request is charged to the canister that is being managed. Most methods only permit the controllers to call them. Calls to raw_rand and deposit_cycles are never accepted as ingress messages.

Interface overview

The interface description, in Candid syntax, describes the available functionality.

The binary encoding of arguments and results are as per Candid specification.

IC method create_canister

This method can only be called by canisters and subnet admins, i.e., it cannot be called by external users who are not subnet admins via ingress messages.

Before deploying a canister, the administrator of the canister first has to register it with the IC, to get a canister id (with an empty canister behind it), and then separately install the code.

The optional settings parameter can be used to set the following settings:

• controllers (vec principal)

  A list of at most 10 principals. The principals in this list become the controllers of the canister. Note that the caller of the create_canister call is not a controller of the canister unless it is a member of the controllers list.

  Default value: A list containing only the caller of the create_canister call.

• compute_allocation (nat)

  Must be a number between 0 and 100, inclusively. It indicates how much compute power should be guaranteed to this canister, expressed as a percentage of the maximum compute power that a single canister can allocate. If the IC cannot provide the requested allocation, for example because it is oversubscribed, the call will be rejected.

  Default value: 0

• memory_allocation (nat)

  Must be a number between 0 and 2⁶⁴-1, inclusively. It indicates an amount of memory in bytes that the canister is guaranteed to be allowed to use in total. If the IC cannot guarantee the requested memory allocation, for example because it is oversubscribed, then the call will be rejected.

  Default value: 0

• freezing_threshold (nat)

  Must be a number between 0 and 2⁶⁴-1, inclusively, and indicates a length of time in seconds.

  A canister is considered frozen whenever the IC estimates that the canister would be depleted of cycles before freezing_threshold seconds pass, given the canister’s current size and the IC’s current cost for storage.

  Calls to a frozen canister will be rejected with SYS_TRANSIENT reject code. Additionally, a canister cannot perform calls if that would, due the cost of the call and transferred cycles, would push the balance into frozen territory; these calls fail with ic0.call_perform returning a non-zero error code.

  Default value: 2592000 (approximately 30 days).

• reserved_cycles_limit (nat)

  Must be a number between 0 and 2¹²⁸-1, inclusively, and indicates the upper limit on reserved_cycles of the canister.

  An operation that allocates resources such as compute and memory will fail if the new value of reserved_cycles exceeds this limit.

  Default value: 5_000_000_000_000 (5 trillion cycles).

• wasm_memory_limit (nat)

  Must be a number between 0 and 2⁴⁸-1 (i.e., 256TB), inclusively, and indicates the upper limit on the WASM heap memory consumption of the canister in bytes.

  An operation (update method, canister init, canister post_upgrade) that causes the WASM heap memory consumption to exceed this limit will trap. The WASM heap memory limit is ignored for query methods, response callback handlers, global timers, heartbeats, and canister pre_upgrade.

  If set to 0, then there’s no upper limit on the WASM heap memory consumption of the canister subject to the available memory on the IC.

  Default value: 0 (i.e., no explicit limit).

  Note: in a future release of this specification, the default value and whether the limit is enforced for global timers and heartbeats might change.

• log_visibility (log_visibility)

  Controls who can access the canister’s logs through the fetch_canister_logs endpoint of the management canister. Can be one of:

  • controllers: Only the canister’s controllers can fetch logs
  • public: Anyone can fetch the canister’s logs
  • allowed_viewers (vec principal): Only principals in the provided list and the canister’s controllers can fetch logs, the maximum length of the list is 10

  Default value: controllers.

• snapshot_visibility (snapshot_visibility)

  Controls who can access the canister’s snapshots through the following endpoints of the management canister:

  • read_canister_snapshot_metadata
  • read_canister_snapshot_data
  • list_canister_snapshots

  Can be one of:

  • controllers: Only the canister’s controllers can read its snapshots
  • public: Anyone can read the canister’s snapshots
  • allowed_viewers (vec principal): Only principals in the provided list and the canister’s controllers can read its snapshots, the maximum length of the list is 10

  Default value: controllers.

• wasm_memory_threshold (nat)

  Must be a number between 0 and 2⁶⁴-1, inclusively, and indicates the threshold on the remaining wasm memory size of the canister in bytes: if the remaining wasm memory size of the canister is below the threshold, execution of the “on low wasm memory” hook is scheduled.

  Default value: 0 (i.e., the “on low wasm memory” hook is never scheduled).

• environment_variables (environment_variables)

  A record containing key-value pairs where both key and value are UTF-8 encoded strings. These variables are accessible to the canister during execution and can be used to configure canister behavior without code changes. Each key must be unique.

  The maximum number of environment variables is implementation-defined. The maximum length of keys and values is implementation-defined.

  Default value: null (i.e., no environment variables provided).

The optional sender_canister_version parameter can contain the caller’s canister version. If provided, its value must be equal to ic0.canister_version.

Until code is installed, the canister is Empty and behaves like a canister that has no public methods.

Cycles to pay for the call must be explicitly transferred with the call, i.e., they are not automatically deducted from the caller’s balance implicitly (e.g., as for inter-canister calls). (No cycles are required on subnets that have a non-empty list of subnet admins.)

IC method update_settings

This method can be called by canisters as well as by external users via ingress messages.

Only controllers of the canister can update settings. See IC method for a description of settings.

Not including a setting in the settings record means not changing that field. The defaults described above are only relevant during canister creation.

The optional sender_canister_version parameter can contain the caller’s canister version. If provided, its value must be equal to ic0.canister_version.

IC method upload_chunk

This method can be called by canisters as well as by external users via ingress messages.

Canisters have associated some storage space (hence forth chunk storage) where they can hold chunks of Wasm modules that are too lage to fit in a single message. This method allows the controllers of a canister (and the canister itself) to upload such chunks. The method returns the hash of the chunk that was stored. The size of each chunk must be at most 1MiB. The maximum number of chunks in the chunk store is CHUNK_STORE_SIZE chunks. The storage cost of each chunk is fixed and corresponds to storing 1MiB of data.

IC method clear_chunk_store

This method can be called by canisters as well as by external users via ingress messages.

Canister controllers (and the canister itself) can clear the entire chunk storage of a canister.

IC method stored_chunks

This method can be called by canisters as well as by external users via ingress messages.

Canister controllers (and the canister itself) can list the hashes of chunks in the chunk storage of a canister.

IC method install_code

This method can be called by canisters as well as by external users via ingress messages.

This method installs code into a canister.

Only controllers of the canister can install code.

• If mode = variant { install }, the canister must be empty before. This will instantiate the canister module and invoke its canister_init method (if present), as explained in Section “Canister initialization”, passing the arg to the canister.

• If mode = variant { reinstall }, if the canister was not empty, its existing code and state (including stable memory) is removed before proceeding as for mode = install.

  Note that this is different from uninstall_code followed by install_code, as uninstall_code generates a synthetic reject response to all callers of the uninstalled canister that the uninstalled canister did not yet reply to and ensures that callbacks to outstanding calls made by the uninstalled canister won’t be executed (i.e., upon receiving a response from a downstream call made by the uninstalled canister, the cycles attached to the response are refunded, but no callbacks are executed).

• If mode = variant { upgrade } or mode = variant { upgrade = opt record { skip_pre_upgrade = .., wasm_memory_persistence = .. } }, this will perform an upgrade of a non-empty canister as described in Canister upgrades, passing arg to the canister_post_upgrade method of the new instance. If skip_pre_upgrade = opt true, then the canister_pre_upgrade method on the old instance is not executed. If wasm_memory_persistence = opt keep, then the WebAssembly memory is preserved.

This is atomic: If the response to this request is a reject, then this call had no effect.

Note

Some canisters may not be able to make sense of callbacks after upgrades; these should be stopped first, to wait for all outstanding callbacks, or be uninstalled first, to prevent outstanding callbacks from being invoked (by marking the corresponding call contexts as deleted). It is expected that the canister admin (or their tooling) does that separately.

The wasm_module field specifies the canister module to be installed. The system supports multiple encodings of the wasm_module field, as described in Canister module format:

• If the wasm_module starts with byte sequence [0x00, 'a', 's', 'm'], the system parses wasm_module as a raw WebAssembly binary.

• If the wasm_module starts with byte sequence [0x1f, 0x8b, 0x08], the system parses wasm_module as a gzip-compressed WebAssembly binary.

The optional sender_canister_version parameter can contain the caller’s canister version. If provided, its value must be equal to ic0.canister_version.

This method traps if the canister’s cycle balance decreases below the canister’s freezing limit after executing the method.

IC method install_chunked_code

This method can be called by canisters as well as by external users via ingress messages.

This method installs code that had previously been uploaded in chunks.

Only controllers of the target canister can call this method.

The mode, arg, and sender_canister_version parameters are as for install_code. The target_canister specifies the canister where the code should be installed. The optional store_canister specifies the canister in whose chunk storage the chunks are stored (this parameter defaults to target_canister if not specified). For the call to succeed, the caller must be a controller of the store_canister or the caller must be the store_canister. The store_canister must be on the same subnet as the target canister.

The chunk_hashes_list specifies a list of hash values [h1,...,hk] with k <= MAX_CHUNKS_IN_LARGE_WASM. The system looks up in the chunk store of store_canister (or that of the target canister if store_canister is not specified) blobs corresponding to h1,...,hk and concatenates them to obtain a blob of bytes referred to as wasm_module in install_code. It then checks that the SHA-256 hash of wasm_module is equal to the wasm_module_hash parameter and calls install_code with parameters (record {mode; target_canister; wasm_module; arg; sender_canister_version}).

IC method uninstall_code

This method can be called by canisters as well as by external users via ingress messages.

This method removes a canister’s code and state, making the canister empty again.

Only controllers of the canister or subnet admins can uninstall code.

Uninstalling a canister’s code will reject all calls that the canister has not yet responded to, and drop the canister’s code and state. Outstanding responses to the canister will not be processed, even if they arrive after code has been installed again. Cycles attached to such responses will still be refunded though.

The canister is now empty. In particular, any incoming or queued calls will be rejected.

A canister after uninstalling retains its cycle balances, controllers, history, status, and allocations.

The optional sender_canister_version parameter can contain the caller’s canister version. If provided, its value must be equal to ic0.canister_version.

IC method canister_status

This method can be called by canisters as well as by external users via ingress messages. This method can also be called by external users via non-replicated (query) calls, but it cannot be called from composite query calls.

Indicates various information about the canister. It contains:

• The status of the canister. It could be one of running, stopping or stopped.

• A bool ready_for_migration indicating whether a stopped canister is ready to be migrated to another subnet (i.e., whether it has empty queues and flushed streams). This flag can only ever be true if the status variant (see above) is stopped. This property is guaranteed by the protocol, but deliberately not on the type level in order to facilitate backwards compatible service evolution.

• The canister version.

• The “settings” of the canister containing:

  • The controllers of the canister. The order of returned controllers may vary depending on the implementation.

  • The compute allocation of the canister.

  • The memory allocation of the canister in bytes.

  • The freezing threshold of the canister in seconds.

  • The reserved cycles limit of the canister, i.e., the maximum number of cycles that can be in the canister’s reserved balance after increasing the canister’s memory allocation and/or actual memory usage.

  • The visibility of the canister’s logs.

  • The visibility of the canister’s snapshots.

  • The WASM heap memory limit of the canister in bytes (the value of 0 means that there is no explicit limit).

  • The “low wasm memory” threshold, which is used to determine when the canister_on_low_wasm_memory function is executed.

  • The environment variables of the canister, which is a record containing key-value pairs used to configure the canister’s behavior.

• A SHA256 hash of the module installed on the canister. This is null if the canister is empty.

• The actual memory usage of the canister, representing the total memory consumed by the canister.

• A record containing detailed breakdown of memory usage into individual components (see Memory Metrics for more details).

• The cycle balance of the canister.

• The reserved cycles balance of the canister, i.e., the number of cycles reserved when increasing the canister’s memory allocation and/or actual memory usage.

• The idle cycle consumption of the canister, i.e., the number of cycles burned by the canister per day due to its compute and memory allocation and actual memory usage.

• Statistics regarding the query call execution of the canister, i.e., a record containing the following fields:

  • num_calls_total: the total number of query and composite query methods evaluated on the canister,

  • num_instructions_total: the total number of WebAssembly instructions executed during the evaluation of query and composite query methods,

  • request_payload_bytes_total: the total number of query and composite query method payload bytes, and

  • response_payload_bytes_total: the total number of query and composite query response payload (reply data or reject message) bytes.

Only the controllers of the canister or the canister itself or subnet admins can request its status.

Memory Metrics

* `wasm_memory_size`: Represents the Wasm memory usage of the canister, i.e. the heap memory used by the canister's WebAssembly code.

* `stable_memory_size`: Represents the stable memory usage of the canister.

* `global_memory_size`: Represents the memory usage of the global variables that the canister is using.

* `wasm_binary_size`: Represents the memory occupied by the Wasm binary that is currently installed on the canister. This is the size of the binary uploaded via `install_code` or `install_chunked_code`, e.g., the compressed size if the uploaded binary is gzipped.

* `custom_sections_size`: Represents the memory used by custom sections defined by the canister, which may include additional metadata or configuration data.

* `canister_history_size`: Represents the memory used for storing the canister's history.

* `wasm_chunk_store_size`: Represents the memory used by the Wasm chunk store of the canister.

* `snapshots_size`: Represents the memory consumed by all snapshots that belong to this canister.

All sizes are expressed in bytes.

IC method canister_info

This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.

Provides the history of the canister, its current module SHA-256 hash, and its current controllers. Every canister can call this method on every other canister (including itself). Users cannot call this method.

The canister history consists of a list of canister changes (canister creation, code uninstallation, code deployment, loading a snapshot, controllers change, canister renaming). Every canister change consists of the system timestamp at which the change was performed, the canister version after performing the change, the change’s origin (a user or a canister), and its details. The change origin includes the principal (called originator in the following) that initiated the change and, if the originator is a canister, the originator’s canister version when the originator initiated the change (if available).

• Canister creation is described by the full set of controllers along with a hash of the environment variables, if environment variables were specified. The order of controllers stored in the canister history may vary depending on the implementation.
• Code deployment is described by its mode (code install, code reinstall, code upgrade) and the SHA-256 hash of the newly deployed canister module.
• Loading a snapshot is described by the canister ID of the canister from which the snapshot was loaded (if that canister ID is different than the canister ID onto which the snapshot is loaded), the snapshot ID, the canister version and timestamp at which the snapshot was taken (the canister version and timestamp refer to the canister from which the snapshot was loaded), and the source of the snapshot (canister state or metadata upload).
• Controllers change is described by the full new set of controllers after the change. The order of controllers stored in the canister history may vary depending on the implementation.
• Canister renaming is described by the canister ID and the total number of canister changes before renaming as well as the canister ID, the canister version, and the total number of canister changes of the new canister ID. Because only a dedicated NNS canister can perform canister renaming, the actual principal who requested canister renaming is recorded in a separate field requested_by. The total number of canister changes reported by the IC method canister_info is overriden to the total number of canister changes of the new canister ID. Canister changes referring to the canister ID before renaming are preserved.

The system can drop the oldest canister changes from the list to keep its length bounded (at least 20 changes are guaranteed to remain in the list). The system also drops all canister changes if the canister runs out of cycles.

The following parameters should be supplied for the call:

• canister_id: the canister ID of the canister to retrieve information about.

• num_requested_changes: optional, specifies the number of requested canister changes. If not provided, the default value of 0 will be used.

The returned response contains the following fields:

• total_num_changes: the total number of canister changes that have been ever recorded in the history. This value does not change if the system drops the oldest canister changes from the list of changes.

• recent_changes: the list containing the most recent canister changes. If num_requested_changes is provided, then this list contains that number of changes or, if more changes are requested than available in the history, then this list contains all changes available in the history. If num_requested_changes is not specified, then this list is empty.

• module_hash: the SHA-256 hash of the currently installed canister module (or null if the canister is empty).

• controllers: the current set of canister controllers. The order of returned controllers may vary depending on the implementation.

IC method canister_metadata

This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.

Provides access to canister’s metadata contained in custom sections whose names have the form icp:public <name> or icp:private <name> (see Canister module format for requirements on custom sections).

Every canister can retrieve public metadata (in custom sections whose names have the form icp:public <name>) of every other canister (including itself). Only controllers of a canister can access its private metadata (in custom sections whose names have the form icp:private <name>).

The following parameters should be supplied for the call:

• canister_id (principal): the canister ID of the canister to retrieve metadata from.

• name (text): identifies canister’s metadata contained in a custom section whose name has the form icp:public <name> or icp:private <name> (note that a canister cannot have custom sections with both icp:public <name> or icp:private <name> as names for the same <name>, see Canister module format).

The returned response contains the following fields:

• value (blob): the content of canister’s metadata identified by the given name.

IC method stop_canister

This method can be called by canisters as well as by external users via ingress messages.

The controllers of a canister or subnet admins may stop a canister (e.g., to prepare for a canister upgrade).

When this method successfully returns, then the canister status is stopped at that point. However, note that the canister might be restarted at any time due to a concurrent call.

The execution of this method proceeds as follows:

• The immediate effect is that the status of the canister is changed to stopping (unless the canister is already stopped).
• The IC now rejects all calls to a stopping canister, indicating that the canister is stopping. Responses to a stopping canister are processed as usual.
• When all outstanding responses have been processed (so that there are no open call contexts), the canister status is changed to stopped.
• If the canister status is changed to stopped within an implementation-specific timeout, then this method successfully returns.
• Otherwise, this method returns an error (the canister status is still stopping and might eventually become stopped if all outstanding responses have been processed and the canister has not been restarted by a separate call).

IC method start_canister

This method can be called by canisters as well as by external users via ingress messages.

A canister may be started by its controllers or subnet admins.

If the canister status was stopped or stopping then the canister status is simply set to running. In the latter case all stop_canister calls which are processing fail (and are rejected).

If the canister was already running then the status stays unchanged.

IC method delete_canister

This method can be called by canisters as well as by external users via ingress messages.

This method deletes a canister from the IC.

Only controllers of the canister or subnet admins can delete it and the canister must already be stopped. Deleting a canister cannot be undone, any state stored on the canister is permanently deleted and its cycles are discarded. Once a canister is deleted, its ID cannot be reused.

IC method deposit_cycles

This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.

This method deposits the cycles included in this call into the specified canister.

IC method raw_rand

This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.

This method takes no input and returns 32 pseudo-random bytes to the caller. The return value is unknown to any part of the IC at time of the submission of this call. A new return value is generated for each call to this method.

IC method ecdsa_public_key

This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.

This method returns a SEC1 encoded ECDSA public key for the given canister using the given derivation path. If the canister_id is unspecified, it will default to the canister id of the caller. The derivation_path is a vector of variable length byte strings. Each byte string may be of arbitrary length, including empty. The total number of byte strings in the derivation_path must be at most 255. The key_id is a struct specifying both a curve and a name. The availability of a particular key_id depends on the implementation.

For curve secp256k1, the public key is derived using a generalization of BIP32 (see ia.cr/2021/1330, Appendix D). To derive (non-hardened) BIP32-compatible public keys, each byte string (blob) in the derivation_path must be a 4-byte big-endian encoding of an unsigned integer less than 2³¹. If the derivation_path contains a byte string that is not a 4-byte big-endian encoding of an unsigned integer less than 2³¹, then a derived public key will be returned, but that key derivation process will not be compatible with the BIP32 standard.

The return value is an extended public key consisting of an ECDSA public_key, encoded in SEC1 compressed form, and a chain_code, which can be used to deterministically derive child keys of the public_key.

This call requires that an ECDSA key with ID key_id was generated by the IC. Otherwise, the call is rejected.

IC method sign_with_ecdsa

This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.

This method returns a new ECDSA signature of the given message_hash that can be separately verified against a derived ECDSA public key. This public key can be obtained by calling ecdsa_public_key with the caller’s canister_id, and the same derivation_path and key_id used here.

Note

If the signing request returns a reject response whose reject code is SYS_UNKNOWN or CANISTER_ERROR, the signature may exist in the system even though it’s not returned to the requesting canister. Thus, canisters should not rely on the signature not existing in these cases.

The signatures are encoded as the concatenation of the SEC1 encodings of the two values r and s. For curve secp256k1, this corresponds to 32-byte big-endian encoding.

This call requires that an ECDSA key with ID key_id was generated by the IC, the signing functionality for that key was enabled, and message_hash is 32 bytes long. Otherwise, the call is is rejected.

Cycles to pay for the call must be explicitly transferred with the call, i.e., they are not automatically deducted from the caller’s balance implicitly (e.g., as for inter-canister calls).

IC method schnorr_public_key

This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.

This method returns a (derived) Schnorr public key for the given canister using the given derivation path. If the canister_id is unspecified, it will default to the canister id of the caller. The derivation_path is a vector of variable length byte strings. Each byte string may be of arbitrary length, including empty. The total number of byte strings in the derivation_path must be at most 255. The key_id is a struct specifying both an algorithm and a name. The availability of a particular key_id depends on the implementation.

The return value is an extended Schnorr public key consisting of a Schnorr public_key and a chain_code. The chain code can be used to deterministically derive child keys of the public_key. Both the derivation and the encoding of the public key depends on the key ID’s algorithm:

• For algorithm bip340secp256k1, the public key is derived using the generalization of BIP32 defined in ia.cr/2021/1330, Appendix D. To derive (non-hardened) BIP32-compatible public keys, each byte string (blob) in the derivation_path must be a 4-byte big-endian encoding of an unsigned integer less than 2³¹. If the derivation_path contains a byte string that is not a 4-byte big-endian encoding of an unsigned integer less than 2³¹, then a derived public key will be returned, but that key derivation process will not be compatible with the BIP32 standard.

  The public key is encoded in SEC1 compressed form. To use BIP32 public keys to verify BIP340 Schnorr signatures, the first byte of the (33-byte) SEC1-encoded public key must be removed (see BIP-340, Public Key Conversion).

• For algorithm ed25519, the public key is derived using the scheme specified in Ed25519 hierarchical key derivation.

  The public key is encoded in standard 32-byte compressed form (see RFC8032, 5.1.2 Encoding).

This call requires that a Schnorr key with ID key_id was generated by the IC. Otherwise, the call is rejected.

Ed25519 hierarchical key derivation

This section describes a child key derivation (CKD) function for computing child public keys from Ed25519 parent public keys. The section is inspired by BIP32 and uses similar wording and structure.

Motivation

To support the Ed25519 variant of threshold Schnorr signatures on the Internet Computer, a key derivation scheme compatible with Ed25519 signatures is required. For a respective signing service on the Internet Computer to be efficient, the signing subnet maintains only a single master key pair and derives signing child keys for each canister. Although there exist various hierarchical key derivation schemes (e.g., BIP32, SLIP10, BIP32-Ed25519, Schnorrkel), all of the analyzed schemes are either incompatible in a threshold setting (e.g., use hardened key derivation only), comply with clamping which adds unnecessary complexity, or otherwise rely on non-standard primitives. For these reasons, a new derivation scheme is specified here. This scheme does not make use of clamping (see RFC8032, Section 5.1.5, Item 2), because it is unnecessary in the given setting, and satisfies the following requirements:

• Off-chain availability: New public keys can be computed off-chain from a master public key without requiring interaction with the IC.
• Hierarchical derivation: Derived keys are organized in a tree such that from any public key it is possible to derive new child keys. The first level is used to derive unique canister-specific keys from the master key.
• Simplicity: The scheme is simple to implement using existing libraries.

Conventions

We will assume the elliptic curve (EC) operations using the field and curve parameters as defined by Ed25519 (see RFC8032, Section 5.1). Variables below are either:

• Integers modulo the order of the curve’s prime order subgroup (referred to as L).
• Points on the curve.
• Byte sequences.

Addition (+) of two points is defined as application of the EC group operation. Concatenation (||) is the operation of appending one byte sequence onto another.

We assume the following functions:

• point(p): returns the point resulting from EC point multiplication (repeated application of the EC group operation) of the Ed25519 base point with the integer p.
• ser_P(P): serializes the point to a byte sequence using standard 32-byte compressed form (see RFC8032, 5.1.2 Encoding).
• utf8(s): returns the UTF-8 encoding of string s.
• parse₅₁₂(p): interprets a 64-byte sequence as a 512-bit number, most significant byte first.
• HKDF(salt,IKM,info,N) -> OKM: HMAC-based key derivation function (see RFC5869) using HMAC-SHA512 (see RFC4231) calculating N-bytes long output key material (OKM) from (byte sequences) salt, input key material (IKM), and application specific information info.

Extended keys

Public keys are extended with an extra 32 bytes of entropy, which extension is called chain code. An extended public key is represented as (K, c), with K = point(k) and c being the chain code, for some private key k. Each extended key can have an arbitrary number of child keys. The scheme does not support hardened derivation of child keys.

Child key derivation (CKD) function

Given a parent extended public key and an index i, it is possible to compute the corresponding child extended public key. The function CKDpub computes a child extended public key from a parent extended public key and an index i, where i is a byte sequence of arbitrary length (including empty).

CKDpub((K_par, c_par), i) → (K_i, c_i):

• let IKM = ser_P(K_par) || i.
• let OKM = HKDF(c_par, IKM, utf8(“Ed25519”), 96).
• Split OKM into a 64-byte and a 32-byte sequence, tweak and c_i.
• let K_i = K_par + point(parse₅₁₂(tweak) mod L).
• return (K_i, c_i).

Key tree

A key tree can be built by repeatedly applying CKDpub, starting with one root, called the master extended public key M. Computing CKDpub(M, i) for different values of i results in a number of level-0 derived keys. As each of these is again an extended key, CKDpub can be applied to those as well. The sequence of indices used when repeatedly applying CKDpub is called the derivation path.

The function KTpub computes a child extended public key from a parent extended public key and a derivation path d.

KTpub((K_par, c_par), d) → (K_d, c_d):

• let (K_d, c_d) = (K_par, c_par)
• for all indices i in d: (K_d, c_d) = CKDpub((K_d, c_d), i)
• return (K_d, c_d).

IC method sign_with_schnorr

This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.

This method returns a Schnorr signature of the given message that can be verified against a (derived) public key obtained by calling schnorr_public_key using the caller’s canister_id and the given derivation_path and key_id.

Note

If the signing request returns a reject response whose reject code is SYS_UNKNOWN or CANISTER_ERROR, the signature may exist in the system even though it’s not returned to the requesting canister. Thus, canisters should not rely on the signature not existing in these cases.

The encoding of the signature depends on the key ID’s algorithm:

• For algorithm bip340secp256k1, the signature is encoded in 64 bytes according to BIP340.

• For algorithm ed25519, the signature is encoded in 64 bytes according to RFC8032, 5.1.6 Sign. Note that the returned signature is non-deterministic and a different signature may be computed every time it is requested.

This call requires that a Schnorr key with ID key_id was generated by the IC and the signing functionality for that key was enabled. Otherwise, the call is rejected.

This call accepts an optional auxiliary parameter aux. The auxiliary parameter type schnorr_aux is an enumeration. The only currently supported variant is bip341 which allows passing a Merkle tree root hash, which is required to implement Taproot signatures as defined in BIP341. The bip341 variant is only allowed for bip340secp256k1 signatures, and if provided the merkle_root_hash must be generated in accordance with BIP341’s specification for taproot_output_script. Specifically it should be either an empty bytestring (for the script == None case) or else 32 bytes generated using the procedure documented as taproot_tree_helper. If no auxiliary parameter is provided, then bip340secp256k1 signatures are generated in accordance with BIP340.

On the Internet Computer, the tuple of the requested master key, the calling canister, and derivation path determines which private key is used to generate the signature, and which public key is returned by schnorr_public_key.

When using BIP341 signatures, the actual signature that is created will be relative to the Schnorr signature derived as described in BIP341’s taproot_sign_script. The key returned by schnorr_public_key is the value identified in BIP341 as internal_pubkey.

Cycles to pay for the call must be explicitly transferred with the call, i.e., they are not automatically deducted from the caller’s balance implicitly (e.g., as for inter-canister calls).

IC method vetkd_public_key

This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.

This method returns the vetKD public (verification) key derived from the vetKD master public key with ID key_id for the canister with the given canister_id and the given context.

If the canister_id is unspecified, it will default to the canister id of the caller. The context is a byte string of variable length. The key_id is a struct specifying both a curve and a name. The availability of a particular key_id depends on the implementation.

The public key returned for an empty context is called canister public key. Given this canister public key, the public key for a particular context can also be derived offline.

For curve bls12_381_g2, the returned public_key is a G₂ element in compressed form in BLS Signatures Draft RFC encoding.

This call requires that a vetKD master key with ID key_id was generated by the IC and the key derivation functionality for that key was enabled, and that the canister_id meets the requirement of a canister id. Otherwise, the call is is rejected.

IC method vetkd_derive_key

This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.

This method returns a vetKD key (aka vetKey) encrypted under transport_public_key and derived from the vetKD master key with ID key_id based on the caller’s input for a given context.

Both the input and the context are byte strings of variable length. While both are inputs to the underlying key derivation algorithm (implicitly together with the calling canister’s ID), input is intended as the primary differentiator when deriving different keys, while context is intended as domain separator. The key_id is a struct specifying both a curve and a name. The availability of a particular key_id depends on the implementation.

Both the encrypted and the decrypted form of the vetKD key can be verified by using the respective vetKD public (verification) key, which can be obtained by calling the IC method vetkd_public_key.

For curve bls12_381_g2, the following holds:

• The transport_public_key is a G₁ element in compressed form in BLS Signatures Draft RFC encoding. Transport public keys are created by calculating tpk = g₁^tsk, where the transport secret key tsk is chosen uniformly at random from Z_p.

• The returned encrypted_key is the blob E1 · E2 · E3, where E₁ and E₃ are G₁ elements, and E₂ is a G₂ element, all in compressed form in BLS Signatures Draft RFC encoding.

  The encrypted key can be verified by ensuring e(E₁, g₂) == e(g₁, E₂), and e(E₃, g₂) == e(tpk, E₂) * e(H(dpk · input), dpk), where dpk is the derived (vetKD) public key associated with the respective context, key_id, and the canister ID of the caller.

• The decrypted vetKD key k is obtained by calculating E₃ * E₁^-tsk, where tsk ∈ Z_p is the transport secret key that was used to generate the transport_public_key.

  The key can be verified by ensuring e(k, g₂) == e(H(dpk · input), dpk), where dpk is the derived (vetKD) public key associated with the respective context, key_id, and the canister ID of the caller. Such verification protects against untrusted canisters returning invalid keys.

where

• g₁, g₂ are generators of G₁, G₂, which are groups of prime order p,

• * denotes the group operation in G₁, G₂, and G_T,

• e: G1 x G2 → GT is the pairing (see BLS Signatures Draft RFC, Appendix A),

• H hashes into G₁ according to the BLS12-381 message augmentation scheme ciphersuite in the BLS Signatures Draft RFC (see also Hashing to Elliptic Curves Draft RFC),

• · and · denote concatenation

This call requires that a vetKD master key with ID key_id was generated by the IC and the key derivation functionality for that key was enabled. Otherwise, the call is is rejected.

Cycles to pay for the call must be explicitly transferred with the call, i.e., they are not automatically deducted from the caller’s balance implicitly (e.g., as for inter-canister calls).

IC method http_request

This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.

This method makes an HTTP request to a given URL and returns the HTTP response, possibly after a transformation.

The method can be called in either replicated or non-replicated mode. In the replicated mode, the same HTTP request is performed by multiple IC replicas, providing strong guarantees on the integrity of the response. In the non-replicated mode, the request is made by a single replica, with weak integrity guarantees.

Note

The non-replicated mode is considered EXPERIMENTAL. Canister developers must be aware that the API may evolve in a non-backward-compatible way.

Both because of replication and to handle network issues, the canister should aim to issue idempotent requests, meaning that it must not change the state at the remote server, or that the remote server has the means to identify duplicated requests. Otherwise, the risk of failure increases.

In the replicated mode, the responses for all identical requests must match, too. However, a web service could return slightly different responses for identical idempotent requests. For example, it may include some unique identification or a timestamp that would vary across responses.

For this reason, the calling canister can supply a transformation function, which the IC uses to let the canister sanitize the responses from such unique values. The transformation function is executed separately on the corresponding response received for a request (both in replicated and non-replicated modes). Only the transformed response will be available to the calling canister.

Currently, the GET, HEAD, and POST methods are supported for HTTP requests. Additionally, the PUT and DELETE methods are supported in non-replicated mode only. PUT and DELETE are restricted to non-replicated mode to avoid confusing race conditions that may occur with replicated execution.

It is important to note the following for the usage of the POST method:

• The calling canister must make sure that the remote server is able to recognize requests as duplicates of each other and apply only one of them, even if they are sent from multiple sources. This may require, for example, to set a certain request header to uniquely identify the request. This is especially important in the replicated mode.

• There is no guarantee that all sent requests are as specified by the canister.

Furthermore, for all methods, the following holds:

• There are no confidentiality guarantees on the request or response content.

• In the replicated mode, if the canister receives a response, then at least one request that was sent matched the canister’s request, and the response was to that request. In the non-replicated mode, there are no such guarantees. The canister should not assume the integrity of the response and must check it by some other means.

For security reasons, only HTTPS connections are allowed (URLs must start with https://). The IC uses industry-standard root CA lists to validate certificates of remote web servers.

The size of an HTTP request from the canister or an HTTP response from the remote HTTP server is the total number of bytes representing the names and values of HTTP headers and the HTTP body. The maximal size for the request from the canister is 2MB (2,000,000B). Each request can specify a maximal size for the response from the remote HTTP server. The upper limit on the maximal size for the response is 2MB (2,000,000B) and this value also applies if no maximal size value is specified. An error will be returned when the request or response is larger than the maximal size.

The following parameters should be supplied for the call:

• url - the requested URL. The URL must be valid according to RFC-3986, it might contain non-ASCII characters according to RFC-3987, and its length must not exceed 8192. The URL may specify a custom port number.

• max_response_bytes - optional, specifies the maximal size of the response in bytes. If provided, the value must not exceed 2MB (2,000,000B). The call will be charged based on this parameter. If not provided, the maximum of 2MB will be used.

• method - currently, GET, HEAD, and POST are supported. Additionally, PUT and DELETE are supported in non-replicated mode only.

• headers - list of HTTP request headers and their corresponding values

• body - optional, the content of the request’s body

• transform - an optional record that includes a function that transforms raw responses to sanitized responses, and a byte-encoded context that is provided to the function upon invocation, along with the response to be sanitized. If provided, the calling canister itself must export this function

• is_replicated - optional, selecting between replicated and non-replicated modes.

Note

The is_replicated field is considered EXPERIMENTAL.

Cycles to pay for the call must be explicitly transferred with the call, i.e., they are not automatically deducted from the caller’s balance implicitly (e.g., as for inter-canister calls).

The returned response (and the response provided to the transform function, if specified) contains the following fields:

• status - the response status (e.g., 200, 404)

• headers - list of HTTP response headers and their corresponding values

• body - the response’s body

The transform function may, for example, transform the body in any way, add or remove headers, modify headers, etc. The maximal number of bytes representing the response produced by the transform function is equal to max_response_bytes, if provided, otherwise the default value of 2MB (2,000,000B) is used as the limit. Note that the number of bytes representing the response produced by the transform function includes the serialization overhead of the encoding produced by the canister.

When the transform function is invoked by the system due to a canister HTTP request, the caller’s identity is the principal of the management canister. This information can be used by developers to implement an access control mechanism for this function.

The following additional limits apply to HTTP requests and HTTP responses from the remote server:

• the number of headers must not exceed 64,

• the number of bytes representing a header name or value must not exceed 8KiB, and

• the total number of bytes representing the header names and values must not exceed 48KiB.

If the request headers provided by the canister do not contain a user-agent header (case-insensitive), then the IC sends a user-agent header (case-insensitive) with the value ic/1.0 in addition to the headers provided by the canister. Such an additional header does not contribute to the above limits on HTTP request headers.

Note

The Internet Computer mainnet supports requests to both IPv6 and IPv4 destinations. The system prioritizes a direct connection to IPv6 addresses (i.e., the domain has a AAAA DNS record). If a direct connection cannot be established (e.g., the domain only has an IPv4 address via an A record), the request is automatically retried through a proxy.

If you do not specify the max_response_bytes parameter, the maximum of a 2MB response will be charged for, which is expensive in terms of cycles. Always set the parameter to a reasonable upper bound of the expected (network and transformed) response size to not incur unnecessary cycles costs for your request.

IC method node_metrics_history

This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.

Note

The node metrics management canister API is considered EXPERIMENTAL. Canister developers must be aware that the API may evolve in a non-backward-compatible way.

Given a subnet ID as input, this method returns a time series of node metrics (field node_metrics). The timestamps are represented as nanoseconds since 1970-01-01 (field timestamp_nanos) at which the metrics were sampled. The returned timestamps are all timestamps after (and including) the provided timestamp (field start_at_timestamp_nanos) for which node metrics are available. The maximum number of returned timestamps is 60 and no two returned timestamps belong to the same UTC day.

Note that a sample will only include metrics for nodes whose metrics changed compared to the previous sample. This means that if a node disappears in one sample and later reappears its metrics will restart from 0 and consumers of this API need to adjust for these resets when aggregating over multiple samples.

A single metric entry is a record with the following fields:

• node_id (principal): the principal characterizing a node;

• num_blocks_proposed_total (nat64): the number of blocks proposed by this node;

• num_block_failures_total (nat64): the number of failed block proposals by this node.

IC method subnet_info

This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.

Given a subnet ID as input, this method returns a record subnet_info containing metadata about that subnet.

The fields returned are:

• replica_version (text) of the targeted subnet
• registry_version (nat64) of the targeted subnet

IC method take_canister_snapshot

This method can be called by canisters as well as by external users via ingress messages.

This method takes a snapshot of the specified canister. A snapshot consists of the wasm memory, stable memory, certified variables, wasm chunk store and wasm binary.

A take_canister_snapshot call creates a new snapshot. However, the call might fail if the maximum number of snapshots per canister is reached. This error can be avoided by providing an existing snapshot ID via the optional replace_snapshot parameter. That existing snapshot will be deleted once a new snapshot has been successfully created.

It’s important to note that a new snapshot might increase the memory footprint of the canister. Thus, the canister’s balance must have a sufficient amount of cycles so that the canister does not become frozen. This issue can be mitigated by uninstalling code of the canister via the optional uninstall_code parameter after a new snapshot has been successfully created. The exact semantics of uninstalling code is described in the section on the IC method uninstall_code.

Only controllers can take a snapshot of a canister and load it back to the canister.

Note

It’s important to stop a canister before taking a snapshot to ensure that all outstanding callbacks are completed. Failing to do so may cause the canister to not make sense of the callbacks if its state is restored using the snapshot. It is expected that the canister controllers (or their tooling) do this separately.

The optional sender_canister_version parameter can contain the caller’s canister version. If provided, its value must be equal to ic0.canister_version.

IC method load_canister_snapshot

This method can be called by canisters as well as by external users via ingress messages.

This method loads a snapshot identified by snapshot_id onto the canister. It fails if no snapshot with the specified snapshot_id can be found.

The snapshot can only be loaded onto a canister that belongs to the same subnet as the canister from which the snapshot is loaded.

The caller must be a controller of

• the canister onto which the snapshot is loaded; and

• the canister from which the snapshot is loaded.

Note

It’s important to stop a canister before loading a snapshot to ensure that all outstanding callbacks are completed. Failing to do so may cause the canister to not make sense of the callbacks if its state is restored. It is expected that the canister controllers (or their tooling) do this separately.

The optional sender_canister_version parameter can contain the caller’s canister version. If provided, its value must be equal to ic0.canister_version.

IC method read_canister_snapshot_metadata

This method can be called by canisters as well as by external users via ingress messages.

Who is allowed to read the metadata of a snapshot of that canister is determined by the field snapshot_visibility in canister_settings and can be one of the following variants:

• controllers: Only the canister’s controllers can read its snapshots metadata
• public: Anyone can read the canister’s snapshots metadata
• allowed_viewers (vec principal): Only principals in the provided list and the canister’s controllers can read snapshots metadata, the maximum length of the list is 10

This method returns all metadata of a snapshot identified by snapshot_id of the canister identified by canister_id. It fails if no snapshot with the specified snapshot_id can be found for that canister.

The returned metadata of a snapshot contain:

• the “source” of the snapshot, i.e., whether the snapshot was created by taking the canister state using the method take_canister_snapshot or by (snapshot) metadata upload using the method upload_canister_snapshot_metadata;

• the timestamp at which the snapshot was created, i.e., the method take_canister_snapshot or upload_canister_snapshot_metadata executed;

• the size of the canister WASM (in bytes);

• values of WASM globals (not to be confused with global variables in a high-level programming language) that are either exported or mutable in the canister WASM;

• sizes of WASM (a.k.a. heap) and stable memory (in bytes);

• hashes of chunks in the WASM chunk store;

• the canister version when the snapshot was created, i.e., the method take_canister_snapshot or upload_canister_snapshot_metadata executed;

• the certified data;

• (optional) the state of the global timer, i.e., whether it is inactive or active with a deadline (in nanoseconds since 1970-01-01);

• (optional) the state of the on low wasm memory hook, i.e., whether the condition for the hook to be scheduled is not satisfied, the hook is ready to be executed (i.e., the hook has been scheduled), or the hook has already been executed.

The state of the global timer and on low wasm memory hook are null for existing snapshots created before release release-2025-04-03_03-15-base (68fc31a141b25f842f078c600168d8211339f422 rolled out between April 7, 2025, and April 14, 2025, in the ICP mainnet.

IC method read_canister_snapshot_data

This method can be called by canisters as well as by external users via ingress messages.

Who is allowed to read a snapshot of that canister is determined by the field snapshot_visibility in canister_settings and can be one of the following variants:

• controllers: Only the canister’s controllers can read its snapshots
• public: Anyone can read the canister’s snapshots
• allowed_viewers (vec principal): Only principals in the provided list and the canister’s controllers can read snapshots, the maximum length of the list is 10

This method returns a requested kind of (binary) data from a snapshot identified by snapshot_id of the canister identified by canister_id. It fails if no snapshot with the specified snapshot_id can be found for that canister.

The following kinds of (binary) data from a snapshot can be requested:

• chunk of the canister WASM starting at a given offset and with a given size of the chunk (offset + size must not exceed the canister WASM size as in the snapshot metadata);

• chunk of the WASM (a.k.a. heap) memory starting at a given offset and with a given size of the chunk (offset + size must not exceed the WASM memory size as in the snapshot metadata);

• chunk of the stable memory starting at a given offset and with a given size of the chunk (offset + size must not exceed the stable memory size as in the snapshot metadata);

• (full) chunk in the WASM chunk store identified by its hash (hash must be present in the snapshot metadata).

IC method upload_canister_snapshot_metadata

This method can be called by canisters as well as by external users via ingress messages.

Only controllers of a canister can create a snapshot of that canister by uploading the snapshot’s metadata.

An upload_canister_snapshot_metadata call creates a new snapshot. However, the call might fail if the maximum number of snapshots per canister is reached. This error can be avoided by providing an existing snapshot ID via the optional replace_snapshot parameter. That existing snapshot will be deleted once a new snapshot has been successfully created (in particular, before data is uploaded to that new snapshot using subsequent upload_canister_snapshot_data calls).

It’s important to note that a new snapshot will increase the memory footprint of the canister. Thus, the canister’s balance must have a sufficient amount of cycles so that the canister does not become frozen.

Uploaded metadata of a snapshot contain:

• the size of the canister WASM (in bytes);

• values of WASM globals (not to be confused with global variables in a high-level programming language) that are either exported or mutable in the canister WASM;

• sizes of WASM (a.k.a. heap) and stable memory (in bytes);

• the certified data;

• (optional) the state of the global timer, i.e., whether it is inactive or active with a deadline (in nanoseconds since 1970-01-01);

• (optional) the state of the on low wasm memory hook, i.e., whether the condition for the hook to be scheduled is not satisfied, the hook is ready to be executed (i.e., the hook has been scheduled), or the hook has already been executed.

If the state of the global timer and/or the on low wasm memory hook are not provided in the uploaded metadata, then their state is not updated when loading the snapshot using the method load_canister_snapshot.

IC method upload_canister_snapshot_data

This method can be called by canisters as well as by external users via ingress messages.

Only controllers of a canister can upload data to a snapshot of that canister.

This method uploads a provided (binary) chunk of a provided kind of (binary) data to a snapshot identified by snapshot_id of the canister identified by canister_id. It fails if no snapshot with the specified snapshot_id can be found for that canister or if the snapshot with the specified snapshot_id has been created using the method take_canister_snapshot (i.e., not by uploading snapshot metadata).

The following kinds of (binary) data can be uploaded to a snapshot:

• chunk of the canister WASM starting at a given offset (offset + |chunk| must not exceed the canister WASM size as in the snapshot metadata);

• chunk of the WASM (a.k.a. heap) memory starting at a given offset (offset + |chunk| must not exceed the WASM memory size as in the snapshot metadata);

• chunk of the stable memory starting at a given offset (offset + |chunk| must not exceed the stable memory size as in the snapshot metadata);

• (full) chunk in the WASM chunk store (the length |chunk| of the provided chunk must be at most 1MiB and the maximum number of chunks in the chunk store of the snapshot is CHUNK_STORE_SIZE chunks).

It’s important to note that uploading a chunk to the WASM chunk store of the snapshot will increase the memory footprint of the canister. Thus, the canister’s balance must have a sufficient amount of cycles so that the canister does not become frozen. On the other hand, uploading a chunk to the canister WASM, WASM (a.k.a.) heap memory, and stable memory does increase the memory footprint of the canister since their sizes have been fixed when uploading the snapshot’s metadata.

IC method list_canister_snapshots

This method can be called by canisters as well as by external users via ingress messages.

This method lists the snapshots of the canister identified by canister_id.

Who is allowed to list the snapshots of that canister is determined by the field snapshot_visibility in canister_settings and can be one of the following variants:

• controllers: Only the canister’s controllers can list its snapshots
• public: Anyone can list the canister’s snapshots
• allowed_viewers (vec principal): Only principals in the provided list and the canister’s controllers can list the snapshots, the maximum length of the list is 10

IC method delete_canister_snapshot

This method can be called by canisters as well as by external users via ingress messages.

This method deletes a specified snapshot that belongs to an existing canister. An error will be returned if the snapshot is not found.

A snapshot cannot be found if it was never created, it was previously deleted, replaced by a new snapshot through a take_canister_snapshot or upload_canister_snapshot_metadata request, or if the canister itself has been deleted or run out of cycles.

A snapshot may be deleted only by the controllers of the canister that the snapshot belongs to.

IC method fetch_canister_logs

This method can only be called by external users via non-replicated (query) calls, i.e., it cannot be called by canisters, cannot be called via replicated calls, and cannot be called from composite query calls.

Given a canister ID as input, this method returns a vector of logs of that canister including its trap messages. The canister logs are not collected in canister methods running in non-replicated mode (NRQ, TQ, CQ, CRy, CRt, CC, and F modes, as defined in Overview of imports) and the canister logs are purged when the canister is reinstalled or uninstalled. The total size of all returned logs does not exceed 4KiB. If new logs are added resulting in exceeding the maximum total log size of 4KiB, the oldest logs will be removed. Logs persist across canister upgrades and they are deleted if the canister is reinstalled or uninstalled.

The log visibility is defined in the log_visibility field of canister_settings and can be one of the following variants:

• controllers: only the canister’s controllers can fetch logs (default);
• public: everyone can fetch logs;
• allowed_viewers (vec principal): only principals in the provided list and the canister’s controllers can fetch logs, the maximum length of the list is 10.

A single log is a record with the following fields:

• idx (nat64): the unique sequence number of the log for this particular canister;
• timestamp_nanos (nat64): the timestamp as nanoseconds since 1970-01-01 at which the log was recorded;
• content (blob): the actual content of the log;

The response of a query comes from a single replica, and is therefore not appropriate for security-sensitive applications. Replica-signed queries may improve security because the recipient can verify the response comes from the correct subnet.

IC method list_canisters

This method can only be called by external users with subnet admin privileges via non-replicated (query) calls, i.e., it cannot be called by canisters, cannot be called via replicated calls, and cannot be called from composite query calls.

This method returns the list of all canisters on the subnet as consecutive canister ID ranges. Deleted canisters are not included in the result.

A canister ID range is a record with the following fields:

• start (principal): the first canister ID in the range (inclusive);
• end (principal): the last canister ID in the range (inclusive).

The response of a query comes from a single replica, and is therefore not appropriate for security-sensitive applications. Replica-signed queries may improve security because the recipient can verify the response comes from the correct subnet.

The IC Bitcoin API

The Bitcoin API exposed by the management canister is DEPRECATED. Developers should interact with the Bitcoin canisters (ghsi2-tqaaa-aaaan-aaaca-cai for Bitcoin mainnet and g4xu7-jiaaa-aaaan-aaaaq-cai for Bitcoin testnet) directly. Information about Bitcoin and the IC Bitcoin integration can be found in the Bitcoin developer guides and the Bitcoin integration documentation.

IC method bitcoin_get_utxos

Note

This method is DEPRECATED. Canister developers are advised to call the method of the same name on the Bitcoin (mainnet or testnet) canister.

This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.

Given a get_utxos_request, which must specify a Bitcoin address and a Bitcoin network (mainnet or testnet), the function returns all unspent transaction outputs (UTXOs) associated with the provided address in the specified Bitcoin network based on the current view of the Bitcoin blockchain available to the Bitcoin component. The UTXOs are returned sorted by block height in descending order.

The following address formats are supported:

• Pay to public key hash (P2PKH)

• Pay to script hash (P2SH)

• Pay to witness public key hash (P2WPKH)

• Pay to witness script hash (P2WSH)

• Pay to taproot (P2TR)

If the address is malformed, the call is rejected.

The optional filter parameter can be used to restrict the set of returned UTXOs, either providing a minimum number of confirmations or a page reference when pagination is used for addresses with many UTXOs. In the first case, only UTXOs with at least the provided number of confirmations are returned, i.e., transactions with fewer than this number of confirmations are not considered. In other words, if the number of confirmations is c, an output is returned if it occurred in a transaction with at least c confirmations and there is no transaction that spends the same output with at least c confirmations.

There is an upper bound of 144 on the minimum number of confirmations. If a larger minimum number of confirmations is specified, the call is rejected. Note that this is not a severe restriction as the minimum number of confirmations is typically set to a value around 6 in practice.

It is important to note that the validity of transactions is not verified in the Bitcoin component. The Bitcoin component relies on the proof of work that goes into the blocks and the verification of the blocks in the Bitcoin network. For a newly discovered block, a regular Bitcoin (full) node therefore provides a higher level of security than the Bitcoin component, which implies that it is advisable to set the number of confirmations to a reasonably large value, such as 6, to gain confidence in the correctness of the returned UTXOs.

There is an upper bound of 10,000 UTXOs that can be returned in a single request. For addresses that contain sufficiently many UTXOs, a partial set of the address’s UTXOs are returned along with a page reference.

In the second case, a page reference (a series of bytes) must be provided, which instructs the Bitcoin component to collect UTXOs starting from the corresponding “page”.

A get_utxos_request without the optional filter results in a request that considers the full blockchain, which is equivalent to setting min_confirmations to 0.

The recommended workflow is to issue a request with the desired number of confirmations. If the next_page field in the response is not empty, there are more UTXOs than in the returned vector. In that case, the page field should be set to the next_page bytes in the subsequent request to obtain the next batch of UTXOs.

IC method bitcoin_get_balance

Note

This method is DEPRECATED. Canister developers are advised to call the method of the same name on the Bitcoin (mainnet or testnet) canister.

This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.

Given a get_balance_request, which must specify a Bitcoin address and a Bitcoin network (mainnet or testnet), the function returns the current balance of this address in Satoshi (10^8 Satoshi = 1 Bitcoin) in the specified Bitcoin network. The same address formats as for bitcoin_get_utxos are supported.

If the address is malformed, the call is rejected.

The optional min_confirmations parameter can be used to limit the set of considered UTXOs for the calculation of the balance to those with at least the provided number of confirmations in the same manner as for the bitcoin_get_utxos call.

Given an address and the optional min_confirmations parameter, bitcoin_get_balance iterates over all UTXOs, i.e., the same balance is returned as when calling bitcoin_get_utxos for the same address and the same number of confirmations and, if necessary, using pagination to get all UTXOs for the same tip hash.

IC method bitcoin_send_transaction

Note

This method is DEPRECATED. Canister developers are advised to call the method of the same name on the Bitcoin (mainnet or testnet) canister.

This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.

Given a send_transaction_request, which must specify a blob of a Bitcoin transaction and a Bitcoin network (mainnet or testnet), several checks are performed:

• The transaction is well formed.

• The transaction only consumes unspent outputs with respect to the current (longest) blockchain, i.e., there is no block on the (longest) chain that consumes any of these outputs.

• There is a positive transaction fee.

If at least one of these checks fails, the call is rejected.

If the transaction passes these tests, the transaction is forwarded to the specified Bitcoin network. Note that the function does not provide any guarantees that the transaction will make it into the mempool or that the transaction will ever appear in a block.

IC method bitcoin_get_current_fee_percentiles

Note

This method is DEPRECATED. Canister developers are advised to call the method of the same name on the Bitcoin (mainnet or testnet) canister.

This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.

The transaction fees in the Bitcoin network change dynamically based on the number of pending transactions. It must be possible for a canister to determine an adequate fee when creating a Bitcoin transaction.

This function returns fee percentiles, measured in millisatoshi/vbyte (1000 millisatoshi = 1 satoshi), over the last 10,000 transactions in the specified network, i.e., over the transactions in the last approximately 4-10 blocks.

The standard nearest-rank estimation method, inclusive, with the addition of a 0th percentile is used. Concretely, for any i from 1 to 100, the ith percentile is the fee with rank ⌈i * 100⌉. The 0th percentile is defined as the smallest fee (excluding coinbase transactions).

IC method bitcoin_get_block_headers

Note

This method is DEPRECATED. Canister developers are advised to call the method of the same name on the Bitcoin (mainnet or testnet) canister.

This method can only be called by canisters, i.e., it cannot be called by external users via ingress messages.

Given a start height, an optional end height, and a Bitcoin network (mainnet or testnet), the function returns the block headers in the provided range. The range is inclusive, i.e., the block headers at the start and end heights are returned as well. An error is returned when an end height is specified that is greater than the tip height.

If no end height is specified, all blocks until the tip height, i.e., the largest available height, are returned. However, if the range from the start height to the end height or the tip height is large, only a prefix of the requested block headers may be returned in order to bound the size of the response.

The response is guaranteed to contain the block headers in order: if it contains any block headers, the first block header occurs at the start height, the second block header occurs at the start height plus one and so forth.

The response is a record consisting of the tip height and the vector of block headers. The block headers are 80-byte blobs in the standard Bitcoin format.

The IC Provisional API

The IC Provisional API for creating canisters and topping up canisters out of thin air is only available in local development instances.

IC method provisional_create_canister_with_cycles

This method can be called by canisters as well as by external users via ingress messages.

As a provisional method on development instances, the provisional_create_canister_with_cycles method is provided. It behaves as create_canister, but initializes the canister’s balance with amount fresh cycles (using DEFAULT_PROVISIONAL_CYCLES_BALANCE if amount = null). If specified_id is provided, the canister is created under this id. Note that canister creation using create_canister or provisional_create_canister_with_cycles with specified_id = null can fail after calling provisional_create_canister_with_cycles with provided specified_id. In that case, canister creation should be retried.

The optional sender_canister_version parameter can contain the caller’s canister version. If provided, its value must be equal to ic0.canister_version.

Cycles added to this call via ic0.call_cycles_add and ic0.call_cycles_add128 are returned to the caller.

This method is only available in local development instances.

IC method provisional_top_up_canister

This method can be called by canisters as well as by external users via ingress messages.

As a provisional method on development instances, the provisional_top_up_canister method is provided. It adds amount cycles to the balance of canister identified by amount.

Cycles added to this call via ic0.call_cycles_add and ic0.call_cycles_add128 are returned to the caller.

Any user can top-up any canister this way.

This method is only available in local development instances.