187 lines
3.9 KiB
Markdown
187 lines
3.9 KiB
Markdown
# 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
|
|
|