# spec-31: Aere Quantum Migration Toolkit

> **Note added 2026-09-24 (consensus).** Where this document says that consensus is classical secp256k1 ECDSA and not post-quantum, read it as the per-block finality statement it was until block 24,300,000 (AIP-22 stage 4, 2026-10-25). Since that block every validator attributes a consensus vote only through its verified post-quantum seal, and a block is post-quantum final once the next anchor, at most 32 blocks later, carries the certificate that covers it; headers still carry classical ECDSA commit seals until AIP-22 stage 5 (this sentence corrected on 2026-10-25). It no longer describes all of consensus on chain 2800: since 2026-08-14 every anchor block must carry a certificate of validator post-quantum seals under its hash (Falcon-512, with SLH-DSA as well since 2026-09-04), and since 2026-09-05 (block 17,250,000) the nine AERE-client validators (nine of the ten) refuse a commit message without a valid Falcon-512 seal of its author, and since 2026-09-08 (block 17,700,000) any QBFT consensus message without one, while the tenth, the second client, enforced that seal only on commit messages until block 24,300,000 and attributes every consensus message only through it since (this clause corrected on 2026-10-12, 2026-10-25 and 2026-10-28; until 2026-10-28 it dated the refusal of every message type to 2026-09-05, the date of the commit layer alone). (Note applied to this document on 2026-10-28.)

Status date: 2026-07-19
Location: `aerenew/pqc-migration-toolkit/`
Runtime: pure Node built-ins (Node 18+), zero runtime dependencies.

## What it is

A real, runnable toolkit that helps anyone assess and migrate an EVM account
toward post-quantum readiness on Aere Network (chain 2800) or any EVM chain via
RPC. It extends Aere's internal account-migration work outward into a usable
tool. Three parts plus a self-test and a README.

## The four deliverables

1. PQC-readiness scanner, `scan.js`. Given an EVM address, detects EOA vs
   contract, and for contracts scans bytecode for quantum-vulnerable signature
   primitives (ecrecover 0x01, P-256 0x100) versus Aere's live post-quantum
   precompiles (0x0AE1..0x0AE5). Outputs RED (classical-only), YELLOW (hybrid),
   GREEN (PQC-capable). Runnable: `node scan.js <address> --rpc <url>`, plus
   offline `--bytecode 0x..` and `--fixture <name>` paths.

2. Migration SDK, `pqc-migration-toolkit/lib/migrate.js` + `plan.js`. CREATE2 address derivation
   mirroring `AerePQCAccountFactory.predictAddress`, calldata builders for
   `createAccount` (PQC account) and `registerIdentity` (hybrid ECDSA+Falcon),
   and a step-by-step migration plan over Aere's existing live primitives
   (AerePQCAccount/Factory, AereHybridAuth, AerePQCKeyRegistry, EIP-7702).

3. Migration cost simulator, `simulate.js`. Estimates migration gas from the
   MEASURED PQC verify costs (Falcon-512 86,336 verify-and-record tx / 40,000
   marginal; hybrid 89,336 / 43,000; Falcon-1024 145,496; ML-DSA-44 351,050;
   SLH-DSA-128s 558,276), plus the CREATE2 deploy (1,493,084) and the deployed
   Solidity-verifier path (~10.5M), at the 1 Gwei floor.

4. README, `README.md`. Honest positioning: Aere is the post-quantum EVM L1
   (five live NIST PQC precompiles + a live Falcon-owned account and factory), so
   it is the natural home for PQC migration tooling. This is a STARTING toolkit,
   not a finished product.

## How the scanner is genuinely honest (not a grep)

- Opcode-aware decoding: walks the instruction stream skipping PUSH immediates,
  so a matched constant is a real push (a naive `610ae1` substring search
  false-positives).
- Local stack simulation: for every CALL/STATICCALL/DELEGATECALL/CALLCODE it
  recovers the address argument (2nd stack item) per basic block, so it flags an
  actual call to 0x0AE1 rather than the number 0x0AE5 used as a memory length.
  An earlier proximity-only version misread AereHybridAuth as YELLOW for exactly
  that reason; the stack-simulation version reads it RED correctly.
- Signature-verify addresses 0x0AE1..0x0AE4 are distinctive, so a bare push is a
  medium-confidence fallback. The common literals 0x01, 0x100, 0x0AE5 count only
  when resolved as an actual CALL target.

## What actually ran (real results, this session)

`node selftest.js` (no network) ALL PASS:
- keccak256("") == c5d2460186f7233c... (zero-dep keccak is correct).
- predictPqcAccountAddress re-derived the LIVE sample AerePQCAccount address
  0xa42a5e7F72E46BadC11367650Ec34D676194326f from its real 897-byte Falcon key
  (CREATE2 math byte-correct vs a real deployment).
- Scanner on 4 REAL bytecode fixtures: AerePQCAttestation GREEN, AerePQCTxAccount
  GREEN, AereHybridAuth RED (Solidity-verifier scope limit), AereFalcon512Verifier
  RED (0x0100 are literals). Synthetic hybrid YELLOW; empty code RED (EOA).

Live against https://rpc.aere.network (the --rpc path is NOT [MEASURE]; it ran):
- AerePQCAttestation 0x465d... => GREEN, chainId 2800, 4402 bytes (matches fixture).
- Foundation EOA 0x0243... => RED, 0 bytes of code.
- createAccount(bytes,uint256) selector 0x0fd8377b computed by the zero-dep
  keccak is present in the live factory's deployed bytecode.

## Scope boundary (restated in tool output)

Migrating account authentication to a PQC scheme does NOT make Aere consensus
post-quantum. Mainnet 2800 still seals blocks with classical secp256k1 QBFT, and
the ZK verifiers (BN254 Groth16) are classical.

## [VERIFY] / [MEASURE] flags carried

- [VERIFY] AereHybridAuth is repo source only; no mainnet address in the address
  book as of 2026-07-19, so the hybrid path's deploy step is founder/deployer
  gated (flagged in plan output).
- [VERIFY] Scanner cannot see Falcon verification done via the SOLIDITY
  AereFalcon512Verifier (a contract call, not a precompile), so such contracts
  read RED; confirm auth paths against source.
- [VERIFY] ecrecover (0x01) is resolved by stack sim, but the literal 1 is
  common; a contract with no signature precompile call correctly reads RED.
- [VERIFY] Testnet-only precompiles 0x0AE6..0x0AE8 are not on mainnet 2800.
- [MEASURE] Only the live scan needs network; offline scans and the whole
  self-test run with no RPC.

## Founder-gated caveat

The AerePQCAccountFactory (0xd5315Ea7...CE58) is live and createAccount is
permissionless, so deploying a PQC account is possible today. Deploying NEW
contracts or a corrected V2 redeploy of an account factory is signed by the
Foundation/deployer key, not by this toolkit.

## Files

scan.js, plan.js, simulate.js, selftest.js, README.md, package.json,
lib/{keccak,bytecode,scanner,migrate,simulate,precompiles,rpc}.js,
fixtures/{AerePQCAttestation,AerePQCTxAccount,AereHybridAuth,AereFalcon512Verifier}.hex
+ fixtures/index.json (real deployed bytecode extracted from repo artifacts).