@intentsolutionsio/flash-loan-simulator 1.0.0 → 1.0.5

package/skills/simulating-flash-loans/references/errors.md

@@ -3,6 +3,7 @@
 ## RPC Connection Errors
 
 ### ERR-001: RPC Connection Timeout
+
 ```
 Error: Request timed out after 30000ms
 ```
@@ -10,16 +11,20 @@ Error: Request timed out after 30000ms
 **Cause:** Network latency or overloaded RPC endpoint.
 
 **Solution:**
+
 1. Switch to a different RPC endpoint:
+
    ```yaml
    rpc_endpoints:
-     ethereum: "https://rpc.ankr.com/eth"      # Free, no signup
+     ethereum: "eth"      # Free, no signup
      backup: "https://eth.llamarpc.com"        # Alternative
    ```
+
 2. Increase timeout in settings.yaml
 3. Check network connectivity
 
 ### ERR-002: RPC Rate Limited
+
 ```
 Error: 429 Too Many Requests
 ```
@@ -27,11 +32,14 @@ Error: 429 Too Many Requests
 **Cause:** Free RPC tier limits exceeded.
 
 **Solution:**
+
 1. Add delay between requests:
+
    ```python
    import time
    time.sleep(0.5)  # 500ms between calls
    ```
+
 2. Switch to a different free RPC (rotate between Ankr, Chainstack, Llamarpc)
 3. Use a private RPC for production (Alchemy, Chainstack, Infura, or QuickNode)
 
@@ -40,6 +48,7 @@ Error: 429 Too Many Requests
 ## Simulation Errors
 
 ### ERR-010: Insufficient Liquidity
+
 ```
 Error: Loan amount exceeds available liquidity
 Provider: Aave V3
@@ -50,11 +59,13 @@ Requested: 100,000 ETH
 **Cause:** Flash loan amount exceeds pool depth.
 
 **Solution:**
+
 1. Reduce loan amount
 2. Split across multiple providers
 3. Use a different asset with more liquidity
 
 ### ERR-011: Unsupported Asset
+
 ```
 Error: Asset 'SHIB' not supported by provider 'dYdX'
 ```
@@ -62,14 +73,18 @@ Error: Asset 'SHIB' not supported by provider 'dYdX'
 **Cause:** Provider doesn't support the requested token.
 
 **Solution:**
+
 1. Check provider's supported assets:
+
    ```bash
    python flash_simulator.py compare SHIB 1000
    ```
+
 2. Use a different provider (Aave V3 supports more assets)
 3. Swap to a supported intermediary token
 
 ### ERR-012: Chain Mismatch
+
 ```
 Error: Provider 'dYdX' not available on chain 'polygon'
 ```
@@ -77,6 +92,7 @@ Error: Provider 'dYdX' not available on chain 'polygon'
 **Cause:** Provider only operates on specific chains.
 
 **Solution:**
+
 1. Check provider chains:
    - dYdX: Ethereum only
    - Aave V3: Ethereum, Polygon, Arbitrum, Optimism, Avalanche
@@ -88,6 +104,7 @@ Error: Provider 'dYdX' not available on chain 'polygon'
 ## Strategy Errors
 
 ### ERR-020: No Profitable Route
+
 ```
 Error: All simulated routes result in loss
 Best route: -0.05 ETH (-$125.00)
@@ -96,12 +113,14 @@ Best route: -0.05 ETH (-$125.00)
 **Cause:** Current market conditions don't support the arbitrage.
 
 **Solution:**
+
 1. Wait for better price differences
 2. Try different token pairs
 3. Consider smaller trade sizes (less slippage)
 4. Check for stale price data
 
 ### ERR-021: Negative Profit Margin
+
 ```
 Warning: Strategy unprofitable after costs
 Gross profit: +0.10 ETH
@@ -112,12 +131,14 @@ Net profit: -0.05 ETH
 **Cause:** Costs (gas + fees) exceed the arbitrage opportunity.
 
 **Solution:**
+
 1. Use a zero-fee provider (dYdX)
 2. Wait for lower gas prices
 3. Increase trade size to improve margin ratio
 4. Find larger price discrepancies
 
 ### ERR-022: High MEV Competition
+
 ```
 Warning: MEV competition score 85/100
 This pair has high bot activity
@@ -126,6 +147,7 @@ This pair has high bot activity
 **Cause:** ETH/USDC and similar pairs are heavily competed.
 
 **Solution:**
+
 1. Use Flashbots Protect for private transactions
 2. Try less-competitive pairs
 3. Consider smaller, faster trades
