aere-research/execution-kernel/MACHINE-INTERFACE-CONTRACT.md

# MachineInterface (MI) contract, Execution Kernel treapta 1

Chain 2800 (AERE). Written 2026-08-15, the day the post-quantum consensus milestone went
live at block 14,050,000. This is the seam for interface **I3** in
`aerenew/strategie/EXECUTION-KERNEL-2026-08-15.md`.

This document is a **contract**, not an implementation. Treapta 1 adds no new infrastructure.
Production Besu already ships `BlockProcessor` and `MainnetBlockProcessor` under
`ethereum/core/.../mainnet/`. Treapta 1 is (a) the written contract of what that seam guarantees
and forbids, and (b) a differential replay harness that proves two independent execution paths
derive the **same** post-state from the same input on **real live blocks**. The harness lives
next to this file: `mi-replay-diferential.mjs`.

The rule of the house applies to every sentence here: **a claim asserts no more than the
measurement that backs it.** Anything below that the harness does not measure is marked
NOT MEASURED in the harness output, never asserted as proven.

---

## 1. What MI is, in one line

    MI(pre_state, block) -> (post_state, receipts)

MI is the pure function that a block-processing engine computes. Given the world state before
a block (`pre_state`) and the block itself (`block`), it produces the world state after the
block executed (`post_state`) and the execution output (`receipts`). Nothing else is an input.
Nothing else is an output.

The value of treapta 1 is not a new virtual machine. It is that this function is **named,
isolated, and re-derivable from a stranger's machine**, so that "a second execution engine
tomorrow" becomes a mechanical slot instead of a promise.

---

## 2. The interface

```
interface MachineInterface {
    // Deterministic, side-effect-free block execution.
    // Reads state ONLY through `view`. Writes nothing outside the returned post_state.
    Result execute(StateView view, Block block);
}

// The only channel through which MI may read prior state.
interface StateView {
    Account   account(Address a);        // nonce, balance, codeHash, storageRoot
    Bytes     code(Address a);
    Word      storage(Address a, Word slot);
    Hash      blockHash(long number);    // only within the EIP-2935 / BLOCKHASH window
    Header    header();                  // the header of the block being executed
    // NO clock, NO filesystem, NO network, NO RNG, NO ambient config read here.
}

// The output of execute(). Fully determined by (pre_state, block).
struct Result {
    Hash              postStateRoot;     // world-state trie root AFTER the block
    List<Receipt>     receipts;          // one per transaction, in order
    Hash              receiptsRoot;      // trie root of receipts
    long              gasUsed;
    Bloom             logsBloom;         // OR of every receipt bloom
}
```

The three roots and `gasUsed`/`logsBloom` are exactly the header fields the live chain already
commits per block, so an MI result is checkable against the canonical header with no privileged
access. That is what the harness does.

---

## 3. What MI guarantees

1. **Determinism.** For a fixed `(pre_state, block)`, `execute` returns one and only one
   `Result`, on every machine, in every process, at every wall-clock time. Two runs that
   disagree are a contract violation, not a nondeterministic outcome to be retried. See section 5
   for the exact definition of "same" used here.

2. **Purity of reads.** Every byte of prior state that influences the result is read through
   `StateView`. If a value is not reachable through `StateView`, it may not change the result.
   This is the load-bearing rule and it has its own section (section 4).

3. **Isolation of writes.** `execute` mutates nothing observable except by returning
   `post_state`. No global, no cache that a later block can read, no file, no counter. A cache
   is permitted only if it is a pure function of `StateView` inputs and is invisible to the
   result (an index that can be dropped and rebuilt with byte-identical output; see the D-153 /
   log-filter-cache lesson in `CLAUDE.md`, "a computed index is deleted without losing history").

4. **Input closure.** The admissible inputs are exactly those in section 6. Anything outside
   that set (a timestamp read from the OS clock, an environment variable, a random seed, the
   identity of which validator won the round) is forbidden as an input. The base-fee-floor fork
   is a function of `block.number` and system properties fixed per node, therefore part of the
   ruleset, not an ambient input; see section 6.

