docs: chain-key cryptography concept page

[marc0olo]

Summary

• Explains chain-key cryptography from a developer perspective: what it enables, how it works, and what you can do with it
• Covers threshold BLS (consensus, certification, randomness), threshold ECDSA, threshold Schnorr (BIP340 + Ed25519), and distributed key generation
• Includes deployed master keys table (6 keys: test + production for each scheme)
• Includes supported chains table showing which signature schemes each chain uses and the integration method
• Covers key derivation (BIP-32 compatible for ECDSA/BIP340), pre-signature optimization, and chain evolution (subnet membership changes via key resharing)
• Concept page only — no CLI commands per Diataxis rules; links to management canister reference and chain fusion guides for practical usage

Sync recommendation

informed by dfinity/portal docs/references/t-sigs-how-it-works.mdx, docs/building-apps/chain-fusion/overview.mdx, docs/building-apps/chain-fusion/supported-chains.mdx

[marc0olo]

Review: Chain-Key Cryptography

Must fix

• EdDSA framing as a third signature scheme. The PR lists three schemes in the table header: "Threshold ECDSA", "Threshold Schnorr (BIP340)", and "Threshold Schnorr (Ed25519)". The opening paragraph also says "threshold ECDSA, Schnorr, and EdDSA signatures." However, the portal source (t-sigs-how-it-works.mdx:9) states ICP supports threshold ECDSA and threshold Schnorr — two schemes, not three. Ed25519 is an algorithm within the Schnorr API (schnorr_public_key, sign_with_schnorr), not a separate scheme with its own API. The "Chain-key signatures" section and table should reflect this: two schemes (ECDSA + Schnorr), with Schnorr supporting two algorithms (BIP340 and Ed25519).

• Cardano missing Schnorr in supported chains table. The PR lists Cardano as "ECDSA, EdDSA" but the portal source (supported-chains.mdx:77) lists "ECDSA, EdDSA, Schnorr".

• Missing Ethereum guide cross-link. The stub's <!-- Cross-Links --> specifies guides/chain-fusion/ethereum, and the file exists. The "What's next" section only links to Bitcoin via the Chain Fusion concept page but doesn't mention the Ethereum guide directly. Since ECDSA is the primary scheme for Ethereum integration, a direct link would be valuable.

Suggestions

• Missing chains from the supported chains table. The portal source lists several chains not in the PR table: Aptos, Avalanche, Hedera, Kaspa, Monero, Stacks, Sui, TRON, XRP. The PR says "this is not exhaustive" which is fair, but some notable omissions (XRP, Avalanche, TRON — all top-20 chains) could be worth including for completeness. At minimum, consider adding them since the portal already lists them.

• "key management across subnets" coverage is thin. The content brief asks about key management across subnets. The DKG section mentions key resharing briefly, and the "Deployed keys" table mentions signing subnets, but the concept of backup subnets (the portal says each key is deployed on two subnets — one for signing, one for backup) isn't explained. Adding a sentence about this would improve coverage.

• Learn Hub link at bottom is vague. The chain evolution section ends with "see the Learn Hub" — a generic link with no specific article. The stub lists specific Learn Hub articles (Chain Evolution: 34210120121748). Either link to the specific article or drop the link entirely.

• "fast finality" in frontmatter description. The description says "fast finality" but the page doesn't discuss finality — it discusses fast verification. Consider aligning the description with the actual content.

Verified

• All 9 internal links resolve to existing files (network-overview.md, certified-variables.md, onchain-randomness.md, chain-fusion.md, management-canister.md, ic-interface-spec.md, cycles-costs.md, vetkeys.md, bitcoin.md)
• API method names (ecdsa_public_key, sign_with_ecdsa, schnorr_public_key, sign_with_schnorr) verified against portal source
• 6 deployed master keys verified against portal source
• Key derivation description (BIP-32 for ECDSA/BIP340, custom for Ed25519) verified
• DKG fault tolerance ("up to one-third") verified
• BIP340/Schnorr/Taproot terminology verified
• No dfx references, no .mdx/JSX, code is prose-only (appropriate for concept page), frontmatter complete
• Diataxis: concept page — explains "what" and "why" without CLI commands or step-by-step instructions ✓
• Content brief coverage: threshold ECDSA ✓, threshold Schnorr ✓, BLS ✓, chain evolution ✓, developer perspective ✓, supported chains table ✓

[marc0olo]

Feedback addressed:

• Fixed EdDSA framing: two schemes (ECDSA + Schnorr with two algorithm variants), not three separate schemes
• Fixed supported chains intro sentence to correctly group Schnorr variants
• Corrected Cardano to Ed25519 only (ECDSA/Schnorr are Plutus VM builtins, not tx auth)
• Corrected Cosmos to ECDSA only (Ed25519 is validator-only, not user accounts)
• Normalized Bitcoin/Dogecoin integration method to "Direct"
• Added 7 verified chains: Aptos, Avalanche, Hedera, Stacks, Sui, TRON, XRP
• Dropped Monero (CLSAG ring sigs incompatible with ICP's Ed25519) and Kaspa (BIP-340 compatibility unverified)
• Added Ethereum guide cross-link to What's next section
• Added backup subnet availability note to Deployed keys section
• Replaced generic Learn Hub link with specific Chain Evolution article
• Fixed frontmatter description: "fast finality" → "fast verification"