docs: Chain Fusion deep dives

[marc0olo]

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

[marc0olo]

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, <!-- Upstream: --> comment present on all new files.

[marc0olo]

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]

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.

[marc0olo]

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