@intentsolutionsio/mempool-analyzer 1.0.0

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

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+"""
+Transaction Decoder
+
+Decode Ethereum transaction input data using known ABIs.
+
+Author: Jeremy Longshore <jeremy@intentsolutions.io>
+Version: 1.0.0
+License: MIT
+"""
+
+from typing import Any, Dict, Optional
+from dataclasses import dataclass
+
+
+# Common DEX method signatures (first 4 bytes of keccak256)
+METHOD_SIGNATURES = {
+    # Uniswap V2 Router
+    "0x38ed1739": {"name": "swapExactTokensForTokens", "type": "swap"},
+    "0x8803dbee": {"name": "swapTokensForExactTokens", "type": "swap"},
+    "0x7ff36ab5": {"name": "swapExactETHForTokens", "type": "swap"},
+    "0x4a25d94a": {"name": "swapTokensForExactETH", "type": "swap"},
+    "0x18cbafe5": {"name": "swapExactTokensForETH", "type": "swap"},
+    "0xfb3bdb41": {"name": "swapETHForExactTokens", "type": "swap"},
+    "0xe8e33700": {"name": "addLiquidity", "type": "liquidity"},
+    "0xf305d719": {"name": "addLiquidityETH", "type": "liquidity"},
+    "0xbaa2abde": {"name": "removeLiquidity", "type": "liquidity"},
+    "0x02751cec": {"name": "removeLiquidityETH", "type": "liquidity"},
+
+    # Uniswap V3 Router
+    "0x414bf389": {"name": "exactInputSingle", "type": "swap"},
+    "0xc04b8d59": {"name": "exactInput", "type": "swap"},
+    "0xdb3e2198": {"name": "exactOutputSingle", "type": "swap"},
+    "0xf28c0498": {"name": "exactOutput", "type": "swap"},
+    "0x5ae401dc": {"name": "multicall", "type": "multicall"},
+    "0xac9650d8": {"name": "multicall", "type": "multicall"},
+
+    # ERC20
+    "0xa9059cbb": {"name": "transfer", "type": "transfer"},
+    "0x23b872dd": {"name": "transferFrom", "type": "transfer"},
+    "0x095ea7b3": {"name": "approve", "type": "approval"},
+
+    # Common
+    "0x": {"name": "ETH Transfer", "type": "transfer"},
+}
+
+# Known contract addresses
+KNOWN_CONTRACTS = {
+    # Ethereum Mainnet
+    "0x7a250d5630b4cf539739df2c5dacb4c659f2488d": "Uniswap V2 Router",
+    "0xe592427a0aece92de3edee1f18e0157c05861564": "Uniswap V3 Router",
+    "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45": "Uniswap Universal Router",
+    "0xd9e1ce17f2641f24ae83637ab66a2cca9c378b9f": "SushiSwap Router",
+    "0x1111111254fb6c44bac0bed2854e76f90643097d": "1inch Router",
+    "0xdef1c0ded9bec7f1a1670819833240f027b25eff": "0x Exchange Proxy",
+    "0x881d40237659c251811cec9c364ef91dc08d300c": "Metamask Swap Router",
+
+    # Tokens
+    "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2": "WETH",
+    "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": "USDC",
+    "0xdac17f958d2ee523a2206206994597c13d831ec7": "USDT",
+    "0x6b175474e89094c44da98b954eedeac495271d0f": "DAI",
+}
+
+
+@dataclass
+class DecodedCall:
+    """Decoded function call."""
+    method_name: str
+    method_type: str  # swap, transfer, approval, liquidity, multicall, unknown
+    contract_name: Optional[str]
+    raw_signature: str
+    params: Dict[str, Any]
+
+
+@dataclass
+class SwapInfo:
+    """Detected swap information."""
+    dex: str
+    method: str
+    token_in: Optional[str]
+    token_out: Optional[str]
+    amount_in: Optional[int]
+    amount_out_min: Optional[int]
+    is_exact_input: bool
+
+
+class TransactionDecoder:
+    """Decode Ethereum transaction input data."""
+
+    def __init__(self, verbose: bool = False):
+        """Initialize decoder."""
+        self.verbose = verbose
+
+    def decode_input(self, input_data: str, to_address: str = None) -> DecodedCall:
+        """Decode transaction input data.
+
+        Args:
+            input_data: Transaction input (hex string)
+            to_address: Destination contract address
+
+        Returns:
+            DecodedCall with decoded information
+        """
+        if not input_data or input_data == "0x":
+            return DecodedCall(
+                method_name="ETH Transfer",
+                method_type="transfer",
+                contract_name=self._get_contract_name(to_address) if to_address else None,
+                raw_signature="0x",
+                params={},
+            )
+
+        # Get method signature (first 4 bytes)
+        signature = input_data[:10].lower()
+
+        method_info = METHOD_SIGNATURES.get(signature, {
+            "name": "Unknown",
+            "type": "unknown",
+        })
+
+        contract_name = self._get_contract_name(to_address) if to_address else None
+
+        return DecodedCall(
+            method_name=method_info["name"],
+            method_type=method_info["type"],
+            contract_name=contract_name,
+            raw_signature=signature,
+            params=self._decode_params(input_data, signature),
+        )
+
+    def _get_contract_name(self, address: str) -> Optional[str]:
+        """Get known contract name."""
+        if not address:
+            return None
+        return KNOWN_CONTRACTS.get(address.lower())
+
+    def _decode_params(self, input_data: str, signature: str) -> Dict[str, Any]:
+        """Decode function parameters (simplified)."""
+        if len(input_data) < 10:
+            return {}
+
+        # Remove signature
+        data = input_data[10:]
+        if not data:
+            return {}
+
+        params = {}
+
+        # Parse 32-byte chunks
+        chunks = [data[i:i+64] for i in range(0, len(data), 64)]
+
+        # For swaps, try to extract amounts
+        if signature in ["0x38ed1739", "0x8803dbee"]:
+            # swapExactTokensForTokens / swapTokensForExactTokens
+            if len(chunks) >= 2:
+                params["amountIn"] = int(chunks[0], 16) if chunks[0] else 0
+                params["amountOutMin"] = int(chunks[1], 16) if chunks[1] else 0
+
+        elif signature in ["0x7ff36ab5", "0xfb3bdb41"]:
+            # swapExactETHForTokens / swapETHForExactTokens
+            if len(chunks) >= 1:
+                params["amountOutMin"] = int(chunks[0], 16) if chunks[0] else 0
+
+        elif signature == "0xa9059cbb":
+            # transfer(address, uint256)
+            if len(chunks) >= 2:
+                params["to"] = "0x" + chunks[0][-40:]
+                params["amount"] = int(chunks[1], 16) if chunks[1] else 0
+
+        elif signature == "0x095ea7b3":
+            # approve(address, uint256)
+            if len(chunks) >= 2:
+                params["spender"] = "0x" + chunks[0][-40:]
+                params["amount"] = int(chunks[1], 16) if chunks[1] else 0
+
+        return params
+
+    def identify_dex_swap(self, input_data: str, to_address: str) -> Optional[SwapInfo]:
+        """Identify if transaction is a DEX swap.
+
+        Args:
+            input_data: Transaction input data
+            to_address: Destination address
+
+        Returns:
+            SwapInfo if swap detected, None otherwise
+        """
+        decoded = self.decode_input(input_data, to_address)
+
+        if decoded.method_type != "swap":
+            return None
+
+        dex = decoded.contract_name or "Unknown DEX"
+        is_exact_input = "exact" in decoded.method_name.lower() and "input" in decoded.method_name.lower()
+
+        return SwapInfo(
+            dex=dex,
+            method=decoded.method_name,
+            token_in=None,  # Would need path decoding
+            token_out=None,
+            amount_in=decoded.params.get("amountIn"),
+            amount_out_min=decoded.params.get("amountOutMin"),
+            is_exact_input=is_exact_input,
+        )
+
+    def classify_transaction(self, tx: Dict) -> str:
+        """Classify transaction type.
+
+        Args:
+            tx: Transaction dict with 'input' and 'to' fields
+
+        Returns:
+            Transaction type string
+        """
+        input_data = tx.get("input_data", "") or tx.get("input", "")
+        to_address = tx.get("to_address", "") or tx.get("to", "")
+
+        decoded = self.decode_input(input_data, to_address)
+        return decoded.method_type
+
+    def estimate_attached_eth_usd_value(
+        self,
+        tx: Dict,
+        eth_price: float = 3000.0
+    ) -> float:
+        """Estimate USD value of ETH attached to transaction (msg.value).
+
+        Note: This only calculates the USD value of ETH sent with the transaction.
+        For token swaps, the actual value is in the tokens being exchanged,
+        not the attached ETH (which is often zero). Use this for ETH transfers
+        or transactions that include ETH payment.
+
+        Args:
+            tx: Transaction dict with 'value' field (in wei)
+            eth_price: Current ETH price in USD
+
+        Returns:
+            USD value of attached ETH (not the full transaction value for swaps)
+        """
+        value_wei = tx.get("value", 0)
+        if isinstance(value_wei, str):
+            value_wei = int(value_wei, 16) if value_wei.startswith("0x") else int(value_wei)
+
+        value_eth = value_wei / 10**18
+        return value_eth * eth_price
+
+    # Backward compatibility alias
+    estimate_usd_value = estimate_attached_eth_usd_value
+
+
+def main():
+    """CLI entry point for testing."""
+    decoder = TransactionDecoder(verbose=True)
+
+    # Test decode
+    test_cases = [
+        ("0x38ed1739" + "0" * 256, "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D"),
+        ("0xa9059cbb" + "0" * 128, "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"),
+        ("0x", None),
+    ]
+
+    print("=== Transaction Decoding Tests ===")
+    for input_data, to_addr in test_cases:
+        decoded = decoder.decode_input(input_data, to_addr)
+        print(f"\nInput: {input_data[:20]}...")
+        print(f"  Method: {decoded.method_name}")
+        print(f"  Type: {decoded.method_type}")
+        print(f"  Contract: {decoded.contract_name or 'Unknown'}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/skill-adapter/assets/README.md

@@ -0,0 +1,6 @@
+# Assets
+
+Bundled resources for mempool-analyzer skill
+
+- [ ] alert_templates/: Directory containing templates for different types of alerts (email, Slack, etc.).
+- [ ] example_transactions/: Directory containing example transactions for analysis.

package/skills/skill-adapter/assets/config-template.json

@@ -0,0 +1,32 @@
+{
+  "skill": {
+    "name": "skill-name",
+    "version": "1.0.0",
+    "enabled": true,
+    "settings": {
+      "verbose": false,
+      "autoActivate": true,
+      "toolRestrictions": true
+    }
+  },
+  "triggers": {
+    "keywords": [
+      "example-trigger-1",
+      "example-trigger-2"
+    ],
+    "patterns": []
+  },
+  "tools": {
+    "allowed": [
+      "Read",
+      "Grep",
+      "Bash"
+    ],
+    "restricted": []
+  },
+  "metadata": {
+    "author": "Plugin Author",
+    "category": "general",
+    "tags": []
+  }
+}

package/skills/skill-adapter/assets/skill-schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Claude Skill Configuration",
+  "type": "object",
+  "required": ["name", "description"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$",
+      "maxLength": 64,
+      "description": "Skill identifier (lowercase, hyphens only)"
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 1024,
+      "description": "What the skill does and when to use it"
+    },
+    "allowed-tools": {
+      "type": "string",
+      "description": "Comma-separated list of allowed tools"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version (x.y.z)"
+    }
+  }
+}

