Initial commit

2025-11-20 15:35:25 -08:00
commit bfbe3ee8b7
59 changed files with 7187 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,260 @@
+# 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**
+