237-combo/README.md

# 🚀 DeFi Starter Kit

> A comprehensive TypeScript + Foundry starter kit for building on top of core DeFi protocols including Aave v3, Uniswap v3/v4, Protocolink, Compound III, Balancer v3, and Curve crvUSD.

[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-blue.svg)](https://www.typescriptlang.org/)
[![Foundry](https://img.shields.io/badge/Foundry-Latest-orange.svg)](https://getfoundry.sh/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

---

## ✨ Features

| Feature | Description | Status |
|---------|-------------|--------|
| 🌐 **Multi-chain** | Ethereum, Base, Arbitrum, Optimism, Polygon | ✅ |
| 🔒 **Type-safe** | Full TypeScript types for all addresses and configurations | ✅ |
| 🏭 **Production-ready** | All examples include error handling, slippage protection | ✅ |
| 🧪 **Comprehensive testing** | Foundry fork tests for all major integrations | ✅ |
| 🛠️ **Modern tooling** | viem, Foundry, Protocolink SDK | ✅ |
| 🔐 **Security focus** | Security checklists, best practices documented | ✅ |
| 🔌 **Extensible** | Easy to add new chains, protocols, examples | ✅ |

---

## 🚀 Quick Start

### 📦 Installation

```bash
# Install dependencies
pnpm install

# Install Foundry (if not already installed)
curl -L https://foundry.paradigm.xyz | bash
foundryup
```

### ⚙️ Environment Setup

Before running tests, set up your environment variables:

```bash
# 1. Copy example environment file
cp .env.example .env

# 2. Edit .env and add your RPC URLs
# MAINNET_RPC_URL=https://mainnet.infura.io/v3/YOUR_KEY

# 3. Verify setup
pnpm run check:env
pnpm run verify:setup
```

> 📖 See [docs/ENV_SETUP.md](./docs/ENV_SETUP.md) for detailed setup instructions.

---

## 🧪 DeFi Strategy Testing

The project includes a comprehensive DeFi strategy testing CLI for testing strategies against local mainnet forks.

### 🎯 Quick Commands

```bash
# Run a strategy scenario
pnpm run strat run scenarios/aave/leveraged-long.yml

# Run with custom network and reports
pnpm run strat run scenarios/aave/leveraged-long.yml \
  --network mainnet \
  --report out/run.json \
  --html out/report.html

# Fuzz test a scenario
pnpm run strat fuzz scenarios/aave/leveraged-long.yml --iters 100 --seed 42

# List available failure injections
pnpm run strat failures

# Compare two runs
pnpm run strat compare out/run1.json out/run2.json

# Test script with real fork
export MAINNET_RPC_URL=https://mainnet.infura.io/v3/YOUR_KEY
pnpm run strat:test
```

### ✨ Strategy Testing Features

- ✅ **Aave v3 adapter** - Supply, borrow, repay, withdraw, flash loans
- ✅ **Uniswap v3 adapter** - Swaps with slippage protection
- ✅ **Compound v3 adapter** - Supply, borrow, repay
- ✅ **Failure injection** - Oracle shocks, time travel, liquidity shocks
- ✅ **Fuzzing** - Parameterized inputs for edge case discovery
- ✅ **Automatic token funding** - Via whale impersonation
- ✅ **Multiple reports** - HTML, JSON, and JUnit XML

> 📖 See [docs/STRATEGY_TESTING.md](./docs/STRATEGY_TESTING.md) for comprehensive documentation and [scenarios/README.md](./scenarios/README.md) for example scenarios.

---

## 🎓 Examples

### 📝 Run Examples

```bash
# Aave supply and borrow
tsx examples/ts/aave-supply-borrow.ts

# Uniswap v3 swap
tsx examples/ts/uniswap-v3-swap.ts

# Protocolink multi-protocol composition
tsx examples/ts/protocolink-compose.ts

# Compound III supply and borrow
tsx examples/ts/compound3-supply-borrow.ts
```

### 🧪 Run Tests

```bash
# Run Foundry tests
forge test

# Run tests with fork
forge test --fork-url $MAINNET_RPC_URL
```

### 🖥️ Use CLI

```bash
# Build a transaction plan
pnpm run cli build-plan -- --chain 1

# Get a quote
pnpm run cli quote -- --protocol uniswapv3 --type swap --token-in USDC --token-out WETH --amount 1000

# Execute a plan
pnpm run cli execute -- --chain 1 --plan plan.json
```

---

## 📁 Project Structure

```
.
├── config/
│   ├── chains/           # 🔗 Chain-specific configurations
│   │   ├── mainnet.ts
│   │   ├── base.ts
│   │   └── ...
│   └── addresses.ts      # 📍 Address exports
├── contracts/
│   ├── examples/         # 📜 Solidity example contracts
│   └── interfaces/       # 🔌 Contract interfaces
├── src/
│   ├── cli/              # 🖥️ CLI implementation
│   ├── strat/            # 🧪 Strategy testing framework
│   └── utils/            # 🛠️ Utility functions
├── examples/
│   ├── ts/               # 📘 TypeScript examples
│   └── subgraphs/        # 🔍 Subgraph queries
├── test/                 # 🧪 Foundry tests
└── docs/                 # 📚 Documentation
```

---

## 🔌 Supported Protocols

### 🏦 Aave v3
- ✅ Supply and borrow
- ✅ Flash loans (single and multi-asset)
- ✅ Pool discovery via PoolAddressesProvider

### 🔄 Uniswap v3/v4
- ✅ Token swaps
- ✅ TWAP oracles
- ✅ Permit2 integration
- ✅ Universal Router

### 🔗 Protocolink
- ✅ Multi-protocol composition
- ✅ Batch transactions
- ✅ Permit2 integration

### 🏛️ Compound III
- ✅ Supply collateral
- ✅ Borrow base asset

### 🔷 Additional Protocols
- ⚙️ Balancer v3
- ⚙️ Curve crvUSD

---

## 📘 Code Examples

### 🏦 Aave v3: Supply and Borrow

```typescript
import { createWalletRpcClient } from './src/utils/chain-config.js';
import { getAavePoolAddress } from './src/utils/addresses.js';

const walletClient = createWalletRpcClient(1, privateKey);
const poolAddress = getAavePoolAddress(1);

// Supply collateral
await walletClient.writeContract({
  address: poolAddress,
  abi: POOL_ABI,
  functionName: 'supply',
  args: [asset, amount, account, 0],
});

// Borrow
await walletClient.writeContract({
  address: poolAddress,
  abi: POOL_ABI,
  functionName: 'borrow',
  args: [debtAsset, borrowAmount, 2, 0, account],
});
```

### 🔄 Uniswap v3: Swap

```typescript
import { getUniswapSwapRouter02 } from './src/utils/addresses.js';

const routerAddress = getUniswapSwapRouter02(1);

await walletClient.writeContract({
  address: routerAddress,
  abi: SWAP_ROUTER_ABI,
  functionName: 'exactInputSingle',
  args: [swapParams],
});
```

### 🔗 Protocolink: Multi-Protocol Composition

```typescript
import * as api from '@protocolink/api';

// Build swap logic
const swapQuotation = await api.protocols.uniswapv3.getSwapTokenQuotation(chainId, {
  input: { token: USDC, amount: '1000' },
  tokenOut: WBTC,
  slippage: 100,
});
const swapLogic = api.protocols.uniswapv3.newSwapTokenLogic(swapQuotation);

// Build supply logic
const supplyQuotation = await api.protocols.aavev3.getSupplyQuotation(chainId, {
  input: swapQuotation.output,
});
const supplyLogic = api.protocols.aavev3.newSupplyLogic(supplyQuotation);

// Execute
const routerData = await api.router.getRouterData(chainId, {
  account,
  logics: [swapLogic, supplyLogic],
});
```

---

## 📚 Documentation

| Document | Description |
|----------|-------------|
| 📖 [Integration Guide](./docs/INTEGRATION_GUIDE.md) | Step-by-step integration guide |
| 🔐 [Security Best Practices](./docs/SECURITY.md) | Security checklist and best practices |
| 🔗 [Chain Configuration](./docs/CHAIN_CONFIG.md) | How to add new chains |
| 🧪 [Strategy Testing](./docs/STRATEGY_TESTING.md) | Comprehensive strategy testing guide |
| ⚙️ [Environment Setup](./docs/ENV_SETUP.md) | Environment variable configuration |

---

## 🌐 Supported Chains

| Chain | Chain ID | Status |
|-------|----------|--------|
| Ethereum Mainnet | 1 | ✅ |
| Base | 8453 | ✅ |
| Arbitrum One | 42161 | ✅ |
| Optimism | 10 | ✅ |
| Polygon | 137 | ✅ |

---

## 🔐 Security

> ⚠️ **IMPORTANT**: This is a starter kit for learning and development. Before deploying to production:

1. ✅ Review all security best practices in [docs/SECURITY.md](./docs/SECURITY.md)
2. ✅ Get professional security audits
3. ✅ Test thoroughly on testnets
4. ✅ Start with small amounts on mainnet
5. ✅ Understand the risks of each protocol

---

## 🤝 Contributing

Contributions are welcome! Please:

1. 🍴 Fork the repository
2. 🌿 Create a feature branch
3. ✏️ Make your changes
4. 🧪 Add tests
5. 📤 Submit a pull request

---

## 📄 License

MIT

---

## 🔗 Resources

| Resource | Link |
|----------|------|
| Aave Documentation | [docs.aave.com](https://docs.aave.com/) |
| Uniswap Documentation | [docs.uniswap.org](https://docs.uniswap.org/) |
| Protocolink Documentation | [docs.protocolink.com](https://docs.protocolink.com/) |
| Compound III Documentation | [docs.compound.finance](https://docs.compound.finance/) |
| Viem Documentation | [viem.sh](https://viem.sh/) |
| Foundry Documentation | [book.getfoundry.sh](https://book.getfoundry.sh/) |

---

## ⚠️ Disclaimer

This software is provided "as is" without warranty of any kind. Use at your own risk. The authors are not responsible for any losses incurred from using this software.