Republished from a clean root: the compiled artifact is gone from history, and the local line of work joins the sanitized public line

The public history carried kat/__pycache__/mlkem768_reference.cpython-314.pyc,
a compiled Python artifact embedding the operator's absolute local path. Text
secret scanners do not read compiled binaries, which is exactly how it slipped
through, and removing it from the tip would have left it reachable through the
old root commits. So this repository is republished from a single clean root.

This root also carries, from the previously unpublished line of work:
- corrected LICENSE year, LICENSING.md, VERIFY-POLICY.md, and
  CITATIONS-UNRESOLVED.md remeasured 2026-08-11 (101 paths, README aligned)
- O-018: run_consensus_verification.py ran 19 of 29 models and reported PASS;
  it now runs all 29, and computemarket_smt.py gains resolveByTimeout /
  reclaimUnsettled cases plus a negative control
- O-006: the word 'audited' removed from next to Bouncy Castle, twice, after a
  concurrent edit resurrected it
- O-014: prior art named and dated - Algorand's native falcon_verify shipped
  about ten months before AERE's precompiles; the primacy claim is withdrawn
  where it was implied
- bench/ scripts parametrized so they actually run for an outsider (the
  earlier textual sanitization left $STAGING unexpanded inside Python strings)
- AIP-2/AIP-3 errata with measured figures, spec remeasurements at 2026-08-01,
  and the spec-zk-stack retractions (owner is an operational key, not the
  Foundation; 'maximally sound' withdrawn; aggregator V1 deprecated)
The redacted bench-host environment files from the sanitized line are kept
exactly as published; the unredacted local variants are not carried.
This commit is contained in:
Aere Network committed 2026-08-15 13:52:14 +03:00
commit 6cb0140fae
177 files changed
+33777

No files matched your search

