docs: add flash loan, binding, and testing documentation
Additional documentation and testing infrastructure: ## Documentation Added - PROFIT_ROADMAP.md - 4-week profitability roadmap - PRODUCTION_DEPLOYMENT.md - Production deployment guide - docs/FLASH_LOAN_DEPLOYMENT_GUIDE.md - Flash loan implementation - docs/FLASH_LOAN_IMPLEMENTATION_SUMMARY.md - Flash loan summary - docs/BINDING_CONSISTENCY_GUIDE.md - Contract binding guidelines - docs/BINDING_QUICK_START.md - Quick start for bindings - docs/COMPLETE_FORK_TESTING_GUIDE.md - Fork testing guide ## Testing Scripts Added - scripts/generate-test-report.sh - Generate test reports - scripts/monitor-24h-test.sh - 24-hour monitoring - scripts/start-24h-test.sh - Start long-running tests - scripts/stop-24h-test.sh - Stop test runs 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Krypto Kajun
348
docs/BINDING_QUICK_START.md
Normal file
348
docs/BINDING_QUICK_START.md
Normal file
@@ -0,0 +1,348 @@
|
||||
# Quick Start: Contract Binding Consistency
|
||||
|
||||
## Immediate Action Items
|
||||
|
||||
### 1. Compile Mev-Alpha Contracts
|
||||
|
||||
```bash
|
||||
cd /home/administrator/projects/Mev-Alpha
|
||||
forge clean
|
||||
forge build
|
||||
|
||||
# This will create out/ directory with compiled artifacts
|
||||
```
|
||||
|
||||
**Note**: Compilation may take 2-3 minutes due to 108 dependencies.
|
||||
|
||||
### 2. Generate Go Bindings
|
||||
|
||||
Once compilation completes:
|
||||
|
||||
```bash
|
||||
cd /home/administrator/projects/mev-beta
|
||||
./scripts/generate-bindings.sh
|
||||
```
|
||||
|
||||
This script will:
|
||||
- Verify compiled artifacts exist
|
||||
- Generate Go bindings using `abigen`
|
||||
- Organize bindings by type (contracts, interfaces, utils, dex)
|
||||
- Create address constants file
|
||||
- Backup existing bindings
|
||||
|
||||
### 3. Verify Bindings
|
||||
|
||||
```bash
|
||||
# Check generated files
|
||||
ls -la bindings/
|
||||
|
||||
# Verify they compile
|
||||
go build ./bindings/...
|
||||
|
||||
# Run go mod tidy
|
||||
go mod tidy
|
||||
```
|
||||
|
||||
## Current Binding Inventory
|
||||
|
||||
### ✅ Existing Bindings (May Need Update)
|
||||
|
||||
Located in `/home/administrator/projects/mev-beta/bindings/`:
|
||||
|
||||
```
|
||||
bindings/
|
||||
├── contracts/
|
||||
│ ├── arbitrageexecutor.go # ArbitrageExecutor contract
|
||||
│ ├── baseflashswapper.go # Base flash swapper
|
||||
│ ├── uniswapv2flashswapper.go # Uniswap V2 flash swapper
|
||||
│ ├── uniswapv3flashswapper.go # Uniswap V3 flash swapper
|
||||
│ ├── dexmath.go # DEX math library
|
||||
│ └── shared_types.go # Shared type definitions
|
||||
├── interfaces/
|
||||
│ ├── arbitrage.go # IArbitrage interface
|
||||
│ └── flash_swapper.go # IFlashSwapper interface
|
||||
├── tokens/
|
||||
│ ├── ierc20.go # ERC20 interface
|
||||
│ ├── iuniswapv2pair.go # Uniswap V2 pair
|
||||
│ └── iuniswapv3pool*.go # Uniswap V3 pool interfaces
|
||||
└── uniswap/
|
||||
├── uniswap_v2_pair.go # V2 pair binding
|
||||
└── uniswap_v3_pool_*.go # V3 pool bindings
|
||||
```
|
||||
|
||||
### 📋 Contracts in Mev-Alpha (Source of Truth)
|
||||
|
||||
Located in `/home/administrator/projects/Mev-Alpha/src/`:
|
||||
|
||||
```
|
||||
src/
|
||||
├── core/
|
||||
│ ├── ArbitrageExecutor.sol ✅ Has binding
|
||||
│ ├── BaseFlashSwapper.sol ✅ Has binding
|
||||
│ ├── DataFetcher.sol ⚠️ Needs binding
|
||||
│ ├── PriceOracle.sol ⚠️ Needs binding
|
||||
│ └── liquidation/
|
||||
│ └── AaveLiquidator.sol ⚠️ Needs binding
|
||||
├── dex/
|
||||
│ ├── UniswapV2FlashSwapper.sol ✅ Has binding
|
||||
│ └── UniswapV3FlashSwapper.sol ✅ Has binding
|
||||
├── interfaces/
|
||||
│ ├── IArbitrage.sol ✅ Has binding
|
||||
│ ├── IFlashSwapper.sol ✅ Has binding
|
||||
│ ├── IDataFetcher.sol ⚠️ Needs binding
|
||||
│ └── IERC165.sol ⚠️ Needs binding
|
||||
├── libraries/
|
||||
│ ├── DEXMath.sol ✅ Has binding
|
||||
│ ├── ProfitCalculator.sol ⚠️ Needs binding
|
||||
│ ├── UniswapV3Math.sol ⚠️ Needs binding
|
||||
│ ├── CurveMath.sol ⚠️ Needs binding
|
||||
│ ├── BalancerMath.sol ⚠️ Needs binding
|
||||
│ └── AlgebraMath.sol ⚠️ Needs binding
|
||||
└── utils/
|
||||
├── GasOptimizer.sol ⚠️ Needs binding
|
||||
├── MulticallUtils.sol ⚠️ Needs binding
|
||||
└── TokenUtils.sol ⚠️ Needs binding
|
||||
```
|
||||
|
||||
**Legend**:
|
||||
- ✅ Has binding: Binding exists in mev-beta
|
||||
- ⚠️ Needs binding: No binding found or may be outdated
|
||||
|
||||
## Files Using Manual ABI Calls (Need Refactoring)
|
||||
|
||||
### High Priority
|
||||
|
||||
1. **`pkg/uniswap/contracts.go`** (548 lines)
|
||||
- Manual ABI packing for slot0(), liquidity(), token0(), token1(), fee()
|
||||
- Replace with: `bindings/tokens.IUniswapV3Pool` binding
|
||||
- Impact: Core pool interaction logic
|
||||
|
||||
2. **`pkg/arbitrum/abi_decoder.go`** (Critical for transaction parsing)
|
||||
- Manual Keccak256 hashing for function selectors
|
||||
- Manual ABI unpacking for swap parameters
|
||||
- Partial refactor: Use bindings for known contracts, keep manual parsing for unknown/multi-protocol
|
||||
|
||||
3. **`pkg/events/parser.go`**
|
||||
- Event signature hashing
|
||||
- Replace with: Binding event filters and parsers
|
||||
|
||||
### Medium Priority
|
||||
|
||||
4. **`pkg/calldata/swaps.go`**
|
||||
- Swap data encoding
|
||||
- Use binding methods instead
|
||||
|
||||
5. **`pkg/arbitrum/parser/core.go`**
|
||||
- Transaction parsing
|
||||
- Integrate with bindings
|
||||
|
||||
6. **`pkg/pools/create2.go`**
|
||||
- Pool address calculation
|
||||
- Keep as-is (doesn't require bindings)
|
||||
|
||||
### Low Priority (Keep As-Is)
|
||||
|
||||
7. **`pkg/common/selectors/selectors.go`** ✅ KEEP
|
||||
- Centralized selector definitions
|
||||
- Useful for quick lookups and validation
|
||||
- Don't require changes
|
||||
|
||||
## Refactoring Example
|
||||
|
||||
### Before (Manual ABI)
|
||||
|
||||
```go
|
||||
// pkg/uniswap/contracts.go (current)
|
||||
func (p *UniswapV3Pool) callSlot0(ctx context.Context) (*Slot0Data, error) {
|
||||
data, err := p.abi.Pack("slot0")
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("failed to pack slot0 call: %w", err)
|
||||
}
|
||||
|
||||
msg := ethereum.CallMsg{
|
||||
To: &p.address,
|
||||
Data: data,
|
||||
}
|
||||
|
||||
result, err := p.client.CallContract(ctx, msg, nil)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("failed to call slot0: %w", err)
|
||||
}
|
||||
|
||||
unpacked, err := p.abi.Unpack("slot0", result)
|
||||
// ... manual unpacking logic
|
||||
}
|
||||
```
|
||||
|
||||
### After (Using Bindings)
|
||||
|
||||
```go
|
||||
// pkg/uniswap/contracts.go (refactored)
|
||||
import (
|
||||
"github.com/yourusername/mev-beta/bindings/tokens"
|
||||
"github.com/ethereum/go-ethereum/accounts/abi/bind"
|
||||
)
|
||||
|
||||
func (p *UniswapV3Pool) callSlot0(ctx context.Context) (*Slot0Data, error) {
|
||||
pool, err := tokens.NewIUniswapV3PoolState(p.address, p.client)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("failed to create pool binding: %w", err)
|
||||
}
|
||||
|
||||
slot0, err := pool.Slot0(&bind.CallOpts{Context: ctx})
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("failed to call slot0: %w", err)
|
||||
}
|
||||
|
||||
return &Slot0Data{
|
||||
SqrtPriceX96: uint256.MustFromBig(slot0.SqrtPriceX96),
|
||||
Tick: int(slot0.Tick.Int64()),
|
||||
// ... use typed struct fields directly
|
||||
}, nil
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- 50% less code
|
||||
- Type-safe (compile-time errors instead of runtime)
|
||||
- Auto-completion in IDE
|
||||
- Handles ABI changes automatically on regeneration
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### 1. Unit Tests
|
||||
|
||||
```bash
|
||||
# Test each refactored package
|
||||
go test ./pkg/uniswap -v
|
||||
go test ./pkg/arbitrum -v
|
||||
go test ./pkg/events -v
|
||||
```
|
||||
|
||||
### 2. Integration Tests
|
||||
|
||||
```bash
|
||||
# Test against Arbitrum testnet
|
||||
export ARBITRUM_RPC_ENDPOINT="https://sepolia-rollup.arbitrum.io/rpc"
|
||||
export ARBITRUM_WS_ENDPOINT="wss://sepolia-rollup.arbitrum.io/ws"
|
||||
|
||||
go test ./pkg/... -tags=integration -v
|
||||
```
|
||||
|
||||
### 3. Build Validation
|
||||
|
||||
```bash
|
||||
# Ensure everything compiles
|
||||
cd /home/administrator/projects/mev-beta
|
||||
go mod tidy
|
||||
go build ./...
|
||||
|
||||
# Run the bot with --dry-run to validate
|
||||
./mev-bot start --dry-run
|
||||
```
|
||||
|
||||
## Common Issues & Solutions
|
||||
|
||||
### Issue: abigen not found
|
||||
|
||||
```bash
|
||||
# Install abigen
|
||||
go install github.com/ethereum/go-ethereum/cmd/abigen@latest
|
||||
|
||||
# Verify installation
|
||||
which abigen
|
||||
abigen --version
|
||||
```
|
||||
|
||||
### Issue: jq command not found
|
||||
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt-get update && sudo apt-get install -y jq
|
||||
|
||||
# macOS
|
||||
brew install jq
|
||||
```
|
||||
|
||||
### Issue: Compilation errors after binding update
|
||||
|
||||
```bash
|
||||
# Clear Go cache
|
||||
go clean -cache -modcache -testcache
|
||||
|
||||
# Re-download dependencies
|
||||
go mod tidy
|
||||
go mod download
|
||||
|
||||
# Rebuild
|
||||
go build ./...
|
||||
```
|
||||
|
||||
### Issue: Binding mismatch with deployed contract
|
||||
|
||||
**Solution**: Ensure you're using the correct contract version:
|
||||
|
||||
1. Check deployed contract address
|
||||
2. Verify ABI matches on Arbiscan
|
||||
3. Regenerate bindings from correct source
|
||||
4. Update address in `bindings/addresses.go`
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Binding Size
|
||||
|
||||
Generated bindings can be large (10-30KB per contract). This is normal and doesn't impact runtime performance.
|
||||
|
||||
### Compilation Time
|
||||
|
||||
Initial `go build` after generating bindings may take 30-60 seconds due to:
|
||||
- ABI parsing
|
||||
- Type generation
|
||||
- Method generation
|
||||
|
||||
Subsequent builds use Go's build cache and are much faster.
|
||||
|
||||
## Next Steps After Binding Generation
|
||||
|
||||
1. **Update imports**: Replace manual ABI imports with binding imports
|
||||
2. **Refactor pkg/uniswap**: Highest impact, most direct mapping
|
||||
3. **Refactor pkg/arbitrum**: Careful - keep flexibility for multi-protocol
|
||||
4. **Add tests**: Unit tests for each refactored function
|
||||
5. **Integration test**: End-to-end arbitrage detection
|
||||
6. **Document changes**: Update code comments and docs
|
||||
7. **Performance test**: Ensure no regression in transaction processing
|
||||
|
||||
## Useful Commands
|
||||
|
||||
```bash
|
||||
# Find all manual ABI packing calls
|
||||
grep -r "abi\.Pack\|abi\.Unpack" pkg/ --exclude-dir=test -n
|
||||
|
||||
# Find all Keccak256 selector computations
|
||||
grep -r "crypto\.Keccak256" pkg/ --exclude-dir=test -n
|
||||
|
||||
# Count binding files
|
||||
find bindings/ -name "*.go" | wc -l
|
||||
|
||||
# Check binding package imports
|
||||
go list -f '{{join .Imports "\n"}}' ./bindings/... | sort -u
|
||||
|
||||
# Validate all Go files compile
|
||||
gofmt -l pkg/ bindings/
|
||||
|
||||
# Run static analysis
|
||||
go vet ./...
|
||||
golangci-lint run
|
||||
```
|
||||
|
||||
## Support & References
|
||||
|
||||
- **Comprehensive Guide**: See `docs/BINDING_CONSISTENCY_GUIDE.md`
|
||||
- **abigen Documentation**: https://geth.ethereum.org/docs/tools/abigen
|
||||
- **Foundry Build**: https://book.getfoundry.sh/reference/forge/forge-build
|
||||
- **Go-Ethereum Bindings**: https://pkg.go.dev/github.com/ethereum/go-ethereum/accounts/abi/bind
|
||||
|
||||
---
|
||||
|
||||
**Status**: Ready to Execute
|
||||
**Next Action**: Run `forge build` in Mev-Alpha directory
|
||||
Reference in New Issue
Block a user