docs: Chain Fusion deep dives by marc0olo · Pull Request #213 · dfinity/developer-docs

marc0olo · 2026-05-06T15:12:35Z

Summary

Moves docs/concepts/chain-fusion.md → docs/concepts/chain-fusion/index.md (unchanged content, updated relative links)
Adds 6 new conceptual sub-pages under docs/concepts/chain-fusion/:
- bitcoin.md — Bitcoin adapter, Bitcoin canister API, Bitcoin checker canister (SDN list), ckBTC architecture and flows
- ethereum.md — HTTPS outcalls + chain-key ECDSA integration, EVM RPC canister architecture, ckETH/ckERC20
- solana.md — SOL RPC canister, Ed25519 threshold signing, ckSOL
- dogecoin.md — Dogecoin adapter + canister (Bitcoin fork, same architecture)
- exchange-rate-canister.md — XRC on uzr34, request/response format, cycle costs, median rate logic
- chain-key-tokens.md — Architecture (minter/ledger/index/archive), minting flows, redemption flows, deployed tokens table
Deletes all 10 staging files from .migration/learn-hub/how-does-icp-work/chain-fusion/
Updates cross-links in chain-key-cryptography.md, concepts/index.md, choose-your-path.md, and the four chain-fusion guide pages

Sync recommendation

informed by learn hub staging files — chain-fusion section

Move docs/concepts/chain-fusion.md → docs/concepts/chain-fusion/index.md and add six new sub-pages covering Bitcoin, Ethereum, Solana, Dogecoin, the Exchange Rate Canister, and chain-key tokens in depth. All 10 staging files under .migration/learn-hub/.../chain-fusion/ consumed and deleted. Cross-links updated in chain-key-cryptography.md, concepts/index.md, choose-your-path.md, and the four chain-fusion guide pages.

marc0olo · 2026-05-06T15:54:29Z

Review notes

Structure, page organisation, and internal links all look good. One issue needs to be fixed before merge:

Em-dashes (banned per CLAUDE.md, pervasive): Multiple new files use em-dashes in body text and as bullet/list description separators. Affected files and examples:

bitcoin.md: body text ("Bitcoin transactions — all without bridges...") and API bullet descriptions (`bitcoin_get_balance` — returns...)
ethereum.md: body text and bullet descriptions (lines 16, 28–29, 37–42, 48)
chain-key-tokens.md: body text and numbered list descriptions (lines 6, 18–21)
exchange-rate-canister.md: body text (lines 24, 46)

CLAUDE.md bans em-dashes in all content: body text, bullet descriptions, and link label text. Replace with colons, commas, or parentheses throughout.

No other issues: .md links to .mdx files resolve correctly via Astro, inbound links from guide pages and concept pages updated correctly,  comment present on all new files.

marc0olo · 2026-05-06T16:14:33Z

Review feedback

1. Em-dashes (banned project-wide)

26 instances of — across 4 files. Em-dashes are banned in all prose per the project rules; replace each with :, ,, ;, or (...) depending on context.

docs/concepts/chain-fusion/bitcoin.md (8 instances — lines 6, 12, 22, 23, 24, 25, 35, 36):

Line 6: transactions — all without → transactions, all without
Line 12: Bitcoin canister — a canister running → Bitcoin canister (a canister running...)
Lines 22–25: API bullet descriptions ( — returns …, — broadcasts …) → use : (bitcoin_get_balance: returns …)
Lines 35–36: checker bullet descriptions ( — checks …) → use :

docs/concepts/chain-fusion/ethereum.md (10 instances — lines 16, 28, 29, 37, 38, 39, 40, 41, 42, 48):

Line 16: This flow — query, sign, submit — lets → This flow (query, sign, submit) lets
Lines 28–29: consistency labels ( — all queried providers …, — providers returned …) → use :
Lines 37–42: API method bullets ( — block data, — transaction data, etc.) → use :
Line 48: as ckBTC — a minter canister → as ckBTC (a minter canister...)

docs/concepts/chain-fusion/chain-key-tokens.md (6 instances — lines 6, 12, 18, 19, 20, 21):

