fix(critical): complete execution pipeline - all blockers fixed and operational

2025-11-04 10:24:34 -06:00
parent 0b1c7bbc86
commit 52d555ccdf
410 changed files with 99504 additions and 28488 deletions
--- a/docs/TOKEN_PAIRS_LIST.md
+++ b/docs/TOKEN_PAIRS_LIST.md
@@ -0,0 +1,269 @@
+# Token Pairs Being Monitored - Complete List
+
+## Summary
+
+The MEV bot discovers pools for **45 unique token pairs** across **10 major Arbitrum tokens**, resulting in **50-60+ individual pools** when accounting for multiple DEXes and fee tiers per pair.
+
+---
+
+## The 10 Tokens
+
+| # | Symbol | Name | Address (Arbitrum) | Type |
+|---|--------|------|--------------------|------|
+| 1 | WETH | Wrapped Ether | 0x82af49447d8a07e3bd95bd0d56f35241523fbab1 | Base Asset |
+| 2 | USDC | USD Coin | 0xaf88d065e77c8cc2239327c5edb3a432268e5831 | Stablecoin |
+| 3 | USDT | Tether | 0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9 | Stablecoin |
+| 4 | ARB | Arbitrum | 0x912ce59144191c1204e64559fe8253a0e49e6548 | Governance |
+| 5 | WBTC | Wrapped Bitcoin | 0x2f2a2543b76a4166549f7aab2e75bef0aefc5b0f | BTC Proxy |
+| 6 | DAI | Dai Stablecoin | 0xda10009cbd5d07dd0cecc66161fc93d7c9000da1 | Stablecoin |
+| 7 | LINK | Chainlink | 0xf97f4df75117a78c1a5a0dbb814af92458539fb4 | Oracle |
+| 8 | UNI | Uniswap | 0xfa7f8980b0f1e64a2062791cc3b0871572f1f7f0 | Governance |
+| 9 | GMX | GMX | 0xfc5a1a6eb076a2c7ad06ed22c90d7e710e35ad0a | Perps |
+| 10 | GRT | The Graph | 0x9623063377ad1b27544c965ccd7342f7ea7e88c7 | Indexing |
+
+---
+
+## All 45 Token Pairs
+
+### WETH Pairs (9)
+1. **WETH/USDC** ⭐ - Highest volume pair
+2. **WETH/USDT** ⭐ - High volume
+3. **WETH/ARB** ⭐ - Arbitrum native
+4. **WETH/WBTC** ⭐ - BTC-ETH correlation
+5. WETH/DAI
+6. WETH/LINK
+7. WETH/UNI
+8. **WETH/GMX** ⭐ - Popular on Arbitrum
+9. WETH/GRT
+
+### USDC Pairs (8)
+10. **USDC/USDT** ⭐ - Stablecoin arbitrage
+11. **USDC/ARB** ⭐ - High volume
+12. USDC/WBTC
+13. **USDC/DAI** ⭐ - Stablecoin trio
+14. USDC/LINK
+15. USDC/UNI
+16. **USDC/GMX** ⭐ - GMX liquidity
+17. USDC/GRT
+
+### USDT Pairs (7)
+18. **USDT/ARB** ⭐ - High volume
+19. USDT/WBTC
+20. **USDT/DAI** ⭐ - Stablecoin arbitrage
+21. USDT/LINK
+22. USDT/UNI
+23. USDT/GMX
+24. USDT/GRT
+
+### ARB Pairs (6)
+25. ARB/WBTC
+26. ARB/DAI
+27. ARB/LINK
+28. ARB/UNI
+29. **ARB/GMX** ⭐ - Both Arbitrum natives
+30. ARB/GRT
+
+### WBTC Pairs (5)
+31. WBTC/DAI
+32. WBTC/LINK
+33. WBTC/UNI
+34. WBTC/GMX
+35. WBTC/GRT
+
+### DAI Pairs (4)
+36. DAI/LINK
+37. DAI/UNI
+38. DAI/GMX
+39. DAI/GRT
+
+### LINK Pairs (3)
+40. LINK/UNI
+41. LINK/GMX
+42. LINK/GRT
+
+### UNI Pairs (2)
+43. UNI/GMX
+44. UNI/GRT
+
+### GMX Pairs (1)
+45. GMX/GRT
+
+---
+
+## Why 50+ Pools from 45 Pairs?
+
+Each token pair can have **multiple pools** across different:
+
+### 1. DEX Protocols (6)
+- **Uniswap V3** - Concentrated liquidity
+- **Uniswap V2** - Classic AMM
+- **SushiSwap** - Fork of V2
+- **Camelot** - Arbitrum-native DEX
+- **Curve** - Optimized for stablecoins
+- **Balancer** - Multi-asset pools
+
+### 2. Fee Tiers (Uniswap V3)
+- **0.05%** - Stablecoin pairs
+- **0.3%** - Most pairs (standard)
+- **1%** - Exotic/volatile pairs
+
+### Example: WETH/USDC Pools
+```
+Token Pair: WETH/USDC
+├─ Uniswap V3 (0.05% fee) → Pool #1
+├─ Uniswap V3 (0.3% fee)  → Pool #2
+├─ Uniswap V3 (1% fee)    → Pool #3
+├─ SushiSwap              → Pool #4
+└─ Camelot                → Pool #5
+
+Result: 1 pair = 5 pools
+```
+
+---
+
+## High-Priority Pairs (⭐)
+
+These pairs typically have the highest liquidity and trading volume:
+
+| Rank | Pair | Why High Priority |
+|------|------|-------------------|
+| 1 | WETH/USDC | Highest volume, tightest spreads |
+| 2 | WETH/USDT | Second highest volume |
+| 3 | WETH/ARB | Native token, high activity |
+| 4 | USDC/USDT | Stablecoin arbitrage opportunities |
+| 5 | USDC/ARB | High ARB trading volume |
+| 6 | USDC/DAI | Stablecoin triangular arbitrage |
+| 7 | USDT/DAI | Additional stablecoin route |
+| 8 | WETH/WBTC | BTC-ETH correlation trades |
+| 9 | WETH/GMX | GMX is popular on Arbitrum |
+| 10 | USDC/GMX | GMX primary liquidity |
+
+---
+
+## Discovery Process
+
+### CREATE2 Calculation
+For each token pair, the bot:
+1. Calculates deterministic pool addresses using CREATE2
+2. Checks all 6 DEX factory contracts
+3. Validates pools exist on-chain
+4. Fetches pool metadata (reserves, liquidity)
+5. Caches valid pools to `data/pools.json`
+
+### Pool Validation
+```go
+// For each token pair
+for i := 0; i < len(tokenList); i++ {
+    for j := i + 1; j < len(tokenList); j++ {
+        // Discover all pools for this pair across all DEXes
+        pools := DiscoverPoolsForTokenPair(token0, token1)
+
+        // Could find 1-5 pools per pair
+    }
+}
+```
+
+---
+
+## Expected Pool Distribution
+
+| Pool Type | Count | Notes |
+|-----------|-------|-------|
+| Uniswap V3 (0.3%) | 20-25 | Most common |
+| Uniswap V3 (0.05%) | 8-10 | Stablecoin pairs |
+| Uniswap V3 (1%) | 3-5 | Volatile pairs |
+| SushiSwap | 10-12 | Popular pairs |
+| Camelot | 8-10 | Arbitrum native |
+| Curve | 2-3 | Stablecoin only |
+| **Total** | **50-65** | Varies by liquidity |
+
+---
+
+## Arbitrage Opportunities
+
+### Two-Hop Arbitrage
+Example: Price divergence between DEXes
+```
+Buy WETH on Uniswap V3 (0.3%) → Sell WETH on SushiSwap
+```
+
+### Triangular Arbitrage
+Example: Multi-hop with price inefficiencies
+```
+USDC → WETH (Uniswap) → ARB (Camelot) → USDC (SushiSwap)
+```
+
+### Stablecoin Arbitrage
+Example: Peg deviation trading
+```
+USDC → USDT (Curve 0.05%) → DAI (Uniswap) → USDC (SushiSwap)
+```
+
+---
+
+## Monitoring Strategy
+
+### Real-Time
+- Listen for swap events on all 50+ pools
+- Calculate price divergences across DEXes
+- Detect arbitrage opportunities instantly
+
+### Periodic
+- Re-discover pools every 24 hours
+- Update pool metadata (reserves, liquidity)
+- Remove inactive/deprecated pools
+
+### Dynamic
+- Add new tokens as they gain volume
+- Monitor for new pool deployments
+- Adjust based on profitability data
+
+---
+
+## Mathematical Proof
+
+**Combination Formula**:
+```
+C(n,k) = n! / (k! × (n-k)!)
+
+For 10 tokens, choosing 2 at a time:
+C(10,2) = 10! / (2! × 8!)
+        = (10 × 9) / (2 × 1)
+        = 45 unique pairs
+```
+
+**Pool Multiplier**:
+```
+45 pairs × 1.2 average pools per pair = ~54 pools
+(Some pairs have 1 pool, some have 3-5)
+```
+
+---
+
+## Future Expansion
+
+### Short Term
+- Add 5 more tokens (60 pairs → 75+ pools)
+- Include Arbitrum Nova pairs
+- Monitor USDC.e (bridged USDC) separately
+
+### Long Term
+- Cross-chain pairs (Arbitrum ↔ Ethereum)
+- Exotic pairs with lower volume
+- LP token arbitrage
+- Options protocol integration
+
+---
+
+## References
+
+- **Code**: `cmd/mev-bot/main.go:256-323`
+- **Token Addresses**: `internal/tokens/arbitrum.go`
+- **Pool Discovery**: `pkg/pools/discovery.go`
+- **CREATE2 Calculation**: `pkg/pools/create2.go`
+
+---
+
+**Last Updated**: October 30, 2025
+**Pool Count**: 45 pairs → 50-60+ pools
+**Status**: Active Discovery Implemented