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 WIP PR adds 14 new documentation pages for the 2026.1 security release, covering post-quantum ML-DSA keys, zero-downtime consensus key rotation (staking and PoA), and Cosmos-KMS remote signing. It also updates existing pages (run-production, keyring, run-node, staking/README, PoA api and overview) to reflect the new release and correct stale content.

• Key rotation (concept + staking + PoA procedures): step-by-step guides are test-verified on a local chain; the PoA page is marked provisional against feat(enterprise/poa): consensus key rotations cosmos-sdk#26590.
• Post-quantum keys (survey, genesis/governance enable, validator migration, user account creation): governance flow and account creation are test-verified; the validator keygen step is a documented TODO pending release tooling.
• Cosmos-KMS remote signing (overview, file-backend tutorial, backend configuration, key rotation, config reference, best practices, TMKMS migration): file-backend tutorial and KMS rotation are verified end-to-end; AWS KMS and PKCS#11 backend sections carry explicit test TODOs; the TMKMS migration guide is a partial skeleton with clearly marked gaps.
• All new pages carry noindex: true and docs.json registration is complete.

Confidence Score: 5/5

Safe to continue reviewing; all changes are documentation only with no executable code paths affected.

Every changed file is an MDX documentation page or a work log entry. The procedural pages that are marked test-verified carry hidden verification comments with environment details. Incomplete sections (TMKMS migration skeleton, AWS/PKCS#11 backend, ML-DSA keygen) are consistently marked with noindex: true and explicit TODO comments, so unfinished content cannot reach readers. The only finding is a style guide violation in poa/api.mdx that follows the pre-existing bold-label pattern of that file and has no reader-facing impact.

sdk/next/kms/migrate-from-tmkms.mdx has three skeleton sections (softsign key format, state migration, YubiHSM) that must be filled before the page can be published. sdk/next/enterprise/poa/api.mdx and sdk/next/keys/rotate-validator-key-poa.mdx are provisional against cosmos/cosmos-sdk#26590 and need re-verification at merge.

Important Files Changed

Filename	Overview
docs.json	Adds three nav groups under Run a Node (Key Rotation, Post-quantum Keys, Remote Signing: Cosmos-KMS) with all 14 new pages correctly registered; no redirects needed since paths are new.
sdk/next/keys/key-rotation.mdx	New concept page explaining consensus key rotation mechanics, safety rails, and PoA vs staking differences; accurate and well-linked. Bold list items flagged in a previous review pass.
sdk/next/keys/rotate-validator-key.mdx	Step-by-step staking rotation guide with test-verified commands, correct state-sync pointer, and appropriate double-sign Danger callout.
sdk/next/keys/post-quantum-keys.mdx	ML-DSA survey page with accurate size/cost numbers and correct EVM/EIP roadmap description; bold Example: previously flagged.
sdk/next/keys/enable-ml-dsa-keys.mdx	Governance-path guide with test-verified jq command for building the consensus param proposal; Warning callout correctly explains the null-field failure mode.
sdk/next/keys/create-ml-dsa-account.mdx	Test-verified ML-DSA account creation guide; content and commands are correct.
sdk/next/kms/tutorial-file-backend.mdx	End-to-end verified tutorial for Cosmos-KMS file backend; correctly documents the signer-first startup requirement and the startup-timeout edge case.
sdk/next/kms/rotate-key-remote-signer.mdx	Test-verified rotation guide for a KMS-held key; Danger callout correctly warns against using show-validator on a remote-signing node.
sdk/next/kms/configuration-reference.mdx	Complete kms.yaml field reference transcribed from config.go; two open TODOs on algorithm default behavior and gRPC TLS requirements are clearly marked.
sdk/next/kms/migrate-from-tmkms.mdx	Skeleton migration guide with correct config mapping table and double-sign Danger callout; softsign key format conversion, state migration, and YubiHSM sections are stubs with explicit TODOs — not yet safe to publish as-is.
sdk/next/enterprise/poa/api.mdx	Adds RotateConsPubKey message reference (provisional against cosmos/cosmos-sdk#26590); new section uses bold labels matching the pre-existing file style but violating the no-bold rule.
sdk/next/node/run-production.mdx	TMKMS walkthrough replaced with concise Cosmos-KMS pointer and TMKMS deprecation Note; clean substitution with correct links.
sdk/next/node/keyring.mdx	Corrects two pre-existing errors: fixes broken in-page anchor and updates key algorithm list to match the actual keyring source (secp256k1 + ml_dsa_65, removing the stale ed25519/--algo claim).
sdk/next/kms/best-practices.mdx	Security-oriented placement and transport guide; correctly explains the SecretConnection vs Noise asymmetry and the one-signer-per-key rule with an appropriately loud Danger callout.
work-log/security-release.md	Work log for the branch; entries follow the required format (date, bullet points, brief descriptions) and are thorough.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Operator submits MsgRotateConsPubKey] --> B[Chain emits power update to CometBFT:
old key → 0, new key → full power]
    B --> C{2 heights pass}
    C --> D[CometBFT activates new key
Chain stores new key]
    D --> E[Shadow node starts signing]
    D --> F[Old node stops signing]
    E --> G[Retire old node / signer]

    subgraph Zero-downtime window
        H[Old node still signing] -.-> C
        I[Shadow node syncing
non-signing full node] -.-> C
    end

    subgraph Remote signer path
        J[New key in KMS backend] --> K[Second kms process
for shadow node]
        K --> I
    end

    subgraph ML-DSA path
        L[Generate ml_dsa_65 key] --> M[Replace priv_validator_key.json
on shadow node]
        M --> I
    end

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"}}}%%
flowchart TD
    A[Operator submits MsgRotateConsPubKey] --> B[Chain emits power update to CometBFT:
old key → 0, new key → full power]
    B --> C{2 heights pass}
    C --> D[CometBFT activates new key
Chain stores new key]
    D --> E[Shadow node starts signing]
    D --> F[Old node stops signing]
    E --> G[Retire old node / signer]

    subgraph Zero-downtime window
        H[Old node still signing] -.-> C
        I[Shadow node syncing
non-signing full node] -.-> C
    end

    subgraph Remote signer path
        J[New key in KMS backend] --> K[Second kms process
for shadow node]
        K --> I
    end

    subgraph ML-DSA path
        L[Generate ml_dsa_65 key] --> M[Replace priv_validator_key.json
on shadow node]
        M --> I
    end

Loading

_{Reviews (2): Last reviewed commit: "update todos" | 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