WIP: Ledger security release docs (2026.1)

[evanorti]

WIP: Ledger security release docs (2026.1)

Documentation for the 2026.1 security release: post-quantum keys (ML-DSA),
zero-downtime consensus key rotation, and remote signing via Cosmos-KMS.
Every technical claim is code- or test-verified before its page merges.

Nav: three groups under Run a Node (SDK next): Key Rotation, Post-quantum Keys,
Remote Signing: Cosmos-KMS.

Key Rotation

• Key rotation — concept: which keys rotate, mechanics, safety rails
• Rotate a consensus key, Staking — test-verified on a localnet
• Rotate a consensus key, PoA — provisional against feat(enterprise/poa): consensus key rotations cosmos-sdk#26590 until merge

Post-quantum Keys

• Post-quantum keys — keys and algorithms survey, ML-DSA, costs, EVM note
• Enable ML-DSA keys — genesis and governance paths; governance flow test-verified
• Migrate a validator to ML-DSA — keygen step blocked on tooling (TODO(ERIC) in page)
• Create an ML-DSA account — test-verified on a localnet

Remote Signing: Cosmos-KMS

• Cosmos-KMS and remote signing (overview)
• Remote signing tutorial — test-verified e2e
• Configure a signing backend (AWS KMS, PKCS#11, file) — AWS/PKCS#11 sections pending execution
• Rotate a consensus key held in Cosmos-KMS — test-verified e2e
• Cosmos-KMS configuration reference
• Remote signing best practices
• Migrate from TMKMS — skeleton; TODO(ERIC) sections pending content

Module references and release-impact fixes

• x/staking README: MsgRotateConsPubKey, KeyRotationFee, rotation stores, End-Block
• PoA api/governance/overview: RotateConsPubKey (provisional until #26590 merges)
• run-production: TMKMS walkthrough replaced with Cosmos-KMS links + deprecation note
• keyring: key algorithms corrected (secp256k1 + ml_dsa_65 via --key-type), new pages linked
• run-node: state-sync-adjacent next steps, link fixes

Upgrading

• 0.53/0.54 → 0.55 upgrade docs — blocked on UPGRADING content (FOU-754)

Verification

Five flows run end to end against local chains, commands exactly as published:
governance param change, staking rotation, ML-DSA account, kms file-backend
tutorial, and kms rotation. Each tested page carries a hidden verification
comment with environment and commits.

• npx mint broken-links clean

Review

• Per-page review issues with instructions live in Linear (Ledger Security Docs
  project, FOU-739 to FOU-755): rotation set → Matt, ML-DSA + kms sets → Eric,
  release notes → Alex. Open eng questions are tracked there, and as TODO(ERIC)/
  TODO(MATT) comments in the pages.

[greptile-apps]

Greptile Summary

This PR adds the 2026.1 security release documentation: consensus key rotation (staking and PoA), post-quantum ML-DSA keys, and remote signing via Cosmos-KMS. The content is thorough and most guides are end-to-end verified against local chains.

• Thirteen new pages across sdk/next/keys/ and sdk/next/kms/ cover key rotation concepts and procedures, ML-DSA key enablement and migration, and the full Cosmos-KMS lifecycle (tutorial, backend configuration, rotation, TMKMS migration, best practices, and reference).
• Existing pages (run-production.mdx, keyring.mdx, run-node.mdx, and the staking module README) are updated to reference the new content and remove the outdated TMKMS walkthrough.
• The algorithm/backend support matrix is stated differently in configure-backend.mdx and configuration-reference.mdx: the reference says mldsa65 is file-only while configure-backend and the work log confirm it works on all three backends; the reference says secp256k1eth is file-only while configure-backend lists it under AWS KMS — these two pages need to be reconciled before the content ships.

Confidence Score: 4/5

Safe to merge after reconciling the algorithm/backend matrix between configuration-reference.mdx and configure-backend.mdx; all other content is well-verified.

The two KMS pages disagree about which algorithms each backend supports: the reference says mldsa65 is file-only while the configure-backend page and the work log confirm it works on all three backends; the configure-backend page says AWS KMS supports secp256k1eth while the reference (backed by source traces in the work log) says secp256k1eth is file-only. An operator configuring a production mldsa65 setup against AWS KMS would get the wrong answer from whichever page they consult. Everything else in the PR is consistent and well-grounded.

sdk/next/kms/configuration-reference.mdx and sdk/next/kms/configure-backend.mdx need to be reconciled on the per-backend algorithm support matrix before this ships.

Important Files Changed

Filename	Overview
sdk/next/kms/configuration-reference.mdx	New reference page for kms.yaml fields; line 44's algorithm/backend matrix incorrectly restricts mldsa65 to the file backend, contradicting configure-backend.mdx and the work-log's source confirmation that mldsa65 works on all three backends.
sdk/next/kms/configure-backend.mdx	New guide for AWS KMS, PKCS#11, and file backends; line 20 overstates AWS KMS algorithm coverage by including secp256k1eth, which contradicts the configuration-reference and work-log source trace identifying secp256k1eth as file-only.
sdk/next/kms/tutorial-file-backend.mdx	New end-to-end tutorial for Cosmos-KMS file backend; startup timing race condition between signer and node is clearly documented in a Note callout; no issues found.
sdk/next/kms/rotate-key-remote-signer.mdx	New tutorial for rotating a consensus key held in Cosmos-KMS; procedure is well-grounded with a hidden e2e verification comment; double-sign danger is clearly called out.
sdk/next/kms/migrate-from-tmkms.mdx	New migration guide from TMKMS to Cosmos-KMS; tmkms.toml-to-kms.yaml mapping table is thorough; softsign key conversion is verified; double-sign cutover procedure has a clear Danger callout.
sdk/next/kms/best-practices.mdx	New best practices page for remote signing; covers placement, transport pinning, key protection levels, and the one-signer rule; no issues found.
sdk/next/keys/key-rotation.mdx	New concept page for consensus key rotation; covers mechanics, safety rails, PoA differences, and slashing accountability; no new issues beyond those already in review threads.
sdk/next/keys/rotate-validator-key.mdx	New zero-downtime staking rotation tutorial; localnet-verified; double-sign danger and rotation limit edge cases are clearly documented.
sdk/next/keys/post-quantum-keys.mdx	New survey of key types and ML-DSA; cost table is accurate; EVM post-quantum path correctly tied to EIP-7702/8051/8141 roadmap; no issues found.
sdk/next/modules/staking/README.mdx	Adds MsgRotateConsPubKey message docs, KeyRotationFee parameter row, four rotation state stores, and end-block lifecycle; links back to the procedural guides; no issues found.
sdk/next/node/run-production.mdx	Replaces the full TMKMS walkthrough with a brief Cosmos-KMS pointer and a migration note; no issues found.
work-log/security-release.md	Work log for the security release branch; entries are out of chronological order and are far more verbose than the short guideline in work-log/CLAUDE.md.
docs.json	Adds three nav groups (Key Rotation, Post-quantum Keys, Remote Signing: Cosmos-KMS) under Run a Node; all new pages are registered; structure uses a Guides subgroup correctly.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Op as Operator
    participant Node as Validator Node
    participant KMS as Cosmos-KMS
    participant Backend as Key Backend
    participant Chain as Chain

    Note over Op,Chain: Setup
    Op->>KMS: kms init --home ~/.kms
    Op->>KMS: Configure kms.yaml
    Op->>Node: Set priv_validator_laddr

    Note over Op,Chain: Startup
    Op->>KMS: kms start
    KMS->>Node: dial tcp://host:26659 (retries)
    Op->>Node: simd start
    Node-->>KMS: privval connection accepted
    KMS->>Backend: load / fetch key
    Backend-->>KMS: key material
    Node->>KMS: GetPubKey request
    KMS-->>Node: consensus public key

    Note over Op,Chain: Per-block signing
    Node->>KMS: SignVote / SignProposal
    KMS->>Backend: sign(message)
    Backend-->>KMS: signature
    KMS-->>Node: signed vote / proposal
    Node->>Chain: broadcast signed vote

    Note over Op,Chain: Key rotation
    Op->>KMS: kms init --home ~/.kms2
    Op->>Node: simd start shadow node
    Op->>Chain: MsgRotateConsPubKey
    Chain-->>Node: validator set update
    Op->>KMS: stop old signer and node

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Op as Operator
    participant Node as Validator Node
    participant KMS as Cosmos-KMS
    participant Backend as Key Backend
    participant Chain as Chain

    Note over Op,Chain: Setup
    Op->>KMS: kms init --home ~/.kms
    Op->>KMS: Configure kms.yaml
    Op->>Node: Set priv_validator_laddr

    Note over Op,Chain: Startup
    Op->>KMS: kms start
    KMS->>Node: dial tcp://host:26659 (retries)
    Op->>Node: simd start
    Node-->>KMS: privval connection accepted
    KMS->>Backend: load / fetch key
    Backend-->>KMS: key material
    Node->>KMS: GetPubKey request
    KMS-->>Node: consensus public key

    Note over Op,Chain: Per-block signing
    Node->>KMS: SignVote / SignProposal
    KMS->>Backend: sign(message)
    Backend-->>KMS: signature
    KMS-->>Node: signed vote / proposal
    Node->>Chain: broadcast signed vote

    Note over Op,Chain: Key rotation
    Op->>KMS: kms init --home ~/.kms2
    Op->>Node: simd start shadow node
    Op->>Chain: MsgRotateConsPubKey
    Chain-->>Node: validator set update
    Op->>KMS: stop old signer and node

Loading

_{Reviews (3): Last reviewed commit: "Update tutorial-file-backend.mdx" | Re-trigger Greptile}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cosmos-docs	🟢 Ready	View Preview	Jul 10, 2026, 7:56 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[evanorti]

@greptileai plz rereview

[evanorti]

@Eric-Warehime This happens often in tests:

When you start the signer first, it keeps trying to connect and waits longer between each attempt, eventually settling into a knock every 10 seconds. The node only holds its door open for 3 seconds at startup and never retries, so if you're slow starting it, the two never line up and the node quits.

You need to do it within 5 seconds, which is harder for humans.