mev-beta/TODO_BINDING_MIGRATION.md

Contract Binding Migration - Action Plan

Created: 2025-10-26 Status: Ready to Execute Priority: High - Ensures type safety and maintainability

Executive Summary

The mev-beta Go bot currently uses a mix of:

• Generated Go bindings (partially outdated)
• Manual ABI packing/unpacking
• Manual function selector computation

This creates risks of:

• Type mismatches
• Runtime errors from ABI changes
• Maintenance overhead
• Missed contract updates

Solution: Generate fresh bindings from Mev-Alpha Solidity contracts and refactor to use them consistently.

Phase 1: Binding Generation ✅ READY

Prerequisites

• Foundry installed (forge 1.0.0-stable)
• abigen installed (/home/administrator/go/bin/abigen)
• jq installed (for JSON parsing)
• Mev-Alpha contracts available (/home/administrator/projects/Mev-Alpha)

Scripts Created

• /home/administrator/projects/mev-beta/scripts/generate-bindings.sh
  • Compiles Solidity contracts
  • Generates Go bindings for all contracts
  • Organizes by package (contracts, interfaces, utils, dex)
  • Creates backup of existing bindings
  • Generates address constants

Execution Steps

# Step 1: Compile Mev-Alpha contracts (2-3 minutes)
cd /home/administrator/projects/Mev-Alpha
forge clean
forge build

# Step 2: Generate bindings (1-2 minutes)
cd /home/administrator/projects/mev-beta
./scripts/generate-bindings.sh

# Step 3: Verify (30 seconds)
go build ./bindings/...
go mod tidy

Phase 2: Code Refactoring 🔄 PENDING

Priority 1: pkg/uniswap/contracts.go (High Impact)

Lines to Refactor: 155-548 (393 lines)

Current Issues:

• Manual abi.Pack() for slot0, liquidity, token0, token1, fee
• Manual abi.Unpack() and type conversions
• Error-prone unpacking logic

Refactoring Strategy:

// Before
data, _ := p.abi.Pack("slot0")
result, _ := p.client.CallContract(ctx, msg, nil)
unpacked, _ := p.abi.Unpack("slot0", result)

// After
import "github.com/yourusername/mev-beta/bindings/tokens"
pool, _ := tokens.NewIUniswapV3PoolState(address, client)
slot0, _ := pool.Slot0(&bind.CallOpts{Context: ctx})

Estimated Effort: 2-3 hours Risk: Low - Direct mapping, well-tested interface

Test Plan:

• Unit tests for each function (slot0, liquidity, etc.)
• Integration test with Arbitrum testnet
• Mainnet fork test for realistic data

Priority 2: pkg/arbitrum/abi_decoder.go (Medium Impact)

Lines to Review: 1-2000+ (large file)

Current Issues:

• Manual Keccak256 for function selectors
• Custom ABI decoding for multiple protocols
• Complex multicall parsing

Refactoring Strategy:

1. Keep manual parsing for:

   • Unknown/unverified contracts
   • Multi-protocol aggregation
   • Edge cases not covered by bindings

2. Replace with bindings for:

   • Known Uniswap V2/V3 calls
   • Standard ERC20 operations
   • Verified protocol contracts

Estimated Effort: 4-6 hours Risk: Medium - Must preserve multi-protocol flexibility

Test Plan:

• Test against 1000+ real Arbitrum transactions
• Verify multicall parsing accuracy
• Ensure backward compatibility

Priority 3: pkg/events/parser.go (Medium Impact)

Current Issues:

• Manual event signature hashing
• Custom event parsing logic

Refactoring Strategy:

// Before
sig := crypto.Keccak256Hash([]byte("Swap(address,uint256,uint256)"))

// After
import "github.com/yourusername/mev-beta/bindings/contracts"
event, _ := binding.ParseSwap(log)

Estimated Effort: 2-3 hours Risk: Low - Event parsing is well-structured

Priority 4: pkg/calldata/swaps.go (Low Impact)

Estimated Effort: 1-2 hours Risk: Low

Priority 5: Other Files (Low Impact)

Files with minimal manual ABI usage:

• pkg/arbitrum/parser/core.go
• pkg/arbitrum/swap_pipeline.go
• pkg/oracle/price_oracle.go

Estimated Effort: 2-3 hours total Risk: Low

Phase 3: Testing & Validation 🧪 PENDING

Test Coverage Requirements

• Unit tests for all refactored functions (>90% coverage)
• Integration tests against Arbitrum testnet
• Fork tests with mainnet data
• Performance benchmarks (no regression)
• Error handling tests

Validation Checklist

• All manual abi.Pack() calls reviewed
• All crypto.Keccak256 selector calls reviewed
• Type conversions validated
• Error messages preserved/improved
• Logging preserved
• Performance maintained or improved

