Initial commit

2025-11-20 15:35:25 -08:00
commit bfbe3ee8b7
59 changed files with 7187 additions and 0 deletions
--- a/docs/ATOMIC_CYCLE.md
+++ b/docs/ATOMIC_CYCLE.md
@@ -0,0 +1,186 @@
+# Atomic Amortizing Cycle
+
+## Overview
+
+The atomic amortizing cycle is the core mechanism of the DBIS system. It guarantees that every execution improves the position (debt↓, collateral↑, LTV↓, HF↑) in a single atomic transaction.
+
+## Cycle Phases
+
+### Phase 1: Pre-Execution Validation
+```
+GovernanceGuard.enforceInvariants()
+  ↓
+PolicyEngine.evaluateAll()
+  ↓
+ConfigRegistry.getMaxLoops()
+  ↓
+Vault.snapshotPosition()
+```
+
+**Checks:**
+- Policy modules approve action
+- Max loops not exceeded
+- Position snapshot taken
+
+### Phase 2: Flash Loan Execution
+```
+FlashLoanRouter.flashLoan()
+  ↓
+Provider-specific flash loan (Aave/Balancer/Uniswap/DAI)
+  ↓
+Kernel.onFlashLoan() callback
+```
+
+**Actions:**
+- Borrow flash loan amount
+- Execute callback with borrowed funds
+
+### Phase 3: Amortization Operations
+```
+onFlashLoan() callback:
+  1. Harvest yield (if available)
+  2. Swap to target asset
+  3. Split funds:
+     - 50% repay debt
+     - 50% add collateral
+  4. Repay flash loan (principal + fee)
+```
+
+**Math:**
+```
+yieldAmount = harvestYield()
+totalAmount = flashAmount + yieldAmount
+swapAmount = swapToTargetAsset(totalAmount)
+debtRepayment = swapAmount / 2
+collateralAddition = swapAmount - debtRepayment
+```
+
+### Phase 4: Invariant Verification
+```
+Vault.verifyPositionImproved(
+  collateralBefore,
+  debtBefore,
+  healthFactorBefore
+)
+```
+
+**Checks:**
+- `debtAfter < debtBefore` ✓
+- `collateralAfter > collateralBefore` ✓
+- `healthFactorAfter > healthFactorBefore` ✓
+
+### Phase 5: Completion
+```
+If invariants pass:
+  - Emit AmortizationExecuted event
+  - Return success
+If invariants fail:
+  - Emit InvariantFail event
+  - Revert transaction
+```
+
+## Recursive Cycles
+
+The kernel can execute multiple cycles in sequence:
+
+```solidity
+for (uint256 i = 0; i < maxLoops; i++) {
+    executeSingleStep();
+    
+    // Early exit if target achieved
+    if (currentHF >= targetHF) {
+        break;
+    }
+    
+    // Early exit if no improvement
+    if (noImprovement) {
+        break;
+    }
+}
+```
+
+Each cycle must improve the position independently.
+
+## Example Flow
+
+### Input
+- Current Position:
+  - Collateral: $1,000,000
+  - Debt: $800,000
+  - HF: 1.05
+  - LTV: 80%
+
+### Cycle Execution
+1. Flash loan: $100,000 USDC
+2. Swap: $100,000 → $100,000 USDC (no swap needed)
+3. Repay debt: $50,000
+4. Add collateral: $50,000
+
+### Output
+- New Position:
+  - Collateral: $1,050,000 (+$50,000)
+  - Debt: $750,000 (-$50,000)
+  - HF: 1.12 (+0.07)
+  - LTV: 71.4% (-8.6%)
+
+### Invariant Check
+- ✓ Debt decreased
+- ✓ Collateral increased
+- ✓ HF improved
+- ✓ LTV decreased
+
+**Result: SUCCESS**
+
+## Gas Optimization
+
+### Batch Operations
+- Multiple cycles in one transaction
+- Batch collateral toggles
+- Batch policy evaluations
+
+### Flash Loan Optimization
+- Use cheapest provider (DAI flash mint = 0% fee)
+- Split across providers for large amounts
+- Optimal provider selection
+
+### Early Exits
+- Exit if target HF achieved
+- Exit if no improvement possible
+- Exit if max loops reached
+
+## Error Handling
+
+### Revert Conditions
+1. Policy check fails
+2. Flash loan unavailable
+3. Swap fails (slippage too high)
+4. Debt repayment fails
+5. Invariant check fails
+
+### Recovery
+All state changes are atomic. On revert:
+- Flash loan not borrowed (or automatically repaid)
+- Position unchanged
+- Can retry with different parameters
+
+## Monitoring
+
+### Events Emitted
+- `AmortizationExecuted(cyclesExecuted, collateralIncrease, debtDecrease, hfImprovement)`
+- `InvariantFail(reason)`
+- `SingleStepCompleted(collateralAdded, debtRepaid)`
+
+### Metrics Tracked
+- Cycles executed per transaction
+- Average HF improvement per cycle
+- Gas cost per cycle
+- Success rate
+
+## Safety Guarantees
+
+1. **Atomicity**: All-or-nothing execution
+2. **Invariant Preservation**: Position always improves
+3. **Reversibility**: Can revert at any point
+4. **Policy Compliance**: All policies must approve
+5. **Access Control**: Only authorized operators
+