@intentsolutionsio/mempool-analyzer 1.0.0

package/skills/analyzing-mempool/config/settings.yaml

@@ -0,0 +1,43 @@
+# Mempool Analyzer Configuration
+# Copy to ~/.mempool_analyzer.yaml and customize
+
+# RPC Configuration
+rpc:
+  ethereum: "https://eth.llamarpc.com"
+  polygon: "https://polygon-rpc.com"
+  arbitrum: "https://arb1.arbitrum.io/rpc"
+  optimism: "https://mainnet.optimism.io"
+  base: "https://mainnet.base.org"
+
+# Default Settings
+defaults:
+  chain: "ethereum"
+  limit: 100
+  eth_price: 3000.0
+
+# Gas Analysis
+gas:
+  cache_ttl: 10  # seconds
+  percentiles: [10, 25, 50, 75, 90]
+
+# MEV Detection
+mev:
+  min_swap_value_usd: 10000  # $10k minimum
+  min_profit_usd: 100        # $100 minimum profit
+  detection_types:
+    - sandwich
+    - arbitrage
+    - liquidation
+
+# Known DEX Routers
+routers:
+  uniswap_v2: "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D"
+  uniswap_v3: "0xE592427A0AEce92De3Edee1F18E0157C05861564"
+  sushiswap: "0xd9e1cE17f2641f24aE83637ab66a2cca9C378B9F"
+  oneinch: "0x1111111254fb6c44bac0bed2854e76f90643097d"
+
+# Output Settings
+output:
+  format: "table"
+  max_display: 50
+  show_raw_data: false

package/skills/analyzing-mempool/references/errors.md

