mev-beta/docs/BINDING_CONSISTENCY_GUIDE.md

MEV Bot Contract Binding Consistency Guide

Overview

This document provides a comprehensive guide to ensuring contract binding consistency between the Mev-Alpha Solidity contracts and the mev-beta Go implementation.

Current Status

Findings

1. Existing Bindings: The /home/administrator/projects/mev-beta/bindings directory contains Go bindings for contracts, but they may not be up-to-date with the latest Solidity contracts in Mev-Alpha.

2. Mixed Approach: The codebase currently uses a combination of:

   • Generated bindings (bindings/contracts/*.go)
   • Manual ABI packing (pkg/uniswap/contracts.go, pkg/arbitrum/abi_decoder.go)
   • Function selector computation (pkg/common/selectors/selectors.go)

3. Inconsistency Risk: Using manual ABI calls alongside bindings creates potential for:

   • Function signature mismatches
   • Type conversion errors
   • Missed contract updates
   • Maintenance overhead

Recommended Approach

Phase 1: Generate Fresh Bindings

Script Created: /home/administrator/projects/mev-beta/scripts/generate-bindings.sh

This script will:

1. Compile all Mev-Alpha Solidity contracts using Foundry
2. Extract ABI from compiled JSON artifacts
3. Generate Go bindings using abigen
4. Organize bindings by contract type:
   • bindings/contracts/ - Core contracts (ArbitrageExecutor, BaseFlashSwapper)
   • bindings/interfaces/ - Interfaces (IArbitrage, IFlashSwapper)
   • bindings/dex/ - DEX-specific contracts (UniswapV2/V3FlashSwapper)
   • bindings/utils/ - Math and utility libraries
   • bindings/tokens/ - Token interfaces

To Run:

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

Note: Compilation of Mev-Alpha contracts may take several minutes due to the large dependency tree (108 files).

Phase 2: Refactor Contract Interactions

Current Anti-Patterns

❌ Manual ABI Packing (pkg/uniswap/contracts.go:156-160):

// DON'T DO THIS
data, err := p.abi.Pack("slot0")
if err != nil {
    return nil, fmt.Errorf("failed to pack slot0 call: %w", err)
}

✅ Use Generated Bindings:

// DO THIS
import "github.com/yourusername/mev-beta/bindings/tokens"

pool, err := tokens.NewIUniswapV3PoolActions(poolAddress, client)
if err != nil {
    return nil, fmt.Errorf("failed to create pool binding: %w", err)
}

slot0, err := pool.Slot0(&bind.CallOpts{})
if err != nil {
    return nil, fmt.Errorf("failed to call slot0: %w", err)
}

Files Requiring Updates

1. pkg/uniswap/contracts.go (lines 155-332)

   • Replace manual abi.Pack() calls with binding methods
   • Use typed struct returns instead of UnpackIntoInterface

2. pkg/arbitrum/abi_decoder.go (entire file)

   • Consider using binding-generated events for parsing
   • Keep for multi-protocol ABI decoding where bindings don't exist

3. pkg/common/selectors/selectors.go (entire file)

   • KEEP THIS FILE - selectors are useful for quick function ID checks
   • But prefer bindings for actual contract calls

4. Other files using crypto.Keccak256 for selectors:

   • /home/administrator/projects/mev-beta/pkg/events/parser.go
   • /home/administrator/projects/mev-beta/pkg/monitor/concurrent.go
   • /home/administrator/projects/mev-beta/pkg/calldata/swaps.go

Phase 3: Binding Usage Patterns

Pattern 1: Contract Instantiation

import (
    "github.com/ethereum/go-ethereum/accounts/abi/bind"
    "github.com/ethereum/go-ethereum/common"
    "github.com/ethereum/go-ethereum/ethclient"

    "github.com/yourusername/mev-beta/bindings/contracts"
)

// Create contract instance
arbitrageExecutor, err := contracts.NewArbitrageExecutor(
    common.HexToAddress("0x..."),
    client,
)
if err != nil {
    return err
}

Pattern 2: Reading Contract State

// Use binding methods for view functions
isAuthorized, err := arbitrageExecutor.AuthorizedCallers(
    &bind.CallOpts{},
    userAddress,
)
if err != nil {
    return err
}

Pattern 3: Writing Transactions

// Prepare transaction options
auth, err := bind.NewKeyedTransactorWithChainID(privateKey, chainID)
if err != nil {
    return err
}

// Build arbitrage params using generated struct
params := contracts.IArbitrageArbitrageParams{
    Tokens:    []common.Address{token0, token1, token2},
    Pools:     []common.Address{pool1, pool2},
    Amounts:   []*big.Int{amount1, amount2},
    SwapData:  [][]byte{data1, data2},
    MinProfit: minProfit,
}

// Execute transaction
tx, err := arbitrageExecutor.ExecuteArbitrage(auth, params)
if err != nil {
    return err
}

Pattern 4: Event Parsing

// Filter logs
logs, err := client.FilterLogs(ctx, ethereum.FilterQuery{
    FromBlock: startBlock,
    ToBlock:   endBlock,
    Addresses: []common.Address{contractAddress},
})

// Parse events using bindings
for _, log := range logs {
    event, err := arbitrageExecutor.ParseArbitrageExecuted(log)
    if err != nil {
        continue
    }

    // Use typed fields
    fmt.Printf("Arbitrage executed by %s with profit %s\n",
        event.Initiator.Hex(),
        event.Profit.String(),
    )
}

Phase 4: Contract Address Management

Created: bindings/addresses.go

This file centralizes all deployed contract addresses:

package bindings

import "github.com/ethereum/go-ethereum/common"

var (
    // Core contracts (update after deployment)
    ArbitrageExecutorAddress     = common.HexToAddress("0x...")
    UniswapV3FlashSwapperAddress = common.HexToAddress("0x...")

    // Known DEX addresses on Arbitrum
    UniswapV3Factory = common.HexToAddress("0x1F98431c8aD98523631AE4a59f267346ea31F984")
    SushiswapRouter  = common.HexToAddress("0x1b02dA8Cb0d097eB8D57A175b88c7D8b47997506")
    // ...
}

Usage:

import "github.com/yourusername/mev-beta/bindings"

executor, err := contracts.NewArbitrageExecutor(
    bindings.ArbitrageExecutorAddress,
    client,
)

Benefits of Binding Consistency

1. Type Safety: Compile-time checking of function signatures and parameters
2. Reduced Errors: No manual ABI encoding/decoding mistakes
3. Easier Maintenance: Contract updates automatically propagate via re-generation
4. Better IDE Support: Auto-completion and type hints
5. Cleaner Code: More readable and self-documenting

Migration Checklist

• Audit existing contract interaction patterns
• Create binding generation script
• Compile Mev-Alpha Solidity contracts
• Generate fresh Go bindings
• Update pkg/uniswap/contracts.go to use bindings
• Update pkg/arbitrum/abi_decoder.go where applicable
• Update contract address constants
• Test all contract interactions
• Run integration tests
• Update documentation

Testing Strategy

Unit Tests

For each refactored file, ensure:

1. All contract calls use bindings
2. Error handling is preserved
3. Return types are correctly converted

Integration Tests

Test against:

1. Arbitrum testnet (Sepolia)
2. Local Anvil fork
3. Mainnet fork (read-only)

Validation Script

# Check for manual ABI packing (should be minimal)
grep -r "abi.Pack" pkg/ --exclude-dir=test

# Check for manual Keccak256 selector computation (review each)
grep -r "crypto.Keccak256" pkg/ --exclude-dir=test

# Ensure bindings compile
go build ./bindings/...

# Run tests
go test ./pkg/... -v

Troubleshooting

Issue: abigen fails with "no type MyStruct"

Solution: Ensure structs are defined in interfaces or export them from contracts.

Issue: Binding import conflicts

Solution: Use package aliases:

import (
    contractsArbitrage "github.com/yourusername/mev-beta/bindings/contracts"
    interfacesArbitrage "github.com/yourusername/mev-beta/bindings/interfaces"
)

Issue: Contract ABI changed but bindings not updated

Solution: Re-run generation script:

./scripts/generate-bindings.sh
go mod tidy

Best Practices

1. Always regenerate bindings after contract changes
2. Use semantic versioning for contract deployments
3. Keep function selectors file for reference, but prefer bindings
4. Document which contracts are deployed vs. mocks
5. Use typed structs from bindings, not map[string]interface{}

References

• go-ethereum abigen documentation
• Solidity ABI Specification
• Foundry Book - Deploying and Verifying

---

Last Updated: 2025-10-26 Status: In Progress - Awaiting contract compilation