# pq-finality-circuit

The off-chain research core of the Aere Network Post-Quantum Finality Certificate
(research item #4).

## What is here

`xmss-verify-core/` is the IMPLEMENTED and TESTED per-validator VERIFICATION CORE: an
RFC 8391 XMSS-SHA2_10_256 hash-based signature verifier (WOTS+ one-time signature plus
the XMSS Merkle authentication-path check that recovers the root public key). It is the
exact inner computation the aggregation zkVM guest runs for each validator. It is
`no_std`, allocation-free, float-free, hash-only, deterministic, and has ZERO external
dependencies, so it tests fully offline.

It is validated against the OFFICIAL github.com/XMSS/xmss-reference known-answer vector
committed at `../../contracts/test/fixtures/xmss-sha2_10_256-kat.json`, the same vector
the deployed on-chain `AereXmssVerifier.sol` uses.

## Run the test

```
cd xmss-verify-core
cargo test --offline
```

Expected: 12 tests pass. The genuine official signature verifies (recovers the official
root); every tamper (WOTS+ value, checksum chain, auth node, message, leaf index,
claimed root, R randomizer) fails; and the bundled SHA-256 matches FIPS 180-4.

## Regenerate the test vector

```
node scripts/gen_vectors.mjs
```

Reads the committed official KAT JSON and rewrites `xmss-verify-core/src/vectors.rs`, so
the Rust vector is provably derived from the official fixture with no hand transcription.

## Honest scope

- IMPLEMENTED and TESTED: the verification core (this crate).
- NOT implemented, `[MEASURE]`, multi-week specialist work: the full zkVM aggregation
  guest, the SP1 proving pipeline, and the end-to-end certificate.
- UNCHANGED and fail-closed: the on-chain verifier and registry under
  `../../contracts/contracts/pqfinality/`.

This is the ADDITIVE post-quantum finality-attestation read path. Aere consensus stays
classical ECDSA QBFT. Post-quantum finality is NOT live end to end.

Full design and effort estimate: `../../docs/AERE-XMSS-AGGREGATION-CIRCUIT.md`.