Supersim

Supersim is a local multi-L2 development environment that simulates the Superchain with a single L1 and multiple OP-Stack L2s.

Quick Start

# Install
brew install ethereum-optimism/tap/supersim

# Start vanilla mode (3 chains: L1=900, L2s=901,902)
supersim

Core Concepts

• Vanilla Mode: Local dev chains with predeployed OP Stack contracts
• Fork Mode: Fork real networks (mainnet, testnet) locally
• Interop: L2-to-L2 message passing and SuperchainERC20 tokens

Chain Configuration (Vanilla)

Chain	ChainID	RPC Port
L1	900	8545
OPChainA	901	9545
OPChainB	902	9546

Common Commands

# Vanilla mode with auto-relay for L2->L2 transfers
supersim --interop.autorelay

# Fork mode - specify chains to fork
supersim fork --chains=op,base,zora

# Fork with interop contracts
supersim fork --chains=op,base,zora --interop.enabled

Example: L1 to L2 Deposit

# 1. Check L2 balance
cast balance 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --rpc-url http://127.0.0.1:9545

# 2. Bridge ETH (use L1StandardBridge address from supersim output)
cast send <L1StandardBridgeAddress> "bridgeETH(uint32,bytes)" 50000 0x \
  --value 0.1ether --rpc-url http://127.0.0.1:8545 \
  --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

# 3. Verify L2 balance increased
cast balance 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --rpc-url http://127.0.0.1:9545

Example: L2 to L2 Transfer

# Requires --interop.autorelay flag on supersim

# 1. Mint tokens on source chain (901)
cast send 0x420beeF000000000000000000000000000000001 \
  "mint(address,uint256)" 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 1000 \
  --rpc-url http://127.0.0.1:9545 \
  --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

# 2. Send to destination chain (902)
cast send 0x4200000000000000000000000000000000000028 \
  "sendERC20(address,address,uint256,uint256)" \
  0x420beeF000000000000000000000000000000001 \
  0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 1000 902 \
  --rpc-url http://127.0.0.1:9545 \
  --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

# 3. Check balance on destination chain
cast balance --erc20 0x420beeF000000000000000000000000000000001 \
  0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --rpc-url http://127.0.0.1:9546

Key Predeploy Addresses (Vanilla)

Contract	Address
L2NativeSuperchainERC20	0x420beeF000000000000000000000000000000001
SuperchainTokenBridge	0x4200000000000000000000000000000000000028

Docker Usage

# Build
docker build -t supersim .

# Run
docker run --rm -it --network host supersim:latest

Resources

• Full Documentation
• Training Video
• SuperchainERC20 Starter Kit