@intentsolutionsio/flash-loan-simulator 1.0.0 → 1.0.5

package/README.md

@@ -35,12 +35,14 @@ Simulate and analyze flash loan strategies including arbitrage, liquidations, an
 ### Why Free RPCs Work for Flash Loan Simulations
 
 **Simulation Requirements:**
+
 - Read blockchain state (getBlock, getTransaction, call)
 - Query DeFi protocol data (Aave, Uniswap, Balancer)
 - Gas estimation (estimateGas)
 - Historical data for backtesting
 
 **Free RPCs provide:**
+
 - 25-100 requests/second (more than enough for simulations)
 - Archive node access (historical data)
 - Multi-chain support (Ethereum, Polygon, Arbitrum)
@@ -55,14 +57,16 @@ Simulate and analyze flash loan strategies including arbitrage, liquidations, an
 **What:** Public RPC endpoints for 15+ chains
 
 **Limits:**
+
 - Ethereum: 30 requests/second
 - No rate limits on queries
 - Archive data available
 
 **Setup:**
+
 ```json
 {
-  "rpcEndpoint": "https://rpc.ankr.com/eth"
+  "rpcEndpoint": "eth"
 }
 ```
 
@@ -75,11 +79,13 @@ Simulate and analyze flash loan strategies including arbitrage, liquidations, an
 **What:** Free tier with 100K requests/day
 
 **Limits:**
+
 - 100,000 requests/day (sufficient for development)
 - 10 requests/second
 - Requires free account (no credit card)
 
 **Setup:**
+
 ```json
 {
   "rpcEndpoint": "https://mainnet.infura.io/v3/YOUR_FREE_KEY"
@@ -95,11 +101,13 @@ Simulate and analyze flash loan strategies including arbitrage, liquidations, an
 **What:** 3M requests/month free
 
 **Limits:**
+
 - 3,000,000 requests/month
 - 25 requests/second
 - Free account (no card)
 
 **Setup:**
+
 ```json
 {
   "rpcEndpoint": "https://nd-XXX-XXX-XXX.p2pify.com/YOUR_FREE_KEY"
@@ -115,11 +123,13 @@ Simulate and analyze flash loan strategies including arbitrage, liquidations, an
 **What:** Community-run public endpoints
 
 **Limits:**
+
 - Variable rate limits
 - May be slower during peak times
 - No signup required
 
 **Setup:**
+
 ```json
 {
   "rpcEndpoint": "https://eth.llamarpc.com"
@@ -129,6 +139,7 @@ Simulate and analyze flash loan strategies including arbitrage, liquidations, an
 **Cost:** $0 (completely free)
 
 **Alternatives:**
+
 - `https://ethereum.publicnode.com`
 - `https://cloudflare-eth.com`
 - `https://rpc.flashbots.net` (MEV-protected)
@@ -149,7 +160,7 @@ Simulate and analyze flash loan strategies including arbitrage, liquidations, an
     "gasPrice": "auto",
     "minProfitUSD": 50
   },
-  "rpcEndpoint": "https://rpc.ankr.com/eth"
+  "rpcEndpoint": "eth"
 }
 ```
 
@@ -164,6 +175,7 @@ Simulate and analyze flash loan strategies including arbitrage, liquidations, an
 ```
 
 **Setup Steps:**
