# 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