5. **Finality independence.** MI is an execution seam, not a consensus rule. It never decides
   finality. Finality on 2800 is QBFT + Falcon (interfaces I1/I2). An MI implementation that is
   slow, absent, or divergent must never be able to touch whether a block is final. This mirrors
   the golden rule of I4: proofs never gate finality; MI never gates it either.

---

## 4. The purity rule of StateView (the one that matters)

**Everything that can change the result is read through `StateView`, and nothing else is.**

Why it is the rule the whole treapta stands on: the failure mode of a second execution path
(Block-STM in treapta 4, or a second client today) is not a loud crash. It is a **silent state
divergence**, a `post_state` that differs by one slot with no error raised. The only way that
divergence stays impossible is if the complete set of inputs is closed and named, so that two
implementations reading the same `StateView` over the same `block` cannot legally reach two
answers.

Concretely, MI is in violation if any of the following influence the result:

- the wall-clock time, an OS timer, or process uptime;
- an environment variable, a config file, or any node-local setting **other than** the fixed
  ruleset parameters of section 6;
- a random number, a map iteration order, a thread-scheduling order, or floating point;
- the contents of any cache that is not a pure function of `StateView` inputs;
- state at a height outside the window `StateView` exposes (the `blockHash` / EIP-2935 window);
- which node, which peer, or which validator produced or relayed the block.

**Negative control, required.** The purity rule is not proven by reading code and agreeing it
looks pure. It is proven by **planting an impurity and watching the gate go red.** A conforming
treapta-1 test suite MUST include at least one planted violation of the list above (for example:
make `execute` branch on `System.currentTimeMillis()`), and MUST show the differential gate
turns that plant into a divergence. A gate that has never rejected an impure implementation is
applause, not a gate. The runnable analogue of this, at the header-root level, is the negative
control mode of `mi-replay-diferential.mjs` (section 8).

---

## 5. What determinism means here

"Same result" is defined by **byte-level equality of the committed commitments**, compared in
both directions (section 7). Two MI results for the same input are equal when, and only when:

| field | equality |
|---|---|
| `postStateRoot` | identical 32-byte hash |
| `receiptsRoot` | identical 32-byte hash |
| `transactionsRoot` (input identity) | identical 32-byte hash |
| `logsBloom` | identical 256 bytes |
| `gasUsed` | identical integer value (compared by value, so `0x1f4` == `0x01f4`) |
| block `hash`, `parentHash` | identical 32-byte hash |

Determinism is a claim about these commitments, not about internal representation. Two clients
may lay out their trie nodes differently in memory, name their threads differently, and store
`extraData` differently for the same block (QBFT lets each node assemble the final header
locally, and the block hash does not cover the seals; see `CLAUDE.md`). None of that is an MI
input or output. Only the commitments above are.

**Determinism is measured across implementations, not asserted from one.** A single client
agreeing with itself proves nothing about determinism. The measurement that means something is
two engines built by different teams in different languages deriving the same commitments from
the same input. Today that is Besu (live producer; note that upstream Besu ships with parallel
transaction processing enabled by default and the fleet does not disable it, so the live engine
is the parallel-capable one, idling on empty blocks) versus Nethermind (second client, live at
`client2.aere.network`). **The independence claim has a boundary, stated here rather than found
by a hostile reader:** it holds for the upstream engine skeletons (different teams, different
languages, different codebases), and it does NOT hold for the AERE-specific ruleset. The floor
fork, the lapse windows and the PQ precompiles have a single author, this project, ported into
both forks. A rule bug with a common author passes any differential gate by construction,
because both sides inherit it. Cross-client agreement therefore catches implementation
divergence, not specification error; specification error is what the formal models and hostile
reads are for. Tomorrow Block-STM enters through the same seam (treapta 4), measured by the
same harness.

**Honesty boundary, carried from `cross-client-determinism/`.** A matching header root served
over RPC proves, on its own, only that both endpoints **serve the same bytes** for a block that
travels over devp2p. The load-bearing fact underneath is that Nethermind **validates on
processing and rejects on disagreement**: this exact client has rejected live blocks it computed
differently (`WithdrawalsEmpty` at 2,075,341, `HeaderGasUsedMismatch` at 2,149,971). A block
that sits in the follower's canonical chain below its processed head is therefore a block whose
`post_state` the follower's own engine reproduced. The harness states this boundary on every run
and never claims more than it.

