✨ feat: Add fork-state host with RPC integration and 3-tier caching

[roninjin10]

Summary

• Implements lazy-fetch blockchain state from remote RPC endpoints
• 3-tier caching: local modifications → fork cache (pristine) → RPC fallback
• WASM-compatible via user-injectable RPC request function
• References TEVM monorepo architecture while adapting to Zig idioms

Architecture

Core Components

• src/host/json_rpc.zig - JSON-RPC request builders and response parsers

  • buildGetStorageAtParams() / parseStorageResponse()
  • buildGetBalanceParams() / parseBalanceResponse()
  • buildGetCodeParams() / parseCodeResponse()
  • buildGetTransactionCountParams() / parseNonceResponse()
  • BlockTag support: "latest", "earliest", "pending", block number, block hash

• src/host/fork_host.zig - Fork-enabled host with 3-tier caching

  • local_* maps: Modified state during EVM execution
  • fork_cache_* maps: Pristine remote data (immutable)
  • RPC fallback on cache miss
  • Unit tests with mocked RPC responses

• src/host/test_host.zig - In-memory test host (moved from test/specs/)

• src/root_c.zig - WASM integration

  • extern "env" fn js_rpc_request() - JavaScript callback
  • export fn evm_set_fork_config() - Configure fork block and RPC
  • wasmRpcRequest() - Wrapper for calling JavaScript

WASM Integration Pattern

// JavaScript provides this via WebAssembly.instantiate imports
extern "env" fn js_rpc_request(
    method_ptr: [*]const u8,
    method_len: usize,
    params_ptr: [*]const u8,
    params_len: usize,
    response_buffer: [*]u8,
    response_capacity: usize,
) c_int;

// Zig calls it via wrapper
fn wasmRpcRequest(...) isize {
    return js_rpc_request(...);
}

Usage (WASM)

const wasm = await WebAssembly.instantiate(wasmBytes, {
  env: {
    js_rpc_request: (methodPtr, methodLen, paramsPtr, paramsLen, bufPtr, bufCap) => {
      const method = readString(methodPtr, methodLen);
      const params = readString(paramsPtr, paramsLen);
      const response = await fetch(RPC_URL, {
        method: 'POST',
        body: JSON.stringify({ jsonrpc: '2.0', method, params, id: 1 })
      });
      writeString(bufPtr, bufCap, await response.text());
      return response.ok ? response.text().length : -1;
    }
  }
});

const evm = wasm.instance.exports.evm_create();
wasm.instance.exports.evm_set_fork_config(evm, "latest", 6);

Test Plan

• Build succeeds (native and WASM)
• AST validation passes
• WASM size: 228KB (reasonable growth)
• Unit tests included in fork_host.zig
• Test imports added to src/root.zig
• Documentation updated in CLAUDE.md

Files Changed

• src/host/json_rpc.zig - 412 lines (new)
• src/host/fork_host.zig - 525 lines (new)
• src/host/test_host.zig - 191 lines (moved from test/specs/)
• src/root_c.zig - +139 lines (WASM integration)
• src/root.zig - +2 lines (test imports)
• CLAUDE.md - +26 lines (test filtering docs)

🤖 Generated with Claude Code