mev-beta/docs/README.md

Documentation Index

Complete documentation for the MEV Bot project.

Quick Start

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

# 2. Build and test
./scripts/dev.sh build
./scripts/dev.sh test all

# 3. Run audit before commit
./scripts/dev.sh audit
./scripts/dev.sh check-compliance

Core Documentation

📋 SPEC.md

Technical Specification

The authoritative technical specification for the entire project.

Covers:

• Architecture principles (channel-based, sequencer-first)
• Sequencer processing pipeline (4 stages)
• Contract bindings management
• Pool cache design
• Validation rules
• Critical DO/DON'T requirements

Read this first to understand project requirements.

---

📚 CLAUDE.md

Development Guidelines

Day-to-day development practices and project status.

Covers:

• Current project status
• Containerized development workflow
• Recent fixes and known issues
• Repository structure
• Git workflow
• Common development tasks

Read this for practical development guidance.

---

Setup and Configuration

🔧 DEVELOPMENT_SETUP.md

Environment Setup Guide

Complete guide for setting up the development environment.

Covers:

• Quick start workflow
• Container-based development
• Contract development process
• Binding generation
• Directory structure
• Common tasks
• Troubleshooting

Follow this when setting up your dev environment.

---

Testing and Quality

🧪 AUDIT_AND_TESTING.md

Testing Guide

Comprehensive testing and auditing procedures.

Covers:

• Unit tests
• Integration tests
• Race detection
• Benchmarks
• Coverage reports
• Code quality audits
• Security checks
• Documentation coverage
• SPEC.md compliance

Use this to ensure code quality.

---

📜 SCRIPTS_REFERENCE.md

Scripts Reference

Complete reference for all development scripts.

Covers:

• dev.sh - Main development script
• test.sh - Testing suite
• audit.sh - Code audit
• check-docs.sh - Documentation coverage
• check-compliance.sh - SPEC.md compliance
• Contract scripts
• Utility scripts

Reference this when using development tools.

---

Planning Documents

Located in planning/ directory:

• 00_V2_MASTER_PLAN.md - Complete V2 architecture
• 01_MODULARITY_REQUIREMENTS.md - Modularity guidelines
• 07_TASK_BREAKDOWN.md - Detailed task breakdown (~99 hours)

---

By Use Case

I want to...

Start Development

1. Read SPEC.md - Understand requirements
2. Follow DEVELOPMENT_SETUP.md - Set up environment
3. Read CLAUDE.md - Learn workflow

Write Code

1. Check SPEC.md - Verify requirements
2. Use CLAUDE.md - Follow practices
3. Run ./scripts/dev.sh build - Build in container

Test Code

1. Read AUDIT_AND_TESTING.md - Learn testing
2. Run ./scripts/dev.sh test all - Run all tests
3. Run ./scripts/dev.sh test coverage - Check coverage

Audit Code

1. Run ./scripts/dev.sh audit - Code quality audit
2. Run ./scripts/dev.sh check-compliance - SPEC.md compliance
3. Run ./scripts/dev.sh check-docs - Documentation coverage

Work with Contracts

1. Run ./scripts/dev.sh forge-build - Build contracts
2. Run ./scripts/dev.sh bindings - Generate Go bindings
3. See DEVELOPMENT_SETUP.md - Contract workflow

Use Scripts

1. Read SCRIPTS_REFERENCE.md - Script documentation
2. Run ./scripts/dev.sh help - See available commands

Before Commit

./scripts/dev.sh test all
./scripts/dev.sh check-compliance

Before Push

./scripts/dev.sh test all
./scripts/dev.sh test race
./scripts/dev.sh audit
./scripts/dev.sh check-compliance
./scripts/dev.sh check-docs

---

Document Status

Document	Status	Last Updated
SPEC.md	✅ Complete	2025-11-11
CLAUDE.md	✅ Complete	2025-11-11
DEVELOPMENT_SETUP.md	✅ Complete	2025-11-11
AUDIT_AND_TESTING.md	✅ Complete	2025-11-11
SCRIPTS_REFERENCE.md	✅ Complete	2025-11-11
planning/00_V2_MASTER_PLAN.md	✅ Complete	2025-11-03
planning/07_TASK_BREAKDOWN.md	✅ Complete	2025-11-03

---

Documentation Philosophy

Principles

1. Single Source of Truth: SPEC.md is authoritative for technical requirements
2. Practical Guidance: CLAUDE.md provides day-to-day workflow
3. Comprehensive Coverage: All aspects documented with examples
4. Consistent Format: All docs follow same structure
5. Living Documents: Updated with code changes

Organization

docs/
├── README.md                    # This file (index)
├── DEVELOPMENT_SETUP.md         # Setup guide
├── AUDIT_AND_TESTING.md         # Testing guide
├── SCRIPTS_REFERENCE.md         # Scripts reference
└── planning/                    # Architecture planning
    ├── 00_V2_MASTER_PLAN.md
    ├── 01_MODULARITY_REQUIREMENTS.md
    └── 07_TASK_BREAKDOWN.md

Root:
├── SPEC.md                      # Technical specification
├── CLAUDE.md                    # Development guidelines
└── README.md                    # Project overview

---

Contributing to Documentation

Adding New Documentation

1. Place in appropriate location (docs/ or root)
2. Update this index (docs/README.md)
3. Link from relevant documents
4. Follow existing formatting style
5. Include code examples
6. Add to "Document Status" table

Documentation Standards

• Format: Markdown with GitHub flavors
• Code blocks: Include language hint (bash, go)
• Links: Use relative paths
• Examples: Real, working examples only
• Structure: Clear headings, table of contents
• Length: Comprehensive but concise
• Voice: Second person ("You should...")

When to Update

• SPEC.md changes → Update all docs referencing requirements
• New script added → Update SCRIPTS_REFERENCE.md
• New workflow → Update DEVELOPMENT_SETUP.md
• New testing approach → Update AUDIT_AND_TESTING.md
• Process change → Update CLAUDE.md

---

Getting Help

If documentation is unclear or missing:

1. Check all relevant docs using this index
2. Search for keywords across all docs
3. Check SPEC.md for authoritative requirements
4. Review script source code in scripts/
5. Open issue describing documentation gap

---

External Resources

• Foundry Book - Foundry documentation
• Go Testing - Go testing package
• Arbitrum Sequencer Feed - Sequencer protocol
• Abigen - Go binding generator