Initial commit: Set up MEV bot project structure

docs/architecture.md

@@ -0,0 +1,58 @@
+# MEV Bot Architecture
+
+This document describes the high-level architecture of the MEV bot.
+
+## Components
+
+### 1. Arbitrum Monitor
+Responsible for monitoring the Arbitrum sequencer for new blocks and transactions.
+
+Key responsibilities:
+- Connect to Arbitrum RPC endpoint
+- Monitor new blocks as they are added
+- Identify potential swap transactions
+- Extract transaction details
+
+### 2. Market Scanner
+Analyzes potential swap transactions to determine if they create arbitrage opportunities.
+
+Key responsibilities:
+- Calculate price impact of swaps
+- Scan for arbitrage opportunities across pools
+- Estimate profitability after gas costs
+- Filter opportunities based on configured thresholds
+
+### 3. Uniswap Pricing
+Handles all Uniswap V3 pricing calculations.
+
+Key responsibilities:
+- Convert between sqrtPriceX96 and ticks
+- Calculate price impact of swaps
+- Work with liquidity values
+- Implement Uniswap V3 mathematical formulas
+
+### 4. Transaction Executor
+Responsible for executing profitable arbitrage transactions.
+
+Key responsibilities:
+- Construct arbitrage transactions
+- Optimize gas usage
+- Submit transactions to flashbots or similar services
+- Handle transaction confirmation and errors
+
+## Data Flow
+
+1. Arbitrum Monitor detects new blocks and transactions
+2. Potential swap transactions are sent to Market Scanner
+3. Market Scanner analyzes swaps and identifies opportunities
+4. Profitable opportunities are sent to Transaction Executor
+5. Transaction Executor constructs and submits arbitrage transactions
+
+## Configuration
+
+The bot is configured through config/config.yaml which allows customization of:
+- Arbitrum RPC endpoints
+- Polling intervals
+- Profit thresholds
+- Gas price multipliers
+- Logging settings

docs/monitoring.md

@@ -0,0 +1,40 @@
+# Monitoring System Documentation
+
+This document explains how the MEV bot monitors the Arbitrum sequencer for potential swap transactions.
+
+## Overview
+
+The monitoring system connects to an Arbitrum RPC endpoint and continuously monitors for new blocks and transactions. It identifies potential swap transactions and forwards them to the market scanner for analysis.
+
+## Components
+
+### ArbitrumMonitor
+The main monitoring component that handles:
+- Connecting to the Arbitrum RPC endpoint
+- Polling for new blocks
+- Processing transactions in new blocks
+- Identifying potential swap transactions
+
+### Transaction Processing
+Each transaction is analyzed to determine if it's a potential swap:
+1. Check if the transaction is calling a known DEX contract
+2. Decode the transaction data to extract swap parameters
+3. Extract token addresses and amounts
+4. Calculate potential price impact
+
+## Configuration
+
+The monitoring system is configured through config/config.yaml:
+- `arbitrum.rpc_endpoint`: The RPC endpoint to connect to
+- `bot.polling_interval`: How often to check for new blocks
+- `arbitrum.chain_id`: The chain ID to ensure we're on the correct network
+
+## Implementation Details
+
+The monitor uses the go-ethereum library to interact with the Arbitrum network. It implements efficient polling to minimize RPC calls while ensuring timely detection of new blocks.
+
+Key features:
+- Graceful error handling and reconnection
+- Configurable polling intervals
+- Transaction sender identification
+- Support for both RPC and WebSocket endpoints

docs/uniswap-pricing.md

@@ -0,0 +1,57 @@
+# Uniswap V3 Pricing Documentation
+
+This document explains the Uniswap V3 pricing model and how it's implemented in the MEV bot.
+
+## Core Concepts
+
+### Ticks
+In Uniswap V3, prices are represented as ticks. A tick is defined as:
+
+```
+tick = log√1.0001(√P)
+```
+
+Where P is the price of token1 in terms of token0.
+
+Ticks are integers that range from -887272 to 887272.
+
+### sqrtPriceX96
+Prices are stored internally as sqrtPriceX96, which is:
+
+```
+sqrtPriceX96 = √P * 2^96
+```
+
+This allows for precise fixed-point arithmetic without floating-point operations.
+
+### Liquidity
+Liquidity in a pool is represented as a uint128 value that determines the depth of the pool at a given price.
+
+## Mathematical Relationships
+
+### Converting between representations
+
+1. Tick to sqrtPriceX96:
+   ```
+   sqrtPriceX96 = 1.0001^(tick/2) * 2^96
+   ```
+
+2. sqrtPriceX96 to Tick:
+   ```
+   tick = log_1.0001(sqrtPriceX96 / 2^96)^2
+   ```
+
+3. Price to Tick:
+   ```
+   tick = log_1.0001(price)
+   ```
+
+## Implementation Details
+
+Our Go implementation uses the math/big package for precision and handles the fixed-point arithmetic required for Uniswap V3 calculations.
+
+Key functions:
+- `SqrtPriceX96ToPrice`: Converts sqrtPriceX96 to a floating-point price
+- `PriceToSqrtPriceX96`: Converts a floating-point price to sqrtPriceX96
+- `TickToSqrtPriceX96`: Converts a tick to sqrtPriceX96
+- `SqrtPriceX96ToTick`: Converts sqrtPriceX96 to a tick