Native Bitcoin integration

A canister does not connect to Bitcoin nodes itself. The documentation describes a Bitcoin canister running on a system subnet that maintains a view of the Bitcoin blockchain, and a Bitcoin adapter that connects the network to the Bitcoin peer-to-peer network. Canisters read through the Bitcoin canister, which exposes methods for the data a wallet needs.

The documented methods cover the balance of an address, the UTXOs held by an address, the current fee percentiles, block headers, and general blockchain information such as the current height and the network. A canister that wants to construct a transaction needs the UTXOs to spend and a fee estimate, and both are available. The documentation notes that the Bitcoin canister's view follows the Bitcoin network with a delay, so a canister should not assume it sees the tip of the chain.

The documentation also describes the trust model for reads. The Bitcoin canister runs on a system subnet and its responses are subject to the network's consensus, so a canister reading a balance is trusting the network's view of Bitcoin rather than querying a node it chose. That is a different trust assumption from running your own node, and it is worth understanding before building anything that depends on the exact state of the chain.

Writing is a two-step process. The canister constructs a Bitcoin transaction — selecting UTXOs, building outputs, computing the sighash for each input — and then asks the management canister to sign the sighashes with the key that controls the address. The documentation describes the signing methods for both ECDSA and Schnorr, and the transaction is then submitted through the Bitcoin canister's send method.

The documentation is explicit about a caveat that matters for correctness. A signing request can return an error while the signature has in fact been produced, so a canister cannot treat a failed signing call as proof that no signature exists. A protocol that assumes otherwise can be made to sign twice, which for a Bitcoin transaction means two transactions spending the same UTXO. The chain-key cryptography page covers the signing protocol and this caveat.

Fees are a Bitcoin concern rather than a network one. The documentation describes a method that returns current fee percentiles, which a canister uses to choose a fee rate. A transaction that pays too little may sit unconfirmed for a long time, and a canister that wants to replace it must construct a replacement that spends the same inputs with a higher fee. None of this is abstracted away.

ckBTC is the network's chain-key token for bitcoin. The documentation describes it as an ICRC-1 token backed one-to-one by bitcoin held at an address the network controls, minted when a deposit is confirmed and redeemed when a holder wants the underlying. It exists because most applications want a token they can transfer at network speed rather than a UTXO they must manage.

The documentation describes a KYT check on deposits, performed by a dedicated canister, which screens incoming funds before minting. That is a policy layer rather than a cryptographic one, and it means a deposit can be refused. A user who wants to hold bitcoin without that policy should hold it directly at an address they control rather than in ckBTC.

The limits of the integration are worth stating. A canister can spend from addresses whose keys it derives; it cannot spend from arbitrary addresses, and it cannot reverse a Bitcoin transaction. Confirmation times are Bitcoin's, not the network's. And the whole arrangement depends on the network continuing to operate and to sign, which is the same dependency every application on the network has.