mev-beta/docs/DEVELOPMENT_SETUP.md

Development Environment Setup

Overview

This project enforces containerized development for consistency and adherence to SPEC.md requirements.

Key Documents

• SPEC.md - Technical specification and architecture requirements
• CLAUDE.md - Development guidelines and workflow
• bindings/README.md - Contract bindings usage and generation

Quick Start

# 1. Start development containers
./scripts/dev.sh up

# 2. Build contracts
./scripts/dev.sh forge-build

# 3. Generate Go bindings
./scripts/dev.sh bindings

# 4. Build Go application
./scripts/dev.sh build

# 5. Run tests
./scripts/dev.sh test

Development Workflow

1. Container-Based Development

NEVER run builds or tests outside of containers.

All commands use ./scripts/dev.sh which ensures:

• Consistent build environment
• Proper dependency management
• Compliance with SPEC.md
• Reproducible builds

2. Contract Development

# Build all Solidity contracts
./scripts/dev.sh forge-build

# Run contract tests
./scripts/dev.sh forge-test

# Generate Go bindings from ABIs
./scripts/dev.sh bindings

Contract Structure:

contracts/
├── lib/                    # Foundry dependencies (official DEX contracts)
│   ├── v2-core/           # Uniswap V2
│   ├── v3-core/           # Uniswap V3
│   ├── v3-periphery/      # Uniswap V3 Router
│   └── openzeppelin/      # OpenZeppelin contracts
├── src/                    # Custom contracts and interfaces
│   ├── interfaces/        # Interface definitions
│   ├── libraries/         # Utility libraries
│   └── utils/             # Helper contracts
├── out/                    # Build artifacts (ABIs, bytecode)
└── foundry.toml           # Foundry configuration

3. Go Development

# Build application
./scripts/dev.sh build

# Run tests
./scripts/dev.sh test

# Enter Go container for interactive development
./scripts/dev.sh go
# Inside container:
# go test ./pkg/sequencer/... -v
# go run ./cmd/mev-bot/main.go

4. Binding Generation

IMPORTANT: Use official contract ABIs from Foundry builds, NOT manual JSON files.

# 1. Build contracts first
./scripts/dev.sh forge-build

# 2. Generate bindings
./scripts/dev.sh bindings

# Generated bindings appear in:
bindings/
├── uniswap_v2/
│   ├── router.go          # UniswapV2Router02
│   └── pair.go            # UniswapV2Pair
├── uniswap_v3/
│   ├── router.go          # SwapRouter
│   └── pool.go            # UniswapV3Pool
└── README.md              # Usage documentation

Directory Structure

/docker/mev-beta/
├── SPEC.md                      # Technical specification
├── CLAUDE.md                    # Development guidelines
│
├── scripts/
│   ├── dev.sh                  # Main development script ⭐
│   ├── dev-up.sh               # Start containers
│   ├── dev-down.sh             # Stop containers
│   ├── generate-bindings.sh    # Legacy bindings script
│   └── generate-bindings-in-container.sh  # Container-based bindings
│
├── contracts/                   # Foundry project
│   ├── lib/                    # Dependencies (git submodules)
│   ├── src/                    # Contract sources
│   ├── out/                    # Build artifacts
│   └── foundry.toml            # Configuration
│
├── bindings/                    # Generated Go bindings
│   ├── uniswap_v2/
│   ├── uniswap_v3/
│   └── README.md
│
├── pkg/                         # Go packages
│   ├── sequencer/              # Arbitrum sequencer feed
│   ├── pools/                  # Pool cache and discovery
│   └── ...
│
├── cmd/
│   └── mev-bot/                # Application entry point
│
├── docker-compose.yml           # Container definitions
└── docs/
    ├── planning/               # V2 architecture plans
    └── DEVELOPMENT_SETUP.md    # This file

Container Reference

mev-go-dev

• Image: golang:1.21-alpine
• Purpose: Go development, testing, building
• Tools: go, abigen, gcc, git
• Working Dir: /workspace
• Access: ./scripts/dev.sh go

mev-foundry

• Image: ghcr.io/foundry-rs/foundry:latest
• Purpose: Solidity contract development
• Tools: forge, cast, anvil
• Working Dir: /workspace
• Access: ./scripts/dev.sh foundry

mev-python-dev

• Image: python:3.11-slim
• Purpose: Analysis scripts, data processing
• Tools: python, pip
• Working Dir: /workspace
• Access: ./scripts/dev.sh python

Common Tasks

Adding New DEX Contract

# 1. Enter Foundry container
./scripts/dev.sh foundry

# 2. Install official contract
cd /workspace/contracts
forge install <org>/<repo>

# 3. Exit container and rebuild
exit
./scripts/dev.sh forge-build

# 4. Generate Go bindings
./scripts/dev.sh bindings

Debugging Build Issues

# Check container status
./scripts/dev.sh ps

# View logs
./scripts/dev.sh logs go-dev

# Clean and rebuild
./scripts/dev.sh clean
./scripts/dev.sh forge-build
./scripts/dev.sh build

Running Specific Tests

# Enter Go container
./scripts/dev.sh go

# Inside container, run specific tests
go test ./pkg/sequencer/... -v -run TestSwapFilter
go test ./pkg/pools/... -v -run TestPoolCache

Development Rules (from SPEC.md)

MUST DO ✅

• Use ./scripts/dev.sh for all operations
• Use Arbitrum sequencer feed as primary data source
• Derive contract ABIs from official sources via Foundry
• Generate Go bindings with abigen
• Use channels for ALL inter-component communication
• Validate ALL parsed data before propagation
• Emit comprehensive metrics and structured logs

MUST NOT DO ❌

• Run builds outside of containers
• Use HTTP RPC as primary data source
• Write manual ABI JSON files
• Hardcode function selectors
• Allow zero addresses or zero amounts to propagate
• Use blocking operations in hot paths

Troubleshooting

Container Won't Start

# Check Podman status
podman ps -a

# Check logs
podman logs mev-go-dev

# Force restart
./scripts/dev.sh down
./scripts/dev.sh up

Build Failures

# Clean artifacts
./scripts/dev.sh clean

# Restart containers
./scripts/dev.sh restart

# Rebuild
./scripts/dev.sh forge-build
./scripts/dev.sh build

Binding Generation Fails

# Ensure contracts are built first
./scripts/dev.sh forge-build

# Check for artifacts
ls -la contracts/out/

# Manually generate if needed
./scripts/dev.sh go
# Inside container:
./scripts/generate-bindings-in-container.sh

Next Steps

1. Add More DEX Contracts: Install Camelot, Balancer, Curve, Kyber
2. Fix Contract Compilation: Resolve Solidity errors in src/
3. Complete Swap Detection: Implement ABI-based swap parsing
4. Test Pool Discovery: Verify pool cache functionality
5. Deploy Phase 1: Monitor sequencer feed in production

References

• SPEC.md - Complete technical specification
• CLAUDE.md - Project guidelines and status
• bindings/README.md - Contract binding usage
• docs/planning/00_V2_MASTER_PLAN.md - Architecture overview