The REVM engine can run without the Chasm console or fullscreen interface. Any frontend that can launch a process and exchange newline-delimited JSON can control the same live debugger session. This includes editor extensions, browser backends, terminal interfaces, and clients written in languages other than Python.
The transport is JSON-RPC 2.0 over standard input and standard output. Each input line is one request and each output line is its response. The server writes protocol data only to standard output. Process diagnostics go to standard error.
Rust 1.91 or newer is required for the pinned REVM version. This repository ships a
complete request stream that pauses before SSTORE, changes its value operand from 1
to 9, resumes, and reads the committed storage from the finish event:
$ uv run chasm-engine < examples/headless-session.jsonl
{"id":1,"jsonrpc":"2.0","result":{"methods":["hello","open","start","transact","wait_event","snapshot","set_breakpoints","set_stack","write_memory","set_gas","set_pc","step","read_storage","write_storage","state","evaluate","evaluate_call","execute_opcode","set_prank","respond_host","resume","close","shutdown"],"protocol":"chasm-debugger/1","transport":"jsonl-stdio"}}
{"id":2,"jsonrpc":"2.0","result":{"started":true}}
{"id":3,"jsonrpc":"2.0","result":{"snapshot":{"address":"0x1000000000000000000000000000000000000001","calldata":"0x","caller":"0x2000000000000000000000000000000000000002","code_address":"0x1000000000000000000000000000000000000001","depth":0,"frames":[{"address":"0x1000000000000000000000000000000000000001","calldata":"0x","caller":"0x2000000000000000000000000000000000000002","code":"0x600160005500","code_address":"0x1000000000000000000000000000000000000001","depth":0,"gas_limit":79000,"gas_remaining":78994,"is_static":false,"kind":"call","opcode":85,"pc":4,"value":"0x0"}],"gas_limit":79000,"gas_refund":0,"gas_remaining":78994,"gas_used":6,"is_static":false,"memory":"0x","memory_size":0,"mnemonic":"SSTORE","opcode":85,"origin":"0x2000000000000000000000000000000000000002","pc":4,"reason":"breakpoint","stack":["0x0","0x1"],"step":3,"value":"0x0"},"type":"paused"}}
{"id":4,"jsonrpc":"2.0","result":"0x9"}
{"id":5,"jsonrpc":"2.0","result":null}
{"id":6,"jsonrpc":"2.0","result":{"created_address":null,"gas_used":43106,"logs":[],"output":"0x","storage":[{"address":"0x1000000000000000000000000000000000000001","key":"0x0","value":"0x9"}],"success":true,"type":"finished"}}
{"id":7,"jsonrpc":"2.0","result":null}An installed package exposes the same process as chasm-engine. A frontend launches that
command and keeps its standard input and standard output pipes open. A Rust application
can instead depend on chasm-revm-headless and call serve with any buffered reader and
writer.
Call hello first and require chasm-debugger/1. A client should stop if it receives a
protocol version it does not support.
Every request has a string or numeric id, the JSON-RPC version, a method, and an object
of named parameters:
{"jsonrpc":"2.0","id":1,"method":"hello","params":{}}The process owns one session at a time. start creates a compatible one-transaction
session. open creates a persistent chain and transact submits CALL or CREATE
transactions against its committed state. wait_event waits for the next pause or
terminal event, and close discards the chain. shutdown closes it and exits the process
after sending its response.
| Method | Parameters | Result |
|---|---|---|
hello |
{} |
Protocol version, transport, and method names |
open |
Initial accounts and breakpoints |
{"opened":true} |
start |
Session configuration below | {"started":true} |
transact |
caller, optional to, data, value, gas_limit, and commit |
{"started":true} |
wait_event |
{"timeout_ms":5000} |
A paused, finished, or failed event |
snapshot |
{} |
The current paused frame |
set_breakpoints |
{"breakpoints":[{"address":"0x...","pc":4}]} |
Number installed |
set_stack |
{"index":1,"value":"0x9"} |
Written word |
write_memory |
{"offset":64,"data":"0x1234"} |
Bytes written |
set_gas |
{"gas":50000} |
New remaining gas |
set_pc |
{"pc":16} |
New program counter, which must be a JUMPDEST |
step |
{"count":1} |
null; execution pauses before the next opcode |
read_storage |
{"key":"0x0"} |
Storage word |
write_storage |
{"key":"0x0","value":"0x9"} |
Written word |
state |
A tagged state operation such as {"op":"read_balance","address":"0x..."} |
The requested value |
evaluate |
{"bytecode":"0x...","keep":false} |
Returned bytes |
evaluate_call |
Bytecode, calldata, caller, value, gas limit, and keep |
Success, output, and gas used |
execute_opcode |
opcode, arguments, and outputs |
Output word and gas used |
set_prank |
New sender and optional caller, origin, persistence, and delegate flag | null |
respond_host |
{"output":"0x...","revert":false} |
null |
resume |
{} |
null |
close |
{} |
null |
shutdown |
{} |
null, followed by process exit |
Omitting to from transact executes a CREATE transaction and reports the new address as
created_address in the finish event. Supplying to executes a CALL. Persistent chains
retain account and storage changes between transactions unless commit is false.
state reads and writes balances, code, nonces, persistent or transient storage, block
fields, access warmth, and accumulated logs. evaluate_call executes injected bytecode
with explicit frame inputs; keep: false rolls its journal back. execute_opcode runs one
opcode against the paused frame without consuming its stack or gas, while retaining state
and memory changes. set_prank configures caller rewriting in the core; omit new_sender
to clear it.
wait_event is a bounded long poll, not an unsolicited server message. Its default
timeout is 5 seconds. A graphical frontend can use a shorter timeout when it needs to
refresh or cancel its own task promptly.
A call to Foundry's VM or console address may produce a host_call event with address,
caller, data, and gas_limit. The client must handle the calldata and send exactly one
respond_host request. output becomes the call's return data. Setting revert to true
returns that data with the EVM REVERT status. This keeps cheatcode policy outside the
engine and lets headless clients add host functions without changing REVM execution.
entry must match one account in accounts. The call uses a default funded caller and a
gas limit of 100000 unless those values are supplied. Account balance and storage are
optional:
{
"entry": "0x1000000000000000000000000000000000000001",
"caller": "0x2000000000000000000000000000000000000002",
"gas_limit": 100000,
"accounts": [
{
"address": "0x1000000000000000000000000000000000000001",
"code": "0x600160005500",
"balance": "0x0",
"storage": [{"key": "0x1", "value": "0x2"}]
}
],
"breakpoints": [
{"address": "0x1000000000000000000000000000000000000001", "pc": 4}
]
}Addresses are 20-byte hex strings. Input EVM words may be decimal or 0x-prefixed hex.
Output words are hex. Byte strings are hex with an even number of digits.
A pause event contains a snapshot of the frame that is still executing:
{
"type": "paused",
"snapshot": {
"reason": "breakpoint",
"step": 3,
"address": "0x1000000000000000000000000000000000000001",
"code_address": "0x1000000000000000000000000000000000000001",
"caller": "0x2000000000000000000000000000000000000002",
"origin": "0x2000000000000000000000000000000000000002",
"value": "0x0",
"calldata": "0x",
"is_static": false,
"depth": 0,
"pc": 4,
"opcode": 85,
"mnemonic": "SSTORE",
"gas_limit": 79000,
"gas_remaining": 78994,
"gas_used": 6,
"gas_refund": 0,
"stack": ["0x0", "0x1"],
"memory_size": 0,
"memory": "0x",
"frames": [
{
"depth": 0,
"kind": "call",
"address": "0x1000000000000000000000000000000000000001",
"code_address": "0x1000000000000000000000000000000000000001",
"caller": "0x2000000000000000000000000000000000000002",
"value": "0x0",
"calldata": "0x",
"is_static": false,
"pc": 4,
"opcode": 85,
"gas_limit": 79000,
"gas_remaining": 78994,
"code": "0x600160005500"
}
]
}
}reason is breakpoint, step, revert, or out_of_gas. A finish event contains
success, gas_used, output, logs, and the changed storage slots. The frames array runs from the
outermost frame to the paused frame and retains each caller's last program counter. A
failed event contains a message.
Errors use the JSON-RPC error shape. The server stays alive after parse, request, method, parameter, engine, and session-state errors:
| Code | Meaning |
|---|---|
-32700 |
Invalid JSON |
-32600 |
Invalid JSON-RPC request |
-32601 |
Unknown method |
-32602 |
Invalid parameters |
-32000 |
REVM engine error or timeout |
-32001 |
No active session, or a session is already active |
The console, fullscreen TUI, Web3 provider, and JSON-RPC server all use this same Rust core. Frontends choose the direct Python bridge or the process boundary; neither owns EVM execution policy.