@@ -136,6 +158,7 @@ This pair has high bot activity
 ## Risk Assessment Errors
 
 ### ERR-030: Critical Risk Score
+
 ```
 Warning: Risk score 78/100 (CRITICAL)
 Viability: NO-GO
@@ -144,14 +167,18 @@ Viability: NO-GO
 **Cause:** Multiple risk factors are elevated.
 
 **Solution:**
+
 1. Review individual risk factors:
+
    ```bash
    python flash_simulator.py arbitrage ETH USDC 100 --risk-analysis
    ```
+
 2. Address the highest-scoring factors
 3. Consider a different strategy or timing
 
 ### ERR-031: Protocol Risk Warning
+
 ```
 Warning: Using unaudited protocol 'NewDEX'
 Protocol risk score: 80/100
@@ -160,6 +187,7 @@ Protocol risk score: 80/100
 **Cause:** Less-established protocol increases smart contract risk.
 
 **Solution:**
+
 1. Verify protocol audits before using
 2. Stick to well-audited protocols (Aave, Uniswap, Balancer)
 3. Limit exposure to newer protocols
@@ -169,6 +197,7 @@ Protocol risk score: 80/100
 ## Gas Estimation Errors
 
 ### ERR-040: Gas Price Spike
+
 ```
 Warning: Current gas price 150 gwei (normal: 30 gwei)
 Strategy breakeven gas: 45 gwei
@@ -177,16 +206,20 @@ Strategy breakeven gas: 45 gwei
 **Cause:** Network congestion causing unprofitable gas costs.
 
 **Solution:**
+
 1. Wait for gas prices to normalize
 2. Use gas oracles to estimate future prices:
+
    ```python
    # Check if current gas is above breakeven
    if current_gas > breakeven_gas:
        print("Wait for lower gas prices")
    ```
+
 3. Set gas price limits in execution scripts
 
 ### ERR-041: Gas Estimation Failed
+
 ```
 Error: Could not estimate gas for transaction
 ```
@@ -194,6 +227,7 @@ Error: Could not estimate gas for transaction
 **Cause:** Transaction would revert on-chain.
 
 **Solution:**
+
 1. Check token approvals
 2. Verify sufficient balances
 3. Test on forked mainnet first
@@ -204,11 +238,13 @@ Error: Could not estimate gas for transaction
 ## Input Validation Errors
 
 ### ERR-050: Invalid Amount
+
 ```
 Error: Invalid amount 'abc' - must be numeric
 ```
 
 **Solution:**
+
 ```bash
 # Correct usage
 python flash_simulator.py arbitrage ETH USDC 100    # Integer
@@ -216,6 +252,7 @@ python flash_simulator.py arbitrage ETH USDC 100.5  # Decimal
 ```
 
 ### ERR-051: Invalid Token Symbol
+
 ```
 Error: Unknown token 'ETHEREUM' - did you mean 'ETH'?
 ```
@@ -224,11 +261,13 @@ Error: Unknown token 'ETHEREUM' - did you mean 'ETH'?
 Use standard token symbols: ETH, WETH, USDC, USDT, DAI, WBTC
 
 ### ERR-052: Invalid Provider
+
 ```
 Error: Unknown provider 'aavev3' - valid options: aave, dydx, balancer, uniswap
 ```
 
 **Solution:**
+
 ```bash
 # Use lowercase provider names
 python flash_simulator.py arbitrage ETH USDC 100 --provider aave
@@ -239,6 +278,7 @@ python flash_simulator.py arbitrage ETH USDC 100 --provider aave
 ## Output/Format Errors
 
 ### ERR-060: JSON Export Failed
+
 ```
 Error: Cannot serialize Decimal to JSON
 ```
@@ -246,6 +286,7 @@ Error: Cannot serialize Decimal to JSON
 **Cause:** Custom Decimal types not handled.
 
 **Solution:** The simulator handles this automatically. If using custom code:
+
 ```python
 from formatters import DecimalEncoder
 import json
@@ -257,7 +298,9 @@ json.dumps(data, cls=DecimalEncoder)
 ## Recovery Procedures
 
 ### Complete Reset
+
 If simulator is in an inconsistent state:
+
 ```bash
 # Clear any cached data
 rm -rf ~/.cache/flash-simulator/
@@ -267,14 +310,16 @@ pip install --upgrade web3 httpx
 ```
 
 ### Verify RPC Connectivity
+
 ```bash
 # Test RPC endpoint
 curl -X POST -H "Content-Type: application/json" \
   --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
