base-simulacrum 0.1.0

# Base Simulacrum


[![Crates.io](https://img.shields.io/crates/v/base-simulacrum.svg)](https://crates.io/crates/base-simulacrum)
[![Documentation](https://docs.rs/base-simulacrum/badge.svg)](https://docs.rs/base-simulacrum)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Build Status](https://img.shields.io/github/actions/workflow/status/Dominion77/base-simulacrum/ci.yml?branch=main)](https://github.com/Dominion77/base-simulacrum/actions)

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](https://book.getfoundry.sh/getting-started/installation) (for `anvil`)

## Installation


### From Source


```bash
git clone https://github.com/Dominion77/base-simulacrum.git
cd base-simulacrum
cargo install --path .
```

### From Crates.io (once published)


```bash
cargo install base-simulacrum
```

### From Git Repository


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

## Usage


### Quick Start


```bash
# 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:**
```bash
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:**
```bash
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:**
```bash
base-simulacrum --help
base-simulacrum run --help
base-simulacrum status --help
```

### Real Command Examples


```bash
# 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](USAGE.md) for detailed documentation and [COMMANDS.md](COMMANDS.md) for complete command reference.

## Batch Configuration Format


Create a JSON file with the following structure:

```json
{
  "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


```bash
cargo test
```

## License


MIT