Dev Environment Overview

Version: 2.0.0 Last Updated: 2026-03-16 Crate: mirage-rs/ (chain backend) + packages/dev/ui/ (debug UI)

Reader orientation: This document is the overview of Bardo’s local development environment (section 15). It introduces mirage-rs, a single Rust binary that replaces Anvil for DeFi development by forking a live chain and replaying blocks through an in-process revm instance. The key concept is that your local transactions execute alongside real market activity, so LP positions accrue fees from real swaps and vaults track real NAV changes. This section also covers the debug UI, contract deployment pipeline, and scenario tooling. See prd2/shared/glossary.md for full term definitions.

Why This Exists

Building on top of the Uniswap stack (V2, V3, V4, UniswapX, Universal Router, ERC-8004) means testing against the real thing. Mock stubs miss the protocol interactions that matter: V4 hook callbacks during swaps, concentrated liquidity tick crossings, UniswapX Dutch auction fills, ERC-8004 identity gates.

But Anvil’s fork mode has a fundamental limitation: forked chains are frozen snapshots. You fork mainnet at block N, execute your trade, and then nothing. The rest of the market doesn’t move. You can’t see what happens to your LP position when ETH drops 5% an hour later. You can’t watch how your vault’s NAV tracks as the underlying assets fluctuate.

mirage-rs fixes this. It forks a live chain, replays incoming blocks through an in-process revm instance, and lets you trade alongside the real market. Your transactions execute locally; mainnet transactions continue flowing in. You see the combined state: your positions plus the market’s actual movements.

This replaces Anvil, the TypeScript deployment tooling, and all prior mirage implementations. One Rust binary.

Goals

Non-Goals

Two Modes

Live Fork Mode

Fork any EVM chain at a specific block (or latest). The block follower subscribes to new blocks via WebSocket and replays them through the local revm instance. Your local transactions are interleaved with mainnet transactions.

Best for:

• Seeing how markets move after your trades
• Testing LP strategies against real price action
• Observing vault NAV changes under real market conditions
• Evaluating agent strategies against live data

mirage-rs --rpc-url wss://eth-mainnet.g.alchemy.com/v2/KEY --follow

Fresh Testnet Mode

Start with a blank chain. Deploy all contracts from scratch. No external RPC needed.

Best for:

• Offline development
• CI environments
• Testing exact deployment sequences
• Deterministic, reproducible environments

mirage-rs --fresh --chain-id 31337

Architecture

+-----------------------------------------------------+
|                    mirage-rs binary                   |
|                                                       |
|  +-----------+  +-------------+  +-----------+       |
|  | JSON-RPC  |  |   Block     |  | Divergence|       |
|  |  Server   |  |  Follower   |  | Detector  |       |
|  |(jsonrpsee)|  | (WS/HTTP)   |  |           |       |
|  +-----+-----+  +------+------+  +-----+-----+      |
|        |               |               |              |
|  +-----v---------------v---------------v--------+    |
|  |              EVM Executor (revm)              |    |
|  |  +------------------------------------------+|    |
|  |  | ForkState                                 ||    |
|  |  |  +--------------------------------------+ ||    |
|  |  |  | CacheDB (in-memory, mutable)         | ||    |
|  |  |  |  +--------------------------------+  | ||    |
|  |  |  |  | RemoteDB (lazy RPC fetch)      |  | ||    |
|  |  |  |  +--------------------------------+  | ||    |
|  |  |  +--------------------------------------+ ||    |
|  |  +------------------------------------------+|    |
|  +-----------------------------------------------+   |
+-----------------------------------------------------+
          ^                           |
          | JSON-RPC                  | RPC fetch on cache miss
          |                           v
   Debug UI / viem             Upstream RPC (mainnet)

Three layers:

1. ForkState – In-memory EVM state. CacheDB<RemoteDB> provides two-layer caching: mutations stay in CacheDB, cache misses fetch from upstream RPC at the fork block.
2. EVM Executor – revm configured for Cancun spec. Executes transactions, commits state changes, returns receipts.
3. Surfaces – JSON-RPC server for external tools, block follower for live data, divergence detector for validation.

Package Layout

mirage-rs/                    # Rust binary -- the chain backend
+-- src/
|   +-- main.rs               # Entry point, CLI, lifecycle
|   +-- cli.rs                # clap argument parsing
|   +-- config.rs             # MirageConfig, SyncMode
|   +-- error.rs              # Error types
|   +-- prefetch.rs           # Block state prefetching
|   +-- state/                # ForkState, RemoteDB, overlay, snapshots, manipulation
|   +-- executor/             # EvmExecutor, block/tx env construction
|   +-- follower/             # Block following, tx filtering
|   +-- rpc/                  # JSON-RPC server (eth_*, mirage_*, net_*, web3_*)
|   +-- divergence/           # Replay vs mainnet comparison
|   +-- simulators/           # Gas, lending (stub), oracle (stub)
+-- Cargo.toml
+-- rust-toolchain.toml

packages/dev/
+-- ui/                       # React + Vite debug UI (connects via JSON-RPC)
+-- browser/                  # Browser SPA (deprioritized)

Tech Stack

Ports

Cross-References