+
 1. Sign up at [infura.io](https://infura.io) (free, no card)
 2. Create project
 3. Copy API key
@@ -176,10 +188,10 @@ Simulate and analyze flash loan strategies including arbitrage, liquidations, an
 ```json
 {
   "networks": {
-    "ethereum": "https://rpc.ankr.com/eth",
-    "polygon": "https://rpc.ankr.com/polygon",
-    "arbitrum": "https://rpc.ankr.com/arbitrum",
-    "optimism": "https://rpc.ankr.com/optimism"
+    "ethereum": "eth",
+    "polygon": "polygon",
+    "arbitrum": "arbitrum",
+    "optimism": "optimism"
   }
 }
 ```
@@ -191,10 +203,12 @@ Simulate and analyze flash loan strategies including arbitrage, liquidations, an
 #### Paid Approach (Alchemy)
 
 **Annual Subscriptions:**
+
 - Alchemy Growth: $49/mo → $588/year
 - Alchemy Scale: $199/mo → $2,388/year (if high usage)
 
 **Advantages:**
+
 - 660 requests/second
 - Advanced analytics dashboard
 - Dedicated support
@@ -202,12 +216,14 @@ Simulate and analyze flash loan strategies including arbitrage, liquidations, an
 #### Free Approach (Public RPCs)
 
 **Annual Subscriptions:**
+
 - Ankr: $0
 - Infura free tier: $0
 - Public RPCs: $0
 - **Total: $0/year**
 
 **Advantages:**
+
 - 25-100 requests/second (sufficient for simulations)
 - Archive data for backtesting
 - No rate limit concerns for development
@@ -218,7 +234,7 @@ Simulate and analyze flash loan strategies including arbitrage, liquidations, an
 
 #### Flash Loan Arbitrage Simulation
 
-```javascript
+```text
 const { ethers } = require('ethers');
 
 // Before (Alchemy - Paid)
@@ -228,7 +244,7 @@ const provider = new ethers.providers.JsonRpcProvider(
 
 // After (Ankr - FREE)
 const provider = new ethers.providers.JsonRpcProvider(
-  'https://rpc.ankr.com/eth'  // $0/mo
+  'eth'  // $0/mo
 );
 
 // Same simulation capability, zero cost
@@ -241,7 +257,7 @@ const profit = calculateArbitrage(uniswapPrice, sushiswapPrice);
 
 #### Aave Liquidation Simulation
 
-```javascript
+```text
 // Using free Infura RPC
 const provider = new ethers.providers.JsonRpcProvider(
   `https://mainnet.infura.io/v3/${INFURA_FREE_KEY}`  // $0 (free tier)
@@ -274,6 +290,7 @@ if (healthFactor < 1e18) {
 ### When Free RPCs Are NOT Enough
 
 **Use paid Alchemy if:**
+
 - You're deploying live flash loan bots (need <50ms latency)
 - You need >100 requests/second
 - You require webhooks for mempool monitoring
@@ -287,7 +304,7 @@ if (healthFactor < 1e18) {
 
 ```javascript
 const RPC_ENDPOINTS = {
-  development: 'https://rpc.ankr.com/eth',  // $0
+  development: 'eth',  // $0
   production: `https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_KEY}`  // $49/mo
 };
 
@@ -300,7 +317,7 @@ const provider = new ethers.providers.JsonRpcProvider(
 
 ### Resources
 
-- **Ankr RPCs:** [rpc.ankr.com](https://rpc.ankr.com) (FREE, no signup)
+- **Ankr RPCs:** rpc.ankr.com (FREE, no signup)
 - **Infura Free:** [infura.io/pricing](https://infura.io/pricing) (100K req/day)
 - **Chainstack Free:** [chainstack.com/pricing](https://chainstack.com/pricing) (3M req/month)
 - **Public RPCs List:** [chainlist.org](https://chainlist.org) (community endpoints)
@@ -312,6 +329,7 @@ const provider = new ethers.providers.JsonRpcProvider(
 ## Usage
 
 The flash loan agent automatically activates when you discuss:
+
 - Flash loan strategies and simulations
 - DeFi arbitrage opportunities
 - Liquidation strategies
@@ -382,6 +400,7 @@ Create a `.flashloan-config.json` file:
 ## Risk Warnings
 
 ️ **Critical Considerations**:
+
 - Smart contract code must be thoroughly audited
 - Gas costs can eliminate profitability
 - Front-running by MEV bots is common
@@ -404,7 +423,7 @@ MIT License - See LICENSE file for details
 ## Support
 
 - GitHub Issues: [Report bugs](https://github.com/jeremylongshore/claude-code-plugins/issues)
-- Documentation: [Full docs](https://docs.claude-code-plugins.com)
+- Documentation: Full docs
 
 ---
 

package/agents/flashloan-agent.md

@@ -10,6 +10,7 @@ You are a specialized agent for simulating flash loan strategies, analyzing DeFi
 ## Your Capabilities
 
 ### Flash Loan Simulation
+
 - Simulate flash loan transactions across Aave, dYdX, Uniswap V3, and Balancer
 - Calculate optimal loan amounts for various strategies
 - Model multi-step transactions with gas costs
@@ -17,6 +18,7 @@ You are a specialized agent for simulating flash loan strategies, analyzing DeFi
 - Test strategies against historical data
 
 ### Arbitrage Analysis
+
 - **DEX arbitrage**: Identify price discrepancies across Uniswap, SushiSwap, Curve, Balancer
 - **Liquidation arbitrage**: Simulate profitable liquidations on lending protocols
 - **Collateral swap**: Optimize position refinancing across protocols
@@ -24,6 +26,7 @@ You are a specialized agent for simulating flash loan strategies, analyzing DeFi
 - **Cross-chain arbitrage**: Simulate bridge-based arbitrage (with flash loans)
 
 ### Strategy Types
+
 1. **Simple Arbitrage**: Buy low on DEX A, sell high on DEX B
 2. **Liquidation**: Flash loan to liquidate undercollateralized positions
 3. **Collateral Swap**: Refinance positions at better rates
@@ -32,6 +35,7 @@ You are a specialized agent for simulating flash loan strategies, analyzing DeFi
 6. **Wash Trading Prevention**: Analyze for circular trading patterns
 
 ### Risk Analysis
+
 - Gas cost modeling with EIP-1559 dynamics
 - Slippage estimation based on liquidity depth
 - Front-running risk assessment
@@ -42,6 +46,7 @@ You are a specialized agent for simulating flash loan strategies, analyzing DeFi
 ## When to Activate
 
 Activate this agent when users need to:
+
 - Simulate flash loan strategies before execution
 - Analyze DEX arbitrage opportunities
 - Calculate optimal liquidation strategies
@@ -54,6 +59,7 @@ Activate this agent when users need to:
 ## Approach
 
 ### Simulation Methodology
+
 1. **Strategy Definition**: Define the flash loan strategy and steps
 2. **Data Collection**: Gather current prices, liquidity, and protocol parameters
 3. **Transaction Modeling**: Build the multi-step transaction flow
@@ -63,7 +69,9 @@ Activate this agent when users need to:
 7. **Optimization**: Suggest improvements to maximize profitability
 
 ### Output Format
+
 Present simulations in structured format:
+
 ```
  FLASH LOAN STRATEGY SIMULATION
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -149,6 +157,7 @@ contract FlashLoanArbitrage {
     }
 }
 ```
+
 ```
 
 ## Flash Loan Providers
@@ -192,22 +201,30 @@ Always include comprehensive risk warnings:
 
 ### 1. Simple DEX Arbitrage
 ```
+
 Borrow 1000 ETH → Buy USDC on Uniswap → Sell USDC on SushiSwap → Repay ETH
+
 ```
 
 ### 2. Liquidation on Aave
 ```
+
 Borrow collateral asset → Liquidate undercollateralized position → Sell collateral → Repay loan
+
 ```
 
 ### 3. Collateral Swap
 ```
+
 Borrow new collateral → Deposit to protocol → Withdraw old collateral → Swap → Repay loan
+
 ```
 
 ### 4. Triangular Arbitrage
 ```
+
 Borrow ETH → ETH to USDC → USDC to DAI → DAI to ETH (at profit) → Repay
+
 ```
 
 ## Simulation Tools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentsolutionsio/flash-loan-simulator",
-  "version": "1.0.0",
+  "version": "1.0.5",
   "description": "Simulate and analyze flash loan strategies including arbitrage, liquidations, and collateral swaps",
   "keywords": [
     "crypto",

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

@@ -60,33 +60,43 @@ The flash loan simulator uses a **strategy-protocol abstraction pattern** where
 ## Progressive Disclosure Strategy
 
 ### Level 1: Quick Profitability Check (Default)
+
 ```bash
 python flash_simulator.py arbitrage ETH USDC 100 --provider aave
 ```
+
 Output: Simple profit/loss with recommendation.
 
 ### Level 2: Detailed Breakdown
+
 ```bash
 python flash_simulator.py arbitrage ETH USDC 100 --breakdown
 ```
+
 Output: Step-by-step costs and revenues.
 
 ### Level 3: Multi-Provider Comparison
+
 ```bash
 python flash_simulator.py arbitrage ETH USDC 100 --compare-providers
 ```
+
 Output: Aave vs dYdX vs Balancer comparison.
 
 ### Level 4: Risk Analysis
+
 ```bash
 python flash_simulator.py arbitrage ETH USDC 100 --risk-analysis
 ```
+
 Output: MEV competition, execution risk, protocol risk scores.
 
 ### Level 5: Full Simulation
+
 ```bash
 python flash_simulator.py arbitrage ETH USDC 100 --full --output json
 ```
+
 Output: Complete analysis with all details.
 
 ## Tool Permission Strategy
@@ -96,11 +106,13 @@ allowed-tools: Read, Write, Edit, Grep, Glob, Bash(crypto:flashloan-*)
 ```
 
 ### Rationale
+
 - **Read/Write/Edit**: Configuration and output management
 - **Grep/Glob**: Search for contract addresses and ABIs
 - **Bash(crypto:flashloan-*)**: Scoped to flash loan simulation scripts
 
 ### Prohibited
+
 - No unrestricted Bash execution
 - No private key or wallet access
 - No actual transaction signing
@@ -161,7 +173,6 @@ class FlashLoanProvider(ABC):
         """Simulate flash loan execution."""
         pass
 
-
 class AaveV3Provider(FlashLoanProvider):
     """Aave V3 flash loan provider adapter."""
 
@@ -176,7 +187,6 @@ class AaveV3Provider(FlashLoanProvider):
     def get_fee(self, asset: str, amount: Decimal) -> Decimal:
         return amount * self.FEE_RATE
 
-
 class DydxProvider(FlashLoanProvider):
     """dYdX flash loan provider adapter (0% fee)."""
 
@@ -187,7 +197,6 @@ class DydxProvider(FlashLoanProvider):
     def get_fee(self, asset: str, amount: Decimal) -> Decimal:
         return Decimal("0")  # dYdX has 0% flash loan fee
 
-
 class BalancerProvider(FlashLoanProvider):
     """Balancer flash loan provider adapter."""
 
@@ -210,7 +219,6 @@ class FlashLoanStrategy(ABC):
         """Calculate net profit after all costs."""
         pass
 
-
 class SimpleArbitrageStrategy(FlashLoanStrategy):
     """Two-DEX arbitrage: buy low, sell high."""
 
@@ -222,7 +230,6 @@ class SimpleArbitrageStrategy(FlashLoanStrategy):
         # 5. Keep profit
         pass
 
-
 class LiquidationStrategy(FlashLoanStrategy):
     """Liquidate undercollateralized positions."""
 
@@ -342,12 +349,11 @@ class SimulationError(Exception):
         self.recoverable = recoverable
         self.hint = hint
 
-
 class RPCManager:
     """RPC connection manager with automatic fallback."""
 
     PROVIDERS = [
-        "https://rpc.ankr.com/eth",
+        "eth",
         "https://eth.llamarpc.com",
         "https://ethereum.publicnode.com",
     ]
@@ -404,17 +410,20 @@ python flash_simulator.py --opportunities opportunities.json --simulate-all
 ## Testing Strategy
 
 ### Unit Tests
+
 - Protocol adapter fee calculations
 - Profit calculation math
 - Risk scoring algorithms
 - Gas estimation accuracy
 
 ### Integration Tests
+
 - RPC connectivity (mocked)
 - Multi-provider comparison
 - Strategy composition
 
 ### Acceptance Tests
+
 - Simulation matches historical actual profits (±10%)
 - All strategy types complete without error
 - Free RPC tier sufficient for basic usage
@@ -422,12 +431,14 @@ python flash_simulator.py --opportunities opportunities.json --simulate-all
 ## Security & Compliance
 
 ### Safety Measures
+
 - **No execution**: Simulation only, never signs transactions
 - **No private keys**: Tool cannot access wallets
 - **Read-only RPC**: Only view functions, no state changes
 - **Educational disclaimer**: Clear warnings about real risks
 
 ### Data Handling
+
 - No sensitive data storage
 - API keys in environment variables only
 - No transaction broadcasting
@@ -435,6 +446,7 @@ python flash_simulator.py --opportunities opportunities.json --simulate-all
 ## Dependencies
 
 ### Python Packages
+
 ```
 web3>=6.0.0            # Ethereum interaction
 httpx>=0.24.0          # Async HTTP client
@@ -443,11 +455,13 @@ rich>=13.0             # Terminal formatting
 ```
 
 ### External Services
+
 - Free RPC endpoints (Ankr, Chainstack free tier, Infura free tier)
 - DeFiLlama API (protocol TVL)
 - Etherscan API (gas oracle)
 
 ### Protocol Contracts (Read-Only)
+
 - Aave V3 Pool
 - dYdX Solo Margin
 - Balancer Vault

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

@@ -20,18 +20,21 @@ Flash loans are powerful DeFi primitives that allow borrowing any amount without
 ## 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
@@ -63,13 +66,13 @@ Flash loans are powerful DeFi primitives that allow borrowing any amount without
 
 ### Important (P1)
 
-4. **As a researcher**, I want to simulate triangular arbitrage, so that I can evaluate multi-hop strategies.
+1. **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.
+2. **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
@@ -77,7 +80,7 @@ Flash loans are powerful DeFi primitives that allow borrowing any amount without
 
 ### Nice-to-Have (P2)
 
-6. **As an auditor**, I want to simulate flash loan attack scenarios, so that I can test protocol security.
+1. **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
@@ -196,12 +199,14 @@ Flash loans are powerful DeFi primitives that allow borrowing any amount without
 ## 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
@@ -227,6 +232,7 @@ Flash loans are powerful DeFi primitives that allow borrowing any amount without
 - Protocol exploits may have legal implications
 
 Users should:
+
 - Never deploy unaudited code
 - Start with testnets before mainnet
 - Understand the risks fully

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

@@ -1,16 +1,23 @@
 ---
 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".
+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]
+tags:
+- crypto
+- simulating-flash
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
 # Simulating Flash Loans
 
@@ -32,29 +39,40 @@ Simulate flash loan strategies across Aave V3, dYdX, and Balancer with profitabi
 ## 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
@@ -83,17 +101,20 @@ 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
 ```
@@ -104,6 +125,6 @@ See `${CLAUDE_SKILL_DIR}/references/examples.md` for multi-provider comparison a
 
 - `${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)
+- dYdX Flash Loans
+- Balancer Flash Loans
 - [Flashbots Protect](https://docs.flashbots.net/flashbots-protect/overview)