Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions docs/concepts/chain-fusion/bitcoin.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand All @@ -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).
Expand Down
2 changes: 2 additions & 0 deletions docs/concepts/chain-fusion/dogecoin.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
27 changes: 27 additions & 0 deletions docs/concepts/chain-fusion/ethereum.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions docs/concepts/chain-fusion/exchange-rate-canister.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
27 changes: 27 additions & 0 deletions docs/concepts/chain-fusion/solana.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading