docs: protocol canisters reference

[marc0olo]

Summary

• Bitcoin canisters: mainnet (ghsi2) and testnet (g4xu7) with subnets, specs, key API endpoints; notes deprecation of management canister Bitcoin API
• ckBTC: mainnet + testnet4 ledger/minter/index IDs, minter configuration parameters, all endpoints, deposit/withdrawal flow
• ckETH: ledger/minter IDs, deposit/withdrawal flow
• EVM RPC canister: supported chains, built-in RPC providers table, cycle cost formula, consensus strategy guidance
• Exchange rate canister: data sources, rate aggregation, Candid interface, cycle costs table, icp canister call example
• SNS-W canister: purpose and subnet
• Quick reference table: all 10 canister IDs in one place

Sync recommendation

informed by dfinity/portal — chain fusion and protocol canister reference pages; informed by dfinity/icskills — ckbtc, evm-rpc

[marc0olo]

Review: Protocol Canisters

Must fix

• Invalid --with-cycles flag in XRC example: The CLI example at line 245 uses --with-cycles 10000000000, but --with-cycles is not a valid flag for icp canister call. Per .sources/icp-cli/docs/reference/cli.md and crates/icp-cli/src/commands/canister/call.rs, the --cycles flag in icp canister call only exists for proxy calls (requires = "proxy") and is not applicable to direct canister calls. The icp-cli has no mechanism for attaching cycles to a direct (non-proxy) canister call. The example should either be removed or rewritten to clarify that calling the XRC from the CLI directly does not allow cycle attachment — only canister-to-canister calls can attach cycles to the XRC. (Note: the icskills evm-rpc/SKILL.md also uses --with-cycles — that may itself be a bug in the skill file, but the docs should not repeat an unverified flag.)

• Broken internal links — bitcoin and ethereum chain-fusion guides: Lines 42, 102, and 128 link to ../guides/chain-fusion/bitcoin.md and ../guides/chain-fusion/ethereum.md, but both files do not exist with a .md extension. The actual files are bitcoin.mdx and ethereum.mdx. Per project rules, links to .mdx pages use .md extension (Astro resolves both), so the links themselves are syntactically correct — but ls docs/guides/chain-fusion/bitcoin.md returns "No such file". Running ls docs/guides/chain-fusion/bitcoin.mdx confirms the .mdx file exists. This means the links are valid per Astro conventions; however, the same check at line 284 (Next steps section) also links to these files and should be confirmed working at build time. No action needed per project rules — links to .mdx pages always use .md extension — but this should be confirmed by npm run build.

• Missing ckETH Index canister: The page includes a ckBTC Index canister (n5wcd-faaaa-aaaar-qaaea-cai) but omits the ckETH Index canister (s3zol-vqaaa-aaaar-qacpa-cai), which exists per .sources/icskills/skills/icrc-ledger/SKILL.md. The portal also confirms "The ckETH ledger and ckETH index canisters are regular ICRC-1 compliant canisters." The ckETH section table and the Quick Reference table should both include the ckETH Index canister for completeness.

Suggestions

• Unverified deprecation claim for management canister Bitcoin API: The callout on line 14 states "The management canister Bitcoin API (bitcoin_get_utxos, bitcoin_get_balance, etc.) is deprecated." The management canister spec (public/reference/ic.did) still contains these methods without any deprecation annotation, and portal's btc-api.mdx does not describe them as deprecated. If this is correct, a source citation would help. If it cannot be sourced from .sources/, consider softening to "Call the Bitcoin canisters directly for better performance" rather than stating deprecation without evidence.

• Bitcoin section uses "testnet" vs ckBTC section uses "Testnet4": The Bitcoin canister section heading is "Bitcoin testnet" (line 24) but the ckBTC section heading is "Bitcoin Testnet4" (line 56). The portal names it "Testnet (v4)". For consistency, the Bitcoin canister section should use "Bitcoin testnet (v4)" or "Bitcoin Testnet4" to match ckBTC and clarify it is the same network.

• SNS-W section links externally when an internal page exists: Line 265 links to https://learn.internetcomputer.org/hc/en-us/articles/34084394684564-SNS-Service-Nervous-System for "governance context". There is an internal stub at docs/concepts/governance.md. Per project rules, internal pages are preferred over external URLs. Since the governance stub is currently empty, the external link is acceptable for now — but should be updated to the internal link once the governance concept page is filled.

• ckETH section does not list ckETH minter endpoints: Unlike the ckBTC section, which documents minter endpoints in detail, the ckETH section omits equivalent minter endpoints (e.g., withdraw_eth). For consistency, either list the key ckETH minter endpoints or add a note explaining the intentional omission (e.g., the ckETH minter is primarily for bridge flows, not direct integration).

Verified