The full record of that mechanism, stated before a hostile reader states it for us: every time
reject-on-disagreement fired on the live chain, the resolution was to change the rejecting
follower until it accepted the producer's chain. The two rejections cited above were resolved by
patching the follower (missing predeploys, missing chainspec keys), and the largest episode is
the floor-lapse window of section 6: the follower refused ~109,000 canonical blocks and was
given a hardcoded acceptance window (`AereFloorLapse.cs`). Two things keep the fact
load-bearing anyway. First, the acceptance windows live in header-fee derivation only; state
root, receipts root and gas used stay fully validated inside the windows, so the post-state
inference above survives. Second, the mechanism demonstrably still fires: after the first
window was encoded, the follower stopped again at 13,596,032, which is exactly how the second
lapse window was discovered. A rejection mechanism whose firings keep finding real producer
defects is doing its job; a contract that cited only its flattering firings was not.

---

## 6. Admissible inputs

`execute(StateView view, Block block)` admits exactly:

1. **`block`**: header + ordered transaction list. From the header, MI may use only the fields
   that are consensus inputs to execution: `number`, `parentHash`, `timestamp` (as the block's
   own declared timestamp, an input carried IN the block, never read from the OS clock),
   `gasLimit`, `baseFeePerGas`, `coinbase`/`miner`, `prevRandao`/`mixHash`, `withdrawals`,
   and the blob fields where active. `extraData`/seals are consensus material, not execution
   input, and MI must not branch execution on them.

2. **`view`**: the pre-state, reachable only through `StateView` as defined in section 4.