Regression Prevention

# Before refactoring - capture baseline
go test ./pkg/... -bench=. -benchmem > baseline.txt

# After refactoring - compare
go test ./pkg/... -bench=. -benchmem > refactored.txt
benchstat baseline.txt refactored.txt

Phase 4: Documentation 📚 IN PROGRESS

Documentation Status

• docs/BINDING_CONSISTENCY_GUIDE.md - Comprehensive guide
• docs/BINDING_QUICK_START.md - Quick reference
• TODO_BINDING_MIGRATION.md - This file
• Update pkg/*/README.md files
• Update CLAUDE.md with binding patterns
• Create migration changelog

Timeline Estimates

Phase	Tasks	Estimated Time	Status
Phase 1	Binding Generation	30 minutes	✅ Ready
Phase 2.1	pkg/uniswap refactor	2-3 hours	🔄 Pending
Phase 2.2	pkg/arbitrum refactor	4-6 hours	🔄 Pending
Phase 2.3	pkg/events refactor	2-3 hours	🔄 Pending
Phase 2.4	Other refactors	3-5 hours	🔄 Pending
Phase 3	Testing	4-6 hours	🔄 Pending
Phase 4	Documentation	2-3 hours	🟡 In Progress
TOTAL		18-26 hours

Risk Assessment

High Risks

• ABI Mismatch: Bindings don't match deployed contracts

  • Mitigation: Verify contract addresses and ABIs on Arbiscan
  • Detection: Integration tests against real contracts

• Type Conversion Errors: *big.Int to uint256, etc.

  • Mitigation: Comprehensive unit tests
  • Detection: Runtime validation and bounds checking

Medium Risks

• Performance Regression: Binding overhead vs. manual calls

  • Mitigation: Benchmark tests
  • Detection: Continuous performance monitoring

• Breaking Changes: Refactor breaks existing functionality

  • Mitigation: Comprehensive test suite first
  • Detection: CI/CD pipeline validation

Low Risks

• Compilation Issues: Go build failures
  • Mitigation: Incremental changes, frequent builds
  • Detection: Immediate (compile-time)

Success Criteria

Phase 1 Complete When:

• All Mev-Alpha contracts compile successfully
• Go bindings generated for all contracts
• Bindings compile without errors
• go mod tidy completes successfully

Phase 2 Complete When:

• <5 instances of manual abi.Pack() remain (only where necessary)
• All contract interactions use typed bindings
• Code review approved
• No new golangci-lint warnings

Phase 3 Complete When:

• >90% test coverage on refactored code
• All integration tests pass
• Performance benchmarks show no regression
• Fork tests pass against mainnet data

Phase 4 Complete When:

• All documentation updated
• Migration guide complete
• Code examples provided
• CHANGELOG.md updated

Rollback Plan

If critical issues are discovered:

1. Immediate Rollback (5 minutes):

   cd /home/administrator/projects/mev-beta
   rm -rf bindings/
   cp -r bindings_backup_YYYYMMDD_HHMMSS/ bindings/
   git checkout -- pkg/
   

2. Partial Rollback (per file):

   git checkout -- pkg/uniswap/contracts.go
   

3. Investigation:

   • Review failed tests
   • Check contract addresses
   • Verify ABI versions
   • Consult logs

Next Immediate Actions

1. NOW: Run forge build in Mev-Alpha

   cd /home/administrator/projects/Mev-Alpha
   forge build
   

2. AFTER BUILD: Run binding generation

   cd /home/administrator/projects/mev-beta
   ./scripts/generate-bindings.sh
   

3. VERIFY: Check bindings compile

   go build ./bindings/...
   

4. BEGIN REFACTOR: Start with pkg/uniswap/contracts.go

   • Create feature branch
   • Refactor one function at a time
   • Test after each change
   • Commit frequently

Questions & Clarifications

Q: Should we keep pkg/common/selectors/selectors.go?

A: YES - Keep for reference and validation, but prefer bindings for actual calls.

Q: What about contracts not in Mev-Alpha?

A: Keep manual ABI for third-party contracts (Balancer, Curve, etc.) unless we add their ABIs to bindings.

Q: How to handle contract upgrades?

A:

1. Update Solidity contract
2. Regenerate bindings
3. Update tests
4. Deploy new version
5. Update addresses.go

Q: Should we version bindings?

A: Consider using git tags and semantic versioning for binding versions tied to contract deployments.

---

Sign-Off

Prepared By: Claude Code Reviewed By: Pending Approved By: Pending Start Date: TBD Target Completion: TBD

Notes: This migration is recommended for production readiness but can be done incrementally. Start with high-impact files (pkg/uniswap) to demonstrate value before tackling complex files (pkg/arbitrum).