no_five/docs/ARCHITECTURE.md

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