package/skills/skill-adapter/assets/test-data.json

@@ -0,0 +1,27 @@
+{
+  "testCases": [
+    {
+      "name": "Basic activation test",
+      "input": "trigger phrase example",
+      "expected": {
+        "activated": true,
+        "toolsUsed": ["Read", "Grep"],
+        "success": true
+      }
+    },
+    {
+      "name": "Complex workflow test",
+      "input": "multi-step trigger example",
+      "expected": {
+        "activated": true,
+        "steps": 3,
+        "toolsUsed": ["Read", "Write", "Bash"],
+        "success": true
+      }
+    }
+  ],
+  "fixtures": {
+    "sampleInput": "example data",
+    "expectedOutput": "processed result"
+  }
+}

package/skills/skill-adapter/references/README.md

@@ -0,0 +1,4 @@
+# References
+
+Bundled resources for mempool-analyzer skill
+

package/skills/skill-adapter/references/best-practices.md

@@ -0,0 +1,69 @@
+# Skill Best Practices
+
+Guidelines for optimal skill usage and development.
+
+## For Users
+
+### Activation Best Practices
+
+1. **Use Clear Trigger Phrases**
+   - Match phrases from skill description
+   - Be specific about intent
+   - Provide necessary context
+
+2. **Provide Sufficient Context**
+   - Include relevant file paths
+   - Specify scope of analysis
+   - Mention any constraints
+
+3. **Understand Tool Permissions**
+   - Check allowed-tools in frontmatter
+   - Know what the skill can/cannot do
+   - Request appropriate actions
+
+### Workflow Optimization
+
+- Start with simple requests
+- Build up to complex workflows
+- Verify each step before proceeding
+- Use skill consistently for related tasks
+
+## For Developers
+
+### Skill Development Guidelines
+
+1. **Clear Descriptions**
+   - Include explicit trigger phrases
+   - Document all capabilities
+   - Specify limitations
+
+2. **Proper Tool Permissions**
+   - Use minimal necessary tools
+   - Document security implications
+   - Test with restricted tools
+
+3. **Comprehensive Documentation**
+   - Provide usage examples
+   - Document common pitfalls
+   - Include troubleshooting guide
+
+### Maintenance
+
+- Keep version updated
+- Test after tool updates
+- Monitor user feedback
+- Iterate on descriptions
+
+## Performance Tips
+
+- Scope skills to specific domains
+- Avoid overlapping trigger phrases
+- Keep descriptions under 1024 chars
+- Test activation reliability
+
+## Security Considerations
+
+- Never include secrets in skill files
+- Validate all inputs
+- Use read-only tools when possible
+- Document security requirements

