@terrariumlabs/evm 0.3.0

package/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "terrarium-evm"
+version = "0.3.0"
+edition = "2021"
+description = "revm compiled to WebAssembly as a Terrarium execution backend"
+license = "MIT"
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+# no C dependencies (secp256k1 / c-kzg / blst are replaced by their pure-Rust fallbacks), so it builds for wasm32
+revm = { version = "43", default-features = false, features = ["std", "optional_balance_check", "optional_block_gas_limit", "optional_no_base_fee", "optional_eip3607"] }
+wasm-bindgen = "0.2"
+js-sys = "0.3"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+hex = "0.4"
+# wasm32-unknown-unknown has no OS entropy source: route getrandom (pulled in transitively) through the browser/Node APIs
+getrandom = { version = "0.2", features = ["js"] }
+
+[profile.release]
+opt-level = 3
+lto = true
+codegen-units = 1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Martin (damarnez)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# @terrariumlabs/evm
+
+[revm](https://github.com/bluealloy/revm) 43 compiled to WebAssembly, as the execution engine of Terrarium. About 1.5 MB
+of wasm, no C dependencies (k256 for secp256k1, arkworks for bn254/bls12-381, pure-Rust KZG), built with wasm-bindgen
+`--target web`. `pkg/` is committed so JavaScript users need no Rust toolchain.
+
+## What it does, and only that
+It executes one transaction per call. Everything else stays in JavaScript: accounts, code and storage, checkpoints and
+reverts, blocks and receipts, persistence, fork recording. The engine asks the host for what it reads and returns a
+state diff to apply:
+
+```js
+import init, { run, version } from '@terrariumlabs/evm';
+await init({ module_or_path: wasmBytesOrUrl });
+const result = JSON.parse(run(host, JSON.stringify({ tx, block, cfg })));
+// result: { success, reason, gasUsed, gasRefunded, output, created, logs, state, sloads }
+```
+`host` is a plain object with synchronous methods `account(address)`, `storage(address, slot)`, `blockHash(number)`.
+If the host cannot answer synchronously it throws `{ missing: true }`; `run` throws `"missing"`, the caller loads the
+state and calls again. Reads are recorded, so re-runs are exact. `cfg.traceSloads` returns every SLOAD (address, slot)
+— how Terrarium's `deal` finds a token's balance slot. Field-by-field schema: [docs/api.md](../../docs/api.md).
+
+## Build
+```bash
+rustup target add wasm32-unknown-unknown
+cargo install wasm-bindgen-cli          # 0.2.127 at the time of writing; must match the wasm-bindgen crate version
+npm run build                           # cargo build --release --target wasm32-unknown-unknown && wasm-bindgen --target web --out-dir pkg
+node smoke.mjs                          # deploy PEPE, call balanceOf, trace the balance slot — PASS
+```
+`getrandom` is pinned with its `js` feature: wasm32-unknown-unknown has no OS entropy source.
+
+## Fidelity and speed
+`npm run test:uniswap` (repo root) runs a 14-transaction Uniswap V2 scenario on this engine and on Anvil: every
+transaction hash, receipt, log, call result and revert payload is byte-identical, every block's header hash and roots
+recompute from the RPC output. The scenario takes ≈135 ms here (≈35 ms inside the wasm) versus ≈75 ms on native Anvil.
+`test/unit/wasm.test.mjs` pins the `run` / `host` contract described above. Since terrarium 0.3 this is the only
+execution engine.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@terrariumlabs/evm",
+  "version": "0.3.0",
+  "description": "revm compiled to WebAssembly: the fast execution backend for Terrarium",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/damarnez/terrarium.git",
+    "directory": "packages/terrarium-evm"
+  },
+  "homepage": "https://github.com/damarnez/terrarium#readme",
+  "bugs": "https://github.com/damarnez/terrarium/issues",
+  "keywords": [
+    "ethereum",
+    "evm",
+    "revm",
+    "wasm",
+    "eip-1193",
+    "eip-6963",
+    "wallet",
+    "dapp",
+    "testing",
+    "simulator",
+    "anvil",
+    "rust",
+    "wasm-bindgen"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "pkg/terrarium_evm.js",
+  "exports": {
+    ".": "./pkg/terrarium_evm.js",
+    "./wasm": "./pkg/terrarium_evm_bg.wasm"
+  },
+  "files": [
+    "pkg",
+    "src",
+    "Cargo.toml"
+  ],
+  "scripts": {
+    "build": "cargo build --release --target wasm32-unknown-unknown && wasm-bindgen --target web --out-dir pkg target/wasm32-unknown-unknown/release/terrarium_evm.wasm"
+  }
+}

