Base Simulacrum

A headless CLI tool for locally testing EIP-5792 batch transactions against a simulated Base environment.

Overview

base-simulacrum allows you to test complex transaction batching (like token approvals + swaps) and gas sponsorship locally without deploying to a testnet or connecting a real wallet.

Architecture

┌────────────────────────────────────────────────────────┐
│                 Simulacrum CLI Tool                    │
└───────────────────────────┬────────────────────────────┘
                            │ Spawns
                            ▼
┌────────────────────────────────────────────────────────┐
│           Anvil Node (Local Base Fork/EVM)             │
└───────────────────────────┬────────────────────────────┘
                            │ Exposes Local RPC
                            ▼
┌──────────────────────────────────────────────────────────────────────┐
│                  EIP-5792 State Machine (Rust Engine)                │
│                                                                      │
│  1. wallet_sendCalls parser (Batch execution)                       │
│  2. Local Paymaster Simulator (Gas estimation & sponsorship)        │
│  3. wallet_getCallsStatus tracker                                   │
└──────────────────────────────────────────────────────────────────────┘

Features

Local EVM Simulation: Automatically spawns and manages Anvil instances
EIP-5792 Implementation: Full wallet_sendCalls and wallet_getCallsStatus support
Gas Sponsorship: Mock paymaster for testing sponsored transactions
Network Forking: Test against real contract state from Base, Ethereum, or any EVM chain
Atomic Batching: Execute multiple transactions that succeed or fail together
Zero External Dependencies: No browser, frontend, or live network required
Deterministic Testing: Millisecond-fast execution against in-memory EVM
Parallel Testing: Run multiple test suites simultaneously on different ports

Prerequisites

Rust 1.75+
Foundry (for anvil)

Installation

From Source

git clone https://github.com/Dominion77/base-simulacrum.git

cd base-simulacrum

cargo install --path .

From Crates.io (once published)

cargo install base-simulacrum

From Git Repository

cargo install --git https://github.com/Dominion77/base-simulacrum.git

Usage

Quick Start

# Basic single transaction

base-simulacrum run --calls simple-test.json


# Multi-call batch with gas sponsorship

base-simulacrum run --calls test-batch.json --sponsor


# Fork from Base mainnet

base-simulacrum run --calls batch.json --fork https://mainnet.base.org --sponsor

All Available Commands

Run a batch transaction:

base-simulacrum run --calls <PATH> [OPTIONS]


Options:

  --calls <PATH>         Path to JSON batch configuration file (required)
  --sponsor              Enable gas sponsorship simulation

  --chain-id <ID>        Chain ID for local network (default: 8453)
  --port <PORT>          Port for Anvil instance (default: 8545)
  --fork <URL>           Fork from a live network RPC URL

  -h, --help             Print help

Check batch status:

base-simulacrum status --batch-id <ID> [OPTIONS]


Options:

  --batch-id <ID>        Batch ID from previous run (required)
  --rpc <URL>            RPC URL of Anvil instance (default: http://127.0.0.1:8545)
  -h, --help             Print help

Get help:

base-simulacrum --help

base-simulacrum run --help

base-simulacrum status --help

Real Command Examples

# 1. Simple ETH transfer

base-simulacrum run --calls simple-test.json


# 2. Multi-call batch with sponsorship

base-simulacrum run --calls test-batch.json --sponsor


# 3. Custom chain ID (Ethereum mainnet)

base-simulacrum run --calls batch.json --chain-id 1


# 4. Custom port (avoid conflicts)

base-simulacrum run --calls batch.json --port 9545


# 5. Fork from Base mainnet

base-simulacrum run --calls batch.json --fork https://mainnet.base.org


# 6. All options combined

base-simulacrum run --calls batch.json --sponsor --chain-id 8453 --port 8545 --fork https://mainnet.base.org


# 7. Check batch status

base-simulacrum status --batch-id 0x0c457f06dd7f405a8eaba50a289944a3

See USAGE.md for detailed documentation and COMMANDS.md for complete command reference.

Batch Configuration Format

Create a JSON file with the following structure:

{
  "version": "1.0",
  "chainId": "0x2105",
  "from": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
  "calls": [
    {
      "to": "0x5FbDB2315678afecb367f032d93F642f64180aa3",
      "data": "0x095ea7b3...",
      "value": null
    }
  ],
  "capabilities": {
    "paymasterService": {
      "url": "https://api.developer.coinbase.com/rpc/v1/base/paymaster"
    }
  }
}

Project Structure

src/
├── main.rs       # CLI entry point with clap
├── anvil.rs      # Anvil process management
├── engine.rs     # EIP-5792 state machine
├── paymaster.rs  # Local gas sponsorship simulator
└── types.rs      # Shared data structures

Testing

cargo test

License

MIT

base-simulacrum 0.1.0