mev-beta/docs/architecture/flash_loan_execution_architecture.md

# Flash Loan Execution Architecture
**Version:** 1.0
**Date:** October 28, 2025
**Status:** Design Document

## Executive Summary

This document outlines the comprehensive architecture for flash loan-based arbitrage execution in the MEV bot. The system supports multiple flash loan providers (Aave, Balancer, Uniswap), implements robust safety checks, and handles the complete lifecycle from opportunity detection to profit realization.

---

## Table of Contents

1. [System Overview](#system-overview)
2. [Architecture Components](#architecture-components)
3. [Execution Flow](#execution-flow)
4. [Provider Implementations](#provider-implementations)
5. [Safety & Risk Management](#safety--risk-management)
6. [Transaction Signing & Dispatch](#transaction-signing--dispatch)
7. [Error Handling & Recovery](#error-handling--recovery)
8. [Monitoring & Analytics](#monitoring--analytics)

---

## System Overview

### Goals

- **Capital Efficiency**: Execute arbitrage with zero upfront capital using flash loans
- **Safety First**: Comprehensive validation and risk management at every step
- **Multi-Provider Support**: Use the best flash loan provider for each opportunity
- **Production Ready**: Handle real-world edge cases, errors, and race conditions

### High-Level Architecture

```
┌─────────────────────────────────────────────────────────┐
│            Opportunity Detection Layer                  │
│  (Market Scanner, Price Feed, Arbitrage Detector)       │
└──────────────────┬──────────────────────────────────────┘
                   │ Opportunities
                   ▼
┌─────────────────────────────────────────────────────────┐
│         Opportunity Validation & Ranking                │
│  (Profit Calculator, Risk Assessor, Price Impact)       │
└──────────────────┬──────────────────────────────────────┘
                   │ Validated Opportunities
                   ▼
┌─────────────────────────────────────────────────────────┐
│          Flash Loan Provider Selection                  │
│   (Aave, Balancer, Uniswap Flash Swap Selector)         │
└──────────────────┬──────────────────────────────────────┘
                   │ Provider + Execution Plan
                   ▼
┌─────────────────────────────────────────────────────────┐
│           Transaction Builder & Signer                  │
│  (Calldata Encoder, Gas Estimator, Nonce Manager)       │
└──────────────────┬──────────────────────────────────────┘
                   │ Signed Transaction
                   ▼
┌─────────────────────────────────────────────────────────┐
│           Transaction Dispatcher                        │
│  (Mempool Broadcaster, Flashbots Relay, Private RPC)    │
└──────────────────┬──────────────────────────────────────┘
                   │ Transaction Hash
                   ▼
┌─────────────────────────────────────────────────────────┐
│          Execution Monitor & Confirmation               │
│  (Receipt Waiter, Event Parser, Profit Calculator)      │
└─────────────────────────────────────────────────────────┘
```

---

## Architecture Components

### 1. Flash Loan Provider Interface

All flash loan providers implement this common interface:

```go
type FlashLoanProvider interface {
    // Execute flash loan with given opportunity
    ExecuteFlashLoan(ctx context.Context, opp *ArbitrageOpportunity, config *ExecutionConfig) (*ExecutionResult, error)

    // Get maximum borrowable amount for token
    GetMaxLoanAmount(ctx context.Context, token common.Address) (*big.Int, error)

    // Calculate flash loan fee
    GetFee(ctx context.Context, amount *big.Int) (*big.Int, error)

    // Check if provider supports token
    SupportsToken(token common.Address) bool

    // Get provider name
    Name() string

    // Get provider priority (lower = higher priority)
    Priority() int
}
```

### 2. Flash Loan Orchestrator

Central coordinator that:
- Receives validated arbitrage opportunities
- Selects optimal flash loan provider
- Manages execution queue and priority
- Handles concurrent execution limits
- Tracks execution state and history

```go
type FlashLoanOrchestrator struct {
    providers []FlashLoanProvider
    executionQueue *PriorityQueue
    executionLimiter *ConcurrencyLimiter
    stateTracker *ExecutionStateTracker
    metricsCollector *MetricsCollector
}
```

### 3. Transaction Builder

Constructs and signs transactions for flash loan execution:

```go
type TransactionBuilder struct {
    client *ethclient.Client
    keyManager *security.KeyManager
    nonceManager *arbitrage.NonceManager
    gasEstimator *arbitrum.L2GasEstimator

    // Build transaction calldata
    BuildCalldata(opp *ArbitrageOpportunity, provider FlashLoanProvider) ([]byte, error)

    // Estimate gas for transaction
    EstimateGas(tx *types.Transaction) (uint64, error)

    // Sign transaction
    SignTransaction(tx *types.Transaction) (*types.Transaction, error)
}
```

### 4. Transaction Dispatcher

Sends signed transactions to the network:

```go
type TransactionDispatcher struct {
    client *ethclient.Client
    logger *logger.Logger

    // Dispatch modes
    useFlashbots bool
    flashbotsRelay string
    usePrivateRPC bool
    privateRPCURL string

    // Dispatch transaction
    Dispatch(ctx context.Context, tx *types.Transaction, mode DispatchMode) (common.Hash, error)

    // Wait for confirmation
    WaitForConfirmation(ctx context.Context, txHash common.Hash, confirmations uint64) (*types.Receipt, error)
}
```

### 5. Execution Monitor

Monitors transaction execution and parses results:

```go
type ExecutionMonitor struct {
    client *ethclient.Client
    eventParser *events.Parser

    // Monitor execution
    MonitorExecution(ctx context.Context, txHash common.Hash) (*ExecutionResult, error)

    // Parse profit from receipt
    ParseProfit(receipt *types.Receipt) (*big.Int, error)

    // Handle reverts
    ParseRevertReason(receipt *types.Receipt) string
}
```

---

## Execution Flow

### Step-by-Step Execution Process

#### Phase 1: Pre-Execution Validation (500ms max)

```
1. Opportunity Received
   ├─ Validate opportunity structure
   ├─ Check price impact thresholds
   ├─ Verify tokens are not blacklisted
   └─ Calculate expected profit

2. Provider Selection
   ├─ Check token support across providers
   ├─ Calculate fees for each provider
   ├─ Select provider with lowest cost
   └─ Verify provider has sufficient liquidity

3. Risk Assessment
   ├─ Check current gas prices
   ├─ Validate slippage limits
   ├─ Verify position size limits
   └─ Check daily volume limits

4. Final Profitability Check
   ├─ Net Profit = Gross Profit - Gas Costs - Flash Loan Fees
   ├─ Reject if Net Profit < MinProfitThreshold
   └─ Continue if profitable
```

#### Phase 2: Transaction Construction (200ms max)

```
1. Build Flash Loan Calldata
   ├─ Encode arbitrage path
   ├─ Calculate minimum output amounts
   ├─ Set recipient address
   └─ Add safety parameters

2. Estimate Gas
   ├─ Call estimateGas on RPC
   ├─ Apply safety multiplier (1.2x)
   ├─ Calculate gas cost in ETH
   └─ Re-validate profitability with gas cost

3. Get Nonce
   ├─ Query pending nonce from network
   ├─ Check nonce manager for next available
   ├─ Handle nonce collisions
   └─ Reserve nonce for this transaction

4. Build Transaction Object
   ├─ Set to: Flash Loan Provider address
   ├─ Set data: Encoded calldata
   ├─ Set gas: Estimated gas limit
   ├─ Set gasPrice: Current gas price + priority fee
   ├─ Set nonce: Reserved nonce
   └─ Set value: 0 (flash loans don't require upfront payment)

5. Sign Transaction
   ├─ Load private key from KeyManager
   ├─ Sign with EIP-155 (ChainID: 42161 for Arbitrum)
   ├─ Verify signature
   └─ Serialize to RLP
```

#### Phase 3: Transaction Dispatch (1-2s max)

```
1. Choose Dispatch Method
   ├─ If MEV Protection Enabled → Use Flashbots/Private RPC
   ├─ If High Competition → Use Private RPC
   └─ Default → Public Mempool

2. Send Transaction
   ├─ Dispatch via chosen method
   ├─ Receive transaction hash
   ├─ Log submission
   └─ Start monitoring

3. Handle Errors
   ├─ If "nonce too low" → Get new nonce and retry
   ├─ If "gas too low" → Increase gas and retry
   ├─ If "insufficient funds" → Abort (critical error)
   ├─ If "already known" → Wait for existing tx
   └─ If network error → Retry with exponential backoff
```

#### Phase 4: Execution Monitoring (5-30s)

```
1. Wait for Inclusion
   ├─ Poll for transaction receipt
   ├─ Timeout after 30 seconds
   ├─ Check if transaction replaced
   └─ Handle dropped transactions

2. Verify Execution
   ├─ Check receipt status (1 = success, 0 = revert)
   ├─ If reverted → Parse revert reason
   ├─ If succeeded → Continue
   └─ If dropped → Handle re-submission

3. Parse Events
   ├─ Extract ArbitrageExecuted event
   ├─ Parse actual profit
   ├─ Parse gas used
   └─ Calculate ROI

4. Update State
   ├─ Mark nonce as confirmed
   ├─ Update profit tracking
   ├─ Log execution result
   └─ Emit metrics
```

---

## Provider Implementations

### 1. Aave Flash Loan Provider

**Advantages:**
- Large liquidity pools
- Supports many tokens
- Fixed fee (0.09%)
- Very reliable

**Implementation:**

```go
func (a *AaveFlashLoanProvider) ExecuteFlashLoan(
    ctx context.Context,
    opp *ArbitrageOpportunity,
    config *ExecutionConfig,
) (*ExecutionResult, error) {
    // 1. Build flash loan parameters
    assets := []common.Address{opp.TokenIn}
    amounts := []*big.Int{opp.AmountIn}
    modes := []*big.Int{big.NewInt(0)} // 0 = no debt, must repay in same transaction

    // 2. Encode arbitrage path as userData
    userData := encodeArbitragePath(opp)

    // 3. Build flashLoan() calldata
    aaveABI := getAavePoolABI()
    calldata, err := aaveABI.Pack(
        "flashLoan",
        a.receiverContract,  // Receiver contract
        assets,              // Assets to borrow
        amounts,             // Amounts to borrow
        modes,               // Interest rate modes (0 for none)
        a.onBehalfOf,        // On behalf of address
        userData,            // Encoded arbitrage data
        uint16(0),           // Referral code
    )

    // 4. Build and sign transaction
    tx := buildTransaction(a.poolAddress, calldata, config)
    signedTx, err := signTransaction(tx, keyManager)

    // 5. Dispatch transaction
    txHash, err := dispatcher.Dispatch(ctx, signedTx, DispatchModeMEV)

    // 6. Monitor execution
    receipt, err := monitor.WaitForConfirmation(ctx, txHash, 1)

    // 7. Parse result
    result := parseExecutionResult(receipt, opp)

    return result, nil
}
```

### 2. Balancer Flash Loan Provider

**Advantages:**
- Zero fees (!)
- Large liquidity
- Multi-token flash loans supported

**Implementation:**

```go
func (b *BalancerFlashLoanProvider) ExecuteFlashLoan(
    ctx context.Context,
    opp *ArbitrageOpportunity,
    config *ExecutionConfig,
) (*ExecutionResult, error) {
    // 1. Build flash loan parameters
    tokens := []common.Address{opp.TokenIn}
    amounts := []*big.Int{opp.AmountIn}

    // 2. Encode arbitrage path
    userData := encodeArbitragePath(opp)

    // 3. Build flashLoan() calldata for Balancer Vault
    vaultABI := getBalancerVaultABI()
    calldata, err := vaultABI.Pack(
        "flashLoan",
        b.receiverContract,  // IFlashLoanReceiver
        tokens,              // Tokens to borrow
        amounts,             // Amounts to borrow
        userData,            // Encoded arbitrage path
    )

    // 4-7. Same as Aave (build, sign, dispatch, monitor)
    // ...
}
```

### 3. Uniswap Flash Swap Provider

**Advantages:**
- Available on all token pairs
- No separate flash loan contract needed
- Fee is same as swap fee (0.3%)

**Implementation:**

```go
func (u *UniswapFlashSwapProvider) ExecuteFlashLoan(
    ctx context.Context,
    opp *ArbitrageOpportunity,
    config *ExecutionConfig,
) (*ExecutionResult, error) {
    // 1. Find optimal pool for flash swap
    pool := findBestPoolForFlashSwap(opp.TokenIn, opp.AmountIn)

    // 2. Determine amount0Out and amount1Out
    amount0Out, amount1Out := calculateSwapAmounts(pool, opp)

    // 3. Encode arbitrage path
    userData := encodeArbitragePath(opp)

    // 4. Build swap() calldata for Uniswap V2 pair
    pairABI := getUniswapV2PairABI()
    calldata, err := pairABI.Pack(
        "swap",
        amount0Out,           // Amount of token0 to receive
        amount1Out,           // Amount of token1 to receive
        u.receiverContract,   // Recipient (our contract)
        userData,             // Triggers callback
    )

    // 5-8. Same as others
    // ...
}
```

---

## Safety & Risk Management

### Pre-Execution Checks

```go
type SafetyValidator struct {
    priceImpactValidator *validation.PriceImpactValidator
    blacklistChecker     *security.BlacklistChecker
    positionLimiter      *risk.PositionLimiter
}

func (sv *SafetyValidator) ValidateExecution(opp *ArbitrageOpportunity) error {
    // 1. Price Impact
    if result := sv.priceImpactValidator.ValidatePriceImpact(opp.PriceImpact); !result.IsAcceptable {
        return fmt.Errorf("price impact too high: %s", result.Recommendation)
    }

    // 2. Blacklist Check
    if sv.blacklistChecker.IsBlacklisted(opp.TokenIn) || sv.blacklistChecker.IsBlacklisted(opp.TokenOut) {
        return fmt.Errorf("token is blacklisted")
    }

    // 3. Position Size
    if opp.AmountIn.Cmp(sv.positionLimiter.MaxPositionSize) > 0 {
        return fmt.Errorf("position size exceeds limit")
    }

    // 4. Slippage Protection
    if opp.Slippage > sv.maxSlippage {
        return fmt.Errorf("slippage %f%% exceeds max %f%%", opp.Slippage, sv.maxSlippage)
    }

    return nil
}
```

### Circuit Breakers

```go
type CircuitBreaker struct {
    consecutiveFailures int
    maxFailures         int
    resetTimeout        time.Duration
    lastFailure         time.Time
    state               CircuitState
}

func (cb *CircuitBreaker) ShouldExecute() bool {
    if cb.state == CircuitStateOpen {
        // Check if we should try half-open
        if time.Since(cb.lastFailure) > cb.resetTimeout {
            cb.state = CircuitStateHalfOpen
            return true
        }
        return false
    }
    return true
}

func (cb *CircuitBreaker) RecordSuccess() {
    cb.consecutiveFailures = 0
    cb.state = CircuitStateClosed
}

func (cb *CircuitBreaker) RecordFailure() {
    cb.consecutiveFailures++
    cb.lastFailure = time.Now()

    if cb.consecutiveFailures >= cb.maxFailures {
        cb.state = CircuitStateOpen
        // Trigger alerts
    }
}
```

---

## Transaction Signing & Dispatch

### Transaction Signing Flow

```go
func SignFlashLoanTransaction(
    opp *ArbitrageOpportunity,
    provider FlashLoanProvider,
    keyManager *security.KeyManager,
    nonceManager *NonceManager,
    gasEstimator *GasEstimator,
) (*types.Transaction, error) {

    // 1. Build calldata
    calldata, err := provider.BuildCalldata(opp)
    if err != nil {
        return nil, fmt.Errorf("failed to build calldata: %w", err)
    }

    // 2. Estimate gas
    gasLimit, err := gasEstimator.EstimateGas(provider.Address(), calldata)
    if err != nil {
        return nil, fmt.Errorf("failed to estimate gas: %w", err)
    }

    // 3. Get gas price
    gasPrice, priorityFee, err := gasEstimator.GetGasPrice(context.Background())
    if err != nil {
        return nil, fmt.Errorf("failed to get gas price: %w", err)
    }

    // 4. Get nonce
    nonce, err := nonceManager.GetNextNonce(context.Background())
    if err != nil {
        return nil, fmt.Errorf("failed to get nonce: %w", err)
    }

    // 5. Build transaction
    tx := types.NewTx(&types.DynamicFeeTx{
        ChainID:   big.NewInt(42161), // Arbitrum
        Nonce:     nonce,
        GasTipCap: priorityFee,
        GasFeeCap: gasPrice,
        Gas:       gasLimit,
        To:        &provider.Address(),
        Value:     big.NewInt(0),
        Data:      calldata,
    })

    // 6. Sign transaction
    privateKey, err := keyManager.GetPrivateKey()
    if err != nil {
        return nil, fmt.Errorf("failed to get private key: %w", err)
    }

    signer := types.LatestSignerForChainID(big.NewInt(42161))
    signedTx, err := types.SignTx(tx, signer, privateKey)
    if err != nil {
        return nil, fmt.Errorf("failed to sign transaction: %w", err)
    }

    return signedTx, nil
}
```

### Dispatch Strategies

**1. Public Mempool (Default)**
```go
func (d *TransactionDispatcher) DispatchPublic(ctx context.Context, tx *types.Transaction) (common.Hash, error) {
    err := d.client.SendTransaction(ctx, tx)
    if err != nil {
        return common.Hash{}, err
    }
    return tx.Hash(), nil
}
```

**2. Flashbots Relay (MEV Protection)**
```go
func (d *TransactionDispatcher) DispatchFlashbots(ctx context.Context, tx *types.Transaction) (common.Hash, error) {
    bundle := types.MevBundle{
        Txs: types.Transactions{tx},
        BlockNumber: currentBlock + 1,
    }

    bundleHash, err := d.flashbotsClient.SendBundle(ctx, bundle)
    if err != nil {
        return common.Hash{}, err
    }

    return bundleHash, nil
}
```

**3. Private RPC (Low Latency)**
```go
func (d *TransactionDispatcher) DispatchPrivate(ctx context.Context, tx *types.Transaction) (common.Hash, error) {
    err := d.privateClient.SendTransaction(ctx, tx)
    if err != nil {
        return common.Hash{}, err
    }
    return tx.Hash(), nil
}
```

---

## Error Handling & Recovery

### Common Errors and Responses

| Error | Cause | Response |
|-------|-------|----------|
| `nonce too low` | Transaction already mined | Get new nonce, retry |
| `nonce too high` | Nonce gap exists | Reset nonce manager, retry |
| `insufficient funds` | Not enough ETH for gas | Abort, alert operator |
| `gas price too low` | Network congestion | Increase gas price, retry |
| `execution reverted` | Smart contract revert | Parse reason, log, abort |
| `transaction underpriced` | Gas price below network minimum | Get current gas price, retry |
| `already known` | Duplicate transaction | Wait for confirmation |
| `replacement transaction underpriced` | Replacement needs higher gas | Increase gas by 10%, retry |

### Retry Strategy

```go
func (executor *FlashLoanExecutor) executeWithRetry(
    ctx context.Context,
    opp *ArbitrageOpportunity,
) (*ExecutionResult, error) {

    var lastErr error
    for attempt := 0; attempt < executor.config.RetryAttempts; attempt++ {
        result, err := executor.attemptExecution(ctx, opp)

        if err == nil {
            return result, nil
        }

        lastErr = err

        // Check if error is retryable
        if !isRetryable(err) {
            return nil, fmt.Errorf("non-retryable error: %w", err)
        }

        // Handle specific errors
        if strings.Contains(err.Error(), "nonce too low") {
            executor.nonceManager.Reset()
        } else if strings.Contains(err.Error(), "gas price too low") {
            executor.increaseGasPrice()
        }

        // Exponential backoff
        backoff := time.Duration(stdmath.Pow(2, float64(attempt))) * executor.config.RetryDelay
        time.Sleep(backoff)
    }

    return nil, fmt.Errorf("max retries exceeded: %w", lastErr)
}
```

---

## Monitoring & Analytics

### Metrics to Track

1. **Execution Metrics**
   - Total executions (successful / failed / reverted)
   - Average execution time
   - Gas used per execution
   - Nonce collision rate

2. **Profit Metrics**
   - Total profit (gross / net)
   - Average profit per execution
   - Profit by provider
   - ROI by token pair

3. **Performance Metrics**
   - Latency from opportunity detection to execution
   - Transaction confirmation time
   - Success rate by provider
   - Revert rate by reason

4. **Risk Metrics**
   - Largest position size executed
   - Highest price impact accepted
   - Slippage encountered
   - Failed transactions by reason

### Logging Format

```go
type ExecutionLog struct {
    Timestamp       time.Time
    OpportunityID   string
    Provider        string
    TokenIn         string
    TokenOut        string
    AmountIn        string
    EstimatedProfit string
    ActualProfit    string
    GasUsed         uint64
    GasCost         string
    TransactionHash string
    Status          string
    Error           string
    ExecutionTime   time.Duration
}
```

---

## Implementation Checklist

### Phase 1: Core Infrastructure (Week 1)
- [ ] Implement TransactionBuilder
- [ ] Implement NonceManager improvements
- [ ] Implement TransactionDispatcher
- [ ] Add comprehensive error handling
- [ ] Create execution state tracking

### Phase 2: Provider Implementation (Week 2)
- [ ] Complete Balancer flash loan provider
- [ ] Complete Aave flash loan provider
- [ ] Complete Uniswap flash swap provider
- [ ] Add provider selection logic
- [ ] Implement fee comparison

### Phase 3: Safety & Testing (Week 3)
- [ ] Implement circuit breakers
- [ ] Add position size limits
- [ ] Create simulation/dry-run mode
- [ ] Comprehensive unit tests
- [ ] Integration tests with testnet

### Phase 4: Production Deployment (Week 4)
- [ ] Deploy flash loan receiver contracts
- [ ] Configure private RPC/Flashbots
- [ ] Set up monitoring dashboards
- [ ] Production smoke tests
- [ ] Gradual rollout with small positions

---

## Security Considerations

### Private Key Management

1. **Never log private keys**
2. **Use hardware security modules (HSM) in production**
3. **Implement key rotation**
4. **Encrypt keys at rest**
5. **Limit key access to execution process only**

### Smart Contract Security

1. **Audit all receiver contracts before deployment**
2. **Use access control (Ownable)**
3. **Implement reentrancy guards**
4. **Set maximum borrow limits**
5. **Add emergency pause functionality**

### Transaction Security

1. **Validate all inputs before signing**
2. **Use EIP-155 replay protection**
3. **Verify transaction before dispatch**
4. **Monitor for front-running**
5. **Use private mempools when needed**

---

## Conclusion

This flash loan execution architecture provides a robust, production-ready system for executing MEV arbitrage opportunities. Key features include:

- **Multi-provider support** for optimal cost and availability
- **Comprehensive safety checks** at every stage
- **Robust error handling** with intelligent retry logic
- **Detailed monitoring** for operations and debugging
- **Production hardened** design for real-world usage

The modular design allows for easy extension, testing, and maintenance while ensuring safety and profitability.

---

**Next Steps**: Proceed with implementation following the phased checklist above.