package/pkg/terrarium_evm.d.ts

@@ -0,0 +1,49 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Execute one transaction. `request` is a JSON string (RunRequest); returns a JSON string (RunResult).
+ * Throws a string starting with `missing` when the host could not provide some state (re-run after fetching), and a
+ * string starting with `invalid:` for a transaction the node would refuse (bad nonce, insufficient funds...).
+ */
+export function run(host: any, request: string): string;
+
+export function version(): string;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly run: (a: any, b: number, c: number) => [number, number, number, number];
+    readonly version: () => [number, number];
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_exn_store: (a: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;

package/pkg/terrarium_evm.js

@@ -0,0 +1,390 @@
+/* @ts-self-types="./terrarium_evm.d.ts" */
+
+/**
+ * Execute one transaction. `request` is a JSON string (RunRequest); returns a JSON string (RunResult).
+ * Throws a string starting with `missing` when the host could not provide some state (re-run after fetching), and a
+ * string starting with `invalid:` for a transaction the node would refuse (bad nonce, insufficient funds...).
+ * @param {any} host
+ * @param {string} request
+ * @returns {string}
+ */
+export function run(host, request) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(request, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.run(host, ptr0, len0);
+        var ptr2 = ret[0];
+        var len2 = ret[1];
+        if (ret[3]) {
+            ptr2 = 0; len2 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+
+/**
+ * @returns {string}
+ */
+export function version() {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        const ret = wasm.version();
+        deferred1_0 = ret[0];
+        deferred1_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+    }
+}
+function __wbg_get_imports() {
+    const import0 = {
+        __proto__: null,
+        __wbg___wbindgen_boolean_get_c9c83ebd41b34df3: function(arg0) {
+            const v = arg0;
+            const ret = typeof(v) === 'boolean' ? v : undefined;
+            return isLikeNone(ret) ? 0xFFFFFF : ret ? 1 : 0;
+        },
+        __wbg___wbindgen_debug_string_a57024b9c6e4a48b: function(arg0, arg1) {
+            const ret = debugString(arg1);
+            const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        },
+        __wbg___wbindgen_is_null_7d13f41e1a2d5140: function(arg0) {
+            const ret = arg0 === null;
+            return ret;
+        },
+        __wbg___wbindgen_is_undefined_6cff064c44e0d823: function(arg0) {
+            const ret = arg0 === undefined;
+            return ret;
+        },
+        __wbg___wbindgen_string_get_d154f1e671052120: function(arg0, arg1) {
+            const obj = arg1;
+            const ret = typeof(obj) === 'string' ? obj : undefined;
+            var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            var len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        },
+        __wbg___wbindgen_throw_bb96b2010945f0bc: function(arg0, arg1) {
+            throw new Error(getStringFromWasm0(arg0, arg1));
+        },
+        __wbg_account_865c9c68e728eee9: function() { return handleError(function (arg0, arg1, arg2) {
+            const ret = arg0.account(getStringFromWasm0(arg1, arg2));
+            return ret;
+        }, arguments); },
+        __wbg_blockHash_7e3aa4fc3b1cfb6b: function() { return handleError(function (arg0, arg1) {
+            const ret = arg0.blockHash(arg1);
+            return ret;
+        }, arguments); },
+        __wbg_get_971a0c45d172643f: function() { return handleError(function (arg0, arg1) {
+            const ret = Reflect.get(arg0, arg1);
+            return ret;
+        }, arguments); },
+        __wbg_storage_51594800c64c7b13: function() { return handleError(function (arg0, arg1, arg2, arg3, arg4) {
+            const ret = arg0.storage(getStringFromWasm0(arg1, arg2), getStringFromWasm0(arg3, arg4));
+            return ret;
+        }, arguments); },
+        __wbindgen_cast_0000000000000001: function(arg0, arg1) {
+            // Cast intrinsic for `Ref(String) -> Externref`.
+            const ret = getStringFromWasm0(arg0, arg1);
+            return ret;
+        },
+        __wbindgen_init_externref_table: function() {
+            const table = wasm.__wbindgen_externrefs;
+            const offset = table.grow(4);
+            table.set(0, undefined);
+            table.set(offset + 0, undefined);
+            table.set(offset + 1, null);
+            table.set(offset + 2, true);
+            table.set(offset + 3, false);
+        },
+    };
+    return {
+        __proto__: null,
+        "./terrarium_evm_bg.js": import0,
+    };
+}
+
+function addToExternrefTable0(obj) {
+    const idx = wasm.__externref_table_alloc();
+    wasm.__wbindgen_externrefs.set(idx, obj);
+    return idx;
+}
+
+function debugString(val) {
+    // primitive types
+    const type = typeof val;
+    if (type == 'number' || type == 'boolean' || val == null) {
+        return  `${val}`;
+    }
+    if (type == 'string') {
+        return `"${val}"`;
+    }
+    if (type == 'symbol') {
+        const description = val.description;
+        if (description == null) {
+            return 'Symbol';
+        } else {
+            return `Symbol(${description})`;
+        }
+    }
+    if (type == 'function') {
+        const name = val.name;
+        if (typeof name == 'string' && name.length > 0) {
+            return `Function(${name})`;
+        } else {
+            return 'Function';
+        }
+    }
+    // objects
+    if (Array.isArray(val)) {
+        const length = val.length;
+        let debug = '[';
+        if (length > 0) {
+            debug += debugString(val[0]);
+        }
+        for(let i = 1; i < length; i++) {
+            debug += ', ' + debugString(val[i]);
+        }
+        debug += ']';
+        return debug;
+    }
+    // Test for built-in
+    const builtInMatches = /\[object ([^\]]+)\]/.exec(toString.call(val));
+    let className;
+    if (builtInMatches && builtInMatches.length > 1) {
+        className = builtInMatches[1];
+    } else {
+        // Failed to match the standard '[object ClassName]'
+        return toString.call(val);
+    }
+    if (className == 'Object') {
+        // we're a user defined class or Object
+        // JSON.stringify avoids problems with cycles, and is generally much
+        // easier than looping through ownProperties of `val`.
+        try {
+            return 'Object(' + JSON.stringify(val) + ')';
+        } catch (_) {
+            return 'Object';
+        }
+    }
+    // errors
+    if (val instanceof Error) {
+        return `${val.name}: ${val.message}\n${val.stack}`;
+    }
+    // TODO we could test for more things here, like `Set`s and `Map`s.
+    return className;
+}
+
+let cachedDataViewMemory0 = null;
+function getDataViewMemory0() {
+    if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {
+        cachedDataViewMemory0 = new DataView(wasm.memory.buffer);
+    }
+    return cachedDataViewMemory0;
+}
+
+function getStringFromWasm0(ptr, len) {
+    return decodeText(ptr >>> 0, len);
+}
+
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+
+function handleError(f, args) {
+    try {
+        return f.apply(this, args);
+    } catch (e) {
+        const idx = addToExternrefTable0(e);
+        wasm.__wbindgen_exn_store(idx);
+    }
+}
+
+function isLikeNone(x) {
+    return x === undefined || x === null;
+}
+
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
+function takeFromExternrefTable0(idx) {
+    const value = wasm.__wbindgen_externrefs.get(idx);
+    wasm.__externref_table_dealloc(idx);
+    return value;
+}
+
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+cachedTextDecoder.decode();
+const MAX_SAFARI_DECODE_BYTES = 2146435072;
+let numBytesDecoded = 0;
+function decodeText(ptr, len) {
+    numBytesDecoded += len;
+    if (numBytesDecoded >= MAX_SAFARI_DECODE_BYTES) {
+        cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+        cachedTextDecoder.decode();
+        numBytesDecoded = len;
+    }
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+
+const cachedTextEncoder = new TextEncoder();
+
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    };
+}
+
+let WASM_VECTOR_LEN = 0;
+
+let wasmModule, wasmInstance, wasm;
+function __wbg_finalize_init(instance, module) {
+    wasmInstance = instance;
+    wasm = instance.exports;
+    wasmModule = module;
+    cachedDataViewMemory0 = null;
+    cachedUint8ArrayMemory0 = null;
+    wasm.__wbindgen_start();
+    return wasm;
+}
+
+async function __wbg_load(module, imports) {
+    if (typeof Response === 'function' && module instanceof Response) {
+        if (!module.ok) {
+            throw new Error(`failed to fetch Wasm: ${module.status} ${module.statusText} fetching '${module.url}'`);
+        }
+
+        if (typeof WebAssembly.instantiateStreaming === 'function') {
+            try {
+                return await WebAssembly.instantiateStreaming(module, imports);
+            } catch (e) {
+                const validResponse = expectedResponseType(module.type);
+
+                if (validResponse && module.headers.get('Content-Type') !== 'application/wasm') {
+                    console.warn("`WebAssembly.instantiateStreaming` failed because your server does not serve Wasm with `application/wasm` MIME type. Falling back to `WebAssembly.instantiate` which is slower. Original error:\n", e);
+
+                } else { throw e; }
+            }
+        }
+
+        const bytes = await module.arrayBuffer();
+        return await WebAssembly.instantiate(bytes, imports);
+    } else {
+        const instance = await WebAssembly.instantiate(module, imports);
+
+        if (instance instanceof WebAssembly.Instance) {
+            return { instance, module };
+        } else {
+            return instance;
+        }
+    }
+
+    function expectedResponseType(type) {
+        switch (type) {
+            case 'basic': case 'cors': case 'default': return true;
+        }
+        return false;
+    }
+}
+
+function initSync(module) {
+    if (wasm !== undefined) return wasm;
+
+
+    if (module !== undefined) {
+        if (Object.getPrototypeOf(module) === Object.prototype) {
+            ({module} = module)
+        } else {
+            console.warn('using deprecated parameters for `initSync()`; pass a single object instead')
+        }
+    }
+
+    const imports = __wbg_get_imports();
+    if (!(module instanceof WebAssembly.Module)) {
+        module = new WebAssembly.Module(module);
+    }
+    const instance = new WebAssembly.Instance(module, imports);
+    return __wbg_finalize_init(instance, module);
+}
+
+async function __wbg_init(module_or_path) {
+    if (wasm !== undefined) return wasm;
+
+
+    if (module_or_path !== undefined) {
+        if (Object.getPrototypeOf(module_or_path) === Object.prototype) {
+            ({module_or_path} = module_or_path)
+        } else {
+            console.warn('using deprecated parameters for the initialization function; pass a single object instead')
+        }
+    }
+
+    if (module_or_path === undefined) {
+        module_or_path = new URL('terrarium_evm_bg.wasm', import.meta.url);
+    }
+    const imports = __wbg_get_imports();
+
+    if (typeof module_or_path === 'string' || (typeof Request === 'function' && module_or_path instanceof Request) || (typeof URL === 'function' && module_or_path instanceof URL)) {
+        module_or_path = fetch(module_or_path);
+    }
+
+    const { instance, module } = await __wbg_load(await module_or_path, imports);
+
+    return __wbg_finalize_init(instance, module);
+}
+
+export { initSync, __wbg_init as default };

