strategic/ARCHITECTURE.md

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