copper-tone-tech/mev-beta
1
0
Fork 0
Code Issues Pull Requests 7 Actions Packages Projects Releases Wiki Activity
Files
33d5ef5bbcb69ba8ce3a02f7a3cda312d6ec6a86
mev-beta/docs/README.md
Administrator 3505921207 feat: comprehensive audit infrastructure and Phase 1 refactoring 
This commit includes:

## Audit & Testing Infrastructure
- scripts/audit.sh: 12-section comprehensive codebase audit
- scripts/test.sh: 7 test types (unit, integration, race, bench, coverage, contracts, pkg)
- scripts/check-compliance.sh: SPEC.md compliance validation
- scripts/check-docs.sh: Documentation coverage checker
- scripts/dev.sh: Unified development script with all commands

## Documentation
- SPEC.md: Authoritative technical specification
- docs/AUDIT_AND_TESTING.md: Complete testing guide (600+ lines)
- docs/SCRIPTS_REFERENCE.md: All scripts documented (700+ lines)
- docs/README.md: Documentation index and navigation
- docs/DEVELOPMENT_SETUP.md: Environment setup guide
- docs/REFACTORING_PLAN.md: Systematic refactoring plan

## Phase 1 Refactoring (Critical Fixes)
- pkg/validation/helpers.go: Validation functions for addresses/amounts
- pkg/sequencer/selector_registry.go: Thread-safe selector registry
- pkg/sequencer/reader.go: Fixed race conditions with atomic metrics
- pkg/sequencer/swap_filter.go: Fixed race conditions, added error logging
- pkg/sequencer/decoder.go: Added address validation

## Changes Summary
- Fixed race conditions on 13 metric counters (atomic operations)
- Added validation at all ingress points
- Eliminated silent error handling
- Created selector registry for future ABI migration
- Reduced SPEC.md violations from 7 to 5

Build Status: ✅ All packages compile
Compliance: ✅ No race conditions, no silent failures
Documentation: ✅ 1,700+ lines across 5 comprehensive guides

🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-11 07:17:13 +01:00

270 lines
6.8 KiB
Markdown
Raw Blame History

# Documentation Index
Complete documentation for the MEV Bot project.
## Quick Start
```bash
# 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](../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](../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](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](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.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](../SPEC.md) - Understand requirements
2. Follow [DEVELOPMENT_SETUP.md](DEVELOPMENT_SETUP.md) - Set up environment
3. Read [CLAUDE.md](../CLAUDE.md) - Learn workflow
#### Write Code
1. Check [SPEC.md](../SPEC.md) - Verify requirements
2. Use [CLAUDE.md](../CLAUDE.md) - Follow practices
3. Run `./scripts/dev.sh build` - Build in container
#### Test Code
1. Read [AUDIT_AND_TESTING.md](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](DEVELOPMENT_SETUP.md) - Contract workflow
#### Use Scripts
1. Read [SCRIPTS_REFERENCE.md](SCRIPTS_REFERENCE.md) - Script documentation
2. Run `./scripts/dev.sh help` - See available commands
#### Before Commit
```bash
./scripts/dev.sh test all
./scripts/dev.sh check-compliance
```
#### Before Push
```bash
./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](https://book.getfoundry.sh/) - Foundry documentation
- [Go Testing](https://pkg.go.dev/testing) - Go testing package
- [Arbitrum Sequencer Feed](https://www.degencode.com/p/decoding-the-arbitrum-sequencer-feed) - Sequencer protocol
- [Abigen](https://geth.ethereum.org/docs/tools/abigen) - Go binding generator
Reference in New Issue View Git Blame Copy Permalink