aere-docs/AERE-XMSS-CIRCUIT-CORE-SUMMARY.md

# Post-Quantum Finality Certificate (#4): XMSS aggregation circuit, verification core

> **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.)

Date: 2026-07-19

## What was asked

Advance the research core of Aere Network's Post-Quantum Finality Certificate: the
off-chain XMSS/leanSig aggregation circuit that a zkVM would run to prove a quorum of
validators hash-based-signed a block. Implement the tractable, independently-testable
VERIFICATION CORE now (validated against real vectors) and specify the rest as design.
Never claim the aggregation proof works end to end.

## What was found (grounding)

- OFFICIAL RFC 8391 XMSS-SHA2_10_256 known-answer vector already committed at
  `aere-contracts/test/fixtures/xmss-sha2_10_256-kat.json`
  (github.com/XMSS/xmss-reference, oid=1, idx=512, msg=0x25, pubRoot 0x9d898033...c3483).
- Deployed on-chain XMSS verifier + independent JS oracle:
  `contracts/contracts/pqc/AereXmssVerifier.sol`, `contracts/test/xmssVerifier.test.js`.
- SP1 guest style is a clean "pure-Rust core crate + thin no_main guest + std test"
  split (`aerenew/zk-light-client/qbft-finality` + `guest`), sha2/k256 SP1-patched.
- On-chain public-values layout (192 bytes, 6 words) and quorum rule read from
  `contracts/contracts/pqfinality/AereFinalityCertificateVerifier.sol`:
  abi.encode(bytes32 blockHash, uint256 blockHeight, bytes32 validatorSetRoot,
  uint256 validatorSetSize, uint256 quorumCount, bytes32 attestationDomain);
  threshold `_quorumThreshold(n) = (2n+2)/3 = ceil(2N/3)`.
- Committee commitment (registry-defined, flat keccak):
  leaf_i = keccak256(abi.encode(validator_i, keyEpoch_i, keyHash_i)),
  keyHash_i = keccak256(pubKey_i), root = keccak256(abi.encode(leaves)).
- Attestation message: attestationDomain = keccak256(abi.encode(DOMAIN_PREFIX, chainId,
  registry)); M = keccak256(abi.encode(attestationDomain, blockHash, blockHeight)).

## What was built (IMPLEMENTED + TESTED)

Dir: `aerenew/pqc-fork/pq-finality-circuit/`
- `xmss-verify-core/` Rust crate, ZERO external deps, `no_std`, allocation-free,
  float-free, hash-only, deterministic (models the aggregation guest's per-validator
  inner logic):
  - `aere-research/pq-finality-circuit/xmss-verify-core/src/sha256.rs` dependency-free SHA-256 (FIPS 180-4). Note: production SP1 guest
    swaps in the SP1-patched `sha2` precompile; identical bytes.
  - `aere-research/pq-finality-circuit/xmss-verify-core/src/xmss.rs` RFC 8391 XMSS-SHA2_10_256 verify core: chain_lengths, WOTS_PKFromSig,
    L-tree, compute_root, xmss_recover_root, xmss_verify. Byte-for-byte model of the
    on-chain AereXmssVerifier.sol / JS oracle.
  - `aere-research/pq-finality-circuit/xmss-verify-core/src/vectors.rs` official vector, GENERATED from the committed KAT (provenance,
    no hand transcription).
  - `aere-research/pq-finality-circuit/xmss-verify-core/tests/kat.rs` known-answer validation.
- `aere-research/pq-finality-circuit/scripts/gen_vectors.mjs` regenerates vectors.rs from the committed JSON.
- `README.md`.

## REAL vector-test result (run, not asserted from memory)

`cargo test --offline` in `xmss-verify-core/`: 12 passed, 0 failed.
- recovers_the_official_reference_root: OK (recovers pubRoot 0x9d898033...c3483)
- accepts_the_official_reference_signature: OK
- rejects tampered: wots value, wots tail/checksum, auth node, message, leaf index,
  wrong claimed root, tampered R randomizer: all fail to verify (OK)
- sha256 self-checks vs FIPS 180-4 ("abc", ""): OK
- chain_lengths checksum shape: OK

## Design doc written

`aerenew/docs/AERE-XMSS-AGGREGATION-CIRCUIT.md`:
- Full aggregation-circuit design: per validator recover XMSS root, recompute the
  registry committee commitment (membership), verify each attestation, structural
  distinctness, count >= ceil(2N/3), emit the exact 192-byte public values bound to the
  on-chain verifier; message + domain binding spelled out.
- Scheme choice + tradeoff: WOTS+/XMSS (standardized RFC 8391, most conservative,
  matches on-chain verifier, one-time/few-time so rotation required, which
  AerePQAttestationKeyRegistry already models; SHA-256 expensive in-circuit) vs
  leanSig/Poseidon2 (SP1/STARK-native field, dramatically cheaper + scalable, but newer
  and hashing story diverges from the deployed SHA-256 verifier); SLH-DSA stateless
  alternative; ML-DSA is lattice not hash-based (out of scope for the hash-only claim).
- Structural cost table (derivable): ~3320 SHA-256 calls per validator worst case,
  ~23k for N=7.
- Effort estimate: several weeks specialist work + audit for the full guest + proving.
- Honest status labels throughout.

## HONESTY flags

- [MEASURE] / NOT implemented: the zkVM aggregation guest, SP1 proving pipeline,
  end-to-end certificate, cycle counts, proving latency/memory, real-gateway verify gas,
  native-STARK vs Groth16-wrap decision.
- [VERIFY]: exact Solidity `abi.encode` framing the guest must reproduce for the
  committee commitment (address/uint32 left-padding to 96-byte leaf pre-image; the
  bytes32[] ABI head of a 0x20 offset word + N length word before the leaves). Flagged
  in the doc; to be matched against the deployed registry when the guest is built.
- Verification core is REAL + tested against the official vector (above).

## On-chain side

UNCHANGED. AereFinalityCertificateVerifier.sol and AerePQAttestationKeyRegistry.sol were
only Read, never modified; their tests untouched. Still fail-closed: no certificate can
pass the real gateway until a real guest + real proof exist.

## Scope boundary held

Additive PQ finality attestation only. Base QBFT consensus is still classical ECDSA;
this does not flip it. PQ finality is NOT live end to end.