package/pkg/terrarium_evm_bg.wasm.d.ts

@@ -0,0 +1,13 @@
+/* tslint:disable */
+/* eslint-disable */
+export const memory: WebAssembly.Memory;
+export const run: (a: any, b: number, c: number) => [number, number, number, number];
+export const version: () => [number, number];
+export const __wbindgen_malloc: (a: number, b: number) => number;
+export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+export const __wbindgen_exn_store: (a: number) => void;
+export const __externref_table_alloc: () => number;
+export const __wbindgen_externrefs: WebAssembly.Table;
+export const __externref_table_dealloc: (a: number) => void;
+export const __wbindgen_free: (a: number, b: number, c: number) => void;
+export const __wbindgen_start: () => void;

package/src/lib.rs

@@ -0,0 +1,215 @@
+//! terrarium-evm: revm behind a tiny host interface, compiled to WebAssembly.
+//!
+//! The JavaScript side owns ALL state (accounts, code, storage, checkpoints, persistence, fork recording). This crate
+//! only executes: it asks the host for whatever it reads, and returns the result plus the state diff to apply.
+//! If the host cannot answer synchronously (fork mode: the slot has to be fetched from a node), it throws an error
+//! marked `missing`; execution aborts, the host fetches, and re-runs. Reads are recorded, so re-runs are exact.
+use std::collections::HashMap;
+use std::str::FromStr;
+
+use revm::context::{BlockEnv, CfgEnv, Context, TxEnv};
+use revm::context_interface::result::{EVMError, ExecutionResult, Output};
+use revm::database_interface::{DBErrorMarker, Database};
+use revm::handler::{MainBuilder, MainContext};
+use revm::inspector::{InspectEvm, Inspector};
+use revm::interpreter::interpreter::EthInterpreter;
+use revm::interpreter::interpreter_types::{InputsTr, Jumps, StackTr};
+#[allow(unused_imports)] use StackTr as _StackTrUsed;
+use revm::interpreter::Interpreter;
+use revm::primitives::hardfork::SpecId;
+use revm::primitives::{Address, Bytes, TxKind, B256, U256};
+use revm::state::{AccountInfo, Bytecode};
+use serde::{Deserialize, Serialize};
+use wasm_bindgen::prelude::*;
+
+// ---------------------------------------------------------------- the host (JavaScript) ------------------------------
+#[wasm_bindgen]
+extern "C" {
+    pub type Host;
+    /// -> null (no account) | { balance, nonce, codeHash, code } as hex strings. Throws { missing: true } to abort.
+    #[wasm_bindgen(method, catch)]
+    fn account(this: &Host, address: &str) -> Result<JsValue, JsValue>;
+    /// -> 32-byte hex
+    #[wasm_bindgen(method, catch)]
+    fn storage(this: &Host, address: &str, slot: &str) -> Result<JsValue, JsValue>;
+    /// -> 32-byte hex
+    #[wasm_bindgen(method, catch, js_name = blockHash)]
+    fn block_hash(this: &Host, number: f64) -> Result<JsValue, JsValue>;
+}
+
+#[derive(Debug)]
+pub enum HostError { Missing, Other(String) }
+impl std::fmt::Display for HostError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { match self { HostError::Missing => write!(f, "missing state"), HostError::Other(s) => write!(f, "{s}") } }
+}
+impl std::error::Error for HostError {}
+impl DBErrorMarker for HostError {}
+
+fn js_err(e: JsValue) -> HostError {
+    let missing = js_sys::Reflect::get(&e, &JsValue::from_str("missing")).ok().and_then(|v| v.as_bool()).unwrap_or(false);
+    if missing { HostError::Missing } else { HostError::Other(format!("{e:?}")) }
+}
+fn js_str(v: &JsValue, key: &str) -> Result<String, HostError> {
+    js_sys::Reflect::get(v, &JsValue::from_str(key)).ok().and_then(|x| x.as_string()).ok_or_else(|| HostError::Other(format!("host returned no `{key}`")))
+}
+fn parse_u256(s: &str) -> Result<U256, HostError> { U256::from_str(s).map_err(|e| HostError::Other(format!("bad u256 {s}: {e}"))) }
+fn parse_b256(s: &str) -> Result<B256, HostError> { B256::from_str(s).map_err(|e| HostError::Other(format!("bad b256 {s}: {e}"))) }
+fn parse_addr(s: &str) -> Result<Address, HostError> { Address::from_str(s).map_err(|e| HostError::Other(format!("bad address {s}: {e}"))) }
+fn parse_bytes(s: &str) -> Result<Bytes, HostError> { Bytes::from_str(s).map_err(|e| HostError::Other(format!("bad bytes: {e}"))) }
+
+/// revm's view of the world: every read goes to the host, cached for the duration of one run.
+struct HostDb<'a> { host: &'a Host, accounts: HashMap<Address, Option<AccountInfo>>, storage: HashMap<(Address, U256), U256> }
+
+impl<'a> Database for HostDb<'a> {
+    type Error = HostError;
+    fn basic(&mut self, address: Address) -> Result<Option<AccountInfo>, HostError> {
+        if let Some(a) = self.accounts.get(&address) { return Ok(a.clone()); }
+        let v = self.host.account(&format!("{address:?}")).map_err(js_err)?;
+        let info = if v.is_null() || v.is_undefined() { None } else {
+            let code = parse_bytes(&js_str(&v, "code")?)?;
+            let code_hash = parse_b256(&js_str(&v, "codeHash")?)?;
+            let mut info = AccountInfo::default();
+            info.balance = parse_u256(&js_str(&v, "balance")?)?; info.nonce = parse_u256(&js_str(&v, "nonce")?)?.to::<u64>(); info.code_hash = code_hash;
+            if !code.is_empty() { info.code = Some(Bytecode::new_raw(code)); }   // code comes with the account: revm never needs code_by_hash
+            Some(info)
+        };
+        self.accounts.insert(address, info.clone());
+        Ok(info)
+    }
+    fn code_by_hash(&mut self, _code_hash: B256) -> Result<Bytecode, HostError> { Ok(Bytecode::default()) }   // never reached: basic() carries the code
+    fn storage(&mut self, address: Address, index: U256) -> Result<U256, HostError> {
+        if let Some(v) = self.storage.get(&(address, index)) { return Ok(*v); }
+        let v = self.host.storage(&format!("{address:?}"), &format!("{index:#066x}")).map_err(js_err)?;
+        let value = parse_u256(&v.as_string().ok_or_else(|| HostError::Other("storage: not a string".into()))?)?;
+        self.storage.insert((address, index), value);
+        Ok(value)
+    }
+    fn block_hash(&mut self, number: u64) -> Result<B256, HostError> {
+        let v = self.host.block_hash(number as f64).map_err(js_err)?;
+        parse_b256(&v.as_string().ok_or_else(|| HostError::Other("blockHash: not a string".into()))?)
+    }
+}
+
+// ---------------------------------------------------------------- SLOAD tracer (for `deal`'s slot discovery) ---------
+#[derive(Default)]
+struct SloadTracer { on: bool, reads: Vec<(Address, U256)> }
+impl<CTX> Inspector<CTX, EthInterpreter> for SloadTracer {
+    fn step(&mut self, interp: &mut Interpreter<EthInterpreter>, _ctx: &mut CTX) {
+        if self.on && interp.bytecode.opcode() == 0x54 {
+            if let Some(slot) = interp.stack.top() { let slot = *slot; self.reads.push((interp.input.target_address(), slot)); }
+        }
+    }
+}
+
+// ---------------------------------------------------------------- request / response ----------------------------------
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RunRequest { tx: TxIn, block: BlockIn, cfg: CfgIn }
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TxIn { from: String, to: Option<String>, value: String, data: String, gas_limit: String, gas_price: String, priority_fee: Option<String>, nonce: Option<String>, tx_type: Option<u8> }
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BlockIn { number: String, timestamp: String, gas_limit: String, base_fee: String, coinbase: Option<String>, prev_randao: Option<String> }
+#[derive(Deserialize, Default)]
+#[serde(rename_all = "camelCase", default)]
+pub struct CfgIn { chain_id: u64, spec: Option<String>, skip_balance: bool, skip_nonce: bool, skip_block_gas_limit: bool, no_base_fee: bool, skip_eip3607: bool, trace_sloads: bool }
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct LogOut { address: String, topics: Vec<String>, data: String }
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountOut { address: String, deleted: bool, balance: String, nonce: String, code_hash: String, code: Option<String>, storage: Vec<(String, String)> }
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RunResult { success: bool, reason: String, gas_used: u64, gas_refunded: u64, output: String, created: Option<String>, logs: Vec<LogOut>, state: Vec<AccountOut>, sloads: Vec<(String, String)> }
+
+fn spec_of(name: Option<&str>) -> SpecId {
+    match name.map(|s| s.to_ascii_lowercase()).as_deref() { Some("prague") => SpecId::PRAGUE, Some("shanghai") => SpecId::SHANGHAI, Some("merge") | Some("paris") => SpecId::MERGE, Some("osaka") => SpecId::OSAKA, _ => SpecId::CANCUN }
+}
+fn u64_of(s: &str) -> Result<u64, HostError> { Ok(parse_u256(s)?.to::<u64>()) }
+fn u128_of(s: &str) -> Result<u128, HostError> { Ok(parse_u256(s)?.to::<u128>()) }
+
+#[wasm_bindgen]
+pub fn version() -> String { format!("terrarium-evm {} / revm 43", env!("CARGO_PKG_VERSION")) }
+
+/// Execute one transaction. `request` is a JSON string (RunRequest); returns a JSON string (RunResult).
+/// Throws a string starting with `missing` when the host could not provide some state (re-run after fetching), and a
+/// string starting with `invalid:` for a transaction the node would refuse (bad nonce, insufficient funds...).
+#[wasm_bindgen]
+pub fn run(host: &Host, request: &str) -> Result<String, JsValue> {
+    let req: RunRequest = serde_json::from_str(request).map_err(|e| JsValue::from_str(&format!("bad request: {e}")))?;
+    run_inner(host, req).map_err(|e| JsValue::from_str(&e))
+}
+
+fn run_inner(host: &Host, req: RunRequest) -> Result<String, String> {
+    let h = |e: HostError| e.to_string();
+    let block = BlockEnv {
+        number: parse_u256(&req.block.number).map_err(h)?,
+        beneficiary: req.block.coinbase.as_deref().map(parse_addr).transpose().map_err(h)?.unwrap_or(Address::ZERO),
+        timestamp: parse_u256(&req.block.timestamp).map_err(h)?,
+        gas_limit: u64_of(&req.block.gas_limit).map_err(h)?,
+        basefee: u64_of(&req.block.base_fee).map_err(h)?,
+        difficulty: U256::ZERO,
+        prevrandao: Some(req.block.prev_randao.as_deref().map(parse_b256).transpose().map_err(h)?.unwrap_or(B256::ZERO)),
+        ..Default::default()
+    };
+    let caller = parse_addr(&req.tx.from).map_err(h)?;
+    let tx = TxEnv {
+        tx_type: req.tx.tx_type.unwrap_or(2),
+        caller,
+        gas_limit: u64_of(&req.tx.gas_limit).map_err(h)?,
+        gas_price: u128_of(&req.tx.gas_price).map_err(h)?,
+        gas_priority_fee: req.tx.priority_fee.as_deref().map(u128_of).transpose().map_err(h)?,
+        kind: match &req.tx.to { Some(to) => TxKind::Call(parse_addr(to).map_err(h)?), None => TxKind::Create },
+        value: parse_u256(&req.tx.value).map_err(h)?,
+        data: parse_bytes(&req.tx.data).map_err(h)?,
+        nonce: req.tx.nonce.as_deref().map(u64_of).transpose().map_err(h)?.unwrap_or(0),
+        chain_id: Some(req.cfg.chain_id),
+        ..Default::default()
+    };
+    let mut cfg = CfgEnv::new_with_spec(spec_of(req.cfg.spec.as_deref()));
+    cfg.chain_id = req.cfg.chain_id;
+    cfg.disable_nonce_check = req.cfg.skip_nonce;
+    cfg.disable_balance_check = req.cfg.skip_balance;
+    cfg.disable_block_gas_limit = req.cfg.skip_block_gas_limit;
+    cfg.disable_base_fee = req.cfg.no_base_fee;
+    cfg.disable_eip3607 = req.cfg.skip_eip3607;   // simulations may originate from a contract address
+    cfg.limit_contract_code_size = Some(usize::MAX);   // allowUnlimitedContractSize, like the JS engine
+    cfg.limit_contract_initcode_size = Some(usize::MAX);
+
+    let db = HostDb { host, accounts: HashMap::new(), storage: HashMap::new() };
+    let ctx = Context::mainnet().with_db(db).with_block(block).with_cfg(cfg);
+    let mut evm = ctx.build_mainnet_with_inspector(SloadTracer { on: req.cfg.trace_sloads, reads: Vec::new() });
+    let res = match evm.inspect_tx(tx) {
+        Ok(r) => r,
+        Err(EVMError::Database(HostError::Missing)) => return Err("missing".into()),
+        Err(EVMError::Database(e)) => return Err(format!("host: {e}")),
+        Err(EVMError::Transaction(e)) => return Err(format!("invalid: {e:?}")),
+        Err(EVMError::Header(e)) => return Err(format!("invalid header: {e:?}")),
+        Err(e) => return Err(format!("evm: {e:?}")),
+    };
+    let sloads = evm.inspector.reads.iter().map(|(a, s)| (format!("{a:?}"), format!("{s:#066x}"))).collect();
+
+    let (success, reason, gas, logs, output, created) = match res.result {
+        ExecutionResult::Success { reason, gas, logs, output } => { let created = match &output { Output::Create(_, addr) => addr.map(|a| format!("{a:?}")), _ => None }; (true, format!("{reason:?}"), gas, logs, output.into_data(), created) }
+        ExecutionResult::Revert { gas, logs, output } => (false, "revert".to_string(), gas, logs, output, None),
+        ExecutionResult::Halt { reason, gas, logs } => (false, format!("{reason:?}"), gas, logs, Bytes::new(), None),
+    };
+    let mut state = Vec::new();
+    for (address, acc) in res.state.iter() {
+        if !acc.is_touched() { continue; }
+        let deleted = acc.is_selfdestructed() || acc.is_empty();
+        let storage = acc.storage.iter().filter(|(_, s)| s.is_changed()).map(|(k, s)| (format!("{k:#066x}"), format!("{:#066x}", s.present_value))).collect();
+        let code = if acc.is_created() { acc.info.code.as_ref().map(|c| format!("0x{}", hex::encode(c.original_byte_slice()))) } else { None };
+        state.push(AccountOut { address: format!("{address:?}"), deleted, balance: format!("{:#x}", acc.info.balance), nonce: format!("{:#x}", acc.info.nonce), code_hash: format!("{:?}", acc.info.code_hash), code, storage });
+    }
+    let out = RunResult {
+        success, reason, gas_used: gas.tx_gas_used(), gas_refunded: gas.final_refunded(),
+        output: format!("0x{}", hex::encode(&output)), created,
+        logs: logs.iter().map(|l| LogOut { address: format!("{:?}", l.address), topics: l.data.topics().iter().map(|t| format!("{t:?}")).collect(), data: format!("0x{}", hex::encode(&l.data.data)) }).collect(),
+        state, sloads,
+    };
+    serde_json::to_string(&out).map_err(|e| e.to_string())
+}