Risk Engine V1

TL;DR: The Risk Engine ensures all positions are adequately collateralized by calculating margin requirements using worst-case APR assumptions. It answers: "If Variable Yield moves maximally against this position, how much could they lose?"

Overview

The Risk Engine is the protocol's safety mechanism. It calculates how much margin each position needs by considering the worst possible outcome.

The Worst Case APR Mechanism

Why Worst Case?

Consider this position:

User locked 6% Fixed Yield on 100,000 USDC for 90 days

Question: How much margin do they need? Answer: Depends on what VY could do...

• If VY = 4% → User profits → No margin needed

• If VY = 6% → Break even → No margin needed

• If VY = 12% → User loses 6% → Needs margin to cover ~$1,480 loss

• If VY = 20% → User loses 14% → Needs margin to cover ~$3,450 loss

The protocol can't know what VY will actually be. So it assumes the worst case and requires margin to cover that.

Two Worst Case Factors

The protocol maintains two worst-case VY assumptions per pool:

// Storage in CollateralEngine
mapping(bytes32 => uint256) worstCaseVariableFactorPositiveWad; // For receiving VY
mapping(bytes32 => uint256) worstCaseVariableFactorNegativeWad; // For paying VY

Factor	When Used	Scenario
worstCaseVariableFactorPositive	variableTokenBalance > 0 (receiving VY)	VY drops to minimum
worstCaseVariableFactorNegative	variableTokenBalance < 0 (paying VY)	VY rises to maximum

Example: FY Position (Locking Fixed Yield)

The user is long fixed yield and short variable yield:

• fixedTokenBalance = +100,000 (receiving FY)

• variableTokenBalance = −100,000 (paying VY)

Because variableYieldBalance < 0 , the risk engine applies worstCaseVariableFactorNegative (the “VY goes high” worst case for payers).

Assumptions: • Fixed yield locked at 6% APR • Term = 90 days • worstCaseVariableFactorNegative = 12% APR (admin-set)

Worst-case cashflow over the term is computed as:

cashflow = fixedToken × (term/365 × fixedAPR) + variableToken × (term/365 × worstCaseVY)
= 100,000 × (90/365 × 0.06) + (−100,000) × (90/365 × 0.12)
= 100,000 × 0.0148 − 100,000 × 0.0296
= 1,480 − 2,960
= −1,480 USD

Margin required is the absolute value of the worst-case loss:

MarginRequired = |−1,480| = 1,480 USD.

Example: VY Position (Trading Variable Yield)

The user is short fixed yield and long variable yield:

• fixedTokenBalance = −100,000 (paying FY)

• variableTokenBalance = +100,000 (receiving VY)

Because variableTokenBalance > 0 , the risk engine applies worstCaseVariableFactorPositive (the “VY goes low” worst case for receivers).

Assumptions:

• Fixed yield given up is 6% APR

• Term = 90 days

• worstCaseVariableFactorPositive = 2% APR (admin-set)

Worst-case cashflow over the term:

cashflow = fixedToken × (term/365 × fixedAPR) + variableToken × (term/365 × worstCaseVY)
= (−100,000) × (90/365 × 0.06) + 100,000 × (90/365 × 0.02)
= −1,480 + 493
= −987 USD

Margin required:

MarginRequired = |−987| = 987 USD.

The Calculation Flow

Step 1: Get Position Data

Position.Info memory position = positions.get(account, poolId, tickLower, tickUpper);
// Returns: fixedTokenBalance, variableTokenBalance, liquidity, etc.

Step 2: Determine Which Worst Case Factor

uint256 worstCaseVariableFactorWad = variableTokenBalance > 0
    ? worstCaseVariableFactorPositiveWad[poolId]   // Receiving VY → VY might drop
    : worstCaseVariableFactorNegativeWad[poolId];  // Paying VY → VY might rise

Step 3: Calculate Worst Case Cashflow

int256 cashflow = FixedAndVariableMath.calculateSettlementCashflow(
    fixedTokenBalance,
    variableTokenBalance,
    termStartTimestampWad,
    termEndTimestampWad,
    worstCaseVariableFactorWad
);

Step 4: Convert to Margin Requirement

// Only negative cashflows matter (losses)
if (cashflow > 0) {
    cashflow = 0;  // Profit → no margin needed
} else {
    cashflow = -cashflow;  // Loss → need margin
}

// Convert to USD
(uint256 priceInUSDCWad,, bool valid) = oracleHub.getPriceUsdWad(underlyingAsset);
marginRequirement = cashflow × priceInUSDCWad;

