182 lines
4.1 KiB
Markdown
182 lines
4.1 KiB
Markdown
# 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
|
|
|