Initial commit

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