@intentsolutionsio/flash-loan-simulator 1.0.0

package/skills/simulating-flash-loans/PRD.md

@@ -0,0 +1,239 @@
+# PRD: Flash Loan Simulator
+
+## Summary
+
+**One-liner**: Simulate and analyze flash loan strategies with profitability calculations and risk assessment
+**Domain**: Cryptocurrency / DeFi / Flash Loans
+**Users**: DeFi Developers, Arbitrage Researchers, Smart Contract Auditors
+
+## Problem Statement
+
+Flash loans are powerful DeFi primitives that allow borrowing any amount without collateral, provided the loan is repaid within the same transaction. However, evaluating flash loan strategies is challenging:
+
+1. No easy way to simulate complex multi-step transactions before deployment
+2. Profitability calculations require accounting for gas, fees, and slippage
+3. Competition from MEV bots makes many strategies unprofitable
+4. Risk assessment requires understanding multiple protocols simultaneously
+5. Real execution on mainnet is expensive and risky for testing
+6. Historical backtesting requires archive node access and complex setup
+
+## Target Users
+
+### Persona 1: DeFi Developer
+- **Profile**: Building flash loan arbitrage bots or liquidation systems
+- **Pain Points**: Testing on mainnet is expensive; needs simulation before deployment
+- **Goals**: Validate profitability; optimize gas usage; identify edge cases
+- **Usage Pattern**: Daily simulation runs during development cycle
+
+### Persona 2: Arbitrage Researcher
+- **Profile**: Analyzes DeFi protocols for arbitrage opportunities
+- **Pain Points**: Manual calculation of multi-hop arbitrage is error-prone
+- **Goals**: Quickly evaluate opportunities; backtest historical scenarios
+- **Usage Pattern**: Continuous opportunity scanning and analysis
+
+### Persona 3: Smart Contract Auditor
+- **Profile**: Reviews DeFi protocols for vulnerabilities
+- **Pain Points**: Needs to simulate attack vectors without executing them
+- **Goals**: Understand flash loan attack scenarios; verify protocol safety
+- **Usage Pattern**: Deep-dive analysis during security audits
+
+## User Stories
+
+### Critical (P0)
+
+1. **As a DeFi developer**, I want to simulate a flash loan arbitrage between two DEXs, so that I can verify profitability before deploying my contract.
+   - **Acceptance Criteria**:
+     - Input: Token pair, loan amount, source DEX, target DEX
+     - Output: Expected profit/loss after all fees
+     - Includes gas cost estimation at current prices
+     - Shows breakdown of each transaction step
+
+2. **As a researcher**, I want to calculate liquidation profitability on Aave, so that I can identify profitable opportunities.
+   - **Acceptance Criteria**:
+     - Input: Borrower address or health factor threshold
+     - Output: Liquidation bonus minus costs
+     - Shows collateral and debt values
+     - Estimates competition level
+
+3. **As a developer**, I want to compare flash loan providers, so that I can choose the cheapest option.
+   - **Acceptance Criteria**:
+     - Compare Aave (0.09%), dYdX (0%), Balancer (variable)
+     - Account for available liquidity per asset
+     - Show total cost including gas differences
+
+### Important (P1)
+
+4. **As a researcher**, I want to simulate triangular arbitrage, so that I can evaluate multi-hop strategies.
+   - **Acceptance Criteria**:
+     - Support 3+ DEX paths
+     - Calculate cumulative slippage
+     - Show optimal route and amounts
+
+5. **As a developer**, I want to backtest strategies against historical data, so that I can validate my approach.
+   - **Acceptance Criteria**:
+     - Input: Strategy parameters, date range
+     - Output: Historical profit/loss per opportunity
+     - Shows win rate and average profit
+
+### Nice-to-Have (P2)
+
+6. **As an auditor**, I want to simulate flash loan attack scenarios, so that I can test protocol security.
+   - **Acceptance Criteria**:
+     - Template attack patterns (price manipulation, governance, etc.)
+     - Safe simulation without actual execution
+     - Detailed transaction trace
+
+## Functional Requirements
+
+### Core Features
+
+- **REQ-1**: Flash Loan Provider Support
+  - Aave V3 (0.09% fee, multi-chain)
+  - dYdX (0% fee, ETH mainnet)
+  - Balancer (variable fee, multi-chain)
+  - Uniswap V3 flash swaps (implicit fee)
+
+- **REQ-2**: Strategy Simulation Engine
+  - Simple arbitrage (2 DEX)
+  - Triangular arbitrage (3+ DEX)
+  - Liquidation profitability
+  - Collateral swap simulation
+  - Debt refinancing analysis
+
+- **REQ-3**: Profitability Calculator
+  - Gross profit from price differences
+  - Flash loan fee deduction
+  - Gas cost estimation (EIP-1559)
+  - Slippage impact modeling
+  - Net profit/loss after all costs
+
+- **REQ-4**: Risk Assessment
+  - MEV competition analysis
+  - Execution risk scoring
+  - Protocol risk factors
+  - Liquidity depth checks
+
+- **REQ-5**: RPC Configuration
+  - Free public RPCs (Ankr, Chainstack, Infura)
+  - Custom RPC endpoint support
+  - Multi-chain configuration
+  - Automatic fallback
+
+### Supported Strategies
+
+| Strategy | Description | Complexity |
+|----------|-------------|------------|
+| Simple Arbitrage | Buy low on DEX A, sell high on DEX B | Low |
+| Triangular Arbitrage | A→B→C→A circular trading | Medium |
+| Liquidation | Repay debt, claim collateral bonus | Medium |
+| Collateral Swap | Replace collateral without closing position | Medium |
+| Self-Liquidation | Efficiently close own position | Low |
+| Debt Refinancing | Move debt to better rates | High |
+
+## Non-Goals
+
+- **NOT** executing real flash loans (simulation only)
+- **NOT** generating production-ready Solidity code
+- **NOT** real-time opportunity alerts (analysis only)
+- **NOT** MEV protection or Flashbots integration
+- **NOT** managing private keys or signing transactions
+
+## API Integrations
+
+| API | Purpose | Auth | Rate Limits |
+|-----|---------|------|-------------|
+| Ankr RPC | Free blockchain queries | None | 30 req/sec |
+| Chainstack Free | RPC | API Key | 25 req/sec |
+| DeFiLlama | TVL and protocol data | None | Generous |
+| Etherscan | Gas oracle, contract ABIs | API Key | 5 req/sec |
+| Infura Free | RPC with archive data | API Key | 10 req/sec |
+| The Graph | DEX subgraph queries | None | Varies |
+
+## Success Metrics
+
+| Metric | Target | Measurement |
+|--------|--------|-------------|
+| Simulation Accuracy | Within 5% of actual profit | Backtest vs. historical |
+| Strategy Coverage | 6 strategy types | Feature completeness |
+| Response Time | <5 seconds per simulation | Performance monitoring |
+| Free RPC Usage | 100% usable without paid tier | User feedback |
+
+## UX Flow
+
+```
+1. User Input
+   ├── Strategy type (arbitrage, liquidation, etc.)
+   ├── Parameters (tokens, amounts, DEXs)
+   ├── Chain (Ethereum, Polygon, Arbitrum)
+   └── RPC endpoint (default: free public)
+
+2. Data Collection
+   ├── Fetch current prices from DEXs
+   ├── Query protocol state (Aave positions, etc.)
+   ├── Get gas prices and estimates
+   └── Check liquidity depth
+
+3. Simulation Engine
+   ├── Calculate gross profit
+   ├── Deduct flash loan fees
+   ├── Subtract gas costs
+   ├── Apply slippage model
+   └── Compute net profit/loss
+
+4. Risk Analysis
+   ├── Score MEV competition risk
+   ├── Check execution feasibility
+   ├── Assess protocol risks
+   └── Rate overall viability
+
+5. Results Output
+   ├── Profit/loss breakdown
+   ├── Step-by-step transaction flow
+   ├── Risk assessment summary
+   └── Recommendations
+```
+
+## Constraints & Assumptions
+
+### Constraints
+- Free RPC endpoints have rate limits (25-100 req/sec)
+- Historical simulations require archive node access
+- Gas estimates are approximations (actual may vary ±20%)
+- Price data has latency (not real-time MEV-competitive)
+
+### Assumptions
+- User understands DeFi and flash loan concepts
+- User has access to RPC endpoint (free or paid)
+- Simulation results are for analysis, not execution
+- Market conditions change; simulations are point-in-time
+
+## Risk Assessment
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| Stale price data | High | Medium | Clear timestamp warnings |
+| RPC rate limiting | Medium | Low | Multi-provider fallback |
+| Inaccurate gas estimate | Medium | Medium | Add safety margin to calculations |
+| Strategy already exploited | High | Low | Competition scoring in output |
+| Protocol changes | Low | High | Version-aware protocol configs |
+
+## Educational Disclaimer
+
+**IMPORTANT**: This tool is for **educational and research purposes only**. Flash loan strategies involve significant risks:
+
+- Smart contract bugs can cause total loss of funds
+- MEV bots compete for the same opportunities
+- Gas costs can exceed profits
+- Protocol exploits may have legal implications
+
+Users should:
+- Never deploy unaudited code
+- Start with testnets before mainnet
+- Understand the risks fully
+- Consult legal counsel if needed
+
+## Version History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0.0 | 2025-01-15 | Claude | Initial PRD |

