base-simulacrum 0.1.0

# Base Simulacrum - Complete Command Reference


## Table of Contents

- [Installation](#installation)
- [Help Commands](#help-commands)
- [Run Command](#run-command)
- [Status Command](#status-command)
- [Real Examples](#real-examples)

## Installation


```bash
# From crates.io (once published)

cargo install base-simulacrum

# From git

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

# From source

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

## Help Commands


```bash
# General help

base-simulacrum --help

# Run command help

base-simulacrum run --help

# Status command help

base-simulacrum status --help
```

## Run Command


### Syntax

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

### Required Arguments

- `--calls <PATH>` - Path to JSON batch configuration file

### Optional Arguments

- `--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

### All Possible Run Commands


#### Basic Usage

```bash
# Minimal command (uses all defaults)

base-simulacrum run --calls batch.json

# With gas sponsorship

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

# Custom chain ID

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

# Custom port

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

# Fork from network

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

#### Combined Options

```bash
# Sponsorship + custom chain

base-simulacrum run --calls batch.json --sponsor --chain-id 8453

# Sponsorship + custom port

base-simulacrum run --calls batch.json --sponsor --port 8545

# Sponsorship + fork

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

# Custom chain + port

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

# Custom chain + fork

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

# Custom port + fork

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

# All options

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

#### Network-Specific Commands

```bash
# Base Mainnet

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

# Base Sepolia

base-simulacrum run --calls batch.json --fork https://sepolia.base.org --chain-id 84532

# Ethereum Mainnet

base-simulacrum run --calls batch.json --fork https://eth.llamarpc.com --chain-id 1

# Optimism

base-simulacrum run --calls batch.json --fork https://mainnet.optimism.io --chain-id 10

# Arbitrum

base-simulacrum run --calls batch.json --fork https://arb1.arbitrum.io/rpc --chain-id 42161

# Polygon

base-simulacrum run --calls batch.json --fork https://polygon-rpc.com --chain-id 137
```

#### Testing Scenarios

```bash
# Simple ETH transfer

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

# Multi-call batch

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

# Token approval + swap

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

# DeFi interaction testing

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

# NFT minting batch

base-simulacrum run --calls nft-mint.json --sponsor

# Contract deployment batch

base-simulacrum run --calls deploy-batch.json --chain-id 31337
```

#### Parallel Testing

```bash
# Run multiple tests on different ports

base-simulacrum run --calls batch1.json --port 8545 &
base-simulacrum run --calls batch2.json --port 8546 &
base-simulacrum run --calls batch3.json --port 8547 &
```

## Status Command


### Syntax

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

### Required Arguments

- `--batch-id <ID>` - Batch ID from previous run

### Optional Arguments

- `--rpc <URL>` - RPC URL of Anvil instance (default: http://127.0.0.1:8545)

### All Possible Status Commands


```bash
# Default RPC

base-simulacrum status --batch-id 0x0c457f06dd7f405a8eaba50a289944a3

# Custom RPC URL

base-simulacrum status --batch-id 0x7c09f77296f04458b468448a537f0eda --rpc http://127.0.0.1:8545

# Different port

base-simulacrum status --batch-id 0x123abc --rpc http://127.0.0.1:9545

# Remote Anvil

base-simulacrum status --batch-id 0x456def --rpc http://192.168.1.100:8545

# Localhost with explicit protocol

base-simulacrum status --batch-id 0x789ghi --rpc http://localhost:8545
```

## Real Examples


### Example 1: Simple ETH Transfer

```bash
# Create simple-test.json

cat > simple-test.json << 'EOF'
{
  "version": "1.0",
  "chainId": "0x2105",
  "from": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
  "calls": [
    {
      "to": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
      "data": "0x",
      "value": "0xde0b6b3a7640000",
      "gas": null
    }
  ]
}
EOF

# Run it

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

### Example 2: Multi-Call Batch with Sponsorship

```bash
# Create test-batch.json

cat > test-batch.json << 'EOF'
{
  "version": "1.0",
  "chainId": "0x2105",
  "from": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
  "calls": [
    {
      "to": "0x0000000000000000000000000000000000000001",
      "data": "0x",
      "value": "0x16345785d8a0000",
      "gas": null
    },
    {
      "to": "0x0000000000000000000000000000000000000002",
      "data": "0x",
      "value": "0x2386f26fc10000",
      "gas": null
    }
  ],
  "capabilities": {
    "paymasterService": {
      "url": "https://api.developer.coinbase.com/rpc/v1/base/paymaster"
    }
  }
}
EOF

# Run it with sponsorship

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

### Example 3: Fork Testing

```bash
# Test against Base mainnet state

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

### Example 4: CI/CD Integration

```bash
#!/bin/bash

# test-batches.sh


echo "Testing EIP-5792 batches..."

# Test 1: Simple transfer

base-simulacrum run --calls tests/simple.json || exit 1

# Test 2: Multi-call

base-simulacrum run --calls tests/multi.json --sponsor || exit 1

# Test 3: Fork test

base-simulacrum run --calls tests/fork.json --fork https://mainnet.base.org || exit 1

echo "All tests passed!"
```

## Output Examples


### Successful Run

```
🚀 Base Simulacrum: Local EIP-5792 Batch Tester
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📄 Loaded batch configuration:
   Version: 1.0
   Chain ID: 0x2105
   From: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
   Calls: 2

✓ Anvil spawned on http://127.0.0.1:8545 (chain_id: 8453)

⚙️  Executing batch transaction...

📦 Processing batch with 2 calls
💰 Gas sponsorship enabled (estimated: 70000 gas)
  → Executing call 1/2 to 0x0000000000000000000000000000000000000001
    ✓ Call 1 confirmed (gas: 24000)
  → Executing call 2/2 to 0x0000000000000000000000000000000000000002
    ✓ Call 2 confirmed (gas: 21060)

✓ Batch execution completed successfully
  Batch ID: 0x7c09f77296f04458b468448a537f0eda

📊 Fetching execution status...
   Status: Confirmed
   Receipts: 2

   Receipt 1:
     Status: 0x1
     Block: 0x1
     Gas Used: 0x5dc0
     Tx Hash: 0x1a3fc49ff820fc483df2ec047124eddc6c36aab8acf6eaaee0fbf64041dfec64

   Receipt 2:
     Status: 0x1
     Block: 0x2
     Gas Used: 0x5244
     Tx Hash: 0x05cf40083f977a4695805c38b16c30a9ae99292b6fd799ec3d150fe8f2308fb6

✓ Anvil process terminated

✓ Test completed successfully
```

## Troubleshooting


### Anvil Not Found

```
Error: SpawnFailed("program not found")
```
**Solution:** Install Foundry and add to PATH
```bash
curl -L https://foundry.paradigm.xyz | bash
foundryup
```

### Port In Use

```
Error: StartupTimeout
```
**Solution:** Use different port
```bash
base-simulacrum run --calls batch.json --port 9545
```

### Invalid JSON

```
Error: expected value at line 1 column 1
```
**Solution:** Validate JSON syntax
```bash
cat batch.json | jq .
```