-  https://rpc.ankr.com/eth
+  eth
 ```
 
 ### Test Simulation Engine
+
 ```bash
 # Run built-in demo
 python strategy_engine.py

package/skills/simulating-flash-loans/references/examples.md

@@ -14,6 +14,7 @@ python flash_simulator.py arbitrage ETH USDC 100 \
 ```
 
 **Expected Output:**
+
 ```
 ==================== FLASH LOAN SIMULATION ====================
 
@@ -70,6 +71,7 @@ python flash_simulator.py compare ETH 100
 ```
 
 **Expected Output:**
+
 ```
 =================== PROVIDER COMPARISON ===================
 
@@ -97,6 +99,7 @@ python flash_simulator.py arbitrage ETH USDC 100 --full
 ```
 
 **Expected Output:**
+
 ```
 ==================== FLASH LOAN SIMULATION ====================
 [... strategy result ...]
@@ -174,6 +177,7 @@ python flash_simulator.py triangular ETH USDC WBTC ETH --amount 50
 ```
 
 **Expected Output:**
+
 ```
 ==================== FLASH LOAN SIMULATION ====================
 
@@ -240,6 +244,7 @@ python flash_simulator.py liquidation \
 ```
 
 **Expected Output:**
+
 ```
 ==================== FLASH LOAN SIMULATION ====================
 
