@intentsolutionsio/mempool-analyzer 1.0.0

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

@@ -0,0 +1,299 @@
+#!/usr/bin/env python3
+"""
+Gas Price Analyzer
+
+Analyze gas prices and recommend optimal fees.
+
+Author: Jeremy Longshore <jeremy@intentsolutions.io>
+Version: 1.0.0
+License: MIT
+"""
+
+from typing import Dict, Any, List, Optional
+from dataclasses import dataclass
+import statistics
+
+
+@dataclass
+class GasRecommendation:
+    """Gas price recommendation."""
+    priority: str  # slow, standard, fast, instant
+    max_fee: int  # in wei
+    priority_fee: int  # in wei
+    estimated_wait: str  # e.g., "2-5 blocks"
+    confidence: float  # 0.0 to 1.0
+
+
+@dataclass
+class GasDistribution:
+    """Gas price distribution analysis."""
+    min_gwei: float
+    max_gwei: float
+    mean_gwei: float
+    median_gwei: float
+    p10_gwei: float  # 10th percentile
+    p25_gwei: float  # 25th percentile
+    p50_gwei: float  # 50th percentile
+    p75_gwei: float  # 75th percentile
+    p90_gwei: float  # 90th percentile
+    sample_count: int
+
+
+class GasAnalyzer:
+    """Analyze mempool gas prices and provide recommendations."""
+
+    def __init__(self, verbose: bool = False):
+        """Initialize gas analyzer."""
+        self.verbose = verbose
+
+    def analyze_pending_gas(
+        self,
+        pending_txs: List[Any],
+        base_fee: int = None
+    ) -> GasDistribution:
+        """Analyze gas price distribution in pending transactions.
+
+        Args:
+            pending_txs: List of pending transactions
+            base_fee: Current base fee in wei
+
+        Returns:
+            GasDistribution with statistics
+        """
+        # Extract gas prices
+        gas_prices = []
+        for tx in pending_txs:
+            if hasattr(tx, "gas_price"):
+                gas_prices.append(tx.gas_price)
+            elif isinstance(tx, dict) and "gasPrice" in tx:
+                price = tx["gasPrice"]
+                if isinstance(price, str):
+                    price = int(price, 16)
+                gas_prices.append(price)
+
+        if not gas_prices:
+            # Return defaults if no data
+            default_gwei = 30.0
+            return GasDistribution(
+                min_gwei=default_gwei,
+                max_gwei=default_gwei,
+                mean_gwei=default_gwei,
+                median_gwei=default_gwei,
+                p10_gwei=default_gwei - 5,
+                p25_gwei=default_gwei - 2,
+                p50_gwei=default_gwei,
+                p75_gwei=default_gwei + 5,
+                p90_gwei=default_gwei + 10,
+                sample_count=0,
+            )
+
+        # Convert to gwei
+        gwei_prices = [p / 10**9 for p in gas_prices]
+        sorted_prices = sorted(gwei_prices)
+        n = len(sorted_prices)
+
+        def percentile(p: float) -> float:
+            idx = int(n * p / 100)
+            return sorted_prices[min(idx, n - 1)]
+
+        return GasDistribution(
+            min_gwei=min(gwei_prices),
+            max_gwei=max(gwei_prices),
+            mean_gwei=statistics.mean(gwei_prices),
+            median_gwei=statistics.median(gwei_prices),
+            p10_gwei=percentile(10),
+            p25_gwei=percentile(25),
+            p50_gwei=percentile(50),
+            p75_gwei=percentile(75),
+            p90_gwei=percentile(90),
+            sample_count=n,
+        )
+
+    def recommend_gas(
+        self,
+        distribution: GasDistribution = None,
+        base_fee: int = None,
+        priority: str = "standard"
+    ) -> GasRecommendation:
+        """Get gas price recommendation.
+
+        Args:
+            distribution: Gas distribution from analyze_pending_gas
+            base_fee: Current base fee in wei
+            priority: slow, standard, fast, or instant
+
+        Returns:
+            GasRecommendation
+        """
+        # Use distribution or defaults
+        if distribution:
+            prices = {
+                "slow": distribution.p10_gwei,
+                "standard": distribution.p50_gwei,
+                "fast": distribution.p75_gwei,
+                "instant": distribution.p90_gwei,
+            }
+        else:
+            # Default recommendations
+            prices = {
+                "slow": 25,
+                "standard": 35,
+                "fast": 50,
+                "instant": 75,
+            }
+
+        wait_times = {
+            "slow": "10+ blocks (~3 min)",
+            "standard": "2-5 blocks (~1 min)",
+            "fast": "1-2 blocks (~30 sec)",
+            "instant": "Next block (~12 sec)",
+        }
+
+        confidence = {
+            "slow": 0.7,
+            "standard": 0.9,
+            "fast": 0.95,
+            "instant": 0.99,
+        }
+
+        selected_gwei = prices.get(priority, prices["standard"])
+
+        # Calculate max fee and priority fee
+        if base_fee:
+            base_gwei = base_fee / 10**9
+            priority_fee_gwei = max(selected_gwei - base_gwei, 1.0)
+            # Max fee should be 2x base fee + priority to handle base fee spikes
+            max_fee_gwei = base_gwei * 2 + priority_fee_gwei
+        else:
+            priority_fee_gwei = 2.0
+            max_fee_gwei = selected_gwei
+
+        return GasRecommendation(
+            priority=priority,
+            max_fee=int(max_fee_gwei * 10**9),
+            priority_fee=int(priority_fee_gwei * 10**9),
+            estimated_wait=wait_times.get(priority, "Unknown"),
+            confidence=confidence.get(priority, 0.5),
+        )
+
+    def estimate_inclusion_time(
+        self,
+        gas_price: int,
+        distribution: GasDistribution
+    ) -> str:
+        """Estimate time to transaction inclusion.
+
+        Args:
+            gas_price: Your gas price in wei
+            distribution: Current gas distribution
+
+        Returns:
+            Estimated wait time string
+        """
+        gwei = gas_price / 10**9
+
+        if gwei >= distribution.p90_gwei:
+            return "Next block (~12 sec)"
+        elif gwei >= distribution.p75_gwei:
+            return "1-2 blocks (~30 sec)"
+        elif gwei >= distribution.p50_gwei:
+            return "2-5 blocks (~1 min)"
+        elif gwei >= distribution.p25_gwei:
+            return "5-10 blocks (~2 min)"
+        elif gwei >= distribution.p10_gwei:
+            return "10+ blocks (~3+ min)"
+        else:
+            return "May not be included"
+
+    def format_distribution(self, dist: GasDistribution) -> str:
+        """Format gas distribution for display.
+
+        Args:
+            dist: GasDistribution to format
+
+        Returns:
+            Formatted string
+        """
+        lines = [
+            "",
+            "GAS PRICE DISTRIBUTION",
+            "=" * 50,
+            f"Sample Size: {dist.sample_count} pending transactions",
+            "",
+            f"  Min:    {dist.min_gwei:6.1f} gwei",
+            f"  10th%:  {dist.p10_gwei:6.1f} gwei (Slow)",
+            f"  25th%:  {dist.p25_gwei:6.1f} gwei",
+            f"  50th%:  {dist.p50_gwei:6.1f} gwei (Standard)",
+            f"  75th%:  {dist.p75_gwei:6.1f} gwei (Fast)",
+            f"  90th%:  {dist.p90_gwei:6.1f} gwei (Instant)",
+            f"  Max:    {dist.max_gwei:6.1f} gwei",
+            "",
+            f"  Mean:   {dist.mean_gwei:6.1f} gwei",
+            f"  Median: {dist.median_gwei:6.1f} gwei",
+            "=" * 50,
+        ]
+        return "\n".join(lines)
+
+    def format_recommendations(self, base_fee: int = None) -> str:
+        """Format all gas recommendations for display.
+
+        Args:
+            base_fee: Current base fee in wei
+
+        Returns:
+            Formatted string
+        """
+        lines = [
+            "",
+            "GAS RECOMMENDATIONS",
+            "=" * 60,
+        ]
+
+        if base_fee:
+            lines.append(f"Current Base Fee: {base_fee / 10**9:.1f} gwei")
+            lines.append("")
+
+        lines.append(f"{'Priority':<12} {'Max Fee':<12} {'Priority Fee':<14} {'Est. Wait':<20}")
+        lines.append("-" * 60)
+
+        for priority in ["slow", "standard", "fast", "instant"]:
+            rec = self.recommend_gas(priority=priority, base_fee=base_fee)
+            max_fee_gwei = rec.max_fee / 10**9
+            priority_gwei = rec.priority_fee / 10**9
+            lines.append(
+                f"{priority.capitalize():<12} {max_fee_gwei:<12.1f} {priority_gwei:<14.1f} {rec.estimated_wait:<20}"
+            )
+
+        lines.append("=" * 60)
+        return "\n".join(lines)
+
+
+def main():
+    """CLI entry point for testing."""
+    analyzer = GasAnalyzer(verbose=True)
+
+    # Create mock pending transactions
+    class MockTx:
+        def __init__(self, gas_price):
+            self.gas_price = gas_price
+
+    import random
+    base = 30 * 10**9
+    mock_txs = [MockTx(base + random.randint(-10, 30) * 10**9) for _ in range(100)]
+
+    # Analyze
+    dist = analyzer.analyze_pending_gas(mock_txs, base_fee=base)
+    print(analyzer.format_distribution(dist))
+
+    # Recommendations
+    print(analyzer.format_recommendations(base_fee=base))
+
+    # Test inclusion estimate
+    print("\n=== Inclusion Time Estimates ===")
+    for gwei in [25, 30, 40, 50, 70]:
+        est = analyzer.estimate_inclusion_time(gwei * 10**9, dist)
+        print(f"  {gwei} gwei: {est}")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,320 @@
+#!/usr/bin/env python3
+"""
+Mempool Analyzer CLI
+
+Monitor blockchain mempools for pending transactions and MEV opportunities.
+
+Author: Jeremy Longshore <jeremy@intentsolutions.io>
+Version: 1.0.0
+License: MIT
+
+Usage:
+    python mempool_analyzer.py pending                # View pending transactions
+    python mempool_analyzer.py gas                    # Gas price analysis
+    python mempool_analyzer.py swaps                  # Pending DEX swaps
+    python mempool_analyzer.py mev                    # MEV opportunity scan
+    python mempool_analyzer.py summary                # Overall summary
+"""
+
+import argparse
+import sys
+
+from rpc_client import RPCClient
+from tx_decoder import TransactionDecoder
+from gas_analyzer import GasAnalyzer
+from mev_detector import MEVDetector
+from formatters import (
+    format_pending_tx_table,
+    format_pending_swaps_table,
+    format_mempool_summary,
+    format_json,
+)
+
+
+DEFAULT_ETH_PRICE = 3000.0
+
+
+def cmd_pending(args):
+    """Show pending transactions."""
+    client = RPCClient(
+        rpc_url=args.rpc_url,
+        chain=args.chain,
+        verbose=args.verbose,
+    )
+
+    pending = client.get_pending_transactions(limit=args.limit, allow_mock=args.demo)
+
+    if args.format == "json":
+        print(format_json(pending))
+    else:
+        print(format_pending_tx_table(pending, eth_price=args.eth_price))
+
+
+def cmd_gas(args):
+    """Analyze gas prices."""
+    client = RPCClient(
+        rpc_url=args.rpc_url,
+        chain=args.chain,
+        verbose=args.verbose,
+    )
+    analyzer = GasAnalyzer(verbose=args.verbose)
+
+    # Get gas info
+    gas_info = client.get_gas_price()
+
+    # Get pending transactions for distribution analysis
+    pending = client.get_pending_transactions(limit=200, allow_mock=args.demo)
+    distribution = analyzer.analyze_pending_gas(pending, base_fee=gas_info.base_fee)
+
+    if args.format == "json":
+        result = {
+            "gas_info": vars(gas_info),
+            "distribution": vars(distribution),
+        }
+        print(format_json(result))
+    else:
+        print(analyzer.format_distribution(distribution))
+        print(analyzer.format_recommendations(base_fee=gas_info.base_fee))
+
+
+def cmd_swaps(args):
+    """Show pending DEX swaps."""
+    client = RPCClient(
+        rpc_url=args.rpc_url,
+        chain=args.chain,
+        verbose=args.verbose,
+    )
+    detector = MEVDetector(verbose=args.verbose)
+
+    pending = client.get_pending_transactions(limit=args.limit, allow_mock=args.demo)
+    swaps = detector.detect_pending_swaps(pending, eth_price=args.eth_price)
+
+    if args.format == "json":
+        print(format_json(swaps))
+    else:
+        print(format_pending_swaps_table(swaps))
+
+
+def cmd_mev(args):
+    """Scan for MEV opportunities."""
+    client = RPCClient(
+        rpc_url=args.rpc_url,
+        chain=args.chain,
+        verbose=args.verbose,
+    )
+    detector = MEVDetector(verbose=args.verbose)
+
+    pending = client.get_pending_transactions(limit=args.limit, allow_mock=args.demo)
+    results = detector.detect_all_opportunities(pending, eth_price=args.eth_price)
+
+    if args.format == "json":
+        # Convert opportunities to serializable format
+        serialized = {
+            "pending_swaps": results["pending_swaps"],
+            "sandwich": [vars(o) for o in results["sandwich"]],
+            "arbitrage": [vars(o) for o in results["arbitrage"]],
+            "liquidation": [vars(o) for o in results["liquidation"]],
+        }
+        print(format_json(serialized))
+    else:
+        print(f"\nPending Swaps Analyzed: {results['pending_swaps']}")
+
+        all_opps = results["sandwich"] + results["arbitrage"] + results["liquidation"]
+        print(detector.format_opportunities(all_opps))
+
+
+def cmd_summary(args):
+    """Show mempool summary."""
+    client = RPCClient(
+        rpc_url=args.rpc_url,
+        chain=args.chain,
+        verbose=args.verbose,
+    )
+    detector = MEVDetector(verbose=args.verbose)
+
+    # Gather data
+    gas_info = client.get_gas_price()
+    pending = client.get_pending_transactions(limit=200, allow_mock=args.demo)
+    swaps = detector.detect_pending_swaps(pending, eth_price=args.eth_price)
+    results = detector.detect_all_opportunities(pending, eth_price=args.eth_price)
+
+    total_opportunities = (
+        len(results["sandwich"]) +
+        len(results["arbitrage"]) +
+        len(results["liquidation"])
+    )
+
+    if args.format == "json":
+        summary = {
+            "pending_count": len(pending),
+            "swap_count": len(swaps),
+            "opportunity_count": total_opportunities,
+            "gas_info": vars(gas_info),
+        }
+        print(format_json(summary))
+    else:
+        print(format_mempool_summary(
+            pending_count=len(pending),
+            gas_info=gas_info,
+            swap_count=len(swaps),
+            opportunities=total_opportunities,
+        ))
+
+
+def cmd_watch(args):
+    """Watch contract for pending interactions."""
+    client = RPCClient(
+        rpc_url=args.rpc_url,
+        chain=args.chain,
+        verbose=args.verbose,
+    )
+    decoder = TransactionDecoder(verbose=args.verbose)
+
+    contract = args.contract.lower()
+
+    print(f"\nWatching for pending transactions to: {contract}")
+    print("=" * 60)
+
+    pending = client.get_pending_transactions(limit=args.limit, allow_mock=args.demo)
+
+    matching = [
+        tx for tx in pending
+        if tx.to_address and tx.to_address.lower() == contract
+    ]
+
+    if not matching:
+        print("No pending transactions found for this contract.")
+        return
+
+    if args.format == "json":
+        print(format_json(matching))
+    else:
+        print(f"Found {len(matching)} pending transactions:\n")
+        for tx in matching:
+            decoded = decoder.decode_input(tx.input_data, tx.to_address)
+            print(f"  {tx.hash[:16]}...")
+            print(f"    Method: {decoded.method_name}")
+            print(f"    From: {tx.from_address[:16]}...")
+            print(f"    Gas: {tx.gas_price / 10**9:.1f} gwei")
+            print()
+
+
+def cmd_status(args):
+    """Show connection status."""
+    client = RPCClient(
+        rpc_url=args.rpc_url,
+        chain=args.chain,
+        verbose=args.verbose,
+    )
+
+    print("\nMEMPOOL ANALYZER STATUS")
+    print("=" * 50)
+    print(f"Chain: {args.chain}")
+    print(f"RPC URL: {client.rpc_url[:50]}...")
+
+    try:
+        block = client.get_block_number()
+        print(f"Current Block: {block:,}")
+        print("Connection: OK")
+    except Exception as e:
+        print(f"Connection: Error - {e}")
+
+    gas_info = client.get_gas_price()
+    print(f"\nGas Price: {gas_info.gas_price / 10**9:.1f} gwei")
+    print(f"Base Fee: {gas_info.base_fee / 10**9:.1f} gwei")
+    print("=" * 50)
+
+
+def main():
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description="Mempool Analyzer - Monitor pending transactions and MEV",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  %(prog)s pending                       View pending transactions
+  %(prog)s gas                           Analyze gas prices
+  %(prog)s swaps                         Show pending DEX swaps
+  %(prog)s mev                           Scan for MEV opportunities
+  %(prog)s summary                       Overall mempool summary
+  %(prog)s watch 0x7a250d...             Watch contract for pending txs
+  %(prog)s status                        Check connection status
+  %(prog)s --demo pending                Use mock data for testing
+        """
+    )
+
+    parser.add_argument("-v", "--verbose", action="store_true", help="Verbose output")
+    parser.add_argument("--format", choices=["table", "json"], default="table",
+                        help="Output format")
+    parser.add_argument("--rpc-url", help="Custom RPC URL")
+    parser.add_argument("--chain", default="ethereum",
+                        choices=["ethereum", "polygon", "arbitrum", "optimism", "base"],
+                        help="Blockchain network")
+    parser.add_argument("--eth-price", type=float, default=DEFAULT_ETH_PRICE,
+                        help=f"ETH price for USD conversion (default: {DEFAULT_ETH_PRICE})")
+    parser.add_argument("--demo", action="store_true",
+                        help="Use mock data when RPC fails (for testing/demo)")
+
+    subparsers = parser.add_subparsers(dest="command", help="Command to run")
+
+    # pending command
+    pending_parser = subparsers.add_parser("pending", help="View pending transactions")
+    pending_parser.add_argument("--limit", type=int, default=50,
+                                help="Max transactions to show")
+
+    # gas command
+    subparsers.add_parser("gas", help="Analyze gas prices")
+
+    # swaps command
+    swaps_parser = subparsers.add_parser("swaps", help="Show pending DEX swaps")
+    swaps_parser.add_argument("--limit", type=int, default=100,
+                              help="Max transactions to analyze")
+
+    # mev command
+    mev_parser = subparsers.add_parser("mev", help="Scan for MEV opportunities")
+    mev_parser.add_argument("--limit", type=int, default=200,
+                            help="Max transactions to analyze")
+
+    # summary command
+    subparsers.add_parser("summary", help="Mempool summary")
+
+    # watch command
+    watch_parser = subparsers.add_parser("watch", help="Watch contract for pending txs")
+    watch_parser.add_argument("contract", help="Contract address to watch")
+    watch_parser.add_argument("--limit", type=int, default=100,
+                              help="Max transactions to check")
+
+    # status command
+    subparsers.add_parser("status", help="Check connection status")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        # Default to summary
+        args.command = "summary"
+
+    commands = {
+        "pending": cmd_pending,
+        "gas": cmd_gas,
+        "swaps": cmd_swaps,
+        "mev": cmd_mev,
+        "summary": cmd_summary,
+        "watch": cmd_watch,
+        "status": cmd_status,
+    }
+
+    try:
+        commands[args.command](args)
+    except KeyboardInterrupt:
+        print("\nInterrupted")
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}")
+        if args.verbose:
+            import traceback
+            traceback.print_exc()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()