[WIP] Add documentation for EigenPhi DEX State Tracker

[Copilot]

EigenPhi DEX State Tracker Documentation Plan

This PR adds comprehensive documentation for the EigenPhi DEX State Tracker project - a real-time Uniswap V2/V3/V4 pool state monitoring system built on Reth ExEx.

Checklist

• Create docs/eigenphi/ directory structure
• Create main README.md with project overview and navigation
• Create requirements documents:
  • 00-requirements/business-requirements.md
  • 00-requirements/technical-architecture.md
  • 00-requirements/data-model.md
• Create iteration plan documents:
  • 01-iteration-plan/overview.md
  • 01-iteration-plan/iteration-1-v2-monitoring.md
  • 01-iteration-plan/iteration-2-v3-ticks.md
  • 01-iteration-plan/iteration-3-storage-api.md
  • 01-iteration-plan/iteration-4-websocket-reorg.md
  • 01-iteration-plan/iteration-5-v4-production.md
• Create technical decision documents:
  • 02-technical-decisions/state-reading-strategy.md
  • 02-technical-decisions/constraint-calculation.md
  • 02-technical-decisions/reorg-handling.md
• Create implementation guides:
  • 03-implementation-guides/node-setup-sepolia.md
  • 03-implementation-guides/exex-development.md
  • 03-implementation-guides/api-specification.md
• Verify all documentation follows repository conventions
• Verify all internal links work correctly

Original prompt

Add EigenPhi DEX State Tracker Documentation

📋 Summary

Add comprehensive documentation for the EigenPhi DEX State Tracker project - a real-time Uniswap V2/V3/V4 pool state monitoring system built on Reth ExEx.

📁 New Files Structure

docs/eigenphi/
├── README.md                                    # Project overview
├── 00-requirements/
│   ├── business-requirements.md                 # Business requirements
│   ├── technical-architecture.md                # Technical architecture
│   └── data-model.md                            # Data model definitions
├── 01-iteration-plan/
│   ├── overview.md                              # Iteration overview
│   ├── iteration-1-v2-monitoring.md             # Iteration 1 plan
│   ├── iteration-2-v3-ticks.md                  # Iteration 2 plan
│   ├── iteration-3-storage-api.md               # Iteration 3 plan
│   ├── iteration-4-websocket-reorg.md           # Iteration 4 plan
│   └── iteration-5-v4-production.md             # Iteration 5 plan
├── 02-technical-decisions/
│   ├── state-reading-strategy.md                # Raw State reading strategy
│   ├── constraint-calculation.md                # Constraint State calculation
│   └── reorg-handling.md                        # Reorg handling approach
└── 03-implementation-guides/
    ├── node-setup-sepolia.md                    # Sepolia node setup guide
    ├── exex-development.md                      # ExEx development guide
    └── api-specification.md                     # API specification

📝 Documentation Content

1. Project Overview (README.md)

• System architecture diagram
• Core features and capabilities
• Tech stack (Reth + Lighthouse + ExEx + RocksDB + Redis)
• Quick start guide
• Document navigation

2. Requirements Documents

• business-requirements.md:

  • Real-time push requirements (WebSocket, Block-level)
  • Historical query requirements (HTTP API)
  • Supported protocols (V2/V3/V4)
  • Performance requirements (>99% capture rate, <500ms latency)

• technical-architecture.md:

  • Data flow: Event Listening → Raw State Reading → Constraint Calculation → Push/Store
  • Two-state model: Raw State (on-chain data) + Constraint State (mathematical curve abstraction)
  • Storage architecture: RocksDB (historical) + Redis (hot cache)

• data-model.md:

  • Complete Go struct definitions for all data types
  • Token metadata (including StorageKey for balance reading)
  • PoolCreatedAction, TransferAction, PoolAction
  • UniswapV2/V3/V4RawState structures
  • ConstraintState with 3 curve types (Linear, Hyperbolic, Weighted)
  • Push/Query message formats

3. Iteration Plan (5 iterations, 10-13 weeks total)

Iteration 1: V2 Monitoring (2-3 weeks)

• Setup Reth + Lighthouse on Sepolia
• Implement V2 event listening
• Read V2 Raw State from chain
• Generate placeholder Constraint State
• Output to logs

Iteration 2: V3 + Ticks (2-3 weeks)

• V3 event listening
• Read V3 Raw State (slot0, liquidity, ticks)
• Implement Tick range query (current ± N initialized ticks)
• Batch RPC call optimization
• Mixed V2+V3 push

Iteration 3: Storage + API (2 weeks)

• RocksDB persistent storage
• Redis hot cache
• HTTP REST API (health, single/batch pool query, stats)
• OpenAPI documentation
• Integration tests

Iteration 4: WebSocket + Reorg (2 weeks)

• WebSocket server with subscription model
• Block-level data push
• Reorg detection and handling
• Client reconnection and sync
• Prometheus metrics + Grafana dashboard

Iteration 5: V4 + Production (2-3 weeks)

• V4 Pool monitoring
• Real Constraint calculation algorithm integration
• Performance testing (500 Pool/Block capacity)
• Mainnet deployment preparation
• Complete documentation

4. Technical Decisions

State Reading Strategy:

• Option chosen: Full on-chain reading (not event-based)
• V2: getReserves()
• V3/V4: slot0() + liquidity() + ticks()
• Ensures 100% data accuracy

Constraint Calculation:

• Real-time calculation in ExEx (not API layer)
• Pure mathematical function (no external dependencies)
• Detailed algorithm to be provided later

Reorg Handling:

• Send reorg notification to clients
• Rollback RocksDB data
• Clear affected Redis cache
• Push new chain data

5. Implementation Guides

