Designing for the swap: crypto-agility and a migration plan

Most migration pain comes from assumptions baked in long ago: a 64 in a buffer size, a 32-byte key column, a message format with no version field. Agility means removing those assumptions before you need to.

type Alg = "ed25519" | "ml-dsa-44" | "ml-dsa-65" | "slh-dsa-sha2-128s";

interface Signer {
  alg: Alg;
  publicKey(): Uint8Array;              // never assume 32 bytes
  sign(msg: Uint8Array): Promise<Uint8Array>;  // never assume 64 bytes
}

type SignedBlob = {
  v: 2;                // versioned format
  alg: Alg;            // stored with the signature, not implied
  pk: Uint8Array;
  sig: Uint8Array;
  body: Uint8Array;
};

• Route all signing and verification through one interface. Any direct call to a curve library is a place you will have to find later.
• Store an algorithm identifier next to every key and signature.
• Size buffers, database columns and message limits for kilobytes.
• Add a test “fat signer” that emits 5 KB signatures, and run your suite with it to find hidden size limits.

1. Map. List every key, signature and handshake: what it protects, where it lives, who holds it and how long it stays valid. Include off-chain services and third-party dependencies.

2. Rank. Order the list by lifetime times value. Michele Mosca's rule of thumb is useful here: if the time the data must stay safe plus the time your migration takes is longer than the time until a capable machine exists, you are already late.

3. Rehearse. Take one path and make it work end to end with ML-DSA or ML-KEM in a test build. Measure sizes, latency and failures. This turns guesses into numbers.

4. Run both. Deploy hybrid key exchange and dual signatures in production while keeping the classical path working.

5. Retire. Require the post-quantum path, rotate the old keys out and remove classical-only code. Write down what changed so the next swap is easier.

During a transition, a message carries both an Ed25519 signature and an ML-DSA signature, and verifiers check both. The order of the rollout matters more than the format:

• Verifiers first: ship code that accepts and checks the new signature when present.
• Signers second: start emitting both signatures once enough verifiers understand them.
• Require last: reject messages without the post-quantum signature only when every signer has moved.

The IETF is standardising “composite” signatures for certificates on the same idea. For your own off-chain protocols, a simple versioned envelope with both signatures is usually enough.

Solana wallets derive Ed25519 keys from a BIP-39 seed along SLIP-0010 paths such as m/44'/501'/0'/0'. ML-DSA key generation also starts from a 32-byte seed, so a wallet could derive post-quantum keys from the same master secret with a separate, clearly labelled derivation step. No standard path exists yet. Avoid inventing one in production, because users would be locked into your wallet.

Hardware wallets face real constraints: limited memory for 2–4 KB signatures, and secure elements that may not support ML-DSA yet. Encrypted cloud backups of seeds are the harvest-now risk from chapter 03, and they should move to hybrid encryption early.

• Known-answer tests against NIST's published vectors for every scheme you ship.
• Round-trip and tamper tests: a signature must verify, and an edited message must fail. The Lab runs the toy version of this.
• Size-limit tests along every path a key or signature travels, including logs, queues and databases.
• A performance budget per endpoint, measured on your slowest supported device.

Start from lifetimes. Anything that must stay secret past the mid-2030s should already travel under hybrid key exchange. Signing roots with long lives (treasuries, upgrade authorities, validator withdraw keys) should be movable well before then, which means designing that move now. NIST IR 8547's proposed dates, deprecation after 2030 and disallowance after 2035, make a reasonable outer bound.