# 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
- [x] Foundry installed (forge 1.0.0-stable)
- [x] abigen installed (/home/administrator/go/bin/abigen)
- [x] jq installed (for JSON parsing)
- [x] Mev-Alpha contracts available (/home/administrator/projects/Mev-Alpha)

### Scripts Created
- [x] `/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

```bash
# 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**:
```go
// 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**:
```go
// 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

```bash
# 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

- [x] docs/BINDING_CONSISTENCY_GUIDE.md - Comprehensive guide
- [x] docs/BINDING_QUICK_START.md - Quick reference
- [x] 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:
- [x] 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):
   ```bash
   cd /home/administrator/projects/mev-beta
   rm -rf bindings/
   cp -r bindings_backup_YYYYMMDD_HHMMSS/ bindings/
   git checkout -- pkg/
   ```

2. **Partial Rollback** (per file):
   ```bash
   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
   ```bash
   cd /home/administrator/projects/Mev-Alpha
   forge build
   ```

2. **AFTER BUILD**: Run binding generation
   ```bash
   cd /home/administrator/projects/mev-beta
   ./scripts/generate-bindings.sh
   ```

3. **VERIFY**: Check bindings compile
   ```bash
   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).