168 lines
4.5 KiB
Markdown
168 lines
4.5 KiB
Markdown
# Strategic - TypeScript CLI + Solidity Atomic Executor
|
|
|
|
**Status**: ✅ **Active**
|
|
**Purpose**: A full-stack TypeScript CLI scaffold with Solidity atomic executor for executing complex DeFi strategies atomically. Enables users to define multi-step DeFi operations in JSON and execute them atomically on-chain with comprehensive safety guards.
|
|
|
|
## 🎯 Overview
|
|
|
|
Strategic is a DeFi strategy execution framework that allows developers and traders to:
|
|
- **Define complex strategies** in a simple JSON DSL
|
|
- **Execute atomically** across multiple DeFi protocols in a single transaction
|
|
- **Ensure safety** with built-in guards (oracle checks, slippage protection, health factor monitoring)
|
|
- **Simulate before execution** using fork testing and dry-run modes
|
|
- **Protect against MEV** with Flashbots integration
|
|
|
|
**Use Cases**:
|
|
- Leveraged yield farming strategies
|
|
- Arbitrage opportunities across protocols
|
|
- Debt refinancing and position optimization
|
|
- Multi-protocol flash loan strategies
|
|
- Risk-managed DeFi operations
|
|
|
|
## Features
|
|
|
|
- **Strategy JSON DSL** with blinds (sealed runtime params), guards, and steps
|
|
- **Protocol Adapters**: Aave v3, Compound v3, Uniswap v3, MakerDAO, Balancer, Curve, 1inch/0x, Lido, GMX
|
|
- **Atomic Execution**: Single-chain atomic calls via multicall or flash loan callback
|
|
- **Safety Guards**: Oracle sanity, TWAP sanity, max gas, min health factor, slippage, position limits
|
|
- **Flashbots Integration**: MEV-synchronized multi-wallet coordination
|
|
- **Fork Simulation**: Anvil/Tenderly fork simulation with state snapshots
|
|
- **Cross-Chain Support**: Orchestrator for CCIP/LayerZero/Wormhole (placeholder)
|
|
- **Multi-Chain**: Mainnet, Arbitrum, Optimism, Base
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pnpm install
|
|
pnpm build
|
|
```
|
|
|
|
## Setup
|
|
|
|
1. Copy environment template:
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
2. Fill in your RPC endpoints and private key:
|
|
```env
|
|
RPC_MAINNET=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
|
|
PRIVATE_KEY=your_private_key_here
|
|
```
|
|
|
|
3. Deploy the executor (Foundry):
|
|
```bash
|
|
forge script script/Deploy.s.sol --rpc-url $RPC_MAINNET --broadcast
|
|
```
|
|
|
|
4. Update `EXECUTOR_ADDR` in `.env`
|
|
|
|
## Usage
|
|
|
|
### Run a strategy
|
|
|
|
```bash
|
|
# Simulate execution
|
|
pnpm start run strategies/sample.recursive.json --simulate
|
|
|
|
# Dry run (validate only)
|
|
pnpm start run strategies/sample.recursive.json --dry
|
|
|
|
# Explain strategy
|
|
pnpm start run strategies/sample.recursive.json --explain
|
|
|
|
# Fork simulation
|
|
pnpm start run strategies/sample.recursive.json --simulate --fork $RPC_MAINNET --block 18000000
|
|
```
|
|
|
|
### Validate a strategy
|
|
|
|
```bash
|
|
pnpm start validate strategies/sample.recursive.json
|
|
```
|
|
|
|
## Strategy DSL
|
|
|
|
Strategies are defined in JSON with the following structure:
|
|
|
|
```json
|
|
{
|
|
"name": "Strategy Name",
|
|
"chain": "mainnet",
|
|
"executor": "0x...",
|
|
"blinds": [
|
|
{
|
|
"name": "amount",
|
|
"type": "uint256",
|
|
"description": "Amount to use"
|
|
}
|
|
],
|
|
"guards": [
|
|
{
|
|
"type": "minHealthFactor",
|
|
"params": { "minHF": 1.2, "user": "0x..." },
|
|
"onFailure": "revert"
|
|
}
|
|
],
|
|
"steps": [
|
|
{
|
|
"id": "step1",
|
|
"action": {
|
|
"type": "aaveV3.supply",
|
|
"asset": "0x...",
|
|
"amount": "{{amount}}"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Architecture
|
|
|
|
- **CLI** (`src/cli.ts`): Commander-based CLI with prompts
|
|
- **Strategy Loader** (`src/strategy.ts`): Loads and validates strategy JSON
|
|
- **Planner/Compiler** (`src/planner/compiler.ts`): Bundles steps into atomic calls
|
|
- **Guards** (`src/guards/`): Safety checks (oracle, slippage, HF, etc.)
|
|
- **Adapters** (`src/adapters/`): Protocol integrations
|
|
- **Executor** (`contracts/AtomicExecutor.sol`): Solidity contract for atomic execution
|
|
- **Engine** (`src/engine.ts`): Execution engine with simulation support
|
|
|
|
## Protocol Adapters
|
|
|
|
- **Aave v3**: supply, withdraw, borrow, repay, flash loan, EMode, collateral
|
|
- **Compound v3**: supply, withdraw, borrow, repay, allow, liquidity
|
|
- **Uniswap v3**: exact input/output swaps, multi-hop, TWAP
|
|
- **MakerDAO**: vault ops (open, frob, join, exit)
|
|
- **Balancer V2**: swaps, batch swaps
|
|
- **Curve**: exchange, exchange_underlying, pool registry
|
|
- **1inch/0x**: RFQ integration
|
|
- **Lido**: stETH/wstETH wrap/unwrap
|
|
- **GMX**: perps position management
|
|
|
|
## Guards
|
|
|
|
- `oracleSanity`: Chainlink oracle price checks
|
|
- `twapSanity`: Uniswap TWAP validation
|
|
- `maxGas`: Gas limit/price ceilings
|
|
- `minHealthFactor`: Aave health factor minimum
|
|
- `slippage`: Slippage protection
|
|
- `positionDeltaLimit`: Position size limits
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Run tests
|
|
pnpm test
|
|
|
|
# Lint
|
|
pnpm lint
|
|
|
|
# Format
|
|
pnpm format
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|
|
|