114 lines
3.5 KiB
Markdown
114 lines
3.5 KiB
Markdown
|
# Architecture Documentation
|
||
|
|
|
||
|
|
## System Overview
|
||
|
|
|
||
|
|
Strategic is a TypeScript CLI + Solidity atomic executor for DeFi strategies. It enables users to define complex multi-step DeFi operations in JSON and execute them atomically on-chain.
|
||
|
|
|
||
|
|
## Execution Flow
|
||
|
|
|
||
|
|
```
|
||
|
|
Strategy JSON
|
||
|
|
↓
|
||
|
|
Strategy Loader (validate, substitute blinds)
|
||
|
|
↓
|
||
|
|
Planner/Compiler (compile steps → calls)
|
||
|
|
↓
|
||
|
|
Guard Evaluation (pre-execution checks)
|
||
|
|
↓
|
||
|
|
Execution Engine
|
||
|
|
├─ Simulation Mode (fork testing)
|
||
|
|
├─ Dry Run (validation only)
|
||
|
|
├─ Explain Mode (show plan)
|
||
|
|
└─ Live Execution
|
||
|
|
├─ Direct (via executor contract)
|
||
|
|
└─ Flashbots (MEV protection)
|
||
|
|
```
|
||
|
|
|
||
|
|
## Flash Loan Flow
|
||
|
|
|
||
|
|
```
|
||
|
|
1. Strategy defines aaveV3.flashLoan step
|
||
|
|
2. Compiler detects flash loan requirement
|
||
|
|
3. Steps after flash loan are compiled as callback operations
|
||
|
|
4. Executor.executeFlashLoan() is called
|
||
|
|
5. Aave Pool calls executeOperation() callback
|
||
|
|
6. Callback operations execute atomically
|
||
|
|
7. Flash loan is repaid automatically
|
||
|
|
```
|
||
|
|
|
||
|
|
## Guard Evaluation Order
|
||
|
|
|
||
|
|
1. **Global Guards** (strategy-level)
|
||
|
|
- Evaluated before compilation
|
||
|
|
- If any guard with `onFailure: "revert"` fails, execution stops
|
||
|
|
|
||
|
|
2. **Step Guards** (per-step)
|
||
|
|
- Evaluated before each step execution
|
||
|
|
- Can be `revert`, `warn`, or `skip`
|
||
|
|
|
||
|
|
3. **Post-Execution Guards**
|
||
|
|
- Evaluated after execution completes
|
||
|
|
- Used for validation (e.g., health factor check)
|
||
|
|
|
||
|
|
## Component Architecture
|
||
|
|
|
||
|
|
### Core Components
|
||
|
|
|
||
|
|
- **CLI** (`src/cli.ts`): User interface, command parsing
|
||
|
|
- **Strategy Loader** (`src/strategy.ts`): JSON parsing, validation, blind substitution
|
||
|
|
- **Planner/Compiler** (`src/planner/compiler.ts`): Step → call compilation
|
||
|
|
- **Guard Engine** (`src/planner/guards.ts`): Safety check evaluation
|
||
|
|
- **Execution Engine** (`src/engine.ts`): Orchestrates execution
|
||
|
|
- **AtomicExecutor.sol**: On-chain executor contract
|
||
|
|
|
||
|
|
### Adapters
|
||
|
|
|
||
|
|
Protocol-specific adapters abstract contract interactions:
|
||
|
|
- Each adapter provides typed methods
|
||
|
|
- Handles ABI encoding/decoding
|
||
|
|
- Manages protocol-specific logic
|
||
|
|
|
||
|
|
### Guards
|
||
|
|
|
||
|
|
Safety checks that can block execution:
|
||
|
|
- `oracleSanity`: Price validation
|
||
|
|
- `twapSanity`: TWAP price checks
|
||
|
|
- `maxGas`: Gas limits
|
||
|
|
- `minHealthFactor`: Aave health factor
|
||
|
|
- `slippage`: Slippage protection
|
||
|
|
- `positionDeltaLimit`: Position size limits
|
||
|
|
|
||
|
|
## Data Flow
|
||
|
|
|
||
|
|
1. **Strategy Definition**: JSON file with steps, guards, blinds
|
||
|
|
2. **Blind Substitution**: Runtime values replace `{{blind}}` placeholders
|
||
|
|
3. **Compilation**: Steps → contract calls (calldata)
|
||
|
|
4. **Guard Evaluation**: Safety checks before execution
|
||
|
|
5. **Execution**: Calls sent to executor contract
|
||
|
|
6. **Telemetry**: Results logged (opt-in)
|
||
|
|
|
||
|
|
## Security Model
|
||
|
|
|
||
|
|
- **Allow-List**: Executor only calls allow-listed contracts
|
||
|
|
- **Pausability**: Owner can pause executor
|
||
|
|
- **Flash Loan Security**: Only authorized pools can call callback
|
||
|
|
- **Guard Enforcement**: Guards can block unsafe operations
|
||
|
|
- **Reentrancy Protection**: Executor uses ReentrancyGuard
|
||
|
|
|
||
|
|
## Cross-Chain Architecture
|
||
|
|
|
||
|
|
For cross-chain strategies:
|
||
|
|
1. Source chain executes initial steps
|
||
|
|
2. Bridge message sent (CCIP/LayerZero/Wormhole)
|
||
|
|
3. Target chain receives message
|
||
|
|
4. Compensating leg executes if main leg fails
|
||
|
|
5. State guards monitor message delivery
|
||
|
|
|
||
|
|
## Testing Strategy
|
||
|
|
|
||
|
|
- **Unit Tests**: Individual components (adapters, guards, compiler)
|
||
|
|
- **Integration Tests**: End-to-end strategy execution
|
||
|
|
- **Foundry Tests**: Solidity contract testing
|
||
|
|
- **Fork Simulation**: Test on mainnet fork before live execution
|
||
|
|
|