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. The hosted HTTP transport keeps no session: every POST stands alone, and a gateway restart does not drop an install. 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_artifact, inspect_artifact, …), 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 (eip-canonical-data.mdc). Twins stay after the EIP is on mainnet; fork role may rotate around them. sunset is for no honest lab observation, not for activation.
• 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 — internal catalog ids (simulate, transaction, block, generate, probe); live probe maps them to MCP tools via queryShapes. The engine returns structured results.
• Fork = capability set — (baseHardfork, eips[]) à la carte; named forks are catalog capabilities (summary, advertised EIPs, tools), not id-only shortcuts.
• Provenance on every result — engine version, fork config, advertised EIP status, spec URL, spec date, named test release, stability rollup, human caveat. Named eips[] add a compact Spec: clause.

End-user summary: Capabilities, Guarantees.

Changelog

Design Principles Changelog

1. v0.102026-10-06Hosted HTTP transport keeps no session id. A restart does not drop an install.
2. v0.92026-09-18Named eips[] caveats include a compact Spec: snapshot.
3. v0.82026-09-17Twins stay after mainnet activation; sunset is for no honest lab observation.
4. v0.72026-09-16Named forks are catalog capabilities alongside EIP modules; generic hardfork runs stay on the same verbs.
5. v0.52026-09-10block shape (run_block) alongside simulate / transaction / generate / probe.
6. v0.42026-09-08transaction shape alongside simulate / generate / probe.
7. v0.32026-07-20Consolidated from overview and execution-engine under internals/.