aere-docs/README.md

# aere-docs

The honest engineering and research documentation set for Aere Network.

This repository is the written half of the Aere Network "verify yourself" core. It collects the
protocol specification, the engineering and security spec, the EIP compatibility matrix, the
post-quantum cryptography and governance documents, the STARK verifier port specifications (with
their explicit caveats), the formal verification coverage reports, the reproducible-build and
cross-client determinism documents, and the reproducibility manifest.

## Scope, stated up front

Aere Network runs post-quantum signature verification natively on mainnet: Falcon-512 (`0x0AE1`),
Falcon-1024 (`0x0AE2`), ML-DSA-44 (`0x0AE3`), SLH-DSA-128s (`0x0AE4`) and SHAKE256 (`0x0AE5`)
have been live as precompiles since the AerePQC fork, `activationTime` 1783820272, whose first
block at or after that timestamp is 9,189,161. You can call them yourself against
`https://rpc.aere.network` without asking us for anything. Start with
`{"jsonrpc":"2.0","id":1,"method":"eth_config","params":[]}`, which returns that activation time and
the live precompile list straight from the node. Note that block 9,189,161 itself contains no
transactions, because a fork activation is a configuration change and not a transaction, so it is
not the place to look for evidence. The proof that the precompiles are running is a gas measurement
at `latest`, set out in `DOVADA-PQC-VERIFICABILA-2026-07-20.md`.

**Consensus on chain 2800 is classical secp256k1 ECDSA QBFT on every block, with a post-quantum
checkpoint every 32 blocks.** Since block 13,014,000 anchor blocks carry, under the block hash, a
certificate of validator Falcon-512 seals, and since 2026-08-14 a node rejects an anchor block with
fewer than three valid seals (f+1 of nine, not a quorum; eight or nine are carried in practice). That
checkpoint lives in the aere-node repository (patch 0003 and `anchor/`), not in this one: nothing in
this repository makes consensus post-quantum, and the chain is not "post-quantum consensus" without
that qualification (the per-block quorum claim published on 2026-08-15 was withdrawn on 2026-08-19).

Two further limits worth knowing before you judge anything else here:

- `0x0AE6` (ML-KEM-768) and `0x0AE7` (Falcon HashToPoint) are **testnet only**. They are not
  active on mainnet.
- The on-chain zero-knowledge verifiers are classical BN254. They are broken by Shor's algorithm
  like any other elliptic-curve construction, and we do not describe them as quantum-safe.

The network is operated by nine Foundation-run validators (f=2, commit quorum 6 of 9; seven until
2026-08-09), so its Nakamoto coefficient is effectively one today. That is a real limitation, it is on the roadmap, and it is not fixed by any
code in this repository.

## Which citations you can follow, and which you cannot

Read this before you try to follow a citation, because it limits the "verify yourself" promise and
you should hear it from us rather than discover it.

**How a citation resolves.** Paths are written relative to a side-by-side checkout of the published
Aere repositories, so a resolvable path begins with a repository name, for example
`aere-contracts/contracts/pqc/AereCryptoRegistry.sol`. Paths written relative to the document you
are reading also resolve. Nothing else does.

**What was wrong until 2026-08-03.** Many documents supported a claim with a path beginning
`aerenew/`, which is the larger private working tree these repositories were split out of. An
earlier version of this section stated that there were 270 such paths and that none of them resolved
in any public repository. The second half of that was wrong, and wrong in the direction that
understated us: MEASURED on 2026-08-03, 228 of those citations named a file that **is** published,
merely under its private path. They have been rewritten to the published path and you can now open
them. No citation was deleted.

**What remains.** MEASURED on 2026-08-11, 365 distinct cited paths across the four repositories
still do not resolve to any published file, 259 of them in this repository. Every one of them is
listed, with the documents that cite it, in `CITATIONS-UNRESOLVED.md`. That file is generated and
enforced: a citation that stops resolving and is not listed there fails our check, and a listed path
that is no longer cited fails it too, so the list cannot quietly rot.