• Sepolia node setup (Docker Compose + systemd)
• ExEx development guide (project structure, event handling, state reading)
• API specification (endpoints, request/response formats, error handling)

🎯 Purpose

This documentation serves as:

1. Design reference for the entire project
2. Implementation guide for developers
3. Knowledge base for future iterations
4. Onboarding material for new team members

✅ Acceptance Criteria

• All documentation files created in docs/eigenphi/
• README with clear navigation structure
• Complete data model definitions (Go structs)
• Detailed 5-iteration plan with acceptance criteria
• Technical decision rationa...

This pull request was created as a result of the following prompt from Copilot chat.

Add EigenPhi DEX State Tracker Documentation

📋 Summary

Add comprehensive documentation for the EigenPhi DEX State Tracker project - a real-time Uniswap V2/V3/V4 pool state monitoring system built on Reth ExEx.

📁 New Files Structure

docs/eigenphi/
├── README.md                                    # Project overview
├── 00-requirements/
│   ├── business-requirements.md                 # Business requirements
│   ├── technical-architecture.md                # Technical architecture
│   └── data-model.md                            # Data model definitions
├── 01-iteration-plan/
│   ├── overview.md                              # Iteration overview
│   ├── iteration-1-v2-monitoring.md             # Iteration 1 plan
│   ├── iteration-2-v3-ticks.md                  # Iteration 2 plan
│   ├── iteration-3-storage-api.md               # Iteration 3 plan
│   ├── iteration-4-websocket-reorg.md           # Iteration 4 plan
│   └── iteration-5-v4-production.md             # Iteration 5 plan
├── 02-technical-decisions/
│   ├── state-reading-strategy.md                # Raw State reading strategy
│   ├── constraint-calculation.md                # Constraint State calculation
│   └── reorg-handling.md                        # Reorg handling approach
└── 03-implementation-guides/
    ├── node-setup-sepolia.md                    # Sepolia node setup guide
    ├── exex-development.md                      # ExEx development guide
    └── api-specification.md                     # API specification

📝 Documentation Content

1. Project Overview (README.md)

• System architecture diagram
• Core features and capabilities
• Tech stack (Reth + Lighthouse + ExEx + RocksDB + Redis)
• Quick start guide
• Document navigation

2. Requirements Documents

• business-requirements.md:

  • Real-time push requirements (WebSocket, Block-level)
  • Historical query requirements (HTTP API)
  • Supported protocols (V2/V3/V4)
  • Performance requirements (>99% capture rate, <500ms latency)

• technical-architecture.md:

  • Data flow: Event Listening → Raw State Reading → Constraint Calculation → Push/Store
  • Two-state model: Raw State (on-chain data) + Constraint State (mathematical curve abstraction)
  • Storage architecture: RocksDB (historical) + Redis (hot cache)

• data-model.md:

  • Complete Go struct definitions for all data types
  • Token metadata (including StorageKey for balance reading)
  • PoolCreatedAction, TransferAction, PoolAction
  • UniswapV2/V3/V4RawState structures
  • ConstraintState with 3 curve types (Linear, Hyperbolic, Weighted)
  • Push/Query message formats

3. Iteration Plan (5 iterations, 10-13 weeks total)

Iteration 1: V2 Monitoring (2-3 weeks)

• Setup Reth + Lighthouse on Sepolia
• Implement V2 event listening
• Read V2 Raw State from chain
• Generate placeholder Constraint State
• Output to logs

Iteration 2: V3 + Ticks (2-3 weeks)

• V3 event listening
• Read V3 Raw State (slot0, liquidity, ticks)
• Implement Tick range query (current ± N initialized ticks)
• Batch RPC call optimization
• Mixed V2+V3 push

Iteration 3: Storage + API (2 weeks)

• RocksDB persistent storage
• Redis hot cache
• HTTP REST API (health, single/batch pool query, stats)
• OpenAPI documentation
• Integration tests

Iteration 4: WebSocket + Reorg (2 weeks)

• WebSocket server with subscription model
• Block-level data push
• Reorg detection and handling
• Client reconnection and sync
• Prometheus metrics + Grafana dashboard

Iteration 5: V4 + Production (2-3 weeks)

• V4 Pool monitoring
• Real Constraint calculation algorithm integration
• Performance testing (500 Pool/Block capacity)
• Mainnet deployment preparation
• Complete documentation

4. Technical Decisions

State Reading Strategy:

• Option chosen: Full on-chain reading (not event-based)
• V2: getReserves()
• V3/V4: slot0() + liquidity() + ticks()
• Ensures 100% data accuracy

Constraint Calculation:

• Real-time calculation in ExEx (not API layer)
• Pure mathematical function (no external dependencies)
• Detailed algorithm to be provided later

Reorg Handling:

• Send reorg notification to clients
• Rollback RocksDB data
• Clear affected Redis cache
• Push new chain data

5. Implementation Guides

• Sepolia node setup (Docker Compose + systemd)
• ExEx development guide (project structure, event handling, state reading)
• API specification (endpoints, request/response formats, error handling)

🎯 Purpose

This documentation serves as:

1. Design reference for the entire project
2. Implementation guide for developers
3. Knowledge base for future iterations
4. Onboarding material for new team members

✅ Acceptance Criteria

• All documentation files created in docs/eigenphi/
• README with clear navigation structure
• Complete data model definitions (Go structs)
• Detailed 5-iteration plan with acceptance criteria
• Technical decision rationale documented
• Implementation guides ready for development

📅 Timeline

• Documentation Date: 2024-12-21
• Author: hitdavid
• Next Step: Begin Iteration 1 implementation

🔗 Related Issues

N/A - This is the initial documentation PR

---

Note: The actual Constraint State calculation algorithm will be provided in a future iteration. Current documentation uses placeholder descriptions.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.