From 3a768c691799e377897c2879df16056b2dedf062 Mon Sep 17 00:00:00 2001 From: Leo Eichhorn Date: Thu, 8 Oct 2026 11:29:58 +0000 Subject: [PATCH] docs: add the secp256r1 ECDSA keys to the chain-key pages The interface spec and the management canister reference gained the `secp256r1` curve in #394. The concept and cycle cost pages still described threshold ECDSA as secp256k1 only. - The scheme table on the chain-key cryptography page gets a `secp256r1` (NIST P-256) row. Its use cases are web standards that require ES256: JSON Web Tokens, and VAPID web push (RFC 8292, section 2). - The key derivation paragraph names SLIP-10 for P-256, matching the `ecdsa_public_key` section of the spec. - The deployed keys table and the cycle costs table list `(secp256r1, test_key_1)` and `(secp256r1, key_1)` next to the secp256k1 keys, on the same subnets and at the same fees. `ic0.cost_sign_with_ecdsa` prices a signature by the subnet that holds the key, not by the curve. --- docs/concepts/chain-key-cryptography.md | 9 ++++++--- docs/references/cycle-costs.md | 4 ++-- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/concepts/chain-key-cryptography.md b/docs/concepts/chain-key-cryptography.md index d4cfc37c..c9647878 100644 --- a/docs/concepts/chain-key-cryptography.md +++ b/docs/concepts/chain-key-cryptography.md @@ -40,11 +40,12 @@ BLS was chosen for two properties: Chain-key signatures extend threshold cryptography beyond ICP's internal operations. They let canisters hold keys for external signature schemes and sign arbitrary messages, which means canisters can control accounts on other chains. -Two signature schemes are supported, with the Schnorr API offering two algorithm variants: +Two signature schemes are supported. The ECDSA API offers two curves, and the Schnorr API offers two algorithms: -| Scheme | Algorithm | Key ID examples | Use cases | +| Scheme | Curve or algorithm | Key ID examples | Use cases | |--------|-----------|-----------------|-----------| | Threshold ECDSA | `secp256k1` | `key_1`, `test_key_1` | Bitcoin (legacy/SegWit), Ethereum, EVM chains, Filecoin | +| Threshold ECDSA | `secp256r1` (NIST P-256) | `key_1`, `test_key_1` | JSON Web Tokens signed with ES256, VAPID web push | | Threshold Schnorr | `bip340secp256k1` | `key_1`, `test_key_1` | Bitcoin Taproot, Ordinals | | Threshold Schnorr | `ed25519` | `key_1`, `test_key_1` | Solana, TON, Polkadot, Cardano, NEAR | @@ -67,7 +68,7 @@ Threshold Schnorr (including Ed25519) protocols are simplified variants of the E A small number of **master keys** are deployed across the network: one per signature scheme. From each master key, the protocol derives a unique **canister root key** for every canister using the canister's principal as input. From the root key, canisters can derive an unlimited number of child keys by providing a `derivation_path` in API calls. -For ECDSA and BIP340, key derivation uses a generalized form of [BIP-32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki), which means derived keys are compatible with standard Bitcoin and Ethereum HD wallet tooling. Ed25519 uses a custom hierarchical derivation mechanism designed for this use case. +For ECDSA on `secp256k1` and for BIP340, key derivation uses a generalized form of [BIP-32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki), which means derived keys are compatible with standard Bitcoin and Ethereum HD wallet tooling. ECDSA on `secp256r1` uses the same generalization over P-256, which is [SLIP-10](https://github.com/satoshilabs/slips/blob/master/slip-0010.md). Ed25519 uses a custom hierarchical derivation mechanism designed for this use case. Derivation is transparent: it happens inside the protocol as part of the signing and public-key-retrieval APIs. You provide a derivation path and the protocol handles the rest. @@ -91,6 +92,8 @@ The following master keys are deployed at the time of writing. The Network Nervo |--------|--------|---------|----------------| | `(secp256k1, test_key_1)` | ECDSA | Development and testing | 13-node subnet | | `(secp256k1, key_1)` | ECDSA | Production | High-replication subnet | +| `(secp256r1, test_key_1)` | ECDSA | Development and testing | 13-node subnet | +| `(secp256r1, key_1)` | ECDSA | Production | High-replication subnet | | `(bip340secp256k1, test_key_1)` | Schnorr | Development and testing | 13-node subnet | | `(bip340secp256k1, key_1)` | Schnorr | Production | High-replication subnet | | `(ed25519, test_key_1)` | Schnorr (Ed25519) | Development and testing | 13-node subnet | diff --git a/docs/references/cycle-costs.md b/docs/references/cycle-costs.md index 2c5b2e10..4d2aa17e 100644 --- a/docs/references/cycle-costs.md +++ b/docs/references/cycle-costs.md @@ -94,8 +94,8 @@ Threshold signing and key derivation are core ICP protocol capabilities: the cry | Key name | Algorithm(s) | Environment | Signing subnet | Cycles | ~USD | |----------|-------------|------------|----------------|--------|------| -| `test_key_1` | ECDSA (`secp256k1`), Schnorr (`bip340secp256k1`, `ed25519`) | Testing | 13-node (`fuqsr`) | 10_000_000_000 | ~$0.0137 | -| `key_1` | ECDSA (`secp256k1`), Schnorr (`bip340secp256k1`, `ed25519`) | Production | 34-node fiduciary (`pzp6e`) | 26_153_846_153 | ~$0.0357 | +| `test_key_1` | ECDSA (`secp256k1`, `secp256r1`), Schnorr (`bip340secp256k1`, `ed25519`) | Testing | 13-node (`fuqsr`) | 10_000_000_000 | ~$0.0137 | +| `key_1` | ECDSA (`secp256k1`, `secp256r1`), Schnorr (`bip340secp256k1`, `ed25519`) | Production | 34-node fiduciary (`pzp6e`) | 26_153_846_153 | ~$0.0357 | If the canister may be blackholed or called by other canisters, send more cycles than the listed cost: unused cycles are refunded, and this ensures calls succeed if the signing subnet grows in node count.