# 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