LP Position Scenario Analysis

LP positions are more complex because their token balances change as price moves.

The Problem

LP provides liquidity between 5% and 8% FY (ticks tickLower to tickUpper)

Current FY = 6.5% (within range)

What if FY moves?

• If FY → 5%: LP has more variableTokens

• If FY → 8%: LP has more fixedTokens

Each scenario has different margin requirement!

The Solution: Evaluate Both Extremes

function calculatePositionObligation(...) {
    if (position.liquidity == 0) {
        // Simple trader position
        return getMarginRequirement(fixedTokenBalance, variableTokenBalance, ...);
    }
    
    // LP position: check both scenarios
    uint256 marginReq = 0;
    
    // Scenario 1: Price moves to tickLower (FY drops)
    if (currentTick > tickLower) {
        uint256 mr1 = scenarioMarginRequirement(
            position,
            currentTick → tickLower,
            liquidity
        );
        marginReq = max(marginReq, mr1);
    }
    
    // Scenario 2: Price moves to tickUpper (FY rises)
    if (currentTick < tickUpper) {
        uint256 mr2 = scenarioMarginRequirement(
            position,
            currentTick → tickUpper,
            liquidity
        );
        marginReq = max(marginReq, mr2);
    }
    
    return marginReq;
}

Scenario Calculation

function scenarioMarginRequirement(position, tickFrom, tickTo, liquidity) {
    // Calculate how token balances change if price moves
    (extraFixed, extraVariable) = getExtraBalances(tickFrom, tickTo, liquidity, ...);
    
    // New balances under this scenario
    scenarioFixed = position.fixedTokenBalance + extraFixed;
    scenarioVariable = position.variableTokenBalance + extraVariable;
    
    // Calculate margin requirement for this scenario
    return getMarginRequirement(scenarioFixed, scenarioVariable, ...);
}

Collateral Valuation

Discount Factors

Not all collateral is valued equally:

mapping(address => uint256) marginTokenDiscountFactorWad;

// Examples:
USDC:  1.0e18  (100% value)
USDT:  0.98e18 (98% value)
ETH:   0.90e18 (90% value)
WBTC:  0.85e18 (85% value)

Total Collateral Value

function calculateMarginValue(account) {
    totalValue = 0;
    
    for each asset in account.marginAssets:
        if (!whitelisted[asset]) continue;
        
        balance = account.balances[asset];
        price = oracleHub.getPriceUsdWad(asset);
        discount = marginTokenDiscountFactorWad[asset];
        
        // Special case: isolated margin token gets 100% value
        if (asset == account.isolatedMarginToken) {
            discount = 1.0;
        }
        
        totalValue += balance × price × discount;
    
    return totalValue;
}

Health Check

The Final Comparison

function checkMarginRequirement(account) {
    marginRequired = calculateAccountObligation(account);
    marginValue = calculateMarginValue(account);
    
    if (marginRequired > marginValue) {
        revert MarginRequirementNotMet(marginRequired, marginValue);
    }
}

Liquidation Threshold

Health Factor = marginValue / marginRequired

HF > 1.0:  Safe
HF = 1.0:  At threshold
HF < 1.0:  Liquidatable

Admin Configuration

Setting Worst Case Factors

// Admin sets worst case VY for each pool
function setWorstCaseVariableFactor(
    bytes32 poolId,
    uint256 worstCaseVariableFactorPositiveWad,  // e.g., 0.02e18 (2% VY)
    uint256 worstCaseVariableFactorNegativeWad   // e.g., 0.15e18 (15% VY)
) external onlyOwner;

Choosing Values

Factor	Meaning	Typical Range
Positive (VY low)	Min VY if you're receiving it	0-3%
Negative (VY high)	Max VY if you're paying it	10-20%

These should be set based on:

• Historical VY volatility for the underlying protocol

• Term length (longer = more uncertainty)

• Risk tolerance of the protocol

Key Takeaways

1. Worst case, not expected — Always assume VY moves maximally against user

2. Two scenarios per direction — Low VY for receivers, high VY for payers

3. LP scenario analysis — Check both tick boundaries for LPs

4. Discount factors — Volatile collateral gets haircut

5. Admin controlled — Worst case factors are protocol parameters

Next Steps

• Collateral Engine V1 — How positions are stored

• Liquidations — What happens when margin is insufficient

• Margin System — Detailed margin mechanics