@@ -296,6 +301,7 @@ python flash_simulator.py arbitrage ETH USDC 100 --full --output json > simulati
 ```
 
 **Example JSON Output:**
+
 ```json
 {
   "simulation": {
@@ -369,6 +375,7 @@ python flash_simulator.py arbitrage ETH USDC 100 \
 ```
 
 **Key Difference:**
+
 - Flash loan fee: 0.00 ETH (vs 0.09 ETH with Aave)
 - Net profit increases by ~$225
 
@@ -386,6 +393,7 @@ python flash_simulator.py arbitrage ETH USDC 100 \
 ```
 
 This adjusts:
+
 - All USD calculations use $3,500/ETH
 - Gas costs calculated at 50 gwei
 - Breakeven gas price recalculated
@@ -482,6 +490,7 @@ if __name__ == "__main__":
 ## Integration Patterns
 
 ### Batch Analysis
+
 ```bash
 # Analyze multiple pairs
 for pair in "ETH-USDC" "WBTC-ETH" "ETH-DAI"; do
@@ -491,6 +500,7 @@ done
 ```
 
 ### Pipeline Integration
+
 ```bash
 # Feed into analysis pipeline
 python flash_simulator.py arbitrage ETH USDC 100 --output json | \
@@ -498,6 +508,7 @@ python flash_simulator.py arbitrage ETH USDC 100 --output json | \
 ```
 
 ### Automated Monitoring
+
 ```bash
 # Check profitability every minute
 while true; do
@@ -523,6 +534,7 @@ All examples are for educational purposes only. Flash loan strategies involve si
 4. **Market Risk**: Prices change between simulation and execution
 
 Always:
+
 - Test on testnets first
 - Start with small amounts
 - Use MEV protection in production

package/skills/simulating-flash-loans/references/implementation.md

@@ -40,6 +40,7 @@ When `--risk-analysis` is enabled, four risk factors are scored 0-100:
 - **Liquidity Risk** (0-100): Whether pool depth supports the trade size. Score > 80 means trade may move price significantly.
 
 Overall viability grades:
+
 - **A**: All risks low, high confidence
 - **B**: Moderate risks, proceed with caution
 - **C**: High risks, likely unprofitable
@@ -48,20 +49,25 @@ Overall viability grades:
 ## Output Modes
 
 **Quick Mode** (default):
+
 - Net profit/loss, provider recommendation, Go/No-Go verdict
 
 **Breakdown Mode** (`--breakdown`):
+
 - Step-by-step transaction flow, individual cost components, slippage estimates
 
 **Comparison Mode** (`--compare-providers`):
+
 - All providers ranked by net profit, fee differences, liquidity availability
 
 **Risk Analysis** (`--risk-analysis`):
+
 - Competition score, execution probability, protocol safety, overall viability grade
 
 ## Educational Disclaimer
 
 **FOR EDUCATIONAL PURPOSES ONLY.** Flash loan strategies involve significant risks:
+
 - Smart contract bugs can cause total loss of borrowed funds
 - MEV bots compete for the same opportunities with faster infrastructure
 - Gas costs can exceed profits, especially during network congestion

package/skills/simulating-flash-loans/scripts/flash_simulator.py

@@ -18,7 +18,6 @@ Usage:
 import argparse
 import sys
 from decimal import Decimal, InvalidOperation
-from typing import Optional
 
 from strategy_engine import (
     StrategyFactory,
@@ -77,77 +76,39 @@ EDUCATIONAL DISCLAIMER:
     subparsers = parser.add_subparsers(dest="command", help="Simulation type")
 
     # Arbitrage subcommand
-    arb_parser = subparsers.add_parser(
-        "arbitrage", help="Simple two-DEX arbitrage simulation"
-    )
-    arb_parser.add_argument(
-        "input_token", help="Input token (e.g., ETH)"
-    )
-    arb_parser.add_argument(
-        "output_token", help="Output token (e.g., USDC)"
-    )
-    arb_parser.add_argument(
-        "amount", type=str, help="Loan amount"
-    )
-    arb_parser.add_argument(
-        "--dex-buy", default="sushiswap", help="DEX to buy on (default: sushiswap)"
-    )
-    arb_parser.add_argument(
-        "--dex-sell", default="uniswap", help="DEX to sell on (default: uniswap)"
-    )
-    arb_parser.add_argument(
-        "--provider", default="aave", help="Flash loan provider (default: aave)"
-    )
+    arb_parser = subparsers.add_parser("arbitrage", help="Simple two-DEX arbitrage simulation")
+    arb_parser.add_argument("input_token", help="Input token (e.g., ETH)")
+    arb_parser.add_argument("output_token", help="Output token (e.g., USDC)")
+    arb_parser.add_argument("amount", type=str, help="Loan amount")
+    arb_parser.add_argument("--dex-buy", default="sushiswap", help="DEX to buy on (default: sushiswap)")
+    arb_parser.add_argument("--dex-sell", default="uniswap", help="DEX to sell on (default: uniswap)")
+    arb_parser.add_argument("--provider", default="aave", help="Flash loan provider (default: aave)")
 
     # Triangular arbitrage subcommand
-    tri_parser = subparsers.add_parser(
-        "triangular", help="Multi-hop circular arbitrage simulation"
-    )
-    tri_parser.add_argument(
-        "tokens", nargs="+", help="Token path (e.g., ETH USDC WBTC ETH)"
-    )
-    tri_parser.add_argument(
-        "--amount", type=str, required=True, help="Loan amount"
-    )
-    tri_parser.add_argument(
-        "--provider", default="aave", help="Flash loan provider (default: aave)"
-    )
+    tri_parser = subparsers.add_parser("triangular", help="Multi-hop circular arbitrage simulation")
+    tri_parser.add_argument("tokens", nargs="+", help="Token path (e.g., ETH USDC WBTC ETH)")
+    tri_parser.add_argument("--amount", type=str, required=True, help="Loan amount")
+    tri_parser.add_argument("--provider", default="aave", help="Flash loan provider (default: aave)")
 
     # Liquidation subcommand
-    liq_parser = subparsers.add_parser(
-        "liquidation", help="Liquidation opportunity analysis"
-    )
-    liq_parser.add_argument(
-        "--protocol", default="aave", help="Lending protocol (default: aave)"
-    )
+    liq_parser = subparsers.add_parser("liquidation", help="Liquidation opportunity analysis")
+    liq_parser.add_argument("--protocol", default="aave", help="Lending protocol (default: aave)")
     liq_parser.add_argument(
         "--health-factor",
         type=float,
         default=0.95,
         help="Health factor threshold (default: 0.95)",
     )
-    liq_parser.add_argument(
-        "--collateral", default="ETH", help="Collateral asset (default: ETH)"
-    )
-    liq_parser.add_argument(
-        "--debt", default="USDC", help="Debt asset (default: USDC)"
-    )
-    liq_parser.add_argument(
-        "--amount", type=str, default="10", help="Debt amount to liquidate"
-    )
-    liq_parser.add_argument(
-        "--provider", default="aave", help="Flash loan provider (default: aave)"
-    )
+    liq_parser.add_argument("--collateral", default="ETH", help="Collateral asset (default: ETH)")
+    liq_parser.add_argument("--debt", default="USDC", help="Debt asset (default: USDC)")
+    liq_parser.add_argument("--amount", type=str, default="10", help="Debt amount to liquidate")
+    liq_parser.add_argument("--provider", default="aave", help="Flash loan provider (default: aave)")
 
     # Compare providers subcommand
-    cmp_parser = subparsers.add_parser(
-        "compare", help="Compare flash loan providers"
-    )
+    cmp_parser = subparsers.add_parser("compare", help="Compare flash loan providers")
     cmp_parser.add_argument("asset", help="Asset to borrow (e.g., ETH)")
     cmp_parser.add_argument("amount", type=str, help="Amount to borrow")
-    cmp_parser.add_argument(
-        "--chain", default="ethereum", help="Chain (default: ethereum)"
-    )
+    cmp_parser.add_argument("--chain", default="ethereum", help="Chain (default: ethereum)")
 
     # Global options
     for sub in [arb_parser, tri_parser, liq_parser]:
@@ -223,9 +184,7 @@ def run_arbitrage(args: argparse.Namespace) -> int:
     providers = None
 
     if args.full or hasattr(args, "compare_providers") and args.compare_providers:
-        calculator = ProfitCalculator(
-            eth_price_usd=args.eth_price, gas_price_gwei=args.gas_price
-        )
+        calculator = ProfitCalculator(eth_price_usd=args.eth_price, gas_price_gwei=args.gas_price)
         breakdown = calculator.calculate_breakdown(result)
 
     if args.full or (hasattr(args, "risk_analysis") and args.risk_analysis):
@@ -234,9 +193,7 @@ def run_arbitrage(args: argparse.Namespace) -> int:
 
     if args.full or (hasattr(args, "compare_providers") and args.compare_providers):
         manager = ProviderManager()
-        providers = manager.compare_providers(
-            args.input_token.upper(), amount, "ethereum"
-        )
+        providers = manager.compare_providers(args.input_token.upper(), amount, "ethereum")
 
     # Format output
     output_result(args, result, breakdown, assessment, providers)
@@ -276,18 +233,14 @@ def run_triangular(args: argparse.Namespace) -> int:
     providers = None
 
     if args.full:
-        calculator = ProfitCalculator(
-            eth_price_usd=args.eth_price, gas_price_gwei=args.gas_price
-        )
+        calculator = ProfitCalculator(eth_price_usd=args.eth_price, gas_price_gwei=args.gas_price)
         breakdown = calculator.calculate_breakdown(result)
 
         assessor = RiskAssessor(eth_price_usd=args.eth_price)
         assessment = assessor.assess(result)
 
         manager = ProviderManager()
-        providers = manager.compare_providers(
-            args.tokens[0].upper(), amount, "ethereum"
-        )
+        providers = manager.compare_providers(args.tokens[0].upper(), amount, "ethereum")
 
     if hasattr(args, "risk_analysis") and args.risk_analysis:
         assessor = RiskAssessor(eth_price_usd=args.eth_price)
@@ -330,18 +283,14 @@ def run_liquidation(args: argparse.Namespace) -> int:
     providers = None
 
     if args.full:
-        calculator = ProfitCalculator(
-            eth_price_usd=args.eth_price, gas_price_gwei=args.gas_price
-        )
+        calculator = ProfitCalculator(eth_price_usd=args.eth_price, gas_price_gwei=args.gas_price)
         breakdown = calculator.calculate_breakdown(result)
 
         assessor = RiskAssessor(eth_price_usd=args.eth_price)
         assessment = assessor.assess(result)
 
         manager = ProviderManager()
-        providers = manager.compare_providers(
-            args.debt.upper(), amount, "ethereum"
-        )
+        providers = manager.compare_providers(args.debt.upper(), amount, "ethereum")
 
     if hasattr(args, "risk_analysis") and args.risk_analysis:
         assessor = RiskAssessor(eth_price_usd=args.eth_price)
@@ -362,9 +311,7 @@ def run_compare(args: argparse.Namespace) -> int:
         return 1
 
     manager = ProviderManager()
-    providers = manager.compare_providers(
-        args.asset.upper(), amount, args.chain.lower()
-    )
+    providers = manager.compare_providers(args.asset.upper(), amount, args.chain.lower())
 
     if not providers:
         print(
@@ -375,7 +322,7 @@ def run_compare(args: argparse.Namespace) -> int:
 
     # Format output
     if args.output == "json":
-        json_fmt = JSONFormatter()
+        JSONFormatter()
         # Create a minimal result for JSON output
         output = {
             "comparison": {
@@ -396,6 +343,7 @@ def run_compare(args: argparse.Namespace) -> int:
             ],
         }
         import json
+
         print(json.dumps(output, indent=2))
     else:
         console = ConsoleFormatter()
@@ -436,11 +384,7 @@ def output_result(
 
         # Show provider comparison if calculated
         if providers:
-            print(
-                console.format_provider_comparison(
-                    providers, result.loan_asset, result.loan_amount
-                )
-            )
+            print(console.format_provider_comparison(providers, result.loan_asset, result.loan_amount))
 
         # Always show quick summary at end
         print(console.format_quick_summary(result, assessment))