diff --git a/docs/concepts/chain-fusion/bitcoin.md b/docs/concepts/chain-fusion/bitcoin.md index c861b367..9306ad26 100644 --- a/docs/concepts/chain-fusion/bitcoin.md +++ b/docs/concepts/chain-fusion/bitcoin.md @@ -15,6 +15,8 @@ The integration has two layers: Together, these two layers give a canister the ability to receive bitcoin, check its balance, construct transactions, sign them, and broadcast them to the Bitcoin network. +![Bitcoin integration architecture: a canister calls the Bitcoin canister through the ICP protocol stack, while the Bitcoin adapter connects to the Bitcoin peer-to-peer network](/concepts/chain-fusion/bitcoin-architecture.png) + ## Bitcoin canister API The Bitcoin canister exposes endpoints accessible directly by other canisters: @@ -28,6 +30,28 @@ The Bitcoin canister exposes endpoints accessible directly by other canisters: 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`. +```plantuml +participant "Your Canister" as Canister +participant "Bitcoin Canister" as BC +participant "Chain-Key Signing" as CKS + +Canister -> BC: bitcoin_get_utxos(address, filter) +BC --> Canister: utxos + +Canister -> BC: bitcoin_get_current_fee_percentiles +BC --> Canister: fee_percentiles + +note over Canister: select inputs, build transaction + +loop for each transaction input + Canister -> CKS: sign_with_ecdsa(tx_input) + CKS --> Canister: signature +end + +Canister -> BC: bitcoin_send_transaction(signed_tx) +BC --> Canister: ok +``` + For canister IDs, cycle costs, and the full interface specification, see [Bitcoin canisters](../../references/protocol-canisters.md#bitcoin-canisters). ## Bitcoin checker canister @@ -41,12 +65,16 @@ Two primary endpoints are available: Both endpoints return `Passed` or `Failed`. The canister itself is controlled by the NNS, so its SDN list can only be updated via a governance proposal. +![Bitcoin checker canister flow: the ckBTC minter calls the checker canister, which queries Bitcoin explorers and cross-references the OFAC SDN list before returning a pass or fail result](/concepts/chain-fusion/bitcoin-checker-flow.png) + ## Chain-key Bitcoin (ckBTC) 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. 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. +![ckBTC system architecture: the ckBTC minter handles BTC deposits and withdrawals, the ckBTC ledger records balances, the Bitcoin canister provides UTXO data, and the Bitcoin checker canister screens addresses against the OFAC list](/concepts/chain-fusion/ckbtc-architecture.png) + 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. 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). diff --git a/docs/concepts/chain-fusion/dogecoin.md b/docs/concepts/chain-fusion/dogecoin.md index 124cb389..95606538 100644 --- a/docs/concepts/chain-fusion/dogecoin.md +++ b/docs/concepts/chain-fusion/dogecoin.md @@ -11,6 +11,8 @@ The _Dogecoin adapter_ is a process that runs alongside the ICP replica on each Canister-controlled Dogecoin addresses are derived from chain-key ECDSA public keys, just as in the Bitcoin integration. Transactions are signed using the management canister's `sign_with_ecdsa` API and broadcast to the Dogecoin network through the adapter. +![Dogecoin integration architecture: a canister calls the Dogecoin canister through the ICP protocol stack, while the Dogecoin adapter connects to the Dogecoin peer-to-peer network](/concepts/chain-fusion/dogecoin-architecture.png) + ## Chain-key DOGE (ckDOGE) ckDOGE is the chain-key token representing Dogecoin on ICP, backed 1:1 by real DOGE held in a canister-controlled address. The minter-plus-ledger architecture is the same as [ckBTC](bitcoin.md#chain-key-bitcoin-ckbtc): users deposit DOGE to a minter-controlled address, the minter mints ckDOGE on the ledger, and withdrawals trigger an onchain Dogecoin transaction signed with threshold ECDSA. diff --git a/docs/concepts/chain-fusion/ethereum.md b/docs/concepts/chain-fusion/ethereum.md index 2f462b71..d0d118c1 100644 --- a/docs/concepts/chain-fusion/ethereum.md +++ b/docs/concepts/chain-fusion/ethereum.md @@ -19,6 +19,33 @@ This flow (query, sign, submit) lets canisters call any Ethereum smart contract, 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). +```plantuml +left to right direction + +package "Internet Computer" { + component "Your Canister" as UC + component "EVM RPC Canister" as EVM +} + +package "JSON-RPC Providers" { + component "Provider 1" as P1 + component "Provider 2" as P2 + component "Provider N" as PN +} + +package "Ethereum" { + component "Smart contracts" as SC +} + +UC <--> EVM +EVM --> P1 +EVM --> P2 +EVM --> PN +P1 --> SC +P2 --> SC +PN --> SC +``` + ### Multi-provider architecture ```plantuml diff --git a/docs/concepts/chain-fusion/exchange-rate-canister.md b/docs/concepts/chain-fusion/exchange-rate-canister.md index 3e1ff511..ef965906 100644 --- a/docs/concepts/chain-fusion/exchange-rate-canister.md +++ b/docs/concepts/chain-fusion/exchange-rate-canister.md @@ -33,6 +33,8 @@ Every request must include **1 billion cycles**. Unused cycles are refunded. At ## How rates are computed +![Exchange rate canister data flow: the XRC pulls daily forex rates from forex providers and real-time crypto rates from exchanges, then returns the median rate and metadata to the requesting canister](/concepts/chain-fusion/exchange-rate-canister-flow.png) + When a cryptocurrency rate is not cached, the XRC queries all supported exchanges using HTTPS outcalls to get the asset's price against USDT. It then takes the **median** of all received rates, making the result resistant to outliers. For a cryptocurrency/cryptocurrency pair like BTC/ICP, the XRC derives the rate from independent BTC/USDT and ICP/USDT rates using a cross-product approach before taking the median. For fiat currencies, the XRC downloads daily forex rates from forex data providers on a fixed schedule. USD/USDT is derived by taking the median of rates for several stablecoins against USDT, based on the assumption that at least half of the included stablecoins maintain their USD peg at any given time. diff --git a/docs/concepts/chain-fusion/solana.md b/docs/concepts/chain-fusion/solana.md index ca638be7..fe370ba5 100644 --- a/docs/concepts/chain-fusion/solana.md +++ b/docs/concepts/chain-fusion/solana.md @@ -13,6 +13,33 @@ Supported providers include [Alchemy](https://www.alchemy.com/), [Ankr](https:// Each request is forwarded to multiple providers. If providers return consistent results, that response is passed back to the calling canister. The NNS controls which providers are registered and how the canister behaves, so no single entity can alter its operation. +```plantuml +left to right direction + +package "Internet Computer" { + component "Your Canister" as UC + component "SOL RPC Canister" as SolRpc +} + +package "JSON-RPC Providers" { + component "Provider 1" as P1 + component "Provider 2" as P2 + component "Provider N" as PN +} + +package "Solana" { + component "Programs" as SC +} + +UC <--> SolRpc +SolRpc --> P1 +SolRpc --> P2 +SolRpc --> PN +P1 --> SC +P2 --> SC +PN --> SC +``` + ```plantuml participant "Your Canister" as Canister participant "SOL RPC Canister" as SolRpc diff --git a/public/concepts/chain-fusion/bitcoin-architecture.png b/public/concepts/chain-fusion/bitcoin-architecture.png new file mode 100644 index 00000000..5fbd0015 Binary files /dev/null and b/public/concepts/chain-fusion/bitcoin-architecture.png differ diff --git a/public/concepts/chain-fusion/bitcoin-checker-flow.png b/public/concepts/chain-fusion/bitcoin-checker-flow.png new file mode 100644 index 00000000..59223d16 Binary files /dev/null and b/public/concepts/chain-fusion/bitcoin-checker-flow.png differ diff --git a/public/concepts/chain-fusion/ckbtc-architecture.png b/public/concepts/chain-fusion/ckbtc-architecture.png new file mode 100644 index 00000000..e40ffe92 Binary files /dev/null and b/public/concepts/chain-fusion/ckbtc-architecture.png differ diff --git a/public/concepts/chain-fusion/dogecoin-architecture.png b/public/concepts/chain-fusion/dogecoin-architecture.png new file mode 100644 index 00000000..a0f4315b Binary files /dev/null and b/public/concepts/chain-fusion/dogecoin-architecture.png differ diff --git a/public/concepts/chain-fusion/exchange-rate-canister-flow.png b/public/concepts/chain-fusion/exchange-rate-canister-flow.png new file mode 100644 index 00000000..a3047f8d Binary files /dev/null and b/public/concepts/chain-fusion/exchange-rate-canister-flow.png differ