package/skills/skill-adapter/references/examples.md

@@ -0,0 +1,73 @@
+# Skill Usage Examples
+
+This document provides practical examples of how to use this skill effectively.
+
+## Basic Usage
+
+### Example 1: Simple Activation
+
+**User Request:**
+```
+[Describe trigger phrase here]
+```
+
+**Skill Response:**
+1. Analyzes the request
+2. Performs the required action
+3. Returns results
+
+### Example 2: Complex Workflow
+
+**User Request:**
+```
+[Describe complex scenario]
+```
+
+**Workflow:**
+1. Step 1: Initial analysis
+2. Step 2: Data processing
+3. Step 3: Result generation
+4. Step 4: Validation
+
+## Advanced Patterns
+
+### Pattern 1: Chaining Operations
+
+Combine this skill with other tools:
+```
+Step 1: Use this skill for [purpose]
+Step 2: Chain with [other tool]
+Step 3: Finalize with [action]
+```
+
+### Pattern 2: Error Handling
+
+If issues occur:
+- Check trigger phrase matches
+- Verify context is available
+- Review allowed-tools permissions
+
+## Tips & Best Practices
+
+- ✅ Be specific with trigger phrases
+- ✅ Provide necessary context
+- ✅ Check tool permissions match needs
+- ❌ Avoid vague requests
+- ❌ Don't mix unrelated tasks
+
+## Common Issues
+
+**Issue:** Skill doesn't activate
+**Solution:** Use exact trigger phrases from description
+
+**Issue:** Unexpected results
+**Solution:** Check input format and context
+
+## See Also
+
+- Main SKILL.md for full documentation
+- scripts/ for automation helpers
+- assets/ for configuration examples
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/skill-adapter/scripts/README.md

