771d637289
Some checks failed
contracts-ci / Install (lockfile) → compile → full test suite (push) Has been cancelled
contracts-ci / Ethereum interop (EIP-2537 BLS, prague hardfork) (push) Has been cancelled
contracts-ci / PQC known-answer tests (NIST vectors) (push) Has been cancelled
contracts-ci / Coverage (scoped, with artifacts) (push) Has been cancelled
164 lines
10 KiB
Markdown
164 lines
10 KiB
Markdown
# aere-contracts
|
|
|
|
Solidity smart contracts for Aere Network (chain ID 2800) and their Hardhat test suites.
|
|
|
|
This repository is part of the Aere Network "verify yourself" core. The deployed contract
|
|
bytecode is already public on-chain (readable via `eth_getCode` and the block explorer), so
|
|
publishing the source here lets anyone read, compile, and re-test the exact logic that runs on
|
|
mainnet. Nothing in this repository can move funds or impersonate the network: there are no
|
|
private keys, no mnemonics, and no deployment credentials. Every network account is supplied at
|
|
runtime through environment variables (see `hardhat.config.js`).
|
|
|
|
## Scope, stated up front
|
|
|
|
Aere Network runs post-quantum cryptography natively on mainnet: four signature verifiers,
|
|
Falcon-512 (`0x0AE1`), Falcon-1024 (`0x0AE2`), ML-DSA-44 (`0x0AE3`) and SLH-DSA-128s (`0x0AE4`),
|
|
and the SHAKE256 hash (`0x0AE5`) have been live as precompiles since block 9,189,161 (corrected
|
|
2026-10-28: this listed SHAKE256 among the signature verifiers). You can call them yourself against
|
|
`https://rpc.aere.network` without asking us for anything.
|
|
|
|
**Consensus on chain 2800 is QBFT with post-quantum layers on top of it, each dated
|
|
(headers are still admitted on their ECDSA commit seals until AIP-22 stage 5).** Since block 13,014,000 every
|
|
anchor block carries a certificate of validator post-quantum seals whose 32-byte digest sits under
|
|
the block hash (Falcon-512, with SLH-DSA-SHA2-128s as well since 2026-09-04, at every 128th block
|
|
since 2026-09-29; every anchor was 128 blocks apart from block 17,225,968 to block 20,746,736).
|
|
Since block 20,715,632 (2026-09-29) a node rejects an anchor block with fewer than seven valid
|
|
seals per scheme, as many as the quorum of the ten validators; the minimum was three (f+1 of nine,
|
|
not a quorum) from 2026-08-14 and six from 2026-08-21. Below block 24,148,752 (AIP-22 stage R,
|
|
2026-10-24) those seals proved that the validators signed the block, not that it was decided
|
|
(AIP-22 erratum of 2026-10-01); from that block a certificate that carries the quorum of one round
|
|
proves the decision. Every validator refuses a commit without a valid Falcon-512 seal of its
|
|
author, and since block 24,300,000 (AIP-22 stage 4, 2026-10-25) the Besu-derived validators, nine
|
|
of the ten, count a consensus vote only through the verified post-quantum seal of its author.
|
|
(Corrected 2026-10-28: until that date this paragraph opened by calling consensus on chain 2800
|
|
classical secp256k1 ECDSA QBFT on every block, and said without a date that the seals prove
|
|
signing, not decision.) 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 ten Foundation-run validators since 2026-09-11 (f=3, commit quorum 7
|
|
of 10; nine, with quorum 6 of 9, from 2026-08-09, and seven before; corrected 2026-10-28: this
|
|
said nine), nine of them on the Besu-derived client and the tenth, since 2026-09-11, on a second,
|
|
Nethermind-derived client that proposes and seals blocks, 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.
|
|
|
|
## Layout
|
|
|
|
- `contracts/` the Solidity sources, grouped by domain (pqc, pqfinality, settlement, lending,
|
|
governance, paymaster, oracle, mpc, zkverify, and more).
|
|
- `test/` the Hardhat test suites, including unit tests, fuzz/invariant/property tests, and the
|
|
cryptographic known-answer test (KAT) vectors under `test/fixtures/` and `test/*.json`.
|
|
- `hardhat.config.js` the compiler and network configuration. Keys and RPC URLs are read from
|
|
environment variables only; the sole literal mnemonic present is the well-known public Hardhat
|
|
default (`test test ... junk`) used for local test signers.
|
|
- `package.json` the dependency manifest.
|
|
|
|
### `contracts/pqc-evidence/`: on-chain equivocation evidence (AIP-22 section 6; added 2026-09-23)
|
|
|
|
`PqEquivocationEvidence` records, permanently and without any owner, that ONE validator row of a post-quantum registry epoch sealed
|
|
two different consensus messages of the same type for the same height and round. It proves the row into the registry hash pinned on
|
|
chain for the epoch in force (an 11-byte read-only getter, slot 0), rebuilds both signed pre-images exactly as the clients do, and
|
|
verifies both Falcon-512 seals through the chain's precompile at `0x0AE1`. `contracts/pqc-evidence/test/MockFalcon512.sol` is a
|
|
stand-in for that precompile used ONLY by the local tests (`test/evidence/`); real seals are checked against the live precompile.
|
|
`test/evidence/ExercitiuEchivoc.java` is the program that produced the drill seals below, with the clients' own signing code.
|
|
Measured on the public testnet 28001 on 2026-09-23, not on chain 2800: a drill instance recorded a PREPARE and a COMMIT equivocation
|
|
of drill keys (322,404 and 303,103 gas), and an instance for the testnet's own registry epochs proves the rows of the live epoch and
|
|
verifies live anchor seals through the contract. The procedure and the addresses are in the AIP-22 stage records (aere-research).
|
|
|
|
## Verify
|
|
|
|
```bash
|
|
npm ci # installs the exact locked dependency tree
|
|
npm run compile
|
|
npm test
|
|
```
|
|
|
|
`npm run` lists every entry point this repository offers. Until 2026-08-03 that
|
|
list was empty, because `package.json` carried no `scripts` key at all: `npm run`
|
|
answered with zero lines and exit code 0, which reads as "this project has nothing
|
|
to run" beside 155 test files. The available entries are now:
|
|
|
|
| Command | What it runs |
|
|
| --- | --- |
|
|
| `npm run compile` | `hardhat compile` |
|
|
| `npm test` | `hardhat test`, the whole suite |
|
|
| `npm run test:pqc` | the Falcon, SPHINCS+ and ML-DSA known-answer tests only |
|
|
| `npm run coverage` | coverage over the economic-core cluster, the one scope we measure |
|
|
| `npm run clean` | `hardhat clean` |
|
|
|
|
These are entry points, not claims of a green result. Read the next paragraphs
|
|
before quoting anything from them.
|
|
|
|
**MEASURED 2026-08-03 against this published tree, on Node v24.14.1 and npm
|
|
11.11.0: `npm test` aborts before a single test runs.** `test/shutter-mempool-v2.test.js`
|
|
and `test/shutter-mempool-v3.test.js` both `require('../scripts/shutter-crypto')`,
|
|
and `scripts/` is one of the directories deliberately excluded from publication, so
|
|
Mocha fails to load and the run ends with `MODULE_NOT_FOUND`. Placing that one helper
|
|
back into `scripts/` makes the suite load and start executing normally, which is how
|
|
the cause was confirmed rather than guessed. `npm run test:pqc` is unaffected and
|
|
passed 101 tests in 32 seconds on the same tree. Until the helper is either published
|
|
or the two suites stop depending on it, treat the full-suite result from this
|
|
repository as NOT MEASURED, not as passing and not as failing.
|
|
|
|
Use `npm ci`, not `npm install`. `ci` installs the exact tree recorded in
|
|
`package-lock.json` and fails if the lockfile and `package.json` disagree, so
|
|
you are running against the same dependency versions we measured. `install` is
|
|
free to resolve newer versions and will quietly give you a different tree.
|
|
|
|
Step-by-step instructions with the expected output at each step, the measured
|
|
pass and coverage numbers, and the required tool versions are in **`REPRODUCE.md`
|
|
in the `aere-docs` repository**, not in this one. An earlier version of this
|
|
paragraph referred to `REPRODUCE.md` as though it sat beside this README, which
|
|
would have sent a first-time reader looking for a file that is not here.
|
|
|
|
**Read that document before quoting any number from this repository**, because
|
|
two of the four CI jobs are currently RED and it says so explicitly: the full
|
|
test suite does not complete on a 16 GB machine, and the whole-repository
|
|
coverage figure is NOT MEASURED. Note that the first of those two reasons is
|
|
the one observed on our internal tree, which still has `scripts/`. On this
|
|
published tree the full suite fails earlier and for the different reason given
|
|
above, so memory is not the explanation a reader here should accept. Any "99.8% coverage" figure ever associated
|
|
with this project was never produced by a coverage tool.
|
|
|
|
The same three commands run on every push through the CI pipeline, which is a
|
|
pair of files:
|
|
|
|
- `.gitea/workflows/ci.yml` runs on git.aere.network, the canonical host.
|
|
- `.github/workflows/ci.yml` runs on GitHub mirrors.
|
|
|
|
Gitea Actions scans both directories and prefers `.gitea/`; GitHub scans only
|
|
`.github/`. The two files are identical except for the `upload-artifact`
|
|
version, and each file's header explains why they are split and records which
|
|
jobs are currently passing and failing.
|
|
|
|
To reproduce against the live chain, point `AERE_RPC_URL` at the public RPC
|
|
(`https://rpc.aere.network`, chain ID 2800) and compare compiled bytecode to the on-chain code.
|
|
The full reproducibility manifest lives in the `aere-docs` repository (`REPRODUCE.md`).
|
|
|
|
## Following citations in this repository
|
|
|
|
Paths cited in this repository are written relative to the document that cites them, or relative to
|
|
a side-by-side checkout of the published Aere repositories, in which case they begin with a
|
|
repository name such as `aere-docs/REPRODUCE.md`. MEASURED on 2026-08-03, every cited path in this
|
|
repository resolves to a published file: `CITATIONS-UNRESOLVED.md` is the enforced list of the ones
|
|
that do not, and it currently has zero entries. It is generated by a check, not maintained by hand,
|
|
so it cannot silently fall behind.
|
|
|
|
## What is deliberately not here
|
|
|
|
Deployment scripts, deploy keys, `.env` files, infrastructure configuration, and business or
|
|
operations material are intentionally excluded. This repository is source plus tests only.
|
|
|
|
## License
|
|
|
|
MIT. See `LICENSE`.
|