Skip to content

Commit 8bb5cec

Browse files
committed
fix(chain-fusion): align concept pages with guide/reference layers
Bitcoin concept (bitcoin.md): - Fix factual error: 6 confirmations -> 4 confirmations - Remove minter fee formula and UTXO consolidation sections (moved to protocol-canisters.md reference) - Remove inline operational parameters (KYT fee amount, min withdrawal, batch timing); link to reference instead - Add get_blockchain_info and bitcoin_get_block_headers to API section - Add cross-links to protocol-canisters.md and chain-key-canister-ids.md Ethereum concept (ethereum.md): - Remove duplicated Withdrawals paragraph (covered in chain-key-tokens.md) - Add link to EVM RPC canister reference Solana, Dogecoin, XRC, chain-key-tokens concepts: - Add cross-links to protocol-canisters.md sections and chain-key-canister-ids.md - Add Dogecoin guide link from dogecoin.md
1 parent d86f154 commit 8bb5cec

6 files changed

Lines changed: 27 additions & 34 deletions

File tree

docs/concepts/chain-fusion/bitcoin.md

Lines changed: 17 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -17,15 +17,19 @@ Together, these two layers give a canister the ability to receive bitcoin, check
1717

1818
## Bitcoin canister API
1919

20-
The Bitcoin canister exposes three main endpoints accessible through the management canister:
20+
The Bitcoin canister exposes endpoints accessible directly by other canisters:
2121

2222
- `bitcoin_get_balance`: returns the balance of any Bitcoin address.
2323
- `bitcoin_get_utxos`: returns the unspent transaction outputs (UTXOs) for a given address. This is the primary input when constructing a Bitcoin transaction.
2424
- `bitcoin_get_current_fee_percentiles`: returns recent fee rates so a canister can estimate an appropriate miner fee.
2525
- `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.
2628

2729
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`.
2830

31+
For canister IDs, cycle costs, and the full interface specification, see [Bitcoin canisters](../../references/protocol-canisters.md#bitcoin-canisters).
32+
2933
## Bitcoin checker canister
3034

3135
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
3943

4044
## Chain-key Bitcoin (ckBTC)
4145

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.
4747

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.
4949

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.
5451

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).
5853

5954
### Converting BTC to ckBTC
6055

6156
1. The user calls `get_btc_address` on the minter to receive a deposit address (a P2WPKH address) tied to their principal.
6257
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.
6560

66-
The 6-confirmation requirement protects against Bitcoin chain reorganizations.
61+
The 4-confirmation requirement protects against Bitcoin chain reorganizations.
6762

6863
### Converting ckBTC to BTC
6964

@@ -72,25 +67,17 @@ The recommended flow uses ICRC-2 approval:
7267
1. The user calls `icrc2_approve` on the ckBTC ledger, authorizing the minter to withdraw the desired amount.
7368
2. The user calls `retrieve_btc_with_approval` on the minter, specifying the amount and destination Bitcoin address.
7469
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`.
8671

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).
8873

8974
## Next steps
9075

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
9277
- [Dogecoin integration](dogecoin.md): Bitcoin fork integration using the same architecture
9378
- [Chain Fusion overview](index.md): integration patterns and supported chains
9479
- [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
9582

9683
<!-- Upstream: informed by Learn Hub articles "Bitcoin Integration", "Bitcoin Checker Canister", "Chain-Key Bitcoin" (migrated, source retired) -->

docs/concepts/chain-fusion/chain-key-tokens.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,5 +65,7 @@ The security of a chain-key token rests on two properties:
6565
- [Chain Fusion overview](index.md): the full landscape of ICP crosschain capabilities
6666
- [Chain-key tokens guide](../../guides/digital-assets/chain-key-tokens.md): how to integrate chain-key tokens into an application
6767
- [Chain-key cryptography](../chain-key-cryptography.md): the threshold signing that makes chain-key tokens possible
68+
- [Chain-Key Token Canister IDs](../../references/chain-key-canister-ids.md): minter, ledger, and index IDs for all chain-key tokens
69+
- [Protocol canisters reference](../../references/protocol-canisters.md): minter parameters and endpoints for ckBTC, ckETH, ckDOGE, and ckSOL
6870

6971
<!-- Upstream: informed by Learn Hub articles "Chain-Key Tokens" (migrated, source retired) -->

docs/concepts/chain-fusion/dogecoin.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,9 @@ ckDOGE is the chain-key token representing Dogecoin on ICP, backed 1:1 by real D
1919

2020
- [Bitcoin integration](bitcoin.md): detailed description of the shared adapter and canister architecture
2121
- [Dogecoin canister documentation](https://dfinity.github.io/dogecoin-canister/)
22+
- [Dogecoin guide](../../guides/chain-fusion/dogecoin.md): code examples and canister API
2223
- [Chain Fusion overview](index.md): integration patterns and supported chains
24+
- [Dogecoin canister reference](../../references/protocol-canisters.md#dogecoin-canister): API endpoints
25+
- [Chain-Key Token Canister IDs: ckDOGE](../../references/chain-key-canister-ids.md#ckdoge): ckDOGE minter and ledger IDs
2326

2427
<!-- Upstream: informed by Learn Hub articles "Dogecoin Integration" (migrated, source retired) -->

docs/concepts/chain-fusion/ethereum.md

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ This flow (query, sign, submit) lets canisters call any Ethereum smart contract,
1717

1818
## EVM RPC canister
1919

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).
2121

2222
### Multi-provider architecture
2323

@@ -49,9 +49,7 @@ ckETH and ckERC20 tokens (such as ckUSDC and ckUSDT) are chain-key tokens backed
4949

5050
**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.
5151

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).
5553

5654
## Next steps
5755

docs/concepts/chain-fusion/exchange-rate-canister.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ If the XRC receives largely inconsistent rates from exchanges, it returns an `Ex
5151

5252
- [Chain Fusion overview](index.md): integration patterns and supported chains
5353
- [HTTPS outcalls](../https-outcalls.md): how the XRC fetches external data
54+
- [XRC reference](../../references/protocol-canisters.md#exchange-rate-canister-xrc): canister ID, interface, and cycle costs
5455
- [XRC Candid interface](https://github.com/dfinity/exchange-rate-canister/blob/main/src/xrc/xrc.did)
5556

5657
<!-- Upstream: informed by Learn Hub articles "Exchange Rate Canister" (migrated, source retired) -->

docs/concepts/chain-fusion/solana.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,5 +27,7 @@ ckSOL is the chain-key token representing SOL on ICP. Like ckETH, it is backed 1
2727
- [Chain Fusion overview](index.md): integration patterns and supported chains
2828
- [Ethereum integration](ethereum.md): the EVM RPC canister for comparison
2929
- [Chain-key cryptography](../chain-key-cryptography.md): Ed25519 threshold Schnorr signing
30+
- [SOL RPC canister reference](../../references/protocol-canisters.md#sol-rpc-canister): canister ID and provider list
31+
- [Chain-Key Token Canister IDs: ckSOL](../../references/chain-key-canister-ids.md#cksol): ckSOL minter and ledger IDs
3032

3133
<!-- Upstream: informed by Learn Hub articles "SOL RPC Canister" (migrated, source retired) -->

0 commit comments

Comments
 (0)