@@ -0,0 +1,122 @@
+# Error Handling Guide
+
+## RPC Connection Errors
+
+### Connection Refused
+```
+Error: Connection refused to RPC endpoint
+```
+**Cause**: RPC endpoint is down or unreachable
+**Solution**:
+- Check if RPC URL is correct
+- Try alternative endpoint (Alchemy, Chainstack, Infura, or public RPC)
+- Verify network connectivity
+
+### Timeout
+```
+Error: Request timed out
+```
+**Cause**: RPC node is slow or overloaded
+**Solution**:
+- Increase timeout setting
+- Switch to faster RPC provider
+- Reduce request frequency
+
+### Rate Limited
+```
+Error: Too many requests (429)
+```
+**Cause**: Exceeded RPC provider rate limits
+**Solution**:
+- Reduce polling frequency
+- Upgrade RPC tier (paid Alchemy, Chainstack, or Infura plans)
+- Use multiple RPC endpoints
+
+## Mempool Access Errors
+
+### txpool_content Not Available
+```
+Error: txpool_content not supported
+```
+**Cause**: Not all nodes support txpool methods
+**Solution**:
+- Use Geth node with txpool enabled
+- Try eth_pendingTransactions instead
+- Use mock data for demo purposes
+
+### Empty Mempool
+```
+No pending transactions found
+```
+**Cause**: Mempool is empty or access limited
+**Solution**:
+- Normal during low activity periods
+- Verify RPC supports mempool access
+- Check if node is fully synced
+
+## Transaction Decoding Errors
+
+### Unknown Method Signature
+```
+Warning: Unknown method 0x12345678
+```
+**Cause**: Method signature not in known ABI list
+**Solution**:
+- Transaction will show as "Unknown" type
+- Add ABI to decoder if needed
+- Use Etherscan to look up contract ABI
+
+### Invalid Input Data
+```
+Error: Cannot decode input data
+```
+**Cause**: Malformed or non-standard input
+**Solution**:
+- Skip transaction, continue analysis
+- Raw data still available
+
+## Gas Analysis Errors
+
+### No Sample Data
+```
+Warning: Insufficient data for gas analysis
+```
+**Cause**: Too few pending transactions
+**Solution**:
+- Use default recommendations
+- Wait for more mempool activity
+- Reduce sample requirements
+
+## MEV Detection Errors
+
+### Pool Data Unavailable
+```
+Warning: Cannot fetch pool reserves
+```
+**Cause**: DEX subgraph or pool query failed
+**Solution**:
+- MEV detection will have lower confidence
+- Use estimated values
+- Check subgraph health
+
+## Debugging
+
+### Enable Verbose Mode
+```bash
+python mempool_analyzer.py -v pending
+```
+
+### Check Connection
+```bash
+python mempool_analyzer.py status
+```
+
+### Test RPC Endpoint
+```bash
+curl -X POST -H "Content-Type: application/json" \
+  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
+  YOUR_RPC_URL
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/analyzing-mempool/references/examples.md

@@ -0,0 +1,189 @@
+# Usage Examples
+
+## View Pending Transactions
+
+### Basic View
+```bash
+python mempool_analyzer.py pending
+```
+
+### Limit Results
+```bash
+python mempool_analyzer.py pending --limit 20
+```
+
+### JSON Output
+```bash
+python mempool_analyzer.py pending --format json
+```
+
+## Gas Price Analysis
+
+### Current Gas Prices
+```bash
+python mempool_analyzer.py gas
+```
+
+### Gas Recommendations
+```bash
+python mempool_analyzer.py gas
+# Output shows:
+# - Current base fee
+# - Gas price distribution (10th, 25th, 50th, 75th, 90th percentile)
+# - Recommendations for slow, standard, fast, instant
+```
+
+### JSON for Programmatic Use
+```bash
+python mempool_analyzer.py gas --format json
+```
+
+## Pending DEX Swaps
+
+### View All Pending Swaps
+```bash
+python mempool_analyzer.py swaps
+```
+
+### Analyze More Transactions
+```bash
+python mempool_analyzer.py swaps --limit 200
+```
+
+## MEV Opportunity Scanning
+
+### Scan for Opportunities
+```bash
+python mempool_analyzer.py mev
+```
+
+### Detailed Analysis
+```bash
+python mempool_analyzer.py mev --limit 300 -v
+```
+
+### JSON Output
+```bash
+python mempool_analyzer.py mev --format json
+```
+
+## Mempool Summary
+
+### Quick Overview
+```bash
+python mempool_analyzer.py summary
+```
+
+## Watch Specific Contract
+
+### Monitor Uniswap Router
+```bash
+python mempool_analyzer.py watch 0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D
+```
+
+### Monitor Any Contract
+```bash
+python mempool_analyzer.py watch 0xYOUR_CONTRACT_ADDRESS --limit 200
+```
+
+## Connection Status
+
+### Check RPC Connection
+```bash
+python mempool_analyzer.py status
+```
+
+## Different Chains
+
+### Polygon
+```bash
+python mempool_analyzer.py --chain polygon pending
+python mempool_analyzer.py --chain polygon gas
+```
+
+### Arbitrum
+```bash
+python mempool_analyzer.py --chain arbitrum summary
+```
+
+### Custom RPC URL
+```bash
+python mempool_analyzer.py --rpc-url https://your-rpc.example.com pending
+```
+
+## Common Workflows
+
+### Pre-Transaction Gas Check
+```bash
+# Before sending a transaction, check optimal gas
+python mempool_analyzer.py gas
+
+# Use "Fast" recommendation for quick confirmation
+# Use "Standard" for normal priority
+# Use "Slow" if not time-sensitive
+```
+
+### Monitor for Front-Running Risk
+```bash
+# Check if there are pending swaps that might affect your trade
+python mempool_analyzer.py swaps
+
+# High-value pending swaps = potential slippage
+```
+
+### MEV Opportunity Research
+```bash
+# Educational: See what MEV opportunities exist
+python mempool_analyzer.py mev -v
+
+# Note: This is for research/education only
+# Real MEV extraction requires specialized infrastructure
+```
+
+## Programmatic Usage
+
+```python
+from rpc_client import RPCClient
+from gas_analyzer import GasAnalyzer
+from mev_detector import MEVDetector
+
+# Initialize
+client = RPCClient()
+gas_analyzer = GasAnalyzer()
+mev_detector = MEVDetector()
+
+# Get pending transactions
+pending = client.get_pending_transactions(limit=100)
+
+# Analyze gas
+gas_info = client.get_gas_price()
+distribution = gas_analyzer.analyze_pending_gas(pending)
+
+print(f"Median gas: {distribution.median_gwei:.1f} gwei")
+
+# Detect swaps
+swaps = mev_detector.detect_pending_swaps(pending)
+print(f"Pending swaps: {len(swaps)}")
+```
+
+## Integration with jq
+
+### Filter High Gas Transactions
+```bash
+python mempool_analyzer.py pending --format json | \
+  jq '[.[] | select(.gas_price > 50000000000)]'
+```
+
+### Count by Transaction Type
+```bash
+python mempool_analyzer.py swaps --format json | \
+  jq 'group_by(.dex) | map({dex: .[0].dex, count: length})'
+```
+
+### Export Gas Data
+```bash
+python mempool_analyzer.py gas --format json > gas_snapshot.json
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/analyzing-mempool/references/implementation.md

