261 lines
5.2 KiB
Markdown
261 lines
5.2 KiB
Markdown
# DBIS - Debt-Based Institutional Strategy
|
|
|
|
A comprehensive DeFi leverage management system implementing atomic amortizing cycles to improve position health while maintaining strict invariants.
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- **Node.js** >= 18.0.0
|
|
- **Foundry** (Forge)
|
|
- **Git**
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Clone repository
|
|
git clone <repository-url>
|
|
cd no_five
|
|
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Install Foundry (if not installed)
|
|
curl -L https://foundry.paradigm.xyz | bash
|
|
foundryup
|
|
|
|
# Install Foundry dependencies
|
|
forge install
|
|
```
|
|
|
|
### Environment Setup
|
|
|
|
```bash
|
|
# Copy example env file
|
|
cp .env.example .env
|
|
|
|
# Edit .env with your configuration
|
|
nano .env
|
|
```
|
|
|
|
### Compile Contracts
|
|
|
|
```bash
|
|
forge build
|
|
```
|
|
|
|
### Run Tests
|
|
|
|
```bash
|
|
# All tests
|
|
forge test
|
|
|
|
# With coverage
|
|
forge coverage
|
|
|
|
# Fork tests
|
|
forge test --fork-url $RPC_URL
|
|
```
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
/
|
|
├── contracts/ # Solidity contracts
|
|
│ ├── core/ # Core contracts (Vault, Router, Kernel)
|
|
│ ├── governance/ # Governance contracts (Policies, Config)
|
|
│ ├── oracle/ # Oracle adapter
|
|
│ └── interfaces/ # Contract interfaces
|
|
├── test/ # Foundry tests
|
|
│ ├── kernel/ # Kernel tests
|
|
│ ├── router/ # Router tests
|
|
│ ├── vault/ # Vault tests
|
|
│ ├── integration/ # Integration tests
|
|
│ └── fuzz/ # Fuzz tests
|
|
├── mev-bot/ # MEV bot (TypeScript)
|
|
│ └── src/
|
|
│ ├── strategy/ # Trading strategies
|
|
│ ├── utils/ # Utilities
|
|
│ └── providers/ # Protocol clients
|
|
├── simulation/ # Simulation framework
|
|
│ └── src/ # Simulation modules
|
|
├── scripts/ # Deployment scripts
|
|
└── docs/ # Documentation
|
|
```
|
|
|
|
## 🏗️ Architecture
|
|
|
|
### Core Components
|
|
|
|
1. **DBISInstitutionalVault**: Tracks collateral and debt
|
|
2. **FlashLoanRouter**: Aggregates flash loans from multiple providers
|
|
3. **RecursiveLeverageKernel**: Implements atomic amortizing cycles
|
|
4. **PolicyEngine**: Modular governance system
|
|
5. **GovernanceGuard**: Enforces invariants and policies
|
|
|
|
### Key Features
|
|
|
|
- ✅ **Atomic Amortization**: Guaranteed position improvement per cycle
|
|
- ✅ **Multi-Provider Flash Loans**: Aave, Balancer, Uniswap, DAI
|
|
- ✅ **Modular Policies**: Plugin-based governance
|
|
- ✅ **Invariant Enforcement**: On-chain position verification
|
|
- ✅ **MEV Protection**: Flashbots bundle support
|
|
- ✅ **Multi-Chain Ready**: Deploy to any EVM chain
|
|
|
|
## 📖 Documentation
|
|
|
|
- [Architecture](docs/ARCHITECTURE.md) - System design and components
|
|
- [Invariants](docs/INVARIANTS.md) - Invariant rules and enforcement
|
|
- [Atomic Cycle](docs/ATOMIC_CYCLE.md) - Amortization cycle mechanics
|
|
- [Policy System](docs/POLICY.md) - Governance and policy modules
|
|
- [Deployment](docs/DEPLOYMENT.md) - Deployment guide
|
|
- [Testing](docs/TESTING.md) - Testing guide
|
|
- [MEV Bot](docs/MEV_BOT.md) - MEV bot documentation
|
|
|
|
## 🧪 Testing
|
|
|
|
```bash
|
|
# Unit tests
|
|
forge test --match-path test/vault/
|
|
forge test --match-path test/kernel/
|
|
|
|
# Integration tests
|
|
forge test --match-path test/integration/
|
|
|
|
# Invariant tests
|
|
forge test --match-test invariant
|
|
|
|
# Fuzz tests
|
|
forge test --match-test testFuzz
|
|
|
|
# Fork tests
|
|
forge test --fork-url $RPC_URL
|
|
```
|
|
|
|
## 🚢 Deployment
|
|
|
|
### Testnet
|
|
|
|
```bash
|
|
tsx scripts/testnet.ts
|
|
```
|
|
|
|
### Mainnet
|
|
|
|
```bash
|
|
# Deploy contracts
|
|
tsx scripts/deploy.ts
|
|
|
|
# Configure
|
|
tsx scripts/configure.ts
|
|
```
|
|
|
|
See [Deployment Guide](docs/DEPLOYMENT.md) for detailed instructions.
|
|
|
|
## 🤖 MEV Bot
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
cd mev-bot
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
### Run
|
|
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
See [MEV Bot Documentation](docs/MEV_BOT.md) for details.
|
|
|
|
## 🧮 Simulation
|
|
|
|
Run stress tests and risk analysis:
|
|
|
|
```bash
|
|
cd simulation
|
|
npm install
|
|
|
|
# Run stress tests
|
|
npm run stress
|
|
|
|
# Price shock simulation
|
|
npm run price-shock -20
|
|
|
|
# LTV bounding
|
|
npm run ltv-bounding
|
|
|
|
# Flash liquidity check
|
|
npm run flash-liquidity
|
|
```
|
|
|
|
## 🔒 Security
|
|
|
|
### Core Invariants
|
|
|
|
Every transaction must satisfy:
|
|
- Debt never increases
|
|
- Collateral never decreases
|
|
- Health factor never worsens
|
|
- LTV never worsens
|
|
|
|
### Audit Status
|
|
|
|
⚠️ **Unaudited** - This code is unaudited. Use at your own risk.
|
|
|
|
For production deployments:
|
|
1. Complete security audit
|
|
2. Start with conservative parameters
|
|
3. Monitor closely
|
|
4. Have emergency pause ready
|
|
|
|
## 📊 Monitoring
|
|
|
|
### Events
|
|
|
|
Monitor these events:
|
|
- `AmortizationExecuted`: Successful cycle
|
|
- `InvariantFail`: Invariant violation
|
|
- `PositionSnapshot`: Position change
|
|
- `CollateralAdded`: Collateral increase
|
|
- `DebtRepaid`: Debt decrease
|
|
|
|
### Metrics
|
|
|
|
Track:
|
|
- Health factor trends
|
|
- Flash loan execution rates
|
|
- Policy denial rates
|
|
- Gas costs
|
|
- Position size
|
|
|
|
## 🤝 Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Add tests
|
|
5. Submit a pull request
|
|
|
|
## 📝 License
|
|
|
|
MIT License
|
|
|
|
## ⚠️ Disclaimer
|
|
|
|
This software is provided "as is" without warranty. Use at your own risk. Always audit code before deploying to mainnet.
|
|
|
|
## 🆘 Support
|
|
|
|
For questions or issues:
|
|
- Open an issue on GitHub
|
|
- Review documentation
|
|
- Check test files for examples
|
|
|
|
---
|
|
|
|
**Built with ❤️ for the DeFi community**
|
|
|