Skip to content

feat(satin): follow the Satin specification for SLOTNUM, Oracle hints and the oracle service, KeylessDeploy recognition and activation blocks - #417

Draft
RealiCZ wants to merge 232 commits into
cz/feat/satin-w10from
cz/feat/satin-spec-align
Draft

RealiCZ wants to merge 232 commits into
cz/feat/satin-w10from
cz/feat/satin-spec-align

Conversation

@RealiCZ

@RealiCZ RealiCZ commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Stacked on #409 (cz/feat/satin-w10). Changes that make the Satin engine follow the published Satin specification where it did not yet, in three batches:

  • the first batch covers SLOTNUM, Oracle hints and the oracle service, KeylessDeploy recognition, and the activation-block rules, and makes CI run the whole byte-price grid and the long fuzz run on every pull request;
  • the second batch covers the order of the Oracle read and its charge, free refusal of volatile reads, ModExp's pricing order (on the revm fork), where the L1 block contract's reads are reported, packing budgets for Mega System Transactions, and the EIP-7702 preflight for every authorization list;
  • the third batch covers give-backs into the reservoir only with the legacy share (on the revm fork), history gas for deposits and system-originated transactions, the per-block deployment of the system contracts with a once-per-block resolution of the system address, and what a call refused at its target's beneficiary delegate pays.

The follow-ups from each batch's two reviews are in this branch.

The branch also makes CI gate on Mega EEST, the conformance suite both Satin implementations share, takes main's faster mutation CI (#419), and deletes the tests the suite now duplicates.

Behaviour changes (Satin only)

Earlier specs run on the released legacy engine and are not touched.

First batch

Change Specification rules
SLOTNUM pushes zero, whatever slot number the block environment carries; the read stays a volatile read, marked and refusable as before. The value no longer depends on a field the node supplies, so a stateless validator needs no slot number. SATIN-BASE-005, SATIN-WIT-010
A value-bearing sendHint is admitted, forwarded and counted like any other: only the value condition is dropped from the admission gate. A call with no gas is still dropped; a value call's gas includes its stipend, and a transaction's own call is judged on its first frame's whole gas. SATIN-ORCL-006, SATIN-ICPT-003
A deposit and a Mega System Transaction ask the oracle service nothing and record no answer, as a system call already did: their Oracle reads push the slot's own value, and are loaded, priced and marked as before. The block in which Satin activates holds only deposits, so it asks the service nothing; no activation-block flag is added to the EVM. SATIN-ORCL-005, SATIN-BASE-008
KeylessDeploy recognizes a deployment only once its arguments decode as (bytes, uint256); a call whose arguments do not decode runs the contract's bytecode and is charged no overhead. The arguments are decoded once and passed along. SATIN-ICPT-006, SATIN-KEY-005
The block executor works out whether a block admits only deposits and whether Satin activates in it from its own schedule, the block's timestamp and the parent block's timestamp. API change: MegaBlockExecutionCtx::new takes the parent timestamp as a required Option<u64>; the two caller-set flags and their setters are gone, and Default is removed. mega-evme and the state-test runner pass the real parent timestamp. SATIN-ACT-010, SATIN-BASE-006

Second batch