@@ -0,0 +1,67 @@
+# Implementation Details
+
+## Gas Price Distribution Analysis
+
+The gas analysis command calculates percentile-based recommendations from pending transactions:
+
+**Gas Recommendations:**
+- Slow (10th percentile): May take 10+ blocks
+- Standard (50th percentile): 2-5 blocks
+- Fast (75th percentile): 1-2 blocks
+- Instant (90th percentile): Next block likely
+
+## MEV Detection Details
+
+MEV detection scans for common patterns:
+- **Sandwich attacks**: Detects front-run + back-run pairs targeting the same swap
+- **Arbitrage**: Identifies circular token paths (A→B→A) across DEXs
+- **Liquidation**: Finds health-factor monitoring and repay+seize patterns
+
+**Important:** MEV detection is for educational purposes only. Real MEV extraction requires:
+- Specialized block-builder infrastructure (Flashbots, MEV-Boost)
+- Sub-millisecond execution timing
+- Significant capital for gas auctions
+
+## DEX Swap Detection
+
+The `swaps` command identifies pending DEX transactions by matching method selectors:
+- Uniswap V2/V3: `swapExactTokensForTokens`, `exactInputSingle`
+- SushiSwap: Same interface as Uniswap V2
+- 1inch: `swap`, `unoswap` aggregation methods
+
+## Multi-Chain Support
+
+Supported chains and their mempool characteristics:
+| Chain | Mempool Access | Block Time | Notes |
+|-------|---------------|------------|-------|
+| Ethereum | Full | ~12s | Richest MEV environment |
+| Polygon | Full | ~2s | Lower gas, faster blocks |
+| Arbitrum | Limited | ~0.25s | Sequencer-based, less MEV |
+| Optimism | Limited | ~2s | Sequencer-based |
+| Base | Limited | ~2s | Coinbase sequencer |
+
+## Contract Watching
+
+The `watch` command monitors pending transactions to a specific contract address:
+1. Filters mempool by `to` address
+2. Decodes known method selectors
+3. Estimates gas cost in USD
+4. Identifies transaction type (swap, approve, transfer, etc.)
+
+## Configuration
+
+Edit `${CLAUDE_SKILL_DIR}/config/settings.yaml`:
+```yaml
+rpc_endpoints:
+  ethereum: "https://rpc.ankr.com/eth"
+  polygon: "https://rpc.ankr.com/polygon"
+  arbitrum: "https://rpc.ankr.com/arbitrum"
+
+defaults:
+  chain: ethereum
+  limit: 50
+  output_format: table
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/analyzing-mempool/scripts/formatters.py

@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+"""
+Mempool Analyzer Formatters
+
+Format mempool data for various outputs.
+
+Author: Jeremy Longshore <jeremy@intentsolutions.io>
+Version: 1.0.0
+License: MIT
+"""
+
+import json
+from datetime import datetime
+from typing import Any, List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tx_decoder import TransactionDecoder
+
+
+def format_gwei(wei: int) -> str:
+    """Format wei as gwei."""
+    gwei = wei / 10**9
+    return f"{gwei:.1f} gwei"
+
+
+def format_eth(wei: int) -> str:
+    """Format wei as ETH."""
+    eth = wei / 10**18
+    if eth >= 1:
+        return f"{eth:.4f} ETH"
+    else:
+        return f"{eth:.6f} ETH"
+
+
+def format_usd(value: float) -> str:
+    """Format USD value."""
+    if value >= 1e6:
+        return f"${value / 1e6:.2f}M"
+    elif value >= 1e3:
+        return f"${value / 1e3:.1f}K"
+    else:
+        return f"${value:,.2f}"
+
+
+def format_address(address: str, length: int = 12) -> str:
+    """Truncate address for display."""
+    if not address:
+        return "N/A"
+    if len(address) <= length:
+        return address
+    half = (length - 3) // 2
+    return f"{address[:half]}...{address[-half:]}"
+
+
+def format_pending_tx_table(
+    transactions: List[Any],
+    eth_price: float = 3000.0,
+    decoder: Optional["TransactionDecoder"] = None,
+) -> str:
+    """Format pending transactions as table.
+
+    Args:
+        transactions: List of PendingTransaction objects
+        eth_price: Current ETH price for USD conversion
+        decoder: Optional TransactionDecoder instance (created if not provided)
+
+    Returns:
+        Formatted table string
+    """
+    if not transactions:
+        return "No pending transactions."
+
+    lines = [
+        "",
+        "PENDING TRANSACTIONS",
+        "=" * 100,
+        f"{'Hash':<18} {'From':<14} {'To':<14} {'Value':<12} {'Gas Price':<12} {'Gas':<10} {'Type':<12}",
+        "-" * 100,
+    ]
+
+    # Create decoder only if not provided
+    if decoder is None:
+        from tx_decoder import TransactionDecoder
+        decoder = TransactionDecoder()
+
+    for tx in transactions[:50]:
+        tx_hash = format_address(tx.hash, 16)
+        from_addr = format_address(tx.from_address, 12)
+        to_addr = format_address(tx.to_address or "Contract", 12)
+
+        # Value
+        if tx.value > 0:
+            value_str = format_eth(tx.value)
+        else:
+            value_str = "0"
+
+        gas_price_str = format_gwei(tx.gas_price)
+        gas_str = f"{tx.gas:,}"
+
+        # Decode type
+        decoded = decoder.decode_input(tx.input_data, tx.to_address)
+        tx_type = decoded.method_type[:10]
+
+        lines.append(f"{tx_hash:<18} {from_addr:<14} {to_addr:<14} {value_str:<12} {gas_price_str:<12} {gas_str:<10} {tx_type:<12}")
+
+    lines.append("-" * 100)
+    lines.append(f"Showing {min(len(transactions), 50)} of {len(transactions)} pending transactions")
+
+    return "\n".join(lines)
+
+
+def format_pending_swaps_table(swaps: List[Any]) -> str:
+    """Format pending swaps as table.
+
+    Args:
+        swaps: List of PendingSwap objects
+
+    Returns:
+        Formatted table string
+    """
+    if not swaps:
+        return "No pending swaps detected."
+
+    lines = [
+        "",
+        "PENDING DEX SWAPS",
+        "=" * 90,
+        f"{'Hash':<18} {'DEX':<20} {'Amount In':<16} {'Gas Price':<12} {'From':<14}",
+        "-" * 90,
+    ]
+
+    for swap in swaps[:30]:
+        tx_hash = format_address(swap.tx_hash, 16)
+        dex = swap.dex[:18] if swap.dex else "Unknown"
+
+        if swap.amount_in:
+            amount = format_eth(swap.amount_in)
+        else:
+            amount = "Unknown"
+
+        gas_price = format_gwei(swap.gas_price)
+        from_addr = format_address(swap.from_address, 12)
+
+        lines.append(f"{tx_hash:<18} {dex:<20} {amount:<16} {gas_price:<12} {from_addr:<14}")
+
+    lines.append("-" * 90)
+    lines.append(f"Total: {len(swaps)} pending swaps")
+
+    return "\n".join(lines)
+
+
+def format_mempool_summary(
+    pending_count: int,
+    gas_info: Any,
+    swap_count: int,
+    opportunities: int
+) -> str:
+    """Format mempool summary.
+
+    Args:
+        pending_count: Number of pending transactions
+        gas_info: GasInfo object
+        swap_count: Number of pending swaps
+        opportunities: Number of MEV opportunities
+
+    Returns:
+        Formatted summary string
+    """
+    lines = [
+        "",
+        "MEMPOOL SUMMARY",
+        "=" * 50,
+        f"Pending Transactions: {pending_count:,}",
+        f"Pending Swaps:        {swap_count}",
+        f"MEV Opportunities:    {opportunities}",
+        "",
+        "Gas Prices:",
+        f"  Base Fee:     {format_gwei(gas_info.base_fee)}",
+        f"  Priority Fee: {format_gwei(gas_info.priority_fee)}",
+        f"  Gas Price:    {format_gwei(gas_info.gas_price)}",
+        "=" * 50,
+    ]
+
+    return "\n".join(lines)
+
+
+def format_json(data: Any) -> str:
+    """Format data as JSON."""
+    if hasattr(data, "__iter__") and not isinstance(data, (str, dict)):
+        serialized = []
+        for item in data:
+            if hasattr(item, "__dict__"):
+                serialized.append(vars(item))
+            else:
+                serialized.append(item)
+        return json.dumps(serialized, indent=2, default=str)
+    elif hasattr(data, "__dict__"):
+        return json.dumps(vars(data), indent=2, default=str)
+    else:
+        return json.dumps(data, indent=2, default=str)
+
+
+def format_stream_alert(
+    tx: Any,
+    decoder: Optional["TransactionDecoder"] = None,
+) -> str:
+    """Format single transaction for stream output.
+
+    Args:
+        tx: Transaction object
+        decoder: Optional TransactionDecoder instance (created if not provided)
+
+    Returns:
+        Single-line alert string
+    """
+    timestamp = datetime.now().strftime("%H:%M:%S")
+    tx_hash = format_address(tx.hash, 12)
+    gas_price = tx.gas_price / 10**9
+
+    # Create decoder only if not provided
+    if decoder is None:
+        from tx_decoder import TransactionDecoder
+        decoder = TransactionDecoder()
+    decoded = decoder.decode_input(tx.input_data, tx.to_address)
+
+    if tx.value > 0:
+        value = format_eth(tx.value)
+        return f"[{timestamp}] {tx_hash} | {gas_price:.1f} gwei | {value} | {decoded.method_type}"
+    else:
+        return f"[{timestamp}] {tx_hash} | {gas_price:.1f} gwei | {decoded.method_name}"
+
+
+def main():
+    """CLI entry point for testing."""
+    # Test formatting functions
+    print("=== Format Tests ===")
+    print(f"Gwei: {format_gwei(30 * 10**9)}")
+    print(f"ETH: {format_eth(1.5 * 10**18)}")
+    print(f"USD: {format_usd(1234567)}")
+    print(f"Address: {format_address('0x1234567890abcdef1234567890abcdef12345678')}")
+
+
+if __name__ == "__main__":
+    main()