mev-beta/docs/BINDING_QUICK_START.md

Quick Start: Contract Binding Consistency

Immediate Action Items

1. Compile Mev-Alpha Contracts

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:

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

# 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)

// 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)

// 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

# Test each refactored package
go test ./pkg/uniswap -v
go test ./pkg/arbitrum -v
go test ./pkg/events -v

2. Integration Tests

# 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

# 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

# Install abigen
go install github.com/ethereum/go-ethereum/cmd/abigen@latest

# Verify installation
which abigen
abigen --version

Issue: jq command not found

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install -y jq

# macOS
brew install jq

Issue: Compilation errors after binding update

# 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

# 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