You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/concepts/chain-fusion/bitcoin.md
+17-30Lines changed: 17 additions & 30 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,15 +17,19 @@ Together, these two layers give a canister the ability to receive bitcoin, check
17
17
18
18
## Bitcoin canister API
19
19
20
-
The Bitcoin canister exposes three main endpoints accessible through the management canister:
20
+
The Bitcoin canister exposes endpoints accessible directly by other canisters:
21
21
22
22
-`bitcoin_get_balance`: returns the balance of any Bitcoin address.
23
23
-`bitcoin_get_utxos`: returns the unspent transaction outputs (UTXOs) for a given address. This is the primary input when constructing a Bitcoin transaction.
24
24
-`bitcoin_get_current_fee_percentiles`: returns recent fee rates so a canister can estimate an appropriate miner fee.
25
25
-`bitcoin_send_transaction`: broadcasts a signed transaction to the Bitcoin network via the adapter.
26
+
-`bitcoin_get_block_headers`: returns raw block headers for a range of heights.
27
+
-`get_blockchain_info`: returns current chain state including tip height, block hash, timestamp, difficulty, and UTXO count.
26
28
27
29
A typical flow for a canister spending bitcoin is: fetch UTXOs for its address, select inputs, build the transaction, call `sign_with_ecdsa` (or `sign_with_schnorr` for Taproot) for each input, then call `bitcoin_send_transaction`.
28
30
31
+
For canister IDs, cycle costs, and the full interface specification, see [Bitcoin canisters](../../references/protocol-canisters.md#bitcoin-canisters).
32
+
29
33
## Bitcoin checker canister
30
34
31
35
The Bitcoin checker canister (`oltsj-fqaaa-aaaar-qal5q-cai`) screens Bitcoin addresses and transactions against the [OFAC Specially Designated Nationals (SDN) list](https://sanctionslist.ofac.treas.gov/Home/SdnList). It is used by ckBTC and any canister that wants to avoid handling funds associated with sanctioned activity.
@@ -39,31 +43,22 @@ Both endpoints return `Passed` or `Failed`. The canister itself is controlled by
39
43
40
44
## Chain-key Bitcoin (ckBTC)
41
45
42
-
ckBTC is a digital asset on ICP backed 1:1 by real bitcoin. 1 ckBTC can always be redeemed for 1 BTC and vice versa. Unlike wrapped assets, ckBTC relies on no third-party custodian: the bitcoin is held by a canister-controlled address on the Bitcoin network, and the minting and burning happen entirely onchain.
43
-
44
-
ckBTC transactions settle in seconds and cost a fraction of a satoshi, making it practical for high-frequency or low-value transfers that would be uneconomical on Bitcoin directly.
45
-
46
-
### Canisters
46
+
ckBTC is an asset on ICP backed 1:1 by real bitcoin. 1 ckBTC can always be redeemed for 1 BTC and vice versa. Unlike wrapped assets, ckBTC relies on no third-party custodian: the bitcoin is held by a canister-controlled address on the Bitcoin network, and the minting and burning happen entirely onchain.
47
47
48
-
Two canisters run on the [pzp6e subnet](https://dashboard.internetcomputer.org/subnet/pzp6e-ekpqk-3c5x7-2h6so-njoeq-mt45d-h3h6c-q3mxf-vpeez-fez7a-iae), both controlled by the NNS root canister:
48
+
ckBTC transactions settle in seconds with minimal fees, making it practical for high-frequency or low-value transfers that would be uneconomical on Bitcoin directly.
49
49
50
-
| Canister | ID |
51
-
|----------|-----|
52
-
| ckBTC minter |`mqygn-kiaaa-aaaar-qaadq-cai`|
53
-
| ckBTC ledger |`mxzaz-hqaaa-aaaar-qaada-cai`|
50
+
Two canisters run on the [pzp6e subnet](https://dashboard.internetcomputer.org/subnet/pzp6e-ekpqk-3c5x7-2h6so-njoeq-mt45d-h3h6c-q3mxf-vpeez-fez7a-iae), both controlled by the NNS root canister. The **ledger** is an [ICRC-1/ICRC-2](../../references/icrc-standards.md) compliant ledger that records all ckBTC balances and handles transfers. The **minter** manages the BTC side: it controls Bitcoin addresses, tracks UTXOs, triggers minting when deposits arrive, and signs and submits Bitcoin transactions when users withdraw.
54
51
55
-
The **ledger** is an [ICRC-1/ICRC-2](../../references/icrc-standards.md) compliant ledger. It records all ckBTC balances and handles transfers. The transfer fee is 0.0000001 ckBTC (10 satoshi), sent to the minter's fee subaccount.
56
-
57
-
The **minter** manages the BTC side: it controls Bitcoin addresses, tracks UTXOs, triggers minting when deposits arrive, and signs and submits Bitcoin transactions when users withdraw.
52
+
For canister IDs, minter parameters, and endpoint reference, see [ckBTC minter](../../references/protocol-canisters.md#ckbtc-minter) and [Chain-Key Token Canister IDs](../../references/chain-key-canister-ids.md#ckbtc).
58
53
59
54
### Converting BTC to ckBTC
60
55
61
56
1. The user calls `get_btc_address` on the minter to receive a deposit address (a P2WPKH address) tied to their principal.
62
57
2. The user sends bitcoin to that address on the Bitcoin network.
63
-
3. After 6 confirmations, the user calls `update_balance` on the minter.
64
-
4. The minter fetches UTXOs for the deposit address via `bitcoin_get_utxos` and checks each new UTXO with the Bitcoin checker canister. UTXOs that pass the check are minted as ckBTC into the user's ledger account (minus the 100-satoshi checker fee). UTXOs that fail the check are quarantined.
58
+
3. After 4 confirmations, the user calls `update_balance` on the minter.
59
+
4. The minter fetches UTXOs for the deposit address via `bitcoin_get_utxos` and checks each new UTXO with the Bitcoin checker canister. UTXOs that pass the check are minted as ckBTC into the user's ledger account (minus a KYT fee). UTXOs that fail the check are quarantined.
65
60
66
-
The 6-confirmation requirement protects against Bitcoin chain reorganizations.
61
+
The 4-confirmation requirement protects against Bitcoin chain reorganizations.
67
62
68
63
### Converting ckBTC to BTC
69
64
@@ -72,25 +67,17 @@ The recommended flow uses ICRC-2 approval:
72
67
1. The user calls `icrc2_approve` on the ckBTC ledger, authorizing the minter to withdraw the desired amount.
73
68
2. The user calls `retrieve_btc_with_approval` on the minter, specifying the amount and destination Bitcoin address.
74
69
3. The minter checks the destination address with the Bitcoin checker canister. If it passes, the minter burns the ckBTC from the user's account and queues a Bitcoin withdrawal.
75
-
4. The minter periodically batches pending requests: it selects UTXOs, builds a Bitcoin transaction, signs each input using threshold ECDSA, and submits via `bitcoin_send_transaction`.
76
-
77
-
Requests are batched to reduce Bitcoin miner fees: if at least 20 requests accumulate or the oldest request is 10 minutes old, the minter creates a single transaction serving up to 100 requests.
78
-
79
-
The minimum withdrawal amount is 0.0005 BTC (50,000 satoshi) to ensure the fee remains proportionally small.
80
-
81
-
### Minter fee
82
-
83
-
The minter fee for a withdrawal transaction is `146 × inputs + 4 × outputs + 26` satoshi. This formula covers the cost of threshold ECDSA signatures and transaction broadcasting. The fee is split among all outputs in a batch transaction.
84
-
85
-
### UTXO consolidation
70
+
4. The minter periodically batches pending requests, selects UTXOs, builds a Bitcoin transaction, signs each input using threshold ECDSA, and submits via `bitcoin_send_transaction`.
86
71
87
-
As deposits accumulate, the minter manages a growing set of UTXOs. Too many small UTXOs can make large withdrawals impossible (a Bitcoin transaction is limited to 100 KB). When the UTXO count exceeds 10,000, the minter periodically creates _consolidation transactions_ that merge the 1,000 smallest UTXOs into 2 new outputs, funded from the minter's fee account.
72
+
Requests are batched to reduce Bitcoin miner fees. For the minimum withdrawal amount, fee formula, and UTXO consolidation behavior, see [ckBTC minter](../../references/protocol-canisters.md#ckbtc-minter).
88
73
89
74
## Next steps
90
75
91
-
-[Bitcoin guide](../../guides/chain-fusion/bitcoin.md): build Bitcoin transactions from a canister
76
+
-[Bitcoin guide](../../guides/chain-fusion/bitcoin.md): build Bitcoin transactions from a canister, with code and development setup
92
77
-[Dogecoin integration](dogecoin.md): Bitcoin fork integration using the same architecture
93
78
-[Chain Fusion overview](index.md): integration patterns and supported chains
94
79
-[Chain-key cryptography](../chain-key-cryptography.md): threshold ECDSA and Schnorr signing
80
+
-[Protocol canisters reference](../../references/protocol-canisters.md#bitcoin-canisters): canister IDs, cycle costs, and API details
81
+
-[Chain-Key Token Canister IDs](../../references/chain-key-canister-ids.md#ckbtc): full ckBTC canister ID table including index and testnet
Copy file name to clipboardExpand all lines: docs/concepts/chain-fusion/ethereum.md
+2-4Lines changed: 2 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,7 +17,7 @@ This flow (query, sign, submit) lets canisters call any Ethereum smart contract,
17
17
18
18
## EVM RPC canister
19
19
20
-
The EVM RPC canister (`7hfb6-caaaa-aaaar-qadga-cai`) is a system-level canister that acts as a gateway between ICP canisters and Ethereum JSON-RPC APIs. It is controlled by the NNS, so its behavior cannot be changed by any single party.
20
+
The EVM RPC canister (`7hfb6-caaaa-aaaar-qadga-cai`) is a system-level canister that acts as a gateway between ICP canisters and Ethereum JSON-RPC APIs. It is controlled by the NNS, so its behavior cannot be changed by any single party. For supported chains, built-in providers, and cycle costs, see [EVM RPC canister](../../references/protocol-canisters.md#evm-rpc-canister).
21
21
22
22
### Multi-provider architecture
23
23
@@ -49,9 +49,7 @@ ckETH and ckERC20 tokens (such as ckUSDC and ckUSDT) are chain-key tokens backed
49
49
50
50
**Deposits.** Because ICP cannot observe Ethereum state directly (unlike Bitcoin, which uses a native adapter), ckETH uses a helper smart contract deployed on Ethereum. Users send ETH or ERC-20 assets to this helper contract, which emits an event. The ckETH minter periodically queries the event log via the EVM RPC canister to discover deposits and mints the corresponding chain-key tokens.
51
51
52
-
**Withdrawals.** The user approves the minter to burn their chain-key tokens (via ICRC-2), then calls the withdrawal endpoint. The minter burns the tokens, signs an Ethereum transaction using chain-key ECDSA, and submits it via the EVM RPC canister.
53
-
54
-
For a full description of chain-key token architecture, see [Chain-key tokens](chain-key-tokens.md).
52
+
For full minting, redemption, and security model details, see [Chain-key tokens](chain-key-tokens.md).
0 commit comments