English | 简体中文
A policy interpreter, bytecode compiler, and cross-client test harness for EIP-7906 transaction assertions and EIP-8141 frame transactions.
The repository models this consistency check:
reference(policy, canonical_diff)
== test_evm(compile(policy), canonical_diff)
== participating_clients(frame_transaction)
This is a research prototype. It is not production security software and does not claim mainnet compatibility.
The repository currently includes:
- a versioned policy format and canonical transaction diff;
- a reference evaluator with
pass,fail, andindeterminateresults; - an EIP-7906 bytecode compiler for a pinned ethrex profile;
- a small EVM used to test compiler output;
POST_TXframe-structure checks;- snapshot adapters, a differential runner, and case minimization;
- JSON Schemas, CLI examples, and tests.
It does not yet include a native execution-specs or ethrex adapter. The checked-in clients are fixtures, and no real client has executed the generated bytecode.
Node.js 22 or newer is required. There are no third-party runtime dependencies.
npm test
npm run example
npm run compile:example
npm run frames:example
npm run differential:exampleDirect CLI usage:
node ./src/cli.mjs evaluate \
--policy ./examples/shield-policy.json \
--diff ./examples/shield-diff.json
node ./src/cli.mjs compile \
--policy ./examples/compiled-policy.json
node ./src/cli.mjs validate-frames \
--transaction ./examples/frames.json \
--required-target 0x5555555555555555555555555555555555555555
node ./src/cli.mjs differential \
--policy ./examples/differential-policy.json \
--vector ./test/fixtures/differential-vector.json \
--manifest ./examples/clients.json| Exit code | Meaning |
|---|---|
0 |
Completed or passed |
1 |
Invalid command or input |
2 |
Failed, unsupported compilation, or client divergence |
3 |
Incomplete evidence or client-runner failure |
| Policy | Reference evaluator | Compiler | Notes |
|---|---|---|---|
accountShield |
Yes | Yes | Checks net state only |
balanceDelta with raw basis |
Yes | Yes | Bounded native-balance delta |
balanceDelta with excludingGasPrecharge basis |
Yes | No | Compiler rejects it |
storageTransition |
Yes | Yes | Exact slot before/after values |
codeTransition |
Yes | Yes | Exact code-hash transition |
deployment |
Yes | Yes | Empty-code-hash transition; no creation provenance |
eventPattern |
Yes | Yes | Exact emitter-local occurrence, topics, and data |
Compiled default-deny checks cover the enumerable balance, storage, and event subsets. Policies that require global nonce-only or arbitrary code-change enumeration are rejected rather than weakened.
The compiler is pinned to:
ethrex-eip-7906@1b6c6f15aad78b2ed95581883f5ab1b0f3ba93e9
Opcode bytes in that profile come from an ethrex feature branch. They are provisional and must not be treated as finalized mainnet assignments.
The compiler reports gas as symbolic terms because the EIP still leaves values such as TXTRACE_GAS_COST unsettled. No real-client gas benchmark is included yet.
- Quantities use strings to avoid JavaScript number precision loss.
- Every effect domain has an explicit completeness flag.
- Missing evidence is not normalized to an empty change set.
- A
passapplies only to the supplied policy and evidence model. - Client differences are reported as
unresolved-divergence, not automatically as client bugs. - Command-mode manifests execute local programs and must be treated as trusted input.
src/normalize.mjs policy and canonical-diff validation
src/evaluate.mjs reference evaluator
src/compiler.mjs EVM bytecode compiler
src/bytecode-vm.mjs compiler test VM
src/adapters.mjs snapshot adapters
src/differential.mjs client runner and comparison
src/minimize.mjs case minimization
src/frames.mjs POST_TX structure checks
schemas/ JSON Schemas
examples/ CLI inputs
test/ automated tests
Additional notes: