feat(foundation): create V2 foundation with core interfaces and types

Created complete V2 foundation infrastructure for modular MEV bot:

Core Types (pkg/types/):
- swap.go: SwapEvent with protocol support for 13+ DEXs
- pool.go: PoolInfo with multi-index cache support
- errors.go: Comprehensive error definitions
- Full validation methods and helper functions
- Proper decimal scaling (18 decimals internal representation)

Parser Interface (pkg/parsers/):
- Parser interface for protocol-specific implementations
- Factory interface for routing and registration
- Support for single log and full transaction parsing
- SupportsLog() for dynamic protocol identification

Cache Interface (pkg/cache/):
- PoolCache interface with multi-index support
- O(1) lookups by: address, token pair, protocol, liquidity
- Add, Update, Remove, Count, Clear operations
- Context-aware for cancellation support

Validation Interface (pkg/validation/):
- Validator interface for swap events and pools
- ValidationRules with configurable thresholds
- FilterValid() for batch validation
- Zero address, zero amount, decimal precision checks

Observability (pkg/observability/):
- Logger interface with structured logging (slog)
- Metrics interface with Prometheus integration
- Performance tracking (parse latency, execution)
- Business metrics (arbitrage opportunities, profit)

Project Files:
- go.mod: Module definition with ethereum and prometheus deps
- README.md: Complete project overview and documentation

Architecture Principles:
- Interface-first design for testability
- Single responsibility per interface
- Dependency injection ready
- Observable by default
- 18 decimal internal representation

Ready for Phase 1 implementation:
- All interfaces defined
- Error types established
- Core types validated
- Logging and metrics infrastructure ready

Next: Implement protocol-specific parsers (P2-001 through P2-055)

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

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

pkg/types/errors.go

@@ -0,0 +1,50 @@
+package types
+
+import "errors"
+
+// Validation errors
+var (
+	ErrInvalidTxHash         = errors.New("invalid transaction hash")
+	ErrInvalidPoolAddress    = errors.New("invalid pool address")
+	ErrInvalidToken0Address  = errors.New("invalid token0 address (zero address)")
+	ErrInvalidToken1Address  = errors.New("invalid token1 address (zero address)")
+	ErrInvalidToken0Decimals = errors.New("invalid token0 decimals")
+	ErrInvalidToken1Decimals = errors.New("invalid token1 decimals")
+	ErrUnknownProtocol       = errors.New("unknown protocol")
+	ErrZeroAmounts           = errors.New("all swap amounts are zero")
+	ErrInvalidAmount         = errors.New("invalid amount")
+	ErrInsufficientLiquidity = errors.New("insufficient liquidity")
+)
+
+// Parser errors
+var (
+	ErrUnsupportedProtocol     = errors.New("unsupported protocol")
+	ErrInvalidEventSignature   = errors.New("invalid event signature")
+	ErrInvalidLogData          = errors.New("invalid log data")
+	ErrFailedToDecode          = errors.New("failed to decode event")
+	ErrMissingPoolInfo         = errors.New("missing pool info from cache")
+)
+
+// Cache errors
+var (
+	ErrPoolNotFound      = errors.New("pool not found in cache")
+	ErrCacheNotInitialized = errors.New("cache not initialized")
+	ErrDuplicatePool     = errors.New("pool already exists in cache")
+)
+
+// Arbitrage errors
+var (
+	ErrNoOpportunity          = errors.New("no arbitrage opportunity found")
+	ErrBelowMinProfit         = errors.New("profit below minimum threshold")
+	ErrInvalidPath            = errors.New("invalid arbitrage path")
+	ErrCircularDependency     = errors.New("circular dependency in path")
+)
+
+// Execution errors
+var (
+	ErrExecutionFailed        = errors.New("execution failed")
+	ErrInsufficientBalance    = errors.New("insufficient balance")
+	ErrSlippageExceeded       = errors.New("slippage tolerance exceeded")
+	ErrGasPriceTooHigh        = errors.New("gas price too high")
+	ErrTransactionReverted    = errors.New("transaction reverted")
+)

pkg/types/pool.go

@@ -0,0 +1,124 @@
+package types
+
+import (
+	"math/big"
+
+	"github.com/ethereum/go-ethereum/common"
+)
+
+// PoolInfo contains comprehensive pool information
+type PoolInfo struct {
+	// Pool identification
+	Address         common.Address
+	Protocol        ProtocolType
+	PoolType        string  // e.g., "constant-product", "stable", "weighted"
+
+	// Token information
+	Token0          common.Address
+	Token1          common.Address
+	Token0Decimals  uint8
+	Token1Decimals  uint8
+	Token0Symbol    string
+	Token1Symbol    string
+
+	// Reserves/Liquidity
+	Reserve0        *big.Int
+	Reserve1        *big.Int
+	Liquidity       *big.Int
+
+	// Fee information
+	Fee             uint32  // Fee in basis points (e.g., 30 = 0.3%)
+	FeeGrowth0      *big.Int  // UniswapV3 fee growth
+	FeeGrowth1      *big.Int  // UniswapV3 fee growth
+
+	// Protocol-specific data
+	SqrtPriceX96    *big.Int  // UniswapV3/Camelot V3
+	Tick            *int32    // UniswapV3/Camelot V3
+	TickSpacing     int32     // UniswapV3/Camelot V3
+	AmpCoefficient  *big.Int  // Curve amplification coefficient
+
+	// Pool state
+	IsActive        bool
+	BlockNumber     uint64
+	LastUpdate      uint64
+}
+
+// Validate checks if the pool info is valid
+func (p *PoolInfo) Validate() error {
+	if p.Address == (common.Address{}) {
+		return ErrInvalidPoolAddress
+	}
+
+	if p.Token0 == (common.Address{}) {
+		return ErrInvalidToken0Address
+	}
+
+	if p.Token1 == (common.Address{}) {
+		return ErrInvalidToken1Address
+	}
+
+	if p.Token0Decimals == 0 || p.Token0Decimals > 18 {
+		return ErrInvalidToken0Decimals
+	}
+
+	if p.Token1Decimals == 0 || p.Token1Decimals > 18 {
+		return ErrInvalidToken1Decimals
+	}
+
+	if p.Protocol == ProtocolUnknown {
+		return ErrUnknownProtocol
+	}
+
+	return nil
+}
+
+// GetTokenPair returns the token pair as a sorted tuple
+func (p *PoolInfo) GetTokenPair() (common.Address, common.Address) {
+	if p.Token0.Big().Cmp(p.Token1.Big()) < 0 {
+		return p.Token0, p.Token1
+	}
+	return p.Token1, p.Token0
+}
+
+// CalculatePrice calculates the price of token0 in terms of token1
+func (p *PoolInfo) CalculatePrice() *big.Float {
+	if p.Reserve0 == nil || p.Reserve1 == nil || p.Reserve0.Sign() == 0 {
+		return big.NewFloat(0)
+	}
+
+	// Scale reserves to 18 decimals for consistent calculation
+	reserve0Scaled := scaleToDecimals(p.Reserve0, p.Token0Decimals, 18)
+	reserve1Scaled := scaleToDecimals(p.Reserve1, p.Token1Decimals, 18)
+
+	// Price = Reserve1 / Reserve0
+	reserve0Float := new(big.Float).SetInt(reserve0Scaled)
+	reserve1Float := new(big.Float).SetInt(reserve1Scaled)
+
+	price := new(big.Float).Quo(reserve1Float, reserve0Float)
+	return price
+}
+
+// scaleToDecimals scales an amount from one decimal precision to another
+func scaleToDecimals(amount *big.Int, fromDecimals, toDecimals uint8) *big.Int {
+	if fromDecimals == toDecimals {
+		return new(big.Int).Set(amount)
+	}
+
+	if fromDecimals < toDecimals {
+		// Scale up
+		multiplier := new(big.Int).Exp(
+			big.NewInt(10),
+			big.NewInt(int64(toDecimals-fromDecimals)),
+			nil,
+		)
+		return new(big.Int).Mul(amount, multiplier)
+	}
+
+	// Scale down
+	divisor := new(big.Int).Exp(
+		big.NewInt(10),
+		big.NewInt(int64(fromDecimals-toDecimals)),
+		nil,
+	)
+	return new(big.Int).Div(amount, divisor)
+}

pkg/types/swap.go