• All canister IDs verified against .sources/: Bitcoin mainnet (ghsi2-tqaaa-aaaan-aaaca-cai) and testnet (g4xu7-jiaaa-aaaan-aaaaq-cai) confirmed via .sources/portal/docs/references/system-canisters/index.mdx; ckBTC Ledger, Minter, Index (mainnet and testnet4) confirmed via .sources/icskills/skills/ckbtc/SKILL.md; ckETH Ledger (ss2fx-dyaaa-aaaar-qacoq-cai) and Minter (sv3dd-oaaaa-aaaar-qacoa-cai) confirmed via .sources/portal/docs/defi/rosetta/icrc_rosetta/index.mdx and .sources/portal/docs/defi/chain-key-tokens/ckerc20/overview.mdx; EVM RPC (7hfb6-caaaa-aaaar-qadga-cai) confirmed via .sources/icskills/skills/evm-rpc/SKILL.md; XRC (uf6dk-hyaaa-aaaaq-qaaaq-cai) confirmed via .sources/portal/docs/references/system-canisters/xrc.mdx; SNS-W (qaa6y-5yaaa-aaaaa-aaafa-cai) confirmed via .sources/portal/docs/references/system-canisters/index.mdx.
• ckBTC minter configuration values verified: retrieve_btc_min_amount (50,000 satoshi), min_confirmations (6), kyt_fee (100 satoshi) confirmed via .sources/portal/docs/references/ckbtc-reference.mdx.
• ckBTC transfer fee (10 satoshi) confirmed via .sources/icskills/skills/ckbtc/SKILL.md.
• EVM RPC cost formula, provider table, and supported chain IDs verified against .sources/icskills/skills/evm-rpc/SKILL.md.
• XRC cycle costs (1B required, 20M/260M/500M actual, 1M minimum on error) verified against .sources/portal/docs/references/system-canisters/xrc.mdx.
• XRC data sources (Coinbase, Kucoin, OKX, Gate.io, MEXC, Poloniex, Crypto.com, Bitget, DigiFinex) verified against .sources/portal/docs/references/system-canisters/xrc.mdx.
• ckETH deposit (deposit function, ReceivedEth event) and withdrawal (withdraw_eth, icrc2_approve) flows verified via .sources/portal/docs/defi/chain-key-tokens/cketh/overview.mdx.
• Frontmatter is complete with required title and description fields.
• No dfx references, no mo:base imports, no banned internetcomputer.org/docs/ or docs.internetcomputer.org links found.
• <!-- Upstream: --> comment present at end of page (line 289), listing portal and icskills sources used.
• All non-chain-fusion internal links verified: system-canisters.md and management-canister.md both exist.
• EVM RPC consensus terminology (Equality, MultiRpcResult::Consistent, MultiRpcResult::Inconsistent) matches .sources/icskills/skills/evm-rpc/SKILL.md.
• Page follows Diataxis reference format: tables of IDs, endpoint lists, parameter tables, and example call — appropriate for a reference page.
• SNS-W subnet ID (tdb26-jop6k-...) confirmed as the NNS subnet via .sources/portal/docs/references/system-canisters/index.mdx.
• Quick Reference table at bottom is complete and consistent with individual sections.

[marc0olo]

<!-- feedback-addressed -->
Feedback addressed for PR #72 (docs/reference/protocol-canisters.md):

Changes applied

Must fix — Invalid --with-cycles flag in XRC example (human review, verified correct)

Verified against .sources/icp-cli/docs/reference/cli.md: the --cycles flag on icp canister call only applies when --proxy is specified. There is no --with-cycles flag at all, and direct CLI calls cannot attach cycles. The XRC example was rewritten to remove --with-cycles 10000000000 and add a note explaining that calling the XRC with cycles requires canister-to-canister calls via call_with_payment128. The CLI example is kept for inspection purposes only with a NotEnoughCycles warning.

Must fix — Missing ckETH Index canister (human review, verified correct)

Verified against .sources/icskills/skills/icrc-ledger/SKILL.md: ckETH Index: s3zol-vqaaa-aaaar-qacpa-cai. Added to the ckETH mainnet canister IDs table and the Quick Reference table. Updated the <\!-- Upstream: --> comment to include skills/icrc-ledger/SKILL.md.

Suggestion — Unverified deprecation claim (human review, applied)

Checked public/reference/ic.did and portal sources: the management canister Bitcoin methods (bitcoin_get_utxos, bitcoin_get_balance, etc.) have no deprecation annotations. The portal's btc-api.mdx does not describe them as deprecated. The callout was softened from "is deprecated" to a recommendation to use the Bitcoin canisters directly for better performance. Also removed the secondary mention of "deprecated management canister Bitcoin API" from the Key endpoints paragraph.

Suggestion — Bitcoin testnet naming consistency (human review, applied)

Portal's btc-api.mdx uses "Testnet (v4)" for the Bitcoin canister section. Renamed the section heading from "Bitcoin testnet" to "Bitcoin testnet (v4)" and updated the Quick Reference table row to match.

Changes skipped

Must fix — Broken internal links for bitcoin.md and ethereum.md (human review, skipped)

Per project rules, links to .mdx pages always use .md extension (Astro resolves both). The reviewer confirmed this in their own analysis: "No action needed per project rules." The links ../guides/chain-fusion/bitcoin.md and ../guides/chain-fusion/ethereum.md resolve correctly to the .mdx files at build time. The build failure in this worktree is caused by missing .sources/examples submodule (SSH keys unavailable in sandbox) — confirmed pre-existing by testing with git stash — not by these links.

Suggestion — SNS-W section external link (human review, skipped)

Reviewer noted: "Since the governance stub is currently empty, the external link is acceptable for now." No change needed.

Suggestion — ckETH minter endpoints (human review, skipped)

The ckETH section documents the deposit/withdrawal flows which reference the key endpoints (deposit, withdraw_eth, icrc2_approve). Unlike ckBTC, the ckETH minter exposes fewer endpoints for direct integration (most interaction is via the Ethereum helper contract). The portal source (docs/defi/chain-key-tokens/cketh/overview.mdx) does not provide a comprehensive endpoint list comparable to ckBTC's. The current How it works section adequately covers the key minter interactions.

Build note

npm run build fails in this worktree due to missing .sources/examples submodule (SSH keys blocked in sandbox; git submodule update --init failed for several submodules). This failure is pre-existing and unrelated to the changes in this PR — confirmed by testing with git stash. The error is in docs/guides/backends/https-outcalls.mdx (CodeExample component referencing .sources/examples/). The build passes in the main repo where submodules are fully initialized.