Line 6: underlying asset — held in a canister-controlled address … — and all minting → underlying asset (held in a canister-controlled address on the origin chain), and all minting
Line 12: chain-key key — an address no single → chain-key key, an address no single
Lines 18–21: numbered architecture items ( — manages …, — an ICRC-1/ICRC-2 …, etc.) → use :

docs/concepts/chain-fusion/exchange-rate-canister.md (2 instances — lines 24, 46):

Line 24: fiat currency — for example → fiat currency, for example
Line 46: against USDT — based on → against USDT, based on

2. "on-chain" should be "onchain" (no hyphen)

Two instances:

docs/concepts/chain-fusion/exchange-rate-canister.md line 6: on-chain oracle → onchain oracle
docs/concepts/chain-fusion/index.md line 126: on-chain oracle for asset prices → onchain oracle for asset prices

"Onchain" (no hyphen) is the established convention across this site.

3. Verify fiduciary subnet ID in `bitcoin.md`

bitcoin.md line 48 uses:

pzp6e-ekpqk-3c5x7-2h6so-njoeq-mt45d-h3h6c-q3mxf-vpeq5-fk5o7-yae

docs/guides/canister-management/subnet-selection.md uses:

pzp6e-ekpqk-3c5x7-2h6so-njoeq-mt45d-h3h6c-q3mxf-vpeez-fez7a-iae

The tail groups differ (vpeq5-fk5o7-yae vs vpeez-fez7a-iae). Please confirm the correct value against the dashboard link in the file and update whichever copy is wrong.

marc0olo · 2026-05-06T16:18:21Z

Content accuracy follow-up

Two content accuracy issues to address alongside the style fixes:

1. `bitcoin.md` — batching timeout value needs verification

Line ~57 states: "if at least 20 requests accumulate or the oldest request is 10 minutes old, the minter creates a single transaction."

The source material is internally inconsistent: max_time_in_queue_nanos is described as 5 minutes in one place, while the submission logic description references 10 minutes in another. Please verify the correct value against the current ckBTC minter source before merging and update the page accordingly.

2. `exchange-rate-canister.md` — `decimals` field missing from response description

The response description lists the number of queried sources, number of received sources, standard deviation, and forex timestamp, but omits the decimals field. This field is required to correctly interpret the returned rate: the rate is a scaled integer, and without decimals, a developer cannot convert it to a human-readable price. Please add decimals to the response description.

…mals field - Replace all em-dashes across bitcoin.md, ethereum.md, chain-key-tokens.md, exchange-rate-canister.md, and index.md - Fix fiduciary subnet ID in bitcoin.md (vpeez-fez7a-iae is correct) - Fix on-chain -> onchain in exchange-rate-canister.md and index.md - Add decimals field to exchange-rate-canister.md response description

marc0olo · 2026-05-06T16:43:08Z

Feedback addressed:

Replaced all 26 em-dashes across bitcoin.md, ethereum.md, chain-key-tokens.md, exchange-rate-canister.md, and chain-fusion/index.md
Fixed fiduciary subnet ID in bitcoin.md: vpeq5-fk5o7-yae → vpeez-fez7a-iae (verified against docs/guides/canister-management/subnet-selection.md and docs/references/subnet-types.md)
Fixed on-chain → onchain in exchange-rate-canister.md line 6 and index.md line 126
Added decimals field to the response description in exchange-rate-canister.md (required to convert the scaled integer to a human-readable price)
Batching timeout (10 minutes) verified as correct against the portal ckBTC reference source (max_time_in_queue_nanos description), no change needed

…ers pages - Fix AccountIdentifier em-dash in token-ledgers.md - Revert chain-fusion/ subdirectory links to chain-fusion.md (flat page on main) until PR #213 merges; affects token-ledgers.md and concepts/index.md - Remove broken link to protocol/execution.md#deterministic-time-slicing in cycles.md until PR #209 merges

… pages Replace "chain-key tokens" with "chain-key digital assets" throughout prose. Replace "other blockchains" with "other chains/networks". Replace "cross-chain" with "crosschain". Replace "wrapped tokens" with "wrapped assets". Replace "blockchain address" with "network address". Fix "DAO-governed" to "community-governed". Update section headings and table column names to match.

