From 35a620a582e756cd7e2adade76771be3e4e8621e Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Wed, 18 Mar 2026 14:02:39 +0100 Subject: [PATCH 1/4] docs: Chain Fusion concept page Explain how ICP connects to other blockchains without bridges or oracles. Covers chain-key signatures, integration patterns (direct, RPC canister, HTTPS outcalls), supported chains table, chain-key tokens, and example use cases. --- docs/concepts/chain-fusion.md | 121 ++++++++++++++++++++++++++++++---- 1 file changed, 109 insertions(+), 12 deletions(-) diff --git a/docs/concepts/chain-fusion.md b/docs/concepts/chain-fusion.md index 6c41fdae..7b704f66 100644 --- a/docs/concepts/chain-fusion.md +++ b/docs/concepts/chain-fusion.md @@ -3,20 +3,117 @@ title: "Chain Fusion" description: "How ICP connects to Bitcoin, Ethereum, Solana, and other blockchains natively" sidebar: order: 10 -icskills: [] +icskills: [ckbtc, evm-rpc] --- -TODO: Write content for this page. +Chain Fusion is ICP's approach to cross-chain interoperability. Instead of relying on bridges or oracles, canisters interact with other blockchains directly — they can read state, hold assets, and sign and submit transactions on Bitcoin, Ethereum, Solana, and dozens of other chains. All of this runs onchain with the same trust assumptions as the Internet Computer itself. - -Explain the Chain Fusion vision and architecture. Cover how chain-key signatures enable canisters to sign transactions for other chains, the three integration patterns (direct signing, RPC canister, HTTPS outcalls), supported chains (Bitcoin, Ethereum, Solana, Dogecoin), chain-key tokens (ckBTC, ckETH) as the tokenized bridge alternative, and the EVM RPC canister architecture. Emphasize: no bridges, no oracles, no external dependencies. +The foundation is [chain-key cryptography](chain-key-cryptography.md). Each canister can derive keys for external signature schemes (ECDSA and Schnorr) and request threshold signatures from the protocol. This means a canister can control a Bitcoin address, an Ethereum account, or a Solana wallet — without any single node ever holding the private key. - -- Portal: building-apps/chain-fusion/overview.mdx, supported-chains.mdx, evm-rpc/how-it-works.mdx -- Learn Hub: [Chain Fusion](https://learn.internetcomputer.org/hc/en-us/articles/34329023770260) +## Why Chain Fusion matters - -- guides/chain-fusion/bitcoin -- BTC integration guide -- guides/chain-fusion/ethereum -- ETH integration guide -- concepts/chain-key-cryptography -- underlying crypto -- guides/defi/chain-key-tokens -- ckBTC, ckETH +Most cross-chain solutions introduce a trusted intermediary: a bridge, a multisig, or an oracle network. If that intermediary is compromised, funds are at risk. ICP eliminates this layer entirely. + +A canister interacting with Bitcoin or Ethereum has no external dependency beyond the target chain itself. The signing happens inside the protocol through a threshold cryptographic ceremony distributed across subnet nodes. This gives developers several advantages: + +- **No bridges.** Canisters hold assets directly on external chains. There is no wrapped token that can depeg, no bridge contract that can be exploited. +- **No oracles.** Canisters can read external chain state themselves — either through a direct protocol integration (Bitcoin) or by querying RPC providers via [HTTPS outcalls](https-outcalls.md). +- **Full autonomy.** Canisters can schedule cross-chain actions using [timers](../guides/backends/timers.md), enabling use cases like automated trading, periodic liquidations, or cronjob services — all without external triggers. +- **Web2-like UX.** Because ICP has low-cost computation and a [reverse gas model](reverse-gas-model.md), users can interact with cross-chain dapps through a standard browser without installing a wallet. + +## How it works + +Chain Fusion combines three protocol-level capabilities: + +### 1. Chain-key signatures + +Canisters request threshold ECDSA or Schnorr signatures from the management canister. The protocol derives a unique key for each canister and signs messages without ever reconstructing the private key. This lets canisters control addresses on any blockchain that uses a supported signature scheme. + +Two schemes are available: + +| Scheme | Supported chains | +|--------|-----------------| +| Threshold ECDSA (`secp256k1`) | Bitcoin, Ethereum, all EVM chains, Filecoin, Cosmos | +| Threshold Schnorr (`bip340secp256k1`) | Bitcoin Taproot, Ordinals | +| Threshold Schnorr (`ed25519`) | Solana, TON, Polkadot, Cardano, NEAR, Stellar | + +See [Chain-key cryptography](chain-key-cryptography.md) for the full list of supported chains and the cryptographic details. + +### 2. Reading external chain state + +A canister needs to read the state of an external chain to verify events, check balances, or monitor smart contracts. ICP supports two models: + +- **Direct integration.** The protocol runs a native adapter that connects to the external chain's peer-to-peer network. Bitcoin uses this model — ICP nodes run a Bitcoin adapter that syncs blocks directly, so canisters can query UTXOs and submit transactions through the management canister's Bitcoin API without any intermediary. + +- **RPC integration.** For chains without a direct integration, canisters use [HTTPS outcalls](https-outcalls.md) to query RPC providers. The EVM RPC canister (`7hfb6-caaaa-aaaar-qadga-cai`) provides a typed Candid interface for Ethereum and EVM-compatible chains. It sends each request to at least three independent RPC providers and returns either a `Consistent` result (all providers agree) or an `Inconsistent` result that the caller can handle. Solana has a similar dedicated canister (SOL RPC). For other chains, canisters can make raw HTTPS outcalls to any JSON-RPC endpoint. + +### 3. Submitting transactions + +Once a canister has signed a transaction, it needs to submit it to the target chain. The submission path depends on the integration model: + +- **Bitcoin:** The signed transaction is submitted through the management canister's `bitcoin_send_transaction` API, which broadcasts it via the Bitcoin adapter. +- **Ethereum and EVM chains:** The signed transaction is submitted via the EVM RPC canister's `eth_sendRawTransaction` endpoint, which relays it to RPC providers. +- **Other chains:** The canister submits the transaction by making an HTTPS outcall to the chain's RPC endpoint. + +## Integration patterns + +The combination of signing, reading, and submitting creates three integration patterns that cover all supported chains: + +| Pattern | How state is read | Chains | Trust model | +|---------|------------------|--------|-------------| +| **Direct** | Protocol-level adapter (full node) | Bitcoin, Dogecoin | ICP subnet consensus only | +| **Dedicated RPC canister** | Typed canister queries multiple providers | Ethereum, EVM chains, Solana | ICP consensus + RPC provider agreement | +| **Raw HTTPS outcalls** | Canister makes HTTP requests to RPC endpoints | Any chain with an RPC API | ICP consensus + RPC provider trust | + +Direct integration provides the strongest trust guarantees — the only assumption is that a supermajority of subnet nodes are honest. RPC-based integration adds the assumption that at least one of the queried RPC providers returns correct data, which is mitigated by querying multiple independent providers and comparing results. + +## Chain-key tokens + +Chain-key tokens are digital twins of native assets from other blockchains (for example, ckBTC for Bitcoin and ckETH for Ethereum). Each token is backed 1:1 by the native asset, which is held in a canister-controlled address on the source chain. Minting and burning happen entirely onchain — no bridge, no custodian. + +These tokens implement the [ICRC-2](../guides/defi/token-ledgers.md) token standard, so they can be transferred and traded within the ICP ecosystem with the same speed and cost as any other ICP token. When a user wants to redeem the underlying asset, the minter canister signs and submits a withdrawal transaction on the source chain. + +For details on integrating with chain-key tokens, see the [Chain-key tokens guide](../guides/defi/chain-key-tokens.md). + +## Supported chains + +Any blockchain whose transactions use ECDSA (secp256k1), Schnorr (BIP340 over secp256k1), or Ed25519 signatures can be integrated with ICP. The following table lists chains with established integrations or community-built tooling: + +| Chain | Signature scheme | Integration method | Chain-key token | +|-------|-----------------|-------------------|-----------------| +| Bitcoin | ECDSA, Schnorr | Direct | ckBTC | +| Ethereum | ECDSA | EVM RPC canister | ckETH, ckERC20 | +| EVM chains (Arbitrum, Base, Optimism, etc.) | ECDSA | EVM RPC canister | — | +| Solana | Ed25519 | SOL RPC canister | — | +| Dogecoin | ECDSA | Direct | ckDOGE (upcoming) | +| Aptos | ECDSA, Ed25519 | HTTPS outcalls | — | +| Avalanche | ECDSA | HTTPS outcalls | — | +| Cardano | Ed25519 | HTTPS outcalls | — | +| Cosmos | ECDSA | HTTPS outcalls | — | +| NEAR | Ed25519 | HTTPS outcalls | — | +| Polkadot | ECDSA, Ed25519 | HTTPS outcalls | — | +| Stellar | Ed25519 | HTTPS outcalls | — | +| TON | Ed25519 | HTTPS outcalls | — | +| XRP | ECDSA, Ed25519 | HTTPS outcalls | — | + +This is not exhaustive. If a chain uses a supported signature scheme and has RPC providers accessible over IPv6, integration is possible. + +## Example use cases + +Chain Fusion enables application patterns that are difficult or impossible with bridge-based approaches: + +- **Trustless cronjob service.** A canister monitors an Ethereum DeFi contract via the EVM RPC canister and triggers loan liquidations or batch settlements automatically using timers — no Gelato or Chainlink Keepers needed. +- **Multichain wallet.** A single canister controls addresses on Bitcoin, Ethereum, and Solana simultaneously. Users interact through a web frontend served from ICP without installing chain-specific wallets. +- **Onchain frontend.** An immutable or DAO-governed frontend for an Ethereum smart contract, hosted on ICP as a certified asset. Users interact with the Ethereum contract through the ICP-hosted UI. +- **Cross-chain DeFi.** A lending protocol that accepts Bitcoin as collateral (held in a canister-controlled BTC address) and issues stablecoins as ICRC-2 tokens. +- **Decentralized oracle.** A canister fetches real-world data via HTTPS outcalls and posts it to a smart contract on another chain — replacing centralized oracle networks. + +## What's next + +- [Bitcoin integration](../guides/chain-fusion/bitcoin.md) — build with BTC on ICP +- [Ethereum integration](../guides/chain-fusion/ethereum.md) — interact with Ethereum and EVM chains +- [Chain-key tokens](../guides/defi/chain-key-tokens.md) — ckBTC, ckETH, and ckERC20 +- [Chain-key cryptography](chain-key-cryptography.md) — the threshold signing protocols behind Chain Fusion +- [HTTPS outcalls](https-outcalls.md) — make HTTP requests from canisters + + From 0ec3822d8b264356f9b96564df847c83b248bc3e Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Wed, 18 Mar 2026 14:59:48 +0100 Subject: [PATCH 2/4] docs: deduplicate supported chains, add building blocks section - Remove full supported-chains table from chain-key-cryptography (replaced with cross-link to chain-fusion#supported-chains) - Add "Building blocks" section to chain-fusion concept page listing Bitcoin API, EVM RPC, SOL RPC, chain-key tokens, and Chain Fusion Signer - Mention OISY Wallet as a production example of Chain Fusion Signer - Fix cross-reference text between the two concept pages - Record three decisions in decisions.md --- .docs-plan/decisions.md | 18 ++++++++++++++++++ docs/concepts/chain-fusion.md | 12 +++++++++++- docs/concepts/chain-key-cryptography.md | 25 +------------------------ 3 files changed, 30 insertions(+), 25 deletions(-) diff --git a/.docs-plan/decisions.md b/.docs-plan/decisions.md index 8608e17e..eaf93c7a 100644 --- a/.docs-plan/decisions.md +++ b/.docs-plan/decisions.md @@ -163,6 +163,24 @@ Record decisions that constrain future work — things an agent needs to know th **Rationale:** Keeps `git log` on `main` clean (one commit per page/feature). PR history is always available on GitHub. Auto-delete prevents stale `docs/` branches from accumulating. **Alternatives considered:** Merge commits (noisy history), rebase merge (preserves individual commits nobody needs) +## 2026-03-18: Supported chains table belongs in chain-fusion, not chain-key-cryptography + +**Context:** Both `concepts/chain-key-cryptography.md` and `concepts/chain-fusion.md` had a full supported-chains table with integration methods. This duplicated content and muddied the Diataxis separation — the crypto page should explain *how signing works*, the Chain Fusion page should explain *what you can integrate with*. +**Decision:** (1) Removed the full chains table from `chain-key-cryptography.md`, replaced with a one-liner cross-link to `chain-fusion.md#supported-chains`. (2) Kept the 3-row signature scheme table in `chain-key-cryptography.md` (maps schemes to algorithms — that's about the crypto). (3) The Chain Fusion page is now the single source of truth for the supported chains list. +**Rationale:** Each concept page should own one topic cleanly. The chain-key-cryptography page owns the signing protocols; Chain Fusion owns the integration story. + +## 2026-03-18: Chain Fusion Signer mentioned in concept page; dedicated guide deferred + +**Context:** The [chain-fusion-signer](https://github.com/dfinity/chain-fusion-signer) is a reusable signing canister used by OISY Wallet and others. It needed a home in the docs. +**Decision:** (1) Added a "Building blocks" section to `concepts/chain-fusion.md` listing the key infrastructure components (Bitcoin API, EVM RPC canister, SOL RPC canister, chain-key tokens, Chain Fusion Signer). OISY Wallet is mentioned as a production example. (2) A dedicated guide for using the Chain Fusion Signer will be filed as a GitHub issue for future work. +**Rationale:** The concept page is the natural map of the Chain Fusion ecosystem. A guide would require how-to content that doesn't exist in the current migration plan — better to propose it as a separate page. + +## 2026-03-18: Consider moving wallet-integration from authentication to DeFi + +**Context:** `guides/authentication/wallet-integration.md` covers ICRC signer-standard wallets (OISY, Plug, NFID) for transaction approval. This is closer to DeFi/token workflows than to authentication (which is about identity/login). +**Decision:** Filed as a GitHub issue for discussion. Not changing the structure in this PR — it affects sidebar config and multiple cross-links. The wallet-integration skill already distinguishes between II (auth) and wallet signers (transaction approval), supporting the case for a move. +**Rationale:** Structural moves should be deliberate and reviewed, not done as a side-effect of a content PR. + ## 2026-03-17: Merge binding-generation page into Candid interface guide **Context:** The planned `guides/canister-calls/binding-generation.md` had significant overlap with the existing Candid interface guide, which already covered `.did` generation and JS binding usage. The two dedicated binding tools are `@icp-sdk/bindgen` (JS/TS) and `ic-cdk-bindgen` (Rust) — `didc bind` should not be advertised for binding generation. diff --git a/docs/concepts/chain-fusion.md b/docs/concepts/chain-fusion.md index 7b704f66..66206f1d 100644 --- a/docs/concepts/chain-fusion.md +++ b/docs/concepts/chain-fusion.md @@ -37,7 +37,7 @@ Two schemes are available: | Threshold Schnorr (`bip340secp256k1`) | Bitcoin Taproot, Ordinals | | Threshold Schnorr (`ed25519`) | Solana, TON, Polkadot, Cardano, NEAR, Stellar | -See [Chain-key cryptography](chain-key-cryptography.md) for the full list of supported chains and the cryptographic details. +See [Chain-key cryptography](chain-key-cryptography.md) for details on the threshold signing protocols, key derivation, and deployed keys. ### 2. Reading external chain state @@ -98,6 +98,16 @@ Any blockchain whose transactions use ECDSA (secp256k1), Schnorr (BIP340 over se This is not exhaustive. If a chain uses a supported signature scheme and has RPC providers accessible over IPv6, integration is possible. +## Building blocks + +Several reusable canisters and protocol APIs are available for building Chain Fusion applications: + +- **Bitcoin API.** The management canister exposes `bitcoin_get_utxos`, `bitcoin_get_balance`, and `bitcoin_send_transaction` — a direct protocol-level integration with no intermediary. See [Bitcoin integration](../guides/chain-fusion/bitcoin.md). +- **EVM RPC canister** (`7hfb6-caaaa-aaaar-qadga-cai`). A canister providing a typed Candid interface for Ethereum and EVM-compatible chains. Queries multiple RPC providers and returns consensus results. See [Ethereum integration](../guides/chain-fusion/ethereum.md). +- **SOL RPC canister.** A similar canister for Solana, providing typed access to Solana's JSON-RPC API. See [Solana integration](../guides/chain-fusion/solana.md). +- **Chain-key tokens.** Minter and ledger canisters that implement ckBTC, ckETH, and ckERC20 — trustless 1:1 representations of external assets on ICP. See [Chain-key tokens](../guides/defi/chain-key-tokens.md). +- **Chain Fusion Signer.** A reusable canister that exposes threshold signature APIs directly to web apps and CLI users, with cycle payments via ICRC-2 approval. [OISY Wallet](https://oisy.com) is a prominent production example — a multichain wallet built on ICP that uses the Chain Fusion Signer to manage keys for Bitcoin, Ethereum, and other chains. See the [chain-fusion-signer repository](https://github.com/dfinity/chain-fusion-signer). + ## Example use cases Chain Fusion enables application patterns that are difficult or impossible with bridge-based approaches: diff --git a/docs/concepts/chain-key-cryptography.md b/docs/concepts/chain-key-cryptography.md index 9851d7f2..02b1c9f2 100644 --- a/docs/concepts/chain-key-cryptography.md +++ b/docs/concepts/chain-key-cryptography.md @@ -88,30 +88,7 @@ For signing costs, see [Cycles costs](../reference/cycles-costs.md). ## Supported chains -Any blockchain whose transaction authentication uses ECDSA (secp256k1) or Schnorr signatures (BIP340 over secp256k1, or Ed25519) can be integrated with ICP through chain-key signatures. The following table lists a selection of supported chains: - -| Chain | Signature scheme | Integration method | -|-------|-----------------|-------------------| -| Bitcoin | ECDSA, Schnorr (Taproot) | Direct | -| Ethereum | ECDSA | EVM RPC canister | -| EVM chains (Arbitrum, Base, Optimism, etc.) | ECDSA | EVM RPC canister | -| Solana | Ed25519 | SOL RPC canister | -| Dogecoin | ECDSA | Direct | -| Aptos | ECDSA, Ed25519 | HTTPS outcalls | -| Avalanche | ECDSA | HTTPS outcalls | -| Cardano | Ed25519 | HTTPS outcalls | -| Cosmos | ECDSA | HTTPS outcalls | -| Hedera | ECDSA, Ed25519 | HTTPS outcalls | -| NEAR | Ed25519 | HTTPS outcalls | -| Polkadot | ECDSA, Ed25519 | HTTPS outcalls | -| Stacks | ECDSA | HTTPS outcalls | -| Stellar | Ed25519 | HTTPS outcalls | -| Sui | ECDSA, Ed25519 | HTTPS outcalls | -| TON | Ed25519 | HTTPS outcalls | -| TRON | ECDSA | HTTPS outcalls | -| XRP | ECDSA, Ed25519 | HTTPS outcalls | - -This is not exhaustive. If a chain uses a supported signature scheme and has RPC providers accessible over IPv6, integration is possible. For chain-specific implementation details, see the Bitcoin, Ethereum, and other guides under [Chain Fusion](../guides/chain-fusion/bitcoin.md). +Any blockchain whose transaction authentication uses ECDSA (secp256k1) or Schnorr signatures (BIP340 over secp256k1, or Ed25519) can be integrated with ICP through chain-key signatures. For the full list of supported chains with integration methods and chain-key tokens, see [Chain Fusion — Supported chains](chain-fusion.md#supported-chains). ## Chain evolution From a33d6ccff5bf6b3f964f36e60d1da2b641a53e6c Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Wed, 18 Mar 2026 15:08:24 +0100 Subject: [PATCH 3/4] docs: remove redundant decisions (covered by issues #24, #25) --- .docs-plan/decisions.md | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/.docs-plan/decisions.md b/.docs-plan/decisions.md index eaf93c7a..8608e17e 100644 --- a/.docs-plan/decisions.md +++ b/.docs-plan/decisions.md @@ -163,24 +163,6 @@ Record decisions that constrain future work — things an agent needs to know th **Rationale:** Keeps `git log` on `main` clean (one commit per page/feature). PR history is always available on GitHub. Auto-delete prevents stale `docs/` branches from accumulating. **Alternatives considered:** Merge commits (noisy history), rebase merge (preserves individual commits nobody needs) -## 2026-03-18: Supported chains table belongs in chain-fusion, not chain-key-cryptography - -**Context:** Both `concepts/chain-key-cryptography.md` and `concepts/chain-fusion.md` had a full supported-chains table with integration methods. This duplicated content and muddied the Diataxis separation — the crypto page should explain *how signing works*, the Chain Fusion page should explain *what you can integrate with*. -**Decision:** (1) Removed the full chains table from `chain-key-cryptography.md`, replaced with a one-liner cross-link to `chain-fusion.md#supported-chains`. (2) Kept the 3-row signature scheme table in `chain-key-cryptography.md` (maps schemes to algorithms — that's about the crypto). (3) The Chain Fusion page is now the single source of truth for the supported chains list. -**Rationale:** Each concept page should own one topic cleanly. The chain-key-cryptography page owns the signing protocols; Chain Fusion owns the integration story. - -## 2026-03-18: Chain Fusion Signer mentioned in concept page; dedicated guide deferred - -**Context:** The [chain-fusion-signer](https://github.com/dfinity/chain-fusion-signer) is a reusable signing canister used by OISY Wallet and others. It needed a home in the docs. -**Decision:** (1) Added a "Building blocks" section to `concepts/chain-fusion.md` listing the key infrastructure components (Bitcoin API, EVM RPC canister, SOL RPC canister, chain-key tokens, Chain Fusion Signer). OISY Wallet is mentioned as a production example. (2) A dedicated guide for using the Chain Fusion Signer will be filed as a GitHub issue for future work. -**Rationale:** The concept page is the natural map of the Chain Fusion ecosystem. A guide would require how-to content that doesn't exist in the current migration plan — better to propose it as a separate page. - -## 2026-03-18: Consider moving wallet-integration from authentication to DeFi - -**Context:** `guides/authentication/wallet-integration.md` covers ICRC signer-standard wallets (OISY, Plug, NFID) for transaction approval. This is closer to DeFi/token workflows than to authentication (which is about identity/login). -**Decision:** Filed as a GitHub issue for discussion. Not changing the structure in this PR — it affects sidebar config and multiple cross-links. The wallet-integration skill already distinguishes between II (auth) and wallet signers (transaction approval), supporting the case for a move. -**Rationale:** Structural moves should be deliberate and reviewed, not done as a side-effect of a content PR. - ## 2026-03-17: Merge binding-generation page into Candid interface guide **Context:** The planned `guides/canister-calls/binding-generation.md` had significant overlap with the existing Candid interface guide, which already covered `.did` generation and JS binding usage. The two dedicated binding tools are `@icp-sdk/bindgen` (JS/TS) and `ic-cdk-bindgen` (Rust) — `didc bind` should not be advertised for binding generation. From 7212d5c25607bd84090b26ded74201cbd7703a52 Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Wed, 18 Mar 2026 15:13:09 +0100 Subject: [PATCH 4/4] docs: update ckDOGE and ckSOL status in supported chains table --- docs/concepts/chain-fusion.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/concepts/chain-fusion.md b/docs/concepts/chain-fusion.md index 66206f1d..92947315 100644 --- a/docs/concepts/chain-fusion.md +++ b/docs/concepts/chain-fusion.md @@ -84,8 +84,8 @@ Any blockchain whose transactions use ECDSA (secp256k1), Schnorr (BIP340 over se | Bitcoin | ECDSA, Schnorr | Direct | ckBTC | | Ethereum | ECDSA | EVM RPC canister | ckETH, ckERC20 | | EVM chains (Arbitrum, Base, Optimism, etc.) | ECDSA | EVM RPC canister | — | -| Solana | Ed25519 | SOL RPC canister | — | -| Dogecoin | ECDSA | Direct | ckDOGE (upcoming) | +| Solana | Ed25519 | SOL RPC canister | ckSOL | +| Dogecoin | ECDSA | Direct | ckDOGE | | Aptos | ECDSA, Ed25519 | HTTPS outcalls | — | | Avalanche | ECDSA | HTTPS outcalls | — | | Cardano | Ed25519 | HTTPS outcalls | — |