Initial commit: add .gitignore and README

2026-02-09 21:51:54 -08:00
commit 7003349717
127 changed files with 17576 additions and 0 deletions
--- a/docs/STRATEGY_AUTHORING_GUIDE.md
+++ b/docs/STRATEGY_AUTHORING_GUIDE.md
@@ -0,0 +1,311 @@
+# Strategy Authoring Guide
+
+## Overview
+
+This guide explains how to create and author DeFi strategies using the Strategic executor system.
+
+## Strategy Structure
+
+A strategy is a JSON file that defines a sequence of DeFi operations to execute atomically.
+
+### Basic Structure
+
+```json
+{
+  "name": "Strategy Name",
+  "description": "What this strategy does",
+  "chain": "mainnet",
+  "executor": "0x...",
+  "blinds": [],
+  "guards": [],
+  "steps": []
+}
+```
+
+## Components
+
+### 1. Strategy Metadata
+
+- **name**: Unique identifier for the strategy
+- **description**: Human-readable description
+- **chain**: Target blockchain (mainnet, arbitrum, optimism, base)
+- **executor**: Optional executor contract address (can be set via env)
+
+### 2. Blinds (Sealed Runtime Parameters)
+
+Blinds are values that are substituted at runtime, not stored in the strategy file.
+
+```json
+{
+  "blinds": [
+    {
+      "name": "amount",
+      "type": "uint256",
+      "description": "Amount to supply"
+    }
+  ]
+}
+```
+
+Use blinds in steps:
+```json
+{
+  "amount": { "blind": "amount" }
+}
+```
+
+### 3. Guards (Safety Checks)
+
+Guards prevent unsafe execution:
+
+```json
+{
+  "guards": [
+    {
+      "type": "minHealthFactor",
+      "params": {
+        "minHF": 1.2,
+        "user": "0x..."
+      },
+      "onFailure": "revert"
+    }
+  ]
+}
+```
+
+**Guard Types**:
+- `oracleSanity`: Price validation
+- `twapSanity`: TWAP price checks
+- `maxGas`: Gas limits
+- `minHealthFactor`: Aave health factor
+- `slippage`: Slippage protection
+- `positionDeltaLimit`: Position size limits
+
+**onFailure Options**:
+- `revert`: Stop execution (default)
+- `warn`: Log warning but continue
+- `skip`: Skip the step
+
+### 4. Steps (Operations)
+
+Steps define the actual DeFi operations:
+
+```json
+{
+  "steps": [
+    {
+      "id": "step1",
+      "description": "Supply to Aave",
+      "guards": [],
+      "action": {
+        "type": "aaveV3.supply",
+        "asset": "0x...",
+        "amount": "1000000"
+      }
+    }
+  ]
+}
+```
+
+## Action Types
+
+### Aave v3
+
+```json
+{
+  "type": "aaveV3.supply",
+  "asset": "0x...",
+  "amount": "1000000",
+  "onBehalfOf": "0x..." // optional
+}
+```
+
+```json
+{
+  "type": "aaveV3.withdraw",
+  "asset": "0x...",
+  "amount": "1000000",
+  "to": "0x..." // optional
+}
+```
+
+```json
+{
+  "type": "aaveV3.borrow",
+  "asset": "0x...",
+  "amount": "1000000",
+  "interestRateMode": "variable", // or "stable"
+  "onBehalfOf": "0x..." // optional
+}
+```
+
+```json
+{
+  "type": "aaveV3.repay",
+  "asset": "0x...",
+  "amount": "1000000",
+  "rateMode": "variable",
+  "onBehalfOf": "0x..." // optional
+}
+```
+
+```json
+{
+  "type": "aaveV3.flashLoan",
+  "assets": ["0x..."],
+  "amounts": ["1000000"],
+  "modes": [0] // optional
+}
+```
+
+### Uniswap v3
+
+```json
+{
+  "type": "uniswapV3.swap",
+  "tokenIn": "0x...",
+  "tokenOut": "0x...",
+  "fee": 3000,
+  "amountIn": "1000000",
+  "amountOutMinimum": "990000", // optional
+  "exactInput": true
+}
+```
+
+### Compound v3
+
+```json
+{
+  "type": "compoundV3.supply",
+  "asset": "0x...",
+  "amount": "1000000",
+  "dst": "0x..." // optional
+}
+```
+
+### MakerDAO
+
+```json
+{
+  "type": "maker.openVault",
+  "ilk": "ETH-A"
+}
+```
+
+```json
+{
+  "type": "maker.frob",
+  "cdpId": "123",
+  "dink": "1000000000000000000", // optional
+  "dart": "1000" // optional
+}
+```
+
+### Balancer
+
+```json
+{
+  "type": "balancer.swap",
+  "poolId": "0x...",
+  "kind": "givenIn",
+  "assetIn": "0x...",
+  "assetOut": "0x...",
+  "amount": "1000000"
+}
+```
+
+### Curve
+
+```json
+{
+  "type": "curve.exchange",
+  "pool": "0x...",
+  "i": 0,
+  "j": 1,
+  "dx": "1000000",
+  "minDy": "990000" // optional
+}
+```
+
+### Aggregators
+
+```json
+{
+  "type": "aggregators.swap1Inch",
+  "tokenIn": "0x...",
+  "tokenOut": "0x...",
+  "amountIn": "1000000",
+  "minReturn": "990000", // optional
+  "slippageBps": 50 // optional, default 50
+}
+```
+
+## Flash Loan Strategies
+
+Flash loans require special handling. Steps after a flash loan are executed in the callback:
+
+```json
+{
+  "steps": [
+    {
+      "id": "flashLoan",
+      "action": {
+        "type": "aaveV3.flashLoan",
+        "assets": ["0x..."],
+        "amounts": ["1000000"]
+      }
+    },
+    {
+      "id": "swap",
+      "action": {
+        "type": "uniswapV3.swap",
+        // This executes in the flash loan callback
+      }
+    }
+  ]
+}
+```
+
+## Best Practices
+
+1. **Always use guards** for safety checks
+2. **Use blinds** for sensitive values
+3. **Test on fork** before live execution
+4. **Start small** and increase gradually
+5. **Monitor gas usage**
+6. **Validate addresses** before execution
+7. **Use slippage protection** for swaps
+8. **Check health factors** for lending operations
+
+## Examples
+
+See `strategies/` directory for complete examples:
+- `sample.recursive.json`: Recursive leverage
+- `sample.hedge.json`: Hedging strategy
+- `sample.liquidation.json`: Liquidation helper
+- `sample.stablecoin-hedge.json`: Stablecoin arbitrage
+
+## Validation
+
+Validate your strategy before execution:
+
+```bash
+strategic validate strategy.json
+```
+
+## Execution
+
+```bash
+# Simulate
+strategic run strategy.json --simulate
+
+# Dry run
+strategic run strategy.json --dry
+
+# Explain
+strategic run strategy.json --explain
+
+# Live execution
+strategic run strategy.json
+```
+