+300
View File
@@ -0,0 +1,300 @@
# AERE Account Abstraction and Onboarding Stack
**Chain:** AERE Network, chain ID 2800 (`0xAF0`)
**Consensus:** Hyperledger Besu QBFT, 0.5-second target blocks, sub-second finality, seven validators
**EVM ruleset:** Pectra (Prague/Cancun) plus Fusaka (Osaka), functional parity with Ethereum mainnet
**Source of truth for addresses:** `aerenew/sdk-js/src/addresses.ts`
**Contract source:** `aerenew/contracts/contracts/`
This document specifies the wallet and onboarding layer of AERE: passkey smart accounts, the ERC-4337 EntryPoint, the four gasless paymasters, EIP-7702 EOA delegation, the ERC-7579 modular account line, ERC-6551 token-bound accounts, and the post-quantum smart account. It states plainly what is live on mainnet 2800 today, what is source-complete but not yet deployed, which live contracts are deprecated and what replaced them, and where the current design has seams. Honesty about the seams is deliberate: this is an engineering reference, not marketing copy.
**Revised 2026-08-01.** Every address, code size and balance below was re-read from `https://rpc.aere.network` at head block 11,810,041. That pass found four claims in this document that the chain contradicted, in both directions: contracts described as unbuilt that are live (Section 6, Section 8), and contracts described as canonical that our own registry marks flawed (Section 2.1, Section 5). Each correction is stated in place, next to the sentence it corrects, rather than applied silently.
---
## 1. Substrate: what the chain gives the wallet layer
Two hardfork features do the heavy lifting for account abstraction on AERE.
**RIP-7951 secp256r1 (P-256) precompile at `0x100`.** Fusaka activated at unix `1780220351`, block `2,106,597`. From that block onward the P-256 verification precompile is unconditionally present at address `0x100`. It takes a 160 byte input (`msgHash || r || s || x || y`, five 32 byte words) and returns a 32 byte word whose low bit is set on a valid signature. The fixed cost is **6,900 gas**, measured live on chain 2800 on 2026-07-19 with a calibrated probe (flat across 0/160/161-byte input). Corrected from a previous "roughly 3,450 gas": 3,450 is the price in RIP-7212, the original Layer-2 spec, which RIP-7951 doubled to 6,900 when standardizing for mainnet while keeping the same address, input and output format. Compare roughly 250,000 gas for a pure-Solidity P-256 verification. This is what makes native passkey (WebAuthn) signatures affordable to check on chain, so a user's Face ID, Touch ID, Windows Hello, Android biometric, YubiKey, or EU Digital Identity Wallet key can directly authorize account operations with no seed phrase.
**EIP-7702 EOA delegation (Pectra).** An existing externally owned account can sign a 7702 authorization tuple that makes its account temporarily execute a designated contract's deployed bytecode, while remaining controlled by the original secp256k1 key. AERE uses this to upgrade a plain MetaMask style EOA into a batching, session-key, passkey-capable account without moving funds to a new address.
One substrate constraint shapes the account designs below. AERE's own EntryPoint keeps a strictly sequential, single-dimension per-sender nonce in its own storage (no 2D nonce keys of the kind canonical ERC-4337 v0.7 uses for validator routing). Accounts that want to route between multiple validators therefore cannot encode the route in a nonce key, and instead route on a signature prefix byte. This is called out explicitly in the modular account (Section 6).
---
## 2. Passkey smart accounts (live)
The passkey account is a smart contract wallet whose owner set can be WebAuthn P-256 keys, plain EOA keys, or a mix. It is the production onboarding path for "no seed phrase" users.
### 2.1 Components and addresses
| Component | Address (chain 2800) | Live code | Status |
|---|---|---|---|
| `AereEntryPointV2` | `0x8D6f40598d552fF0Cb358b6012cF4227B86aF770` | 3,127 B | Live |
| `AerePasskeyAccountFactoryV2Fixed` | `0x8FA2B45D63EBaa4551A55d7f33a82d597e423428` | 9,675 B | **Live, CANONICAL. Create new wallets here.** |
| `AerePasskeyAccountFactoryV2` | `0x5FFa9a6487DA4641a1A1e7900ff2bD4525D34fdA` | 9,722 B | **FLAWED. Do NOT create new wallets here.** |
| `AerePasskeyAccountFactory` (V1) | `0xfB0eF980667A79Fe1AB69c5f2d512118F1B30739` | 5,547 B | Legacy, retained for the original demo account |
**Correction of 2026-08-01, and it matters more than most.** An earlier revision of this spec listed `0x5FFa9a64…` as "Live (canonical)" in this table and again in the address appendix, and named no successor. The canonical registry begins that very entry with the word `FLAWED` and carries the line "Do NOT create new wallets here" immediately above it: the accounts that factory deploys carried an `ecrecover`-zero authorization bypass. A reader following the earlier revision would have created a wallet on the factory our own registry tells them to avoid. The corrected factory `AerePasskeyAccountFactoryV2Fixed` `0x8FA2B45D…` has been live with 9,675 bytes of code the whole time and appeared nowhere in this spec. Both facts are stated here rather than fixed silently, because the earlier text is what integrators were reading.
`0x5FFa9a64…` is left on chain and named here on purpose: wallets already minted from it exist, and their holders need to be able to find out what they are holding. Sample account minted by the corrected factory: `AerePasskeyAccountV2_sampleFixed` `0x7C599babc66c350A6cE76673868253e2288D75C1`, 8,430 bytes.
Source: `aere-contracts/contracts/passkey/AerePasskeyAccountV2.sol`, `MultiOwnable.sol`, `WebAuthn.sol`, `AerePasskeyAccountFactoryV2.sol`.
### 2.2 WebAuthn verification (`WebAuthn.sol`)
`WebAuthn.verify` is a precompile-only port adapted from Coinbase's `base-org/webauthn-sol` library. Given the 32 byte challenge, a `requireUV` flag, the parsed `WebAuthnAuth` assertion, and the public key `(x, y)`, it:
1. Rejects malleable signatures (`s > n/2`, guarding against the secp256r1 curve order half).
2. Confirms `clientDataJSON` contains `"type":"webauthn.get"` at the declared `typeIndex`.
3. Reconstructs `"challenge":"<base64url(challenge)>"` and confirms it appears at `challengeIndex`, binding the signed browser payload to the on-chain challenge.
4. Checks the authenticator data flags: User Present always, User Verified when `requireUV` is set (the passkey account passes `requireUV = true`, so a biometric or PIN gesture is required, not a bare presence tap).
5. Computes `sha256(authenticatorData || sha256(clientDataJSON))` and calls the `0x100` precompile.
The FreshCryptoLib fallback path present in the upstream library is stripped, because the precompile is guaranteed on AERE from the Fusaka block.
### 2.3 Ownership model (`MultiOwnable.sol`)
Owners are stored as raw bytes: 32 bytes for an EOA (a `uint160` address left-padded, top 12 bytes must be zero) or 64 bytes for a P-256 public key (`x || y`). Each owner has a monotonic index that is never reused. The authorization gate is a self-call check: `onlyOwner` requires `msg.sender == address(this)`. That means every owner-management action (add EOA owner, add passkey owner, remove owner) must arrive as an authenticated self-call through one of the account's execute paths. Any single registered owner can add or remove other owners, and the set can never be emptied (`removeOwnerAtIndex` reverts `LastOwner` at count 1).
This is the account's recovery model in its live form: keep at least one owner, and optionally pre-register a backup key (for example a hardware EOA) so loss of the primary passkey does not lose the account. A guardian-and-timelock recovery flow is a separate module, `AereSocialRecoveryModule` `0x077514DB…`, which is deployed on mainnet 2800 (Section 6) but is not part of the passkey account itself and is not wired into live passkey wallets.
### 2.4 Authorization paths (`AerePasskeyAccountV2.sol`)
The account exposes three ways to authorize a call, all resolving through the same `_verifyWrappedSignature` routine that selects the owner by index and dispatches to ECDSA recovery (EOA owners, EIP-191 personal_sign envelope, MetaMask compatible) or WebAuthn (passkey owners):
- **ERC-4337 path.** `validateUserOp` is callable only by the account's `entryPoint`. It verifies the wrapped signature over `userOpHash`, returns `0` on success or `1` (`SIG_VALIDATION_FAILED`) on failure per spec (it does not revert on a bad signature), and forwards any `missingAccountFunds` prefund to the EntryPoint. Execution is dispatched by `executeFromEntryPoint` / `executeBatchFromEntryPoint`, both EntryPoint-gated.
- **Direct passkey path.** `executeWithPasskey` / `executeBatchWithPasskey` let the Foundation relayer (or the user self-relaying) drive the account without a bundler. The signer signs a domain-separated `getExecuteChallenge` that binds `address(this)`, `block.chainid`, a monotonic `passkeyNonce`, and the call payload, giving replay protection independent of the EntryPoint nonce.
- **EIP-1271.** `isValidSignature` wraps the queried hash in an `AereAccount1271(address account,uint256 chainid,bytes32 hash)` digest before verifying, preventing cross-account signature replay. This makes the account usable with Permit2, OpenSea, Snapshot, and dapp login flows.
### 2.5 Deployment (`AerePasskeyAccountFactoryV2.sol`)
A CREATE2 factory. `predictAddress(initialOwners[], salt)` returns the counterfactual address; the initial owner set is mixed into the salt, so the same passkey with a different initial owner set produces a different address and multi-owner accounts cannot be front-run at their counterfactual address. `createAccount` is idempotent (returns the existing account if already deployed) and pins every new account to the factory's immutable `defaultEntryPoint`.
---
## 3. ERC-4337 EntryPoint (live) and an honest note on two EntryPoints
AERE ships two EntryPoint contracts, and the distinction matters for anyone integrating.
**`AereEntryPointV2`** at `0x8D6f40598d552fF0Cb358b6012cF4227B86aF770` (source `aere-contracts/contracts/passkey/AereEntryPointV2.sol`) is the account-facing EntryPoint. It implements the canonical `handleOps(PackedUserOperation[], beneficiary)` flow: a validation phase that calls `account.validateUserOp` for every op and reverts the whole batch on any non-zero return, then an execution phase that calls `sender.call(op.callData)`, meters gas, and charges the paymaster's deposit if `paymasterAndData` names one, else the account's own deposit. It computes the canonical v0.7 `userOpHash` (binding the op fields, `address(this)`, and `block.chainid`), keeps per-account deposits, and emits standard `UserOperationEvent` records so bundlers and indexers can subscribe. AERE hosts its own relayer while bootstrapping; the contract is shaped so external bundlers (Pimlico, Stackup, ZeroDev) can target it via per-chain config.
**`AereEntryPoint`** at `0x19773ba45287A64B05d0BCBD59D1371BF51Bd5D2` (source `aere-contracts/contracts/paymaster/AereEntryPoint.sol`) is a lightweight, paymaster-oriented EntryPoint from the Tier-1.3 stack. It implements the deposit and stake surface (`depositTo`, `balanceOf`, `withdrawTo`, `addStake`, `unlockStake`, `withdrawStake`) plus a `relayUserOp` that calls a paymaster's `validatePaymasterUserOp`, executes the sender call, and deducts the paymaster's deposit.
Two honest consequences of this split:
1. **The four paymasters bind to the staking-capable EntryPoint interface.** `PaymasterBase` (Section 4) declares an `IEntryPoint` with `addStake` / `unlockStake` / `withdrawStake`. `AereEntryPointV2` exposes deposit accounting but not staking, whereas the lightweight `AereEntryPoint` implements the full stake surface. The paymaster validation hook (`validatePaymasterUserOp`) is therefore exercised through the lightweight EntryPoint's `relayUserOp` path or through an off-chain relayer that calls the hook directly.
2. **`AereEntryPointV2.handleOps` charges a paymaster's deposit but does not itself call `validatePaymasterUserOp`.** It reads the paymaster address from `paymasterAndData[0:20]` and debits that deposit for `actualGasUsed * maxFee`, but the paymaster's own policy checks (per-sender caps, token pull, quota) are not invoked inside `handleOps`. Unifying paymaster validation into `handleOps` (so a single EntryPoint runs both account and paymaster validation in one batch) is a roadmap item. Until then, gasless sponsorship runs through the relayer-plus-lightweight-EntryPoint path where the hook is actually called.
Also note `handleOps` charges `actualGasUsed * maxFee` (the max fee, not an effective basefee-plus-tip price) and does not implement the full canonical prefund-and-refund economics. It is a compatible subset sufficient for the hosted relayer, not a byte-for-byte reimplementation of eth-infinitism v0.7.
---
## 4. The four gasless paymasters (live)
All four inherit `PaymasterBase` (`aere-contracts/contracts/paymaster/PaymasterBase.sol`), an in-house `Ownable` (OpenZeppelin v4.9) base that exposes `validatePaymasterUserOp` / `postOp` guarded by `onlyEntryPoint`, plus deposit and stake helpers. Each paymaster overrides `_validatePaymasterUserOp` with its own sponsorship policy. "Gasless" here means the user needs no native AERE: either the Foundation, a dApp, the user's stake, or an ERC-20 covers the gas.
### 4.1 Address map
| Paymaster | Address (chain 2800) | Status |
|---|---|---|
| `AereOnboardingPaymaster` | `0x4058E406475Dbed7056Aee0c808f293F05fEa879` | Live |
| `AereAppPaymasterFactory` | `0xEC22603E8712cBc5c31E53370D10f1a80CcB4DF0` | Live (permissionless factory) |
| `AereTokenPaymasterV2` | `0x217f56a5b0C7f35abe4D2fff924A6c13B85d7243` | Live (canonical) |
| `AereStakeQuotaPaymasterV2` | `0xE50464ca7E8E7F542D1816B3172a2330cFE384E8` | Live (canonical) |
| `AereTokenPaymaster` (V1) | `0xEb6e2Eb24e597C85392DdCD68a1F9b654FffdcB2` | Deprecated, do not use |
| `AereStakeQuotaPaymaster` (V1) | `0xD16C86D792444c2667A26dB62f01b90FC0DaB87b` | Deprecated, do not use |
### 4.2 `AereOnboardingPaymaster` (Foundation-funded)
The first-touch paymaster. It sponsors a hard-capped number of UserOps per address (`sponsoredOpsPerSender`, default 3, lifetime, never resets) under a sitewide per-UTC-day cap (`dailySitewideCap`, default 100) for Sybil resistance, with an optional target-contract whitelist. When its Foundation-funded balance drains it refuses all ops until a governance top-up. The design intent recorded in source is that 3 sponsored ops per address plus a sitewide daily cap lets a fixed, small AERE budget onboard a large number of first-time users without an automated refill.
### 4.3 `AereAppPaymaster` via `AereAppPaymasterFactory` (dApp-funded)
Any dApp calls `createPaymaster()` on the factory (no fee, permissionless) and becomes owner of its own `AereAppPaymaster`. The dApp funds it from its own treasury and sets a required target whitelist, an optional sender allowlist, and an optional per-sender lifetime cap. The Foundation contributes nothing. This is the standard pattern for a game, marketplace, or app to sponsor its own users' gas.
### 4.4 `AereTokenPaymasterV2` (pay gas in an ERC-20)
Lets a user pay for gas in any whitelisted ERC-20 rather than native AERE. It reads the token's USD price and the AERE/USD price from an oracle, converts the op's AERE cost to a token amount, applies a markup in basis points (`markupBps`, default 500 = 5%, capped at 3000), and pulls the tokens via `transferFrom` (the user pre-approves). V2 fixes a V1 medium-severity bug: V1's `withdrawToken` used `transferFrom(address(this), ...)`, which needs a self-allowance that never exists, permanently stranding collected token revenue; V2 uses `transfer`, the correct primitive for moving the contract's own balance, so the Foundation can sweep collected fees. Honest dependency: the paymaster's oracle reference is immutable and, per the registry, currently resolves to the legacy price source; repointing it to `AereOracleV2` requires a fresh paymaster deploy.
### 4.5 `AereStakeQuotaPaymasterV2` (stake AERE, get free transactions)
A Tron-style UX: a user's effective AERE stake buys a daily quota of sponsored UserOps (`quotaPerDay = stakedAERE * txPerKiloAerePerDay / 1000`, default 20 free ops per 1000 AERE staked, resetting each UTC day, no rollover). Effective stake is the sum of delegated stake across the validator set, the user's own validator self-stake, and active locked-staking positions. V2 fixes two confirmed high-severity liveness bugs in V1: V1 called a non-existent `balanceOf` on the real staking contract (so the delegated read always returned 0), and V1 decoded `AereLockedStaking.getLock` with the wrong field order (so any real lock hard-reverted validation and the user could never be sponsored). V2 reads the real public getters and aggregates them, matches the real `getLock` field order (amount first), bounds both scan loops at 100 entries so validation cannot be griefed out of gas, and wraps every external read in try/catch so a paused source degrades the quota to 0 rather than bricking validation. It reads the canonical `AereStakingV2` (`0x1D95eF6D17aeAB732dF914Ba2d018c270BC155FC`) and `AereLockedStaking` (`0x21108c28A849b05aE6b7a3a5bc435C9Bc897E7Ad`) getters.
---
## 5. EIP-7702 EOA delegation (live)
For users who already hold a MetaMask style EOA and do not want a new address, EIP-7702 lets that EOA point its delegation tuple at a shared implementation and gain smart-account behavior in place.
| Component | Address (chain 2800) | Live code | Status |
|---|---|---|---|
| `AereDelegate7702V2` | `0xC6d18e0Ce1B6467d952e31315505E0190a4A3310` | 4,535 B | **CANONICAL. Delegate here.** |
| `AereDelegate7702_v1_DEPRECATED_FLAWED` | `0x5673D92080efbd0987402E9335c14200d0a5EaeF` | 4,003 B | **DEPRECATED, two session-key scope escapes.** |
| `AereDelegationRegistry` | `0x6c25c07D134713b6C2F8E19D807423f022903D63` | 1,913 B | Live, informational only |
**Correction of 2026-08-01.** An earlier revision of this spec presented `0x5673D920…` as the live 7702 delegation target with no qualification, and did not mention `AereDelegate7702V2` at all. The canonical registry names `0x5673D920…` `AereDelegate7702_v1_DEPRECATED_FLAWED` for two confirmed session-key scope escapes, and `0xC6d18e0C…` has been live with 4,535 bytes of code the whole time. Worse, the earlier revision described the **defect itself as a feature**: it wrote that `addSessionKey` lets you "register a scoped secondary key with an expiry and a selector allowlist", which is precisely the too-narrow scoping model V2 exists to replace. A selector allowlist alone does not bound what a session key can move; that is the escape. The text below is retained for the V1 contract it describes, with that correction attached.
Because EIP-7702 transmits only code, re-pointing a delegation is a signature, not a migration. An EOA currently delegated to `0x5673D920…` should re-point to `0xC6d18e0C…`.
**`AereDelegate7702`** (`aere-contracts/contracts/delegation/AereDelegate7702.sol`) is the code an EOA delegates to. Because EIP-7702 transmits only code, not storage, every EOA delegating to this one implementation gets independent storage at its own account, and can re-point its delegation at any time with no migration. Its surface:
- `executeBatch(Call[])`: atomic multicall, authorized by the EOA's own transaction signature. The owner check is `msg.sender == address(this)`, which under 7702 is the EOA acting on itself. A transient reentrancy guard protects the batch path.
- `executeWithPasskey(Call, P256Signature)`: a single call authorized by a registered WebAuthn passkey, verified through the `0x100` precompile, with a relayer paying gas. A round-3 fix binds the signed `clientDataJSON` to the specific call by recomputing the expected challenge `keccak256(address(this), passkeyNonce, call)`, base64url-encoding it, and requiring the canonical `"challenge":"<expected>"` substring, which closes a replay hole where an unrelated WebAuthn login signature could have authorized arbitrary calls. A `passkeyNonce` gives replay protection.
- `addSessionKey` / `revokeSessionKey` / `executeWithSessionKey`: register a secondary key with an expiry and a **selector allowlist**, for low-risk, popup-free dApp flows, plus a kill switch. **Read this as the V1 design, not as a recommendation.** A selector allowlist constrains which functions a session key may call and does not constrain what it may move through them; that is one of the two scope escapes for which the canonical registry marks this contract deprecated. `AereDelegate7702V2` `0xC6d18e0C…` is the hardened replacement.
- `setPasskey(x, y)`: register one WebAuthn key. Phase 1 supports a single passkey; the source notes a Phase 2 extension to a MultiOwnable-style set is planned.
**`AereDelegationRegistry`** is a purely informational, permissionless index: an EOA self-registers (`register()`), the registry records the account's delegated code hash and timestamps, and dApps query it to render a "smart-wallet enabled" badge, discover batch-eligible EOAs, and coordinate paymaster eligibility. It holds no funds and has no authority over any account; wrong data only affects the registrant's own UX.
---
## 6. ERC-7579 modular accounts, session keys, social recovery (LIVE on mainnet 2800)
**Correction of 2026-08-01, and this is the largest one in this document.** An earlier revision of this section was headed "in development, not yet on mainnet" and said the modular account line was "not present in the canonical registry (`addresses.ts`) and is therefore not deployed to mainnet 2800", closing with "No mainnet address is cited because none exists yet."
**Every part of that is false.** All four contracts are in the canonical registry and all four carry live code, measured at head block 11,810,041 on `https://rpc.aere.network`:
| Component | Address (chain 2800) | Registry | Live code | Status |
|---|---|---|---|---|
| `AereModularAccountFactory` | `0xE3f45Ed4a81f982fF25ad172A72456a1833a440E` | `addresses.ts:378` | 6,271 B | Live |
| `AereSessionKeyValidatorV2` | `0xC06EAe63Ed12307F56A1506917C48C027D8852ff` | `addresses.ts:381` | 6,165 B | **Live, CANONICAL** |
| `AereSessionKeyValidator_v1_DEPRECATED` | `0x6e03A3D7A4c90d6f8dD6F0BA1F6e8aB1F8990D26` | `addresses.ts:380` | 4,698 B | **Deprecated, per-batch value-cap bypass** |
| `AereSocialRecoveryModule` | `0x077514DB2a85F239145537e8334CC99d42c9D812` | `addresses.ts:382` | 4,034 B | Live |
This was the single largest gap between what we shipped and what we said we shipped. It is recorded here rather than quietly corrected, because "in development" is a claim a reader makes decisions on.
Two things that were true in the earlier revision remain true and are not softened by the correction. These contracts have **no external security audit**, and their on-chain usage is thin. Being deployed is not being proven.
Source files: `aere-contracts/contracts/modular/AereModularAccount.sol`, `AereModularAccountFactory.sol`, `AereSessionKeyValidator.sol`, `AereSessionKeyValidatorV2.sol`, `AereSocialRecoveryModule.sol`.
**`AereModularAccount`** is an ERC-4337 account with ERC-7579-style pluggable modules of two types: validators (type 1, signature validation) and executors (type 2, may call `executeFromExecutor` and `setRootOwner`). It targets `AereEntryPointV2` exactly, and because that EntryPoint uses a single-dimension nonce, the account routes validation on the first signature byte: `0x00` selects the root-owner ECDSA fallback (`0x00 || 65-byte sig` over the EIP-191 envelope), `0x01` selects an installed validator module (`0x01 || 20-byte validator address || payload`). Validators return the canonical 4337 validation-data packing (`authorizer | validUntil<<160 | validAfter<<208`); since `AereEntryPointV2` reverts on any non-zero return and cannot unpack time bounds, the account unpacks the packing itself, enforces the time window against `block.timestamp`, and returns strictly `0` or `1`. It supports `execute` / `executeBatch`, EIP-1271 with the same domain-wrapping convention as the passkey account, and root-owner rotation gated to a self-call or an installed executor.
**`AereSessionKeyValidator` / `AereSessionKeyValidatorV2`** (ERC-7579 type 1) grant a session key a window (`validAfter`, `validUntil`), a per-op native value cap, and an allowlist of `(target, selector)` pairs, with `0x00000000` as the native-transfer sentinel. V2 is a hardened redeploy of the module logic that fixes a confirmed per-batch value-cap bypass (V1 checked each `executeBatch` sub-call's value independently against the per-op cap with no running sum, so a session key could move `maxValuePerOp * N` in one batch); V2 caps the sum of sub-call values, adds a defense-in-depth rule that a session key can never call account-admin selectors (`installModule`, `uninstallModule`, `setRootOwner`, `execute`, `executeBatch`) back into its own account regardless of the allowlist, and adds an optional rolling cumulative spend cap.
**`AereSocialRecoveryModule`** (ERC-7579 type 2 executor) is the guardian-based recovery the live passkey account lacks. An M-of-N guardian set, per account, drives an `initiateRecovery` then `supportRecovery` flow; after a 48 hour timelock and at least the threshold approvals, any guardian may `executeRecovery`, which calls `account.setRootOwner`. The current owner or the account can `cancelRecovery` at any time before execution. Guardian and threshold changes are owner-only (they require `msg.sender == account`).
When this line is audited and deployed, its addresses will be added to `addresses.ts` and this section updated to "live".
---
## 7. ERC-6551 token-bound accounts (live)
ERC-6551 gives every NFT its own wallet. These are account and registry primitives, not tokens: they mint nothing and have no supply.
| Component | Address (chain 2800) |
|---|---|
| `ERC6551Registry` | `0x7fFdA0AcDeB919938dB91dbEa779D841c833EF68` |
| `AereTokenBoundAccount` | `0xBc5e24180f3F75DC6b1965E4aaD3D4F184b6F9E2` |
**`ERC6551Registry`** (`aere-contracts/contracts/tokenbound/ERC6551Registry.sol`) is the verbatim `erc6551/reference` registry: a stateless, owner-less CREATE2 factory that deploys deterministic ERC-1167 minimal-proxy accounts bound to a `(chainId, tokenContract, tokenId)` tuple. The source notes the canonical public deployment lives at `0x000000006551c19487814612e58FE06813775758` on chains that received the deterministic Nick-factory deploy; on AERE the identical source was deployed at the address above (the address differs only because the deterministic factory salt was not replayed here, the bytecode and behavior are identical).
**`AereTokenBoundAccount`** (`aere-contracts/contracts/tokenbound/AereTokenBoundAccount.sol`) is the implementation the proxies point at. Its sole authority source is `ownerOf(tokenId)` on the bound ERC-721, read live. Whoever holds the NFT controls the account: they can `execute` arbitrary calls (operation 0, CALL only; DELEGATECALL and CREATE are rejected so the account can never be hijacked into changing its own logic), and the account produces EIP-1271 signatures on their behalf via OpenZeppelin `SignatureChecker` (so both EOA and smart-contract holders work). It also implements the ERC-4337 path against `AereEntryPointV2` (hardcoded as `ENTRY_POINT`), so a bundler or paymaster can sponsor the NFT wallet's gas. A live demo binds `AereNFT` (`0x3f9A9D9CAB005327869396C69bE226ef98039f1c`) token #1 to account `0x82D24cC4E09CaBfD9B00233438B8B6321CBC13Dd`.
---
## 8. Post-quantum smart account (live, roadmap #270)
The most experimental account in the stack, and the one whose scope needs the most careful statement. It is a working ERC-4337 v0.7 account whose sole owner is a NIST Falcon-512 lattice public key, with no classical ECDSA fallback.
| Component | Address (chain 2800) | Live code | Balance at head |
|---|---|---|---|
| `AerePQCAccountFactory` | `0xd5315Ea7caa60d320c4f34b1bEd70dd9cc02CE58` | 4,727 B | 0 AERE |
| `AerePQCAccount_sample` | `0xa42a5e7F72E46BadC11367650Ec34D676194326f` | 3,463 B | **0.03654 AERE** |
| `AereFalcon512Verifier` | `0x4E8e9682329e646784fB3bd01430aA4bA54D8fFC` | 7,333 B | 0 AERE |
**`AerePQCAccount_sample` is withdrawn as a reference example (2026-08-01).** An earlier revision presented `0xa42a5e7F…` as the account to look at when integrating. Two measured facts change that recommendation. First, it is not empty: it holds 0.03654 AERE at head, which makes it the only funded contract in this family apart from `AereEntryPointV2` (0.020438 AERE). Second, our internal audit records it as the one finding in this area that touches funds: on the deployed code the authorization path and the payment path are not separated, and the live factory still mints accounts with that same property. Neither the amount nor the mechanism makes this urgent, but a contract with a known unseparated authorization path and a non-zero balance is not a reference example, and this spec should not have been pointing integrators at it.
**NOT MEASURED, stated as such:** we did not reproduce a Falcon-512 signature against this account ourselves. Doing so would have meant running heavy proving work on live infrastructure. What is measured above is the balance and the code size; the audit finding is cited from the audit, not re-derived here.
**`AerePQCAccount`** (`aere-contracts/contracts/pqc/AerePQCAccount.sol`) owns exactly one Falcon-512 public key (897 bytes, NIST encoding, header byte `0x09`). Every authorization, a bundled UserOperation, an EIP-1271 check, or the direct `executeWithFalcon` path, is decided by the live on-chain `AereFalcon512Verifier`, which runs real lattice cryptography: SHAKE256 HashToPoint, 14-bit public-key decode, compressed-signature decode, negacyclic NTT multiply mod q=12289 in the ring, centering, and an l2-norm bound check. The signature envelope is `abi.encode(bytes nonce, bytes compSig)` (the 40-byte Falcon salt and the compressed s2 body); the message handed to the verifier is the raw 32 bytes of the relevant hash, which for a UserOperation is the userOpHash that already binds sender and chain. `validateUserOp` returns `0` or `1` per spec. `isValidSignature` is a `view`, so a post-quantum signature can be checked via `eth_call` without sending a transaction. An earlier revision presented that purely as an integration convenience. State it with its limit instead: a free `view` check tells you that a signature verifies against the key the contract holds, at the moment you ask. It is not an authorization, it writes nothing, and on this deployed code it is not separated from the payment path (see above). Treat it as a signature-verification oracle, not as a gate. `AerePQCAccountFactory` is a CREATE2 factory keyed on `(falconPubKey, salt)`, mirroring the passkey factory, binding each account to an immutable EntryPoint and Falcon verifier.
**Honest scope, stated exactly as the registry frames it.** This is Falcon-512 (NIST security level 1), not Falcon-1024. A Falcon-512 verify is heavy: roughly 10.5M gas per PQC authorization. That is real, and a full UserOperation through `AereEntryPointV2.handleOps` was demonstrated end to end with estimated 10,641,716 and measured 10,278,313 gas used, `opSuccess=true`. Those two figures are measured and stand.
**The comparison against a per-transaction cap is downgraded to NOT MEASURED.** An earlier revision asserted that the 10.5M figure "fits under the Fusaka EIP-7825 per-transaction cap of 2^24 = 16,777,216 gas". We have not confirmed that cap on the live chain. An `eth_call` carrying gas 0x2000000, which is 33,554,432 and therefore above the stated cap, succeeded without error, and `eth_estimateGas` does not discriminate. The only conclusive probe is a transaction above the cap, which we do not send. What we did measure is the header `gasLimit` at head, `0x1fffffffffffff` = 9,007,199,254,740,991, identical to genesis, so a 16,777,216 cap does not come from the block limit and cannot be inferred from it. The honest form of the claim is: the operation was executed on chain and succeeded, which is stronger evidence than a comparison against an unverified constant. A native SHAKE or keccak precompile would cut this sharply and is tracked as a separate roadmap item. PQC authorization here is app-layer and account-layer: it secures how this account authorizes operations. **It does not change consensus. AERE's validators sign classical secp256k1 ECDSA under QBFT. There is no post-quantum consensus on chain 2800 and this document never claims one.** That statement is not softened by anything below.
**The native PQC precompiles ARE live on mainnet 2800 (correction of 2026-08-01).** An earlier revision of this sentence said they "are proposed and in development on a scratch fork, not live on mainnet 2800". That is false, and provably so from any public RPC. They activated with the AerePQC fork at block 9,189,161: Falcon-512 at `0x0AE1`, Falcon-1024 at `0x0AE2`, ML-DSA-44 at `0x0AE3`, SLH-DSA-128s at `0x0AE4`, SHAKE256 at `0x0AE5`.
Verified directly rather than asserted. Calling `0x0AE5` with the documented framing, a 32-byte output-length word followed by the raw input bytes, returns for input `abc`:
```
0x483366601360a8771c6863080cc4114d8db44530f8f1e1ee4f94ea37e78b5739
```
and for empty input:
```
0x46b9dd2b0ba88d13233b3feb743eeb243fcd52ea62b81b82b50c27646ed5762f
```
Both match the FIPS 202 vectors exactly. A control call to `0x0AEF`, where no precompile exists, returns `0x`.
Two boundaries on that correction, and neither is optional. **`0x0AE6` and `0x0AE7` are TESTNET ONLY**; calling either on mainnet 2800 returns `0x`, which we measured, and no AERE document may present them as live on mainnet. And the gas cost of the Falcon-512 account path stated above is unchanged by the precompiles being live: a SHAKE precompile helps the hashing step, it does not make a 10.5M gas lattice authorization cheap. That remains a roadmap item. On the broader PQC verifier suite that this account draws on, we are not aware of any other public chain that verifies all of these on-chain; that is the claim, stated with that exact hedge, and nothing stronger. We are not the first public chain to verify a post-quantum signature on-chain, and we do not claim to be: Algorand shipped the native Falcon-1024 `falcon_verify` AVM opcode in a stable release roughly ten months before AERE's precompiles activated at block 9,189,161 (2026-07-12), and places Falcon deeper in its stack than AERE does, inside its own state proofs. That prior art, with sources and dates, is set out in `aere-research/research/pqc-onchain-verification.md`, Section 8.
---
## 9. Honest limitations
This layer is real and on chain, but a credible reader should weigh it against the following, all true today.
- **Decentralization.** AERE runs seven QBFT validators under one operator, one client (Besu), with no external security audit of these contracts and thin real-world usage. The wallet layer inherits that trust profile. Sponsorship and relaying currently depend on a Foundation-hosted relayer.
- **Two EntryPoints, one seam.** As described in Section 3, the account-facing `AereEntryPointV2` and the paymaster-facing lightweight `AereEntryPoint` are distinct, and `handleOps` charges but does not itself invoke the paymaster validation hook. Gasless flows run through the relayer-plus-lightweight-EntryPoint path. Unifying the two is a roadmap item.
- **EntryPoint economics are a subset.** `AereEntryPointV2` uses `maxFee` for gas charging and does not implement full canonical prefund-and-refund. It is sufficient for the hosted relayer, not a drop-in reimplementation of eth-infinitism v0.7.
- **Recovery.** The live passkey account's recovery is "keep at least one owner / add a backup owner". Guardian-and-timelock social recovery is a separate module, `AereSocialRecoveryModule` `0x077514DB…`, which is deployed (Section 6) but is not wired into the live passkey accounts.
- **ERC-7579 modular line IS live, and unaudited.** An earlier revision of this list said the modular account, its factory, both session-key validators and the social recovery module "carry no mainnet address and must not be presented as deployed". They all carry mainnet addresses and are all in the canonical registry; Section 6 has the measured code sizes. The limitation that survives is the real one: none of them has an external security audit and none has meaningful usage. Deployed is not audited.
- **Deprecated contracts are cited alongside their replacements, not silently.** Three entries in this document name a deprecated contract: the passkey factory `0x5FFa9a64…` (Section 2.1), the 7702 delegation target `0x5673D920…` (Section 5), and the session-key validator `0x6e03A3D7…` (Section 6). Each is printed with what is wrong with it and with the canonical successor. Integrators must point at the successors.
- **Post-quantum cost.** The Falcon-512 account is genuinely quantum-resistant at the account layer but costs roughly 10.5M gas per authorization and is level 1, not 1024. It is a real primitive with a heavy price, pending a SHAKE precompile.
- **Deprecated contracts remain on chain.** The V1 token and stake-quota paymasters, and the V1 passkey factory, are retained at their addresses; integrators must point at the canonical V2 addresses listed above.
---
## 10. Address appendix (verbatim from `addresses.ts`)
**EntryPoints**
- `AereEntryPointV2` (accounts): `0x8D6f40598d552fF0Cb358b6012cF4227B86aF770`
- `AereEntryPoint` (lightweight, paymaster relay): `0x19773ba45287A64B05d0BCBD59D1371BF51Bd5D2`
**Passkey wallets**
- `AerePasskeyAccountFactoryV2Fixed` (CANONICAL, create new wallets here): `0x8FA2B45D63EBaa4551A55d7f33a82d597e423428`
- `AerePasskeyAccountV2_sampleFixed`: `0x7C599babc66c350A6cE76673868253e2288D75C1`
- `AerePasskeyAccountFactoryV2` (**FLAWED, do NOT create new wallets here**): `0x5FFa9a6487DA4641a1A1e7900ff2bD4525D34fdA`
- `AerePasskeyAccountFactory` (V1, legacy): `0xfB0eF980667A79Fe1AB69c5f2d512118F1B30739`
**ERC-7579 modular line** (live; see Section 6)
- `AereModularAccountFactory`: `0xE3f45Ed4a81f982fF25ad172A72456a1833a440E`
- `AereSessionKeyValidatorV2` (CANONICAL): `0xC06EAe63Ed12307F56A1506917C48C027D8852ff`
- `AereSessionKeyValidator_v1_DEPRECATED`: `0x6e03A3D7A4c90d6f8dD6F0BA1F6e8aB1F8990D26`
- `AereSocialRecoveryModule`: `0x077514DB2a85F239145537e8334CC99d42c9D812`
**Paymasters**
- `AereOnboardingPaymaster`: `0x4058E406475Dbed7056Aee0c808f293F05fEa879`
- `AereAppPaymasterFactory`: `0xEC22603E8712cBc5c31E53370D10f1a80CcB4DF0`
- `AereTokenPaymasterV2`: `0x217f56a5b0C7f35abe4D2fff924A6c13B85d7243`
- `AereStakeQuotaPaymasterV2`: `0xE50464ca7E8E7F542D1816B3172a2330cFE384E8`
- `AereTokenPaymaster` (V1, deprecated): `0xEb6e2Eb24e597C85392DdCD68a1F9b654FffdcB2`
- `AereStakeQuotaPaymaster` (V1, deprecated): `0xD16C86D792444c2667A26dB62f01b90FC0DaB87b`
**EIP-7702**
- `AereDelegate7702V2` (CANONICAL, delegate here): `0xC6d18e0Ce1B6467d952e31315505E0190a4A3310`
- `AereDelegate7702_v1_DEPRECATED_FLAWED`: `0x5673D92080efbd0987402E9335c14200d0a5EaeF`
- `AereDelegationRegistry`: `0x6c25c07D134713b6C2F8E19D807423f022903D63`
**ERC-6551**
- `ERC6551Registry`: `0x7fFdA0AcDeB919938dB91dbEa779D841c833EF68`
- `AereTokenBoundAccount`: `0xBc5e24180f3F75DC6b1965E4aaD3D4F184b6F9E2`
- Demo NFT (`AereNFT`): `0x3f9A9D9CAB005327869396C69bE226ef98039f1c`
- Demo bound account: `0x82D24cC4E09CaBfD9B00233438B8B6321CBC13Dd`
**Post-quantum account**
- `AerePQCAccountFactory`: `0xd5315Ea7caa60d320c4f34b1bEd70dd9cc02CE58`
- `AerePQCAccount_sample`: `0xa42a5e7F72E46BadC11367650Ec34D676194326f`
- `AereFalcon512Verifier`: `0x4E8e9682329e646784fB3bd01430aA4bA54D8fFC`
**Supporting**
- `AereStakingV2`: `0x1D95eF6D17aeAB732dF914Ba2d018c270BC155FC`
- `AereLockedStaking`: `0x21108c28A849b05aE6b7a3a5bc435C9Bc897E7Ad`
- Foundation (owner of most `Ownable` contracts): `0x0243A4f47D44b40b65D33f20329dE20D00c6f3C3`. Measured at head on 2026-08-02 across all 191 address entries in `sdk-js/src/addresses.ts`: 71 answer `owner()`, 57 return this account, and 14 return an operational deployment account still awaiting transfer to governance. The word "all" was wrong and is corrected here rather than repeated.
**ERC-7579 modular line, corrected 2026-08-02.** This list previously read "in development, no mainnet address" for the whole line, which contradicted Section 6 and the honest-limits list in this same document. Measured at head: `AereModularAccountFactory` `0xE3f45Ed4a81f982fF25ad172A72456a1833a440E` (6,271 bytes), `AereSessionKeyValidatorV2` `0xC06EAe63Ed12307F56A1506917C48C027D8852ff` (6,165 bytes, canonical), `AereSessionKeyValidator_v1_DEPRECATED` `0x6e03A3D7A4c90d6f8dD6F0BA1F6e8aB1F8990D26` (4,698 bytes, superseded because its batch path capped value per sub-call instead of per batch) and `AereSocialRecoveryModule` `0x077514DB2a85F239145537e8334CC99d42c9D812` (4,034 bytes) are all deployed and all in the canonical registry. The one member of the line genuinely absent from the registry is the account implementation `AereModularAccount` itself. What remains true, and is the limitation that matters: none of this line has had an external audit, and none of it is wired into the live passkey accounts.
+330
View File
@@ -0,0 +1,330 @@
# AERE Anti-MEV Design: Threshold-Encrypted Mempool and Batch-Atomic Fair Settlement
Subsystem specification. Status as of 2026-08-01 (re-measured at head block 11,810,041 on `https://rpc.aere.network`). Chain ID 2800 (Hyperledger Besu QBFT, 0.5-second blocks, seven validators, one operator).
## 0. Honesty banner (read first)
This document describes two complementary, **application-layer, opt-in** anti-MEV subsystems that AERE has built and, in part, demonstrated on chain 2800:
1. **AereShutterMempool** (V0 orchestration, V2/V3 threshold-BLS): a Shutter-style threshold-encrypted mempool that hides transaction contents until after an epoch's ordering is fixed.
2. **AereSettlement + AereSolverRegistry + AereVaultRelayer**: a CoW-style batch-atomic settlement DEX where users sign gasless orders and an authorised solver settles the whole batch in one transaction.
What this is **not**, stated plainly so no reader is misled:
- This is **not** base-consensus MEV protection. AERE runs Hyperledger Besu QBFT. A QBFT chain cannot gain a protocol-level encrypted mempool or enshrined proposer-builder separation (PBS) without a client fork. Both subsystems live entirely in smart-contract and off-chain-service space. Validators still sign classical QBFT and order the underlying commit/settle transactions like any other transaction.
- The threshold-encrypted mempool subsystem (V2/V3) is a **proof-of-concept**, and remains one. Both contracts were deployed to chain 2800 and exercised end-to-end.
- **Correction of 2026-08-01, and it cuts against us.** An earlier revision of this banner said that **both** V2 and V3 are "not registered in the canonical SDK address registry". That is wrong for V2 and right for V3, and the direction of the error matters: **V2 is in the canonical registry** at `addresses.ts` line 397 (`AereShutterMempoolV2: '0x135100D523edA8D0AdC70e08af905dE5042A9310'`, 8,339 bytes of live code at head), while **V3 is genuinely absent from it** (0 occurrences, verified; 8,893 bytes of live code at head). So the canonical registry publishes the version carrying the reveal-timeout liveness DoS described in section 4.6, and omits the version that fixes it, while this spec told readers neither was registered. The registry and this document must say the same thing; until the registry is updated, treat V2 as registered-but-superseded and V3 as unregistered-but-corrected, and read section 4.6 before using either.
- Treat the whole subsystem as in-development. Registration is not endorsement, and neither contract has an external audit.
- The batch-settlement contracts (AereSettlement stack) **are** in the canonical registry and were deployed 2026-05-31, but the off-chain solver service, the order-book API, and the front-end intent toggle that would make them a live product are **not yet deployed** (roadmap items recorded in the deployment manifest). On-chain, the settlement contract enforces atomicity and each user's own limit price; it does **not** enforce a uniform clearing price or capture surplus. Those are solver-trust and Phase-2 items, detailed in section 6.
- Both subsystems depend on a **single trusted coordinator/sequencer role** and (for V2/V3) a **trusted-dealer Shamir setup**. The solver set is a **permissioned allowlist** with a single bootstrap solver today. These are real centralisation weaknesses, called out in section 8.
Every contract address quoted below is either verbatim from `sdk-js/src/addresses.ts` (marked CANONICAL) or verbatim from a repository deployment artifact under `contracts/deployments/` (marked POC-ARTIFACT). No address is invented. Where the two sources disagree about a contract's registry status, that disagreement is stated rather than resolved in our favour.
Operator accounts are described by role, not by address. Where an earlier revision printed the coordinator account's hex, it now says "an operational coordinator account": the role is the security-relevant fact, the specific account is operational detail that does not belong in a public spec.
---
## 1. Threat model and design goals
Maximal Extractable Value (MEV) on a public chain is extracted in the gap between when a transaction is broadcast and when it is finally included and ordered. A party that can see pending transaction contents and influence ordering can front-run, back-run, and sandwich user trades. On AERE the primary ordering authority in that gap is the QBFT block proposer and, for the batch-settlement path, the solver that assembles a batch.
AERE attacks the problem from two directions at once:
- **Hide the contents** so that whoever orders transactions cannot tell what they contain until ordering is already fixed. This is the encrypted-mempool subsystem.
- **Remove the intra-batch ordering surface** so that a set of trades clears together, atomically, in one transaction, leaving no slot for an inserted sandwich. This is the batch-settlement subsystem.
Design goals, in priority order:
1. A proposer or sequencer must not be able to reorder or front-run based on plaintext it saw before the ordering was committed.
2. Any accepted decryption key must be provably the real threshold key, not a forgery, so decryption cannot be produced early or by a minority.
3. Liveness must not be held hostage by a single withheld reveal.
4. A user's downside must be bounded by its own signed limit, regardless of solver behaviour, and enforced atomically.
Non-goals for the current phase: trustless data-availability sampling, a distributed key generation (DKG) that removes the dealer, permissionless bonded solvers, on-chain uniform-price verification, and surplus capture. All are named in the roadmap (section 9).
---
## 2. Architecture overview
```
┌─────────────────────────────────────────────┐
user (gasless) │ ENCRYPTED MEMPOOL (opt-in, app-layer) │
───────────────► │ AereShutterMempool V2/V3 (PoC on 2800) │
ciphertext + │ commit → order → threshold-decrypt → reveal│
commitment └───────────────┬─────────────────────────────┘
│ (optional executor hook,
│ NOT wired to settlement today)
▼
┌─────────────────────────────────────────────┐
user (gasless) │ BATCH SETTLEMENT (opt-in, app-layer) │
EIP-712 order │ AereSettlement + Registry + VaultRelayer │
───────────────► │ solver assembles batch → settle() atomic │
└─────────────────────────────────────────────┘
```
The two subsystems are conceptually a pipeline: encrypt order flow so the ordering party is blind, then settle the resulting batch atomically. **Honest note:** they are independent contracts today. AereShutterMempool V2/V3 expose an optional `executor` address that receives `execute(uint64,uint256,bytes)` calls on reveal, but AereSettlement does **not** implement that interface, so nothing wires the mempool's reveal path into the settlement contract at present. Integrating the two (mempool executor to a settlement adapter) is a roadmap item. Each subsystem is described independently below.
---
## 3. Subsystem A1: AereShutterMempool V0 (orchestration, code-only)
Source: `aere-contracts/contracts/mempool/AereShutterMempool.sol`. Compiled artifact present; **no deployment record exists** in `contracts/deployments/`, so V0 is treated as a code-only reference stage that V2/V3 supersede.
V0 establishes the on-chain commit/reveal skeleton without real threshold cryptography. Its stated model:
- **Keyper epochs.** The Foundation opens a keyper epoch (`openEpoch`) carrying a Merkle root of keyper BLS pubkeys and a hash of the aggregated public key. Opening a new epoch implicitly closes the prior one. At most one epoch is open at a time.
- **Ciphertext commitment.** Anyone submits an encrypted envelope with `commit` (or `commitForEpoch` to pin the expected epoch). Storage records the submitter, a SHA-256 hash of the ciphertext blob, an off-chain URI (ipfs/https), the block, and the epoch. `envelopeId = keccak256(epochId, ciphertextHash, sender)`.
- **Key release.** After `startBlock + REVEAL_DELAY_BLOCKS`, the Foundation posts the epoch decryption-key commitment (`releaseDecryptionKey`).
- **Reveal.** `markRevealed` checks that the submitted plaintext binds to the committed ciphertext and released key via `keccak256(abi.encodePacked(plaintext, releasedKey)) == ciphertextHash`, then flags the envelope decrypt-eligible.
The V0 invariant is timing-based: ciphertexts are visible but undecipherable at block N, ordering is finalised by consensus at block N, and the key is released only at block `N + REVEAL_DELAY_BLOCKS`, so post-hoc reordering gains nothing.
The contract records several audit fixes in-source, worth citing because they show the failure modes that motivated V2:
- MED #31: the constructor now requires `revealDelayBlocks >= 1` (a zero delay would defeat protection).
- HIGH #6: `commitForEpoch` lets a caller pin the expected epoch, so a reordered `openEpoch` cannot silently attach a ciphertext to the wrong keyper key and make it permanently undecryptable.
- HIGH #4: `commit` refuses to overwrite an existing envelope slot (no double-reveal via re-commit).
- HIGH #5: `releaseDecryptionKey` is one-shot per epoch (no key overwrite).
- HIGH #3: `markRevealed` is gated to the Foundation and requires the actual plaintext bytes, so nobody can forge a `Revealed` event with an arbitrary plaintext hash.
**Honest limitation of V0.** The "decryption key" is a keccak placeholder, not a real threshold key. The Foundation is the sole releaser and revealer. V0 is orchestration plumbing, not cryptographic anti-MEV. V2 replaces the placeholder with a real threshold-BLS scheme verified on-chain.
---
## 4. Subsystem A2: AereShutterMempool V2 (threshold-BLS, PoC deployed)
Source: `aere-contracts/contracts/mempool/AereShutterMempoolV2.sol`.
**CANONICAL** address, in `sdk-js/src/addresses.ts` line 397: `0x135100D523edA8D0AdC70e08af905dE5042A9310`, 8,339 bytes of live code measured at head block 11,810,041. Deploy tx `0x87ad0d549c396bd5a002b6f9d984483ee3e16567261ff552fd3ce83fb00d3471`, deploy block 8934371. The coordinator role is held by an operational account, which is moving to governance.
**This entry was previously marked POC-ARTIFACT and "not in the canonical SDK registry". It is in the registry.** Note carefully what that means in combination with section 4.6: the registered version is the one with the reveal-timeout liveness DoS, and its fix (V3, below) is the one that is not registered.
### 4.1 Cryptographic construction
V2 implements Boldyreva threshold BLS over the BLS12-381 curve and verifies it on-chain with the EIP-2537 pairing-check precompile at address `0x0f` (0x00...0f). EIP-2537 is live on chain 2800 via the Pectra ruleset (BLS12-381 precompiles at 0x0b through 0x11). The contract comment records that the precompile was probed live on 2800: a valid pairing identity returns 1, garbage input reverts.
Notation used in the contract and in this spec:
- Committee master secret `s`, Shamir `(t, N)`-shared off-chain by a dealer.
- Group public key `PK = s * g2` in G2. This is the epoch encryption public key.
- Keyper public keys `P_i = s_i * g2` in G2. These are the published verifiable-secret-sharing (VSS) commitments.
- Epoch identity `H1 = hashToCurve(epoch tag)` in G1.
- Epoch decryption key `DK = s * H1` in G1. This is the threshold signature over the epoch tag.
- Keyper share `sig_i = s_i * H1` in G1.
- `DK` is reconstructed off-chain from `t` shares by Lagrange interpolation, then verified on-chain.
Two on-chain pairing equalities, both expressed as a product-equals-identity so the single `0x0f` call decides them:
- Share validity: `e(sig_i, g2) == e(H1, P_i)`, checked as `e(sig_i, g2) * e(-H1, P_i) == 1`.
- DK validity: `e(DK, g2) == e(H1, PK)`, checked as `e(DK, g2) * e(-H1, PK) == 1`.
A share or a reconstructed DK that fails its pairing reverts, so a keyper cannot post an inconsistent share and no forged DK is ever accepted. Point encodings follow EIP-2537: a G1 point is 128 bytes, a G2 point is 256 bytes, and the two-pair pairing input is `2 * 384 = 768` bytes. The helper `_pairingCheck2` concatenates the four operands, staticcalls `0x0f`, and returns true only when the 32-byte output decodes to 1.
### 4.2 Epoch lifecycle and phases
An epoch moves through `Phase { None, Open, Ordered, Finalized }`:
1. **Committee registration.** `registerKeypers(addrs, pubkeys, t)` is one-shot and coordinator-only. It stores each keyper's address and 256-byte G2 public key and sets `threshold = t`, `keyperCount = N`.
2. **Open.** `startEpoch(epochId, pk, h1, h1neg)` publishes the epoch encryption key `PK`, the epoch identity `H1`, and its negation, and sets the epoch `Open`.
3. **Submit.** While `Open`, anyone calls `submitEncrypted(epochId, ciphertext, commitment)`. The full ciphertext blob (`U(256-byte G2) || C(payload XOR mask)`) is emitted for off-chain availability; only the binding commitment `keccak256(abi.encode(plaintext, opening))` is stored, and duplicates revert. The sequencer sees only ciphertexts.
4. **Order.** `commitOrdering(epochId, orderingRoot)` is sequencer-only and moves the epoch to `Ordered`. It commits a Merkle root over execution positions and **must** happen before any decryption share exists.
5. **Shares.** `submitDecryptionShare(epochId, keyperIndex, share)` reverts while the epoch is still `Open` or `None` (this is the no-early-decrypt guard) and reverts unless the share passes its on-chain pairing check. Each keyper index can submit once.
6. **Finalize.** Once at least `t` valid shares exist, `finalizeEpoch(epochId, dk)` accepts the off-chain Lagrange reconstruction only if it passes the DK pairing check, and moves the epoch to `Finalized`.
7. **Reveal and execute.** `revealAndExecute(epochId, index, plaintext, opening, proof)` walks the committed ordering strictly in sequence (`index == nextExecIndex`), checks the commitment was actually submitted and not already executed, verifies Merkle membership of `(epochId, index, commitment)` against the committed ordering root, and confirms the plaintext opens the commitment. It then advances the cursor and optionally forwards the plaintext to the configured `executor` as a best-effort `execute(uint64,uint256,bytes)` call (a failing consumer does not roll back the reveal record).
### 4.3 Anti-MEV invariant (V2)
1. Users submit ciphertexts plus a hiding, binding commitment while the epoch is `Open`; the sequencer sees only ciphertexts.
2. The sequencer commits an ordering (a Merkle root over positions) **before** any decryption share can exist; `submitDecryptionShare` reverts until ordering is committed.
3. Keypers post `t` valid shares; anyone reconstructs `DK` off-chain; the reconstruction is pairing-verified on-chain at `finalizeEpoch`.
4. Reveal walks the committed ordering strictly in order; a plaintext that does not open its committed value reverts, and an out-of-order reveal reverts.
Because ordering is fixed while contents are still encrypted, the party that fixes ordering cannot base that ordering on plaintext. Reordering after the fact is impossible: the ordering root is already committed, and reveals must follow it.
### 4.4 Keyper accountability
`reportInconsistentShare(epochId, keyperIndex, allegedShare)` lets anyone flag a keyper whose off-chain share is inconsistent with its on-chain VSS commitment `P_i`. The function reverts if the alleged share actually passes its pairing check, so false accusations are impossible. This emits a `KeyperFlagged` event only; it is a detection primitive, not slashing. Economic slashing of misbehaving keypers is not implemented.
### 4.5 Honest scope and assumptions (V2, from source)
- The symmetric unmasking step (hashing the GT pairing element to a byte mask for XOR) is done **off-chain** by the executor, because the `0x0f` precompile returns only a pairing-equality boolean and cannot output a GT element to hash. On-chain, the plaintext-to-commitment binding is a keccak commitment; DK correctness itself is fully pairing-verified on-chain, so decryption is deterministic and cannot be produced before `t` keypers act.
- `PK`, `P_i`, `H1`, and `H1neg` are published by the committee dealer at registration and epoch start. A malformed published point only breaks liveness (an honest DK or share would fail its pairing); it cannot let a non-committee actor forge `DK`, which still requires the master secret `s` that only `t`-of-`N` shares reconstruct.
- The PoC uses a **trusted-dealer Shamir setup**. A production system would run a DKG so no single party ever holds `s`. This is the single most important cryptographic caveat.
### 4.6 V2 known weakness (fixed in V3)
`revealAndExecute` advances the cursor only on a successful reveal. A single committed position whose plaintext or opening is never revealed (griefed, lost, or malformed) stalls every later position in that epoch forever. There is no skip and no timeout. V3 fixes exactly this.
### 4.7 V2 on-chain demonstration (from deployment artifact)
The V2 deployment artifact records an end-to-end run on chain 2800: a 3-of-5 committee, epoch `8934372` finalized with `shareCount` 3, an ordering root over 2 committed envelopes, and two reveal/execute transactions (`0x552f6779...c7bb`, `0x30f2d141...dc0c`), with `nextExecIndex` reaching 2. The recorded `dkHash` is `0xbb4f9385bf208ea729a5f353434ed126212e377847db7211ac0cfe7e906f3892`. These values are transcribed verbatim from `shutter-mempool-v2.json`; they evidence that the pairing-verified threshold path executed, not a production traffic claim.
---
## 5. Subsystem A3: AereShutterMempool V3 (liveness fix, PoC deployed)
Source: `aere-contracts/contracts/mempool/AereShutterMempoolV3.sol`.
POC-ARTIFACT address (from `contracts/deployments/shutter-mempool-v3.json`), **genuinely not in the canonical SDK registry**, verified by search at 0 occurrences: `0x0C0b0560fcaa534fc30D29ae1D248CC1675281df`, 8,893 bytes of live code measured at head block 11,810,041. Deploy tx `0x72f333214cc61836c334a4e82548175f658db39416f103f5124c9917b40c7fa1`, deploy block 8952902, reveal window 60 seconds. The coordinator role is held by an operational account, which is moving to governance.
**This is the corrected version, and it is the one the registry omits.** Promoting it into `sdk-js/src/addresses.ts`, and marking V2 superseded there, is an open item.
V3 is byte-for-byte the V2 threshold-BLS design (same 3-of-5 committee shape, same commitment binding, same out-of-order reject, same no-early-decrypt guarantee) plus one liveness fix for the reveal-timeout DoS described in 4.6.
### 5.1 The reveal-window escape hatch
- `finalizeEpoch` now stamps a per-epoch `revealDeadline = block.timestamp + REVEAL_WINDOW`, where `REVEAL_WINDOW` is an immutable constructor parameter (60 seconds in the PoC deployment).
- `skipUnrevealed(epochId, index)` advances `nextExecIndex` past the current head position, but only when all four conditions hold: the epoch is `Finalized`, `index == nextExecIndex` (skip strictly at the head), `index < envelopeCount` (there is a position to skip), and `block.timestamp > revealDeadline` (the window has closed). It records `skippedPosition[epochId][index]` and emits `PositionSkipped`.
Because skip only ever acts on the head and a successful reveal advances the head atomically, the head is by construction the still-unrevealed position: a position that was already revealed sits behind the cursor, so skipping it reverts `OutOfOrder`. Revealing is never gated by the deadline; `revealAndExecute` keeps working after the window closes, so a late-but-honest opener can still land its position. Skip is only an escape hatch for a position nobody reveals.
### 5.2 Permissionless-reveal invariant
The liveness argument rests on a protocol invariant that the ciphertext must embed its own opening: the encrypted blob decrypts under `DK` to `(plaintext || opening)` such that `keccak256(abi.encode(plaintext, opening))` equals the committed commitment. This makes reveal permissionless: once `DK` is reconstructed, any holder of the decryption key can open any committed position and call `revealAndExecute`. A well-formed position is therefore always revealable by anyone, so `skipUnrevealed` only ever fires on a position whose opening was genuinely withheld, lost, or malformed, never to censor a revealable transaction. The tradeoff is a little worst-case latency: a stuck position is only skippable after `REVEAL_WINDOW` elapses.
### 5.3 V3 on-chain demonstration (from deployment artifact)
The V3 deployment artifact records the liveness fix exercised on chain 2800: epoch `8952903` finalized (`dkHash` `0xc435edc7fa0eff0f4d2a43556c7d5321294befb67988a03b546d261ddc06081b`, `revealDeadline` 1783700920), position 0 deliberately left unrevealed to simulate a withheld opening, an early `skipUnrevealed` reverting `SkipTooEarly`, then a post-deadline skip (`0x3ee66f74...43ca`) followed by reveal of position 1 (`0x39f75472...fa29`), with `finalNextExecIndex` reaching 2. Transcribed verbatim from `shutter-mempool-v3.json`. This demonstrates that one stuck position no longer stalls the epoch, which was the V2 DoS.
### 5.4 V3 residual weaknesses
The same trusted-dealer, off-chain-unmasking, and single-coordinator caveats from 4.5 carry over unchanged. V3 fixes liveness, not decentralisation. Keyper slashing is still detection-only.
---
## 6. Subsystem B: AereSettlement, solver, and relayer (CoW-style, canonical)
Sources: `aere-contracts/contracts/dex/AereSettlement.sol`, `AereSolverRegistry.sol`, `AereVaultRelayer.sol`.
CANONICAL addresses (verbatim from `sdk-js/src/addresses.ts`):
- `AereSettlement` = `0x9C2957b1622567B4802E4AFd4c42FB2ec70dE875` (Tier-1.9 batch-auction DEX, deployed 2026-05-31)
- `AereSolverRegistry` = `0xDBD29332a9993d2816EF0bD240288E03a8103f3B`
- `AereVaultRelayer` = `0x9FCA122e87E36D7cba20DbEA7b9b7354A4Cece91`
The settlement-stack deployment artifact additionally records a bootstrap solver, held by an operational account whose hex is not published here, and Foundation owner `0x0243A4f47D44b40b65D33f20329dE20D00c6f3C3`.
### 6.1 What it is
A simplified port of CoW Protocol's GPv2 stack. Users sign EIP-712 `Order` structs off-chain (gasless). An authorised solver collects open orders and submits the whole batch atomically via `settle(orders, signatures, executions)`. MEV protection comes from atomicity: because the whole batch executes in one transaction, no actor can insert a sandwich between two orders in the batch.
The `Order` struct carries `user`, `sellToken`, `buyToken`, `sellAmount` (exact, fill-or-kill in v1), `minBuyAmount` (the user's own slippage floor), `validTo` (unix deadline), and `salt` (per-user replay nonce). The `Execution` struct carries just `executedBuyAmount`, the solver's claim of what it will deliver.
`orderHash` builds the EIP-712 digest under the domain `EIP712("AereSettlement", "1")`. The contract inherits `Ownable`, `ReentrancyGuard`, and `EIP712` from OpenZeppelin.
### 6.2 The settle() flow
`settle` is `onlySolver` (allowlist-gated) and `nonReentrant`. It requires equal-length arrays and a non-empty batch. For each order it:
1. Checks `block.timestamp <= o.validTo` (not expired).
2. Requires `executions[i].executedBuyAmount >= o.minBuyAmount` (the user's floor is respected).
3. Recovers the EIP-712 signer with `ECDSA.recover` and requires `signer == o.user`.
4. Requires the order hash is not already `filled`, then marks it filled (replay protection).
5. Pulls `sellAmount` from user to solver through `AereVaultRelayer.transferFromUser` (users approved the relayer, not the settlement contract).
6. Pushes `executedBuyAmount` of `buyToken` from solver to user via `safeTransferFrom` (the solver must have approved the settlement contract for the buy token, or supply liquidity via internal coincidence-of-wants matching).
If any step in the loop reverts, the entire batch reverts, so a user can never be pulled from without receiving at least its `minBuyAmount`. `cancelOrder` lets a user mark its own order consumed on-chain; `isOrderFillable` is a view for open-order checks.
### 6.3 AereVaultRelayer and AereSolverRegistry
`AereVaultRelayer` follows the GPv2VaultRelayer pattern: users approve the relayer once per token (typically MaxUint256), and only the single authorised `settlement` address may call `transferFromUser`. Separating allowances from the settlement contract lets the settlement contract be upgraded without users re-approving. The owner can rotate the settlement address.
`AereSolverRegistry` follows GPv2AllowListAuthentication: an owner-curated `isSolver` allowlist with `addSolver`/`removeSolver`. Phase 1 (current) is an owner-curated allowlist; Phase 2 (not built) is intended to add permissionless bonded-solver entry with slashable AERE stake.
### 6.4 What settle() does and does not guarantee (critical honesty section)
On-chain guarantees that hold today:
- **Atomic batch execution.** No sandwich can be inserted between orders in the batch, because they share one transaction.
- **Per-order limit protection.** Every filled order delivers at least its signed `minBuyAmount`, or the whole batch reverts.
- **Signature and replay safety.** Each fill requires a valid EIP-712 signature from `o.user`, and each order hash can be filled at most once.
What the contract does **not** enforce, despite the docstring's description of finding a "uniform clearing price":
- **Uniform clearing price is not verified on-chain.** The contract checks each order against its own `minBuyAmount` only. It does not check that all orders in a pair cleared at one common price. Uniform-price fairness is a solver behaviour, not a contract invariant. A solver could fill different users of the same pair at different effective prices as long as each clears its own floor.
- **No surplus capture and no protocol fee.** Unlike CoW, this contract has no fee parameter and no surplus accounting. Any price improvement above `minBuyAmount` accrues wherever the solver directs it, not to users or to a protocol sink, on-chain. There is no wiring to `AereSink` (`0x69581B86A48161b067Ff4E01544780625B231676`) for MEV or surplus redistribution in this contract today.
- **No partial fills, no ERC-1271 signatures, no balance modes, no dynamic fees.** The source explicitly states these are omitted and that audit-grade hardening is deferred to Phase 2.
The practical security posture is therefore: **atomicity plus your own limit price protect you from the worst MEV, but you are trusting the permissioned solver for fair (uniform, surplus-returning) pricing above your floor.** That is a meaningful and honest distinction from a fully trust-minimised CoW deployment.
### 6.5 Off-chain solver and relayer service (roadmap, not deployed)
The settlement-stack deployment artifact lists the operational pieces that would make this a live product, all recorded as next steps rather than done:
- Rotate the bootstrap solver to a dedicated solver address.
- Deploy an `aere-cow-solver` Docker container running the default solver.
- Stand up an order-book API at `api.aere.network/cow` storing open orders in a separate explorer-db schema.
- Add an MEV-protected (intent) toggle to `/swap.html` alongside the direct AereSwap mode.
- Phase 2: bonded-solver registry for permissionless entry.
None of these off-chain services is confirmed deployed in the repository artifacts. The on-chain contracts are live; the surrounding solver and order-book infrastructure is in development.
---
## 7. How the two subsystems relate
The intended composition is: encrypted mempool blinds the ordering party to order flow, and batch settlement removes the intra-batch ordering surface. In a fully integrated design, decrypted orders from an epoch would be handed to a settlement executor that clears them as a batch.
**Honest current state:** the two are not integrated on-chain. AereShutterMempool V2/V3 can call an optional `executor.execute(uint64,uint256,bytes)` on reveal, but AereSettlement exposes `settle(...)`, not that interface, and no adapter connects them. A user today would use either the encrypted-mempool PoC or the batch-settlement stack, not a wired pipeline. Building a mempool-to-settlement executor adapter is a named roadmap item.
---
## 8. Consolidated honest limitations and security posture
1. **App-layer, opt-in, not base consensus.** Neither subsystem changes QBFT. Validators sign classical QBFT and can still censor or reorder the underlying commit and settle transactions at the base layer. The encrypted mempool protects transaction **contents** from being front-run; it does not stop a proposer from censoring or reordering ciphertext-commit transactions (though reordering opaque ciphertexts yields no MEV, since the proposer cannot see what is inside). This is not enshrined PBS and not a protocol-level encrypted mempool.
2. **Centralised operator and validator set.** Chain 2800 runs seven validators under one operator, one client (Besu). The encrypted-mempool coordinator and sequencer default to a single operational account in the proofs of concept, and a single sequencer commits ordering. That is the security-relevant fact and it is a trust assumption, not a decentralised guarantee. The specific account is operational detail and is not published here.
3. **Trusted-dealer key setup (V2/V3).** The threshold master secret is Shamir-shared by a dealer in the PoC. Until a DKG replaces the dealer, one party transiently holds `s`. A live product must not ship on a trusted dealer.
4. **Keyper accountability is detection-only.** Inconsistent shares can be flagged on-chain but are not economically slashed.
5. **Permissioned solvers, single bootstrap solver.** The settlement allowlist is owner-curated with one bootstrap solver today. Permissionless bonded, slashable solver entry is unbuilt (Phase 2).
6. **Uniform pricing and surplus are off-chain trust.** As detailed in 6.4, the settlement contract enforces atomicity and per-order floors only.
7. **PoC status of the encrypted mempool.** V2 and V3 are demonstrated, not audited externally, and carry no production-traffic claim. V0 is code-only. On registration, be precise, because an earlier revision of this bullet was not: **V2 IS in the canonical SDK registry** (`addresses.ts:397`) and **V3 is not**. The registered one is the one with the reveal-timeout liveness DoS of section 4.6; the corrected one is the unregistered one. Promoting V3 and marking V2 superseded is an open item, and until it is done a reader who trusts the registry alone gets the worse contract.
8. **No external audit.** The in-source audit-fix annotations reflect internal review. There is no third-party audit of these contracts.
Stating these plainly is deliberate. For a chain with thin usage and a small validator set, credibility comes from precise scoping, not from overclaiming that app-layer opt-in tooling is base-layer MEV resistance.
---
## 9. Roadmap (in development, not yet live)
- **DKG for the keyper committee** to remove the trusted dealer, so no party ever holds the master secret `s`.
- **On-chain (or precompile-assisted) symmetric unmasking.** The V0 source names a proposed decryption precompile at `0x102`; this is a proposed, not-live capability and would need a client fork on a scratch fork, not mainnet 2800. Today unmasking is off-chain and only DK correctness is verified on-chain.
- **Keyper slashing** built on the existing `reportInconsistentShare` detection primitive.
- **Mempool-to-settlement executor adapter** so a decrypted epoch feeds AereSettlement as a batch (section 7).
- **On-chain uniform-price verification and surplus capture** in the settlement path, with surplus routed to users or to `AereSink`.
- **Permissionless bonded-solver registry** with slashable AERE stake (Phase 2 of AereSolverRegistry).
- **Promotion of the encrypted-mempool contracts into the canonical SDK registry** once the trusted-dealer and audit gaps close.
- **Off-chain solver and order-book service deployment** (aere-cow-solver, `api.aere.network/cow`, `/swap.html` intent toggle).
- **External audit** of the full anti-MEV stack.
---
## 10. Address and artifact appendix (verbatim)
CANONICAL, from `aerenew/sdk-js/src/addresses.ts`:
| Contract | Address |
|---|---|
| AereSettlement | `0x9C2957b1622567B4802E4AFd4c42FB2ec70dE875` |
| AereSolverRegistry | `0xDBD29332a9993d2816EF0bD240288E03a8103f3B` |
| AereVaultRelayer | `0x9FCA122e87E36D7cba20DbEA7b9b7354A4Cece91` |
| AereSink (fee sink, referenced, not wired here) | `0x69581B86A48161b067Ff4E01544780625B231676` |
| Foundation (owner) | `0x0243A4f47D44b40b65D33f20329dE20D00c6f3C3` |
Encrypted-mempool contracts. Both are proofs of concept and neither is externally audited. Registry status differs between them and is stated per row; code sizes measured at head block 11,810,041 on 2026-08-01.
| Contract | Address | Live code | Registry status | Source artifact |
|---|---|---|---|---|
| AereShutterMempoolV2 | `0x135100D523edA8D0AdC70e08af905dE5042A9310` | 8,339 B | **CANONICAL** (`addresses.ts:397`); carries the section 4.6 liveness DoS | `shutter-mempool-v2.json` |
| AereShutterMempoolV3 | `0x0C0b0560fcaa534fc30D29ae1D248CC1675281df` | 8,893 B | **NOT in the registry**; fixes the section 4.6 liveness DoS | `shutter-mempool-v3.json` |
Operator roles for both proofs of concept (coordinator, deployer, and the settlement bootstrap solver) are held by operational accounts and are described by role rather than by address.
AereShutterMempool V0 (`AereShutterMempool.sol`) is code and compiled artifact only, with no deployment record, and is superseded by V2/V3.
Precompile dependency: EIP-2537 BLS12-381 pairing check at address `0x0f`, live on chain 2800 under the Pectra ruleset (BLS12-381 precompiles at 0x0b through 0x11).
Contract sources of record:
- `aere-contracts/contracts/mempool/AereShutterMempool.sol` (V0)
- `aere-contracts/contracts/mempool/AereShutterMempoolV2.sol`
- `aere-contracts/contracts/mempool/AereShutterMempoolV3.sol`
- `aere-contracts/contracts/dex/AereSettlement.sol`
- `aere-contracts/contracts/dex/AereSolverRegistry.sol`
- `aere-contracts/contracts/dex/AereVaultRelayer.sol`
+162
View File
@@ -0,0 +1,162 @@
# AERE Network: Trustless Extended Block-Hash Lookback via Native EIP-2935
**Chain:** AERE Network mainnet, chain ID 2800 (Hyperledger Besu QBFT). Measured mean block interval 0.5175 s over the 2,000 blocks to head 11,810,041 on 2026-08-01; seven validators, f=2, one operator.
**Status date:** 2026-08-01. Every on-chain figure (code size, owner, counters, route targets, balances, the EIP-2935 window) was re-read from `https://rpc.aere.network` at head block 11,810,041 on that date. Corrections found in that pass are stated inline, next to the sentence they correct, rather than applied silently.
**Source of truth for addresses:** `sdk-js/src/addresses.ts`. Contract source: `contracts/contracts/anchor/`. Consensus change: the AERE Besu fork.
**Scope:** how AERE extends the trustless block-hash lookback horizon from 256 blocks to 8191 blocks by writing the EIP-2935 history-storage ring buffer inside consensus, and how the `AereHistoryStateRootAnchor` contract turns that reach into canonical, trust-minimized state roots that make the storage-proof coprocessor useful for blocks older than about two minutes.
This document describes a consensus-layer change (native EIP-2935 in the Besu fork) plus one application contract (`AereHistoryStateRootAnchorV2`). It is precise about status: the native EIP-2935 extended-lookback write path is now LIVE on mainnet chain 2800, activated at block 9,189,161 (2026-07-12) as part of the AerePQC hard fork; and the consumer contract that reads it, `AereHistoryStateRootAnchorV2`, is **deployed and registered on mainnet** at `0x4C1F9daD515c7990b65F9833960CA4315216330C` (`addresses.ts` line 391), carrying 2,915 bytes of live code at head. An earlier revision of this document said that consumer contract was "not yet in the canonical address registry and is pending mainnet deployment"; that was true when written and is false now, and the correction is stated in each place it appeared rather than applied silently. Where a capability is live on chain 2800 versus pending versus roadmap, that is stated explicitly.
---
## 0. Honesty preamble (read this first)
1. **The extended-lookback write path is now live on mainnet.** The native EIP-2935 write path was implemented in the AERE Besu fork, demonstrated end-to-end on a fresh scratch chain (chain ID 28099), and activated on live chain 2800 at block 9,189,161 (2026-07-12), bundled into the single AerePQC hard-fork alongside the NIST post-quantum precompiles under one coordinated activation. The history-storage system contract now returns its canonical runtime on mainnet, so the 8191-block window is available. The consumer contract that reads it, `AereHistoryStateRootAnchorV2` `0x4C1F9daD515c7990b65F9833960CA4315216330C`, is deployed and in the canonical registry; its `HISTORY_STORAGE_ADDRESS()` returns `0x0000F90827F1C53a10cb7A02335B175320002935`, read from chain. The live 256-block `AereStateRootAnchorV2` `0x0b959402283c0D2B9db4FfD7823f99782462e488` continues to use the `BLOCKHASH` window by design.
2. **This is an application and consensus-support feature, not a change to how blocks are finalized.** QBFT still produces and finalizes blocks exactly as before. EIP-2935 only adds a consensus-written history buffer that EVM contracts can read. It does not touch validator set, ordering, or finality.
3. **The trust model is identical to `BLOCKHASH`, and no larger.** The value the anchor trusts is written by consensus itself, never by a keeper, relayer, or Foundation key. Extending the reach from 256 to 8191 blocks does not add a new trusted party, and does not remove the honest-majority assumption on the seven-validator QBFT set.
4. **Decentralization baseline.** AERE runs seven QBFT validators, single operator, single client (Besu), no external audit of the AERE-authored contracts. That is the context for everything below. Extended lookback improves a canonicity mechanism; it does not change the operator or validator count.
---
## 1. The problem: the 256-block canonicity horizon
AERE has a live storage-proof coprocessor, `AereStorageProofVerifier` (`0xF9a1A183bEb3147D88dA5927301683fEbFb9362E`, canonical, immutable, no owner). It takes an SP1 Groth16 proof whose guest RLP-walks AERE's real Merkle-Patricia trie from a `stateRoot` down to a storage `value`, and commits exactly 192 bytes of public values, `abi.encode(chainId, blockNumber, stateRoot, account, slot, value)`. It proves a precise statement: **at the state root R, account A's slot S held value V.**
There is one thing that proof cannot do on its own: it cannot show that R is the **canonical** state root of `blockNumber` on chain 2800. Inside the proof, `blockNumber` is just metadata bytes; nothing binds R to the real chain. A caller could hand the verifier any internally-consistent `(R, A, S, V)` from a fabricated trie. So the verifier ships two entry points: `submitProof` (records against a caller-supplied root, canonicity is the caller's problem) and `submitProofWithExpectedRoot` (records only if the proof's root equals a root the caller vouches for). The canonicity check is deliberately pushed to the call site.
The clean, trust-minimized way to supply that canonical root is to recover it from consensus. The EVM already exposes one such source: the `BLOCKHASH` opcode, which returns the true hash of a recent block. AERE's first anchor, `AereStateRootAnchor` (`0x78b40a983E89c91Aefd8A62Be709bDF25ABB57cb`, canonical in `sdk-js/src/addresses.ts`, deployment artifact `contracts/deployments/state-root-anchor.json`), uses exactly this: it reads `blockhash(n)`, checks a caller-supplied RLP header hashes to it, decodes the header's state root, and records that root as anchored. The block hash comes strictly from the opcode, never from a caller argument, so nobody can anchor a fabricated root.
The limit is reach. `BLOCKHASH` serves only the **last 256 blocks**, about 132 seconds at AERE's measured 0.5175 s mean block interval. A consumer wanting to assert "at block N, this contract's owner was X" has roughly two minutes after N to anchor it, or the opcode goes dark and the canonical root is unrecoverable from within the EVM. That is far too tight for any workflow where prover and on-chain consumer are not tightly coupled in time: cross-domain settlement, a light client catching up, an agent proving a historical fact, a dispute over a block already a few minutes old. The deployed 256-block anchor is honest about this in its own source and artifact.
EIP-2935 is the mechanism that closes this gap without introducing a trusted oracle.
---
## 2. EIP-2935: a consensus-written history ring buffer
EIP-2935 (part of the Prague ruleset) defines a **history-storage system contract** at the canonical address `0x0000F90827F1C53a10cb7A02335B175320002935`. Its behavior is simple and its trust properties are the whole point:
- **It is a ring buffer of the last 8191 block hashes.** At the start of every block, the parent block's hash is written into storage slot `(number - 1) % 8191`. The buffer therefore always holds the hashes of the previous 8191 blocks and no more.
- **It is written by consensus, not by a transaction.** On the AERE Besu fork, Besu's `PraguePreExecutionProcessor` performs this write as a **system call from address `0xffff...fffe`** at the start of block processing, before any user transaction runs. There is no externally-owned account, no keeper, no relayer, and no Foundation key involved. The write is part of producing the block. A validator that omitted or forged it would produce a block that other validators reject.
- **It is read by a plain `STATICCALL`.** The runtime code answers a read whose input is the 32-byte big-endian block number and whose output is the 32-byte canonical hash of that block. For any block number **outside** the served range `[number - 8191, number - 1]`, it reverts (and returns no 32-byte value), so an out-of-window query is unambiguous.
The reach is the improvement. 8,191 blocks at the measured 0.5175 s mean interval is roughly **71 minutes** of trustless lookback, against the roughly 132 seconds `BLOCKHASH` gives. Same trust source (consensus), same "the hash is never a caller argument" property, 32x more blocks and about 32x more wall-clock reach.
Note the history on chain 2800. The Pectra ruleset AERE activated in May 2026 nominally listed EIP-2935, but the history-storage contract was not actually populated on mainnet: `eth_getCode` at the system address returned `0x`, so the extended window was unavailable in practice, which is why the live 256-block `AereStateRootAnchor` used `BLOCKHASH`. The AerePQC hard fork (block 9,189,161) added the missing consensus-side write path that makes the ring buffer real: `eth_getCode` at the system address now returns the canonical Pectra runtime (which encodes the 8191-block ring buffer), so the extended window is live on mainnet.
---
## 3. Native implementation in the fork, bundled into the AerePQC hard-fork
The change is in the AERE Besu fork, in the Prague pre-execution path. At each block the `PraguePreExecutionProcessor` writes the parent hash into the EIP-2935 ring buffer via the system-address call described above. Because it is a consensus rule and not a deployed application contract, the buffer is populated deterministically by every validator as a condition of block validity. Nothing needs to be "kept alive" by an operator.
On mainnet this activated as part of the **single AerePQC hard-fork** (Besu `futureEips` milestone, `futureEipsTime = 1783820272`), at block 9,189,161, the same fork that carries AERE's native NIST post-quantum precompiles. Coordinating both into one activation was intentional: mainnet got extended trustless lookback and the post-quantum verification path in one scheduled event. The PQC relevance is scheduling, not cryptography: EIP-2935 is a hash ring buffer, not a post-quantum construction, but it rides the same hard-fork so the network takes one coordinated upgrade instead of two.
**First proven on scratch (chain ID 28099), now live on mainnet.** On a fresh scratch chain with the fork active, the ring buffer was verified end-to-end before the mainnet activation:
- Blocks advanced past the 256-block `BLOCKHASH` horizon.
- A header **258 or more blocks back** (beyond where `BLOCKHASH` returns anything) was anchored: its canonical hash was recovered **purely from the EIP-2935 system contract** via `STATICCALL`, and the header's state root was recovered from that hash alone.
- The served window behaves as specified out to 8191 blocks.
That scratch run demonstrated the write path, the read path, and the anchor contract working together against a real consensus-written buffer. The write path itself has since activated on mainnet at block 9,189,161: the system contract now returns its canonical runtime on chain 2800, so the ring buffer is live. **Both halves are now live on mainnet**: the buffer, and the consumer contract `AereHistoryStateRootAnchorV2` `0x4C1F9daD…` that reads it. Neither is pending. What is pending is narrower and is stated in Section 7.
---
## 4. The `AereHistoryStateRootAnchor` mechanism
`AereHistoryStateRootAnchorV2` (source at `contracts/contracts/anchor/AereHistoryStateRootAnchor.sol`; live on mainnet at `0x4C1F9daD515c7990b65F9833960CA4315216330C`, `addresses.ts` line 391, 2,915 bytes) is the EIP-2935 sibling of `AereStateRootAnchorV2`. It is byte-for-byte the same shape as the 256-block anchor, with one difference: where the block hash comes from.
**Canonical hash source.** `_historyBlockHash(blockNumber)` `STATICCALL`s the system contract at `HISTORY_STORAGE_ADDRESS = 0x0000F90827F1C53a10cb7A02335B175320002935` with the 32-byte block number as input. It treats a revert, a non-32-byte return, or a zero return as out-of-window (`OutOfHistoryWindow`), and requires the system contract to have code at all (`HistoryContractMissing`) so the contract fails closed on a chain where the fork is not active. `HISTORY_SERVE_WINDOW = 8191` is the declared reach. The hash is read at call time from consensus storage and is never taken from a caller argument.
**Anchoring a historical header.** `anchorHistoricalHeader(blockNumber, rlpHeader)`:
1. reads the canonical hash from the ring buffer (`_historyBlockHash`);
2. requires `keccak256(rlpHeader) == canonical`, so the caller cannot substitute a forged header (`HeaderHashMismatch`);
3. decodes the state root from the header at a fixed offset and records `(blockNumber to stateRoot, blockHash, verifiedAt)` permanently.
The decode relies on the fact that a block header's first four fields are fixed-size, so the state root sits at a known offset regardless of any later fields (`extraData`, QBFT commit-seal handling, or the post-Prague tail): `[0] parentHash` (32B, RLP prefix `0xa0`), `[1] ommersHash` (32B, `0xa0`), `[2] beneficiary` (20B, `0x94`), `[3] stateRoot` (32B, `0xa0`). The contract validates each of those prefixes before reading the 32 state-root bytes, and reverts `MalformedHeader` with a numbered code otherwise. This is the same decode logic the live 256-block anchor uses, so QBFT headers that anchor there anchor here identically.
**Proving against an anchored root.** `proveAgainstAnchor(publicValues, proof)`:
1. calls `VERIFIER.verify(publicValues, proof)`, which reverts on an invalid SP1 proof or wrong chainId, and returns `(blockNumber, stateRoot, account, slot, value)` from the proof's committed public values;
2. loads the anchored record for **that same `blockNumber`** (the block number is committed inside the proof, so the caller cannot mismatch the proof and the anchor), reverting `NotAnchored` if absent;
3. requires the proof's committed `stateRoot` equals the anchored `stateRoot` (`RootNotCanonical`);
4. only then calls `VERIFIER.submitProofWithExpectedRoot(publicValues, proof, anchoredRoot)`, which re-verifies and records the slot in the live coprocessor.
**Immutability.** `VERIFIER` is fixed at construction. There is no owner, no admin, and no upgrade path. Anyone may anchor any in-window header, and anyone may prove against any anchored root. Once a `(blockNumber to stateRoot)` record exists, it is permanent and independent of the moving 8191-block ring buffer: the buffer only needs to have served the hash at anchoring time.
---
## 5. Trust model: identical to `BLOCKHASH`, no keeper
The security argument is short because it reduces to consensus.
- The only value the anchor trusts, the canonical block hash, is produced by the same actor that produces `BLOCKHASH`: QBFT consensus, writing the ring buffer as a system call at the start of each block. There is no additional trusted party. An attacker who could forge an EIP-2935 answer could equally forge `BLOCKHASH`, which means they already control block production.
- The header cannot be forged: `keccak256(rlpHeader)` must equal the consensus-written hash, and the state root is decoded from that exact header. A wrong header reverts before anything is recorded.
- The proof cannot be aimed at a wrong root: the block number is inside the proof's public values, the anchor keys on that number, and the state root must match. The verifier reverts the whole call on an invalid proof or chainId mismatch, so no unverified state is ever recorded.
- No component depends on an off-chain keeper, oracle feed, relayer, or Foundation signature. The only liveness requirement is that **someone** anchors a header while it is still inside the 8191-block window; after that the record is permanent.
The honest boundary is the same one that applies to all of AERE: this inherits the honest-majority assumption of a seven-validator, single-operator QBFT set. Extended lookback does not weaken that assumption and does not strengthen it. It moves a mechanism that was capped at 256 blocks up to 8191 blocks under the exact same trust source.
---
## 6. What this unlocks: trust-minimized storage proofs with a usable time horizon
The storage-proof coprocessor is only as useful as the window in which its roots can be made canonical on-chain. With the 256-block anchor, a proof about block N is only trust-minimized if it is anchored within roughly 132 seconds of N. That rules out most real uses. With native EIP-2935, the same proof is trust-minimized if it is anchored within roughly 71 minutes of N, and the resulting record is permanent thereafter.
Concretely, the two-call pattern becomes practical:
1. Within roughly 71 minutes of block N, anyone calls `anchorHistoricalHeader(N, rlpHeader)`. The header is checked against the consensus-written hash and its state root is recorded forever.
2. At any later time, anyone submits a storage proof about slot S of account A at block N via `proveAgainstAnchor`. The proof's root is matched against the permanently anchored canonical root, then recorded in `AereStorageProofVerifier`.
This is the canonicity building block the storage-proof coprocessor was designed to lean on, and the same one the validity anchors want. AERE's rollup validity anchors, the bounded-VM `AereRollupValidity` (`0x38772063572DF94E90351e44ccbBEefD5F497fbd`, canonical) and the full-EVM `AereEVMValidity` (`0x1f2CB0ebDBb21500e99868DbF1dB3abCcDd7DF26`, canonical), prove statements *about* a state transition; anchoring lets a consumer bind those statements to a canonical AERE block instead of a bare root. Extended lookback widens the window for establishing that binding from two minutes to over an hour.
---
## 7. Proven scope versus production (explicit)
**What is proven, and where:**
- Native EIP-2935 write path implemented in the AERE Besu fork (`PraguePreExecutionProcessor`, system-address write, no keeper) and **live on mainnet chain 2800 since block 9,189,161** (the AerePQC hard fork). It was first demonstrated end-to-end on scratch chain **28099** (a header **258+ blocks back**, beyond the 256-block `BLOCKHASH` horizon, anchored with its state root recovered **purely from the system contract**); on mainnet, `eth_getCode` at the system address now returns the canonical Pectra runtime, which serves an **8,191-block window, roughly 71 minutes at the measured 0.5175 s interval**.
- `AereHistoryStateRootAnchor` compiles, and its anchor-then-prove flow works against a real consensus-written ring buffer (verified on the scratch chain). Its decode and prove logic are identical to the live 256-block `AereStateRootAnchor`.
- The downstream consumer, `AereStorageProofVerifier`, is **live on mainnet** and has recorded a real proof (`AereTreasury` `0x687933...6119` slot 0 equals the Foundation `0x0243A4...f3C3` at block 8915939, against canonical state root `0x515fce04...4a92f3`, submit tx `0xe541c52b...6c54`, gasUsed 348,345, under the EIP-7825 per-tx cap).
**What is not yet true:**
- **Correction of 2026-08-01.** This bullet previously read that the 8191-block consumer contract "is not yet deployed or registered on mainnet and is not in `sdk-js/src/addresses.ts`", and called that deployment plus registration "the remaining step". Both are done: `AereHistoryStateRootAnchorV2` is live at `0x4C1F9daD515c7990b65F9833960CA4315216330C` with 2,915 bytes of code and is registered at `addresses.ts` line 391. The live 256-block `AereStateRootAnchorV2` continues to use `BLOCKHASH` by design and is unaffected.
- **What genuinely does remain.** `AereHistoryStateRootAnchorV2.VERIFIER()` returns `0xF9a1A183bEb3147D88dA5927301683fEbFb9362E`, which the canonical registry marks `AereStorageProofVerifier_DEPRECATED_POISONABLE`. Until it is repointed at `AereStorageProofVerifierV2 0x487021f9aE018657B7335ADC6Fc254717751a1Dd`, the extended-lookback path ends in a record we ourselves call poisonable. That, not the deployment, is the open item.
- The extended-window anchor path has been exercised against a consensus-written buffer on the scratch chain; it has not yet been exercised on mainnet under production load, pending the consumer contract deployment above.
- The 8191-block window is still **bounded**. Blocks older than roughly 71 minutes cannot be freshly anchored from within the EVM by this mechanism; only records anchored while in-window survive (permanently). A trustless anchor for arbitrarily old blocks (for example a consensus-maintained accumulator or a checkpoint tree) is a separate, unbuilt design and is explicitly roadmap.
- The decentralization baseline is unchanged: seven validators, one operator, one client, no external audit.
---
## 8. Address and status table
**Canonical (verbatim from `sdk-js/src/addresses.ts`):**
| Role | Contract | Address | Status |
|---|---|---|---|
| Storage-proof coprocessor (consumer) | `AereStorageProofVerifier` | `0xF9a1A183bEb3147D88dA5927301683fEbFb9362E` | Live on chain 2800 |
| SP1 routing (proof verification) | `SP1VerifierGateway` | `0x9ca479C8c52C0EbB4599319a36a5a017BCC70628` | Live on chain 2800 |
| Rollup validity anchor (bounded VM) | `AereRollupValidity` | `0x38772063572DF94E90351e44ccbBEefD5F497fbd` | Live on chain 2800 |
| Recent-lookback anchor (BLOCKHASH, 256) | `AereStateRootAnchor` | `0x78b40a983E89c91Aefd8A62Be709bDF25ABB57cb` | Live on chain 2800, 256-block window |
| Full-EVM validity anchor (single block) | `AereEVMValidity` | `0x1f2CB0ebDBb21500e99868DbF1dB3abCcDd7DF26` | Live on chain 2800 |
| Full-EVM validity anchor (batch) | `AereEVMValidityBatch` | `0x49D30a5999eA5b7f6eFf12196AB006316683Ff3C` | Live on chain 2800 |
**Deployed on mainnet, with registry status attached (corrected 2026-08-02: this heading previously read "not yet in the canonical registry, pending registration", which the rows underneath already contradicted):**
| Role | Contract / component | Address / location | Status |
|---|---|---|---|
| Extended-lookback anchor (EIP-2935, 8191) | `AereHistoryStateRootAnchorV2` | `0x4C1F9daD515c7990b65F9833960CA4315216330C` (`addresses.ts:391`) | **Live on mainnet**, 2,915 bytes; `VERIFIER()` still points at the deprecated `0xF9a1A183…` |
| Native EIP-2935 write path | AERE Besu fork (`PraguePreExecutionProcessor`) | history contract `0x0000F90827F1C53a10cb7A02335B175320002935` | Live on chain 2800 since block 9,189,161 (AerePQC hard fork) |
---
*Every canonical address above is verbatim from `sdk-js/src/addresses.ts`, with its registry status attached, not just its hex. The native EIP-2935 write path is live on mainnet chain 2800 since block 9,189,161 (the AerePQC hard-fork), and the consumer contract that reads it, `AereHistoryStateRootAnchorV2` `0x4C1F9daD…`, is live and registered.*
*Re-measured independently on 2026-08-01 at head block 11,810,041 on `https://rpc.aere.network`, because this document's central claim deserves to be re-derived rather than cited: `eth_getCode` at `0x0000F90827F1C53a10cb7A02335B175320002935` returns **83 bytes**, and reading that contract with a 32-byte block number returned exactly the canonical hash `eth_getBlockByNumber` reports at offsets of 1, 255, 256 and 8,190 blocks behind head, while offsets of 8,191 and beyond revert. That is the 8,191-entry ring behaving as specified, with one slot held by the in-flight block.*
*Block-time-derived figures assume the measured 0.5175 s mean block interval: 256 blocks is about 132 s, 8,191 blocks is about 71 minutes. No throughput or TPS figure is claimed here.*
+302
View File
@@ -0,0 +1,302 @@
# AERE Token-Economic Mechanisms: Burn, Sink Flywheel, and Staking
Subsystem specification. AERE Network mainnet, Chain ID 2800 (Hyperledger Besu QBFT; measured mean block interval 0.5175 s over the 2,000 blocks to head 11,810,041 on 2026-08-01; seven validators, f=2, commit quorum 5 of 7, one operator).
Source of truth for addresses: `aerenew/sdk-js/src/addresses.ts`. Source of truth for logic: `aerenew/contracts/contracts/`.
Solidity 0.8.23, OpenZeppelin 4.9.6.
## Scope and honesty preface
This document specifies the on-chain money mechanisms that make AERE deflationary and that pay stakers:
1. The validator-coinbase burn split (`AereCoinbaseSplitter` and its V2 successor).
2. The permanent burn endpoint (`AereFeeBurnVault`).
3. The immutable three-bucket revenue router (`AereSink`), configured 15/40/45 across BURN, BUYBACK, and STAKER-YIELD.
4. The liquid-staking receipt token (`sAERE`, ERC-4626).
5. The staking-reward products: delegated validator staking (`AereStakingV2`, 8% default APR) and fixed-term locked staking (`AereLockedStaking`, 10 to 30% APY).
Read the following honestly before the mechanism detail:
- **Fixed supply, no new issuance.** Total supply is capped at 2,800,000,000 AERE at genesis-v2 (2026-05-07). None of the mechanisms below mint tokens. Staking rewards are paid out of pre-allocated genesis reserves that the Foundation seeds into each reward pool, not out of adaptive inflation. This is a deliberate design choice, not an oversight.
- **The APRs are a reserve-funded subsidy, not perpetual issuance.** Because supply is fixed, the 8% delegated APR and the 10 to 30% locked APYs are finite: they draw down a Foundation-seeded reserve. They are sustainable only as long as that reserve funds them, or, in the long run, as far as real protocol-fee revenue routed through `AereSink` replaces the subsidy. The intended end-state is that the fee flywheel, not the reserve, pays stakers.
- **Realized throughput is thin.** The chain runs with seven validators under one operator, one client, and no external audit. Burn and yield volume to date depend on validators actually running the coinbase-forwarder daemon and on real fee flow. This spec states parameters and formulas that are verifiable from source. It does not quote lifetime-burned, TVL, or yield figures; those are to be read live from the contracts' on-chain counters.
- **The base-fee framing is precise.** AERE's QBFT chain does not run EIP-1559 protocol-level base-fee burning. The "37.5% burn" is applied to validator coinbase rewards by a splitter contract that validators call, operationalizing whitepaper section 3.3 at the coinbase layer rather than in consensus. Where this matters it is stated inline.
Native AERE is the gas and value token. `WAERE` (`0x7e84d7d66d5da4cfE46Da67CDEeB05B323e1f5e8`) is the ERC-20 wrapper, minted 1:1 by depositing native AERE (WETH9 design). Every ERC-20-facing mechanism below (the sink, sAERE) operates on WAERE; the splitter wraps native AERE into WAERE before routing it to the sink.
## 1. Fixed-supply foundation
Genesis-v2 allocations (from the registry header, chain 2800):
The table below gives the genesis-v2 allocation and, next to it, the balance actually held by each address today. **These are two different numbers and this spec previously printed only the first.** Balances read with `eth_getBalance` at head block 11,810,041 on `https://rpc.aere.network`, 2026-08-01.
| Allocation | Allocated at genesis | Held at head 11,810,041 | Address |
|---|---|---|---|
| Strategic Investor (sold off-chain) | 100,000,000 | 100,000,000 | `0xaee2f3989f0AB23296Fa3b92247fe67587141311` |
| Foundation (chain admin / contract owner) | 180,000,000 | 179,999,989.9987 | `0x0243A4f47D44b40b65D33f20329dE20D00c6f3C3` |
| Mining Reserve | 1,400,000,000 | 1,400,000,000 | `0x038f59A40ceeCd599A4588E4B0ff4642a0fbfFB8` |
| Ecosystem Reserve | 560,000,000 | **0.6999958** | `0xB6a364F47d21DC2CbEB803565c111c1026e11C75` |
| Team Reserve | 420,000,000 | 420,000,000 | `0x7968C438204a78B4e032fcFFd9A56Edb15fdCCdf` |
| Airdrop Reserve | 140,000,000 | 140,000,000 | `0x261913fA73D6F109382F1aE98Ff6822ff03628B1` |
| **Sum of the six addresses above** | **2,800,000,000** | **2,239,999,990.6987** | |
**Correction of 2026-08-01: this table did not add up, and now it says so.** An earlier revision printed the allocation column and the sentence "Total 2,800,000,000 AERE, capped" directly beneath it, with no balance column. A reader who checked the Ecosystem Reserve address against the chain found under 1 AERE there and no explanation anywhere in this document.
The supply cap is unchanged and is not in question: 2,800,000,000 AERE, fixed at genesis-v2 on 2026-05-07, with no consensus-level minting on chain 2800 and no path in any contract in this spec that re-mints. What changed is location, not quantity. The Ecosystem Reserve allocation was moved off its genesis address, which is why that row reads under 1 AERE and why the six addresses fall 560,000,009.3 AERE short of the cap. Of that difference, 559,999,999 AERE is held at a **single separate account** on chain and the remaining 10.3 AERE is the fee spend of these six wallets since genesis. That last figure is a reconciliation of the allocation column against the balance column, not a traced sum of transactions, so treat it as **NOT MEASURED** as an independent number.
The receiving account is deliberately not named in this document. Nothing about the sum is hidden by that: the cap, the six balances, the shortfall and the amount held elsewhere are all printed above, and the arithmetic closes. Two things this spec also does **not** state, because they are not measured here: when the movement happened, and why. Public nodes retain roughly 500 blocks of state (measured at head: `eth_getBalance` 300 blocks back answers, 512 blocks back returns null), so the move cannot be re-derived from state through the public RPC today. Bringing that balance under the same governance handover as the rest of the protocol is an open roadmap item.
**Ownership: verified, not assumed.** Every Ownable contract in this spec is owned by the Foundation account `0x0243A4f47D44b40b65D33f20329dE20D00c6f3C3` (a single-key Foundation-controlled account, not a deployed multisig). Re-read at head on 2026-08-01: `owner()` returns that account on `AereCoinbaseSplitter` `0xb4b0eCe9…`, `AereCoinbaseSplitterV2` `0x8C1A48eF…`, `AereStakingV2` `0x1D95eF6D…`, `AereLockedStaking` `0x21108c28…`, `AereGovernanceStaked` `0x8D77C888…` and `AereLendingOracle` `0xc0f18A56…`. `AereSink`, `sAERE`, `AereFeeBurnVault`, `WAERE` and `AereSwapRouter` expose no `owner()` at all, consistent with the "no owner, no admin" claim made for them below. This paragraph is accurate as written; it was re-verified rather than carried forward.
The economic thesis is monotone: the burn path only ever removes AERE from circulation against this fixed cap, and no path re-mints.
## 2. The validator-coinbase burn split
### 2.1 V1: AereCoinbaseSplitter
Address: `0xb4b0eCe9011613A5b84248a9B42a0f309E6F01Ec` (owner = Foundation). Source: `AereCoinbaseSplitter.sol`.
A validator (or its forwarder daemon) calls `splitAndDistribute(validator)` or `splitToSelf()` with accumulated coinbase as `msg.value`. The contract atomically:
1. Sends `burnBps / 10000` of `msg.value` to `AereFeeBurnVault`.
2. Sends the remainder back to the validator address.
3. Increments cumulative counters (`totalBurned`, `totalDistributed`, and per-caller maps) and emits `Burned` / `Distributed`.
Parameters:
- `burnBps = 3750` (37.5%), matching whitepaper section 3.3.
- Owner-adjustable via `setBurnBps`, hard-capped at 5000 (50%). The whitepaper wording is "up to 37.5%"; the 50% cap gives headroom while bounding abuse.
- `burnVault` is owner-settable (`setBurnVault`, non-zero required).
The contract is `ReentrancyGuard`-protected and cannot custody funds across calls: every call fully dispatches `msg.value`. Anyone can call it (no burn allowlist), which is what lets a public explorer verify the deflation claim in O(1) reads from `burnStats()`.
Note on the word "sealed": the burn rate is not immutable. It is owner-adjustable inside `[0, 5000]` bps. The truly sealed component of the token economy is `AereSink` (section 4), which has no owner at all.
### 2.2 V2: AereCoinbaseSplitterV2
Address: `0x8C1A48eFA57b66fEE743A00E3899c29ad3Fd27b4` (owner = Foundation). Source: `AereCoinbaseSplitterV2.sol`.
V2 replaces the two-way split with a three-way split that adds the sink bucket, so a slice of every validator reward feeds the sAERE flywheel instead of returning entirely to the validator.
Buckets (basis points, owner-configurable within hard caps):
| Bucket | Default | Cap | Destination |
|---|---|---|---|
| `burnBps` | 3750 (37.5%) | `MAX_BURN_BPS = 5000` | `AereFeeBurnVault` |
| `sinkBps` | 1500 (15.0%) | `MAX_SINK_BPS = 3000` | `AereSink` (via WAERE) |
| `rebateBps` (derived) | 4750 (47.5%) | `10000 - burn - sink` | validator |
`setBps(_burnBps, _sinkBps)` enforces both caps and `burn + sink <= 10000`; `rebateBps` is a live-derived view. The sink share is routed by wrapping the native slice into WAERE (`IWAERE.deposit`), approving the sink, and calling `IAereSink.flush(WAERE, sinkAmt)` in the same transaction. If the sink call reverts, the whole split reverts and the validator retries.
Sink-rotation safety: the sink address is owner-settable but rate-limited. `proposeSink` starts a `SINK_CHANGE_TIMELOCK = 7 days` timer; `acceptSink` can only fire after it elapses; `cancelPendingSink` aborts. This gives validators seven days of warning before any sink swap.
Important operational caveat, stated honestly: the V2 constructor leaves `sink` unset. Until `proposeSink` + `acceptSink` wire a live sink, V2 behaves like V1 (the 15% sink slice is folded into the rebate, `sinkAmt = 0`). This spec documents the configured three-way design; whether the live V2 currently has its sink accepted and pointed at `AereSink` `0x69581B86A48161b067Ff4E01544780625B231676` is a Foundation operational state to confirm on-chain, not an invariant of the code. Validators migrate from V1 to V2 by repointing their off-chain forwarder daemon; V1 stays deployed and continues to honor V1 burn behavior for any flow still hitting it.
### 2.3 Deflation math (V2 default, worked)
For a validator coinbase reward `R` under the V2 defaults and the sink's 15/40/45 configuration (section 4):
- Direct burn: `0.375 R`.
- Sink input: `0.15 R`. Inside the sink, BURN (15%) plus BUYBACK (40%) are both AERE-destroying, so `0.55 x 0.15 R = 0.0825 R` is burned, and STAKER-YIELD (45%) sends `0.45 x 0.15 R = 0.0675 R` to sAERE holders. This arithmetic holds because coinbase reward `R` is native AERE, which the splitter wraps to WAERE, so the sink takes the no-swap branch and merges BURN and BUYBACK into one transfer. For a **non-AERE** inflow the BUYBACK leg cannot execute at all, because `AereSink.DEX_ROUTER()` is `0x…0001` and immutable; see Section 2.1. The `0.0825 R` figure is therefore correct for the coinbase path and must not be generalized to arbitrary fee tokens.
- Rebate to validator: `0.475 R`.
Aggregating:
- **Total burned: 0.4575 R (45.75%).**
- **Total to stakers (sAERE): 0.0675 R (6.75%).**
- **Rebated to validator: 0.475 R (47.5%).**
- Protocol-directed (not rebated): 52.5%.
The "~52.5% net deflation" figure in the V2 source comment counts the entire sink slice as protocol-directed. The stricter, more honest number for actual token destruction is 45.75%, because 6.75% of the reward becomes staker yield rather than being burned. Both are stated so a reader can pick the definition they mean.
All of the above are default and design parameters. `burnBps`, `sinkBps`, and the sink's internal split determine the real numbers; the sink split is a deploy-time immutable (section 4).
## 3. The burn endpoint: AereFeeBurnVault
Address: `0x696afDF4f814e6Fd6aa45CE14C498ed9375fB2c6`. Source: `AereFeeBurnVault.sol`. No owner, no admin.
A stateless sink with **no withdraw function and no admin escape hatch**. Native AERE arrives via `receive()` or `burn()`; ERC-20s arrive via `burnToken(token, amount)` (pull-via-approval). Counters `totalBurnedAERE` and `totalBurnedToken[token]` make deflation queryable in a single read.
Honesty on "obliteration": AERE that enters this vault is permanently removed from circulation because nothing can move it out. It is not literally sent to `address(0)` until someone calls the permissionless `sweepToZero()`, which forwards the whole native balance to `address(0)` (Besu QBFT permits this) and increments `totalSentToZero`. So there are two honest ways to describe the state: "removed from circulation on a no-withdraw contract" (always true on arrival) and "obliterated to the zero address" (true after `sweepToZero`). Both counters are exposed. ERC-20 burns stay on the contract forever (no zero-sweep for tokens).
## 4. The immutable flywheel: AereSink
Address: `0x69581B86A48161b067Ff4E01544780625B231676`. Source: `aere-contracts/contracts/sink/AereSink.sol`. **No owner, no admin, no setters, no pause, no upgrade proxy.**
`AereSink` is the single entry point for any protocol fee stream that should accrue to AERE holders. It splits every inflow across three buckets whose recipients and basis points are set once at deploy and are `immutable` thereafter. The constructor reverts unless `BURN_BPS + BUYBACK_BPS + STAKER_YIELD_BPS == 10000`.
Registry-documented deployed configuration: **15 / 40 / 45 (BURN / BUYBACK / STAKER-YIELD)**. Because these are constructor-set immutables, the specific values are not re-derivable from the source alone; the 15/40/45 figure is the canonical deployed split per the registry and the locked architecture design, and the code guarantees only that they sum to 10000 and can never change.
Buckets:
1. **BURN** (15%): transferred to `AereFeeBurnVault` on top of the splitter's 37.5%.
2. **BUYBACK-and-burn** (40%): non-AERE inflows are swapped to AERE via the DEX router, then sent to the burn vault. When the inflow is already AERE/WAERE (the normal case, since the splitter wraps before flushing), BURN and BUYBACK are merged into a single transfer to the burn vault, because buying AERE with AERE is a no-op.
3. **STAKER-YIELD** (45%): transferred (or swapped) into the `sAERE` vault. A raw transfer into an ERC-4626 vault lifts `totalAssets` without minting shares, so the exchange rate appreciates for all sAERE holders. This is the flywheel's connection from fees to stakers.
Entry point: `flush(token, amount)`. The caller approves the sink, then the sink pulls via `transferFrom`, computes the three parts (the staker part absorbs rounding residue so no dust accumulates on AERE inflows), and dispatches. After crediting the staker bucket it calls `sAERE.sync()` (best-effort) so the vault immediately begins linearly dripping the arrival rather than leaving a step-function price jump for a sandwicher to race.
Sandwich resistance on swaps: for non-AERE inflows, `amountOutMin` is computed from an external oracle price floor (`_computeOracleFloor`) rather than from the DEX pool reserves, because pool reserves can be manipulated by the same actor in one transaction. The oracle interface is compatible with `AereLendingOracle.getPrice`, normalized to 18 decimals, with an immutable `MAX_SLIPPAGE_BPS` tolerance. If the oracle is unset or reverts, the swap floor falls back to 1 (accept any non-zero output).
> **MEASURED, AND IT CHANGES THIS PARAGRAPH. The live sink is wired to neither.**
>
> Read on `AereSink 0x69581B86A48161b067Ff4E01544780625B231676` at head block 11,810,041:
>
> - `DEX_ROUTER()` returns `0x0000000000000000000000000000000000000001`
> - `ORACLE()` returns `0x0000000000000000000000000000000000000000`
>
> Both are **immutable**. An earlier revision of this paragraph named `AereSwapRouter 0x7526B2E5526EfA84018378b60F2844Dad77523D8` and `AereLendingOracle 0xc0f18A567067F1B84BDf75eDEbFaDdCBb70A4C49` as the sink's router and oracle. The sink is connected to neither, and because both fields are immutable, it cannot be connected to them without redeploying it.
>
> The consequences are exact and they are not small:
>
> 1. The **BUYBACK bucket, at 4,000 bps the largest of the three, cannot execute for a non-AERE token.** There is no reachable router to swap through. Confirmed alongside: `BURN_BPS() = 1500` and `BUYBACK_BPS() = 4000`, so the 15 / 40 / 45 split itself is real and correctly stated everywhere in this document.
> 2. The **oracle-derived sandwich floor described above is not active.** With `ORACLE()` at the zero address, the documented `_computeOracleFloor` path degenerates to the fallback of 1, which accepts any non-zero output. The protection is described in this spec and is not running.
>
> What still works exactly as written: the AERE and WAERE inflow path, which is the normal case, takes the no-swap branch, merges BURN and BUYBACK into one transfer to the burn vault, and needs neither router nor oracle. That is the path that has actually carried volume.
>
> This is a wiring gap on a contract whose immutability is, correctly, the credibility anchor of the whole design. Immutability cuts both ways: nobody can change the split under holders, and nobody can fix this without a redeploy and a rewire of fee sources. Both halves are true and both belong in the same paragraph.
Failure isolation: a failed swap (dead pair, slippage) does not revert the whole flush. The tokens stay as dust, a `SwapFailed` event fires, and the approval is cleared. Anyone can later call the permissionless `sweepDust(token)` to re-flush accumulated dust through the same three buckets. `flush` and `sweepDust` are both `nonReentrant`.
Immutability is the point. There is no `setBucket`, no `setRecipient`, no `setRouter`. If the router ever needs replacing, the sink is redeployed and fee sources are rewired. The absence of any admin key is the credibility anchor of the whole flywheel: holders can verify that the 15/40/45 split and the recipients cannot be changed under them.
Honest note on non-18-decimal tokens: the oracle floor math assumes 18-decimal tokens on both sides. A non-18-decimal fee token would be systematically mispriced by `_computeOracleFloor`; production integrations of exotic fee tokens should add a decimals-normalizing oracle wrapper. In practice the primary inflow is WAERE (18 decimals), which takes the no-swap path.
## 5. The liquid-staking receipt: sAERE
Address: `0xA2125bE9C6fd4196D9F94757Df18B3a2A5e650b0`. Source: `aere-contracts/contracts/staking/sAERE.sol`, an OpenZeppelin ERC-4626 vault over WAERE. **No owner, no admin, no pause, no upgrade proxy, no parameter setters.**
Depositors lock WAERE and receive sAERE. The WAERE-per-sAERE exchange rate drifts up as `AereSink`'s STAKER-YIELD bucket routes fees in. This is "real yield": it comes from protocol fee inflows, not from issuance, and the provider does not choose whether, when, or how much (once funds arrive they vest mechanically). There is no fixed APR; the rate is whatever the fee flow produces.
Linear drip (audit fix R5, HIGH-1). Yield is not recognized as a step function the instant the sink transfers AERE in. Arrivals are folded into a reward reserve that vests linearly over `DRIP_DURATION = 7 days`:
- `totalAssets()` returns the on-contract balance minus the still-unvested reserve, so share price grows continuously with time, not in blocks-sized jumps.
- `sync()` is permissionless and idempotent; it is also called inside every deposit and withdraw. It detects arrivals since `lastObservedBalance` and (re)computes `rewardRate` and `periodFinish`.
- Grief guard (audit fix R6, HIGH): a fresh drip period only restarts if arrivals are at least `DRIP_RESTART_THRESHOLD_BPS = 100` (1%) of the unvested reserve, or there is no active period. Tiny 1-wei-per-block arrivals only top up `rewardRate` without extending `periodFinish`, so a griefer cannot indefinitely stall stakers' vesting.
Killing this drip is what defeats the flash-loan sandwich (deposit, flush the sink, redeem in one block): the share price cannot jump within a block.
Inflation-attack moat (audit fix R5, HIGH-4). `_decimalsOffset()` is overridden from OZ's default 0 to 6, giving a 1e6 virtual-share offset, which is the primary defense against the classic ERC-4626 first-depositor inflation attack. A dead-shares seed is also minted to `0x…dEaD` at deploy. Honesty note for implementers: the contract's header comment describes a "1 WAERE" seed, but the compiled constant is `DEAD_SHARES_SEED_WAERE = 1000 wei`; the effective moat is the 1e6 decimals offset regardless of the seed size, so this documentation discrepancy does not affect safety.
Views for integrators: `pricePerShare()` (`convertToAssets(1e18)`), `undistributedRewards()`, and `atomicState()` (a single-block snapshot of balance, totalAssets, undistributed, supply, rewardRate, periodFinish, lastObservedBalance) for drift-free invariant checks.
Honest caveat on realized yield: sAERE only appreciates if fees actually flow through `AereSink`. With thin current usage, realized sAERE yield to date is minimal and should be read live from the exchange rate, not assumed. The mechanism is real and admin-free; the volume is early.
## 6. Staking-reward products
AERE has three distinct staking surfaces. They are frequently conflated; they are not the same and only sAERE is admin-free real-yield.
### 6.1 Delegated validator staking: AereStakingV2
Address: `0x1D95eF6D17aeAB732dF914Ba2d018c270BC155FC` (owner = Foundation). Source: `aere-contracts/contracts/staking/AereStakingV2.sol`. This is a bug-fix redeploy of V1 (`0xAbDb01d9A4f41792129b2654Fb6DDB9689360DEc`, deprecated, 0 validators / 0 staked / 0 balance). Do not use V1.
Model: token holders delegate native AERE to validators and earn APR; validators post a self-stake bond and take a commission on delegator rewards. **See "the bond is not slashable once a validator leaves" below before relying on the word bond.**
Parameters:
- `rewardRateBps = 800` (8% APR) default, **owner-settable** via `setRewardRateBps` in `[1, 10000]` bps. The registry flags this: the founder should confirm the intended live APR, since V1's effective rate was mis-scaled to roughly 1.6%.
- `MIN_VALIDATOR_SELF_STAKE = 500 ether` (500 AERE).
- `MIN_DELEGATION = 1 ether` (1 AERE).
- `UNBONDING_PERIOD = 7 days`.
- `SLASH_RATE_BPS = 500` (5% of self-stake per slash, owner-only `slash`, and **only while the validator is still active**; see the bond note at the end of this section).
- `MAX_COMMISSION_BPS = 5000` (50% cap on validator commission).
Accrual is timestamp-based: `reward = amount x rewardRateBps x secondsElapsed / (10000 x 365 days)`, which is immune to block-time changes (V1's bug divided by a hardcoded 0.1s-block count, underpaying roughly 5x). Every amount-changing path calls `_settle` first, so a top-up earns zero retroactive reward. Validator commission is split off gross and credited to `commissionAccrued`, claimable via `claimCommission`. Delegators claim via `claimRewards`; unbonding queues into a 7-day queue drained by `claimUnbonded`. A validator's own self-stake earns no reward; slashed AERE stays in the pool as surplus backing rewards, with no admin withdrawal of principal.
> **The self-stake is not a slashable bond once the validator chooses to leave. Correction of 2026-08-01.**
>
> An earlier revision of this line, and of the `SLASH_RATE_BPS` bullet above, described the self-stake as "a slashable bond". Read against the live `AereStakingV2` source, that overstates the guarantee, and the gap is the whole point of a bond.
>
> - `slash(address, string)` requires `v.active` and removes `SLASH_RATE_BPS = 500` bps of `v.selfStake`.
> - `deregisterValidator()` is permissive. It sets `v.selfStake = 0`, sets `v.active = false`, and pushes the **entire** self-stake into `unbondQueue`.
> - `slash` never touches `unbondQueue`.
>
> So the punishable amount is whatever the validator has left in `selfStake` at the moment the owner acts, and the validator decides that, unilaterally, by deregistering first. A bond that the bonded party can withdraw from the reach of the penalty is not a bond; it is a deposit with a notice period. The penalty is, in the operative sense, optional for the person being penalised.
>
> The accurate statement is: **`slash` removes 5% of a validator's self-stake for as long as that validator remains active, and stops being able to reach the self-stake the moment they deregister.** The 7-day unbonding queue delays withdrawal; it does not preserve slashability.
>
> Two measured facts that bound how much this matters today, and they are the reason this is written up rather than escalated: `totalStaked()` on `0x1D95eF6D…` is **0** and the contract's balance is **0** at head. Nobody has staked anything, so nobody is currently relying on this bond. That is a reason to fix the wording and the contract before there is stake, not a reason to leave the wording as it was.
>
> Confirmed by reading at head: `SLASH_RATE_BPS() = 500`, `UNBONDING_PERIOD() = 604800` seconds, which is 7 days exactly.
Honest funding caveat, stated in the source itself: rewards and commission are paid from this contract's native AERE balance. Because supply is fixed at 2.8B with no consensus-level minting, the pool must be seeded by the Foundation (out of genesis reserves) until protocol-level reward minting is wired to consensus, which is not built. `claimRewards` reverts with "pool insufficient (needs foundation top-up)" if the balance cannot cover the claim. So the 8% APR is a reserve-funded subsidy today, not native issuance.
### 6.2 Fixed-term locked staking: AereLockedStaking
Address: `0x21108c28A849b05aE6b7a3a5bc435C9Bc897E7Ad` (owner = Foundation). Source: `AereLockedStaking.sol`.
Users lock native AERE for a fixed term and earn a fixed APY paid in AERE at maturity. Early exit forfeits all reward and returns principal only.
| Tier | Duration | APY (`APY_BPS`) |
|---|---|---|
| 0 | 30 days | 10% (1000) |
| 1 | 90 days | 15% (1500) |
| 2 | 180 days | 22% (2200) |
| 3 | 365 days | 30% (3000) |
- `MIN_STAKE = 1 ether`, `MAX_STAKE = 100_000 ether` per lock.
- Reward = `principal x APY_BPS x duration / (365 days x 10000)`.
- Principal protection: `withdraw` reverts unless `balance >= total + totalPrincipal`, so other stakers' locked principal can never be drained to pay a maturity. The reward reserve is `balance - totalPrincipal`, seeded by the Foundation via `receive()` (anyone can donate).
Honest sustainability note: a 30% APY on a 365-day lock, funded from a finite Foundation-seeded reserve against a fixed 2.8B cap, is a subsidy with a runway, not a perpetual rate. It is safe (principal is protected, and maturities that the reserve cannot cover simply cannot be withdrawn until topped up), but it is not self-funding until real fee revenue through the sink is large enough to underwrite it. This is the core tension of a fixed-supply chain paying staking yield, and it is by design that the sink flywheel, not the reserve, is meant to be the long-run funding source.
### 6.3 Governance staking: AereGovernanceStaked
Address: `0x8D77C888e439C4fADb2e23F1567a0A1965F80bCb`. Source: `AereGovernanceStaked.sol`. Not a yield product; included for completeness because it reads staking state. Voting power equals the total AERE a holder has delegated across all validators in the staking contract (stake-to-vote). `PROPOSAL_THRESHOLD = 100000 ether`, `QUORUM_PERCENTAGE = 20%` of total staked, `VOTING_PERIOD = 7 days`, `EXECUTION_DELAY = 2 days`. The 7-day unbonding period makes vote-borrowing impractical.
## 7. End-to-end flywheel
```
validator coinbase reward R
|
v
AereCoinbaseSplitterV2 (37.5% burn / 15% sink / 47.5% rebate)
| | |
| | +--> validator (0.475 R)
| +--> wrap to WAERE --> AereSink.flush()
| | (sink 15 / 40 / 45; 55% burn-eq + 45% yield)
| +--> BURN 15% + BUYBACK 40% --> AereFeeBurnVault
| +--> STAKER-YIELD 45% --> sAERE (rate appreciates)
+--> AereFeeBurnVault (0.375 R, permanent)
```
Net per reward `R` (defaults): 0.4575 R burned, 0.0675 R to sAERE holders, 0.475 R rebated. The same `AereSink` is the intended router for other fee streams (fee-monetization, settlement, and similar), so as real usage grows, sAERE yield rises and burn accelerates without any parameter change and without any admin action, because the sink has no admin.
**Read that diagram as the design, not as a measured flow.** Three things bound it, all measured at head block 11,810,041 on 2026-08-01.
1. **The BUYBACK leg is drawn for a non-AERE inflow and cannot run for one.** `AereSink.DEX_ROUTER()` is `0x…0001` and immutable. For AERE and WAERE inflows, the normal case, the diagram is correct because that path never swaps.
2. **Almost nothing has gone through it.** `AereCoinbaseSplitter` (V1) reports `totalBurned() = 137,352,594,046,167,719` wei, which is 0.137352594046167719 AERE. That is the entire lifetime figure.
3. **"Burned" in that counter means "routed to the burn vault", not "destroyed".** `AereFeeBurnVault 0x696afDF4f814e6Fd6aa45CE14C498ed9375fB2c6` holds exactly 0.137352594046167719 AERE at head, byte-identical to the counter, and the zero address holds 0. So the full amount the counter calls burned is still sitting in the vault. The vault is a permanent endpoint with no withdrawal path, so the AERE is out of circulation in the economically meaningful sense, and it has not been destroyed in the ledger sense. Anyone reading `totalBurned()` should know which of those two they are being told. Both numbers are public and they agree; the label is what needed fixing.
## 8. Honest limitations and open items
- **Sink wiring on V2 is an operational state, not a code invariant.** The three-way split is only active once the Foundation runs `proposeSink` + `acceptSink` (7-day timelock) pointing V2 at `AereSink`. Confirm on-chain before quoting the 45.75% number as live.
- **Staking APRs are reserve-funded subsidies.** No consensus-level reward minting exists; `AereStakingV2` and `AereLockedStaking` pay from Foundation-seeded balances out of the fixed 2.8B. This is honest and on-strategy (no adaptive issuance), but it means the APR is bounded by the reserve until fee flow replaces it.
- **Splitter throughput depends on validators.** Burn only happens when validators route coinbase through the splitter. With seven validators under one operator, realized burn volume is early. Measured at head on 2026-08-01: lifetime `totalBurned()` is 0.137352594046167719 AERE, all of it currently held by `AereFeeBurnVault`.
- **The sink's buyback bucket and sandwich floor are not wired.** `AereSink.DEX_ROUTER()` is `0x…0001` and `ORACLE()` is the zero address, both immutable. The 40% buyback bucket cannot execute for a non-AERE token, and the oracle-derived minimum-output floor is not active. Section 2.1 has the detail. Fixing it means redeploying the sink and rewiring fee sources; there is no setter, by design.
- **The validator self-stake stops being slashable at deregistration.** `deregisterValidator()` moves the whole self-stake into the unbonding queue and `slash` does not reach the queue. Section 6.1 has the detail. `totalStaked()` is 0 today, so nobody is relying on it yet.
- **No external audit.** All fixes above are internal audit rounds (R5, R6, and the finding-numbered redeploys). The mechanisms are admin-minimized and reentrancy-guarded, but they have not had a third-party audit.
- **sAERE doc discrepancy.** The header comment says a 1 WAERE dead-seed; the constant is 1000 wei. Safety rests on the 1e6 decimals offset, so this is cosmetic, but it should be reconciled in a future redeploy or doc pass.
- **AERE `AereToken.sol` note.** The native token is AERE itself; `AereToken.sol` is only a governance-compatibility shim over WAERE. There is no separately mintable ERC-20 AERE.
## 9. Roadmap / in development
- **Consensus-wired reward minting is not built.** Long-term, staking rewards should be funded by protocol-level mechanics rather than reserve top-ups. Today this is explicitly a roadmap item (the staking source comments say "until protocol-level minting is wired to consensus"). Any such change must respect the fixed 2.8B cap; adaptive issuance is off-strategy and out of scope.
- **Fee-source expansion into the sink.** Broadening the set of contracts that `flush` into `AereSink` (beyond the coinbase splitter) is the primary lever to make sAERE yield and the burn self-sustaining. This is additive and requires no change to the immutable sink.
- **V1-to-V2 splitter migration completion.** Once all validators point their forwarder daemons at `AereCoinbaseSplitterV2`, V1 `burnBps` can be set to 0 and V1 retired.
## Appendix: address registry (verbatim, chain 2800)
| Contract | Address |
|---|---|
| WAERE | `0x7e84d7d66d5da4cfE46Da67CDEeB05B323e1f5e8` |
| AereCoinbaseSplitter (V1) | `0xb4b0eCe9011613A5b84248a9B42a0f309E6F01Ec` |
| AereCoinbaseSplitterV2 | `0x8C1A48eFA57b66fEE743A00E3899c29ad3Fd27b4` |
| AereFeeBurnVault | `0x696afDF4f814e6Fd6aa45CE14C498ed9375fB2c6` |
| AereSink | `0x69581B86A48161b067Ff4E01544780625B231676` |
| sAERE | `0xA2125bE9C6fd4196D9F94757Df18B3a2A5e650b0` |
| AereStakingV2 | `0x1D95eF6D17aeAB732dF914Ba2d018c270BC155FC` |
| AereStaking V1 (deprecated) | `0xAbDb01d9A4f41792129b2654Fb6DDB9689360DEc` |
| AereLockedStaking | `0x21108c28A849b05aE6b7a3a5bc435C9Bc897E7Ad` |
| AereGovernanceStaked | `0x8D77C888e439C4fADb2e23F1567a0A1965F80bCb` |
| AereSwapRouter (sink DEX router) | `0x7526B2E5526EfA84018378b60F2844Dad77523D8` |
| AereLendingOracle (sink swap-floor oracle) | `0xc0f18A567067F1B84BDf75eDEbFaDdCBb70A4C49` |
| Foundation (owner of Ownable contracts) | `0x0243A4f47D44b40b65D33f20329dE20D00c6f3C3` |
+245
View File
@@ -0,0 +1,245 @@
# AERE Network: Full-EVM Validity Rollup (revm-in-SP1)
**Chain:** AERE Network mainnet, chain ID 2800 (Hyperledger Besu QBFT). Measured mean block interval 0.5175 s over the 2,000 blocks to head 11,810,041 on 2026-08-01; seven validators, f=2, one operator.
**Status date:** 2026-08-01. Every on-chain figure (code size, owner, counters, route targets, balances, the EIP-2935 window) was re-read from `https://rpc.aere.network` at head block 11,810,041 on that date. Corrections found in that pass are stated inline, next to the sentence they correct, rather than applied silently.
**Source of truth for addresses:** `sdk-js/src/addresses.ts`. Contract source: `contracts/contracts/`. Guest/host prover: `rollup-evm-validity/`.
**Scope:** the REAL full-EVM validity path: a live chain-2800 block re-executed with `revm` inside the SP1 zkVM, its post-state root proven, and that proof verified on-chain through the SP1 gateway into the `AereEVMValidity` anchor. This document also states, honestly, what is and is not proven, and how this work supersedes the earlier bounded-VM proof of concept.
---
## 0. Honesty preamble (read this first)
Four points frame everything that follows.
1. **This is a proof-of-approach, not a production rollup.** What has been proven is that a REAL AERE mainnet block, executed with a real EVM (`revm`) inside a zkVM, reproduces the canonical post-state root, and that the resulting proof verifies on chain 2800. The proven block is small (one EIP-1559 transaction). It is not a large batch, and the anchor records isolated proven blocks rather than a continuous sequenced chain. No claim built on this should imply a full-throughput validity rollup exists today.
2. **The realism is the point.** The guest runs the actual `revm` execution stack (SP1-patched `reth` 1.9.3 / `revm`), not a hand-written subset. Full opcode set, call frames, `SLOAD`/`SSTORE`, `LOG`, EIP-1559 base-fee burn plus priority-to-coinbase, and the Cancun/Prague/Osaka system calls all execute and all affect the proven state root. This is the difference from the prior bounded-VM PoC (section 9).
3. **The anchors are now in the canonical registry.** `AereEVMValidity` (single block) at `0x1f2CB0ebDBb21500e99868DbF1dB3abCcDd7DF26` and its multi-block sibling `AereEVMValidityBatch` at `0x49D30a5999eA5b7f6eFf12196AB006316683Ff3C` are both live on chain 2800, have real proofs recorded, and are now promoted into `sdk-js/src/addresses.ts` (verbatim there). Both are immutable, admin-free, and permissionless to record.
4. **The crypto is classical, a known hedge.** SP1 Groth16 proves over BN254 and QBFT signs with classical keys, so this validity path is not itself post-quantum. AERE's post-quantum work (the verifier suite and the `AerePQC` hard-fork that also carries the native EIP-2935 lookback of section 8) is tracked separately.
---
## 1. What is proven (the theorem)
For a target chain-2800 block `B` with parent `P`, the SP1 Groth16 proof establishes:
> Executing block `B`'s transactions with `revm` (Cancun/Prague/Osaka rules per the chain-2800 genesis schedule) against the account and storage state committed by `P.stateRoot`, then re-rooting the resulting sparse Merkle-Patricia trie, yields a post-state root exactly equal to `B.header.stateRoot`.
The public values committed by the guest are exactly 224 bytes (`7 x 32`), ABI-encode compatible:
```
abi.encode(
uint256 chainId, // == block.chainid (2800)
uint256 blockNumber, // proven block height
bytes32 prevStateRoot, // parent block state root (pre-state anchor)
bytes32 postStateRoot, // proven post-execution state root == header.stateRoot
bytes32 txRoot, // header.transactionsRoot (binds the executed txs)
uint256 gasUsed, // total gas used by the block
uint256 numTxns // number of transactions executed
)
```
`txRoot` binds the proof to the canonical header's exact transaction set, `prevStateRoot` and `postStateRoot` bind it to the concrete pre-state and the post-state the real chain published, and `chainId` prevents cross-chain replay.
---
## 2. Architecture: host witness, guest re-execution, on-chain anchor
The pipeline has three stages, each with a distinct trust role.
```
chain-2800 node SP1 zkVM (guest) chain 2800 (on-chain)
--------------- ---------------- ---------------------
eth_getProof / block / code revm re-execute block SP1VerifierGateway
-> EthClientExecutorInput -> re-root sparse MPT -> 0x9ca479...70628
(host pre-flight revm) commit 224-byte pv -> AereEVMValidity anchor
```
- **Host (`rollup-evm-validity/host`).** Gathers the pre-state witness for block `B` from the live node using `rsp`'s `EthHostExecutor`, which drives `eth_getProof` plus block and code RPC. It runs `revm` once, off chain, against a proof-recording database and asserts the recomputed post-state root equals `header.stateRoot`. This pre-flight produces no proof, only the serialized witness (`EthClientExecutorInput`).
- **Guest (`rollup-evm-validity/guest`, ELF `aere-client`).** Re-executes the block with `revm` inside the zkVM via `rsp_client_executor::EthClientExecutor`, re-roots the trie, and commits the 224-byte public values. Execution only succeeds when the computed post-state root matches `header.stateRoot`; a mismatch panics and no valid proof exists.
- **Anchor (`AereEVMValidity`).** Verifies the Groth16 proof through the SP1 gateway and, on success, records the block. Verification is delegated entirely to the gateway; the anchor adds no trust of its own beyond binding the exact program.
The gateway `SP1VerifierGateway` at `0x9ca479C8c52C0EbB4599319a36a5a017BCC70628` is the same canonical SP1 verifier gateway used by the rest of AERE's zk stack, routed by the leading 4-byte selector `0x4388a21c` (SP1 v6 Groth16).
---
## 3. The guest: revm inside the zkVM (rsp / sp1-reth)
The guest is a thin driver around the `rsp` (sp1-reth) client executor. Its whole body is: read the bincode witness, capture the parent state root, transaction count and block number, build the chain-2800 `ChainSpec` from the embedded genesis, then:
```rust
let executor = EthClientExecutor::eth(chain_spec, input.custom_beneficiary);
let header = executor.execute(input).expect("EVM execution / state-root check failed");
```
`EthClientExecutor::execute` is real `revm`. It applies each transaction against the witnessed pre-state, charges gas, splits EIP-1559 fees (base fee burned, priority tip to the beneficiary), runs the pre/post-execution system calls, and folds the modified accounts and storage back into the sparse trie to recompute the root. The guest then commits `chainId`, `blockNumber`, `prevStateRoot`, `postStateRoot`, `txRoot`, `gasUsed`, `numTxns`.
**Version pinning.** The guest builds against `reth` tag `v1.9.3` and `sp1-zkvm =6.1.0` (this is the `rsp` / sp1-reth line tagged `reth-1.9.3-sp1-6.1.0`, not the old bounded toy VM). The precompile patches match `rsp`'s reference client so that in-guest hashing and signature recovery are zk-accelerated: `sha2`, `sha3` (Keccak for trie and `keccak256`), `k256` (`ecrecover`), `p256`, and `substrate-bn`, all from the `sp1-patches` forks. This is what keeps a full block's Keccak-heavy trie walk inside a tractable cycle budget.
**Program binding.** The anchor's immutable `PROGRAM_VKEY` is the SP1 verification key of exactly this guest ELF: `0x00d79882d2f72013ede3b1be9d44edcad08107858e00dded883fe3b02dbbb808`. Binding the vkey binds the exact `revm`-in-zkVM program; a proof from any other program is rejected by the gateway.
---
## 4. The witness path (eth_getProof, sparse MPT, re-root)
The guest never sees full chain state. It sees a witness: only the accounts and storage slots the block touches, each with the Merkle proof that ties it to `P.stateRoot`. The witness type `ClientExecutorInput` (patched in `rollup-evm-validity/rsp-patches/io.rs`) carries:
- `current_block` (the block `B` to execute),
- `ancestor_headers` (at least the parent, to supply `P.stateRoot` and the `BLOCKHASH` map),
- `parent_state` (an `EthereumState`: the state trie plus the per-account storage tries, populated from `eth_getProof`),
- `bytecodes` (the contract code the block executes),
- `genesis`, `custom_beneficiary`, `opcode_tracking`.
`witness_db` verifies the witness before execution: the provided `parent_state` must hash to `P.stateRoot` (`state_anchor() == state.state_root()`), and each account's `storage_root` in the state trie must equal the hash of its supplied storage trie. Reads during execution go through a `TrieDB` `DatabaseRef` that resolves accounts and storage by walking these witnessed tries (`state_trie.get_rlp`, `storage_tries[...].get_rlp`), so any slot the block reads must have been included in the witness with a valid proof, or execution fails. After execution the same trie machinery folds the writes back and recomputes the root. This is what makes the proof a validity statement over the real MPT rather than over an opaque snapshot.
`eth_getProof` is therefore the sole bridge between the live node and the proven computation. The witness is trustless in the sense that a wrong or incomplete witness cannot produce a passing proof: the pre-state root check, the per-account storage-root check, and the final post-state root equality each independently reject it.
---
## 5. QBFT header adaptations
AERE runs Besu QBFT, not proof-of-work or a beacon-chain layer, and this required exactly one honest adaptation to the stock `rsp` witness logic, isolated in `is_qbft_relaxed()`.
Under QBFT, the canonical block hash is **not** `keccak256(rlp(header))`, because the validator commit seals are excluded from the hashed header. Stock `rsp` links ancestor headers by asserting `keccak(rlp(parent)) == child.parent_hash`, which never holds on chain 2800. The patch relaxes **only** that ancestor parent-hash linkage assertion, and only for chain 2800:
```rust
fn is_qbft_relaxed(&self) -> bool {
matches!(&self.genesis, Genesis::Custom(c) if c.chain_id == 2800)
}
```
Everything that actually secures the state transition stays enforced:
- the `BLOCKHASH` map is still built from the canonical `child.parent_hash()` values, so the `BLOCKHASH` opcode returns real hashes;
- the parent state root is still checked against `parent_header.state_root()`;
- the post-state root is still asserted equal to `header.stateRoot`.
The relaxation removes a hash-shape assumption that is false under QBFT; it does not remove any check on the proven state transition. Other L1 fields QBFT lacks (parent beacon block root and blob base fee, both zero on chain 2800) are handled by the chain-2800 `ChainSpec` built from genesis, consistent with the live node.
---
## 6. The on-chain anchor: AereEVMValidity
`AereEVMValidity` (source `contracts/contracts/parallel/AereEVMValidity.sol`) is deployed at `0x1f2CB0ebDBb21500e99868DbF1dB3abCcDd7DF26` (canonical in `sdk-js/src/addresses.ts`; recorded in `contracts/deployments/evm-validity.json`, deploy tx `0x22284d1d...15e51b`, deploy block 9074452, an operational deployment account). A multi-block sibling, `AereEVMValidityBatch` at `0x49D30a5999eA5b7f6eFf12196AB006316683Ff3C` (also canonical), records a contiguous batch of real blocks in one Groth16 and is documented in Section 7.1.
Design:
- **Two immutables, no admin.** `SP1_VERIFIER` (the gateway) and `PROGRAM_VKEY` are fixed at construction. There is no owner and no upgrade path. Recording is permissionless. Soundness rests entirely on the Groth16 proof plus the vkey binding.
- **Verify-then-record.** `recordBlock(publicValues, proof)` requires `publicValues.length == 224`, calls the gateway's `verifyProof(PROGRAM_VKEY, publicValues, proof)` inside a `try/catch` that translates a revert into a typed `InvalidProof()`, decodes the seven fields, checks `chainId == block.chainid`, enforces one record per block number, then stores the `ProvenBlock` and updates `latestPostRoot`. A `verify(...)` view offers the same gateway check statelessly for callers who only want to validate without recording.
- **What it does not do.** It does not chain records (there is no `prevRoot == latestRoot` continuity check, unlike the bounded-VM anchor of section 9), and it does not settle withdrawals or sequence a rollup. It is an attestation log of individually proven real blocks.
The trust boundary is stated in the contract's own header comment: this proves REAL EVM execution of a small live block as a proof-of-approach, and records isolated proven blocks rather than a continuous sequencer chain.
---
## 7. Measured results
Two real chain-2800 blocks were proven end-to-end with the server's SP1 v6.1.0 CPU prover (`SP1_PROVER=cpu`, `RAYON_NUM_THREADS=16`, native gnark Groth16). Both blocks carry one real EIP-1559 transaction performing an `SSTORE` plus `LOG` contract call at roughly 33.6k gas, roughly 1.18M RISC-V cycles in the guest, a fresh Groth16 produced in about 533s of CPU time, with peak resident memory about 27.7GB and no out-of-memory.
The block committed on-chain and captured in the repo artifact (`contracts/deployments/evm-validity-proof.json`) is **block 9073073**:
| Field | Value |
| --- | --- |
| chainId | 2800 |
| blockNumber | 9073073 |
| prevStateRoot | `0x31921701d25cb1791d47c0af23b0d84e6f6cdfdd3234a8643638854e588ae5eb` |
| postStateRoot | `0x0403c73b02f82a4e25ddde929995995b624ceb9384a50e0c31755099b5346636` |
| txRoot | `0x00e9301708e05258def41ed6a8ec9523ba98b6ffc5945316e9180c841f5b4864` |
| gasUsed | 33601 |
| numTxns | 1 |
| guest cycles | 1,181,363 |
| proof selector | `0x4388a21c` |
| proof bytes | 356 |
| public values bytes | 224 |
It was recorded on-chain by `recordBlock` in tx `0xb28a39507f8c03e6ffcfed307f9848814dd9d35268f01983825b658cbc56415c` (submit block 9074454, status 1), gas used 460,015 against an estimate of 464,833, comfortably under the EIP-7825 per-transaction cap of 16,777,216. That record cost is dominated by the fixed Groth16 pairing check in the gateway and is essentially independent of the block's own gas or transaction count. A second, freshly produced block, **9075035**, was proven with the identical profile during the same session, demonstrating repeatability on a block mined after the anchor was deployed. Every proof is also tamper-tested: flipping one byte inside `postStateRoot` in the public values makes the on-chain-equivalent `sp1_verifier::Groth16Verifier` reject it, confirming the proof binds the committed root.
---
## 7.1 Batch proofs and the dense-workload result (density caveat removed at demonstrated scale)
Two extensions build directly on Section 7 and are documented here rather than left implicit.
**The multi-block batch anchor, `AereEVMValidityBatch` (`0x49D30a5999eA5b7f6eFf12196AB006316683Ff3C`, canonical).** A sibling anchor records a contiguous batch of real chain-2800 blocks in one Groth16 proof. The batch guest threads each block's recomputed post-state root into the next block's pre-state and re-roots the sparse trie, so the proof verifies only when the final recomputed post-state root equals the canonical `header.stateRoot` of the last block. Its `PROGRAM_VKEY` binds the exact batch guest ELF (`0x00418c4f40178103cc75ae57b63703f6075cabdce23582fed6043ceae819192e`) and differs from the single-block vkey; the 256-byte public values carry `(chainId, firstBlock, lastBlock, numBlocks, prevStateRoot, postStateRoot, totalGas, numTxns)`. A real 16-block batch, chain-2800 blocks **9111008..9111023**, was recorded on-chain via `recordBatch` in tx `0x074a4e6c17855b78db4c56808e253d4c00a7b392cf0d141e4aa0e6e299ded9ec` (submit block 9114536, status 1), gasUsed 460,817, under the cap. Like the single-block anchor it is immutable and admin-free.
**The dense-workload proof (removes the "low tx density" caveat at demonstrated scale).** Historical mainnet blocks are low-density and the live node prunes state (Bonsai), which capped earlier witnessable batches at a handful of transactions (the prior batch was 2 txs across 16 blocks). To show that a genuinely dense real-EVM block is provable and gateway-acceptable, a dense workload was generated on a throwaway single-validator node running the AERE fork profile (chain-config 2800) in archive mode so all touched state is witnessable via `eth_getProof`, and proven with the same real revm-in-SP1 batch prover against the same batch-program vkey:
- A single ultra-dense block of **155 real transactions and 460 SSTOREs** (52 freshly created EOAs, 52 fresh ERC-20 holder slots), 29,572,987 guest cycles. Local SP1 Groth16 verify PASS, tampered `postStateRoot` REJECTED. Verified read-only against the live mainnet SP1 gateway `0x9ca479C8c52C0EbB4599319a36a5a017BCC70628`: the real proof was accepted and both a tampered-public-values and a tampered-proof call reverted.
- A 2-block contiguous, state-continuity-chained dense batch (310 txs, 920 SSTOREs, 27,050,310 gas, 61,366,308 cycles; the guest enforces `post_root(N) == header.stateRoot` and `pre_root(N+1) == post_root(N)`), same live-gateway acceptance read-only with both tampers reverted.
Honest label: this dense chain is an isolated, engineered workload, NOT a replay of historical mainnet blocks; verification against the live gateway was `eth_call` only, no mainnet transaction was sent. Compatibility was confirmed by the guest reproducing Besu 26.4.0's exact `header.stateRoot` for every dense block, the same agreement already established on real chain-2800 blocks (Section 7). What it establishes is that the approach scales to dense, fully-witnessable blocks; the practical ceiling on the box used was about two full-density blocks (~61M cycles) before proving went swap-bound, so a longer dense batch is a prover-resource matter, not an approach question.
**Canonical-binding V2 is DEPLOYED and has recorded nothing. Correction of 2026-08-02.** An earlier revision of this paragraph said the V2 layer "is STAGED, not deployed" and "MUST NOT be deployed yet". That is measurably wrong at head: `AereEVMValidityV2` `0x4884ad6617e320735b65D31915d1aBC884768D9B` carries **2,852 bytes** of live code and `AereEVMValidityBatchV2` `0xe154B8993FB54dB4418e03ef4a04894f29E690aE` carries **3,425 bytes**, both in the canonical registry, read from `https://rpc.aere.network`. What the V2 layer does is unchanged: an updated guest commits `blockHash` + `parentHash` and enforces `prevStateRoot == parent.stateRoot` inside the circuit, closing the canonicity gap of Section 8 by requiring the committed `blockHash` to equal the on-chain canonical hash of that block number. The honest status is therefore the opposite shape of the old one: the contracts exist and the proving side has not caught up. `provenCount()` reads **0** on both V2 anchors and **1** on each V1 anchor, so every real recorded proof today still sits on V1. The changed public-values layout changes the SP1 vkey, so the guest must be re-proved end to end against the deployed V2 vkey before anything can be recorded there. Until that happens, the strongest thing actually proven on chain remains the V1 record, and V1 never claims a record is the canonical chain-2800 block. See `rollup-evm-validity/NOTE.md` and `dense-batch-2026-07-11/NOTE.md`.
---
## 8. Canonicity of the pre-state root (honest gap and the fix)
The proof establishes `postStateRoot` given `prevStateRoot`. It does not, by itself, establish that `prevStateRoot` is the canonical parent state root of the real chain. For the two blocks above, both roots were cross-checked by the host against the live node's headers, so the records are genuine, but a permissionless caller could in principle record a proof over a self-chosen pre-state. Closing that gap trustlessly is the job of the anchoring layer, which has two live-adjacent pieces:
- **`AereStorageProofVerifierV2`** at `0x487021f9aE018657B7335ADC6Fc254717751a1Dd` (3,160 bytes live) proves a value at an account slot against a **given** state root, with the same caveat that canonicity of that root is the caller's responsibility. Its `CANONICAL_ANCHOR()` returns `0x0b959402283c0D2B9db4FfD7823f99782462e488`, read at head.
**Do not use V1 `0xF9a1A183bEb3147D88dA5927301683fEbFb9362E`.** An earlier revision of this bullet named that address with no qualification. The canonical registry calls it `AereStorageProofVerifier_DEPRECATED_POISONABLE` and says literally "DO NOT read `getProven()` as canonical; repoint to V2": because `blockNumber` is only metadata to the verifier, a genuine proof against a non-canonical root can overwrite a record key with a value that was never in the canonical chain. V2 binds to the anchor above and closes that.
- **`AereHistoryStateRootAnchorV2`** at `0x4C1F9daD515c7990b65F9833960CA4315216330C` (2,915 bytes live, `addresses.ts` line 391) recovers a canonical block hash from the native EIP-2935 history-storage system contract at `0x0000F90827F1C53a10cb7A02335B175320002935` via `STATICCALL`, re-derives the header state root from the RLP header, and anchors it. Its `HISTORY_STORAGE_ADDRESS()` returns that same system-contract address, read from chain at head. On the AERE Besu fork the ring buffer is written by QBFT consensus itself at the start of every block (a system call, no keeper, no Foundation key), so the value is produced by consensus exactly like `BLOCKHASH` but with an 8,191-block reach instead of 256, roughly 71 minutes of trustless lookback at the measured 0.5175 s block interval.
**Correction of 2026-08-01: this anchor is no longer scratch-only, and the fork it was waiting for has landed.** An earlier revision described it as "scratch-only so far, bundles into the `AerePQC` hard-fork for mainnet", and proven only on scratch chain 28099. The AerePQC fork activated on mainnet 2800 at block 9,189,161 (timestamp 2026-07-12T01:37:52Z), the EIP-2935 system contract carries **83 bytes** of code at head, and the window was measured end to end on mainnet: reads at 1, 255, 256 and 8,190 blocks behind head each returned exactly the canonical hash `eth_getBlockByNumber` reports for that height, and 8,191 and beyond revert.
**One loose end, stated because it is ours.** `AereHistoryStateRootAnchorV2.VERIFIER()` returns `0xF9a1A183…`, the deprecated storage-proof verifier named above. Until that is repointed at `0x487021f9…`, the extended-lookback path terminates in a record we ourselves call poisonable, and should not be treated as a canonical record path.
The two are complementary: the validity proof says "this pre-state deterministically yields this post-state," the anchor says "this state root is canonical for this height." A production system would require the recorded `prevStateRoot` to be an anchored canonical root before accepting the transition. That wiring is future work, called out here rather than hidden.
---
## 9. How it supersedes the bounded-VM proof of concept
The prior anchor, `AereRollupValidity` at `0x38772063572DF94E90351e44ccbBEefD5F497fbd` (source `contracts/contracts/parallel/AereRollupValidity.sol`), is a **real** validity proof, but of a **bounded** virtual machine. Its guest implements only four transaction kinds (`Transfer`, `Sweep`, `Increment`, `AmmSwap`) over a balance-and-storage map, with a hand-ported `execute_txn` and Keccak state-root folding taken verbatim from AERE's `parallel-executor`. It commits 160-byte public values (`chainId`, `prevRoot`, `postRoot`, `batchHash`, `numTxns`) and, notably, it **does** chain: it enforces `prevRoot == latestRoot` and advances a canonical tip, recording epochs. Epoch 0 is on record from a real proof.
`AereEVMValidity` supersedes it on the axis that matters most, execution fidelity:
| Dimension | `AereRollupValidity` (bounded PoC) | `AereEVMValidity` (full-EVM) |
| --- | --- | --- |
| VM | 4 fixed tx kinds over a map | real `revm`, full opcode set |
| Input | synthetic batch encoding | REAL chain-2800 block + header |
| State model | custom balance/storage map | real account and storage MPT via `eth_getProof` |
| Fees / system calls | none | EIP-1559 split, Cancun/Prague/Osaka system calls |
| Public values | 160 bytes | 224 bytes (adds `blockNumber`, `txRoot`, `gasUsed`) |
| Continuity | chains via `latestRoot` | isolated records (deliberately, for now) |
The bounded VM could never prove that real EVM bytecode on the real chain reproduces the canonical root, because it does not run the EVM. The full-EVM anchor does exactly that. The trade made along the way is that the full-EVM anchor currently drops the continuity chaining the bounded anchor had, because at proof-of-approach stage you prove individual real blocks, not a sequenced batch chain. The continuity and finalization machinery in `AereRollupValidity` is the template to re-add when moving to a production sequencer, this time over real EVM blocks.
---
## 10. Honest scope versus a production sequencer or rollup
What exists today: a real `revm`-in-zkVM guest that re-executes a real chain-2800 block and proves the canonical post-state root; a host that gathers the `eth_getProof` witness and pre-flights execution; an immutable, admin-free on-chain anchor that verifies the Groth16 proof through the canonical SP1 gateway and records the block; and two real blocks proven end-to-end (9073073 recorded on-chain, 9075035 proven fresh) with measured cycles, gas, proving time and memory, plus a passing tamper test.
What does **not** exist yet, stated plainly:
- **Batch scale.** The low-tx-density caveat is now removed at demonstrated scale: dense blocks of 155 txs / 460 SSTOREs each are provable and live-gateway-acceptable, single and 2-block-chained (Section 7.1), and a real 16-block batch is recorded on-chain via `AereEVMValidityBatch`. What still does not exist is a continuous production cadence: proving is single-box CPU and swap-bound past about two full-density blocks (~61M cycles), so a long dense batch or blocks packed to the gas limit motivates GPU proving and proof partitioning, and the anchors still record isolated proven blocks and ranges rather than a sequenced rollup chain.
- **A sequencer.** There is no mempool, ordering service, or forced-inclusion path. The system proves blocks the QBFT chain already produced; it does not sequence a separate rollup.
- **Continuity and settlement.** The anchor records isolated blocks with no `prevRoot == latestRoot` chaining and no withdrawal or bridge settlement. There is no fraud/validity dispute lifecycle beyond "the proof verified."
- **Canonical pre-state binding.** As in section 8, the recorded `prevStateRoot` is not yet required to be an anchored canonical root on-chain.
- **Data availability.** The witness is gathered from a trusted node; there is no DA commitment or sampling for third-party reconstruction.
- **Audit and decentralization.** The contracts are unaudited by an external party, and chain 2800 runs seven QBFT validators under a single operator. The prover is a single CPU box.
None of these gaps is hidden in the contract, the artifacts, or this spec. The correct one-line summary is: **AERE can prove a real EVM block of its own mainnet in zero knowledge and verify that proof on-chain, as a proof-of-approach; it is not yet a throughput-grade validity rollup.**
---
## 11. Path to production
The credible sequence from here, each step building on a demonstrated capability:
1. **Fuller blocks.** Prove blocks with many transactions and near-limit gas, measuring the cycle and memory curve. This is the first honest scaling test.
2. **Continuity.** Re-introduce the `prevRoot == latestRoot` chaining from `AereRollupValidity`, over real EVM blocks, so records form a verified chain rather than a set.
3. **Canonical pre-state binding.** Require the recorded `prevStateRoot` to be an anchored canonical root, by wiring `AereEVMValidity` to `AereHistoryStateRootAnchorV2` at `0x4C1F9daD515c7990b65F9833960CA4315216330C`. **The blocker an earlier revision named for this step is gone:** it said the work waited on that anchor "once that anchor ships in the `AerePQC` fork on mainnet", and the fork shipped at block 9,189,161 with EIP-2935 live. The anchor is deployed and registered. What remains is the wiring itself, plus repointing that anchor's `VERIFIER()` off the deprecated `0xF9a1A183…` and onto `AereStorageProofVerifierV2 0x487021f9…`.
4. **Aggregation.** Fold many per-block validity proofs into one Groth16 via `AereProofAggregatorV2` at `0x944dE720D6C9696Bdf10b6E2F00dd21ABB1A2b4C` (4,663 bytes live, `addresses.ts` line 396). **Not** via `0x6a260238890E740dB12b371E0C5d17a2470F84C5`, which an earlier revision named here without qualification: the canonical registry calls that one `AereProofAggregator_DEPRECATED_UNENFORCED_INNER_VKEYS`, because it counted recognized inner programs without requiring them to be registered. The n=10 demonstration cited below was recorded on V1 and is real as a demonstration of recursion (record tx `0xd1fd4d60...9344d978`, recorded gas roughly 394k, essentially flat in N); the contract to build on is V2, which rejects an unregistered inner program. Measured at head: V1 `aggregationCount` = 2, V2 `aggregationCount` = 1.
5. **DA and sequencing.** Add a data-availability commitment and, only if a distinct rollup is warranted, a sequencer with forced inclusion.
6. **Proving cost.** Move from single-box CPU proving toward GPU and partitioned proving as block size grows.
The engineering already on chain (the SP1 gateway, the aggregator at scale, the EIP-2935 native lookback, the storage-proof verifier) makes these integration steps over demonstrated parts, not research from zero. The honest limit is that the integration has not been done yet.
---
*Every address here is printed verbatim from `sdk-js/src/addresses.ts`. **Copying the hex is not the same as copying the status**, and an earlier revision of this line claimed more than it delivered: it said every address was printed verbatim from the registry, which was true, while leaving two of them (`0xF9a1A183…`, `0x6a260238…`) presented as current when the registry marks both deprecated. Every deprecated address in this document is now printed with its label and its replacement. The EIP-2935 system-contract address is a protocol constant. Figures from the repo artifacts and the session prover run are marked as such; code sizes, counters and the EIP-2935 window were re-read from `https://rpc.aere.network` on 2026-08-01 at head block 11,810,041. None are invented.*
+269
View File
@@ -0,0 +1,269 @@
# AERE Network Subsystem Spec: Identity and Compliance Stack
Status: mixed (live contracts on mainnet plus in-development pieces, marked inline)
Chain: AERE Network, chain ID 2800 (Hyperledger Besu QBFT; measured mean block interval 0.5175 s over the 2,000 blocks to head 11,810,041 on 2026-08-01; seven validators, f=2, commit quorum 5 of 7, one operator)
Source of truth for addresses: `sdk-js/src/addresses.ts`
Source of truth for logic: `contracts/contracts/compliance/*.sol`, `contracts/contracts/AereIdentity.sol`, `zk-circuits/`
## 0. Honest preamble (read this first)
This stack is the identity and regulatory-compliance layer of AERE Network. Before any of the design below, three facts about the environment it runs in must be stated plainly, because they bound how much trust any reader should place in it:
1. AERE is currently operated by the Foundation as a small validator set (seven QBFT validators, one operator, one client implementation, Besu). It has not had an external security audit. Several of the compliance contracts here have zero or near-zero live usage (for example the privacy pool holds 0 deposits at the time of writing). We treat these as honest facts, not as things to hide.
2. Every piece of this stack lives at the application and account layer. None of it changes consensus. Validators sign classical QBFT messages. The identity and compliance contracts are ordinary EVM contracts that apps opt into.
3. Many of the "trust-minimized" claims below reduce to "trust the AERE Foundation to publish honest roots, and rely on an optimistic challenge window to catch it if it does not." Where that is the case we say so, and we describe exactly what a challenger can and cannot do.
A second theme runs through the whole document and deserves to be named up front: the difference between an inclusion proof and an absence proof. Most of the cryptography here proves that something IS in a set (an address is on a sanctions list, a credential is in an issuer's tree, a note is in a Foundation-attested "clean" set). Proving that something is NOT in a set is a fundamentally harder primitive, and where we do not have it, we say so rather than implying we do.
## 1. Architecture
The stack has three tiers:
- On-chain anchors (the Solidity contracts). These store roots, hashes, commitments, and boolean flags. They never store personally identifying information (PII). The one exception in spirit is `AereIdentity`, whose claims are plaintext booleans on-chain (no PII, but the fact that address X holds a "KYC_TIER_1" claim from attestor Y is public).
- Off-chain attestation and ingestion. The Foundation and third-party issuers run off-chain jobs that build Merkle trees (OFAC list, issuer credential sets, association sets) and publish roots through Foundation-gated calls.
- Zero-knowledge provers. SP1 zkVM (Succinct Labs) guest programs prove attribute statements (over-18, jurisdiction, clean-set membership) off-chain; the resulting Groth16 proofs are verified on-chain through the shared `SP1VerifierGateway` at `0x9ca479C8c52C0EbB4599319a36a5a017BCC70628`.
The contracts, all owned by (or gated to) the Foundation account `0x0243A4f47D44b40b65D33f20329dE20D00c6f3C3` (a single-key Foundation-controlled account, not a deployed multisig) where they have an owner.
**Re-verified on chain, 2026-08-01, head block 11,810,041.** `owner()` returns that Foundation account on `AereIdentity 0x658dD2CD…`, `AereZKScreen 0x3A097A45…`, `AereSanctionsRegistry 0xb7d23571…`, `ChainalysisOracleWrapper 0x1B7Be82C…` and `AereForensicEventRegistry 0x4a7526A0…`. `AereTravelRuleHashRegistry`, `AereCompliancePoolV2`, `AereCompliancePoolSP1Verifier` and `AereAttestationGateway` expose no `owner()` at all, which is consistent with the "where they have an owner" qualifier above. This paragraph is accurate as written and was checked rather than carried forward.
| Contract | Address | Role |
|---|---|---|
| AereIdentity | `0x658dD2CD1F798AAb19fEc8FF69A270B2d192CaD1` | DID and revocable-claim registry |
| AereZKScreen (v3) | `0x3A097A459FD26aC79573aCB5adB51430e473C2f1` | ZK attribute-proof anchor |
| AereSanctionsRegistry | `0xb7d235718D99560F6EA4Fc5eAea2F8a306A3Cacf` | OFAC SDN Merkle registry |
| ChainalysisOracleWrapper | `0x1B7Be82C80f368f75Cb3807B1bc05E86A498f85c` | Forwarding sanctions oracle |
| AereForensicEventRegistry | `0x4a7526A068e5DDE9788f6571E4A99095b14C6fff` | Forta-style detection-bot alerts |
| AereTravelRuleHashRegistry | `0xcF0E2e010E6e4506672019b1e570874AEeBC4c84` | FATF Travel Rule hash anchor |
| AereCompliancePoolV2 | `0xB144c923572E5Ac1B6B961C4ccfec36917173465` | Compliant privacy pool |
| AereCompliancePoolSP1Verifier | `0xE2D3fa91b680E835c971761ba75Fde0204AEF95E` | SP1 adapter for the pool |
| AereAttestationGateway | `0x9bdacA8dfF39Fc688e8D3c4bbA13bCFC0580c325` | Regulator-attestation schema registry |
## 2. AereIdentity (live)
Address `0x658dD2CD1F798AAb19fEc8FF69A270B2d192CaD1`, owner Foundation. Solidity `^0.8.19`. This is the oldest and simplest contract in the stack, deployed 2026-05-07 with the core batch.
It is a lightweight on-chain DID registry, compatible in spirit with W3C DID and ERC-1056. Three primitives:
- Profiles. `setProfile(string uri)` lets any address point at a content-addressed profile document (for example `ipfs://...`). Only the pointer and a timestamp live on-chain.
- Attestors. The owner maintains an allowlist (`isAttestor`) of trusted issuers (KYC providers, employers, communities). `addAttestor` / `removeAttestor` are owner-only.
- Claims. An attestor calls `issueClaim(subject, claimType, expiresAt, evidence)`. `claimType` is a keccak256 tag, for example `keccak256("KYC_TIER_1")`, `keccak256("AGE_OVER_18")`, `keccak256("EMAIL_VERIFIED")`. `evidence` is an optional hash of an off-chain document. Claims are keyed `subject -> claimType -> attestor`, so a subject can hold the same claim type from several attestors independently. `revokeClaim` lets the issuing attestor (and only the issuer) revoke. `hasValidClaim(subject, claimType, attestor)` returns true if the claim exists, is not revoked, and is not expired.
Honest scope and limitations:
- Claims are plaintext booleans on-chain. `AereIdentity` reveals that a given address holds a given claim type from a given attestor. It is a transparency-positive, privacy-negative design. It is appropriate for public credentials (DAO membership, "email verified") and inappropriate for anything a user would want to keep private (residency, exact KYC tier). The zero-knowledge path for sensitive attributes is `AereZKScreen` (Section 3), not this contract.
- The evidence field is a bare hash with no schema. `AereAttestationGateway` (Section 10) is the newer, schema-versioned, inheritance-aware successor for structured attestations; `AereIdentity` remains the simple key-value DID layer.
- Ownership is a single `owner` address (the Foundation), not a per-claim governance model. There is no on-chain dispute path for a bad claim beyond the issuer's own `revokeClaim`.
Roadmap: a thin adapter that lets a dApp read an `AereZKScreen` clearance and an `AereIdentity` claim behind one interface is planned but not deployed. Today they are queried separately.
## 3. AereZKScreen v3: zero-knowledge attribute proofs (live anchor; over-18 program REGISTERED and armed)
Address `0x3A097A459FD26aC79573aCB5adB51430e473C2f1` (v3), owner Foundation, SP1 verifier fixed at deploy to the gateway `0x9ca479C8c52C0EbB4599319a36a5a017BCC70628` (SP1 Groth16, selector `0x4388a21c`). Deploy tx `0xf527bdcf1ccdbf41db27237b1004699335078a66f6a04a630554bbd2e1b468f5`, deployed 2026-07-07. This is a Privacy-Pools-style compliance anchor: it records that a user passed an off-chain screen without any of the source data touching the chain.
### 3.1 Model
The Foundation registers "programs." A program is one compliance statement, identified by its SP1 `programVKey` (the verification key of a specific guest circuit). Examples the design targets: an over-18 attribute proof, an EU-jurisdiction / MiCA-eligibility proof, an accredited-investor proof, an OFAC-screen proof. A user runs the corresponding SP1 program off-chain, produces a Groth16 proof, and calls `submitProof(programVKey, publicValues, proof)`. On success the contract stamps `clearedAt[user][programVKey]`. dApps gate access by reading `isCleared(user, programVKey, minTimestamp)`.
The public-values convention is exactly `abi.encode(uint256 chainId, address user, uint256 attestedAt, bytes32 extraDataHash)`, a fixed 128 bytes. `submitProof` enforces the exact length (rejecting trailing-byte spoofs), checks `chainId == block.chainid`, checks `user == msg.sender`, and rejects a proof whose `attestedAt` is in the future or older than the current stored clearance (stale-proof downgrade protection).
### 3.2 The root-binding soundness fix (why v1 and v2 are dead)
This is the most important design decision in the contract, and it is worth being candid that the first two deployments got it wrong.
- v1 `0xE9da9c5F40c2CDfda368885832C59609286e04ee` (dead): declared the SP1 verifier interface as `returns (bool)`. The real SP1 gateway returns nothing and reverts on an invalid proof, so decoding a bool from empty returndata reverted even for valid proofs. `submitProof` could never succeed. Fixed in v2 with a void interface plus try/catch.
- v2 `0x140572e018C0342336dbaAa1713281c15678aFa7` (dead, self-clear hole): the proof commits an `extraDataHash` interpreted as the allowlist Merkle root the screen was checked against. Because the prover supplies that root inside the zkVM, anyone could prove membership in a root of their own making (an "allowlist" containing only themselves), a total soundness break for the compliance claim.
- v3 (live) closes it: each program binds a Foundation-set `authorizedRoot`, and `submitProof` requires `extraDataHash == authorizedRoot` (revert `UnauthorizedRoot` otherwise). The Foundation rotates the root via `setAuthorizedRoot` as the real allowlist changes, and can void an individual clearance via `revoke(user, programVKey)`, which sets a per-user watermark so a clearance whose `attestedAt` is at or below the watermark reads as invalid.
`isCleared` also enforces an optional per-program `expirySeconds`. The contract source explicitly instructs consumers to pass a real `minTimestamp` (for example `block.timestamp - freshnessWindow`), never 0, and to treat clearance as necessary-not-sufficient, ANDing it with a live sanctions check for sanctions-sensitive flows.
### 3.3 The over-18 circuit (real; deep dive)
The guest program lives at `zk-circuits/recursive-aggregation/over18-program/src/main.rs`. It proves in zero knowledge that the prover holds an issuer-attested birth-year credential AND that the birth year implies adulthood, without revealing the birth year.
Mechanics:
- A Foundation-approved KYC issuer publishes a Merkle root of `keccak256(birthYear || user)` leaves for the people it has verified.
- The circuit reads public inputs (chainId, user, attestedAt, root) and private witness (birthYear, Merkle depth, and the sibling path).
- It asserts `birthYear <= MAX_ADULT_BIRTH_YEAR`, where `MAX_ADULT_BIRTH_YEAR = 2008` is a compile-time constant baked into the verification key. This makes the program a dated "adult as of 2026" attribute; it must be recompiled next year to advance the threshold. That is an honest design tradeoff (the constant is part of the vKey, so a stale program cannot silently drift).
- It rebuilds the leaf `keccak256(birthYear.to_be_bytes || user)` and walks the witnessed path to the root, asserting membership. It commits exactly the `AereZKScreen` tuple, with `extraDataHash` carrying the issuer credential-tree root, so the same v3 contract anchors it.
Provenance: this circuit was proven end-to-end and its on-chain SP1 verification key is `0x005aa94ac711bc65d0755b3a94f3622a6e8c76e2cdd708c29869587f633343c5` (it also appears as a leaf in AERE's recursive proof-aggregation demo, alongside the general `zkscreen` program vKey `0x006a211015aee2b90b82d266bef3aa6944551b06c488d86e895489b1dde3e5b7`).
**Status, corrected 2026-08-01: SHIPPED. It is registered, with its authorized root bound.** An earlier revision of this paragraph said registration was "pending a Foundation signature" and that `submitProof` for the over-18 program "reverts `UnknownProgram` on the live contract", and marked the capability "in-development, not shipped".
Measured at head block 11,810,041, reading `programs(0x005aa94ac711bc65d0755b3a94f3622a6e8c76e2cdd708c29869587f633343c5)` on `AereZKScreen 0x3A097A45…`:
- `registered` = **true**
- `programVKey` equals the key queried
- `authorizedRoot` = `0xb3b4d50651d41ba296c9d4fbf2aa153c3c0f30dc32d836fcdbefc9ea5040b304`, which is **non-zero**
- a `description` recorded on chain identifying it as the AERE over-18 attribute, an SP1 Groth16 zero-knowledge proof that an issuer-attested birth year implies age 18+ (born <= 2008), without revealing the date of birth, with no PII on-chain
The non-zero `authorizedRoot` is the part that matters most, because it is what arms the root-binding soundness check in Section 3.2. A program registered with a zero root would be registered and unsound. This one is neither.
So `submitProof` for this program does not revert `UnknownProgram`. The capability is live. **What remains thin is usage, not capability**, and that distinction is now made everywhere in this document rather than collapsed into the word "pending".
### 3.4 EU-jurisdiction and other attribute programs (archetype; in development)
The v3 contract is program-agnostic: any SP1 circuit that commits the four-field tuple and binds an authorized root can be registered. The EU-jurisdiction / MiCA-eligibility proof, the accredited-investor proof, and the OFAC-screen proof are described in the contract as the intended program set, and they follow the identical pattern (issuer-attested credential root, in-circuit predicate over a private attribute, `extraDataHash == authorizedRoot`). Of these, only the over-18 circuit has a real guest program in the repository today. The others are archetypes on the same rail and should be presented as roadmap, not as live capabilities.
## 4. AereSanctionsRegistry: the OFAC Merkle registry (deployed, ONE snapshot, currently unattested)
Address `0xb7d235718D99560F6EA4Fc5eAea2F8a306A3Cacf`, `Ownable`, owner Foundation (re-verified at head), Solidity `0.8.23`, 5,526 bytes of live code. This is a read-only, public-good sanctions registry. There is no fee and no discretionary interception.
### 4.0 Live state, before any description of the design
An earlier revision of this section was headed "(live)" and described a 24-hour cron publishing a root each epoch. **No cron is running, and there is exactly one snapshot.** Read at head block 11,810,041 on 2026-08-01:
| Read | Value |
|---|---|
| `latestEpoch()` | 20641 |
| `snapshots(20640)` | empty |
| `snapshots(20641).root` | `0x0ec5e409b9ab5da067bdbf00e711339aad47cd0bb6aa40d126a0012576643bb3` |
| `snapshots(20641).proposedAt` | 1783408432, which is 2026-07-07T07:13:52Z |
| `snapshots(20641).attestedAt` | **0** |
| `snapshots(20641)` state | **0 = Proposed** |
| `snapshots(20642)` | empty |
| `openChallenges(20641)` | 0 |
| `CHALLENGE_WINDOW()` | 86400 seconds |
So: one root, proposed 25 days ago, zero open challenges, and **never attested**, despite the 24-hour challenge window having elapsed 24 days ago. Nothing is blocking the attestation; it simply has not been called.
**The consequence a consumer needs, stated bluntly.** `isSanctioned` returns true only if the snapshot is **attested** AND the inclusion proof verifies. Because no snapshot is attested, the registry currently answers "not sanctioned" for every address, including addresses that are genuinely on the published root. **Until `attest(20641)` lands, no consumer should treat this contract as a sanctions signal in either direction.** That is a stronger warning than "live", and it is the accurate one.
The design description below is correct and is retained in full. It describes what the contract does when it is being operated. Read it as the mechanism, and read Section 4.0 as the state.
### 4.1 How it works (design)
The intended operating model is one epoch per 24 hours: an off-chain ingester reads the official OFAC Specially Designated Nationals (SDN) list from `treasury.gov`, extracts crypto addresses where present, builds a keccak256 Merkle tree, and the Foundation publishes the root. **That schedule is the design, not the observed behaviour**; see Section 4.0. The single existing snapshot records its source URL and a version stamp on chain, so the tree it was built from can be reproduced. Leaf format: `keccak256(abi.encode(address evmAddress, uint16 listId))`, where `listId` distinguishes the source list. The contract reserves `1 = OFAC SDN`, `2 = OFAC SSI`, `3 = EU consolidated`, `4 = UK HMT`, `5 = UN consolidated`; Phase 1 ships OFAC SDN only.
Lifecycle per epoch is optimistic, mirroring the NAV oracle pattern: `Proposed -> (Challenged?) -> Attested`. `proposeSnapshot(epoch, root, sourceUrl, ipfsCid)` is owner-only and records the canonical OFAC URL the root was built from plus an optional IPFS CID pinning the full list. Anyone may `challenge(epoch, reason)` within the 24h `CHALLENGE_WINDOW` (measured: 86400 seconds); the Foundation may `dismissChallenge`.
**`challenge` takes no bond, and that is a real weakness in this lifecycle.** Read against the live source: `challenge(uint256,string)` is `external` and non-payable, does not read `msg.value`, holds no balance, and the `Challenge` struct carries only `challenger`, `timestamp`, `reason` and `dismissed`. There is no bond field anywhere in the contract. The lifecycle is therefore **optimistic but not bonded**. Other AERE documents have described this cycle as "bonded", including by comparison from the compliance pool's association roots; the compliance pool really does bond, this registry does not, and the comparison is what breaks. It is corrected wherever we control the text.
The practical shape of the weakness: because a challenge is free and each one blocks attestation until the owner separately dismisses it, one party can hold an epoch open indefinitely at the cost of gas alone, forcing one owner transaction per challenge. Measured today `openChallenges(20641) = 0`, so this has not been exercised. The right fix is a bond on `challenge`, and it needs a redeploy. After the window elapses with no open challenges, anyone may `attest(epoch)`, which freezes the root. History is append-only; attested epochs cannot be rewritten, and there is deliberately no "deSanction" path (removing an address would imply the Foundation is making a sanctions decision, which it is not; it only mirrors the canonical list).
Consumers call `isSanctioned(epoch, evmAddress, listId, proof)`, which returns true only if the snapshot is attested AND the Merkle inclusion proof verifies. `isSanctionedLatest(evmAddress, listId, proof)` walks back from the latest epoch to the most recent attested snapshot, bounded at `MAX_EPOCH_SCAN = 64` to prevent a griefable DoS (a Round-3 audit fix).
### 4.2 Inclusion, not absence (the honest core of this contract)
`isSanctioned` is an inclusion proof. It proves that an address IS on the list at a given epoch. It does NOT prove absence. A standard keccak256 Merkle root supports membership proofs only; proving non-membership would require a sorted or sparse Merkle tree (an SMT), which this is not. Consequently:
- "This address is sanctioned" can be proven trustlessly on-chain (given the proof).
- "This address is clean" cannot be proven by this contract. The best a consumer can do is: no valid inclusion proof was supplied. That is a much weaker, trust-the-published-list statement, and it depends on the caller (or an indexer) to actually attempt the lookup rather than skipping it.
For flows that need a positive "clean" assertion, the design intent is to compose this with a positive-allowlist primitive: the compliance pool's association-set inclusion proof (Section 8) or a ZKScreen OFAC-screen program (Section 3.4). Presenting the sanctions registry alone as "sanctions-clean gating" would overstate it, and this spec does not.
### 4.3 Trust and liveness
The published root is Foundation-attested through a Foundation-controlled key (Ledger-signed); the Foundation control point on chain 2800 is a single-key account today, not a deployed multisig (a Safe multisig is roadmap). The optimistic window lets anyone challenge a bad root, but a challenge only forces a dismissal decision; it does not itself prove the root wrong, and it costs the challenger nothing beyond gas because `challenge` takes no bond (Section 4.1).
**Liveness, measured rather than assumed.** The single snapshot has sat in `Proposed` for 25 days with an elapsed challenge window and no open challenges. Whatever the design says about a 24-hour cadence, the observed cadence is one publication and no attestation. A consumer choosing whether to depend on this registry should weigh the observed record, not the intended schedule. The ultimate ground truth is the off-chain OFAC list, and the `sourceUrl` plus `ipfsCid` fields exist so third parties can reproduce and audit the tree. This is honest optimistic security, not trustless.
## 5. ChainalysisOracleWrapper (deployed; inert on 2800 until an upstream is set)
Address `0x1B7Be82C80f368f75Cb3807B1bc05E86A498f85c`, `Ownable`, owner Foundation. Chainalysis publishes a free public `isSanctioned(address)` oracle on Ethereum mainnet and other major chains. This wrapper gives AERE dApps a single stable endpoint with the same interface, forwarding a `STATICCALL` to a configured upstream. On any upstream error (paused, migrated, not present) it returns false rather than reverting, so a consumer is never bricked.
Honest caveat: the Chainalysis oracle is not natively deployed on chain 2800. `upstreamOracle` is settable once by the Foundation via `setUpstream` and frozen by `lockUpstream`. Until an upstream is configured, `isSanctioned` returns false for every address, meaning the wrapper is effectively inert and must not be relied on as the sanctions source. The real on-chain sanctions signal today is the Merkle registry in Section 4. The wrapper is scaffolding for a future Chainalysis (or equivalent) presence on 2800, and it should be labeled as such.
## 6. AereForensicEventRegistry (live)
Address `0x4a7526A068e5DDE9788f6571E4A99095b14C6fff`, `Ownable`, owner Foundation, Solidity `0.8.23`. An open, Forta-style registry where detection bots post structured alerts about suspicious on-chain activity. Bots self-register (`registerBot`), then `emitAlert(botId, subject, alertType, severity, detailUri)`. The alert taxonomy runs 0 (catch-all) through 9 (rug-pull pattern), including 1 (sanctioned-flow), 2 (sandwich/MEV), 5 (bridge exploit), 8 (honeypot). Severity runs 1 (info) to 5 (critical). Consumers read `recentConfirmedAlertCount(subject, minSeverity, windowSeconds)`, bounded at `MAX_RECENT_ITERATIONS = 256` (a Round-3 DoS fix, so an attacker spamming millions of low-severity alerts cannot revert a consumer's in-transaction query).
Honest scope: registration is permissionless, but in Phase 1 only the Foundation confirms alerts (`confirmAlert`), and the read that consumers gate on counts CONFIRMED alerts only. So the trust anchor is again the Foundation. Stake requirements are 0 in Phase 1 (purely reputational); an AERE bond plus staked-community confirmation is described as a Phase 2 item and is not built. This registry is an audit and signaling surface with no custody and no transaction interception.
## 7. AereTravelRuleHashRegistry (live)
Address `0xcF0E2e010E6e4506672019b1e570874AEeBC4c84`, Solidity `0.8.23`, no admin. This is the on-chain anchor for FATF Travel Rule message exchanges (Notabene / IVMS-101 compatible). The Travel Rule requires VASPs to exchange identity payloads for transfers above a jurisdiction threshold (roughly USD 1,000 for the US, EUR 1,000 under EU MiCA). The payloads are confidential and exchanged off-chain over a message bus. This contract anchors only a commitment.
Flow: the originating VASP calls `commit(payloadHash, beneficiaryVasp, threshold)`, storing a keccak256 hash of the IVMS-101 payload, the two VASP addresses, the threshold (USD cents), and a timestamp; the id is indexed under both VASPs for audit retrieval. The beneficiary VASP later calls `acknowledge(id)` to mark receipt and verification, or `dispute(id, reason)` if the on-chain hash does not match what was exchanged. No payload data, and no identity, is ever stored on-chain. The anchor proves the payload existed at a specific block, is append-only, and is auditable by regulators without revealing content.
Design notes and honesty: there is no admin, no Foundation interception, and no custody. The contract is genuinely trust-minimized in the narrow sense that it is just an append-only commitment log; the VASPs self-identify via `msg.sender` and there is no on-chain VASP allowlist, so the registry does not itself vouch that a committing address is a licensed VASP (that verification is off-chain, and can be layered via `AereAttestationGateway`). It is a minimal viable Travel Rule anchor, Phase 1.
## 8. AereCompliancePoolV2: the compliant privacy pool (live; 0 deposits)
Address `0xB144c923572E5Ac1B6B961C4ccfec36917173465`, Solidity `0.8.23`, `ReentrancyGuard`. Deploy tx `0xca77b3a125ac2c9ae3687031e40c7e3e216300158c5785b0583fa231dce5fb85`, block 8910143. It denominates in WAERE (`0x7e84d7d66d5da4cfE46Da67CDEeB05B323e1f5e8`) with a fixed `DENOMINATION` of 1 WAERE, `FOUNDATION` set to the Foundation account (single-key, not a deployed multisig), and `VERIFIER` set to the reused SP1 adapter `0xE2D3fa91b680E835c971761ba75Fde0204AEF95E` (program vKey `0x00aa183a...`). `POOL_ID` is `0x100bc0276cfe121913b849d9804a1575cb9894d7db22561eafe9a8ab50f747c8`. It is a fresh pool: `depositCount` is 0. Present it honestly as a working, tested primitive with no real usage yet.
### 8.1 The Privacy Pools + Travel Rule construction
This is Ameen Soleimani / Vitalik-style Privacy Pools, hybridized with a Travel Rule hook. The core is an append-only keccak256 Merkle tree, `TREE_DEPTH = 20` (capacity 2^20 = 1,048,576 notes), with a rolling 256-root history (`ROOT_HISTORY_SIZE = 256`) so a withdrawal can prove against any recent deposit root. `ZERO_VALUE` is `keccak256("aere.compliance-pool.v1.empty-leaf")`. These parameters are byte-for-byte identical to the v1 pool, which is what lets the same off-chain SP1 circuit and the same deployed verifier keep working.
Deposit path: `deposit(commitment, travelRuleHash, complianceProvider, travelRuleUri)`. The `complianceProvider` must be on a Foundation-managed allowlist (`isComplianceProvider`, set via `setComplianceProvider`). The actual leaf inserted is `keccak256(commitment || msg.sender)` (an R5 leaf-binding fix so a deposit note is bound to its depositor). The `travelRuleHash` and `travelRuleUri` carry the off-chain Travel Rule commitment for the deposit, tying this pool to Section 7's regime.
Withdraw path: `withdraw(proof, depositRoot, associationRoot, nullifierHash, recipient, feeRecipient, fee, refund)`. The contract checks the nullifier is unspent, the `associationRoot` is published (see 8.2), and the `depositRoot` is a known recent root, then calls the SP1 verifier over eight public inputs `[poolId, depositRoot, associationRoot, nullifierHash, recipient, feeRecipient, refund, fee]`. The SP1 guest proves: `commitment = keccak256(secret || nullifier)`; `actualLeaf = keccak256(commitment || depositor)`; `depositRoot` is the Merkle root over the deposit tree containing that leaf; `associationRoot` is the Merkle root over the "clean" subset containing that same leaf; `nullifierHash = keccak256(nullifier)`; and recipient / feeRecipient / refund / fee are all bound so a front-runner cannot substitute them.
### 8.2 Inclusion in a Foundation-attested clean set (the honesty crux)
The compliance property is a positive inclusion proof, not an absence proof. To withdraw, a user proves their note is a member of the association root, which is a Foundation-published Merkle root over the subset of deposits judged "clean" (an Association Set Provider model). This is the honest, correct way to do compliant privacy: the user demonstrates they are in the good set, rather than the impossible-to-verify claim that they are not in some bad set. The tradeoff is explicit: the clean set is Foundation-curated, so a user whose legitimate deposit the Foundation omits cannot withdraw with privacy until included. That is a real centralization point and we state it.
Association roots go through an optimistic lifecycle with a bond, matching the sanctions registry philosophy:
- `proposeAssociationRoot(root)` is Foundation-only.
- `challengeAssociationRoot(root, reason)` is permissionless but requires a `CHALLENGE_BOND` of 100 tokens (100 WAERE), capped at `MAX_DISMISSALS_PER_ROOT = 2`.
- The Foundation may `dismissAssociationRootChallenge` a provably-bad challenge within the 24h window (`ASSOCIATION_ROOT_CHALLENGE_WINDOW = 86400`), which burns the bond to the dead address and restarts the publish window.
- `publishAssociationRoot(root)` finalizes after the window with no active challenge; `withdraw` then accepts it.
### 8.3 The F8 fix (why v1 is dead)
The v1 pool `0x79735c31F289F7A4d6Be3E02aaB70B544796D41d` (0 deposits, left on-chain, harmless) had a real bug: `challengeAssociationRoot` pulled the 100-token bond but there was no path to return it to an honest challenger. If the Foundation dismissed, the bond was burned; if the Foundation simply never acted, the root stayed "challenged" forever with the bond locked. An honest challenger who was right always lost 100 tokens.
V2 fixes this. A challenge now resolves one of two ways. DISMISSED: the Foundation dismisses within the window, the bond is burned to `0x...dEaD` exactly as v1 (preserving the anti-grief property, so griefing a valid root still costs the bond). UPHELD: if the Foundation fails to dismiss within the window, anyone can call `reclaimUpheldChallenge`, which refunds the bond to the challenger and permanently rejects the root (`associationRootRejected`), so a questioned set is never published. That is the safe default for a compliance pool. This was demonstrated live on a byte-identical, deployer-owned twin (`0x736c249F458E9d0E0F97cD03427004a40a77337f`, masked-immutable bytecode identity to the canonical): an upheld reclaim refunded 100 and rejected the root (`reclaimTx 0x609d20af...`), a dismissed challenge burned 100 to dead without refund (`dismissTx 0x45d452e3...`), and a dismissed-then-quiet valid root published (`0x41117e01...`).
Residual risk, stated plainly: there is a liveness assumption on the Foundation. It must dismiss baseless challenges within the window, otherwise the challenge stands and the root is rejected (bond refunded). This fails safe toward challengers and is strictly better than v1, but it is not a trustless mechanism, and a Foundation that goes offline can have valid roots rejected by a single unanswered challenge.
## 9. AereCompliancePoolSP1Verifier (live)
Address `0xE2D3fa91b680E835c971761ba75Fde0204AEF95E`. A thin adapter bridging the pool's `IPrivacyPoolVerifier.verify(bytes proof, uint256[] pubs)` interface to the SP1 gateway. It ABI-encodes the eight public inputs into the exact struct the Rust guest commits (`pool_id, deposit_root, association_root, nullifier_hash, recipient, fee_recipient, refund, fee`), then does a low-level `staticcall` to `SP1.verifyProof(PROGRAM_VKEY, publicValues, proof)`, returning true iff it does not revert. Both `SP1` and `PROGRAM_VKEY` are constructor immutables. The off-chain prover is the SP1 program at `zk-circuits/compliance-pool/program`; keccak256 hashing and `TREE_DEPTH = 20` in the circuit must match the contract, which they do.
## 10. AereAttestationGateway (live)
Address `0x9bdacA8dfF39Fc688e8D3c4bbA13bCFC0580c325`, Solidity `0.8.23`, `FOUNDATION` immutable. A unified, schema-versioned attestation registry for regulator judgments (MiCA CASP licence, EU AI Act conformity, SEC 1099-DA broker reporting, FCA / FINMA / MAS equivalents). It is the structured successor to `AereIdentity` claims.
Model: the Foundation publishes append-only `Schema` records (id, spec hash, semver, spec URI). Per schema, the Foundation authorizes specific attestor addresses (`setAttestor`), which may be the Foundation itself or, for some schemas, the customer's own NCA-registered auditor. An authorized attestor calls `attest(schemaId, subject, parentId, payloadHash, validFrom, validUntil, payloadUri)`; only the hash and validity window live on-chain, no PII. Attestations support optional inheritance (a child references a parent, and validity chases the chain, so a revoked or expired ancestor invalidates the child), bounded by `MAX_INHERITANCE_DEPTH = 8`. Two audit fixes are worth noting: HIGH #23 requires a parent to attest the same subject (no fabricating transitive trust across unrelated subjects), and HIGH #24 only overwrites the schema-wide `latestFor` pointer when the prior is invalid or the new attestation is currently valid (no griefing a valid record with an already-expired one). The source estimates `attest()` at roughly 70k to 80k gas cold-path (a source-code estimate, not a measured figure). Revocation is issuer-only and permanent; `isValidNow` and `subjectCurrentlyAttested` are the read paths.
## 11. Trust model summary and inclusion-vs-absence table
The single most important honesty point for this stack: which statements are cryptographically trustless, which are optimistic (trust-plus-challenge-window), and which are plain Foundation attestations.
| Primitive | What it proves | Proof type | Trust anchor |
|---|---|---|---|
| Sanctions registry `isSanctioned` | address IS on OFAC SDN at epoch | Merkle inclusion | optimistic (Foundation root + 24h challenge) |
| Sanctions registry "clean" | (cannot prove absence) | none available | not provided; do not imply it |
| Compliance pool withdraw | note IS in the clean association set | ZK inclusion (SP1) | optimistic; clean set is Foundation-curated |
| ZKScreen over-18 | birth year in issuer tree AND <= 2008 | ZK inclusion + predicate (SP1) | issuer credential root (Foundation-approved issuer); program REGISTERED with a non-zero authorized root, measured 2026-08-01 |
| ZKScreen EU-jurisdiction / others | archetype, same rail | ZK (roadmap) | roadmap, not live |
| Travel Rule anchor | a payload hash existed at a block | hash commitment | trustless log; VASP identity is off-chain |
| Attestation gateway | a body attested a subject | signed on-chain record | the attestor (Foundation or auditor) |
| Forensic registry | a bot alerted, Foundation confirmed | on-chain record | Foundation confirmation (Phase 1) |
| Chainalysis wrapper | upstream says sanctioned | forwarded call | inert on 2800 until upstream set |
| AereIdentity claim | attestor issued a claim | plaintext on-chain flag | the attestor; no privacy |
Foundation-attested pieces, gathered in one place so nothing is buried: the sanctions Merkle root, the compliance-pool association (clean-set) root, the ZKScreen per-program `authorizedRoot`, the attestation-gateway schemas and attestor authorizations, the compliance-pool provider allowlist, and the forensic-registry alert confirmations are all Foundation-gated. The optimistic challenge windows (sanctions registry, compliance pool) reduce but do not eliminate this trust, and they carry a Foundation liveness assumption. We consider stating this an asset, not a weakness to hide: a compliance stack that pretends to be trustless when it is optimistic is worse than one that is honest about where the trust sits.
## 12. Roadmap and not-yet-live items
- Over-18 program registration on the canonical ZKScreen v3 anchor (a Foundation `registerProgram` call with the authorized issuer root): pending one Foundation signature. The circuit and proof pipeline are real; the live registration is not yet on-chain.
- EU-jurisdiction / MiCA-eligibility, accredited-investor, and OFAC-screen ZKScreen programs: archetypes on the same rail, guest circuits not yet in the repository.
- Chainalysis wrapper upstream: no Chainalysis (or equivalent) oracle deployed on chain 2800; `setUpstream` / `lockUpstream` not yet called.
- Sanctions registry additional lists (SSI, EU, UK HMT, UN): list ids reserved, Phase 1 ships OFAC SDN only.
- Non-membership (absence) proofs: not provided by any current primitive; would require a sparse/sorted Merkle tree, which is a future design item, not present today.
- Forensic registry staked confirmation and AereIdentity-to-ZKScreen adapter: designed, not built.
- External security audit of the whole stack: not performed.
## Appendix: canonical addresses (verbatim from sdk-js/src/addresses.ts)
- Foundation account (single-key, Foundation-controlled, not a deployed multisig): `0x0243A4f47D44b40b65D33f20329dE20D00c6f3C3`
- WAERE: `0x7e84d7d66d5da4cfE46Da67CDEeB05B323e1f5e8`
- AereIdentity: `0x658dD2CD1F798AAb19fEc8FF69A270B2d192CaD1`
- AereZKScreen (v3, live): `0x3A097A459FD26aC79573aCB5adB51430e473C2f1`
- AereZKScreen v2 (dead, self-clear hole): `0x140572e018C0342336dbaAa1713281c15678aFa7`
- AereZKScreen v1 (dead): `0xE9da9c5F40c2CDfda368885832C59609286e04ee`
- AereSanctionsRegistry: `0xb7d235718D99560F6EA4Fc5eAea2F8a306A3Cacf`
- ChainalysisOracleWrapper: `0x1B7Be82C80f368f75Cb3807B1bc05E86A498f85c`
- AereForensicEventRegistry: `0x4a7526A068e5DDE9788f6571E4A99095b14C6fff`
- AereTravelRuleHashRegistry: `0xcF0E2e010E6e4506672019b1e570874AEeBC4c84`
- AereCompliancePoolV2 (canonical): `0xB144c923572E5Ac1B6B961C4ccfec36917173465`
- AereCompliancePool v1 (deprecated, 0 deposits): `0x79735c31F289F7A4d6Be3E02aaB70B544796D41d`
- AereCompliancePoolSP1Verifier: `0xE2D3fa91b680E835c971761ba75Fde0204AEF95E`
- AereAttestationGateway: `0x9bdacA8dfF39Fc688e8D3c4bbA13bCFC0580c325`
- SP1VerifierGateway: `0x9ca479C8c52C0EbB4599319a36a5a017BCC70628`
+476
View File
@@ -0,0 +1,476 @@
# AERE Parallel Execution: Block-STM Executor and On-Chain Hint Registry
Technical specification. Chain 2800 (AERE Network mainnet).
Grounding: `parallel-executor/` (Rust), `rollup-sequencer/src/blockstm/` (TypeScript),
`contracts/contracts/parallel/AereBlockSTMRegistry.sol`,
`contracts/contracts/parallel/AereRollupValidity.sol`,
`contracts/deployments/block-stm-registry.json`, and
`sdk-js/src/addresses.ts`.
---
## 1. Executive summary and honest scope
AERE's parallel-execution work has three distinct pieces at three different levels of maturity.
Stating them plainly up front, because the boundary between "shipped" and "roadmap" is the
whole point of this document:
1. **A real, self-verifying Block-STM parallel executor (shipped, benchmarked).**
`aere-block-stm` is a from-scratch Rust implementation of the Block-STM
optimistic-concurrency algorithm (Gelashvili et al., arXiv:2203.06871, 2022, the same
design behind Aptos and the family Sui and Monad build on). It executes a batch of
transactions across many CPU cores and commits a single keccak256 state root. Every run
also executes the batch sequentially and refuses to emit a root unless the two results
match, so a concurrency bug cannot silently produce a bad commitment. Correctness is proven
over 6000 randomized adversarial comparisons with zero mismatches, and measured speedup on a
16-core box is roughly 8.6x to 9.3x on low and medium-conflict batches.
2. **An on-chain advisory registry (shipped, live).**
`AereBlockSTMRegistry` at `0x98E2C3e615841919d173D8FF642514c5902E8A28` is an opt-in registry
where a contract publishes the storage-slot read/write hints for its own function selectors.
It is advisory metadata for a scheduler, holds no funds, changes no execution semantics, and
has no admin over anyone else.
3. **Moving parallelism into base consensus (roadmap, not built).**
AERE's Layer-1 base layer runs Hyperledger Besu and executes transactions **sequentially**.
Nothing here changes that. Making Besu execute in parallel is a fork of a Java
execution client, a multi-month effort, and is explicitly out of scope for what exists today.
The registry is metadata for that eventual fork; the concrete parallel path that runs today
lives in the **rollup layer**, off-chain in the sequencer.
The honest one-line framing, taken verbatim from the executor README, is: "Real Block-STM
parallel executor, wired into the AERE rollup sequencer; the L1 base layer stays
Besu-sequential."
Everything in Section 2 through Section 5 is code that exists and runs. Section 6 (base-consensus
promotion) and the fraud-proof / full-EVM items in Section 7 are roadmap and are labeled as such.
---
## 2. The parallel executor (`aere-block-stm`)
The executor is a standalone Rust crate under `parallel-executor/` with **zero external
dependencies**: the scheduler, multi-version memory, PRNG and keccak256 are all built on `std`.
The build is fully offline and reproducible.
### 2.1 State and transaction model
The state model is intentionally EVM-shaped but minimal (`aere-research/parallel-executor/src/types.rs`):
- `Key::Balance(account)`: the native-token balance of an account.
- `Key::Storage(contract, slot)`: a single key/value contract storage slot.
Values are `u128`; an absent key reads as `0`. A transaction version is `(txn_index,
incarnation)`, where `incarnation` counts how many times a transaction has been re-executed
after an abort.
The VM understands four transaction kinds (`TxKind`), each chosen because its control flow or its
written *values* depend on what it reads, so a stale read is silently wrong unless caught:
- **Transfer** `{from, to, amount}`: move `amount` if `from` can afford it. Control flow depends
on reading the sender balance.
- **Sweep** `{from, to}`: move the entire balance of `from`. The written values depend directly
on the read balance, a strong serializability probe.
- **Increment** `{contract, slot}`: `storage[slot] += 1`. When many transactions hit the same
slot this is the classic all-conflict counter: the sequential result is `start + count`, and a
correct parallel executor must reproduce exactly that despite reordering.
- **AmmSwap** `{contract, x_slot, y_slot, dx}`: a constant-product swap against a two-slot pool,
modelling a hot DeFi pool that conflicts across concurrent swaps.
Each `Txn` also carries a `gas` field, a simulated per-transaction CPU cost measured in
keccak rounds. It does **not** affect the resulting state (correctness is independent of gas); it
exists so benchmarks charge each transaction a realistic amount of interpreter-like work instead
of measuring only scheduling overhead. This is discussed honestly in Section 4.
### 2.2 One transaction semantics, two drivers
The single most important design decision is in `aere-research/parallel-executor/src/vm.rs`: there is exactly **one**
implementation of what a transaction does, `execute_txn`, and it runs against an abstract
`VmView` trait with two methods, `read(key)` and `write(key, value)`. All arithmetic is
saturating so both paths behave identically and never panic on overflow.
- The **sequential oracle** (`aere-research/parallel-executor/src/sequential.rs`) drives `execute_txn` with a view backed
directly by a live `HashMap` state, applying transactions in strict index order. This is the
definition of the correct answer.
- The **parallel executor** (`aere-research/parallel-executor/src/parallel.rs`) drives the same `execute_txn` with a view backed
by multi-version memory that records the read set and can signal an abort.
Because both paths share the exact same semantics function, the parallel result can differ from
the sequential result **only** if the concurrency control is wrong. That is precisely the
property the correctness harness (Section 3) exercises.
### 2.3 Multi-version memory (MVMemory)
`aere-research/parallel-executor/src/mvmemory.rs` keeps, for every `Key`, an ordered `BTreeMap<txn_index, cell>`, where a cell is
either a concrete `Value(incarnation, value)` written by a transaction, or an `Estimate`
placeholder (a marker that a lower-indexed transaction previously wrote here but is currently
being re-executed, so its value is not trustworthy).
A read by transaction `i` for key `k` returns the entry of the **highest** transaction `j < i`
that wrote `k` (`versions.range(..txn_idx).next_back()`). That is what makes speculative parallel
execution serial-equivalent: transaction `i` always observes the writes of all lower-indexed
transactions that have run, and nothing from higher ones. If the highest lower entry is an
`Estimate`, the read returns `Blocked(j)` and the reader must abort and park on `j`.
Storage is sharded across 256 independent mutexes keyed by an FNV-1a hash of the `Key`, so
non-conflicting transactions touch disjoint locks and run without contention. Hot keys (the
shared counter, the AMM pool) serialize on one shard, which is the honest source of the
high-conflict slowdown, not an implementation defect.
Three operations matter:
- `apply_write_set` installs a completed incarnation's writes, deletes stale entries the previous
incarnation wrote but this one did not, and returns whether the *set* of written keys changed
(Block-STM calls this "wrote a new path" and uses it to trigger suffix revalidation).
- `mark_estimates` converts an aborted transaction's writes into `Estimate` placeholders the
instant it is validation-aborted, so any concurrent higher transaction that reads one of those
keys blocks on it instead of consuming a soon-to-be-wrong value.
- `snapshot_final` materializes the committed state once the block is fully executed and
validated: base overlaid with, for each key, the value written by the highest transaction index
that wrote a concrete value.
### 2.4 The collaborative scheduler
`aere-research/parallel-executor/src/scheduler.rs` implements the Block-STM collaborative scheduler (Algorithm 3 of the paper). It
hands worker threads two kinds of task:
- **Execution** tasks: run incarnation `k` of transaction `i`.
- **Validation** tasks: re-check that an already-executed transaction's recorded read set is
still valid against current MVMemory.
Two atomic cursors, `execution_idx` and `validation_idx`, drive it. Validation of a lower index
always takes priority over execution of a higher one. When a transaction aborts (validation
fails) or writes a new path, the relevant cursor is *decreased* so the affected range is
revisited, and a `decrease_cnt` counter is bumped. The block is done only when both cursors have
passed the end, no task is in flight, and no decrease happened during the check.
Dependencies are handled **without condvars**: when execution of `i` reads an `Estimate` from
`j`, `i` is parked on `j`'s dependency list and its task dropped; when `j` finishes it re-arms `i`
(back to `ReadyToExecute`) and decreases `execution_idx` so a worker re-picks it. `add_dependency`
holds the blocking transaction's status lock across the whole check-then-park critical section, so
`j` cannot transition to `Executed` and drain its dependency list between the check and the push
(which would lose the wakeup). `try_validation_abort` uses a compare-and-set on status so only one
validator can abort a given incarnation.
The `aere-research/parallel-executor/src/parallel.rs` driver spawns `num_threads` workers, each looping `next_task` -> run ->
feed result back -> repeat, until the scheduler reports `Done`. It tracks aggregate stats:
`total_executions` (>= `num_txns`; the excess is re-executions), `total_validations`, and
`total_aborts`.
### 2.5 keccak256 state root
`aere-research/parallel-executor/src/keccak.rs` is a from-scratch keccak256 (standard Keccak-f[1600], rate 1088 bits, original
Keccak `0x01 .. 0x80` padding, i.e. keccak256 not SHA3-256), verified in tests against the known
vectors for `""` and `"abc"`. `state_root` folds a materialized state into one 32-byte root by
sorting non-zero entries into a canonical order (balances tagged `0x00`, storage tagged `0x01`,
big-endian fields) and hashing. The canonical sort makes the root deterministic and independent of
hashmap iteration order, which is exactly what a rollup state commitment requires, and it is
EVM-compatible with zero external crates.
---
## 3. Correctness guarantee (proven, not asserted)
The whole point of Block-STM is that the parallel result must equal sequential execution. The
harness (`aere-block-stm harness`, in `src/main.rs`) proves it empirically.
It runs **6 workload profiles x 200 randomized batches x {1,2,4,8,16} threads = 6000
comparisons** (1200 distinct randomized batches, each compared at five thread counts) and asserts
the Block-STM committed state equals the sequential oracle for every single case. The profiles
include deliberately adversarial fully-conflicting cases: `all-hot` (400 transactions, 200 hot
accounts, conflict probability 1.0) and `brutal-single-counter` (300 transactions on 64 accounts,
one contract, one slot, conflict probability 0.9). Reported result:
```
total (batch x threads) comparisons: 6000
mismatches : 0
RESULT: PASS -- parallel Block-STM == sequential on ALL cases
```
Workloads are generated by a seedable SplitMix64 PRNG (`aere-research/parallel-executor/src/workload.rs`) with no external RNG
crate, so any failing case can be replayed exactly. The default batch mix is 60% transfers, 15%
sweeps, 15% shared-counter increments, and 10% AMM swaps.
`cargo test --release` adds targeted unit checks:
- `shared_counter_is_serialized`: 500 transactions all incrementing one slot yield exactly 500 at
1, 2, 4, 8, and 16 threads (naive parallelism would lose updates).
- `parallel_equals_sequential_random`: 40 seeds x 4 thread counts.
- `keccak_known_answer`: keccak256 of `""` and `"abc"` match the standard vectors.
---
## 4. Measured speedup (honest numbers)
Measured on the AERE infra box: 16 physical cores, Linux 6.8, Rust 1.96. 20,000 transactions per
batch, each carrying a simulated EVM execution cost of `gas = 80` keccak-rounds. Speedup is versus
the single-threaded sequential oracle, median of 7 runs. Reproduce with
`cargo run --release -- bench`.
| Workload | 2 cores | 4 cores | 8 cores | 16 cores | abort % @16 |
|---|---|---|---|---|---|
| Low-conflict (~2% hot-touch) | 1.78x | 3.22x | 5.71x | **8.59x** | 0.3% |
| Medium-conflict (~15%) | 1.87x | 3.54x | 6.24x | **9.31x** | 1.9% |
| High-conflict (single hot counter, 15% of txns) | 1.70x | 3.04x | 4.87x | **4.62x** | 24% |
| Pathological (every tx hits ONE slot) | 0.85x | 0.85x | 0.82x | **0.73x** | 19% |
The "8 to 10x" headline is the low and medium-conflict range (8.59x and 9.31x at 16 cores). The
honest reading, including the cases that do not look good, is stated in the README and repeated
here because it is a credibility asset:
- Low and medium-conflict batches scale nearly linearly.
- The high-conflict batch still reaches roughly 4.6x because only about 15% of its transactions
touch the single hot slot; the rest are independent transfers.
- The **pathological** batch (every transaction increments the same slot) has zero available
parallelism. Block-STM correctly serializes it and is actually *slower* than sequential (0.73x)
because it pays for aborted speculation. This is the expected worst case: no correct parallel
executor can beat sequential when there is nothing to parallelize.
- There is also a floor case: if transactions do near-zero compute (`gas = 0`), concurrency-control
overhead dominates and the parallel executor is slower than sequential. Real EVM transactions are
compute-heavy (opcode interpretation, keccak, ecrecover), which is the regime Block-STM targets,
which is why the benchmark charges a realistic per-transaction cost. Run `bench 0` to see the
floor and `bench 200` for heavier transactions.
These figures are single-machine microbenchmarks of the executor. They are not a network
throughput claim, not a TPS figure, and say nothing about AERE L1, whose base layer remains
Besu-sequential.
---
## 5. Integration into the rollup sequencer
The concrete place this executor runs today is AERE's rollup layer, off-chain in a sequencer.
### 5.1 The wrapper
`rollup-sequencer/src/blockstm/BlockSTMExecutor.ts` exposes:
```
executeBatch(base: Map<StateKey, bigint>, txns: RollupTx[], opts?) : BlockSTMResult
```
It has no npm dependencies (only Node's built-in `child_process`). It serializes the prior L2
state slice and the ordered batch into the executor's line protocol and shells out to the
`aere-block-stm execute` subcommand, which runs the batch across cores, computes the new state,
and returns a keccak256 state root as JSON. The `execute` path runs the batch **both** in parallel
and sequentially and sets `parallelEqualsSequential`; the binary exits non-zero and the wrapper
throws if they diverge, so a bad root can never reach the chain. `BlockSTMResult` carries
`{ stateRoot, numTxns, threads, executions, validations, aborts, parallelEqualsSequential, state }`.
The `execute` stdin wire protocol (`src/main.rs`) is one record per line: `THREADS n`, `GAS n`,
`BASE <key> <value>` (key is `B:<acct>` or `S:<contract>:<slot>`), then `TX TRANSFER|SWEEP|INC|AMM
...`. Output is a single JSON object with the committed root and self-check.
### 5.2 The on-chain commitment flow
The rollup layer is AERE's Rollup-as-a-Service stack. The canonical factory is
`AereRaaSFactoryV2` at `0xB7F8c754AC3155197d76f01857172bBd5a5F39Ab` (bond token
WAERE `0x7e84d7d66d5da4cfE46Da67CDEeB05B323e1f5e8`, sink
`AereSink 0x69581B86A48161b067Ff4E01544780625B231676`), which deploys a fixed
`AereRollupSettlementV2` instance per registered rollup. That per-rollup settlement contract, not
a single global address, is where a sequencer proposes roots. Its call is
`proposeStateRoot(uint256 epoch, bytes32 root, bytes32 l2BlockHash)`, callable only by the
rollup's `sequencer`, with `epoch == latestEpoch + 1`, followed by an optimistic challenge window.
**Who judges that challenge, which this spec previously did not say.** The window is real and the
challenge is bonded, but the arbiter is the defendant. In
`aere-contracts/contracts/raas/AereRollupSettlementV2.sol`, `resolveChallenge(uint256,bool)`
begins with `if (msg.sender != sequencer) revert NotSequencer();`, so the party who decides whether
a challenge succeeds is the same party whose root is being challenged. Resolving with
`accepted = false` defends the root and **slashes the challenger's bond** to the sink. A challenger
who is right can therefore be ruled against by the accused and lose the bond for being right. The
only path that does not run through the sequencer is `resolveChallengeExpired`, which applies when
the sequencer simply ignores a challenge past the defense grace period.
This document was already correct further down when it lists an on-chain fraud-proof verifier as
roadmap. What it was missing is the sentence that says who judges until then, and that omission
made an optimistic-with-a-real-arbiter reading available where none is warranted. **The security of
a rollup settled through this contract rests on the sequencer's honesty, not on a proof**, and a
rollup deployed by `AereRaaSFactoryV2` must not be described as trust-minimised on the strength of
this challenge window. The same warning is carried in the contract source itself.
The flow is therefore:
```
batch of L2 txns -> BlockSTMExecutor.executeBatch() -> { stateRoot, ... }
|
v
settlement.proposeStateRoot(epoch, stateRoot, l2BlockHash)
```
Because the executor guarantees the parallel result equals sequential execution, the committed
root is deterministic and reproducible, which is what makes it safe as an optimistic-rollup
commitment: a Phase-2 fraud proof would re-derive it by re-running the same deterministic
executor over the disputed batch. See `rollup-sequencer/src/blockstm/example.ts` for an
end-to-end run.
### 5.3 Integration status (honest)
- Executor: real Block-STM, correctness-proven, benchmarked. Shipped.
- Integration: the `execute` JSON boundary is live and tested; the TypeScript wrapper drives it and
returns a root ready for `proposeStateRoot`. Shipped as the batch-execution core.
- **Not yet built:** the wiring from a live L2 mempool into `executeBatch` (this module is the
batch-execution core the full sequencer loop plugs into, not a running production sequencer), and
an on-chain optimistic fraud-proof verifier (settlement is optimistic Phase 1 today). These are
roadmap.
---
## 6. The on-chain hint registry: `AereBlockSTMRegistry`
### 6.1 Purpose
For Block-STM to schedule efficiently it benefits from **hints** about which storage slots a
transaction is likely to read or write; a good hint reduces the abort rate. Solidity does not
expose this metadata. `AereBlockSTMRegistry` (`contracts/contracts/parallel/AereBlockSTMRegistry.sol`)
is an opt-in registry where a contract publishes its likely read/write set at the function-selector
grain, so an eventual scheduler can consult it. It is **advisory only**: hints cannot change
execution semantics, and a scheduler always re-validates the actual read/write set after execution.
A wrong hint costs at most one extra abort; it can never make a transaction succeed when it should
fail.
### 6.2 Data model and API
- `SlotHint { bytes32 slotPrefix; Mode mode; }` where `Mode` is `READ`, `WRITE`, or `READWRITE`.
- `HintSet { address publisher; SlotHint[] hints; uint64 publishedAt; }`, stored per
`(target, selector)` key `keccak256(abi.encodePacked(target, selector))`.
Functions:
- `publish(address target, bytes4 selector, SlotHint[] hints)`: publish or replace the hint set.
It caps hints at 64 (`TooManyHints` above that) and **replaces** rather than appends.
- `clear(address target, bytes4 selector)`: clear the set; publisher only.
- `hintsFor(target, selector) -> (publisher, hints, publishedAt)`: the view a scheduler reads.
- `publisherOf(target, selector) -> address`.
### 6.3 Access control (audit fix HIGH #27)
The first publisher for a `(target, selector)` must be the target itself **or** the target's
`Ownable` owner, checked best-effort via a `staticcall` to `owner()` (`_tryOwner`). This closes a
front-run squatting vector: without it, an attacker could publish poisoned hints for a victim
contract's selector before the real owner did. After the first publisher claims a key, only that
publisher can update or clear it (`NotPublisher` otherwise). There is no admin override and no
Foundation gate: the contract author knows its own access pattern best. The registry test
(`contracts/test/block-stm-registry.test.js`) exercises the claim rule, the replace-not-append
behavior, the 64-hint cap, and publisher-only clear.
### 6.4 Deployment facts (live)
- Address: `AereBlockSTMRegistry 0x98E2C3e615841919d173D8FF642514c5902E8A28` (roadmap item #33).
- Deploy tx: `0x5646445f5a6c8a3d9d06db7a6becd95f6227608b64291319fd19d7d928beee72`, block 8877969.
- Deployed from an operational deployment account (moving to governance); the account hex is operational detail and is not published here. Code size 1753 bytes. Deployed 2026-07-10.
- Read-verified at deploy: `hintsFor(unpublished)` returns `(0x0, [], 0)` and
`publisherOf(unpublished)` returns the zero address.
- No owner, no admin, holds no funds.
### 6.5 What the registry does NOT do (honest scope)
The AERE L1 (Besu) executes sequentially today. The registry is metadata for the eventual
Block-STM Besu fork; it does **not** make L1 parallel, and publishing hints has no effect on how
any transaction executes on mainnet right now. Its `hintsFor(target, selector)` view is
intentionally shaped to be the interface a future consensus precompile (planned at `0x103` in the
Phase-2 Besu fork) would read. That precompile and fork do not exist. The contract is deliberately
inert-but-ready: real, correct metadata storage today, waiting for a consumer that is roadmap.
---
## 7. Related on-chain anchor: `AereRollupValidity` (validity proofs of the same executor)
There is a second, stronger settlement path already anchored on-chain for the exact same executor.
`AereRollupValidity` at `0x38772063572DF94E90351e44ccbBEefD5F497fbd` verifies **SP1 zkVM Groth16
validity proofs** that AERE's deterministic rollup executor transitioned a prior state root to a
new one by applying a specific batch. Its `PROGRAM_VKEY` binds the SP1 verification key of the
guest ELF that ports `execute_txn`, keccak256 and state-root folding **verbatim** from
`parallel-executor/src/{vm,keccak}.rs`, so the proven computation is byte-identical to what the
production `aere-block-stm` binary self-checks and what `BlockSTMExecutor` commits. Public values
are exactly 160 bytes: `abi.encode(chainId, prevRoot, postRoot, batchHash, numTxns)`. Submission is
permissionless; an epoch is final the instant its proof verifies (no challenge window), gated by a
`prevRoot == latestRoot` continuity check. It routes through the SP1 gateway
`SP1VerifierGateway 0x9ca479C8c52C0EbB4599319a36a5a017BCC70628`.
Per the SDK registry, epoch 0 has already been recorded from a real proof
(`submitEpoch` `0xd4f8d858...12a4b0`), advancing `latestRoot` to `0x256fa277...25e3ac` with
`epochCount = 1`, under an immutable vkey `0x00c39737...84ad` (these three values are cited in the
abbreviated form they appear in `sdk-js/src/addresses.ts`).
**Honest scope, stated in the contract itself:** this proves the state transition of AERE's
*current* rollup executor, whose VM implements a bounded set of transaction kinds (Transfer,
Sweep, Increment, AmmSwap) over a balance/storage map. It is a real validity proof of *that*
executor. It is **not** a proof of arbitrary EVM bytecode. The path to a full validity rollup is
replacing the executor's VM with a real EVM (revm) inside the zkVM, a separate multi-quarter
effort. No claim built on this contract should imply it proves a full EVM.
---
## 8. Roadmap: moving parallelism into base consensus
What exists today is a proven off-chain executor plus a live on-chain hint registry. Promoting
Block-STM into AERE's base consensus is the roadmap, and it needs work that is not done:
1. **The Besu execution-client fork (the hard blocker).** AERE L1 is Hyperledger Besu, a Java
client that executes block transactions sequentially. Running Block-STM at L1 requires forking
Besu's transaction-processing pipeline to execute speculatively with multi-version memory,
validation, and abort/retry, then reconcile with QBFT block production. This is a multi-month
Java engineering effort and is not mainnet-active. A first prototype now exists and is
benchmarked: a parallel state-root **commit** was added to the forked Besu client's Bonsai
world-state (`aerenew/parallel/`, `parallel_commit.patch`), self-checked to produce a commit
root **bit-identical to the sequential-commit root** across independent-transfer, commit-heavy
SSTORE, deletion, and mixed workloads. The honest finding is a boundary, not a win: the commit
phase is allocation and memory-bandwidth bound, so adding commit worker threads (widths 2 to 16)
is *slower* than a single worker, not faster. The improvement that does hold is a single-threaded
commit rewrite that is roughly **2x cheaper than the stock parallel-trie commit** (for example,
on medium tries about 316.98 ms stock versus 142.38 ms at width 1); end-to-end, Block-STM
execution plus the width-1 commit gives about 1.27x to 1.42x on commit-heavy load versus stock
sequential exec plus sequential commit, and the real execution-side speedup remains the ~8.6x to
9.3x of Section 4. A network throughput win is gated on real execution-heavy load. This is a
research/benchmark control surface (a process-global flag), not a mainnet-active feature; until
the full pipeline lands, the registry's `0x103` precompile consumer does not exist and hints have
no runtime effect on L1.
2. **Fraud proofs for the optimistic rollup path.** The per-rollup `AereRollupSettlementV2`
settlement is optimistic Phase 1: propose plus challenge window, no on-chain fraud-proof
verifier yet. The deterministic executor makes a fraud proof *constructible* (re-run the same
binary over the disputed batch), but the on-chain verifier is not built.
3. **Full-EVM validity.** `AereRollupValidity` proves the bounded four-kind VM, not arbitrary EVM.
A full validity rollup needs a real EVM inside the zkVM.
4. **Production sequencer loop.** The live-mempool -> `executeBatch` -> `proposeStateRoot` loop is
not wired end-to-end; today the module is the batch-execution core, not a running sequencer.
---
## 9. Honest limitations summary
- The AERE L1 mainnet executes **sequentially** on Besu. No parallel execution runs at L1 today,
and the hint registry, while live, has no L1 consumer yet.
- The parallel executor's VM is a **bounded four-kind model** (Transfer, Sweep, Increment,
AmmSwap) over a balance/storage map, not a full EVM. Its correctness proofs and validity proofs
are proofs of *that* executor.
- The measured speedup figures are **single-machine microbenchmarks** (16 cores, gas=80), not a
network throughput or TPS claim.
- The rollup settlement path is optimistic Phase 1 with **no on-chain fraud proof** yet; the
validity-proof anchor covers only the bounded VM.
- Broader chain caveats apply and are not hidden: AERE runs seven validators under one operator, a
single client, and has had no external audit; usage is thin. The self-verifying executor and the
advisory registry are real and proven, but they sit on that foundation.
---
## 10. Address reference (verbatim, chain 2800)
| Contract / entity | Address |
|---|---|
| AereBlockSTMRegistry | `0x98E2C3e615841919d173D8FF642514c5902E8A28` |
| AereRollupValidity | `0x38772063572DF94E90351e44ccbBEefD5F497fbd` |
| AereRaaSFactoryV2 | `0xB7F8c754AC3155197d76f01857172bBd5a5F39Ab` |
| AereSink | `0x69581B86A48161b067Ff4E01544780625B231676` |
| WAERE (RaaS bond token) | `0x7e84d7d66d5da4cfE46Da67CDEeB05B323e1f5e8` |
| SP1VerifierGateway | `0x9ca479C8c52C0EbB4599319a36a5a017BCC70628` |
| Foundation (owner of Ownable contracts) | `0x0243A4f47D44b40b65D33f20329dE20D00c6f3C3` |
| Deployer (registry / validity) | an operational deployment account, moving to governance; hex not published |
`AereRollupSettlementV2` instances are deployed per rollup by `AereRaaSFactoryV2`, so no single
global settlement address exists; the sequencer commits to the per-rollup instance's
`proposeStateRoot`.
@@ -0,0 +1,198 @@
# AERE Network: Recursive Proof Aggregation at Scale
**Chain:** AERE Network mainnet, chain ID 2800 (Hyperledger Besu QBFT).
**Status date:** 2026-08-01. Every on-chain figure (code size, owner, counters, route targets, balances, the EIP-2935 window) was re-read from `https://rpc.aere.network` at head block 11,810,041 on that date. Corrections found in that pass are stated inline, next to the sentence they correct, rather than applied silently.
**Source of truth for addresses:** `sdk-js/src/addresses.ts`. Contract source: `contracts/contracts/zkverify/AereProofAggregator.sol`. Guest and prover source: `zk-circuits/recursive-aggregation-scale/`. On-chain records: `contracts/deployments/proof-aggregator.json` (n=3) and `contracts/deployments/proof-aggregator-scale.json` (n=10).
**Scope:** folding N heterogeneous SP1 proofs into a single Groth16 proof, verified once on-chain, and the gas-amortization argument that follows. This is a focused companion to `spec-zk-stack.md`, which covers the wider verification surface.
---
## 0. Honesty preamble (read this first)
Five points frame everything below.
1. **This is a proof of approach, not a production rollup batcher.** The largest run demonstrated on-chain folds ten inner proofs. That is enough to establish that the recursion, the composite binding, and the constant-cost on-chain verification all work end to end. It is not a claim of a high-throughput sequencing pipeline. n=16 is in progress and is not yet recorded on-chain.
2. **The chain is small and centralized.** AERE runs seven QBFT validators under a single operator on a single client (Besu). There is no external security audit of the AERE-authored contracts. The aggregator is an ordinary EVM contract that any account can call; it does not touch consensus.
3. **Proving happens off-chain and is heavy.** The n=10 aggregation took roughly 1549 seconds of wall time on the prover box (CPU): about 988 seconds to produce the ten inner proofs and about 526 seconds for the final Groth16 wrap. Aggregation buys cheap, constant on-chain verification by spending real off-chain compute. It is not a low-latency path.
4. **The inner statements in the scale run are constructed, not organic user traffic.** The ELFs are the real production programs (their verifying keys are checked byte-for-byte against the on-chain vkeys before any proof enters the fold, and the run aborts if an ELF does not reproduce its published key). The proofs are genuinely produced and genuinely recursively verified. But the per-instance inputs (user addresses, attestation times, credential values) are deterministically derived for the demonstration so that each folded proof is a distinct statement. No claim is made that ten independent users generated these.
5. **The aggregator stores one composite, not each inner statement's payload.** The individual `(vkey, publicValues-hash)` pairs are bound into the composite and emitted in the verification event, but the contract does not persist each inner statement's semantic content. Consumers that need per-proof detail must read the event or re-supply the inner data.
---
## 1. The primitive
> **Which contract to integrate against, corrected 2026-08-01.** An earlier revision of this section called `0x6a260238890E740dB12b371E0C5d17a2470F84C5` "canonical" and named it as the integration target. The address is in `addresses.ts` and the owner reading is correct, but the registry entry is named `AereProofAggregator_DEPRECATED_UNENFORCED_INNER_VKEYS`, and this spec dropped that label while copying the hex.
>
> | Contract | Address | Live code | `aggregationCount` | Status |
> |---|---|---|---|---|
> | `AereProofAggregatorV2` | `0x944dE720D6C9696Bdf10b6E2F00dd21ABB1A2b4C` | 4,663 B | 1 | **CANONICAL. Integrate here.** |
> | `AereProofAggregator_DEPRECATED_UNENFORCED_INNER_VKEYS` | `0x6a260238890E740dB12b371E0C5d17a2470F84C5` | 4,531 B | 2 | **Deprecated.** |
>
> **What is wrong with V1, plainly.** It **counted** how many folded inner programs were recognized as registered and then recorded the aggregation regardless of the count. Registration of the inner programs was never **enforced**. The composite binding described below is enforced on both versions, so neither will let an aggregation claim children it did not fold; what V1 will let through is a fold containing a program nobody registered. V2 rejects that.
>
> Everything below describes the recursion, the composite binding and the gas argument, all of which are shared. The measured n=10 run was recorded on V1 and remains a real demonstration of recursion. Build on V2.
>
> `owner()` measured at head on both: the Foundation account `0x0243A4f47D44b40b65D33f20329dE20D00c6f3C3`.
`AereProofAggregator` at `0x6a260238890E740dB12b371E0C5d17a2470F84C5` (in `addresses.ts`, marked deprecated there; `owner` = Foundation `0x0243A4f47D44b40b65D33f20329dE20D00c6f3C3`) is the on-chain anchor on which the runs below were recorded: an anchor for a single recursive SP1 "proof of proofs." One Groth16 proof attests that N inner SP1 proofs, each from a real, distinct AERE production program, were each verified inside the zkVM. The contract verifies that one Groth16 proof through the live SP1 gateway, recomputes a composite digest from the supplied inner data to bind the proof to exactly which programs were folded, and records the aggregation.
The design goal is amortization: pay for one on-chain verification and one Groth16 wrap, regardless of how many application proofs are folded underneath.
The verifier plumbing is shared with the rest of the ZK stack:
- `SP1VerifierGateway`: `0x9ca479C8c52C0EbB4599319a36a5a017BCC70628` (the aggregator holds this stable gateway address, not a concrete verifier, so new prover versions route in without redeploying the aggregator).
- `SP1VerifierGroth16_v6_1_0`: `0xb5456d48bFdA70635c13b6CBE1Ad0310Dc0171aD` (the concrete verifier the Groth16 selector `0x4388a21c` routes to).
---
## 2. Architecture: recursion in the guest, bind-and-verify in the contract
There are two halves: an SP1 guest that does the recursive verification off-chain, and the Solidity contract that verifies the resulting Groth16 proof on-chain.
### 2.1 The aggregation guest (`recursive-aggregation-scale/agg-program/src/main.rs`)
The guest reads a vector of inner verifying-key digests and a vector of inner public-value byte-strings. For each inner proof it:
1. computes `pv_digest = sha256(publicValues[i])`, the exact digest the SP1 recursion verifier binds an inner proof to;
2. calls `sp1_zkvm::lib::verify::verify_sp1_proof(&vkeys[i], &pv_digest)`, which recursively verifies, inside this zkVM, that a valid inner SP1 proof exists for that verifying key and those public values. If any inner proof is missing or invalid, the aggregation proof cannot be produced at all;
3. folds `(koalabear_vkey_digest_i || pv_digest)` into a running SHA-256.
After the loop it commits a single 32-byte composite. The guest is unchanged from the n=3 version, which is why its verifying key is stable and already registered on-chain. The host asserts the rebuilt guest reproduces the registered aggregation vkey `0x003a70854f258b13c6612b0272421f2d7d97f90eee63e124864c80be61a2672c` and aborts otherwise, since the Foundation, not the prover operator, controls which aggregation vkey the contract will route.
Inner proofs are generated as compressed SP1 (STARK) proofs. The final aggregation is Groth16-wrapped for the on-chain gateway. This is the key economic move: N compressed inner proofs plus one Groth16 wrap of the recursion, rather than N separate Groth16 wraps.
### 2.2 The contract (`AereProofAggregator.sol`)
`recordAggregation(aggVKey, innerVKeyDigests[], innerPvHashes[], publicValues, proof)` is permissionless. It:
1. requires `aggVKey` to be a registered aggregation program (`isAggProgram`);
2. checks array lengths match, N is non-zero, and `publicValues` is exactly 32 bytes;
3. recomputes the composite from the supplied inner digests using the exact same byte layout as the guest, and requires it to equal the committed 32-byte `publicValues` (reverts `CompositeMismatch` otherwise);
4. calls `ISp1Verifier(SP1_VERIFIER).verifyProof(aggVKey, publicValues, proof)` inside a `try/catch`, translating the gateway's revert-on-invalid convention into a typed `InvalidProof()`;
5. counts how many folded inner programs are recognized (registered via `registerInnerProgram`) and stores the aggregation keyed by composite, incrementing `aggregationCount`.
`SP1_VERIFIER` is immutable, set at deploy. Recorded aggregations cannot be altered or removed. A `verifyAggregation(...)` view performs the same recompute-then-verify without recording, so any caller can re-check an aggregation via `eth_call`.
Because the contract recomputes the composite from caller-supplied inner data and requires it to match the proof's own committed output, a caller cannot lie about which programs were folded: changing the claimed inner set changes the recomputed composite, which then fails to equal what the proof committed. The `record-aggregation-scale.js` driver exercises exactly this: tampering the proof body reverts, and dropping one child (so the recomputed composite no longer matches the committed value) reverts. Both rejections are recorded in `proof-aggregator-scale.json`.
---
## 3. The composite binding and the two vkey encodings
The composite is byte-identical between guest and contract:
```
composite = sha256(
u32_be(n)
|| (koalabearVKeyDigest_0 || sha256(publicValues_0))
|| ...
|| (koalabearVKeyDigest_{n-1} || sha256(publicValues_{n-1}))
)
```
Each inner program is identified by two different encodings of the same key. The `koalabearVKeyDigest` is the SP1Field (KoalaBear) digest that `verify_sp1_proof` actually checks (`SP1VerifyingKey::hash_u32`, serialized big-endian). The `onChainVKey` is the BN254 `bytes32` the program publishes for gateway verification. These are not the same 32 bytes. The Foundation registers the mapping between them (`registerInnerProgram(innerVKeyDigest, onChainVKey, label)`), so each folded program can be labelled and cross-checked against its published on-chain key. Binding the KoalaBear digest, rather than the BN254 key, is the sound choice: it is the value the recursion verifier truly checked.
---
## 4. Heterogeneity: three different programs, one proof
The folded set is not N copies of one circuit. The n=10 run folds three distinct programs with three distinct verifying keys:
- **zkscreen** (allowlist / sanctions-screening membership proof), on-chain vkey `0x006a211015aee2b90b82d266bef3aa6944551b06c488d86e895489b1dde3e5b7`, paired with the live `AereZKScreen` verifier `0x3A097A459FD26aC79573aCB5adB51430e473C2f1`.
- **over18** (age-credential proof over a Merkle-committed birth year), on-chain vkey `0x005aa94ac711bc65d0755b3a94f3622a6e8c76e2cdd708c29869587f633343c5`.
- **zkml-mnist** (a 784 to 256 to 10 MLP MNIST classifier run inside the zkVM on a private image), on-chain vkey `0x0061443ce273455d0afcdaf1103ea0a52b970d979896dc83d989e71ba7c4bceb`, paired with the live `AereZKMLVerifier` `0xf1BF15d5018a35D21FBB4Ec868f062DF7C06783c`.
`verify_sp1_proof` verifies any inner SP1 proof regardless of which program produced it, so heterogeneous folding requires no special handling: the guest simply calls it once per inner proof with that proof's own vkey digest. This is the meaningful capability. One settlement event can attest a mixed batch of an identity screen, an age proof, and an ML inference, drawn from unrelated circuits, in a single on-chain verification.
---
## 5. Proven results
### 5.1 First aggregation, n=3 (`proof-aggregator.json`)
One zkscreen, one over18, one zkml-mnist folded into one Groth16 proof.
- composite `0x8e246396a2f40c837501d06c965163db644284ffc877d7cd0d38681b612b4e36`
- on-chain verify tx `0xde4c102ab86567bfb7b384a784c049bf6ded33378e0b71acc0bfe97b7b8d4b39`, block 8811943
- on-chain gas used: **387,858**, result `true`
- aggregation program registered via tx `0x223960cbd60299dc9e09d1609d9be6195067257e70894f1df4460b4bc5e4876c`; inner programs registered for zkscreen, over18, and zkml-mnist.
### 5.2 Aggregation at scale, n=10 (`proof-aggregator-scale.json`)
Four zkscreen, four over18, two zkml-mnist, each instance a distinct statement (distinct derived user address, attestation time, and credential value), folded into one Groth16 proof.
- composite `0x11ee0c089c223aca62a6db85a3299e9d8160c72bdeb83e84e44642a4a37aa1fb`, committed as the proof's 32-byte public values, proof selector `0x4388a21c`
- record tx `0xd1fd4d60635fbafe8b269ea156a6bbc65e2b6ff8b886eb7910569a9c9344d978`, block 8930005
- on-chain gas used: **393,844**, status 1
- read-back: `exists = true`, `count = 10`, `recognized = 10` (all ten inner programs registered), `aggregationCount` now 2
- tamper checks: tampered proof reverts; dropped child reverts
Off-chain proving timings for the n=10 run: inner proofs about 988 seconds total, the Groth16 aggregation about 526 seconds, total wall time about 1549 seconds. Per-program the cost is uneven: each zkscreen and over18 inner proof took roughly 71 to 75 seconds, while each zkml-mnist inner proof took roughly 200 to 205 seconds. The two ML proofs alone account for over 400 of the 988 inner-proving seconds, which is worth noting for anyone planning a batch mix.
---
## 6. Constant on-chain cost
The headline is that the on-chain cost of recording an aggregation is essentially flat in N. The two measured points bracket a 3.3x increase in N:
| N | on-chain gas | tx |
|---|---|---|
| 3 | 387,858 | `0xde4c102a...` |
| 10 | 393,844 | `0xd1fd4d60...` |
Going from three to ten folded proofs raised on-chain gas by about 5,986, roughly 1.5 percent, for more than triple the work folded underneath. The bulk of the cost, roughly 390k gas, is the fixed Groth16 verification through the gateway, which is independent of N. The small residual growth comes from the parts that do scale with N: the calldata for the two `bytes32[]` arrays, the SHA-256 recompute of the composite over N entries, and the loop that counts recognized programs. None of that is the proof check. As N grows further, the per-record gas stays anchored near the single Groth16 verify cost; the marginal on-chain cost of one more folded proof is a few hundred gas of calldata and hashing, not another proof verification. Every record is comfortably under the EIP-7825 (Fusaka) per-transaction gas cap of 2^24 = 16,777,216; the driver estimates gas and asserts it is under the cap before sending.
---
## 7. The amortization argument
The value of aggregation is that many proofs settle behind one verification, on two axes.
**On-chain gas.** The honest baseline is: how much would it cost to get the same N proofs verified on-chain individually? SP1 Groth16 verification through the gateway is on the order of 300k gas per proof. Ten separate verifications is therefore on the order of 3,000,000 gas, before per-record storage overhead. The single aggregated record cost 393,844 gas. That is roughly an 87 percent reduction at n=10, and the saved fraction grows with N, because the aggregated cost is fixed while the individual-verification baseline is linear. Put as a marginal cost: an individually verified proof costs about 300k gas; a folded proof costs a few hundred gas of extra calldata and hashing on top of a shared, one-time 390k.
**Off-chain proving.** The saving is not only gas. Inner proofs are produced as compressed STARKs; only Groth16 and Plonk proofs are gateway-verifiable on-chain. To verify each inner proof individually on-chain, each would need its own Groth16 wrap, and a Groth16 wrap is the expensive step (the single aggregation wrap here took about 526 seconds). Aggregation replaces N Groth16 wraps with exactly one wrap of the recursion. So the amortization is real on both sides: one Groth16 wrap and one on-chain verify stand in for N of each.
**The trade, stated plainly.** Aggregation moves cost from on-chain gas and per-proof settlement events to off-chain proving latency and to a single coarse-grained record. It is the right tool when many application proofs can share one settlement point and one verification event (a periodic attestation batch, a compliance roll-up, a mixed identity-and-inference bundle). It is the wrong tool when each proof must be independently and immediately queryable on-chain with its own stored record, because the aggregator persists one composite, not N per-statement payloads. The inner `(vkey, publicValues-hash)` pairs are recoverable from the `AggregationVerified` event's `innerVKeyDigests` array, but the statement semantics are not stored in contract state.
---
## 8. What is and is not proven
**Proven, on-chain, recorded in the repo:**
- Recursive verification of ten real, heterogeneous inner SP1 proofs (three distinct programs) folded into one Groth16 proof, verified once on-chain.
- The composite binding is sound and enforced: the contract recomputes it from caller-supplied inner data and rejects any mismatch; tampering the proof or altering the claimed inner set reverts.
- On-chain cost is flat in N to within about 1.5 percent across a 3.3x increase, anchored at the single Groth16 verify cost.
- Every folded program's ELF was checked against its published on-chain vkey before proving, and the aggregation guest was checked against its registered vkey.
**Not proven, and not claimed:**
- No run beyond n=10 is recorded on-chain yet. n=16 is in progress.
- The scale-run inner statements are deterministically derived for the demonstration, not organic traffic from ten distinct users.
- This is not a production rollup or a sequencing pipeline. It is an attestation aggregator for application-layer proofs. (AERE's separate rollup-validity work, the bounded-VM `AereRollupValidity` and the newer full-EVM `AereEVMValidity` anchor, is documented elsewhere and is distinct from this contract.)
- No external audit. Three-validator, single-operator chain.
---
## 9. Trust boundary
The cryptographic check is the immutable concrete Groth16 verifier the gateway routes to. Neither the aggregator nor the gateway can forge a verification; both revert on an invalid proof. Two centralization facts remain honest to state. First, the gateway is `Ownable` (Foundation), so route management is Foundation-controlled, though a route can only point at a real verifier, never fabricate a pass. Second, `registerAggProgram` and `registerInnerProgram` are owner-only, so the set of aggregation programs the contract will route, and the human labels attached to inner digests, are Foundation-curated. The `recognized` counter reflects that curation and nothing stronger: an unrecognized-but-cryptographically-valid aggregation would still verify and record, it would simply show `recognized < count`. `recordAggregation` itself is permissionless: anyone holding a valid aggregation proof can record it without a Foundation signature.
---
## 10. Post-quantum note
The aggregation soundness rests on Groth16 over BN254 and on the SP1 recursion, both of which rely on classical hardness assumptions (elliptic-curve pairings and the underlying STARK-to-SNARK stack). They are not post-quantum. This is the standard trade for succinct, constant-size on-chain verification today. AERE's post-quantum hedging lives in a separate signature-verification suite (the Falcon, ML-DSA, SLH-DSA, and XMSS verifiers) rather than in the proof-aggregation path. A future migration of the succinct verifier to a post-quantum SNARK would be a wholesale swap of the concrete verifier behind the gateway, which the route-by-selector design is built to accommodate without redeploying the aggregator.
---
## 11. Roadmap
- Record n=16 on-chain (in progress) and confirm the on-chain gas stays anchored near the single Groth16 verify cost.
- Fold additional registered programs already wired into the host (`eujur`, `accred`) to widen the heterogeneous mix beyond the current three.
- Add an optional per-statement event index for consumers that need per-proof queryability without re-supplying inner data.
- Promote a documented batch-attestation flow (a scheduled aggregation of a period's application proofs) once organic proof traffic exists to batch.
+344
View File
@@ -0,0 +1,344 @@
# AERE Network: Zero-Knowledge Verification Stack
**Chain:** AERE Network mainnet, chain ID 2800 (Hyperledger Besu QBFT).
**Status date:** 2026-08-01. Every on-chain figure below was re-read from `https://rpc.aere.network` at head block 11,810,041 on that date.
**Source of truth for addresses:** `sdk-js/src/addresses.ts`. Contract source: `contracts/contracts/`.
**Scope:** the on-chain proof-verification layer. This covers SP1 (Groth16 / Plonk), RISC Zero, KZG / EIP-4844, Halo2, recursive proof aggregation, zkML, zk-KYC / zk-compliance, and the storage-proof coprocessor.
This document describes what each verifier proves, the exact on-chain path a proof takes to be accepted, and the honest trust boundary of each. It is deliberately conservative about claims: every capability is marked either **live** (deployed and demonstrated with an on-chain transaction recorded in the repo) or **roadmap / in development**.
---
## 0. Honesty preamble (read this first)
Six points frame everything below.
1. **This is an application / account-layer proof stack, not a consensus feature.** AERE's validators sign classical QBFT; none of the verifiers here change how blocks are produced or finalized. The verifiers are ordinary EVM contracts that any account can call. They add verifiable computation on top of the chain, not inside consensus.
2. **The network is small and centralized today.** AERE runs seven QBFT validators operated by a single operator, on a single client (Besu), at a measured mean block interval of 0.5175 s over the last 2,000 blocks. There is no external security audit of the AERE-authored contracts. On-chain usage of these verifiers is thin: the canonical `AereProofRegistry` reports `programCount() = 1` and `proofCount() = 1` at head. None of this is hidden; it is the baseline against which the engineering below should be judged.
3. **Address-citation discipline, corrected 2026-08-01.** Addresses are printed verbatim only when they appear in the canonical registry `sdk-js/src/addresses.ts`. An earlier revision of this spec withheld the hex for five contracts (KZG, Halo2, the recursive aggregator, the zkML verifier, the state-root anchor) on the grounds that they were "pending canonical registration". **That is no longer true and the omission is corrected here: all five are in the registry today**, and their addresses are printed below. Withholding them stopped protecting anything and only kept integrators away from the canonical source. One contract in that group, `AereHalo2ProofAnchor`, really is still absent from the registry, and is marked as such.
4. **Deprecation is stated, not hidden.** Several contracts in this stack have been superseded by corrected redeployments. Where that is so, this spec names the deprecated address, says what is wrong with it, and prints the replacement next to it. A reader who learns from us that something is superseded is better served than one who finds out from the chain.
5. **Ownership language.** Where a contract is described as under an "operational deployment account", that is the literal measured state: `owner()` returns a deployment or operations account rather than the Foundation account `0x0243A4f47D44b40b65D33f20329dE20D00c6f3C3`. These contracts are on the path to governance ownership. Nothing about which accounts those are, or what they could reach, belongs in a public spec.
6. **We do not claim uniqueness beyond what is demonstrable.** Where a superiority framing is tempting, the honest statement is narrow: AERE hosts a multi-prover verification surface (SP1 plus RISC Zero plus a raw KZG precompile path plus a generated Halo2 verifier) behind a route-by-selector gateway, with a permissionless attestation registry on top. That is unusual to have all in one place; it is not a claim that no other chain can verify any one of these.
---
## 1. Architecture: route-by-selector, verify-then-record
Every proof system in the stack follows the same two-layer shape.
**Layer 1, the verifier.** A concrete verifier (SP1 Groth16, SP1 Plonk, a RISC Zero Groth16 verifier, a generated Halo2 verifier, or the EIP-4844 precompile) takes proof bytes plus public inputs and either returns cleanly or reverts. The canonical SP1 and RISC Zero verifiers follow the Succinct / RISC Zero convention: `verifyProof` / `verify` **returns nothing and reverts on an invalid proof**. AERE's wrapper contracts consistently `try/catch` that revert and translate it into a typed `InvalidProof()` error, so a caller never mistakes empty return-data for a failure.
**Layer 2, routing and attestation.** Concrete verifiers sit behind routers keyed on the first 4 bytes of the proof (a version selector):
- `SP1VerifierGateway` routes an SP1 proof to the correct SP1 verifier version by its leading selector, refusing frozen routes.
- `RiscZeroVerifierRouter` routes a RISC Zero seal by its leading selector to the matching zkVM-version verifier.
Because routing is by selector, a new prover version is added with a single `addRoute` / `addVerifier` call on the router. Downstream application contracts that hold only the **router** address need no migration when a new prover version ships. AERE's application verifiers (storage proof, zk-KYC, zkML, rollup validity, aggregator) all hold the SP1 **gateway** address, not a concrete verifier, exactly for this reason.
On top of the routers, `AereProofRegistry` records each successful verification as a permanent, event-indexed attestation, with permissionless program registration.
---
## 2. SP1 (Succinct Labs): Groth16 and Plonk
**Contracts (canonical, in `addresses.ts`):**
- `SP1VerifierGateway`: `0x9ca479C8c52C0EbB4599319a36a5a017BCC70628`
- `SP1VerifierGroth16_v6_1_0`: `0xb5456d48bFdA70635c13b6CBE1Ad0310Dc0171aD` (current production)
- `SP1VerifierGroth16_v6_0_0`: `0xa9BD3020bC9a9614F9e2BC1618153c9fB1890ca6` (prior production, retained)
- `SP1VerifierPlonk_v6_1_0`: `0x24a7a85E6D9A2b120F2730880bE7283dFB14d29B`
**What it proves.** SP1 is a RISC-V zkVM. A guest Rust program is compiled to an ELF; its verification key (`programVKey`, a `bytes32`) binds that exact ELF. A proof attests that the guest ran to completion on some private witness and committed a specific `publicValues` byte-string. Groth16 gives constant-size (roughly 260 to 356-byte) proofs at about 300k gas to verify; Plonk avoids a per-circuit trusted setup at a somewhat higher verification cost. Both are routed by the same gateway.
**Verification path.** `SP1VerifierGateway.verifyProof(programVKey, publicValues, proofBytes)` reads `bytes4(proofBytes[:4])` as the selector, looks up `routes[selector]`, reverts `RouteNotFound` / `RouteIsFrozen` on a bad route, and otherwise delegates to the concrete verifier's `verifyProof`. The Groth16 route selector on chain 2800 is `0x4388a21c` (the leading 4 bytes of the v6.1.0 Groth16 verifier's `VERIFIER_HASH` `0x4388a21c687fdd5f...`); the Plonk verifier hash is `0x5a093a2f...`. **Ownership and trust boundary, measured 2026-08-01.** The gateway is `Ownable`, and `owner()` returns an operational deployment account, **not** the Foundation account `0x0243A4f47D44b40b65D33f20329dE20D00c6f3C3`. An earlier revision of this spec said "Ownable (Foundation)"; that was wrong, and the contract is on the path to governance ownership.
The same earlier revision drew a stronger conclusion than the code supports: it said the route owner "cannot forge a verification, because the actual cryptographic check happens in the immutable concrete verifier the route points at". **Only the first half of that is true.** Each concrete verifier is indeed immutable, so no one can change what a given verifier checks. But `addRoute(bytes4,address)` (selector `0x8c95ff1e` in the live 1,746-byte gateway bytecode) and `freezeRoute(bytes4)` (`0x814856f4`) mean the route owner chooses **which** contract performs the check for a given selector. The honest statement is therefore:
> A proof accepted through the gateway is exactly as sound as the concrete verifier the route currently points at. Immutability protects the verifier; it does not by itself constrain the route owner. An integrator who needs the stronger guarantee should hold the concrete verifier address (`0xb5456d48…`, `0x24a7a85E…`) directly, or wait for the route to be frozen, or wait for the gateway to sit behind governance. Live routes measured at head: `0x4388a21c` to `0xb5456d48…`, `0x5a093a2f` to `0x24a7a85E…`, neither frozen.
This is a real limitation of the router pattern, not of this deployment alone, and the same reasoning applies to `RiscZeroVerifierRouter` in section 3.
**Notes.** A legacy v4.0.0-rc.3 SP1 verifier and registry were deployed on 2026-05-31 (recorded in `contracts/deployments/zkverify-stack.json`) and retain a historical Fibonacci fixture proof (registry proof id 0). Production traffic uses the v6.1.0 gateway above. Every AERE application verifier in this spec that says "SP1" routes through this one gateway.
---
## 3. RISC Zero zkVM: Groth16 receipts
**Contracts (canonical, in `addresses.ts`):**
- `RiscZeroVerifierRouter`: `0x3f7015BC3290e63F7EC68ecF769b00aB296a249C` (2,042 bytes; `owner()` measured at head returns an operational deployment account, not the Foundation account; moving to governance)
- `RiscZeroGroth16Verifier_DEPRECATED`: `0x95cB30f3bdb3187f39203A9907bf707Aef07a1FD` (do not use)
- `RiscZeroGroth16Verifier`: `0xb6fD00D88Bf8B08d6371d2D98E0e239B89Ab5B9D` (corrected)
- `RiscZeroVerifierRouter_Corrected`: `0x62b96F7211F832f47d8Fc0D8317D5867B0Af43E5`
- `AereProofRegistry_Corrected`: `0x174F616E2048A71408E2491791ef77cd6913bbEf`
**What it proves.** RISC Zero is a second RISC-V zkVM. A receipt attests that a guest with a given `imageId` produced a journal whose digest is `journalDigest`. `RiscZeroVerifierRouter.verify(seal, imageId, journalDigest)` routes by the seal's leading selector to the concrete Groth16 verifier, which checks the seal against RISC Zero's `CONTROL_ROOT` / `BN254_CONTROL_ID` circuit-binding constants (`ControlID.sol`) for a specific zkVM release (`VERSION = "5.0.0-rc.1"`).
**A real bug, honestly recorded.** The originally deployed RISC Zero verifier (`0x95cB...a1FD`) was bootstrapped with a **non-canonical control root** (`0xb1f640...488167`) that matches no released risc0 version. That wrong root computes selector `0xc27d1bc0`, so the router could never route a genuine risc0 5.0.0-rc.1 receipt (which carries selector `0xef6cb709`): every real seal reverted `SelectorUnknown`. The fix, recorded in `contracts/deployments/risc0-verifier-fix.json`, deployed a **corrected** verifier (`0xb6fD...5B9D`) with the genuine control root `0x4ec911...bde5b04` and selector `0xef6cb709`.
**Why there is a "corrected" side stack, and the premise that turned out to be wrong.** A parallel corrected router (`0x62b9...43E5`) and registry (`0x174F...bbEf`) were deployed to record a real RISC Zero proof: a risc0 5.0.0-rc.1 Groth16 factorization proof (guest proves knowledge of a nontrivial factorization of n = 11,917,497,200) was registered and recorded (submit tx `0xf9269dde...396e629`, record id 0), with independent public-RPC read-back confirming accept-on-valid and `VerificationFailed()` on tampered journal or seal. That proof and that read-back are real and stand.
The **reason** given for building that side stack does not stand. An earlier revision of this spec said the account that built the fix "cannot `addVerifier` on the Foundation router". Measured at head, `owner()` on the canonical router `0x3f7015BC…` returns that same operational deployment account, so it always could, and it since has. The side stack is therefore historical, not necessary. New integrations should use the canonical router and registry, not `0x62b9…43E5` / `0x174F…bbEf`.
**Canonical RISC Zero recording is LIVE, not roadmap (corrected 2026-08-01).** An earlier revision listed one `addVerifier(0xef6cb709, 0xb6fD…5B9D)` as "staged but not yet executed", and called canonical R0 recording "roadmap". **That transaction has been executed.** Measured at head on `https://rpc.aere.network`:
- `RiscZeroVerifierRouter(0x3f7015BC…).getVerifier(0xef6cb709)` returns `0xb6fD00D88Bf8B08d6371d2D98E0e239B89Ab5B9D`
- the `verifiers(0xef6cb709)` mapping returns the same address
- `AereProofRegistry(0x0A9b0967…).risc0Router()` returns `0x3f7015BC3290e63F7EC68ecF769b00aB296a249C`
- the corrected verifier `0xb6fD00D8…` carries 4,664 bytes of live code
So the canonical path from a genuine risc0 5.0.0-rc.1 seal to a recorded attestation in the canonical registry is connected end to end. What remains open is **usage, not capability**: `programCount()` and `proofCount()` on the canonical registry are both 1 at head, and that single record is an SP1 Fibonacci fixture, not a RISC Zero proof. Capability live, traffic zero.
---
## 4. Multi-prover attestation registry
**Contract (canonical):** `AereProofRegistry`: `0x0A9b09677DbE995ACfC0A28F0033e68F068517Ee` (7,196 bytes; `owner()` measured at head returns an operational deployment account, not the Foundation account; moving to governance).
**Measured usage, stated up front.** The mechanism described below is real and the code is live. The traffic is not. At head, `programCount() = 1` and `proofCount() = 1`. The single registered program is "SP1 Fibonacci (canonical)" and the single recorded proof is the fib(20) = 6765 fixture from block 2,151,318. Every other statement in this section describes a capability, not a volume.
**Purpose.** A single log that verifies **and records** proofs from both SP1 and RISC Zero. Its design goals:
- **Verify then record.** `submitSP1Proof` calls `ISP1Verifier(sp1Gateway).verifyProof(...)` (reverts on invalid), then writes a `ProofRecord` and emits `ProofVerified` with the program key indexed. `submitRiscZeroProof` does the same through `IRiscZeroVerifier(risc0Router).verify(...)`. Off-chain consumers subscribe to `ProofVerified` filtered by their program of interest.
- **Permissionless program registration.** Anyone registers their own SP1 vkey or R0 imageId with a human-readable name plus URL (`registerSP1Program` / `registerRiscZeroProgram`). The Foundation can `disableProgram` a malicious program but cannot disable a legitimate one, and disabling never retroactively invalidates already-recorded proofs.
- **Free verdicts.** `verifySP1Only` / `verifyRiscZeroOnly` are `view` functions that give the verdict (revert-on-invalid) without writing a record, for dApps that need the answer but not a permanent attestation.
Both immutables `sp1Gateway` and `risc0Router` are set at construction. Because the registry holds the **gateway/router** (not a concrete verifier), SP1 v7 or a new R0 verifier plug in upstream with no registry migration. The `AereProofRegistryV2.sol` source in the repo is an equivalent multi-prover registry design; the canonical live registry is the address above.
---
## 5. KZG / EIP-4844 point-evaluation verifier
**Contract (canonical, in `addresses.ts`):** `AereKZGVerifier`: `0x6596307BD8f54d9A91FE364EBC3e594F200AC862`, 1,988 bytes of live code measured at head. KAT plus on-chain verify tx recorded in `contracts/deployments/kzg-verifier.json`. An earlier revision of this spec called this contract "deployed, not yet in `addresses.ts`" and withheld the hex; it has been in the canonical registry (line 386) and the omission is corrected here.
**What it proves.** That a blob polynomial `P` committed to by a 48-byte KZG `commitment` evaluates to `y` at point `z`, that is `P(z) == y`, using the EIP-4844 **point-evaluation precompile at address `0x0A`**. This is the primitive underlying blob-data availability and any KZG-commitment scheme.
**Verification path.** `verifyPointEvaluation(bytes input)` forwards the raw 192-byte precompile input (`versioned_hash(32) | z(32) | y(32) | commitment(48) | proof(48)`) to `0x0A` via `staticcall`. On a valid proof the precompile returns exactly 64 bytes: `uint256(FIELD_ELEMENTS_PER_BLOB = 4096) | uint256(BLS_MODULUS)`. The contract enforces **both** the success flag **and** that canonical 64-byte return (rejecting any other length or constants), then records `(sender, versionedHash, z, y, block, time)` append-only. `checkPointEvaluation` is the gas-cheap `view` twin. Because precompiles have no code, the contract deliberately does no `extcodesize` check; correctness is enforced by the strict canonical-constant return, which no empty account or stray contract can satisfy by chance.
**Live evidence.** EIP-4844 blob support is active on chain 2800: the precompile was confirmed against the official go-ethereum known-answer vector (`pointEvaluation1`), and an on-chain verify transaction is recorded (gasUsed about 255,719 per the artifact). No owner, no admin, append-only.
**Honest scope.** This verifies a KZG opening; it does not by itself prove that a particular blob was posted for a particular transaction. QBFT produces no blobs (`BLOBBASEFEE` returns 0), so this is a verification primitive available to applications, not a data-availability layer the chain itself uses.
---
## 6. Halo2 (bn254 / KZG) verifier plus anchor
**Contracts:** `AereHalo2CubicVerifier` (generated verifier) is **canonical, in `addresses.ts` line 387**: `0x414Cfe640B2770856d3D7262a7a3729f5c07dC55`, 4,804 bytes of live code measured at head. Its companion `AereHalo2ProofAnchor` (record) is genuinely **still absent from `addresses.ts`**; its address, the proof hash and the on-chain verify tx are recorded in `contracts/deployments/halo2-cubic.json`. An earlier revision of this spec described both as pending registration; that was correct for the anchor and wrong for the verifier.
**What it proves.** The bound circuit is a real 4-row standard-PLONK circuit proving knowledge of a private `x` with `x^3 + x + 5 == out`, where `out` is the single public instance (demonstrated with `out = 35`). The verifier is generated by `privacy-scaling-explorations/halo2-solidity-verifier` (bn254 / KZG commitments, Bdfg21 / SHPLONK batch opening) with the verifying key embedded in bytecode.
**Verification path.** `AereHalo2ProofAnchor.verifyAndRecord(proof, instances)` calls `IHalo2Verifier(VERIFIER).verifyProof(proof, instances)`; the generated verifier returns `true` and reverts on an invalid proof. On success the anchor records `(sender, keccak256(proof), keccak256(instances), block, time)` append-only. The verifier address is immutable; no owner, no admin. Per the artifact, on-chain verify gas is about 449,517 (proof 1152 bytes, revm gas about 300,144), with valid-accept and tampered-reject both demonstrated.
**Honest scope: the SRS is a dev setup, not a ceremony.** The KZG structured reference string was generated locally on the AERE build server (`ParamsKZG::setup`), **not** from a public trusted-setup ceremony. That is fine for demonstrating that AERE can host and verify a real Halo2 proof on-chain; it is **not** production-grade for a value-bearing circuit, where a multi-party ceremony SRS would be required. This is the single most important caveat on the Halo2 path and is stated plainly in the artifact.
---
## 7. Recursive proof aggregation
**Contracts, and which one to integrate against.** Both are in `addresses.ts` and both are live; they are not interchangeable.
| Contract | Address | Live code | Status |
|---|---|---|---|
| `AereProofAggregator_DEPRECATED_UNENFORCED_INNER_VKEYS` | `0x6a260238890E740dB12b371E0C5d17a2470F84C5` | 4,531 bytes | **DEPRECATED. Do not integrate.** |
| `AereProofAggregatorV2` | `0x944dE720D6C9696Bdf10b6E2F00dd21ABB1A2b4C` | 4,663 bytes | **CANONICAL** |
**Why V1 is deprecated, stated plainly.** V1 **counted** how many folded inner programs were recognized and then recorded the aggregation regardless. It never **enforced** that every inner program was a registered one. The registry entry names it for exactly that: unenforced inner vkeys. V2 rejects an aggregation containing an unregistered inner program.
`owner()` on both returns the Foundation account `0x0243A4f47D44b40b65D33f20329dE20D00c6f3C3` (measured at head). Aggregation counts at head: V1 = 2, V2 = 1. Aggregation vkey, inner-program mappings and both V1 on-chain records are in `contracts/deployments/proof-aggregator.json` and `proof-aggregator-scale.json`.
**What it proves.** One SP1 Groth16 "proof of proofs." An aggregation guest recursively verified N inner SP1 proofs **inside** the zkVM via `verify_sp1_proof`, and committed a single composite digest binding all N `(innerVKeyDigest, innerPublicValuesHash)` pairs:
```
composite = sha256( u32_be(n) || (innerVKeyDigest_0 || innerPvHash_0) || ... || (innerVKeyDigest_{n-1} || innerPvHash_{n-1}) )
```
`innerVKeyDigest_i` is the KoalaBear (SP1Field) verifying-key digest the recursion verifier actually checked. Binding that, rather than the BN254 on-chain vkey, is the right thing to bind, because it is the digest the recursion actually verified against.
**An earlier revision of this spec called the resulting on-chain check "maximally sound". Withdrawn.** That phrase described V2's behaviour and was attached to V1's address. On V1 the composite binding above is enforced, so an aggregation cannot claim children it did not fold; but membership of each child in the registered-program set was only counted, never required. "Maximally sound" is not a property V1 has. It is the property V2 was built to add.
**Verification path.** `recordAggregation(aggVKey, innerVKeyDigests[], innerPvHashes[], publicValues, proof)`:
1. requires `aggVKey` is a Foundation-registered aggregation program;
2. recomputes `composite` from the supplied inner arrays **byte-for-byte with the guest** and requires it equals the 32-byte `publicValues`;
3. verifies the Groth16 proof through the SP1 gateway (selector `0x4388a21c`);
4. counts how many folded inner programs are recognized (registered via `registerInnerProgram`, which cross-maps each KoalaBear digest to its published on-chain BN254 vkey and a label) and records the aggregation.
**Live evidence.** Two real aggregations are recorded on chain 2800: a 3-proof fold (inner programs `zkscreen`, `over18`, `zkml-mnist`; record tx `0xde4c102a...`, gasUsed about 387,858) and a **10-proof** scale fold of distinct statements (record tx `0xd1fd4d60...`, block 8930005, gasUsed about 393,844, `recognized = 10/10`). Note the gas to verify the aggregate on-chain is roughly flat (about 390k) whether folding 3 or 10 inner proofs; that constant-verification-cost property is the point of recursion. The proving side is not free: the scale artifact records about 526s to produce the aggregation Groth16 and about 988s of inner proving (measured, off-chain). Tampering (mutated proof or a dropped child) reverts.
---
## 8. zkML: private machine-learning inference
**Contract (canonical, in `addresses.ts` line 392):** `AereZKMLVerifier`: `0xf1BF15d5018a35D21FBB4Ec868f062DF7C06783c`, 3,658 bytes of live code measured at head. Model vkey/hash, accuracy and the on-chain verify tx are in `contracts/deployments/zkml-mnist-verifier.json`. An earlier revision called this "deployed, not yet in `addresses.ts`" and withheld the hex; that is corrected here.
**What it proves.** That a registered ML model classified a **private** input without revealing that input. The reference model is a genuinely trained, quantized MNIST digit classifier (784 to 256 to 10 integer MLP, ReLU, argmax). The forward pass runs inside the SP1 zkVM on a private 28x28 image; only the predicted digit is made public.
**Model binding, and which call path actually enforces it.** Each model is registered by the Foundation with `programVKey` (binds the exact guest ELF, which embeds the quantized weights), `modelHash` (`keccak256` of the weight blob, recomputed inside the zkVM), `numClasses`, and a measured `accuracyBps`.
**Only the stateful path enforces registration. The free `view` path does not.** This is the single most important integration caveat on this contract and an earlier revision of this spec did not state it. In the live source:
- `submitInference` / `verifyAndRecord` check that the model is `registered`, and bind `chainId`, `user` and `modelHash` as described below. Use this path if you need "a **registered** model produced this classification".
- the public `verify(bytes32, bytes, bytes)` twin checks **only** that `publicValues` is 128 bytes long and that the Groth16 proof is valid, then decodes the class. It does not consult the model registry, does not check `chainId`, does not check `user`, does not check `modelHash`, and records nothing. The contract's own source comment says as much.
So `verify` answers "some SP1 program with this vkey produced this output", not "the registered model classified this input". An integrator who calls `verify` and reports "registered model" to a user is over-claiming. If you only have the free path available, treat the vkey you pass in as the thing you are trusting, and pin it yourself. The reference model's measured accuracy is **97.98%** (9798 of 10000 correct on the MNIST test set; float baseline 98.01%), recorded on-chain for transparency.
**Verification path.** `submitInference(programVKey, publicValues, proof)` requires the model is registered, requires `publicValues` is exactly 128 bytes = `abi.encode(chainId, user, modelHash, predictedClass)`, verifies the SP1 proof through the gateway, then binds `chainId == block.chainid`, `user == msg.sender`, `modelHash == registered model`, and `predictedClass < numClasses`, and records the user's latest verified prediction. `verify(...)` is a stateless `view` twin. Per the artifact, the reference inference verified on-chain at gasUsed about 326,492; the guest runs about 5.22M cycles using the SP1 keccak precompile to hash the 407,592-byte weight blob (24.5M cycles without it).
**Honest scope.** This proves inference integrity for one small, quantized model on one dataset. It is a real, measured classifier, not a toy with hand-picked weights (it supersedes an earlier 4-to-8-to-3 toy). It is not a general zkML framework and makes no claim about large models.
---
## 9. zk-KYC / zk-compliance
Three related contracts implement "prove a compliance property without putting PII on-chain."
### 9.1 AereZKScreen (canonical)
**Contract:** `AereZKScreen`: `0x3A097A459FD26aC79573aCB5adB51430e473C2f1` (v3; 3,625 bytes live). `owner()` measured at head returns the Foundation account `0x0243A4f47D44b40b65D33f20329dE20D00c6f3C3`, so "Foundation-owned" is accurate here and was re-verified rather than assumed.
**The over-18 attribute program is REGISTERED and live (measured 2026-08-01).** Other AERE documents have described on-chain registration of the over-18 program as "not yet done, pending a single Foundation signature", and said that submitting an over-18 proof would revert as an unknown program. **Measured, that is no longer the case.** Reading `programs(0x005aa94ac711bc65d0755b3a94f3622a6e8c76e2cdd708c29869587f633343c5)` on the live contract returns `registered = true` with a non-zero `authorizedRoot` (`0xb3b4d506…40b304`) and a description recorded on-chain that reads, in part, "SP1 Groth16 zero-knowledge proof that an issuer-attested birth year implies age 18+ (born <= 2008), without revealing the date of birth. No PII on-chain." Because the authorized root is set as well as the registration, the root-binding check described below is armed, not bypassed. The capability is shipped. Usage of it is a separate question and remains thin.
**What it proves.** That a user passed an off-chain compliance screen (sanctions check, residency / accredited-investor / MiCA-jurisdiction attestation) inside an SP1 zkVM, anchoring only a boolean-style clearance. dApps gate access with `isCleared(user, programVKey, minTimestamp)`; no PII touches the chain.
**Verification path plus the critical soundness fix.** `submitProof(programVKey, publicValues, proof)` requires the program is registered, requires `publicValues` is exactly 128 bytes = `abi.encode(chainId, user, attestedAt, extraDataHash)`, verifies the SP1 proof, then enforces: `chainId` matches, `user == msg.sender`, `attestedAt <= now`, and the anti-downgrade rule `attestedAt > clearedAt[user][program]`. The **root-binding** check is the soundness core: each program binds a Foundation-set `authorizedRoot`, and the proof's `extraDataHash` **must equal** that root. Without it, a prover could prove membership in an allowlist of their own making (an "allowlist" containing only themselves), a total break of the compliance claim. The version history in `addresses.ts` records that earlier deployments had exactly this class of hole (v1 `0xE9da9c...` dead; v2 `0x140572...` had a self-clear hole); **v3** (the address above) is the root-binding fix, and adds owner `setAuthorizedRoot` rotation and per-user `revoke`.
**Consumer obligations (documented in-source).** dApps MUST pass a real `minTimestamp` (for example `now - freshnessWindow`), never 0, and MUST treat clearance as necessary-not-sufficient, AND-ing it with a live sanctions check for sanctions-sensitive flows.
### 9.2 AereCompliancePool SP1 verifier (canonical)
**Contracts:** `AereCompliancePoolSP1Verifier`: `0xE2D3fa91b680E835c971761ba75Fde0204AEF95E`; consumed by `AereCompliancePoolV2`: `0xB144c923572E5Ac1B6B961C4ccfec36917173465`.
**What it proves.** A Privacy-Pools-style compliant withdrawal: that a note is a member of a deposit Merkle root **and** an approved association root, with a spent-nullifier, recipient, fee, and refund, all without linking the deposit to the withdrawal. The SP1 guest lives at `zk-circuits/compliance-pool/program`; its vkey is the verifier's immutable `PROGRAM_VKEY` (`0x00aa183a...` per `addresses.ts`).
**Verification path.** `verify(bytes proof, uint256[8] pubs)` re-abi-encodes the 8 public inputs `[poolId, depositRoot, associationRoot, nullifierHash, recipient, feeRecipient, refund, fee]` into the exact struct the guest commits, then `staticcall`s `ISP1Verifier.verifyProof(PROGRAM_VKEY, publicValues, proof)` and returns the success bool to fit the pool's `IPrivacyPoolVerifier` interface. It is a drop-in production replacement for the test `MockPrivacyPoolVerifier`. The pool itself (`AereCompliancePoolV2`) is sanctions-gated plus Travel-Rule-bound and, per `addresses.ts`, currently holds 0 deposits (fresh).
### 9.3 AereAIProof (provenance, not zk)
**Contract:** `AereAIProof`: `0xFf92c669AbF4C1DAE31eBFCC017764036d9D97e6`.
Included here for completeness because it is often grouped with the compliance/attestation set, but it is **signature-based, not zero-knowledge**. Providers register a `modelId` with a signing key and anchor EIP-712-signed `(modelId, inputHash, outputHash, requesterHash, timestamp, nonce)` statements. Only hashes are stored (no raw prompts or completions). It gives tamper-evident AI-inference provenance (useful for agentic AERE402 flows and regulated AI audit logs) with a per-model monotonic nonce, a rotate-invalidates-old-nonce-space watermark, and `ECDSA.recover` against the current signer. It proves who signed what, not a hidden computation.
---
## 10. Storage-proof coprocessor
**Contracts, and which one to integrate against.** All four are in `addresses.ts`; two of them are deprecated.
| Contract | Address | Live code | Status |
|---|---|---|---|
| `AereStorageProofVerifier_DEPRECATED_POISONABLE` | `0xF9a1A183bEb3147D88dA5927301683fEbFb9362E` | 1,710 bytes | **DEPRECATED. Do not read `getProven()` as canonical.** |
| `AereStorageProofVerifierV2` | `0x487021f9aE018657B7335ADC6Fc254717751a1Dd` | 3,160 bytes | **CANONICAL** |
| `AereStateRootAnchor_DEPRECATED_WIRED_TO_POISONABLE_V1` | `0x78b40a983E89c91Aefd8A62Be709bDF25ABB57cb` | see registry | **DEPRECATED** |
| `AereStateRootAnchorV2` | `0x0b959402283c0D2B9db4FfD7823f99782462e488` | 2,652 bytes | **CANONICAL** |
An earlier revision of this spec called `0xF9a1A183…` "canonical, immutable, no owner". Two of those three words are still true and the important one is not. It **is** immutable and it **has** no owner. It is **not** canonical: the canonical registry has named it `_DEPRECATED_POISONABLE` and says literally "DO NOT read `getProven()` as canonical; repoint to V2".
**Why V1 is deprecated, stated plainly.** V1's stored record is keyed on `(blockNumber, account, slot)` but the record it writes carries whatever `stateRoot` the proof asserted. Because `blockNumber` is only metadata to the verifier (see the canonicity gap below), anyone can submit a genuine proof against a **non-canonical** root and thereby overwrite that key with a value that was never in the canonical chain. The record is poisonable. V2 closes this by binding to the canonicity anchor: `AereStorageProofVerifierV2.CANONICAL_ANCHOR()` returns `0x0b959402283c0D2B9db4FfD7823f99782462e488`, verified in both directions at head.
Everything below describes the shared proof mechanism, which is the same in both versions. Integrate it through V2.
**What it proves.** That, at a **given** state root R, an account A's storage slot S held value V. The SP1 guest (`aere-storage-proof-program`) RLP-decodes and hash-chains the real `eth_getProof` account-proof and storage-proof nodes of AERE's Merkle-Patricia state trie: it walks `stateRoot` to `storageRoot`, then `storageRoot` to `value`, panicking on any node whose keccak256 does not match its parent reference. No Foundation-seeded side tree is involved.
**Verification path.** Public values are exactly 192 bytes = `abi.encode(chainId, blockNumber, stateRoot, account, slot, value)`. `submitProof` verifies through the SP1 gateway (`PROGRAM_VKEY = 0x0015e599...b659`), enforces `chainId == block.chainid`, and records `keccak256(blockNumber, account, slot)` to `{stateRoot, value, at}`. `submitProofWithExpectedRoot` additionally reverts unless the proof's `stateRoot == expectedStateRoot`, moving the canonicity check to the call site. `verify` is a stateless `view` twin.
**Live evidence.** A first real proof is recorded: `AereTreasury` (`0x687933...6119`) slot 0 (its `owner`) equals the Foundation (`0x0243A4...f3C3`) at block 8915939, against canonical state root `0x515fce04...4a92f3` (confirmed equal to `eth_getBlockByNumber(8915939).stateRoot`); submit tx `0xe541c52b...6c54`, gasUsed 348,345. Tampered proof or public values revert.
*(An earlier revision added "under the EIP-7825 per-transaction cap of 16,777,216" here. That comparison is withdrawn as **NOT MEASURED**: we have not confirmed the per-transaction cap by reading the live chain. An `eth_call` carrying gas 0x2000000, which is 33,554,432 and therefore above the stated cap, succeeded without error, and `eth_estimateGas` does not discriminate. The only conclusive probe would be a transaction above the cap, which we do not send. What we did measure is that the header `gasLimit` at head is `0x1fffffffffffff` = 9,007,199,254,740,991, so a 16,777,216 cap does not come from the block limit and cannot be inferred from it. The 348,345 figure itself is measured and stands on its own.)*
**Honest scope: the canonicity gap, and how the anchor closes it.** The verifier alone proves "V is slot S of A in the trie whose root is `stateRoot`"; it does **not** prove that `stateRoot` is the canonical root of `blockNumber` (`blockNumber` is metadata). The consumer must establish canonicity independently. `AereStateRootAnchorV2` (`0x0b959402…`) is the building block for that: it recovers a canonical block hash strictly from the `BLOCKHASH` opcode (never a caller argument), checks a caller-supplied RLP header against it, and records the header's state root as an anchored, trust-minimized value. `BLOCKHASH` is live but serves only the last **256 blocks**, about 132 s at the measured 0.5175 s block interval.
**EIP-2935 IS deployed on chain 2800. Correction of 2026-08-01.** An earlier revision of this spec stated twice that "the EIP-2935 history contract is not deployed on chain 2800, so the extended roughly 8191-block window is unavailable". **That is false, and it is false in the direction that under-sells the chain: we said we lacked a capability we have.** Measured at head on `https://rpc.aere.network`:
- `eth_getCode` at `0x0000F90827F1C53a10cb7A02335B175320002935` returns **83 bytes**. The contract is there. It went live with the AerePQC fork at block 9,189,161.
- the serve window was measured end to end by reading the contract directly with a 32-byte block number. Offsets of 1, 255, 256 and 8,190 blocks behind head each returned exactly the canonical block hash reported by `eth_getBlockByNumber` for that height. An offset of 8,191 and anything beyond it reverts. That is the 8,191-entry history ring behaving exactly as specified, with one slot held by the in-flight block.
The consequence for this section is that the extended lookback is **available**, not roadmap. `AereHistoryStateRootAnchorV2` (`0x4C1F9daD515c7990b65F9833960CA4315216330C`, 2,915 bytes, `addresses.ts` line 391) is the deployed consumer of it, and its `HISTORY_STORAGE_ADDRESS()` returns `0x0000F90827F1C53a10cb7A02335B175320002935`, read from chain.
**One open item on that anchor, stated because we found it.** `AereHistoryStateRootAnchorV2.VERIFIER()` returns `0xF9a1A183bEb3147D88dA5927301683fEbFb9362E`, which is the storage-proof verifier this same section marks deprecated. The extended-lookback anchor is therefore wired to the deprecated verifier. Do not treat that combination as a canonical record path until it is repointed. This is a real loose end and it is ours.
---
## 11. Rollup validity anchor
**Contract:** `AereRollupValidity`: `0x38772063572DF94E90351e44ccbBEefD5F497fbd` (immutable, no owner).
**What it proves.** An SP1 Groth16 validity proof that AERE's deterministic rollup executor transitioned `prevRoot` to `postRoot` by applying a batch committed as `batchHash`. Unlike an optimistic rollup with a challenge window, an epoch recorded here is final the instant the proof verifies.
**Verification path.** Public values are exactly 160 bytes = `abi.encode(chainId, prevRoot, postRoot, batchHash, numTxns)`. `submitEpoch(publicValues, proof)` verifies through the SP1 gateway (`PROGRAM_VKEY = 0x00c39737...84ad`, selector `0x4388a21c`), binds `chainId`, enforces canonical-chain continuity `prevRoot == latestRoot`, then records the epoch and advances `latestRoot`. Immutables `SP1_VERIFIER`, `PROGRAM_VKEY`, `GENESIS_ROOT` are fixed at deploy; submission is permissionless and gated only by the proof plus continuity, so anyone can advance the tip and no one can fork it. Epoch 0 is recorded from a **real** proof (submit tx `0xd4f8d858...12a4b0`, block 8880188; `latestRoot = 0x256fa277...25e3ac`, `epochCount = 1`), verified against the production `aere-block-stm` executor's state root for the same 5-tx batch.
**Honest scope.** This proves the state transition of AERE's **current bounded-VM** executor: a fixed transaction set (Transfer / Sweep / Increment / AmmSwap over a balance/storage map), **not** arbitrary EVM bytecode. It is a real validity proof of that executor. Nothing built on this contract should imply it proves a full EVM.
**Update, 2026-08-01.** An earlier revision described replacing the guest VM with a real EVM (revm) inside the zkVM as "a separate multi-quarter effort" still ahead of us. **That work shipped.** `AereEVMValidity` `0x1f2CB0ebDBb21500e99868DbF1dB3abCcDd7DF26` (2,095 bytes live) and `AereEVMValidityBatch` `0x49D30a5999eA5b7f6eFf12196AB006316683Ff3C` (2,776 bytes live) each report `provenCount() = 1` at head, and the canonical-bound successors `AereEVMValidityV2` `0x4884ad66…` (2,852 bytes) and `AereEVMValidityBatchV2` `0xe154B899…` (3,425 bytes) are live. They are the subject of `spec-full-evm-validity.md`. The bounded-VM anchor described in this section remains what it is; the full-EVM path is a different, live contract, and anyone reaching for one should know the other exists.
---
## 12. Consolidated status and address table
**Canonical (verbatim from `sdk-js/src/addresses.ts`):**
| Subsystem | Contract | Address | Status |
|---|---|---|---|
| SP1 routing | `SP1VerifierGateway` | `0x9ca479C8c52C0EbB4599319a36a5a017BCC70628` | Live |
| SP1 Groth16 (prod) | `SP1VerifierGroth16_v6_1_0` | `0xb5456d48bFdA70635c13b6CBE1Ad0310Dc0171aD` | Live |
| SP1 Groth16 (prior) | `SP1VerifierGroth16_v6_0_0` | `0xa9BD3020bC9a9614F9e2BC1618153c9fB1890ca6` | Live, retained |
| SP1 Plonk | `SP1VerifierPlonk_v6_1_0` | `0x24a7a85E6D9A2b120F2730880bE7283dFB14d29B` | Live |
| RISC Zero routing | `RiscZeroVerifierRouter` | `0x3f7015BC3290e63F7EC68ecF769b00aB296a249C` | Live; route `0xef6cb709` is set to `0xb6fD00D8…` (measured) |
| RISC Zero Groth16 (corrected) | `RiscZeroGroth16Verifier` | `0xb6fD00D88Bf8B08d6371d2D98E0e239B89Ab5B9D` | Live |
| RISC Zero Groth16 (bad root) | `RiscZeroGroth16Verifier_DEPRECATED` | `0x95cB30f3bdb3187f39203A9907bf707Aef07a1FD` | Deprecated, do not use |
| RISC Zero corrected router | `RiscZeroVerifierRouter_Corrected` | `0x62b96F7211F832f47d8Fc0D8317D5867B0Af43E5` | Live |
| Multi-prover registry | `AereProofRegistry` | `0x0A9b09677DbE995ACfC0A28F0033e68F068517Ee` | Live, R0 path connected; `programCount` 1, `proofCount` 1 |
| Historical side registry | `AereProofRegistry_Corrected` | `0x174F616E2048A71408E2491791ef77cd6913bbEf` | Live (recorded R0 proof id 0). Historical; use the canonical registry |
| Storage-proof coprocessor | `AereStorageProofVerifierV2` | `0x487021f9aE018657B7335ADC6Fc254717751a1Dd` | **Live, CANONICAL** |
| Storage-proof coprocessor V1 | `AereStorageProofVerifier_DEPRECATED_POISONABLE` | `0xF9a1A183bEb3147D88dA5927301683fEbFb9362E` | **Deprecated, record is poisonable. Do not use** |
| Storage-proof canonicity anchor | `AereStateRootAnchorV2` | `0x0b959402283c0D2B9db4FfD7823f99782462e488` | **Live, CANONICAL** |
| Extended-lookback anchor (EIP-2935) | `AereHistoryStateRootAnchorV2` | `0x4C1F9daD515c7990b65F9833960CA4315216330C` | Live; `VERIFIER()` still points at the deprecated V1 |
| zk-KYC screen | `AereZKScreen` | `0x3A097A459FD26aC79573aCB5adB51430e473C2f1` | Live (v3, root-binding) |
| Compliance-pool SP1 verifier | `AereCompliancePoolSP1Verifier` | `0xE2D3fa91b680E835c971761ba75Fde0204AEF95E` | Live |
| Compliance pool | `AereCompliancePoolV2` | `0xB144c923572E5Ac1B6B961C4ccfec36917173465` | Live (0 deposits) |
| AI-inference provenance (signed, not zk) | `AereAIProof` | `0xFf92c669AbF4C1DAE31eBFCC017764036d9D97e6` | Live |
| Rollup validity anchor | `AereRollupValidity` | `0x38772063572DF94E90351e44ccbBEefD5F497fbd` | Live (bounded VM) |
**Formerly withheld, now printed.** An earlier revision of this spec listed the six rows below as "deployed but NOT yet in the canonical registry" and deliberately omitted their hex. Five of the six have been in `addresses.ts`; the policy of omission was protecting nothing and hiding the canonical source from integrators. Code sizes measured at head.
| Subsystem | Contract | Address | Registry | Live code | Status |
|---|---|---|---|---|---|
| KZG / EIP-4844 | `AereKZGVerifier` | `0x6596307BD8f54d9A91FE364EBC3e594F200AC862` | `addresses.ts:386` | 1,988 B | Live |
| Halo2 verifier | `AereHalo2CubicVerifier` | `0x414Cfe640B2770856d3D7262a7a3729f5c07dC55` | `addresses.ts:387` | 4,804 B | Live, **dev SRS, not a ceremony** |
| Halo2 anchor | `AereHalo2ProofAnchor` | see `contracts/deployments/halo2-cubic.json` | **absent** | not measured | Deployed, genuinely still unregistered |
| Recursive aggregation | `AereProofAggregatorV2` | `0x944dE720D6C9696Bdf10b6E2F00dd21ABB1A2b4C` | `addresses.ts:396` | 4,663 B | **Live, CANONICAL** |
| Recursive aggregation V1 | `AereProofAggregator_DEPRECATED_UNENFORCED_INNER_VKEYS` | `0x6a260238890E740dB12b371E0C5d17a2470F84C5` | `addresses.ts:395` | 4,531 B | **Deprecated. Do not use** |
| zkML | `AereZKMLVerifier` | `0xf1BF15d5018a35D21FBB4Ec868f062DF7C06783c` | `addresses.ts:392` | 3,658 B | Live, 97.98% MNIST; free `verify` path checks no registration |
| State-root anchor | `AereStateRootAnchorV2` | `0x0b959402283c0D2B9db4FfD7823f99782462e488` | `addresses.ts:390` | 2,652 B | Live, 256-block `BLOCKHASH` window |
| Extended-lookback anchor | `AereHistoryStateRootAnchorV2` | `0x4C1F9daD515c7990b65F9833960CA4315216330C` | `addresses.ts:391` | 2,915 B | Live, 8,191-block EIP-2935 ring |
---
## 13. Roadmap summary (explicit "not done yet")
Four items that this list carried on 2026-07-11 have since been done, and are moved out of "not done yet" into the closed list below rather than quietly deleted.
**Still not done:**
- **Halo2 production SRS:** replace the local dev SRS with a multi-party ceremony SRS before any value-bearing Halo2 circuit. This remains the single most important caveat in the stack.
- **Register `AereHalo2ProofAnchor` in `sdk-js/src/addresses.ts`.** It is the one contract in this spec that is genuinely deployed and genuinely unregistered.
- **Repoint `AereHistoryStateRootAnchorV2.VERIFIER()`** away from the deprecated `0xF9a1A183…` and onto `AereStorageProofVerifierV2 0x487021f9…`, so the extended-lookback path is not wired to a poisonable record.
- **Freeze or govern the verifier routes.** While `addRoute` / `addVerifier` remain available to a route owner, "verified through the gateway" is only as strong as the current route (section 2). Freezing the production routes, or moving the routers behind governance, converts that from a trust assumption into a guarantee.
- **Move the routers and the canonical proof registry off the operational deployment account** and onto governance. Measured today, `owner()` on `0x9ca479C8…`, `0x3f7015BC…` and `0x0A9b0967…` is not the Foundation account.
- **Usage.** The canonical registry has one program and one proof. Everything in this spec is capability; almost none of it is traffic. We would rather say that than let a mechanism description read as a volume claim.
**Closed since the previous revision, with the measurement that closed it:**
- ~~Canonical RISC Zero recording, staged and unsigned~~ **DONE.** `getVerifier(0xef6cb709)` on the canonical router returns `0xb6fD00D8…`; `AereProofRegistry.risc0Router()` returns the canonical router. Section 3.
- ~~Promote KZG / Halo2 verifier / aggregator / zkML / state-root anchor into `addresses.ts`~~ **DONE.** All five are in the registry; their addresses are printed in section 12.
- ~~Historical-state canonicity blocked because EIP-2935 is not deployed~~ **The premise was false.** EIP-2935 is live at `0x0000F908…2935` with 83 bytes of code, and the 8,191-block ring was measured end to end. Section 10.
- ~~Full validity rollup: replace the bounded-VM executor guest with revm inside the zkVM~~ **DONE.** `AereEVMValidity` `0x1f2CB0ebDBb21500e99868DbF1dB3abCcDd7DF26` (2,095 bytes) and `AereEVMValidityBatch` `0x49D30a5999eA5b7f6eFf12196AB006316683Ff3C` (2,776 bytes) are live with `provenCount() = 1` each, and the QBFT-canonical-bound successors `AereEVMValidityV2` `0x4884ad6617e320735b65D31915d1aBC884768D9B` (2,852 bytes) and `AereEVMValidityBatchV2` `0xe154B8993FB54dB4418e03ef4a04894f29E690aE` (3,425 bytes) are live as well. See `spec-full-evm-validity.md`. Section 11's "honest next step" paragraph is updated accordingly.
**Decentralization baseline, unchanged:** seven validators, one operator, one client, no external audit, thin usage. That is what we are, it is published, and it is the frame for everything above.
---
*Every address printed above is verbatim from `sdk-js/src/addresses.ts`, with one exception that is marked as absent from it (`AereHalo2ProofAnchor`). Copying the hex correctly is not enough: where the registry marks an entry deprecated, this spec now carries that label too, because an earlier revision copied addresses faithfully and left their status behind. Performance figures (gas, cycles, accuracy, proving times) are quoted from repo deployment artifacts and are measured single-run values, not benchmarked averages. Code sizes, owners, route targets, counters and the EIP-2935 window were re-read from `https://rpc.aere.network` on 2026-08-01 at head block 11,810,041.*