Crate ic_cdk_bitcoin_canister

Expand description

§ic-cdk-bitcoin-canister

This crate provides functionality for making inter-canister calls to the Bitcoin canisters.

The Bitcoin canisters allow for interactions with the Bitcoin network from within the Internet Computer. This crate includes functions and types that facilitate these interactions, adhering to the Bitcoin Canisters Interface Specification.

The types are re-exported from the ic_btc_interface crate.

§Bounded-wait vs. Unbounded-wait

Interacting with the Bitcoin canisters involves making inter-canister calls, which can be either bounded-wait or unbounded-wait.

Most of the functions in this crate use the bounded-wait calls because they only read state. The only function that uses the unbounded-wait call is bitcoin_send_transaction.

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

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

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

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

§Cycle Cost

All the Bitcoin canister methods require cycles to be attached to the call. The helper functions in this crate automatically calculate the required cycles and attach them to the call.

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

§Bitcoin Canister ID

The Bitcoin canister ID is determined by the network. The helper functions in this crate automatically determine the canister ID based on the network field in the request.

For completeness, the get_bitcoin_canister_id function can be used to get the canister ID manually.

Structs§

BlockchainInfo: Information about the blockchain as seen by the canister.
Config: The config of the canister.
Fees
GetBalanceRequest
GetBlockHeadersRequest: A request for getting the block headers from a given height.
GetBlockHeadersResponse: The response returned for a request for getting the block headers from a given height.
GetCurrentFeePercentilesRequest: A request for getting the current fee percentiles.
GetUtxosRequest: A request for getting the UTXOs for a given address.
GetUtxosResponse: The response returned for a request to get the UTXOs of a given address.
InitConfig: The config used to initialize the canister.
OutPoint: A reference to a transaction output.
SendTransactionRequest
SetConfigRequest: A request to update the canister’s config.
Txid
Utxo: An unspent transaction output.

Enums§

CanisterArg
Flag
GetBalanceError
GetBlockHeadersError: Errors when processing a get_block_headers request.
GetUtxosError: Errors when processing a get_utxos request.
Network
NetworkInRequest: A network enum that allows both upper and lowercase variants. Supporting both variants allows us to be compatible with the spec (lowercase) while not breaking current dapps that are using uppercase variants.
SendTransactionError
TxidFromStrError
UtxosFilter: A filter used when requesting UTXOs.
UtxosFilterInRequest: A UtxosFilter enum that allows both upper and lowercase variants. Supporting both variants allows us to be compatible with the spec (lowercase) while not breaking current dapps that are using uppercase variants.

Functions§

bitcoin_get_balance: Gets the current balance of a Bitcoin address in Satoshi.
bitcoin_get_block_headers: Gets the block headers in the provided range of block heights.
bitcoin_get_current_fee_percentiles: Gets the Bitcoin transaction fee percentiles.
bitcoin_get_utxos: Gets all unspent transaction outputs (UTXOs) associated with the provided address.
bitcoin_send_transaction: Sends a Bitcoin transaction to the Bitcoin network.
cost_get_balance: Gets the cycles cost for the bitcoin_get_balance function.
cost_get_block_headers: Gets the cycles cost for the bitcoin_get_block_headers function.
cost_get_current_fee_percentiles: Gets the cycles cost for the bitcoin_get_current_fee_percentiles function.
cost_get_utxos: Gets the cycles cost for the bitcoin_get_utxos function.
cost_send_transaction: Gets the cycles cost for the bitcoin_send_transaction function.
get_bitcoin_canister_id: Gets the canister ID of the Bitcoin canister for the specified network.
get_blockchain_info: Gets information about the current state of the Bitcoin blockchain as seen by the canister.

Type Aliases§

Address
BlockHash
BlockHeader
Height
MillisatoshiPerByte
Page
Satoshi