3. **The fixed ruleset**, which is a pure function of `block.number` and the per-node system
   properties that define the fork schedule, and is identical on every honest node:
   - the EVM fork rules by height/timestamp (Cancun/Prague/Osaka milestones);
   - `aere.basefee.floor.forkBlock = 10141734`, floor 1 Gwei, delivered via `BESU_OPTS`. This is
     the live AERE fork. It is a **rule keyed on block number**, not an ambient input: every node
     computes the same base-fee floor for the same height. An engine that lacks it computes a
     different fee, therefore a different state root, and is a different MI, not the same one with
     a different environment. A binary missing the floor fork froze a real node at a state-root
     mismatch while every shape check stayed green.
   - **The two floor-lapse windows, and they are part of the ruleset, not a footnote.** The live
     chain contains two dated windows in which the floor was NOT applied by the block producer:
     blocks **12,978,617 to 13,087,959** (109,343 blocks; the floor property had been silently
     lost from every validator's options and the base fee decayed to single-digit wei), and
     blocks **13,596,033 to 13,596,141** (a second, smaller lapse, found when the follower
     stopped again exactly at its edge). Inside these windows the base fee of a block is **not a
     function of the parent header**; it depends on which validator won the round. The rule an
     implementation must carry is therefore: **within these two windows, `baseFeePerGas` is
     accepted as given in the header** (validation exception), and outside them the floor rule
     applies strictly. An implementer who takes the floor rule without the windows will halt at
     block 12,978,617, which is precisely what this project's own second client did until the
     exception was encoded (`AereFloorLapse.cs` in the published follower source). A contract
     that omits the windows sends every stranger into the same wall, so they are stated here, in
     the ruleset, with their exact bounds.

Everything not in this list is inadmissible as an input. In particular: no OS clock, no RNG, no
environment read at execution time, no network, no cross-block mutable cache.

---

## 7. Both directions (the D-150 rule)

The most expensive lesson on this project (D-150, 2026-08-07): **we verified what we added,
never what we lost.** Every gate asked "does the new thing contain what we put in?" and none
asked "did it keep what was already there?" A binary missing three production subsystems passed
hundreds of green tests.

Applied to MI differential replay, "both directions" is not optional and not cosmetic:

- **Forward (Besu -> Nethermind):** for every field Besu commits, Nethermind must commit the
  same value. Catches a field Nethermind got **wrong**.
- **Reverse (Nethermind -> Besu):** for every field Nethermind commits, Besu must commit the
  same value. Catches a field Nethermind has that Besu **lacks**, and a block Nethermind holds
  that Besu does not.

The comparison therefore takes the **union of the field keys on both sides** and the **union of
the block numbers on both sides**, and flags three distinct kinds of divergence:

1. present on one side, **absent** on the other (a lost field, or a block only one side holds);
2. present on both, **different** value;
3. and it does this symmetrically, so "only on them" is caught with the same weight as
   "only on us". "Only on them" is the direction that kills.

A one-directional loop (iterate Besu's blocks, ask Nethermind for Besu's fields) is exactly the
D-150 mistake in miniature: it can never see a field or a block that exists only on the other
side. The harness does not do that.

---

## 8. The negative control (why a green run means anything)

A harness that has never gone red is decoration. Before any green run counts, the harness must
be shown to turn a planted divergence into a red verdict, using the **same comparison code** the
real run uses, not a copy of it.

`mi-replay-diferential.mjs` has a built-in negative-control mode driven by the environment
variable `AERE_MI_INJECT`. When it is set, the harness fetches **real** headers from both live
clients, plants exactly one synthetic divergence into the fetched data, runs the **real**
`compareInterval` over it, and then **inverts its success condition**: the run passes only if the
gate caught the exact planted divergence and turned red, and fails if the plant slipped through
green. This is the runnable form of "plant a fault, require red".

The plant can target either direction, so both arms of section 7 are exercised:

| `AERE_MI_INJECT` value | what it plants | which direction it proves |
|---|---|---|
| `stateRoot` (or `1`) | flips one nibble of one block's `stateRoot` on the Nethermind side | forward, value differs |
| `receiptsRoot@5` | corrupts `receiptsRoot` at interval index 5 | forward, value differs |
| `gasUsed` | bumps `gasUsed` by 1 on Nethermind | forward, value differs, numeric |
| `drop` | makes Nethermind "not have" one block | reverse, block only on Besu |
| `missing:stateRoot` | deletes the `stateRoot` field from one Nethermind header | reverse, a **lost** field |
| `stateRoot:besu` | plants the corruption on the Besu side instead | reverse, value differs |

The default `execute`-level purity control (planting an impure read and watching the gate go red)
is the Java-side obligation of section 4; the header-root control above is its runnable analogue
that anyone can execute against the live chain with no build tree.

---

## 9. The gate

Treapta 1 is CLOSED only when all of the following hold, each measured, none asserted:

1. For N real live blocks, every MI field in section 5 is **identical in both directions**
   between the Besu path and the second path. Coverage (N and the exact range) is printed, and
   any block that could not be compared is counted and attributed, never silently dropped.
2. The per-client pre-state linkage holds: within each client, `parentHash(n) == hash(n-1)`
   across the interval, so the `(pre_state, block) -> (post_state)` tuple is pinned as a chain
   and not just a set of isolated roots.
3. The negative control (section 8) turns a planted divergence red, hitting the exact field and
   block it planted, in each direction it is asked to.
4. The Java-side purity control (section 4) plants an impure read and the differential gate turns
   it red.

Items 1 through 3 are runnable today by anyone, against public endpoints, with no dependencies,
via `mi-replay-diferential.mjs`. Item 4 is the obligation on the treapta-1 test suite inside the
fork build.

---

## 10. What this contract does NOT claim

The harness prints a NOT MEASURED block naming these on every run, and its JSON report carries
them in the `honesty` field, so the non-claims travel with every result rather than living only
in this document:

- **That consensus is post-quantum.** It is not. Consensus finality is classical secp256k1 ECDSA
  QBFT plus a Falcon certificate. MI is an execution seam and says nothing about consensus.
- **That equal header roots prove independent execution by themselves.** See the honesty boundary
  in section 5. The load-bearing fact is Nethermind's reject-on-disagreement behaviour, not the
  served bytes.
- **That the second path re-executed history it never reached.** Only blocks both clients hold
  and serve in the compared interval are covered; the rest is counted as uncovered.
- **Anything about performance.** MI determinism is not throughput. This contract makes no TPS
  claim and the harness runs no benchmark.
- **Who operates the validator or client keys.** Address independence is not operator
  independence, and nothing measurable from a public endpoint settles it.
- **State older than roughly the last 512 blocks** on the public endpoints. The harness reads
  headers and bodies pinned to explicit block numbers, never a deep state query, precisely to
  stay inside what these endpoints can answer honestly.