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