mev-beta/docs/BINDING_QUICK_START.md

# Quick Start: Contract Binding Consistency

## Immediate Action Items

### 1. Compile Mev-Alpha Contracts

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

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

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

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

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

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

### 2. Integration Tests

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

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

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

# Verify installation
which abigen
abigen --version
```

### Issue: jq command not found

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

# macOS
brew install jq
```

### Issue: Compilation errors after binding update

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

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