commit 1081915eb09b34ecbb06dfa100b928d8b1be4796 Author: Zhongwei Li Date: Sat Nov 29 18:53:10 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..bdc20c3 --- /dev/null +++ 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" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..abe2d5b --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# dex-aggregator-router + +Find optimal DEX routes for token swaps across multiple exchanges diff --git a/commands/find-best-route.md b/commands/find-best-route.md new file mode 100644 index 0000000..68bbcfc --- /dev/null +++ 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 diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..87101d8 --- /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/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": [] + } +} \ 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..f4a5130 --- /dev/null +++ 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. 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..0483523 --- /dev/null +++ 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. 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..6b842ff --- /dev/null +++ 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. 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"