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

# 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

# Copy example env file
cp .env.example .env

# Edit .env with your configuration
nano .env

Compile Contracts

forge build

Run Tests

# 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 - System design and components
• Invariants - Invariant rules and enforcement
• Atomic Cycle - Amortization cycle mechanics
• Policy System - Governance and policy modules
• Deployment - Deployment guide
• Testing - Testing guide
• MEV Bot - MEV bot documentation

🧪 Testing

# 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

tsx scripts/testnet.ts

Mainnet

# Deploy contracts
tsx scripts/deploy.ts

# Configure
tsx scripts/configure.ts

See Deployment Guide for detailed instructions.

🤖 MEV Bot

Setup

cd mev-bot
npm install
npm run build

Run

npm start

See MEV Bot Documentation for details.

🧮 Simulation

Run stress tests and risk analysis:

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