package/skills/simulating-flash-loans/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: simulating-flash-loans
+description: |
+  Simulate flash loan strategies with profitability calculations and risk assessment across Aave, dYdX, and Balancer.
+  Use when simulating flash loans, analyzing arbitrage profitability, evaluating liquidation opportunities, or comparing flash loan providers.
+  Trigger with phrases like "simulate flash loan", "flash loan arbitrage", "liquidation profit", "compare Aave dYdX", "flash loan strategy", or "DeFi arbitrage simulation".
+
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash(crypto:flashloan-*)
+version: 1.0.0
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+license: MIT
+compatible-with: claude-code, codex, openclaw
+tags: [crypto, simulating-flash]
+---
+# Simulating Flash Loans
+
+## Contents
+
+[Overview](#overview) | [Prerequisites](#prerequisites) | [Instructions](#instructions) | [Output](#output) | [Error Handling](#error-handling) | [Examples](#examples) | [Resources](#resources)
+
+## Overview
+
+Simulate flash loan strategies across Aave V3, dYdX, and Balancer with profitability calculations, gas cost estimation, and risk assessment. Evaluate flash loan opportunities without executing real transactions.
+
+## Prerequisites
+
+1. Install Python 3.9+ with `web3`, `httpx`, and `rich` packages
+2. Configure RPC endpoint access (free public RPCs via https://chainlist.org work fine)
+3. Optionally add Etherscan API key for better gas estimates
+4. Set RPC in `${CLAUDE_SKILL_DIR}/config/settings.yaml` or use `ETH_RPC_URL` env var
+
+## Instructions
+
+1. Simulate a two-DEX arbitrage with automatic fee and gas calculation:
+   ```bash
+   python ${CLAUDE_SKILL_DIR}/scripts/flash_simulator.py arbitrage ETH USDC 100 \
+     --dex-buy uniswap --dex-sell sushiswap
+   ```
+2. Compare flash loan providers to find the cheapest for your strategy:
+   ```bash
+   python ${CLAUDE_SKILL_DIR}/scripts/flash_simulator.py arbitrage ETH USDC 100 --compare-providers
+   ```
+3. Analyze liquidation profitability on lending protocols:
+   ```bash
+   python ${CLAUDE_SKILL_DIR}/scripts/flash_simulator.py liquidation \
+     --protocol aave --health-factor 0.95
+   ```
+4. Simulate triangular arbitrage with multi-hop circular paths:
+   ```bash
+   python ${CLAUDE_SKILL_DIR}/scripts/flash_simulator.py triangular \
+     ETH USDC WBTC ETH --amount 50
+   ```
+5. Add risk assessment (MEV competition, execution, protocol, liquidity) to any simulation:
+   ```bash
+   python ${CLAUDE_SKILL_DIR}/scripts/flash_simulator.py arbitrage ETH USDC 100 --risk-analysis
+   ```
+6. Run full analysis combining all features:
+   ```bash
+   python ${CLAUDE_SKILL_DIR}/scripts/flash_simulator.py arbitrage ETH USDC 100 \
+     --full --output json > simulation.json
+   ```
+
+## Output
+
+- **Quick Mode**: Net profit/loss, provider recommendation, Go/No-Go verdict
+- **Breakdown Mode**: Step-by-step transaction flow with individual cost components
+- **Comparison Mode**: All providers ranked by net profit with fee differences
+- **Risk Analysis**: Competition, execution, protocol, and liquidity scores (0-100) with viability grade (A-F)
+
+See `${CLAUDE_SKILL_DIR}/references/implementation.md` for detailed output examples and risk scoring methodology.
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| RPC Rate Limit | Too many requests | Switch to backup endpoint or wait |
+| Stale Prices | Data older than 30s | Auto-refreshes with warning |
+| No Profitable Route | All routes lose after costs | Try different pairs or amounts |
+| Insufficient Liquidity | Trade exceeds pool depth | Reduce amount or split across pools |
+
+See `${CLAUDE_SKILL_DIR}/references/errors.md` for comprehensive error handling.
+
+## Examples
+
+**Basic arbitrage simulation:**
+```bash
+python ${CLAUDE_SKILL_DIR}/scripts/flash_simulator.py arbitrage ETH USDC 100 \
+  --dex-buy uniswap --dex-sell sushiswap
+```
+
+**Find cheapest provider:**
+```bash
+python ${CLAUDE_SKILL_DIR}/scripts/flash_simulator.py arbitrage ETH USDC 100 --compare-providers
+```
+
+**Liquidation opportunity scan:**
+```bash
+python ${CLAUDE_SKILL_DIR}/scripts/flash_simulator.py liquidation --protocol aave --health-factor 0.95
+```
+
+See `${CLAUDE_SKILL_DIR}/references/examples.md` for multi-provider comparison and backtesting examples.
+
+## Resources
+
+- `${CLAUDE_SKILL_DIR}/references/implementation.md` - Provider comparison, strategy details, risk scoring, output modes
+- [Aave V3 Flash Loans](https://docs.aave.com/developers/guides/flash-loans)
+- [dYdX Flash Loans](https://docs.dydx.exchange/developers/guides/flash-loans)
+- [Balancer Flash Loans](https://docs.balancer.fi/concepts/advanced/flash-loans.html)
+- [Flashbots Protect](https://docs.flashbots.net/flashbots-protect/overview)

package/skills/simulating-flash-loans/config/settings.yaml

@@ -0,0 +1,241 @@
+# Flash Loan Simulator Configuration
+# ===================================
+# Configure RPC endpoints, providers, and simulation parameters.
+# All settings can be overridden via command-line arguments.
+
+# ─────────────────────────────────────────────────────────────────
+# RPC Endpoints
+# ─────────────────────────────────────────────────────────────────
+# Free public RPC endpoints (no signup required).
+# For production use, consider private RPCs (Infura, Alchemy, QuickNode).
+
+rpc_endpoints:
+  ethereum:
+    primary: "https://rpc.ankr.com/eth"
+    backup:
+      - "https://eth.llamarpc.com"
+      - "https://ethereum-rpc.publicnode.com"
+      - "https://1rpc.io/eth"
+  polygon:
+    primary: "https://rpc.ankr.com/polygon"
+    backup:
+      - "https://polygon-rpc.com"
+  arbitrum:
+    primary: "https://rpc.ankr.com/arbitrum"
+    backup:
+      - "https://arb1.arbitrum.io/rpc"
+  optimism:
+    primary: "https://rpc.ankr.com/optimism"
+    backup:
+      - "https://mainnet.optimism.io"
+  avalanche:
+    primary: "https://rpc.ankr.com/avalanche"
+    backup:
+      - "https://api.avax.network/ext/bc/C/rpc"
+
+# ─────────────────────────────────────────────────────────────────
+# Flash Loan Providers
+# ─────────────────────────────────────────────────────────────────
+# Provider configuration with fee rates and contract addresses.
+
+providers:
+  aave:
+    name: "Aave V3"
+    fee_rate: 0.0009  # 0.09%
+    gas_overhead: 100000
+    contracts:
+      ethereum: "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2"
+      polygon: "0x794a61358D6845594F94dc1DB02A252b5b4814aD"
+      arbitrum: "0x794a61358D6845594F94dc1DB02A252b5b4814aD"
+      optimism: "0x794a61358D6845594F94dc1DB02A252b5b4814aD"
+      avalanche: "0x794a61358D6845594F94dc1DB02A252b5b4814aD"
+
+  dydx:
+    name: "dYdX"
+    fee_rate: 0.0  # FREE!
+    gas_overhead: 150000
+    contracts:
+      ethereum: "0x1E0447b19BB6EcFdAe1e4AE1694b0C3659614e4e"
+    notes: "Ethereum mainnet only, limited asset support"
+
+  balancer:
+    name: "Balancer"
+    fee_rate: 0.0001  # 0.01%
+    gas_overhead: 80000
+    contracts:
+      ethereum: "0xBA12222222228d8Ba445958a75a0704d566BF2C8"
+      polygon: "0xBA12222222228d8Ba445958a75a0704d566BF2C8"
+      arbitrum: "0xBA12222222228d8Ba445958a75a0704d566BF2C8"
+
+  uniswap:
+    name: "Uniswap V3"
+    fee_rate: 0.003  # 0.3% (varies by pool)
+    gas_overhead: 120000
+    contracts:
+      ethereum: "0xE592427A0AEce92De3Edee1F18E0157C05861564"
+      polygon: "0xE592427A0AEce92De3Edee1F18E0157C05861564"
+      arbitrum: "0xE592427A0AEce92De3Edee1F18E0157C05861564"
+      optimism: "0xE592427A0AEce92De3Edee1F18E0157C05861564"
+    notes: "Flash swap (not flash loan) - fee is pool-dependent"
+
+# ─────────────────────────────────────────────────────────────────
+# DEX Configuration
+# ─────────────────────────────────────────────────────────────────
+# Supported DEXes for arbitrage simulations.
+
+dexes:
+  uniswap:
+    name: "Uniswap V3"
+    fee_tiers: [0.0001, 0.0005, 0.003, 0.01]  # 0.01%, 0.05%, 0.3%, 1%
+    router:
+      ethereum: "0xE592427A0AEce92De3Edee1F18E0157C05861564"
+      polygon: "0xE592427A0AEce92De3Edee1F18E0157C05861564"
+      arbitrum: "0xE592427A0AEce92De3Edee1F18E0157C05861564"
+
+  sushiswap:
+    name: "SushiSwap"
+    fee_rate: 0.003  # 0.3%
+    router:
+      ethereum: "0xd9e1cE17f2641f24aE83637ab66a2cca9C378B9F"
+      polygon: "0x1b02dA8Cb0d097eB8D57A175b88c7D8b47997506"
+      arbitrum: "0x1b02dA8Cb0d097eB8D57A175b88c7D8b47997506"
+
+  curve:
+    name: "Curve Finance"
+    fee_rate: 0.0004  # 0.04% (for stable pools)
+    router:
+      ethereum: "0x99a58482BD75cbab83b27EC03CA68fF489b5788f"
+
+  balancer:
+    name: "Balancer V2"
+    fee_rate: 0.001  # Varies by pool (0.01% - 10%)
+    vault:
+      ethereum: "0xBA12222222228d8Ba445958a75a0704d566BF2C8"
+
+# ─────────────────────────────────────────────────────────────────
+# Simulation Parameters
+# ─────────────────────────────────────────────────────────────────
+# Default parameters for flash loan simulations.
+
+simulation:
+  # Default market prices (for offline simulation)
+  eth_price_usd: 2500.0
+  btc_price_usd: 68000.0
+
+  # Default gas settings
+  gas_price_gwei: 30.0
+  gas_limit_multiplier: 1.2  # Safety margin
+
+  # Slippage settings
+  default_slippage_percent: 0.5
+  max_slippage_percent: 3.0
+
+  # Request timeout
+  rpc_timeout_ms: 30000
+  request_delay_ms: 500  # Between API calls to avoid rate limits
+
+# ─────────────────────────────────────────────────────────────────
+# Risk Assessment Parameters
+# ─────────────────────────────────────────────────────────────────
+# Weights and thresholds for risk scoring.
+
+risk_assessment:
+  # Factor weights (must sum to 1.0)
+  weights:
+    mev_competition: 0.30
+    execution_risk: 0.25
+    protocol_risk: 0.15
+    liquidity_risk: 0.15
+    profit_margin: 0.15
+
+  # Risk thresholds
+  thresholds:
+    low: 30
+    medium: 50
+    high: 70
+    # Above 70 = CRITICAL
+
+  # Viability mapping
+  viability:
+    go_threshold: 30        # Score <= 30 = GO
+    caution_threshold: 70   # Score <= 70 = CAUTION
+    # Score > 70 = NO-GO
+
+# ─────────────────────────────────────────────────────────────────
+# MEV Protection
+# ─────────────────────────────────────────────────────────────────
+# Configuration for MEV protection in production.
+
+mev_protection:
+  flashbots:
+    enabled: false  # Enable for production
+    relay_url: "https://relay.flashbots.net"
+    bundle_simulation: true
+
+  private_transaction:
+    enabled: false
+    providers:
+      - "flashbots_protect"
+      - "eden_network"
+      - "bloxroute"
+
+# ─────────────────────────────────────────────────────────────────
+# Output Settings
+# ─────────────────────────────────────────────────────────────────
+# Configure output format and verbosity.
+
+output:
+  default_format: "console"  # console, json, markdown
+  console_width: 70
+  show_warnings: true
+  show_recommendations: true
+  verbose: false
+
+# ─────────────────────────────────────────────────────────────────
+# Supported Tokens
+# ─────────────────────────────────────────────────────────────────
+# Token addresses for common assets (Ethereum mainnet).
+
+tokens:
+  ETH:
+    symbol: "ETH"
+    decimals: 18
+    addresses:
+      ethereum: "native"
+  WETH:
+    symbol: "WETH"
+    decimals: 18
+    addresses:
+      ethereum: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
+  USDC:
+    symbol: "USDC"
+    decimals: 6
+    addresses:
+      ethereum: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
+  USDT:
+    symbol: "USDT"
+    decimals: 6
+    addresses:
+      ethereum: "0xdAC17F958D2ee523a2206206994597C13D831ec7"
+  DAI:
+    symbol: "DAI"
+    decimals: 18
+    addresses:
+      ethereum: "0x6B175474E89094C44Da98b954EescdeCB5AF3696dF"
+  WBTC:
+    symbol: "WBTC"
+    decimals: 8
+    addresses:
+      ethereum: "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599"
+
+# ─────────────────────────────────────────────────────────────────
+# Educational Disclaimer
+# ─────────────────────────────────────────────────────────────────
+# This configuration is for educational simulation only.
+# Flash loan strategies carry significant risks:
+#   - Smart contract bugs can cause total loss
+#   - MEV bots compete for the same opportunities
+#   - Gas costs can exceed profits
+#   - Protocol exploits may have legal implications
+#
+# Never deploy unaudited code. Start with testnets.