Crypto-agility and a migration plan

What crypto-agility means#

Crypto-agility is the ability to replace a cryptographic algorithm in a system without redesigning the system. It sounds abstract; in practice it shows up as a handful of concrete properties. Signing and verification go through one interface instead of being called inline from dozens of places. Stored keys and signatures carry an algorithm identifier. Size limits are parameters, not constants. Peers can negotiate which algorithm they will use. And there is a tested procedure for rotating keys.

type SchemeId = "ed25519" | "ml-dsa-65" | "hybrid-ed25519+ml-dsa-65";

interface Signer {
  scheme: SchemeId;
  publicKey(): Uint8Array;
  sign(message: Uint8Array, context: Uint8Array): Promise<Uint8Array>;
}

interface Verifier {
  verify(scheme: SchemeId, publicKey: Uint8Array,
         message: Uint8Array, signature: Uint8Array,
         context: Uint8Array): Promise<boolean>;
}

// Stored alongside every key and signature:
type Tagged<T> = { scheme: SchemeId; version: number; value: T };

None of this needs post-quantum code to exist yet. A codebase where every signature is tagged ed25519 and routed through one interface is already far more agile than one with hard-coded 64-byte buffers. The next historical migration, whatever it is, will be cheaper too.

Step 1 — Inventory#

You cannot migrate what you have not found. Build a written inventory of every place your product creates, stores, transmits or checks a signature or a key exchange. For a Solana product this usually includes:

• User wallet signatures over transactions and over off-chain messages (sign-in, permits, orders).
• Program authorities: upgrade authority, mint and freeze authorities, admin and fee keys stored in program state, multisig members.
• Durable nonce accounts and any pre-signed transactions.
• Backend hot keys: fee payers, cranks, relayers, oracle publishers.
• Off-chain services: API authentication, webhooks, JWT signing, service-to-service TLS.
• Every serialiser, account layout and size check that assumes 32-byte keys or 64-byte signatures.
• Third-party programs and SDKs whose cryptographic choices you inherit.

For each entry record the algorithm, where the key lives, who controls it, how long it lives, and what an attacker could do with it. Searching the codebase for 64, 32, ed25519, nacl, sign and verify finds a surprising amount.

Step 2 — Prioritise#

Rank inventory entries by two things: how long the protected thing must stay safe, and how hard the entry is to change. A useful rule of thumb, sometimes called Mosca's inequality, says you have a problem if the time your data must stay secure plus the time your migration will take exceeds the time until a capable quantum attacker exists. You do not know the last number. You can estimate the first two, and they are usually longer than people expect.

1. 1Confidential data on classical key exchange with a long secrecy lifetime. This is exposed today (chapter 03). Move these channels to hybrid X25519 + ML-KEM-768 first; it is often a configuration change.
2. 2Long-lived, high-value authorities. Program upgrade authorities, treasury multisigs and mint authorities. Make sure each can be rotated, and rehearse the rotation.
3. 3Hard-coded size assumptions in formats you publish or persist. These are cheap to fix now and expensive once other people depend on them.
4. 4User wallet keys. Largely dependent on protocol and wallet support; prepare your app to accept new account types rather than trying to lead.

Step 3 — Prototype#

Build a thin end-to-end prototype with real post-quantum primitives before committing to a design: sign with ML-DSA through your signer interface, store the tagged key and signature, verify them, and run your test suite against the larger sizes. The goal is to discover where your system breaks — buffer sizes, database columns, QR codes, URL lengths, hardware-wallet screens, log redaction — not to ship.

Use maintained, published implementations of FIPS 203, 204 and 205 rather than writing your own, and record which version and parameter set you used. The Lab is a quick way to see real key and signature sizes and relative timings in a browser before you wire anything up. Anything that leaves the prototype stage needs an independent security review.

Step 4 — Dual-sign#

During a transition, a hybrid or composite signature signs the same message with both a classical and a post-quantum key, and the verifier requires both to pass. If either scheme turns out to be weak — a quantum break of Ed25519, or an unexpected flaw or implementation bug in ML-DSA — the other still protects you. The price is carrying both keys and both signatures.

• Bind the pair. Sign a message that includes both public keys and a scheme identifier, so an attacker cannot strip one signature and present the other in a different context. ML-DSA's context string helps with domain separation.
• Verify both, always. A verifier that accepts "either" gives you the security of the weaker scheme.
• Where to do it on Solana today. Off-chain flows you control (sign-in messages, API requests, attestations, software release signing) can dual-sign now. On-chain transaction authorisation cannot, because the protocol verifies Ed25519 signers only (chapter 04).
• Plan the exit. Dual-signing is a bridge. Decide in advance what evidence will let you retire the classical half.

Step 5 — Cut over#

Cut-over means new keys are post-quantum by default, old keys are rotated, and classical-only verification is switched off. For assets, "rotated" means moved: on Solana, funds controlled by an Ed25519 keypair stay exposed until they are transferred to an account whose authority is post-quantum. That requires a destination that the protocol, or your program, can protect with a post-quantum check.

Run cut-over as a staged rollout with metrics: what share of active keys have rotated, which clients still send classical-only signatures, and how many dormant accounts remain. Dormant accounts are the hard tail. Their owners may never return, and nothing on-chain can rotate a key on the owner's behalf without the owner's signature.

Standards bodies give useful outside anchors for internal deadlines. NIST's draft transition report (IR 8547) proposes deprecating quantum-vulnerable public-key algorithms for US federal systems over roughly the next decade. Those are policy targets for a specific audience, not forecasts of when attacks become possible, but they are a reasonable benchmark for "too late".

Wallet key management#

Wallets are where the migration is most visible to users. Today a Solana wallet derives Ed25519 keys deterministically from a seed phrase, and an address is a 32-byte public key that fits on a screen and in a QR code. Post-quantum keys change several assumptions:

• Derivation. ML-DSA and ML-KEM key generation is defined from short seeds, so deterministic derivation from existing secret material is technically straightforward. What is missing is an agreed standard for how wallets should derive them, including domain separation from existing Ed25519 paths. Avoid inventing a scheme that users' future wallets cannot reproduce.
• Storage. Expanded ML-DSA private keys are kilobytes; store the 32-byte seed where possible and expand on use.
• Hardware wallets. Secure elements have limited memory and display. Larger keys, slower signing and multi-kilobyte signatures need firmware and transport support.
• Identifiers. A 1,312-to-2,592-byte public key cannot be the address. Expect addresses to become commitments (hashes) to keys, with the key revealed on use.
• Recovery. Backup and recovery flows must restore both classical and post-quantum keys, and social or multisig recovery must be able to authorise moves into post-quantum accounts.

For app builders the practical stance is to stay compatible, not to lead: avoid assuming a key type or size in your UI and data model, display addresses through one formatting helper, and be ready to accept new account types when wallets and the protocol support them.

Measure where you are#

The Readiness check turns this chapter into fourteen questions across signatures, key management, data-at-rest exposure, protocol agility and migration planning, and returns a per-category score. Use it to start the inventory conversation with your team, then come back to it as you work through the steps. It is a self-assessment, not an audit.