Files

defiQUG 47f6f2de7b Initial commit: add .gitignore and README

2026-02-09 21:51:30 -08:00

8.9 KiB

Raw Permalink Blame History

🚀 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.

✨ 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.

8.9 KiB Raw Permalink Blame History