no_five/docs/ATOMIC_CYCLE.md

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:

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