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

```go
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

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

#### Pattern 3: Writing Transactions

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

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

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

- [x] Audit existing contract interaction patterns
- [x] 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

```bash
# 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:
```go
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:
```bash
./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](https://geth.ethereum.org/docs/tools/abigen)
- [Solidity ABI Specification](https://docs.soliditylang.org/en/latest/abi-spec.html)
- [Foundry Book - Deploying and Verifying](https://book.getfoundry.sh/forge/deploying)

---

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