marc0olo

please check existing comments and apply this on other pages in this PR.

… feedback - Revert title and all prose in chain-key-tokens.md from "chain-key digital assets" back to "chain-key tokens" (technical term must be preserved) - Use "assets" instead of "digital assets" where usage was excessive - Table headings: "Deployed assets" and "Asset" column (not "digital assets") - Apply same revert across ethereum.md, solana.md, dogecoin.md, index.md, chain-key-cryptography.md - bitcoin.md: add ICRC-1/ICRC-2 link on ledger description and remove "digital asset" qualifier

marc0olo · 2026-05-07T12:08:21Z

Feedback addressed:

Reverted chain-key-tokens.md title back to "Chain-Key Tokens" (technical term preserved per inline comment on line 2)
Replaced all "chain-key digital assets" with "chain-key tokens" throughout chain-key-tokens.md, ethereum.md, solana.md, dogecoin.md, index.md, and chain-key-cryptography.md (applied to all pages in this PR per review note)
Changed table headings to "Deployed assets" and "Asset" column (not "digital assets")
Reduced excessive "digital assets" usage: "instructs the ledger to mint tokens", "ICRC-1/ICRC-2 compliant ledger" (not "digital asset ledger"), "asset governance", etc.
bitcoin.md line 55: added ICRC-1/ICRC-2 link on the ledger description; removed "digital asset" qualifier
Also fixed token-ledgers.md on branch docs/concepts-tokens-ledgers (PR docs: Batch 8 — tokens, ledgers, and cycles concepts #215): "chain-key digital assets like ckBTC" → "chain-key tokens like ckBTC"

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

marc0olo · 2026-05-08T08:12:50Z

Content/reference alignment applied based on three-layer audit (concepts, guides, references):

Bitcoin concept (bitcoin.md):

Fixed factual error: "6 confirmations" → "4 confirmations" (guide and protocol-canisters.md both say 4)
Added get_blockchain_info and bitcoin_get_block_headers to API section (were missing)
Removed ### Minter fee and ### UTXO consolidation subsections — moved to references/protocol-canisters.md (PR docs(references): expand protocol-canisters with Bitcoin cycle costs, SOL RPC, and Dogecoin canister #221)
Removed inline operational parameters (KYT fee amount, min withdrawal, batch timing) — replaced with link to reference
Added cross-links to protocol-canisters.md#bitcoin-canisters, protocol-canisters.md#ckbtc-minter, and chain-key-canister-ids.md#ckbtc

Ethereum concept (ethereum.md):

Removed duplicated Withdrawals paragraph (same content already in chain-key-tokens.md)
Added link to EVM RPC canister reference

Solana, Dogecoin, XRC, chain-key-tokens:

Added cross-links to protocol-canisters.md sections and chain-key-canister-ids.md in Next steps sections

Reference additions (separate PR #221):

Bitcoin canister cycle costs table (from guide — authoritative source)
get_blockchain_info added to key endpoints
SOL RPC canister section (new)
Dogecoin canister section (new, ID pending repo lookup)
ckBTC minter fee formula + UTXO consolidation (needs DeFi team verification — flagged with HTML comment)

… SOL RPC, and Dogecoin canister - Add get_blockchain_info to Bitcoin canister key endpoints - Add cycle costs table for all Bitcoin canister endpoints (from Bitcoin guide as authoritative source) - Add Dogecoin canister section with API endpoints (ID pending repo lookup) - Add withdrawal fee formula and UTXO consolidation info to ckBTC minter section (needs DeFi team verification) - Add SOL RPC canister section with canister ID, providers, and guide link - Add SOL RPC to quick reference table

Move plantuml diagrams from the Bitcoin guide to bitcoin.md (concept page), which is the correct layer per Diataxis: architecture diagrams belong in concept pages. The guide retains cross-reference links to the diagrams.

…fix EVM RPC link chain-key-tokens.md still had the 6 confirmations factual error that was fixed in bitcoin.md. The EVM RPC canister inline link text was also misleading (pointed to the Ethereum concept page, not the canister reference).

…t pages Move EVM RPC multi-provider diagram (ethereum), ckDOGE deposit/withdrawal diagrams (dogecoin), and SOL RPC + ckSOL deposit/withdrawal diagrams (solana) from their guide files to the corresponding concept pages. Guides now carry cross-reference links back to the concept page diagrams.

… reference layers index.md: - Replace 3 instances of "management canister" with "Bitcoin canister" for Bitcoin API - Add ICRC-2 section anchor to ledgers.md link ethereum.md: - Add cross-link to chain-key-canister-ids.md#cketh in Next steps exchange-rate-canister.md: - Remove cycle cost table (duplicated in protocol-canisters.md reference) - Replace with single-sentence summary and link to reference guides/bitcoin.mdx: - Fix em-dash in withdrawal prose (→ colon) - Replace banned learn.internetcomputer.org link with internal concept page link guides/dogecoin.md: - Fix "upcoming ckDOGE" → "ckDOGE" (mainnet live) - Standardize koinus → koinu (correct Dogecoin unit name) guides/ethereum.mdx: - Fix "--" range notation in prose (→ "to") guides/solana.mdx: - Add missing Chainstack provider to provider list - Fix "Public Node" → "PublicNode" (correct branding)

## Summary - Moves `docs/concepts/chain-fusion.md` → `docs/concepts/chain-fusion/index.md` (unchanged content, updated relative links) - Adds 6 new conceptual sub-pages under `docs/concepts/chain-fusion/`: - `bitcoin.md` — Bitcoin adapter, Bitcoin canister API, Bitcoin checker canister (SDN list), ckBTC architecture and flows - `ethereum.md` — HTTPS outcalls + chain-key ECDSA integration, EVM RPC canister architecture, ckETH/ckERC20 - `solana.md` — SOL RPC canister, Ed25519 threshold signing, ckSOL - `dogecoin.md` — Dogecoin adapter + canister (Bitcoin fork, same architecture) - `exchange-rate-canister.md` — XRC on uzr34, request/response format, cycle costs, median rate logic - `chain-key-tokens.md` — Architecture (minter/ledger/index/archive), minting flows, redemption flows, deployed tokens table - Deletes all 10 staging files from `.migration/learn-hub/how-does-icp-work/chain-fusion/` - Updates cross-links in `chain-key-cryptography.md`, `concepts/index.md`, `choose-your-path.md`, and the four chain-fusion guide pages ## Sync recommendation `informed by learn hub staging files — chain-fusion section`

…ers pages - Fix AccountIdentifier em-dash in token-ledgers.md - Revert chain-fusion/ subdirectory links to chain-fusion.md (flat page on main) until PR #213 merges; affects token-ledgers.md and concepts/index.md - Remove broken link to protocol/execution.md#deterministic-time-slicing in cycles.md until PR #209 merges

…grams (#229) Closes #223. ## Summary Adds all images and diagrams that were not carried over when PR #213 migrated the chain fusion concept pages. Every image was individually evaluated; three were skipped (see below). ### Raster images added (sourced from Learn Hub) - **`bitcoin.md`**: full-stack integration architecture (adapter + protocol layers + Bitcoin canister); ckBTC system architecture (minter, ledger, Bitcoin canister, checker canister with labeled data flows); Bitcoin checker canister OFAC screening flow - **`dogecoin.md`**: Dogecoin adapter + canister + protocol-stack architecture diagram - **`exchange-rate-canister.md`**: XRC data-flow diagram (forex providers + exchanges → XRC → requesting canister) ### PlantUML diagrams added (source-controlled, new) - **`bitcoin.md`**: Bitcoin canister API spending-flow sequence (`bitcoin_get_utxos` → `sign_with_ecdsa` per input → `bitcoin_send_transaction`) - **`ethereum.md`**: EVM RPC component architecture (Internet Computer | JSON-RPC Providers | Ethereum) — recreated instead of using the Learn Hub raster, which had "Web 2.0" as a zone label (banned term) - **`solana.md`**: SOL RPC component architecture (Internet Computer | JSON-RPC Providers | Solana) — same reason; also complements the existing call-flow sequence diagrams already in this file ### Skipped - **Ethereum marketing render** (`34575033443348`): promotional 3D rendering, not a technical diagram; inconsistent with the clean diagram style used elsewhere - **ckBTC retrieval sequence** (`44598026440340`): the flow it depicts is already expressed in the existing PlantUML in `bitcoin.md` - **SNS supply-demand chart** (`34146812547476`): generic economics textbook diagram with no ICP-specific content ## Sync recommendation `informed by Learn Hub articles "Bitcoin Integration", "Bitcoin Checker Canister", "Chain-Key Bitcoin", "Dogecoin Integration", "Exchange Rate Canister", "EVM RPC Canister", "SOL RPC Canister" (migrated, source retired)`

## Summary - Moves `docs/concepts/chain-fusion.md` → `docs/concepts/chain-fusion/index.md` (unchanged content, updated relative links) - Adds 6 new conceptual sub-pages under `docs/concepts/chain-fusion/`: - `bitcoin.md` — Bitcoin adapter, Bitcoin canister API, Bitcoin checker canister (SDN list), ckBTC architecture and flows - `ethereum.md` — HTTPS outcalls + chain-key ECDSA integration, EVM RPC canister architecture, ckETH/ckERC20 - `solana.md` — SOL RPC canister, Ed25519 threshold signing, ckSOL - `dogecoin.md` — Dogecoin adapter + canister (Bitcoin fork, same architecture) - `exchange-rate-canister.md` — XRC on uzr34, request/response format, cycle costs, median rate logic - `chain-key-tokens.md` — Architecture (minter/ledger/index/archive), minting flows, redemption flows, deployed tokens table - Deletes all 10 staging files from `.migration/learn-hub/how-does-icp-work/chain-fusion/` - Updates cross-links in `chain-key-cryptography.md`, `concepts/index.md`, `choose-your-path.md`, and the four chain-fusion guide pages ## Sync recommendation `informed by learn hub staging files — chain-fusion section`

…grams (#229) Closes #223. ## Summary Adds all images and diagrams that were not carried over when PR #213 migrated the chain fusion concept pages. Every image was individually evaluated; three were skipped (see below). ### Raster images added (sourced from Learn Hub) - **`bitcoin.md`**: full-stack integration architecture (adapter + protocol layers + Bitcoin canister); ckBTC system architecture (minter, ledger, Bitcoin canister, checker canister with labeled data flows); Bitcoin checker canister OFAC screening flow - **`dogecoin.md`**: Dogecoin adapter + canister + protocol-stack architecture diagram - **`exchange-rate-canister.md`**: XRC data-flow diagram (forex providers + exchanges → XRC → requesting canister) ### PlantUML diagrams added (source-controlled, new) - **`bitcoin.md`**: Bitcoin canister API spending-flow sequence (`bitcoin_get_utxos` → `sign_with_ecdsa` per input → `bitcoin_send_transaction`) - **`ethereum.md`**: EVM RPC component architecture (Internet Computer | JSON-RPC Providers | Ethereum) — recreated instead of using the Learn Hub raster, which had "Web 2.0" as a zone label (banned term) - **`solana.md`**: SOL RPC component architecture (Internet Computer | JSON-RPC Providers | Solana) — same reason; also complements the existing call-flow sequence diagrams already in this file ### Skipped - **Ethereum marketing render** (`34575033443348`): promotional 3D rendering, not a technical diagram; inconsistent with the clean diagram style used elsewhere - **ckBTC retrieval sequence** (`44598026440340`): the flow it depicts is already expressed in the existing PlantUML in `bitcoin.md` - **SNS supply-demand chart** (`34146812547476`): generic economics textbook diagram with no ICP-specific content ## Sync recommendation `informed by Learn Hub articles "Bitcoin Integration", "Bitcoin Checker Canister", "Chain-Key Bitcoin", "Dogecoin Integration", "Exchange Rate Canister", "EVM RPC Canister", "SOL RPC Canister" (migrated, source retired)`

…ocs (#208) ## Summary Migrates all 57 developer-relevant articles from the Learn Hub \"How does ICP work?\" section into the developer docs, replacing Learn Hub as the canonical source for ICP protocol concepts before the site is retired. This was executed as 9 content batch PRs plus a post-migration review pass, all merged into this staging branch before landing on `main`: **Batch 1 — Protocol stack** (#209): Consensus, peer-to-peer, message routing, execution layer, state synchronization, and performance concept pages under `docs/concepts/protocol/`. **Batch 2 — Node infrastructure** (#210): `docs/concepts/node-infrastructure.md` — TEE (SEV-SNP) attestation, IC-OS layer model (SetupOS / HostOS / GuestOS), TEE key derivation and disk encryption. **Batch 3 — Edge infrastructure** (#211): `docs/concepts/edge-infrastructure.md` — boundary nodes, HTTP gateway, edge caching. **Batch 4 — Evolution and scaling** (#212): `docs/concepts/evolution-scaling.md` — horizontal scaling via subnet sharding, fault tolerance, governance-driven subnet creation, forkless protocol upgrades. **Chain fusion deep dives** (#213): Expanded `docs/concepts/chain-fusion/` with dedicated pages for Bitcoin integration, ckBTC mechanics, Ethereum integration, EVM RPC, Solana RPC, Dogecoin integration, and Exchange Rate Canister. Architecture and flow diagrams migrated to `public/concepts/chain-fusion/`. **Cryptography deep dives** (#214): Expanded `docs/concepts/chain-key-cryptography.md` and `docs/concepts/certified-data.md` with subnet keys, threshold signing internals, and certified communication theory. **Tokens, ledgers, and cycles** (#215): Expanded `docs/concepts/ledgers.md` and `docs/concepts/cycles.md` with ledger architecture, accounts, sub-accounts, cycles ledger transfer semantics, and NNS tokenomics. **Governance deep dives** (#216): Expanded `docs/concepts/governance.md` and added `docs/concepts/sns-framework.md` — NNS neuron attributes and bonuses, voting rewards formula, Neurons Fund, proposal taxonomy, SNS framework and architecture, DAO settings, launch flow, SNS neurons and rewards, and SNS proposals. **Principals and canister model** (#217): Expanded `docs/concepts/principals.md` and `docs/concepts/canisters.md` — principal model, canister control, Wasm execution model, and `docs/concepts/app-architecture.md`. **Post-migration holistic review** (#218, #226): - Navigation restructured across all concepts, guides, and references — sentence case applied throughout, section indices completed - Cross-reference audit: all Learn Hub outbound links replaced with internal doc links; first-use terms linked to their concept pages - Glossary expanded with TEE, boundary node, and cycle-related entries - System canisters content placement corrected - Exchange Rate Canister restructured across concept, reference, and guide pages (#XRC commits) **Migration infrastructure** (initial prep commits): - `.docs-plan/learn-hub-migration.md` — agent workflow and authoring rules for 9-batch execution - `.docs-plan/learn-hub-navigation.md` — per-article mapping (target file, action type, cross-link table) - `AGENTS.md / CLAUDE.md` — Learn Hub removed from external-docs list; linking rule updated - `sidebar.mjs` — all new concept pages registered ## Closes - Closes #187 — Content gap analysis: Learn Hub vs developer docs - Closes #190 — Gap analysis: articles on learn.internetcomptuter.org vs developer-docs `reference` and `concepts` - Closes #226 — Post-migration holistic review (content placement, nav structure, glossary, first-use terms) ## Sync recommendation hand-written (all pages authored from Learn Hub source articles via Zendesk API; no upstream repo to sync from)

marc0olo requested a review from a team as a code owner May 6, 2026 15:12

marc0olo mentioned this pull request May 6, 2026

docs: Batch 8 — tokens, ledgers, and cycles concepts #215

Merged

marc0olo added 2 commits May 7, 2026 13:12

fix(validate): correct Upstream comment format to use 'informed by'

543aa9b