Change Specification rules
The Oracle's SLOAD charges nothing before the read: it loads the slot, asks the service where it is asked, and marks the read at the compute before the opcode, then charges the 2,100 as one charge, so gas detention judges its crossing on the whole of it. A read that then runs out of gas or crosses keeps its mark. Any other SLOAD keeps its two charges in the same order as before. SATIN-DET-003, SATIN-ORCL-004, SATIN-WIT-012, SATIN-DET-018
With volatile-data access switched off, a refused read costs nothing: the frame reverts with VolatileDataAccessDisabled on the gas it held when the opcode was reached, also below the opcode's static gas or what its body would charge. Opcodes volatile whatever their operands are refused before their operands are checked; an account, call, SELFDESTRUCT or Oracle read keeps the all-operands check and is then refused before its body. A call target's one-hop delegate is resolved for the check as a required read: its database errors are surfaced and nothing is warmed. To refuse below the static gas, the wrapped opcodes charge their static gas themselves (the instruction table carries zero for them). SATIN-MAC-003, SATIN-MAC-004, SATIN-MAC-007, SATIN-VAL-010
ModExp charges its price before EIP-7823's input-size bound, as go-ethereum does: the 500 minimum, then the formula price with each length saturated to 64 bits, then the bound. An over-bound input therefore has its formula price, for the run and for gas detention's quote alike, and a call that detention would stop is stopped instead of burning its forward. The change is in the revm fork's ModExp (the earlier variants are unchanged), and the fork pin moves to it. SATIN-PCMP-007, SATIN-DET-023, SATIN-DET-024
The block executor no longer reads the L1 block contract before the block's first transaction. The account and the slots the block's fee computations and footprint reads reach are reported once each per block, as read-only entries of the first committed transaction that read them, never replacing that transaction's own entries, whichever executor executed the outcome and in whatever order the builder executed its candidates. A fee read's failure follows the transaction's fatal/non-fatal routing; a footprint read's failure stays an internal error. A block that reads none of the contract no longer fails on a database that cannot serve it. SATIN-WIT-003, SATIN-WIT-011, SATIN-PBLK-003, SATIN-BASE-010
A Mega System Transaction is held to the block's three packing budgets and to building policy like any other non-deposit transaction; only deposits stay exempt. SATIN-BLK-003, SATIN-BLK-006, SATIN-BLK-007, SATIN-BLK-011, SATIN-BLK-013
Every EIP-7702 authorization list is simulated before the first frame wherever a KV-update or state-growth limit holds the transaction (always, under Satin's own limits), whatever its length, so the witness holds every authority that passes the chain-id, nonce and signature checks even when the list's application runs out of gas part-way. The limit decision is unchanged. Under a configuration with neither limit, the list is not simulated, so that configuration loads exactly what Ethereum loads. SATIN-AUTH-001, SATIN-AUTH-005, SATIN-WIT-004

Third batch

Change Specification rules
Every give-back — a state or history refill, a rollback's credit, a reservoir a child returns — goes into the reservoir only; regular gas never rises in a frame except by a child's unused regular gas. Fresh state takes a legacy share from regular gas before the reservoir pays: 10,000 for a new slot, 25,000 for a value call's new account or a keyless signer's, 16,000 for a SELFDESTRUCT's new beneficiary, 20,000 for a CREATE's or a keyless creation's account. Gas detention keeps excluding what regular gas paid for state and history, also after it is given back. KeylessDeploy's gasUsed is the net spend across both pools. A first frame's halt returns only the reservoir-paid part of the charges made before it. The change is in the revm fork, behind a configuration switch whose default keeps upstream EIP-8037 behaviour; only Satin's configuration turns it on (the neutral configuration keeps it off), and the fork pin moves to it. SATIN-HIST-012, SATIN-POOL-008, SATIN-POOL-012, SATIN-POOL-014, SATIN-POOL-015, SATIN-POOL-024, SATIN-STATE-012, SATIN-SD-005, SATIN-DET-009, SATIN-KEY-005, SATIN-KEY-015, SATIN-TAKE-002–011
Deposits and system-originated transactions pay history gas as any transaction does (body, calldata, logs, records, deposited code); only system calls stay exempt. A deposit's intrinsic check includes its body's history; a failed deposit reports its whole gas limit as regular gas, no history gas, and its body and calldata as history bytes. A deposit creation whose mint cannot fund its value makes no start record. SATIN-HIST-016, SATIN-HIST-022, SATIN-MST-008, SATIN-MST-010, SATIN-DEP-001, SATIN-DEP-005, SATIN-TAKE-012
Every block deploys the Oracle, the High-Precision Timestamp, KeylessDeploy, MegaAccessControl and MegaLimitControl (installed when missing, code replaced keeping storage when it differs, a read-only entry when right), then the SequencerRegistry (seeded from the chain configuration's bootstrap values, migrated in place from 1.0.0, a block holding other code there is invalid; an existing account's storage is kept), each step committed on its own; the activation block checks only the EIP-7997 factory; Satin may be active from genesis. The live system address is resolved once per block, after the pre-block steps, as a read-only entry committed last; no transaction loads or warms the registry; an unusable registry makes the block invalid. An EVM built without an address reads it once at construction, outside every transaction, with no warming and no charge, so an estimate equals the in-block gas. API change: the bootstrap values are part of the schedule (MegaHardforks::sequencer_registry_bootstrap) and a schedule that activates Satin without them, or with a zero one, is refused by validate_schedule; MegaContext::new_with_system_address builds a context that reads nothing for the address. SATIN-SYSC-003, SATIN-REG-002, SATIN-REG-004, SATIN-REG-008, SATIN-REG-009, SATIN-ACT-004, SATIN-ACT-005, SATIN-ACT-012, SATIN-PBLK-003, SATIN-WIT-008
With volatile-data access switched off, a call whose target operand is not the beneficiary makes its normal steps, and is refused at its one-hop delegate's load when that delegate is the beneficiary: the gas held at the opcode is restored, then the call pays its target's warm access, this opcode's memory expansion and, for a cold target, the cold surcharge last; it reverts with VolatileDataAccessDisabled(10), or is stopped by gas detention when the surcharge crosses. The value transfer and the refused delegate's access are not paid. Every direct refusal stays free. The up-front delegate lookup is gone. SATIN-MAC-003, SATIN-MAC-004, SATIN-MAC-007, SATIN-DET-018, SATIN-OUT-008, SATIN-STOP-020, SATIN-PCMP-008, SATIN-WIT-012
Results the engine builds itself (interceptor answers, engine stops, synthetic frame results) carry the configured give-back mode before any inspector sees them. API change: untouched_call_gas, untouched_create_gas, synthetic_frame_result and synthetic_call_result take the configuration. —

Tests and CI

  • The test database (MemoryDatabase) applies EIP-161 on commit: a touched empty account is removed, as revm's State does; the EIP-7702 authority test now pins the committed answer exactly.
  • The state-growth fuzz property decides an applied authority by existence (an account the state holds empty exists) and every other site by emptiness, as the specification does; the engine already did. A regression test pins the case the long fuzz run found, and the default fuzz run must now reach empty-but-present accounts.
  • Three tests that held only at the constant byte prices are made price-independent (a KeylessDeploy gas bound, an intrinsic-history row, two reservoir scenarios sized from the schedule).
  • price-grid.yml runs the whole grid on every pull request, and fuzz.yml runs the long fuzz (release and debug) and the price-monotonicity check on every pull request. A schedule trigger fires only on the default branch and workflow_dispatch needs the workflow on the default branch, so neither ran on this line before.
  • A registered execution-spec deviation, slotnum-pushes-zero, lists the twelve Amsterdam eip7843_slotnum entries SLOTNUM pushing zero changes, with the state roots Satin produces.
  • The witness tests now also cover outcomes committed by another executor and candidates committed out of execution order, and the neutral Ethereum differential has a regression for an authorization list that runs out of gas part-way.
  • A test of the released Rex6 executor pins that a Mega System Transaction was already held to the block budgets there.

The Mega EEST gate

  • scripts/mega_eest.sh runs every gating case of the pinned Mega EEST commit (scripts/mega_eest.env) on this tree, plain and instrumented. The suite's revm adapter is built against this checkout, with this tree's [patch] blocks and lock, so a pull request that moves the revm fork is tested with its own fork. The script runs only the binaries this build produced.
  • Exit codes: 0 pass; 1 cases failed; 2 no verdict (the suite could not be fetched or built, a mode list was empty, reports were incomplete, or the deliberately wrong expectation did not fail); 3 refused. A run is refused when the pin is not on Mega EEST's default branch, or when a pin move removes or changes cases without declaring them in scripts/mega_eest.env, or changes the repository without declaring the move. The deliberately wrong expectation decides only when every gating case passes.
  • .github/workflows/mega-eest.yml runs the script on every pull request and push to satin, and Mega EEST gate requires a full run on a default-branch pin. It becomes a required check once an administrator adds it to the branch rule.
  • The coverage report merges the suite's run, built with coverage instrumentation, and requires its profiles; cargo-llvm-cov is pinned.
  • The pull-request mutation gate runs every mutant the tests missed against the suite, one at a time. A mutant counts as caught only when its log carries the suite's failing verdict; a build or fetch failure is unscorable, never a kill.
  • main's mutation CI (ci(mutation): let the nightly full run finish (incremental builds, a time budget, four shards) #419) is ported: incremental builds, a time budget with a status line, and the nightly full run in four shards. The follow-up runs (the timeout re-check and the Mega EEST pass) are never sharded again, and a cut-off shard record is named and fails the run. This branch's own line suppressions are re-anchored; main's are not copied.

Tests the conformance suite duplicates

  • The other Satin implementation's team mapped this crate's tests to Mega EEST cases and listed 296 as duplicates. 150 of them are deleted here and 7 are reduced to focused tests of the implementation contract they also held (the keyless refusal and revert decoders, the deployment's returned code hash, a caught keyless stop's raw outcome), each batch in its own commit.
  • A deletion stands only if every input arm the test ran (a gas limit below or above the execution cap, a crowded SALT bucket on the same path, the target, operation, frame ending, account state and transaction kind) and every value it asserted is pinned by a gating case, as the conformance adapter exposes it.
  • Each batch was also gated on a proof: no line, branch or region of crates/mega-evm/src loses coverage against the remaining tests plus the suite's run, and every mutant the deleted tests killed is still killed by a remaining test or by the suite on the mutated tree.
  • The other 139 stay: about two thirds assert what no case can observe (inspector views, tool-set limits, internal APIs), and the rest wait for cases the suite's maintainers are adding. A transaction's returned state must name every account and slot it loaded, read-only entries included, and an untouched entry must carry its pre-state value; the conformance adapter does not observe that yet, so the tests that check it stay until the suite gates on it.
  • The suite pin moves to 990447bc (1,196 cases, quarantine empty; three changed cases declared): the completed fill wave, its ninth batch and a follow-up that sends Oracle hints from a nonzero memory offset and ordinary transactions from an absent sender, with a consumer that also runs every case requiring gas pools uninspected, so the engine's default execution loop is checked too. The gate now checks the suite's deliberately wrong controls in every mode, matched by their indexed file, in both of their forms (a recorded failing path, or a recorded error message), and rejects a report whose own mode field disagrees with the run.

Outcomes

An outcome differential against #409's head over the pinned execution-spec fixtures (main v5.4.0, glamsterdam devnet v8.1.0; equivalence mode, Satin mode and tightened limits; 19,465 Osaka and 15,754 Amsterdam transactions) differs only where intended:

  • the twelve Amsterdam SLOTNUM entries, in equivalence and Satin mode;
  • four modexpRandomInput transactions per run, a direct call to ModExp with an over-bound input and less gas than its formula price, whose halt reason changes from a precompile error to out-of-gas (go-ethereum's answer); gas, state and logs are equal;
  • in Satin mode and with tightened limits, EIP-7702 transactions whose list runs out of gas part-way now hold, as untouched read-only entries, the authorities the simulation loaded; gas, results, logs and committed state are equal.

For the third batch, against the second batch's head over the same fixtures:

  • equivalence mode: every transaction's state no longer holds the SequencerRegistry account (no transaction reads it); nothing else differs, and the give-back switch leaves equivalence mode equal;
  • Satin mode and tightened limits: the same registry entry, and the split between regular gas and the reservoir moves where state is created or given back. Most rows differ only in the reservoir left at the end. Fixtures sized for Ethereum's prices now run out of gas where the legacy share is drawn first (for example sstore_combinations and test_create_deposit_oog). A loop that watches GAS stops earlier, because give-backs no longer refill regular gas.

The execution-spec gate passes with the counts pinned. The Mega EEST suite at 990447bc passes in full on this branch (1,196 cases, plain and instrumented, gas-pool cases also uninspected); its quarantine is empty.

Verification (local)

At this branch's head:

  • formatting, cargo sort, clippy with -D warnings, all-target and no_std checks;
  • the debug suite in its insta form, forge test, the docs lint;
  • the release suite with -D warnings, MSRV 1.94.0;
  • the whole byte-price grid (73 points), the execution-spec gate, the witness replay gate;
  • the long fuzz run (release and debug) and the price-monotonicity check;
  • the pull-request mutation gate (100% of viable mutants killed on the third batch's diff, two owner-approved equivalent suppressions) and the mutation-suppression hygiene check.

Review

Each batch had two independent reviews; both approve, with no open high-impact finding.

  • First batch follow-ups:

    • tests for an unfunded value-bearing sendHint and for the non-canonical argument encodings KeylessDeploy recognizes;
    • the value-hint boundary at the first frame;
    • the executor refusing an absent parent timestamp where it changes the answer;
    • the grid as four parallel shards with a documentation-only skip;
    • a decision-table test for KeylessDeploy's dispatch;
    • documentation corrections.
  • Second batch follow-ups:

    • the L1 block contract's reads are settled where an outcome is committed (an outcome executed by one executor and committed by another left the witness without the contract);
    • the neutral configuration's read set;
    • tests for four mutation survivors;
    • stale statements of the superseded rules in the documentation and review guidance.
  • Third batch follow-ups:

    • results the engine builds carry the configured give-back mode;
    • seeding the registry over an existing account keeps its storage, one rule with every other system contract's deployment and with the migration;
    • tests for eight mutation survivors;
    • a pinning test for a Mega System Transaction short of its body's history;
    • stale statements of the replaced rules in the documentation and the review guide.
  • The Mega EEST gate had two independent reviews over four rounds; both approve. Their findings are fixed in this branch: a failure before the suite's verdict credited as a mutation kill, a stale adapter binary, empty mode lists, unchecked pin provenance and case changes, re-sharded follow-up runs, and cut-off shard records.

The orders the first batch's reviews found unstated were added to the specification in RealiCZ/mega-evm-satin-spec#3; the Satin implementation on evm2 behaves the same way.

Not in this PR

The remaining alignment item follows in a later batch: the removal of Oracle read records from the outcome.

…authority growth test pins the node's answer

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

api:breaking Crate interface change — downstream users must update comp:core Changes to the `mega-evm` core crate comp:doc Changes in the documentation comp:mega-evme Changes to the `mega-evme` tool comp:misc Changes to the miscellaneous part of this repo spec:unstable Changes to the unstable spec (currently REX5)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant