Margin Management

TL;DR: The margin system ensures all positions are adequately collateralized. It uses discount factors for collateral, worst-case VY for requirements, and health factors to monitor risk.

Overview

┌─────────────────────────────────────────────────────────────┐
│                     MARGIN SYSTEM                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Collateral Value         vs        Margin Requirement      │
│  ─────────────────                 ──────────────────       │
│                                                             │
│  Σ(Balance × Price × DF)    ≥    Σ(Position Obligation)    │
│                                                             │
│  If Collateral < Requirement → Liquidation Risk             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Collateral Valuation

Formula

Total Collateral Value = Σ (Balance × Price × Discount Factor)

Discount Factors

Different assets have different risk profiles:

Asset	Discount Factor	Rationale
USDC	1.00 (100%)	Stable, liquid
USDT	0.98 (98%)	Minor depeg risk
DAI	0.97 (97%)	Algorithmic stable
ETH	0.90 (90%)	Volatile but liquid
WBTC	0.85 (85%)	Volatile, wrapped asset

Example Calculation

Account Balances:
- USDC: 5,000
- ETH: 2.0 (@ $2,000/ETH)

Collateral Value:
= (5,000 × $1 × 1.00) + (2.0 × $2,000 × 0.90)
= $5,000 + $3,600
= $8,600 USD effective collateral

Isolated Margin Mode

In isolated margin mode, only the specified token is used:

AccountId {
    owner: 0xABC...,
    id: 1,
    isolatedMarginToken: USDC_ADDRESS  // Only USDC counts
}

The isolated token gets 100% discount factor (no haircut).

Margin Requirements

Position Obligation

Each position has a margin requirement based on potential loss:

Position Obligation = Worst Case Loss × Price

Where:
Worst Case Loss = Settlement Cashflow under worst VY scenario

Worst Case Variable Factor

The protocol uses conservative VY assumptions:

For FY Positions (positive variableTokenBalance):
- Worst case: VY goes very low
- Use: worstCaseVariableFactorNegative

For VY Positions (negative variableTokenBalance):
- Worst case: VY goes very high  
- Use: worstCaseVariableFactorPositive

Example Calculation

Position:
- Notional: 100,000 USDC
- FY locked: 6%
- Term: 90 days
- Worst case VY: 12% (configured)

Worst Case Loss:
= (6% - 12%) × 100,000 × (90/365)
= -6% × 100,000 × 0.247
= -$1,479

Margin Requirement:
= $1,479 × 1.0 (USDC price)
= $1,479

Health Factor

Definition

Health Factor = Collateral Value / Margin Requirement

Interpretation

Health Factor	Status	Action
> 1.5	Safe	No action needed
1.2 - 1.5	Caution	Consider adding margin
1.0 - 1.2	Warning	Add margin urgently
< 1.0	Danger	Liquidation possible

Visual

Health Factor Scale:

   SAFE          CAUTION      WARNING      DANGER
   ────────────────────────────────────────────────
   │            │            │           │
   ▼            ▼            ▼           ▼
   2.0          1.5          1.2         1.0         0
   
   ████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
               ↑
         Your position

LP Position Margin

Liquidity providers have additional margin considerations:

Scenario Analysis

LP positions must cover the worst-case tick movement:

LP Position:
- Tick range: [tickLower, tickUpper]
- Current tick: currentTick
- Liquidity: L

Scenario 1: Price moves to tickLower
- Calculate token deltas
- Compute margin requirement

Scenario 2: Price moves to tickUpper
- Calculate token deltas
- Compute margin requirement

Final Requirement = MAX(Scenario1, Scenario2)

Extra Balances Calculation

function _getExtraBalances(
    int24 fromTick,
    int24 toTick,
    uint128 liquidity,
    ...
) internal view returns (int256, int256) {
    // Calculate what happens if price moves from fromTick to toTick
    // with given liquidity
}

Margin Operations

Deposit

// Deposit margin
collateralEngine.updateAccountMargin(
    account,
    USDC_ADDRESS,
    5000e6  // Positive = deposit
);

Flow:

1. Transfer tokens from user to CollateralEngine

2. Update account balance

3. No margin check needed (deposits only help)

Withdraw

// Withdraw margin
collateralEngine.updateAccountMargin(
    account,
    USDC_ADDRESS,
    -1000e6  // Negative = withdraw
);

Flow:

1. Update position growth (mark to market)

2. Check margin requirement

3. If insufficient → revert

4. Transfer tokens to user

After Trade

// After every trade, margin is checked
function swap(...) {
    // ... execute swap ...
    
    // Update position in CollateralEngine
    collateralEngine.updatePositionPostVAMMAction(...);
    
    // Check margin
    positionMarginRequirement = collateralEngine.checkMarginRequirement(account);
    // Reverts if insufficient
}

Multi-Position Aggregation

Cross-Margin

With cross-margin, all positions share collateral:

Account (Cross-Margin):
├── Position 1: USDC/aUSDC 90-day → Requires $1,200
├── Position 2: ETH/stETH 180-day → Requires $2,500
└── Position 3: USDC/aUSDC 30-day → Requires $800

Total Requirement: $4,500

Collateral:
├── USDC: 3,000 × 1.0 = $3,000
└── ETH: 2.0 × $2,000 × 0.9 = $3,600

Total Collateral: $6,600
Health Factor: 6,600 / 4,500 = 1.47 ✓

Isolated Margin

With isolated margin, each sub-account is separate:

Sub-Account 0 (USDC Isolated):
├── Position 1: Requires $1,200
├── Collateral: 2,000 USDC
└── Health: 2,000 / 1,200 = 1.67 ✓

Sub-Account 1 (USDC Isolated):
├── Position 2: Requires $800
├── Collateral: 1,000 USDC
└── Health: 1,000 / 800 = 1.25 ⚠️

Margin Efficiency

Effective Leverage

Leverage = Notional / Margin

Example:
Notional: 100,000 USDC
Margin: 5,000 USDC
Leverage: 20x

This means $1 of margin controls $20 of notional exposure

Typical Margin Ratios

Use Case	Margin Ratio	Leverage
Conservative	10%	10x
Standard	5%	20x
Aggressive	2.5%	40x

Note: Higher leverage = higher liquidation risk

Best Practices

1. Maintain Buffer

Recommended: Keep Health Factor > 1.5

If Health = 1.2:
- You're close to liquidation zone
- One adverse move could trigger liquidation

2. Monitor Regularly

Check your position:
- Health Factor
- Current VY vs your FY
- Time to maturity

3. Use Isolated Margin for Risky Trades

Risky speculation → Use isolated sub-account
Core positions → Keep in main account

This way, a risky trade gone wrong doesn't affect your other positions

4. Understand Worst Case

Before opening:
1. What's my locked FY?
2. What's the worst case VY?
3. What's my max loss?
4. Is my margin sufficient with buffer?

Key Takeaways

1. Discount factors reduce volatile collateral value

2. Worst case VY determines margin requirement

3. Health Factor = Collateral / Requirement

4. Keep Health > 1.5 to avoid liquidation risk

5. Isolated margin protects other positions

Next Steps

• Liquidations — What happens when margin fails

• Risk Management — Managing your risk

• Getting Started — Start with proper margin