# spec-31: Aere Quantum Migration Toolkit

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, `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).