Deterministic future-fork EVM simulation core for the Feel Your Protocol MCP server.
Pure TypeScript library wrapping EthereumJS v10 — no HTTP, no MCP transport, no payments. The mcp-gateway (Step 3+) exposes engine calls as MCP tools for agents.
Agent → MCP gateway (tools + transport) → execution engine (this repo) → EthereumJS
| Piece | Role |
|---|---|
| This repo | Stateless simulation core — bytecode, traces, registry, provenance |
mcp-gateway |
MCP tools + stdio/HTTP transport (planned) |
mcp-docs |
Public docs — use + internals |
Website explorations are the browser twin; this engine is the headless lab equipment.
| Shape | Engine | Future MCP tool | Status |
|---|---|---|---|
| simulate | simulateBytecode() |
simulate_evm_bytecode |
Shipped |
| compare | compareVariants() |
TBD | Shipped |
| probe | describeCapabilities() |
describe_capabilities |
Shipped |
| generate | generateBal() |
generate_eip7928_bal |
Planned (Step 6) |
An endpoint is the agent-facing MCP tool on a transport (stdio / https://mcp.feelyourprotocol.org/mcp) — not a function in this repo. See lab/endpoints/README.md.
Hands-on exploration lives in lab/ — shapes, I/O contracts, runnable examples, and notes on what to notice.
npm install
npm run lab # overview
npm run lab -- run simulate/01-push1-stop
npm run lab -- run compare/01-two-bytecodes
npm run lab -- run probe/01-capabilities
npm run lab -- io simulate # input/output fields
npm run lab -- endpoints # engine → tool → URL ladderStart here: lab/START.md
npm run test:ci # vitest regression suite
npm run typecheck
npm run lf:ci # eslint + prettier
npm run build # emit dist/CI: .github/workflows/ci.yml
- Raw bytecode only (no Solidity compilation)
- No archive node / no mainnet sync
- No sequential multi-block historical backtesting
- Base protocol layer only
MIT