copper-tone-tech/mev-beta
1
0
Fork 0
Code Issues Pull Requests 7 Actions Packages Projects Releases Wiki Activity

docs: update CLAUDE.md with v2-master branch structure

Browse Source 
Updated project guidance to reflect V2 foundation completion:

Branch Structure:
- v2-master (production, protected)
- v2-master-dev (development, protected)
- feature/v2-prep (archived, foundation complete)
- feature/v2/* (feature branches from v2-master-dev)

Branch Hierarchy:
v2-master ← v2-master-dev ← feature/v2/*

Updated Sections:
- Project Status: V2 Foundation Complete ✅
- Git Workflow: New branch structure and workflow
- Example Workflow: Updated to use v2-master-dev
- What TO Do: Reflects foundation completion
- Key Files: Added V2 foundation files (100% coverage)
- Current Branches: New section documenting branch structure
- Contact and Resources: Updated with completion status

Workflow:
1. Create feature branch from v2-master-dev
2. Implement with 100% test coverage
3. Run make validate locally
4. PR to v2-master-dev (CI/CD enforces coverage)
5. Merge v2-master-dev → v2-master for production

Foundation Status:
- 3,300+ lines (1,500 implementation, 1,800 tests)
- 100% test coverage (enforced)
- CI/CD fully configured
- Ready for protocol parser implementations

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Administrator
2025-11-10 14:55:58 +01:00
parent 95e2c284af
commit 291ccf0c6a
1 changed files with 107 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

137
CLAUDE.md
View File

@@ -2,14 +2,15 @@
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Status: V2 Architecture Planning ## Project Status: V2 Foundation Complete ✅
This repository is currently in **V2 planning phase**. The V1 codebase has been moved to `orig/` for preservation while V2 architecture is being designed. This repository has completed **V2 foundation implementation** with 100% test coverage. The V1 codebase has been moved to `orig/` for preservation.
**Current State:** **Current State:**
- V1 implementation: `orig/` (frozen for reference) - V1 implementation: `orig/` (frozen for reference)
- V2 planning documents: `docs/planning/` - V2 planning documents: `docs/planning/` (complete)
- Active development: Not yet started (planning phase) - V2 foundation: `pkg/` (✅ complete with 100% test coverage)
- Active development: Ready for protocol parser implementations
## Repository Structure ## Repository Structure
@@ -214,6 +215,26 @@ go test ./tests/load/... -v
## Git Workflow ## Git Workflow
### Branch Structure
**V2 Production & Development Branches:**
```
v2-master # Production branch for V2 (protected)
v2-master-dev # Development branch for V2 (protected)
feature/v2-prep # Planning and foundation (archived)
feature/v2/* # Feature branches for development
```
**Branch Hierarchy:**
```
v2-master (production)
↑
└── v2-master-dev (development)
↑
└── feature/v2/* (feature branches)
```
### Branch Strategy (STRICTLY ENFORCED) ### Branch Strategy (STRICTLY ENFORCED)
**ALL V2 development MUST use feature branches:** **ALL V2 development MUST use feature branches:**
@@ -225,31 +246,36 @@ feature/v2/<component>/<task-id>-<description>
# Examples: # Examples:
feature/v2/parsers/P2-002-uniswap-v2-base feature/v2/parsers/P2-002-uniswap-v2-base
feature/v2/cache/P3-001-address-index feature/v2/cache/P3-001-address-index
feature/v2/validation/P4-001-validation-rules feature/v2/arbitrage/P5-001-path-finder
``` ```
**Branch Rules:** **Branch Rules:**
1. ✅ **ALWAYS** create feature branch from `feature/v2-prep` 1. ✅ **ALWAYS** create feature branch from `v2-master-dev`
2. ✅ **NEVER** commit directly to `feature/v2-prep` or `master-dev` 2. ✅ **NEVER** commit directly to `v2-master` or `v2-master-dev`
3. ✅ Branch name MUST match task ID from `07_TASK_BREAKDOWN.md` 3. ✅ Branch name MUST match task ID from `07_TASK_BREAKDOWN.md`
4. ✅ One branch per atomic task (< 2 hours work) 4. ✅ One branch per atomic task (< 2 hours work)
5. ✅ Delete branch after merge 5. ✅ Delete branch after merge
6. ✅ Merge feature → v2-master-dev → v2-master
**Example Workflow:** **Example Workflow:**
```bash ```bash
# 1. Create feature branch # 1. Create feature branch from v2-master-dev
git checkout feature/v2-prep git checkout v2-master-dev
git pull origin feature/v2-prep git pull origin v2-master-dev
git checkout -b feature/v2/parsers/P2-002-uniswap-v2-base git checkout -b feature/v2/parsers/P2-002-uniswap-v2-base
# 2. Implement task P2-002 # 2. Implement task P2-002
# ... make changes ... # ... make changes ...
# 3. Test with 100% coverage (REQUIRED) # 3. Test with 100% coverage (REQUIRED)
go test ./pkg/parsers/uniswap_v2/... -coverprofile=coverage.out make test-coverage
# MUST show 100% coverage # MUST show 100% coverage or CI/CD will fail
# 4. Commit # 4. Run full validation locally
make validate
# All checks must pass
# 5. Commit with conventional format
git add . git add .
git commit -m "feat(parsers): implement UniswapV2 parser base structure git commit -m "feat(parsers): implement UniswapV2 parser base structure
@@ -265,11 +291,21 @@ Tests: 15/15 passing
🤖 Generated with [Claude Code](https://claude.com/claude-code) 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>" Co-Authored-By: Claude <noreply@anthropic.com>"
# 5. Push and create PR # 6. Push and create PR to v2-master-dev
git push -u origin feature/v2/parsers/P2-002-uniswap-v2-base git push -u origin feature/v2/parsers/P2-002-uniswap-v2-base
# 6. After merge, delete branch # 7. Create PR on GitHub targeting v2-master-dev
# Wait for CI/CD to pass (100% coverage enforced)
# 8. Merge PR and delete feature branch
git checkout v2-master-dev
git pull origin v2-master-dev
git branch -d feature/v2/parsers/P2-002-uniswap-v2-base git branch -d feature/v2/parsers/P2-002-uniswap-v2-base
# 9. When ready for production release
git checkout v2-master
git merge --no-ff v2-master-dev
git push origin v2-master
``` ```
### Commit Message Format ### Commit Message Format
@@ -317,35 +353,76 @@ fix: parser bug
- ❌ Allow zero addresses or zero amounts to propagate - ❌ Allow zero addresses or zero amounts to propagate
### What TO Do ### What TO Do
- ✅ Read `docs/planning/00_V2_MASTER_PLAN.md` before starting - ✅ Review foundation implementation in `pkg/` before adding parsers
- ✅ Follow task breakdown in `07_TASK_BREAKDOWN.md` - ✅ Follow task breakdown in `07_TASK_BREAKDOWN.md`
- ✅ Write tests before implementation (TDD) - ✅ Write tests before implementation (TDD - MANDATORY)
- ✅ Use strict validation at all layers - ✅ Use strict validation at all layers
- ✅ Add comprehensive logging and metrics - ✅ Add comprehensive logging and metrics
- ✅ Fix root causes, not symptoms - ✅ Fix root causes, not symptoms
- ✅ Always create feature branches from `v2-master-dev`
- ✅ Run `make validate` before pushing (100% coverage enforced)
## Key Files to Review ## Key Files to Review
### Planning Documents ### Planning Documents (Complete ✅)
- `docs/planning/00_V2_MASTER_PLAN.md` - Complete V2 architecture - `docs/planning/00_V2_MASTER_PLAN.md` - Complete V2 architecture
- `docs/planning/01_MODULARITY_REQUIREMENTS.md` - Component independence
- `docs/planning/02_PROTOCOL_SUPPORT_REQUIREMENTS.md` - 13+ DEX protocols
- `docs/planning/03_TESTING_REQUIREMENTS.md` - 100% coverage enforcement
- `docs/planning/04_PROFITABILITY_PLAN.md` - Sequencer strategy & ROI
- `docs/planning/05_CI_CD_SETUP.md` - Complete pipeline documentation
- `docs/planning/07_TASK_BREAKDOWN.md` - Atomic task list (99+ hours) - `docs/planning/07_TASK_BREAKDOWN.md` - Atomic task list (99+ hours)
- `orig/README_V1.md` - V1 documentation and known issues
### V2 Foundation (Complete ✅ - 100% Coverage)
- `pkg/types/` - Core types (SwapEvent, PoolInfo, errors)
- `pkg/parsers/` - Parser factory with routing
- `pkg/cache/` - Multi-index pool cache (O(1) lookups)
- `pkg/validation/` - Validation pipeline with rules
- `pkg/observability/` - Logging & Prometheus metrics
### V1 Reference Implementation ### V1 Reference Implementation
- `orig/pkg/events/parser.go` - Monolithic parser (to be replaced) - `orig/pkg/events/parser.go` - Monolithic parser (reference)
- `orig/pkg/monitor/concurrent.go` - Arbitrum monitor (to be enhanced) - `orig/pkg/monitor/concurrent.go` - Arbitrum monitor (reference)
- `orig/pkg/pools/discovery.go` - Pool discovery (cache to be multi-indexed) - `orig/pkg/pools/discovery.go` - Pool discovery (reference)
- `orig/pkg/arbitrage/detection_engine.go` - Arbitrage detection (to be improved) - `orig/pkg/arbitrage/detection_engine.go` - Arbitrage detection (reference)
### Documentation
- `README.md` - Project overview and quick start
- `CLAUDE.md` - This file (project guidance)
- `docs/V2_IMPLEMENTATION_STATUS.md` - Implementation progress
- `Makefile` - Build automation commands
- `.golangci.yml` - Linter configuration (40+ linters)
## Current Branches
### Production & Development
- **v2-master** - Production branch for V2 (protected, stable)
- **v2-master-dev** - Development branch for V2 (protected, stable)
- **feature/v2-prep** - Planning and foundation (archived, complete)
### Active Development Pattern
```bash
# Always branch from v2-master-dev
git checkout v2-master-dev
git pull origin v2-master-dev
git checkout -b feature/v2/<component>/<task-id>-<description>
# Merge back to v2-master-dev via PR
# Merge v2-master-dev to v2-master when ready for production
```
## Contact and Resources ## Contact and Resources
- V2 Planning: `docs/planning/` - **V2 Foundation:** `pkg/` (✅ Complete - 100% coverage)
- V1 Reference: `orig/` - **V2 Planning:** `docs/planning/` (✅ Complete - 7 documents)
- Architecture diagrams: In `00_V2_MASTER_PLAN.md` - **V1 Reference:** `orig/` (Frozen for reference)
- Task breakdown: In `07_TASK_BREAKDOWN.md` - **CI/CD:** `.github/workflows/v2-ci.yml` (✅ Configured)
- **Build Tools:** `Makefile` (✅ Ready - `make validate`)
- **Git Hooks:** `.git-hooks/` (✅ Install with `./scripts/install-git-hooks.sh`)
--- ---
**Current Phase**: V2 Planning **Current Phase:** ✅ V2 Foundation Complete (100% Coverage)
**Next Step**: Begin Phase 1 implementation (Foundation) **Next Step:** Phase 2 - Protocol Parser Implementations
**Estimated Time**: 12-13 weeks for complete V2 implementation **Foundation:** 3,300+ lines of code (1,500 implementation, 1,800 tests)
**Status:** Production-ready infrastructure, ready for parsers