feat: create v2-prep branch with comprehensive planning

Restructured project for V2 refactor:

**Structure Changes:**
- Moved all V1 code to orig/ folder (preserved with git mv)
- Created docs/planning/ directory
- Added orig/README_V1.md explaining V1 preservation

**Planning Documents:**
- 00_V2_MASTER_PLAN.md: Complete architecture overview
  - Executive summary of critical V1 issues
  - High-level component architecture diagrams
  - 5-phase implementation roadmap
  - Success metrics and risk mitigation

- 07_TASK_BREAKDOWN.md: Atomic task breakdown
  - 99+ hours of detailed tasks
  - Every task < 2 hours (atomic)
  - Clear dependencies and success criteria
  - Organized by implementation phase

**V2 Key Improvements:**
- Per-exchange parsers (factory pattern)
- Multi-layer strict validation
- Multi-index pool cache
- Background validation pipeline
- Comprehensive observability

**Critical Issues Addressed:**
- Zero address tokens (strict validation + cache enrichment)
- Parsing accuracy (protocol-specific parsers)
- No audit trail (background validation channel)
- Inefficient lookups (multi-index cache)
- Stats disconnection (event-driven metrics)

Next Steps:
1. Review planning documents
2. Begin Phase 1: Foundation (P1-001 through P1-010)
3. Implement parsers in Phase 2
4. Build cache system in Phase 3
5. Add validation pipeline in Phase 4
6. Migrate and test in Phase 5

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

orig/pkg/contracts/flashloan_executor.go

@@ -0,0 +1,175 @@
+package contracts
+
+import (
+	"context"
+	"fmt"
+	"math/big"
+
+	"github.com/ethereum/go-ethereum/accounts/abi/bind"
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/ethclient"
+)
+
+// FlashLoanExecutorConfig holds configuration for flash loan execution
+type FlashLoanExecutorConfig struct {
+	ContractAddress common.Address
+	BalancerVault   common.Address
+	MaxSlippageBps  *big.Int
+	MaxPathLength   *big.Int
+	MinProfitWei    *big.Int
+	OwnerPrivateKey string
+	RPCEndpoint     string
+}
+
+// FlashLoanExecutor manages flash loan arbitrage execution
+type FlashLoanExecutor struct {
+	config   *FlashLoanExecutorConfig
+	client   *ethclient.Client
+	contract *FlashLoanReceiverSecure
+	auth     *bind.TransactOpts
+}
+
+// NewFlashLoanExecutor creates a new flash loan executor
+func NewFlashLoanExecutor(config *FlashLoanExecutorConfig) (*FlashLoanExecutor, error) {
+	client, err := ethclient.Dial(config.RPCEndpoint)
+	if err != nil {
+		return nil, fmt.Errorf("failed to connect to RPC: %w", err)
+	}
+
+	contract, err := NewFlashLoanReceiverSecure(config.ContractAddress, client)
+	if err != nil {
+		return nil, fmt.Errorf("failed to instantiate contract: %w", err)
+	}
+
+	return &FlashLoanExecutor{
+		config:   config,
+		client:   client,
+		contract: contract,
+	}, nil
+}
+
+// ExecuteArbitrage executes a flash loan arbitrage opportunity
+func (e *FlashLoanExecutor) ExecuteArbitrage(
+	ctx context.Context,
+	tokens []common.Address,
+	amounts []*big.Int,
+	path ArbitragePath,
+) (*FlashLoanResult, error) {
+	// Encode the arbitrage path
+	userData, err := e.encodeArbitragePath(path)
+	if err != nil {
+		return nil, fmt.Errorf("failed to encode path: %w", err)
+	}
+
+	// Execute the flash loan arbitrage
+	tx, err := e.contract.ExecuteArbitrage(
+		e.auth,
+		convertToIERC20Array(tokens),
+		amounts,
+		userData,
+	)
+	if err != nil {
+		return nil, fmt.Errorf("flash loan execution failed: %w", err)
+	}
+
+	// Wait for transaction confirmation
+	receipt, err := bind.WaitMined(ctx, e.client, tx)
+	if err != nil {
+		return nil, fmt.Errorf("transaction mining failed: %w", err)
+	}
+
+	return &FlashLoanResult{
+		TxHash:   tx.Hash(),
+		Success:  receipt.Status == 1,
+		GasUsed:  receipt.GasUsed,
+		BlockNum: receipt.BlockNumber.Uint64(),
+	}, nil
+}
+
+// WithdrawProfit withdraws accumulated profits from the contract
+func (e *FlashLoanExecutor) WithdrawProfit(
+	ctx context.Context,
+	token common.Address,
+	amount *big.Int,
+) error {
+	tx, err := e.contract.WithdrawProfit(e.auth, token, amount)
+	if err != nil {
+		return fmt.Errorf("withdraw failed: %w", err)
+	}
+
+	_, err = bind.WaitMined(ctx, e.client, tx)
+	if err != nil {
+		return fmt.Errorf("withdraw transaction mining failed: %w", err)
+	}
+
+	return nil
+}
+
+// EmergencyWithdraw withdraws all funds from the contract
+func (e *FlashLoanExecutor) EmergencyWithdraw(
+	ctx context.Context,
+	token common.Address,
+) error {
+	tx, err := e.contract.EmergencyWithdraw(e.auth, token)
+	if err != nil {
+		return fmt.Errorf("emergency withdraw failed: %w", err)
+	}
+
+	_, err = bind.WaitMined(ctx, e.client, tx)
+	if err != nil {
+		return fmt.Errorf("emergency withdraw transaction mining failed: %w", err)
+	}
+
+	return nil
+}
+
+// GetBalance retrieves the balance of a token in the contract
+func (e *FlashLoanExecutor) GetBalance(
+	ctx context.Context,
+	token common.Address,
+) (*big.Int, error) {
+	opts := &bind.CallOpts{Context: ctx}
+	balance, err := e.contract.GetBalance(opts, token)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get balance: %w", err)
+	}
+
+	return balance, nil
+}
+
+// ArbitragePath represents a multi-hop arbitrage path
+type ArbitragePath struct {
+	Tokens      []common.Address
+	Exchanges   []common.Address
+	Fees        []*big.Int
+	IsV3        []bool
+	MinProfit   *big.Int
+	SlippageBps *big.Int
+}
+
+// FlashLoanResult contains the result of a flash loan execution
+type FlashLoanResult struct {
+	TxHash   common.Hash
+	Success  bool
+	GasUsed  uint64
+	BlockNum uint64
+}
+
+// encodeArbitragePath encodes the arbitrage path into bytes for the contract
+func (e *FlashLoanExecutor) encodeArbitragePath(path ArbitragePath) ([]byte, error) {
+	// TODO: Implement proper ABI encoding for the userData parameter
+	// This will encode: tokens, exchanges, fees, isV3, minProfit, slippageBps
+	return []byte{}, nil
+}
+
+// convertToIERC20Array converts address array to IERC20 array for contract call
+func convertToIERC20Array(addrs []common.Address) []common.Address {
+	return addrs
+}
+
+// Close closes the RPC client connection
+func (e *FlashLoanExecutor) Close() {
+	if e.client != nil {
+		e.client.Close()
+	}
+}