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

pnpm install
pnpm build

Setup

Copy environment template:

cp .env.example .env

Fill in your RPC endpoints and private key:

RPC_MAINNET=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
PRIVATE_KEY=your_private_key_here

Deploy the executor (Foundry):

forge script script/Deploy.s.sol --rpc-url $RPC_MAINNET --broadcast

Update EXECUTOR_ADDR in .env

Usage

Run a strategy

# 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

pnpm start validate strategies/sample.recursive.json

Strategy DSL

Strategies are defined in JSON with the following structure:

{
  "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

# Run tests
pnpm test

# Lint
pnpm lint

# Format
pnpm format

License

MIT

4.5 KiB Raw Blame History