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

[marc0olo]

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

[marc0olo]

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"

[marc0olo]

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)