Design Principles

These boundaries apply to everything we ship.

Service boundaries

• Isolated lab, not a node (BYOS) — We never attach to mainnet, an L2, or an archive RPC. The caller brings — or we construct in this request — the accounts, code, and storage the run needs. That is what “stateless” meant: not a full node, not “the lab world must be empty.”
• Demand-built prestate is in scope — Prefund, install code, seed storage, several txs in one run_block. “Pre-deploy this contract, then EXTCODESIZE it” is one call. Default after the call: discard that world (cheap, parallelizable).
• Call isolation is the default — Each tool call is a fresh lab from that payload. An MCP transport session (stdio process, HTTP mcp-session-id) is not an EVM. Continuation across prompts (“use the contract we just deployed”) is optional later (caller-held snapshot or a short-lived gateway handle) — not shipped, not implied.
• Raw bytecode, base-layer only — No Solidity compilation in the service. ERC/application-layer concerns are out of scope.
• Observability first — Rich execution traces (stack, memory, gas, opcodes) are a primary deliverable.
• Intent-driven MCP tools — Tools match use cases (run bytecode, run transaction, run block, generate BAL, …), not raw library APIs one-to-one.
• Exploration twins — Every live website exploration has an MCP-docs EIP page mapping the same problem set; engine modules ship when a verb can run the change. Canonical metadata lives in website canonical.ts.
• Hard wall — No sequential multi-block historical backtesting (archive-node / revm territory). A lab block of 1–8 constructed txs is not that.

Engine design

• Query shapes, not library APIs — generic verbs (simulate, transaction, block, generate, probe); structured results.
• Fork = capability set — (baseHardfork, eips[]) à la carte; named forks are catalog capabilities (summary, advertised EIPs, shapes), not id-only shortcuts.
• Provenance on every result — engine version, fork config, advertised or explicit EIP maturity metadata.

End-user summary: Capabilities, Guarantees.

Changelog

Design Principles Changelog

1. v0.72026-09-16Named forks are catalog capabilities alongside EIP modules; generic hardfork runs stay on the same verbs.
2. v0.52026-09-10block shape (run_block) alongside simulate / transaction / generate / probe.
3. v0.42026-09-08transaction shape alongside simulate / generate / probe.
4. v0.32026-07-20Consolidated from overview and execution-engine under internals/.