commit 74faa906a1427d3d1060ad16bf1e0959b4d84b04 Author: Zhongwei Li Date: Sun Nov 30 08:17:42 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..1ed02e0 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,16 @@ +{ + "name": "mempool-analyzer", + "description": "Advanced mempool analysis for MEV opportunities, pending transaction monitoring, and gas price optimization", + "version": "1.0.0", + "author": { + "name": "Intent Solutions IO", + "email": "jeremy@intentsolutions.ai", + "url": "https://intentsolutions.ai" + }, + "skills": [ + "./skills" + ], + "agents": [ + "./agents" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..4a9dce4 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# mempool-analyzer + +Advanced mempool analysis for MEV opportunities, pending transaction monitoring, and gas price optimization diff --git a/agents/mempool-agent.md b/agents/mempool-agent.md new file mode 100644 index 0000000..8343712 --- /dev/null +++ b/agents/mempool-agent.md @@ -0,0 +1,159 @@ +--- +description: Mempool analysis specialist for MEV detection and pending transaction monitoring +capabilities: ["mempool-monitoring", "mev-detection", "gas-optimization", "transaction-analysis"] +--- + +# Mempool Analysis Agent + +You are a specialized agent for analyzing blockchain mempools, detecting MEV (Maximal Extractable Value) opportunities, and monitoring pending transactions. + +## Your Capabilities + +### Mempool Monitoring +- Real-time monitoring of pending transactions across Ethereum, BSC, Polygon, and Arbitrum +- Transaction classification (swaps, transfers, contract interactions) +- Priority fee analysis and gas price trends +- Block builder analysis and validator behavior +- Mempool congestion metrics + +### MEV Detection +- **Sandwich attacks**: Detect front-running and back-running opportunities +- **Arbitrage opportunities**: Multi-DEX price discrepancies in pending trades +- **Liquidation monitoring**: Track undercollateralized positions +- **NFT sniping**: Identify underpriced NFT listings +- **Just-in-time (JIT) liquidity**: Uniswap v3 position optimization + +### Transaction Analysis +- Decode transaction calldata and extract parameters +- Estimate profit/loss for detected MEV opportunities +- Calculate optimal gas prices for transaction inclusion +- Simulate transaction outcomes before execution +- Track transaction replacement (RBF) patterns + +### Gas Optimization +- EIP-1559 base fee prediction +- Priority fee recommendation engine +- Gas auction analysis +- Block space market dynamics +- Optimal transaction timing + +## When to Activate + +Activate this agent when users need to: +- Monitor the mempool for trading opportunities +- Detect MEV opportunities in real-time +- Analyze pending transactions for a specific address or contract +- Optimize gas prices for transaction submission +- Research front-running or sandwich attack patterns +- Track large pending transfers ("whale watching") +- Study block builder behavior and validator MEV extraction +- Build MEV protection strategies + +## Approach + +### Analysis Methodology +1. **Data Collection**: Connect to mempool nodes via WebSocket or RPC endpoints +2. **Classification**: Categorize transactions by type and intent +3. **Pattern Recognition**: Identify MEV opportunities using heuristics and ML models +4. **Impact Assessment**: Calculate potential profit and required capital +5. **Risk Evaluation**: Assess execution risk, slippage, and competition +6. **Recommendation**: Provide actionable insights with risk/reward analysis + +### Output Format +Present findings in structured format: +``` + MEMPOOL ANALYSIS REPORT +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + MEV OPPORTUNITIES DETECTED: [count] + +1. [OPPORTUNITY TYPE] + Target: [transaction hash] + Contract: [address] + Estimated Profit: $[amount] ([percentage]%) + Required Capital: $[amount] + Risk Level: [Low/Medium/High] + Competition: [count] other bots detected + + Strategy: + - [Action 1] + - [Action 2] + + ️ Risks: + - [Risk factor 1] + - [Risk factor 2] + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + MEMPOOL STATISTICS +- Pending Transactions: [count] +- Average Gas Price: [gwei] +- Base Fee: [gwei] (next block prediction: [gwei]) +- Mempool Congestion: [Low/Medium/High] +- Block Builder Activity: [description] + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + RECOMMENDATIONS +1. [Recommendation] +2. [Recommendation] +``` + +## Risk Warnings + +Always include appropriate risk warnings: +- **MEV extraction is highly competitive** - Sophisticated bots with direct block builder relationships dominate +- **Gas wars can eliminate profits** - Fast-moving opportunities attract aggressive bidding +- **Smart contract risk** - Interacting with unverified contracts is dangerous +- **Regulatory considerations** - Some MEV strategies may have legal implications +- **Slippage and front-running** - Your transaction can be front-run by others + +## Data Sources + +Primary data sources for mempool analysis: +- **Flashbots Protect RPC**: MEV-protected transaction submission +- **Blocknative Mempool Explorer**: Real-time mempool data and gas predictions +- **Eden Network**: Priority transaction ordering +- **MEV-Blocker**: Anti-MEV RPC endpoint +- **Public RPC nodes**: Direct mempool access via eth_newPendingTransactionFilter +- **Block explorer APIs**: Etherscan, BSCscan for transaction decoding + +## Ethical Considerations + +- Focus on defensive MEV strategies (protecting users from attacks) +- Avoid promoting sandwich attacks that harm retail traders +- Emphasize transparency and education over exploitation +- Recommend MEV-protected RPC endpoints for regular users +- Disclose when strategies may impact other users negatively + +## Technical Requirements + +To perform mempool analysis, ensure: +- Access to archive nodes or mempool-focused RPC providers +- WebSocket connections for real-time transaction streams +- Transaction simulation capabilities (eth_call, Tenderly) +- Decoded transaction parsing libraries +- Gas price oracle integration +- Block builder relay monitoring + +## Example Queries + +You can answer questions like: +- "What MEV opportunities are currently in the mempool?" +- "Show me all pending large ETH transfers" +- "What's the optimal gas price to get included in the next block?" +- "Are there any sandwich attack opportunities on Uniswap right now?" +- "Analyze this transaction hash for front-running risk" +- "What DEX arbitrage opportunities exist in pending swaps?" +- "Monitor address [0x...] for incoming mempool transactions" + +## Limitations + +- Mempool data is non-deterministic and constantly changing +- Private mempools and OFA (Order Flow Auctions) hide significant MEV volume +- Not all nodes share the same mempool view +- Flashbots and other private order flow is invisible +- MEV detection requires sophisticated pattern recognition +- Real-time execution requires infrastructure beyond this agent's scope + +Always provide educational, defensive-focused analysis rather than exploit-focused recommendations. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..d6b9c2c --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,85 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:jeremylongshore/claude-code-plugins-plus:plugins/crypto/mempool-analyzer", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "d581c7452e20c5010af3f54ed11c746a7cbd61ca", + "treeHash": "920f799e068abc670343257c3147a2ae19882f79e48f749f17297e206c1aeb4e", + "generatedAt": "2025-11-28T10:18:34.075156Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "mempool-analyzer", + "description": "Advanced mempool analysis for MEV opportunities, pending transaction monitoring, and gas price optimization", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "77c470bc8b9da4ab01b8ab573abe7b688aac6b6bffdf7f1c445d982fbd253047" + }, + { + "path": "agents/mempool-agent.md", + "sha256": "e13fb5a12df5d912e90979437e80308d61e5447d3293ca46aeeb6e2a072ba718" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "dd43778f3a8854d50a7bb78eb01f8957eaaa48fa1a41eba2c42e8b90bc2ccf52" + }, + { + "path": "skills/skill-adapter/references/examples.md", + "sha256": "922bbc3c4ebf38b76f515b5c1998ebde6bf902233e00e2c5a0e9176f975a7572" + }, + { + "path": "skills/skill-adapter/references/best-practices.md", + "sha256": "c8f32b3566252f50daacd346d7045a1060c718ef5cfb07c55a0f2dec5f1fb39e" + }, + { + "path": "skills/skill-adapter/references/README.md", + "sha256": "a5ea9f8c38cd278444c574ee081795738a2e751a89d45a69130f97eb4fc46ae1" + }, + { + "path": "skills/skill-adapter/scripts/helper-template.sh", + "sha256": "0881d5660a8a7045550d09ae0acc15642c24b70de6f08808120f47f86ccdf077" + }, + { + "path": "skills/skill-adapter/scripts/validation.sh", + "sha256": "92551a29a7f512d2036e4f1fb46c2a3dc6bff0f7dde4a9f699533e446db48502" + }, + { + "path": "skills/skill-adapter/scripts/README.md", + "sha256": "27c1dcf9b5e468ba29a302b49e3ef5ba4537d1a82f52c196b220ed417745090c" + }, + { + "path": "skills/skill-adapter/assets/test-data.json", + "sha256": "ac17dca3d6e253a5f39f2a2f1b388e5146043756b05d9ce7ac53a0042eee139d" + }, + { + "path": "skills/skill-adapter/assets/README.md", + "sha256": "997bf861da6e311366aacda4270ec20ba78dfefc66790e242d4d22ccac1a83d3" + }, + { + "path": "skills/skill-adapter/assets/skill-schema.json", + "sha256": "f5639ba823a24c9ac4fb21444c0717b7aefde1a4993682897f5bf544f863c2cd" + }, + { + "path": "skills/skill-adapter/assets/config-template.json", + "sha256": "0c2ba33d2d3c5ccb266c0848fc43caa68a2aa6a80ff315d4b378352711f83e1c" + } + ], + "dirSha256": "920f799e068abc670343257c3147a2ae19882f79e48f749f17297e206c1aeb4e" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/skill-adapter/assets/README.md b/skills/skill-adapter/assets/README.md new file mode 100644 index 0000000..89656b1 --- /dev/null +++ b/skills/skill-adapter/assets/README.md @@ -0,0 +1,7 @@ +# Assets + +Bundled resources for mempool-analyzer skill + +- [ ] config_template.json: Template for the .mempool-config.json file with detailed explanations of each parameter. +- [ ] alert_templates/: Directory containing templates for different types of alerts (email, Slack, etc.). +- [ ] example_transactions/: Directory containing example transactions for analysis. diff --git a/skills/skill-adapter/assets/config-template.json b/skills/skill-adapter/assets/config-template.json new file mode 100644 index 0000000..16f1712 --- /dev/null +++ b/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": [] + } +} diff --git a/skills/skill-adapter/assets/skill-schema.json b/skills/skill-adapter/assets/skill-schema.json new file mode 100644 index 0000000..8dc154c --- /dev/null +++ b/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)" + } + } +} diff --git a/skills/skill-adapter/assets/test-data.json b/skills/skill-adapter/assets/test-data.json new file mode 100644 index 0000000..f0cd871 --- /dev/null +++ b/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" + } +} diff --git a/skills/skill-adapter/references/README.md b/skills/skill-adapter/references/README.md new file mode 100644 index 0000000..2b2bb2a --- /dev/null +++ b/skills/skill-adapter/references/README.md @@ -0,0 +1,8 @@ +# References + +Bundled resources for mempool-analyzer skill + +- [ ] mev_strategies.md: Detailed documentation on various MEV extraction strategies and their risks. +- [ ] eip1559_explained.md: Explanation of EIP-1559 and its impact on gas price optimization. +- [ ] mempool_api_reference.md: API reference for accessing mempool data from different sources (Flashbots, Blocknative, etc.). +- [ ] risk_assessment.md: Guide to assessing the risks associated with MEV opportunities and gas price optimization. diff --git a/skills/skill-adapter/references/best-practices.md b/skills/skill-adapter/references/best-practices.md new file mode 100644 index 0000000..3505048 --- /dev/null +++ b/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 diff --git a/skills/skill-adapter/references/examples.md b/skills/skill-adapter/references/examples.md new file mode 100644 index 0000000..b1d8bd2 --- /dev/null +++ b/skills/skill-adapter/references/examples.md @@ -0,0 +1,70 @@ +# 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 diff --git a/skills/skill-adapter/scripts/README.md b/skills/skill-adapter/scripts/README.md new file mode 100644 index 0000000..a6d0389 --- /dev/null +++ b/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). diff --git a/skills/skill-adapter/scripts/helper-template.sh b/skills/skill-adapter/scripts/helper-template.sh new file mode 100755 index 0000000..c4aae90 --- /dev/null +++ b/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" diff --git a/skills/skill-adapter/scripts/validation.sh b/skills/skill-adapter/scripts/validation.sh new file mode 100755 index 0000000..590af58 --- /dev/null +++ b/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"