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.

✨ 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

# 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:

# 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 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

# 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 for comprehensive documentation and scenarios/README.md for example scenarios.

🎓 Examples

📝 Run Examples

# 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

# Run Foundry tests
forge test

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

🖥️ Use CLI

# 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

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

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

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	Step-by-step integration guide
🔐 Security Best Practices	Security checklist and best practices
🔗 Chain Configuration	How to add new chains
🧪 Strategy Testing	Comprehensive strategy testing guide
⚙️ Environment Setup	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:

✅ Review all security best practices in docs/SECURITY.md
✅ Get professional security audits
✅ Test thoroughly on testnets
✅ Start with small amounts on mainnet
✅ Understand the risks of each protocol

🤝 Contributing

Contributions are welcome! Please:

🍴 Fork the repository
🌿 Create a feature branch
✏️ Make your changes
🧪 Add tests
📤 Submit a pull request

📄 License

MIT

🔗 Resources

Resource	Link
Aave Documentation	docs.aave.com
Uniswap Documentation	docs.uniswap.org
Protocolink Documentation	docs.protocolink.com
Compound III Documentation	docs.compound.finance
Viem Documentation	viem.sh
Foundry Documentation	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.