dd1410c266
The published line and the local line of this repository had no common ancestor: the public one carried the hygiene pass (no host names, no internal paths), the local one carried a month of corrections that never shipped. This commit ports the local work onto the public line, keeping the public hygiene wording wherever the two touched the same sentence, and keeping the public version of AERE-CROSS-CLIENT-DETERMINISM.md entirely. Carried: LICENSE/LICENSING corrections, VERIFY-POLICY.md, CITATIONS-UNRESOLVED.md remeasured 2026-08-11, the 'audited' adjective removed from next to Bouncy Castle, citation paths rewritten to published form, AIP-8, the QA consolidation report, the second EIP validation pass, fork-height corrections, the AereSink / threshold-factory correction, the forge test floor, and the architecture-map updates.
119 lines
7.2 KiB
Markdown
119 lines
7.2 KiB
Markdown
# 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.** The post-quantum work lives at the
|
|
signature, precompile, account and transport layers. Nothing in this repository makes the consensus
|
|
post-quantum, and nothing in it should be read as claiming so. Where you see post-quantum consensus
|
|
discussed, it is research about what a future activation could look like, not a description of the
|
|
running chain.
|
|
|
|
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 seven Foundation-run validators, 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`.
|