This paragraph said 344 and 244 until 2026-08-11, measured on 2026-08-03. It was left behind by
documents added after that date, and the check caught it: seven newly cited paths did not resolve
and were not declared. The count is written here by hand, so it can drift from the generated file;
when the two disagree, `CITATIONS-UNRESOLVED.md` is the measurement and this sentence is the stale
copy.

A citation is a promise that a claim is checkable. Where the target is not published, the claim is
**traceable but not independently verifiable**, and it should be read as our assertion rather than
as something you can confirm. Triaging the remaining 365 into "publish the source", "mark
permanently private" and "withdraw the claim" is outstanding work.

What IS independently checkable, with no reference to the private tree: everything served by the
public RPC (precompile behaviour, contract bytecode, balances, block data), everything in the
published contract and node sources, and every test in `aere-contracts`. The
`AERE-NIST-VALIDATION-STATUS.md:87` disclosure, which states plainly that the KAT harness source
and vector files are not committed and that the NIST validation is therefore not reproducible from
the repository alone, is the pattern we intend to apply consistently.

## Start here

- `REPRODUCE.md` the single reproducibility manifest. It lists real paths, real commands, and
  real expected outputs so a third party can re-run the tests, the formal models, the KATs, and the
  benchmarks and get the same results. Every quantitative claim carries an honesty tag
  (`[FRESH]`, `[CITED]`, or `[MEASURE]`).
- `AERE-PROTOCOL-SPECIFICATION.md` the protocol specification.
- `AERE-ENGINEERING-SECURITY-SPEC.md` the engineering and security spec.
- `AERE-ARCHITECTURE-MAP.md` the architecture map.

## Contents

- Compatibility and validation: `AERE-EIP-COMPATIBILITY-MATRIX.md`,
  `AERE-NIST-VALIDATION-STATUS.md`, `AERE-CROSS-CLIENT-DETERMINISM.md`,
  `AERE-REPRODUCIBLE-BUILDS.md`, `AERE-BENCHMARK-REPORT.md`.
- Post-quantum: `AERE-POST-QUANTUM-GOVERNANCE.md`, `AERE-QUANTUM-SAFE-NETWORKING.md`,
  `AERE-QUANTUM-MIGRATION*.md`, `AERE-PQ-*.md`, `AERE-XMSS-*.md`, `AIP-PQ-TX-2026-07-18.md`.
- STARK verifier port: the `AERE-STARK-*.md` series, including
  `AERE-STARK-DOC-CAVEAT-SWEEP.md` which records the Hypercube and other caveats plainly.
- Formal verification: `AERE-CERTORA-FORMAL-VERIFICATION.md`, `AERE-TLA-FORMAL-SPEC.md`,
  `AERE-FORMAL-FINAL-COVERAGE.md`, `AERE-FORMAL-BROADEN-REPORT.md`,
  `AERE-FORMAL-EXTENSION-MONEY-CONTRACTS.md`, `AERE-FAULT-INJECTION-HARNESS.md`.
- Security review: `AERE-SECURITY-REVIEW-NEW-CONTRACTS.md`, `AERE-SECURITY-FIXES.md`.
- Process and delivery: `AERE-AIP-PROCESS-AND-INDEX.md`, `AERE-NEW-CONTRACTS-DEPLOY-RUNBOOK.md`,
  `AERE-DEPLOY-RUNBOOK-SUMMARY.md`, `AERE-BUILD-LOOP-SUMMARY-2026-07-19.md`.

## What is deliberately not here

Internal operations material, business and press strategy, infrastructure runbooks that name
hosts, funding and cost documents, and the mainnet-activation and node-provisioning runbooks are
intentionally excluded. Infrastructure IP addresses and host identifiers that appeared in a few
in-scope documents were redacted before staging.

## License

Documentation is provided under MIT. See `LICENSE`.