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 independent engines, built by different teams in different languages, deriving the same commitments from the same input. Today that is Besu (serial, live producer) versus Nethermind (independent second client, live at client2.aere.network). Tomorrow it is Block-STM 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.

---

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. This is exactly the D-150 lesson: a binary missing the floor fork froze a real node at a state-root mismatch while every shape check stayed green.

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

Printed as NOT MEASURED by the harness, never as a pass:

• 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.