237-combo/scenarios/README.md

📋 DeFi Strategy Testing Scenarios

This directory contains example scenarios for testing DeFi strategies using the DeFi Strategy Testing CLI.

---

📚 Example Scenarios

🏦 Aave v3

📈 Leveraged Long Strategy

File: leveraged-long.yml

A leveraged long strategy using Aave v3:

• ✅ Supplies WETH as collateral
• ✅ Borrows USDC
• ✅ Swaps USDC to WETH to increase exposure
• ✅ Validates health factor remains safe

💥 Liquidation Drill

File: liquidation-drill.yml

Tests liquidation scenarios:

• ✅ Sets up a position near liquidation threshold
• ✅ Applies oracle shock
• ✅ Validates health factor drops below 1.0
• ✅ Repays debt to recover

🏛️ Compound v3

💰 Supply and Borrow

File: supply-borrow.yml

Basic Compound v3 supply and borrow:

• ✅ Supplies WETH as collateral
• ✅ Borrows USDC (base asset)
• ✅ Validates borrow balance
• ✅ Repays part of debt

---

🚀 Running Scenarios

Basic Run

# Run a scenario
pnpm run strat:run scenarios/aave/leveraged-long.yml

With Custom Network

# Run with custom network
pnpm run strat:run scenarios/aave/leveraged-long.yml --network base

Generate Reports

# Generate JSON and HTML reports
pnpm run strat:run scenarios/aave/leveraged-long.yml \
  --report out/run.json \
  --html out/report.html

---

📝 Scenario Format

Scenarios are defined in YAML or JSON format:

version: 1
network: mainnet
protocols: [aave-v3, uniswap-v3]

assumptions:
  baseCurrency: USD
  slippageBps: 30
  minHealthFactor: 1.05

accounts:
  trader:
    funded:
      - token: WETH
        amount: "5"

steps:
  - name: Supply WETH
    action: aave-v3.supply
    args:
      asset: WETH
      amount: "5"
      onBehalfOf: $accounts.trader
    assert:
      - aave-v3.healthFactor >= 1.5

---

🔌 Supported Actions

🏦 Aave v3

Action	Description
aave-v3.supply	Supply assets to Aave
aave-v3.withdraw	Withdraw assets from Aave
aave-v3.borrow	Borrow assets from Aave
aave-v3.repay	Repay borrowed assets
aave-v3.flashLoanSimple	Execute a flash loan

🏛️ Compound v3

Action	Description
compound-v3.supply	Supply collateral to Compound v3
compound-v3.withdraw	Withdraw collateral or base asset
compound-v3.borrow	Borrow base asset (withdraws base asset)
compound-v3.repay	Repay debt (supplies base asset)

🔄 Uniswap v3

Action	Description
uniswap-v3.exactInputSingle	Execute an exact input swap
uniswap-v3.exactOutputSingle	Execute an exact output swap

💰 ERC20

Action	Description
erc20.approve	Approve token spending

💥 Failure Injection

Action	Description
failure.oracleShock	Inject an oracle price shock
failure.timeTravel	Advance time
failure.setTimestamp	Set block timestamp
failure.liquidityShock	Move liquidity
failure.setBaseFee	Set gas price
failure.pauseReserve	Pause a reserve (Aave)
failure.capExhaustion	Simulate cap exhaustion

---

✅ Assertions

Assertions can be added to any step:

steps:
  - name: Check health factor
    action: assert
    args:
      expression: "aave-v3.healthFactor >= 1.05"

Supported Assertion Formats

Format	Example	Description
Protocol views	aave-v3.healthFactor >= 1.05	Compare protocol view values
Comparisons	>=, <=, >, <, ==, !=	Standard comparison operators

---

🌐 Network Support

Network	Chain ID	Status
Ethereum Mainnet	1	✅
Base	8453	✅
Arbitrum One	42161	✅
Optimism	10	✅
Polygon	137	✅

💡 Or use chain IDs directly: --network 1 for mainnet.

---

📖 Next Steps

• 📚 Read the Strategy Testing Guide for comprehensive documentation
• 🎯 Explore example scenarios in this directory
• 🧪 Try running scenarios with different parameters
• 💥 Experiment with failure injection scenarios