Initial commit

2025-11-29 18:53:10 +08:00
commit 1081915eb0
14 changed files with 667 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,15 @@
+{
+  "name": "dex-aggregator-router",
+  "description": "Find optimal DEX routes for token swaps across multiple exchanges",
+  "version": "1.0.0",
+  "author": {
+    "name": "Claude Code Plugins",
+    "email": "[email protected]"
+  },
+  "skills": [
+    "./skills"
+  ],
+  "commands": [
+    "./commands"
+  ]
+}
--- a/README.md
+++ b/README.md
@@ -0,0 +1,3 @@
+# dex-aggregator-router
+
+Find optimal DEX routes for token swaps across multiple exchanges
--- a/commands/find-best-route.md
+++ b/commands/find-best-route.md
@@ -0,0 +1,243 @@
+---
+description: Find optimal DEX routing for token swaps
+shortcut: route
+---
+
+# DEX Aggregator Router
+
+You are a DEX routing optimization specialist. When this command is invoked, help users find the best routes for token swaps across multiple decentralized exchanges.
+
+## Your Task
+
+Analyze swap routes and provide optimal trading paths:
+
+1. **Trade Analysis**:
+   - Token pair identification
+   - Trade size and impact
+   - Slippage tolerance requirements
+   - Gas cost considerations
+
+2. **Route Discovery**:
+   - **Direct Routes**: Single-hop swaps
+   - **Multi-Hop Routes**: Intermediate token paths
+   - **Split Routes**: Partial order routing
+   - **Cross-DEX Routes**: Multiple exchange aggregation
+
+3. **Exchange Comparison**:
+   - Uniswap V2/V3
+   - SushiSwap
+   - Curve Finance (stablecoins)
+   - Balancer
+   - 1inch aggregator
+   - Paraswap
+   - Kyber Network
+
+4. **Cost-Benefit Analysis**:
+   - Price impact per route
+   - Gas costs per route
+   - Total effective cost
+   - Net received amount
+
+5. **Execution Strategy**:
+   - Optimal route recommendation
+   - Slippage protection settings
+   - MEV protection options
+   - Transaction timing
+
+## Output Format
+
+Structure your analysis as:
+
+```markdown
+## DEX Route Optimization Report
+
+### Trade Details
+- **From**: [Amount] [Token]
+- **To**: [Token]
+- **Network**: [Ethereum/Arbitrum/Polygon/etc]
+- **Trade Size**: [Small/Medium/Large/Whale]
+
+### Best Route Found
+
+ **RECOMMENDED ROUTE**
+```
+[Token A] → [Token B] → [Token C]
+   DEX1      DEX2
+```
+
+- **Expected Output**: [X] [Token]
+- **Price Impact**: [Y]%
+- **Gas Cost**: ~$[Z]
+- **Total Cost**: [A]%
+- **Effective Rate**: 1 [Token A] = [B] [Token B]
+
+### Route Comparison
+
+| Route | Path | Output | Price Impact | Gas | Total Cost | Net Gain |
+|-------|------|--------|--------------|-----|------------|----------|
+| 1 (Best) | A→B direct (Uni V3) | [X] | 0.5% | $20 | 0.8% | +$500 |
+| 2 | A→C→B (Sushi+Curve) | [Y] | 0.3% | $35 | 0.9% | +$450 |
+| 3 | Split: 70/30 (Uni/1inch) | [Z] | 0.4% | $40 | 1.0% | +$400 |
+
+### Detailed Route Analysis
+
+**Route 1: Direct Swap (Uniswap V3)**
+- Pool: [Token A]/[Token B] (0.3% fee tier)
+- Liquidity: $[X]M
+- Price Impact: [Y]%
+- Gas Estimate: [Z] gwei × [Units] = $[Cost]
+- Pros: Lowest price impact, deep liquidity
+- Cons: Higher gas than V2
+
+**Route 2: Multi-Hop (SushiSwap + Curve)**
+- Path: [A] → [Intermediate] → [B]
+- Total Liquidity: $[X]M
+- Price Impact: [Y]%
+- Gas Estimate: $[Cost]
+- Pros: Lower price impact via intermediate
+- Cons: Higher gas for multi-hop
+
+**Route 3: Split Order (1inch Aggregator)**
+- Split: [70]% Uniswap + [30]% SushiSwap
+- Balanced price impact
+- Gas Estimate: $[Cost]
+- Pros: Risk diversification
+- Cons: Highest gas cost
+
+### Size-Based Recommendations
+
+**For This Trade Size ([Amount]):**
+-  Recommended: [Route #]
+- ️  Avoid: [Route #] (reason: [price impact/gas cost])
+
+**If trade size changes:**
+- < $1,000: Use direct Uniswap V2 (lowest gas)
+- $1,000-$10,000: Use recommended route
+- $10,000-$100,000: Consider split routing
+- > $100,000: Contact market maker or OTC
+
+### Execution Parameters
+
+**Recommended Settings:**
+- **Slippage Tolerance**: [X]% (based on [Y]% impact + [Z]% buffer)
+- **Deadline**: [N] minutes
+- **Max Gas Price**: [G] gwei
+- **MEV Protection**: [Flashbots/Eden/None]
+
+**Transaction Details:**
+```
+From: [Amount] [Token A]
+To (minimum): [Amount] [Token B] (includes slippage)
+Route: [Detailed path]
+Expected gas: [Units] ([Cost] at [gwei])
+```
+
+### Market Conditions
+
+**Liquidity Analysis:**
+- [Token A] TVL across DEXs: $[X]M
+- [Token B] TVL across DEXs: $[Y]M
+- [Token A]/[Token B] total liquidity: $[Z]M
+
+**Volume & Volatility:**
+- 24h volume: $[X]
+- Volatility: [Low/Medium/High]
+- Recommendation: [Add buffer to slippage]
+
+### Risk Factors
+
+️ **Important Considerations:**
+- Price impact increases non-linearly with size
+- Gas costs provided are estimates
+- Mempool congestion may affect execution
+- Consider MEV protection for large trades
+- Slippage may exceed estimate in volatile markets
+
+### Alternative Strategies
+
+**If poor pricing on DEX:**
+-  CEX Transfer: Send to Binance/Coinbase → Swap → Send back
+-  Limit Order: Use CoW Swap or 1inch Limit Order
+-  OTC: Contact OTC desk for large trades (> $100k)
+- ⏰ TWAP: Break into smaller orders over time
+
+### Next Steps
+
+1.  Review recommended route and parameters
+2. ️  Configure slippage in your wallet
+3.  Double-check token addresses (avoid scams)
+4. ⏰ Monitor gas prices for optimal timing
+5.  Execute trade via [Recommended DEX/Aggregator]
+```
+
+## DEX Characteristics
+
+### Uniswap V2
+- **Best for**: Standard pairs, proven security
+- **Liquidity**: Very high
+- **Gas cost**: Medium
+- **Fee**: 0.3% flat
+
+### Uniswap V3
+- **Best for**: Deep liquidity pairs, efficiency
+- **Liquidity**: Concentrated (can be higher effective)
+- **Gas cost**: Higher than V2
+- **Fee**: 0.05%, 0.3%, 1% tiers
+
+### Curve Finance
+- **Best for**: Stablecoin swaps, low slippage
+- **Liquidity**: Excellent for stables
+- **Gas cost**: Low
+- **Fee**: 0.04% typically
+
+### SushiSwap
+- **Best for**: Alternative to Uniswap V2
+- **Liquidity**: Good on major pairs
+- **Gas cost**: Similar to Uni V2
+- **Fee**: 0.3%
+
+### Balancer
+- **Best for**: Multi-token pools
+- **Liquidity**: Moderate
+- **Gas cost**: Higher (complex math)
+- **Fee**: Varies per pool
+
+## Key Concepts
+
+### Price Impact
+```
+Price Impact = (Expected Price - Execution Price) / Expected Price
+```
+- < 0.5%: Good execution
+- 0.5-1%: Acceptable for medium trades
+- 1-3%: High, consider splitting
+- > 3%: Very high, use alternative strategy
+
+### Slippage Tolerance
+```
+Minimum Received = Expected × (1 - Slippage %)
+```
+Recommended settings:
+- Stable pairs: 0.1-0.5%
+- Major pairs: 0.5-1%
+- Volatile pairs: 1-3%
+- Low liquidity: 3-5%
+
+## Example Queries
+
+Users might ask:
+- "Best route to swap 10 ETH for USDC?"
+- "Compare Uniswap vs SushiSwap for DAI → USDC"
+- "I want to swap $50k USDT to ETH - what's the best strategy?"
+- "Why is 1inch giving me better rate than Uniswap?"
+- "Should I split my trade across multiple DEXs?"
+
+## Important Notes
+
+- Always verify token addresses (scam tokens exist)
+- Price impact grows non-linearly with trade size
+- Gas costs can exceed gains on small trades
+- Consider MEV attacks on large trades
+- Use aggregators like 1inch or Paraswap for complex routing
+- Slippage protection is critical in volatile markets
+- This is routing analysis, not financial advice
--- a/plugin.lock.json
+++ b/plugin.lock.json
@@ -0,0 +1,85 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:jeremylongshore/claude-code-plugins-plus:plugins/crypto/dex-aggregator-router",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "6a81151f544578a1755a8cbb084b4d465b013b61",
+    "treeHash": "8a74710a31151935424efb0bf5b41dc8b824ec3ad792c406da50b7f36e406c3e",
+    "generatedAt": "2025-11-28T10:18:24.180360Z",
+    "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": "dex-aggregator-router",
+    "description": "Find optimal DEX routes for token swaps across multiple exchanges",
+    "version": "1.0.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "9acf7ca192509045c2722686a2ab0497efdeb97261ef1627c4e0426d5617a02d"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "aa1f2a0982fb1b82e026a5faa74055324387f69edd810579bc2f99b0615bde08"
+      },
+      {
+        "path": "commands/find-best-route.md",
+        "sha256": "4d54553326fd18f7e5d9df87bd0e6bceb6e173e02901c8dcf47d10a09a034afb"
+      },
+      {
+        "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": "873481c2a390065eb7b4005e1a7d8f79deaf9fb15d42be5ebd6d866bd7671670"
+      },
+      {
+        "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": "f604ffa8f5e2cbea1608b9cacc648813ced31d1f497696bb6bfe01b92ee2aea9"
+      },
+      {
+        "path": "skills/skill-adapter/assets/test-data.json",
+        "sha256": "ac17dca3d6e253a5f39f2a2f1b388e5146043756b05d9ce7ac53a0042eee139d"
+      },
+      {
+        "path": "skills/skill-adapter/assets/README.md",
+        "sha256": "453b152995daf7e8c5307083dc3449a66094c344990a967197073b84265117e7"
+      },
+      {
+        "path": "skills/skill-adapter/assets/skill-schema.json",
+        "sha256": "f5639ba823a24c9ac4fb21444c0717b7aefde1a4993682897f5bf544f863c2cd"
+      },
+      {
+        "path": "skills/skill-adapter/assets/config-template.json",
+        "sha256": "0c2ba33d2d3c5ccb266c0848fc43caa68a2aa6a80ff315d4b378352711f83e1c"
+      }
+    ],
+    "dirSha256": "8a74710a31151935424efb0bf5b41dc8b824ec3ad792c406da50b7f36e406c3e"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
--- a/skills/skill-adapter/assets/README.md
+++ b/skills/skill-adapter/assets/README.md
@@ -0,0 +1,7 @@
+# Assets
+
+Bundled resources for dex-aggregator-router skill
+
+- [ ] example_swap_configurations.json: Example configurations for various token swaps, including input tokens, output tokens, and amounts.
+- [ ] route_comparison_template.md: Template for presenting the comparison of different routes, including price impact, gas costs, and slippage.
+- [ ] risk_assessment_template.md: Template for assessing the risks associated with different routes, including liquidity depth and potential MEV attacks.
--- a/skills/skill-adapter/assets/config-template.json
+++ 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": []
+  }
+}
--- a/skills/skill-adapter/assets/skill-schema.json
+++ 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)"
+    }
+  }
+}
--- a/skills/skill-adapter/assets/test-data.json
+++ 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"
+  }
+}
--- a/skills/skill-adapter/references/README.md
+++ b/skills/skill-adapter/references/README.md
@@ -0,0 +1,7 @@
+# References
+
+Bundled resources for dex-aggregator-router skill
+
+- [ ] dex_api_documentation.md: Comprehensive documentation for the APIs of major DEX aggregators like 1inch, Paraswap, and Matcha.
+- [ ] slippage_tolerance_guide.md: Guide on setting optimal slippage tolerance to balance trade success and price impact.
+- [ ] mev_protection_strategies.md: Documentation outlining strategies for protecting large trades from MEV attacks.
--- a/skills/skill-adapter/references/best-practices.md
+++ 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
--- a/skills/skill-adapter/references/examples.md
+++ 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
--- a/skills/skill-adapter/scripts/README.md
+++ b/skills/skill-adapter/scripts/README.md
@@ -0,0 +1,7 @@
+# Scripts
+
+Bundled resources for dex-aggregator-router skill
+
+- [ ] get_best_route.py: Script to fetch the best route for a given token swap using various DEX aggregators.
+- [ ] compare_exchanges.py: Script to compare the routes and prices offered by different DEXs for a specific swap.
+- [ ] optimize_trade.py: Script to optimize large trades by splitting them across multiple DEXs to minimize price impact.
--- a/skills/skill-adapter/scripts/helper-template.sh
+++ 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"
--- a/skills/skill-adapter/scripts/validation.sh
+++ 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"