Understanding Vault Risks

A comprehensive guide for vault creators on identifying, measuring, and mitigating risks in Flux Protocol vaults.

Overview

As a vault creator, you're responsible for:

• Choosing safe risk parameters

• Monitoring vault health

• Managing bad debt if it occurs

• Protecting LP capital

This guide covers all major risk vectors and mitigation strategies.

---

Table of Contents

1. Risk Types

2. Parameter Selection

3. Monitoring & Alerts

4. Bad Debt Management

5. Oracle Security

6. Emergency Procedures

---

Risk Types

1. Manager Default Risk

Definition: Managers' positions become underwater, leading to bad debt.

Causes:

• Sudden price crashes (collateral value drops below debt)

• Leverage too high (small price moves trigger liquidation)

• Illiquid collateral (can't sell fast enough)

• Oracle lag (prices update too slowly)

Impact: LP shares lose value (socialized losses)

Mitigation:

// Conservative parameters
StrategyParams({
    minBondRatio: 0.3e18,         // 30% bond (lower leverage)
    liquidationBuffer: 0.2e18,     // 20% safety margin
    adlBuffer: 0.1e18,             // 10% ADL buffer
    // ...
});

2. Oracle Manipulation Risk

Definition: Price feeds are manipulated, causing incorrect liquidations or allowing underwater positions.

Causes:

• Flash loan attacks on DEX price feeds

• Compromised oracle nodes

• Low-liquidity markets (easy to manipulate)

• Oracle downtime/delays

Impact:

• False liquidations (healthy positions liquidated)

• Missed liquidations (unhealthy positions not liquidated)

Mitigation:

• Use trusted oracles (Chainlink, not DEX spot prices)

• Avoid exotic/low-liquidity assets

• Monitor oracle health

• Conservative liquidation buffers

3. Smart Contract Risk

Definition: Bugs in vault, wrapper, or strategy contracts.

Causes:

• Uncaught edge cases

• Reentrancy vulnerabilities

• Integer overflow/underflow

• Access control issues

Impact: Loss of all vault funds

Mitigation:

• Use audited contracts

• Immutable strategies (no upgrade risk)

• Start with small TVL

• Comprehensive testing

• Bug bounty program

4. Liquidity Risk

Definition: Unable to withdraw due to high utilization.

Causes:

• All capital borrowed by managers

• Managers holding positions too long

• LP withdrawal surge (bank run)

Impact: LPs can't access capital, queued withdrawals

Mitigation:

// Use ADL to free liquidity
vault.setAdlManager(adlManagerAddress);

// Or set deposit caps
GraduatedCapDepositPolicyTier[] memory tiers = new GraduatedCapDepositPolicyTier[](1);
tiers[0] = GraduatedCapDepositPolicyTier({
    minUtilizationBps: 8000,  // 80% utilization
    maxDepositBps: 500        // Max 5% per deposit
});

5. Interest Rate Risk

Definition: Rates no longer competitive (for Mutable strategies).

Causes:

• Market rates change

• Competing vaults offer better yields

• Vault utilization drops

Impact:

• LPs withdraw (if rates too low)

• Managers avoid vault (if rates too high)

Mitigation (Mutable only):

// Adjust rates to stay competitive
strategy.setAnnualRate(0.12e18);  // Update to 12% APR
// 7-day timelock gives LPs time to exit if they disagree

6. Collateral Composition Risk

Definition: Correlated collateral assets amplify losses.

Causes:

• Multiple similar assets (e.g., all stablecoins)

• All assets in same sector (e.g., all DeFi tokens)

• Contagion risk (one fails, others follow)

Impact: Systemic failure during black swan events

Mitigation:

• Allow diverse asset types in strategy

• Monitor manager position composition

• Set reasonable per-asset limits (if possible)

7. Wrapper Risk

Definition: Asset wrappers have bugs or malicious code.

Causes:

• Unaudited custom wrappers

• Complex wrapper logic (UniV3, etc.)

• Incorrect oracle integration

Impact: Incorrect valuations, loss of funds

Mitigation:

• Only use governance-whitelisted wrappers

• Prefer simple ERC20 wrappers

• Audit custom wrappers thoroughly

• Test wrappers with small amounts first

---

Parameter Selection

Choosing Safe Parameters

Conservative Vault Example:

StrategyParams({
    minBondRatio: 0.3e18,              // 30% bond (3.3x max leverage)
    liquidationBuffer: 0.2e18,          // 20% buffer
    adlBuffer: 0.15e18,                 // 15% ADL buffer
    adlUtilizationThreshold: 0.9e18,    // ADL at 90% utilization
    annualRate: 0.06e18,                // 6% APR
    curatorFeeRate: 500,                // 5% curator fee
    liquidationProfitMargin: 0.02e18    // 2% liquidator profit
});

// Liquidation threshold = 1.0 + 0.3 - 0.2 = 1.1 (110%)
// ADL threshold = 1.1 + 0.15 = 1.25 (125%)

Why conservative?

• Higher bond requirement (30%) = more manager skin in game

• Large buffer (20%) = withstand significant price drops

• Lower leverage (3.3x) = harder to become underwater

• ADL at 90% = protect LP liquidity early

Aggressive Vault Example:

StrategyParams({
    minBondRatio: 0.15e18,              // 15% bond (6.7x max leverage)
    liquidationBuffer: 0.05e18,          // 5% buffer
    adlBuffer: 0.05e18,                  // 5% ADL buffer
    adlUtilizationThreshold: 0.98e18,    // ADL at 98% utilization
    annualRate: 0.15e18,                 // 15% APR
    curatorFeeRate: 1000,                // 10% curator fee
    liquidationProfitMargin: 0.01e18     // 1% liquidator profit
});

// Liquidation threshold = 1.0 + 0.15 - 0.05 = 1.1 (110%)
// ADL threshold = 1.1 + 0.05 = 1.15 (115%)

Why aggressive?

• Lower bond (15%) = higher leverage available

• Small buffer (5%) = tight liquidation window

• Higher leverage (6.7x) = easier to go underwater

• Higher rate (15%) = compensate LPs for risk

Parameter Trade-offs

Parameter	Conservative	Aggressive	Impact
minBondRatio	High (25-30%)	Low (10-15%)	Leverage, manager appeal
liquidationBuffer	Large (15-20%)	Small (5-10%)	Safety margin, liquidation frequency
adlBuffer	Large (10-15%)	Small (5%)	LP protection, ADL frequency
adlUtilizationThreshold	Low (85-90%)	High (95-98%)	LP liquidity, capital efficiency
annualRate	Low (5-8%)	High (12-20%)	LP yield, manager cost
curatorFeeRate	Low (0-5%)	High (10-20%)	Your earnings, LP net yield

Decision Framework

Start here:
│
├─ What's your risk tolerance?
│  ├─ Low → Conservative parameters
│  ├─ Medium → Balanced parameters
│  └─ High → Aggressive parameters
│
├─ What's your target market?
│  ├─ Retail LPs → Conservative (trust is key)
│  ├─ DeFi natives → Balanced (competitive yield)
│  └─ Institutions → Conservative (compliance, predictability)
│
├─ What assets are allowed?
│  ├─ Blue chips only (WETH, WBTC) → Can be more aggressive
│  ├─ Stable assets (USDC, DAI) → Conservative (lower volatility)
│  └─ Exotic assets (long-tail) → Very conservative
│
└─ What's your management style?
   ├─ Hands-off → Immutable, conservative
   ├─ Active monitoring → Mutable, can be balanced
   └─ Very active → Mutable, can be aggressive (with ADL)

---

Monitoring & Alerts

Key Metrics to Track

1. Vault Health

// Total vault metrics
uint256 totalAssets = vault.totalAssets();
uint256 idleLiquidity = vault.getIdleLiquidity();
uint256 utilization = (totalAssets - idleLiquidity) * 100 / totalAssets;
uint256 badDebt = vault.totalBadDebt();

console.log("TVL:", totalAssets);
console.log("Utilization:", utilization, "%");
console.log("Bad Debt:", badDebt);
console.log("Bad Debt %:", badDebt * 100 / totalAssets);

Alert Thresholds:

• Utilization > 95% → ADL consideration

• Bad debt > 0 → Immediate investigation

• Bad debt > 5% of TVL → Crisis mode

• Idle liquidity < $100K → Liquidity concerns

2. Individual Manager Positions

async function monitorManagers(vaultAddress: string) {
  const managers = await getAllManagers(vaultAddress);

  for (const manager of managers) {
    const health = await lens.getManagerHealth(vaultAddress, manager);
    const debt = await vault.getManagerTrueDebt(manager);
    const collateralValue = await lens.getManagerPositionValue(vaultAddress, manager);

    // Alert if approaching liquidation
    const liquidationThreshold = await strategy.liquidationThreshold();
    if (health < liquidationThreshold * 1.1) {  // Within 10% of liquidation
      console.warn(`⚠️  Manager ${manager} health: ${health / 1e16}%`);
    }

    // Alert if large position at risk
    if (debt > 1_000_000e18 && health < liquidationThreshold * 1.2) {
      console.error(`🚨 Large position at risk: ${manager}`);
      console.error(`   Debt: $${debt / 1e18}`);
      console.error(`   Health: ${health / 1e16}%`);
    }
  }
}

// Run every 5 minutes
setInterval(() => monitorManagers(VAULT_ADDRESS), 5 * 60 * 1000);

Alert Thresholds:

• Health < 120% → Warning (in ADL zone)

• Health < 115% → Urgent (near liquidation)

• Health < 110% → Critical (liquidatable)

• Large position (>$1M) + health < 130% → Special monitoring

3. Oracle Health

async function monitorOracles(wrappers: string[]) {
  for (const wrapper of wrappers) {
    const asset = await IAsset(wrapper).underlyingAsset();

    try {
      const price = await oracleRegistry.getPrice(asset);
      const lastUpdate = await oracleRegistry.getLastUpdate(asset);

      const staleness = Date.now() / 1000 - lastUpdate;

      if (staleness > 3600) {  // 1 hour
        console.warn(`⚠️  Stale oracle for ${asset}: ${staleness}s old`);
      }

      // Check price sanity
      const historicalPrice = await getHistoricalPrice(asset);
      const deviation = Math.abs(price - historicalPrice) / historicalPrice;

      if (deviation > 0.1) {  // 10% deviation
        console.error(`🚨 Suspicious price for ${asset}: ${deviation * 100}% deviation`);
      }
    } catch (error) {
      console.error(`❌ Oracle failure for ${asset}:`, error);
    }
  }
}

Dashboard Setup

Create a monitoring dashboard with:

Real-Time Metrics:

• TVL (total value locked)

• Utilization %

• Bad debt %

• Number of active managers

• Total interest earned (lifetime)

Historical Charts:

• TVL over time

• Utilization over time

• Bad debt incidents

• Liquidation events

• Share price growth

Alerts:

• Email/SMS for critical events

• Discord/Telegram notifications

• PagerDuty for emergencies

Example Dashboard (Grafana/Dune):

-- Vault health query
SELECT
    block_time,
    total_assets,
    idle_liquidity,
    (total_assets - idle_liquidity) / total_assets AS utilization,
    bad_debt,
    bad_debt / total_assets AS bad_debt_ratio
FROM flux_vault_metrics
WHERE vault_address = 'YOUR_VAULT'
ORDER BY block_time DESC

---

Bad Debt Management

When Bad Debt Occurs

Bad debt happens when:

Liquidation payment < Manager debt
→ Shortfall = Bad debt
→ Socialized across all LPs

Example:

Manager Position:
- Debt: $100K
- Collateral: $90K (underwater!)
- Bond: $15K

Liquidation:
- Seized value: $90K + $15K = $105K
- After slippage: $103K
- Debt owed: $100K
- Payment: $103K
- Bad debt: $0

But if slippage was worse:
- After slippage: $97K
- Debt owed: $100K
- Payment: $97K
- Bad debt: $3K

Responding to Bad Debt

Immediate Actions:

1. Assess Impact:

   uint256 badDebt = vault.totalBadDebt();
   uint256 totalAssets = vault.totalAssets();
   uint256 impact = badDebt * 100 / (totalAssets + badDebt);
   
   console.log("LP loss:", impact, "%");

2. Communicate with LPs:

   📢 Vault Update:
   
   Bad debt event occurred: $3,000
   Impact on share price: 0.3% loss
   Cause: Price crash on Asset X exceeded liquidation buffer
   
   Actions taken:
   - Liquidation executed promptly
   - Reviewing risk parameters
   - Considering tighter buffers for Asset X
   
   Current vault health:
   - TVL: $997,000 (down from $1M)
   - Utilization: 75%
   - All other positions healthy

3. Root Cause Analysis:

   • Which asset crashed?

   • Was liquidation delayed?

   • Were parameters too aggressive?

   • Oracle issue?

   • Extreme market event (black swan)?

4. Adjust Parameters (if Mutable):

   // Tighten liquidation buffer for risky assets
   // Via strategy update (7-day timelock)
   strategy.setLiquidationBuffer(0.25e18);  // Increase from 20% to 25%

Preventing Future Bad Debt

Parameter Adjustments:

• Increase liquidation buffer

• Increase minimum bond ratio

• Lower adlUtilizationThreshold (ADL earlier)

• Remove problematic assets from allowlist (if Mutable)

Operational Improvements:

• Better oracle monitoring

• Faster liquidation bots

• Higher liquidator incentives

• Proactive manager communication

Capital Injection (optional):

// Vault creator can "eat" bad debt by depositing at a discount
// This benefits remaining LPs

uint256 badDebt = vault.totalBadDebt();
uint256 sharePrice = vault.convertToAssets(1e18);

// Deposit to absorb bad debt
// Your shares worth less, but you help vault recover
vault.deposit(badDebt, creatorAddress);

---

Oracle Security

Oracles are critical infrastructure for Flux vaults. Oracle failures can lead to:

• Incorrect liquidations

• Bad debt accumulation

• Vault insolvency

Oracle Best Practices

1. Use Trusted Sources

Good:

• Chainlink Price Feeds

• Band Protocol

• Pyth Network

Avoid:

• Uniswap V2 spot prices (manipulatable)

• Single DEX as sole source

• Unaudited custom oracles

2. Monitor Oracle Health

interface IOracleRegistry {
    function getPrice(address asset) external view returns (uint256);
    function getLastUpdate(address asset) external view returns (uint256);
    function isOracleHealthy(address asset) external view returns (bool);
}

// Check before relying on price
require(oracle.isOracleHealthy(asset), "Oracle unhealthy");
uint256 price = oracle.getPrice(asset);

3. Sanity Checks

async function validateOraclePrice(asset: string, price: bigint) {
  // Check 1: Not zero
  if (price === 0n) throw new Error("Zero price");

  // Check 2: Not stale (updated within 1 hour)
  const lastUpdate = await oracle.getLastUpdate(asset);
  if (Date.now() / 1000 - lastUpdate > 3600) {
    throw new Error("Stale price");
  }

  // Check 3: Within reasonable bounds (vs. historical)
  const historicalPrice = await getHistoricalAverage(asset, 7 * 24 * 3600);
  const deviation = Math.abs(Number(price - historicalPrice)) / Number(historicalPrice);

  if (deviation > 0.2) {  // 20% deviation
    console.warn(`Suspicious price deviation: ${deviation * 100}%`);
  }
}

4. Multi-Oracle Validation

function getValidatedPrice(address asset)
    public
    view
    returns (uint256 price)
{
    // Get from multiple oracles
    uint256 chainlinkPrice = chainlink.getPrice(asset);
    uint256 uniswapPrice = uniswap.getPrice(asset);

    // Prices should be within 5%
    require(
        abs(chainlinkPrice - uniswapPrice) * 100 / chainlinkPrice < 5,
        "Oracle mismatch"
    );

    // Use average or most conservative
    return (chainlinkPrice + uniswapPrice) / 2;
}

Responding to Oracle Failures

Scenario 1: Oracle goes offline

Impact: Cannot value collateral → Cannot liquidate
Risk: Positions can become underwater without liquidation

Response:
1. Use backup oracle (if available)
2. Pause new borrows until oracle restored
3. Communicate with managers to close positions
4. Monitor other oracles for same asset

Scenario 2: Oracle manipulated

Impact: Incorrect valuations → False liquidations or missed liquidations
Risk: LPs lose money, managers unfairly liquidated

Response:
1. Verify manipulation (check multiple sources)
2. If confirmed: Emergency communication to all users
3. Analyze affected positions
4. Consider governance intervention
5. Switch oracle provider

Scenario 3: Flash loan attack

Impact: Temporary price manipulation
Risk: Depends on oracle design (should be resistant)

Response:
1. Ensure oracle uses TWAP or resistant mechanism
2. If vulnerability found: Urgent patch/migration
3. Educate managers on risks

Oracle Governance

Adding New Asset Oracles:

// Governance proposal to add oracle for new asset
function proposeNewOracle(
    address asset,
    address oracleFeed,
    string memory justification
) external onlyGovernance {
    // 1. Test oracle thoroughly
    // 2. Verify price accuracy
    // 3. Check update frequency
    // 4. Submit proposal with 7-day voting period

    // After approval:
    oracleRegistry.addOracle(asset, oracleFeed);
}

Updating Existing Oracles:

// Switch to better oracle
function updateOracle(address asset, address newOracleFeed)
    external onlyGovernance {
    // Timelock (7 days) gives users time to exit

    oracleRegistry.updateOracle(asset, newOracleFeed);
}

---

Emergency Procedures

Emergency Scenarios

1. Critical Smart Contract Bug

Indicators:

• Funds drained

• Unexpected behavior

• Security researcher disclosure

Immediate Actions:

1. Assess severity (can funds be lost?)
2. If critical:
   - Public disclosure
   - Recommend all users withdraw
   - Contact security partners
   - Prepare patch or migration
3. If non-critical:
   - Private disclosure to team
   - Develop fix
   - Test extensively
   - Deploy update (if upgradeable)

2. Oracle Failure

See Oracle Security above.

3. Bank Run (Mass Withdrawals)

Indicators:

• Utilization suddenly spikes to 100%

• LPs unable to withdraw

• Managers not repaying

Actions:

// Use ADL to free liquidity
address[] memory managersToADL = identifyADLTargets();

for (uint i = 0; i < managersToADL.length; i++) {
    vault.executeADL(managersToADL[i], [], "");

    // Check if we've freed enough liquidity
    if (vault.getIdleLiquidity() > targetLiquidity) break;
}

4. Bad Debt Spiral

Indicators:

• Multiple manager defaults

• Bad debt > 10% of TVL

• Share price dropping rapidly

Actions:

1. Emergency communication to all LPs
2. Identify cause (market crash, oracle issue, etc.)
3. If parameters too aggressive:
   - Propose immediate migration to new vault
   - More conservative parameters
4. If black swan event:
   - Accept losses
   - Transparent reporting
   - Insurance claims (if available)
5. Consider vault wind-down if unrecoverable

---

Related Documentation

• Strategy Selection Guide - Choose safe parameters

• Vault Creation Guide - Deploy your vault

• Oracle Concept - Understand oracle risks

• Liquidation Mechanism - How liquidations protect vaults