# DBIS System Architecture

## Overview

The DBIS (Debt-Based Institutional Strategy) system is a comprehensive DeFi leverage management platform that implements atomic amortizing cycles to improve position health while maintaining strict invariants.

## Core Principles

### 1. Amortization Rule
Every atomic transaction MUST end with:
- **Debt ↓** (decreased)
- **Collateral ↑** (increased)
- **LTV ↓** (decreased loan-to-value ratio)
- **HF ↑** (improved health factor)

If any of these conditions fail, the transaction reverts.

### 2. Policy Controls Over Bot Intelligence
- Bots suggest actions
- **Contracts enforce invariants**
- If invariant fails → revert → no risk

### 3. Single Identity
- One vault address
- One router
- One kernel
- Multisig/MPC owner
- Zero opacity
- Maximum governance safety

### 4. Modular & Upgradeable
All components are swappable:
- Router
- Kernel
- Policy modules
- Providers
- Oracle adapters

## System Components

### Core Contracts

1. **DBISInstitutionalVault.sol**
   - Tracks collateral and debt across multiple assets
   - Integrates with Aave v3 for position data
   - Enforces position invariants

2. **FlashLoanRouter.sol**
   - Aggregates flash loans from multiple providers:
     - Aave v3
     - Balancer Vault
     - Uniswap V3
     - DAI Flash Mint
   - Liquidity-weighted provider selection

3. **RecursiveLeverageKernel.sol**
   - Implements atomic amortizing cycle pipeline:
     1. Harvest yield
     2. Swap to stable/collateral
     3. Split: repay debt + add collateral
     4. Enforce invariants
     5. Revert if LTV worsens

4. **CollateralToggleManager.sol**
   - Manages Aave v3 collateral enable/disable
   - Batch operations for efficiency

### Governance Contracts

5. **ConfigRegistry.sol**
   - Stores all system parameters:
     - Max loops
     - Max flash size per asset
     - Min/Target health factor
     - Allowed assets
     - Provider caps

6. **PolicyEngine.sol**
   - Plugin architecture for policy modules
   - Aggregates policy decisions
   - All modules must approve

7. **GovernanceGuard.sol**
   - Final gatekeeper for all actions
   - Invariant validation
   - Strategy throttling

8. **Policy Modules**
   - **PolicyHFTrend**: Monitors health factor trends
   - **PolicyFlashVolume**: Limits flash loan volume per period
   - **PolicyLiquiditySpread**: Validates liquidity spreads
   - **PolicyProviderConcentration**: Prevents over-concentration

### Oracle Layer

9. **DBISOracleAdapter.sol**
   - Standardizes pricing from multiple sources:
     - Aave oracles
     - Chainlink price feeds
     - Uniswap TWAPs
   - Aggregates with confidence scoring

## Execution Flow

### Atomic Amortizing Cycle

```
1. Kernel.executeAmortizingCycle()
   ↓
2. GovernanceGuard.enforceInvariants()
   ↓
3. Vault.snapshotPosition()
   ↓
4. FlashRouter.flashLoan()
   ↓
5. Kernel.onFlashLoan() callback:
   - Harvest yield
   - Swap to target asset
   - Repay debt
   - Add collateral
   ↓
6. Vault.verifyPositionImproved()
   ↓
7. If invariant fails → revert
   If invariant passes → emit events
```

## Security Model

### Invariant Enforcement

All position changes must satisfy:
- `debtAfter <= debtBefore`
- `collateralAfter >= collateralBefore`
- `healthFactorAfter >= healthFactorBefore`

### Access Control

- **Owner**: Full administrative control
- **Operator**: Can execute amortization cycles
- **Kernel Role**: Can record position changes
- **Policy Modules**: Evaluated by PolicyEngine

### Upgradeability

- All core contracts support UUPS upgradeability
- Policy modules are plugin-based
- Provider addresses are configurable

## Integration Points

### Aave v3
- Position data
- Collateral management
- Borrowing/repayment

### Flash Loan Providers
- Aave v3 Pool
- Balancer Vault
- Uniswap V3 Pools
- DAI Flash Mint

### DEXs
- Uniswap V3 Router (swaps)

### Oracles
- Chainlink Price Feeds
- Aave Oracle
- Uniswap TWAPs

## Multi-Chain Support

The system is designed for multi-chain deployment:
- Primary: Ethereum Mainnet
- Secondary: Arbitrum, Polygon, Base, Optimism

Each chain requires:
- Chain-specific protocol addresses
- Chain-specific oracle feeds
- Chain-specific RPC endpoints