@@ -0,0 +1,115 @@
+// Package types defines core data types for MEV Bot V2
+package types
+
+import (
+	"math/big"
+	"time"
+
+	"github.com/ethereum/go-ethereum/common"
+)
+
+// ProtocolType identifies the DEX protocol
+type ProtocolType string
+
+const (
+	ProtocolUniswapV2        ProtocolType = "uniswap-v2"
+	ProtocolUniswapV3        ProtocolType = "uniswap-v3"
+	ProtocolUniswapV4        ProtocolType = "uniswap-v4"
+	ProtocolCurve            ProtocolType = "curve"
+	ProtocolBalancerV2       ProtocolType = "balancer-v2"
+	ProtocolBalancerV3       ProtocolType = "balancer-v3"
+	ProtocolKyberClassic     ProtocolType = "kyber-classic"
+	ProtocolKyberElastic     ProtocolType = "kyber-elastic"
+	ProtocolCamelotV2        ProtocolType = "camelot-v2"
+	ProtocolCamelotV3AlgebraV1        ProtocolType = "camelot-v3-algebra-v1"
+	ProtocolCamelotV3AlgebraV19       ProtocolType = "camelot-v3-algebra-v1.9"
+	ProtocolCamelotV3AlgebraIntegral  ProtocolType = "camelot-v3-algebra-integral"
+	ProtocolCamelotV3AlgebraDirectional ProtocolType = "camelot-v3-algebra-directional"
+	ProtocolUnknown          ProtocolType = "unknown"
+)
+
+// SwapEvent represents a parsed swap event from any protocol
+type SwapEvent struct {
+	// Event metadata
+	TxHash          common.Hash
+	BlockNumber     uint64
+	LogIndex        uint
+	Timestamp       time.Time
+
+	// Pool information
+	PoolAddress     common.Address
+	Protocol        ProtocolType
+
+	// Token information
+	Token0          common.Address
+	Token1          common.Address
+	Token0Decimals  uint8
+	Token1Decimals  uint8
+
+	// Swap amounts (scaled to 18 decimals internally)
+	Amount0In       *big.Int
+	Amount1In       *big.Int
+	Amount0Out      *big.Int
+	Amount1Out      *big.Int
+
+	// Additional protocol-specific data
+	Fee             *big.Int  // Fee amount (if applicable)
+	SqrtPriceX96    *big.Int  // UniswapV3/Camelot V3 price
+	Liquidity       *big.Int  // Current liquidity
+	Tick            *int32    // UniswapV3/Camelot V3 tick
+
+	// Sender and recipient
+	Sender          common.Address
+	Recipient       common.Address
+}
+
+// Validate checks if the swap event is valid
+func (s *SwapEvent) Validate() error {
+	if s.TxHash == (common.Hash{}) {
+		return ErrInvalidTxHash
+	}
+
+	if s.PoolAddress == (common.Address{}) {
+		return ErrInvalidPoolAddress
+	}
+
+	if s.Token0 == (common.Address{}) {
+		return ErrInvalidToken0Address
+	}
+
+	if s.Token1 == (common.Address{}) {
+		return ErrInvalidToken1Address
+	}
+
+	if s.Protocol == ProtocolUnknown {
+		return ErrUnknownProtocol
+	}
+
+	// At least one amount should be non-zero
+	if isZero(s.Amount0In) && isZero(s.Amount1In) && isZero(s.Amount0Out) && isZero(s.Amount1Out) {
+		return ErrZeroAmounts
+	}
+
+	return nil
+}
+
+// GetInputToken returns the token being swapped in
+func (s *SwapEvent) GetInputToken() (common.Address, *big.Int) {
+	if !isZero(s.Amount0In) {
+		return s.Token0, s.Amount0In
+	}
+	return s.Token1, s.Amount1In
+}
+
+// GetOutputToken returns the token being swapped out
+func (s *SwapEvent) GetOutputToken() (common.Address, *big.Int) {
+	if !isZero(s.Amount0Out) {
+		return s.Token0, s.Amount0Out
+	}
+	return s.Token1, s.Amount1Out
+}
+
+// isZero checks if a big.Int is nil or zero
+func isZero(n *big.Int) bool {
+	return n == nil || n.Sign() == 0
+}