@@ -0,0 +1,8 @@
+# Scripts
+
+Bundled resources for mempool-analyzer skill
+
+- [ ] gas_price_optimizer.py: Script to calculate optimal gas prices based on mempool data and EIP-1559.
+- [ ] mev_detector.py: Script to identify and analyze MEV opportunities (sandwich attacks, arbitrage, liquidations).
+- [ ] transaction_decoder.py: Script to decode transaction calldata and simulate transaction execution.
+- [ ] alert_manager.py: Script to manage and send alerts based on configured thresholds (large transfers, high gas prices, MEV opportunities).

package/skills/skill-adapter/scripts/helper-template.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# Helper script template for skill automation
+# Customize this for your skill's specific needs
+
+set -e
+
+function show_usage() {
+    echo "Usage: $0 [options]"
+    echo ""
+    echo "Options:"
+    echo "  -h, --help     Show this help message"
+    echo "  -v, --verbose  Enable verbose output"
+    echo ""
+}
+
+# Parse arguments
+VERBOSE=false
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -h|--help)
+            show_usage
+            exit 0
+            ;;
+        -v|--verbose)
+            VERBOSE=true
+            shift
+            ;;
+        *)
+            echo "Unknown option: $1"
+            show_usage
+            exit 1
+            ;;
+    esac
+done
+
+# Your skill logic here
+if [ "$VERBOSE" = true ]; then
+    echo "Running skill automation..."
+fi
+
+echo "✅ Complete"

package/skills/skill-adapter/scripts/validation.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# Skill validation helper
+# Validates skill activation and functionality
+
+set -e
+
+echo "🔍 Validating skill..."
+
+# Check if SKILL.md exists
+if [ ! -f "../SKILL.md" ]; then
+    echo "❌ Error: SKILL.md not found"
+    exit 1
+fi
+
+# Validate frontmatter
+if ! grep -q "^---$" "../SKILL.md"; then
+    echo "❌ Error: No frontmatter found"
+    exit 1
+fi
+
+# Check required fields
+if ! grep -q "^name:" "../SKILL.md"; then
+    echo "❌ Error: Missing 'name' field"
+    exit 1
+fi
+
+if ! grep -q "^description:" "../SKILL.md"; then
+    echo "❌ Error: Missing 'description' field"
+    exit 1
+fi
+
+echo "✅ Skill validation passed"