Flux Vault

Flux Vault is an ERC4626-compliant lending vault that enables liquidity providers to earn yield while managers access leveraged capital for trading heterogeneous assets.

What is a Flux Vault?

A Flux Vault combines traditional lending pool functionality with a sophisticated position tracking system. Each vault:

• Has one base asset (e.g., USDC, WETH)

• Allows managers to borrow capital by posting bonds (collateral)

• Tracks manager positions across multiple asset types

• Charges continuous interest on borrowed capital

• Enforces health requirements through liquidations

Unlike traditional lending protocols where users borrow specific assets, Flux enables borrowing capital to trade any whitelisted asset.

---

Key Features

ERC-4626 Compatibility

Flux Vaults implement the ERC-4626 "Tokenized Vault" standard, providing:

• Consistent interface for deposits/withdrawals

• Composable vault shares

• Compatibility with DeFi aggregators

• Standard accounting methods

3-Layer Position Tracking

Positions are organized as: account → subaccount → positionId

// Example: USDC Vault tracking Manager's positions
vault (0x123...)                          // account (vault address)
  └─ manager (0xabc...)                   // subaccount (manager address)
      ├─ 0x00 (WORKING_CAPITAL)           // Active trading capital
      ├─ 0x01 (BOND)                      // Posted collateral
      ├─ 0x02 (WETH position)             // Wrapped WETH
      └─ 0x03 (UniV3 LP position)         // Uniswap V3 NFT

This model enables:

• Multi-asset positions per manager

• Isolated accounting per vault

• Efficient gas usage via flash accounting

Flash Accounting

Instead of storing position values onchain, Flux:

1. Queries wrapper contracts for real-time values during callbacks

2. Calculates total position value dynamically

3. Validates health at the end of unlock() callback

4. Reverts entire transaction if unhealthy

Benefits:

• Lower storage costs

• Always accurate position values

• Simplified state management

Bond-Based Margin System

Managers must post a bond (collateral in base asset) to borrow capital.

Example (20% minimum bond ratio):

• Manager wants to borrow 100K USDC

• Required bond: 20K USDC (20% of 100K)

• Total capital accessed: 100K USDC

• Leverage: 5x (100K / 20K)

Health Check:

Health Ratio = Total Position Value / True Debt
Liquidatable when: Health Ratio < Liquidation Threshold

Where:

• Total Position Value = Sum of all position values (bond + working capital + assets)

• True Debt = Principal debt + accrued interest

• Liquidation Threshold = Typically ~110% (1.1e18)

---

Core Vault Operations

For Liquidity Providers

Deposit

// Standard ERC4626 deposit
baseAsset.approve(address(vault), amount);
uint256 shares = vault.deposit(amount, receiver);

What happens:

1. LP transfers base asset to vault

2. Vault mints shares proportional to amount / sharePrice

3. Shares represent claim on vault assets

Withdraw

// Standard ERC4626 withdrawal
uint256 assets = vault.redeem(shares, receiver, owner);

Withdrawal Behavior:

• Withdrawals succeed immediately if vault has sufficient idle liquidity

• If insufficient liquidity, the withdrawal transaction reverts

• LPs must wait for manager repayments or ADL to free up liquidity

• No withdrawal queue or forced liquidation features

What to do if withdrawal fails:

1. Wait for natural manager repayments (managers close positions over time)

2. If vault utilization is very high (>95%), the ADL Manager may trigger Auto-Deleveraging to free liquidity

3. Monitor vault liquidity and retry when available

See Emergency Withdrawals Guide for detailed information on handling withdrawal failures.

For Managers

Register Executor

Before borrowing, managers must register an executor:

// Option 1: Deploy Weiroll executor (recommended)
address executor = factory.deployWeirollExecutor();

// Option 2: Register custom executor
factory.registerExecutor(manager, customExecutor);

The executor implements IFluxUnlockCallback for position management.

Unlock Pattern

All manager operations use the unified unlock() callback:

// Unlock vault to perform operations
vault.unlock(encodedData);

// Inside callback (IFluxUnlockCallback):
function fluxUnlockCallback(bytes calldata data) external {
    // Called by vault, must return to msg.sender (vault)

    // Borrow capital
    vault.locked_borrow(100_000e6);

    // Trade: USDC → WETH
    // ... swap logic ...

    // Deposit WETH to wrapper
    vault.locked_depositToWrapper(wethWrapper, positionId, wethAmount);

    // At end: vault checks position health
}

Available Locked Operations

Capital Management:

• locked_borrow(amount): Borrow capital from vault

• locked_repay(amount): Repay borrowed capital

Collateral Management:

• locked_depositBond(amount): Add bond collateral

• locked_withdrawBond(amount): Remove bond collateral

Asset Management:

• locked_registerWrapper(wrapper): Enable new asset wrapper

• locked_deregisterWrapper(wrapper): Remove asset wrapper

• locked_depositToWrapper(wrapper, positionId, amount): Deposit to position

• locked_withdrawFromWrapper(wrapper, positionId, amount): Withdraw from position

• locked_claimFromWrapper(wrapper, positionId, amountOrTokenId): Claim pre-received assets

• locked_moveFunds(fromPos, toPos, amount): Move funds between positions

Advanced:

• locked_interactWithWrapper(wrapper, data): Custom wrapper interactions

For Liquidators

Liquidators maintain protocol health by liquidating underwater positions.

Liquidation Flow

// Liquidate unhealthy manager
vault.liquidate(manager, additionalWrappers, weirollScript);

// Inside callback:
function fluxUnlockCallback(bytes calldata data) external {
    // 1. Borrow capital to pay liquidation (capital-free!)
    vault.locked_borrow(minPayment);

    // 2. Pay vault
    baseAsset.transfer(address(vault), minPayment);

    // 3. Extract seized collateral
    vault.locked_withdrawFromWrapper(wrapper, positionId, amount);

    // 4. Swap collateral for profit
    // ... swap logic ...

    // 5. Repay borrowed capital + keep profit
}

Liquidation Bonus:

• Healthy position (collateral ≥ debt): Zero bonus, pay full debt

• Underwater position (collateral < debt): Pay (1 - liquidationProfitMargin) × collateralValue

---

Interest Accrual

How Interest Works

Interest accrues continuously based on the vault's strategy:

// Interest calculation
LP Index = previous index × (1 + rate × time)
True Debt = Principal Debt × (Current LP Index / Snapshot LP Index)

Key Variables:

• lastLpIndex: Current LP index (starts at 1e18)

• lastCheckpointTimestamp: Last time interest accrued

• principalDebt: Manager's debt before interest

• lastLpIndexSnapshot: LP index when manager last updated

Interest Collection

Anyone can trigger interest collection:

// Collect interest from manager's bond
vault.collectInterest(manager);

// Batch collect from multiple managers
vault.batchCollectInterest([manager1, manager2, manager3]);

What happens:

1. Calculate accrued interest: interest = trueDebt - principalDebt

2. Deduct from manager's bond

3. Distribute to protocol, curator, and LPs

4. Update manager's snapshot

Fee Distribution

When interest is collected:

Total Interest
  ├─ Protocol Fee (e.g., 10%)
  ├─ Curator Fee (e.g., 10%)
  └─ LP Share (e.g., 80%)

Configured in the vault's strategy contract.

---

Vault Configuration

Immutable Parameters (Set at Deployment)

function createVault(
    IERC20 asset,              // Base asset (e.g., USDC)
    IAsset baseAssetWrapper,   // Wrapper for base asset
    IStrategy strategy,        // Strategy contract
    IAccessPolicy accessPolicy, // Access control
    string memory name,        // Vault name
    string memory symbol       // Share symbol
) external returns (IFluxVault vault)

Cannot be changed after deployment:

• Base asset

• Strategy (interest rates, bond ratios, allowed assets)

• Access policy (who can deposit)

• Base asset wrapper

Mutable Parameters (If Using Mutable Strategy)

Vaults using MutableFixedRateStrategy can update parameters with 7-day timelock:

• Interest rate

• Curator fee rate

• Allowed asset wrappers (can add, cannot remove)

---

Access Control

Vaults can use different access policies:

Permissionless Access

Anyone can deposit as LP, anyone can borrow as manager (if they meet requirements).

Whitelist Access

Only whitelisted addresses can:

• Deposit as LP

• Borrow as manager

Implemented via WhitelistAccessPolicy or custom policies.

---

Safety Mechanisms

Auto-Deleveraging (ADL)

Vaults support ADL to protect LPs during high utilization:

• Vault creator can set an ADL Manager

• ADL Manager can force-close healthy positions when vault utilization is very high (>95%)

• Managers receive their full net equity back (no penalties)

• Helps free liquidity for LP withdrawals

See Auto-Deleveraging for complete documentation.

Deposit Policies

Vaults can optionally use deposit policies to restrict deposits:

• Utilization-based caps

• Per-user limits

• Time-based restrictions

• Custom logic via IDepositPolicy interface

Access Control

Vaults use access policies to control who can participate:

• Permissionless (anyone can deposit/borrow)

• Whitelisted (only approved addresses)

• Custom policies via IAccessPolicy interface

---

Vault States

Utilization

Utilization = Total Debt / Total Assets

High utilization (>95%) may trigger:

• ADL (Auto-Deleveraging) for managers to free up liquidity

• Withdrawal failures for LPs (must wait for repayments or ADL)

Idle Liquidity

Idle Liquidity = Total Assets - Total Debt

Immediately available for withdrawals without liquidating managers.

Share Price

Share Price = Total Assets / Total Shares

Increases over time as interest accrues to LPs.

---

Position Health

Health Ratio

Health Ratio = Total Position Value / True Debt

Status:

• ≥ 1.1 (110%): Healthy

• < 1.1 (110%): Liquidatable

Total Position Value

Sum of all manager positions:

• Bond (base asset)

• Working capital (base asset)

• Wrapped assets (valued via oracles)

Example:

Manager Position:
  Bond: 20K USDC
  Working Capital: 10K USDC
  WETH position: 30K USDC equivalent
  Total Value: 60K USDC

  True Debt: 50K USDC
  Health Ratio: 60K / 50K = 1.2 (120%) ✓ Healthy

---

What is a MetaVault in Flux?

A MetaVault is a "vault-of-vaults" - an ERC4626-compliant vault that holds shares in multiple underlying FluxVaults rather than directly managing lending positions.

Key Architecture: The Holding Pen Pattern

The most distinctive feature is the holding pen design:

1. User deposits → MetaVault mints shares → Assets stay in an idle pool (not immediately deployed)

2. Allocator later decides when/where to allocate assets to underlying vaults

3. On withdrawal: MetaVault first tries to fulfill from idle pool; if insufficient, the LP must wait or use forceDeallocate

This prevents deposits from getting locked in loans that can't easily be rebalanced.

Core Components

Component	Role
MetaVault (src/FluxMetaVault.sol)	Holds assets (idle pool + underlying vault shares)
Allocator (src/allocators/)	Manages vault list, penalties, and allocation rules
Curator	allocator.owner() - controls allocation strategy

Key Functions

Function	Who Can Call	Purpose
allocate(vault, amount)	Allocator only	Move assets from idle pool → underlying vault
deallocate(vault, amount)	Allocator only	Pull assets from underlying vault → idle (no penalty)
forceDeallocate(vault, amount)	Anyone	Pull assets with a penalty (shares burned from caller)
setFee(newFee)	Curator only	Set performance fee (max 50%)

MetaVault vs Regular FluxVault

Aspect	Regular FluxVault	MetaVault
Purpose	Direct lending vault	Meta-allocator across multiple vaults
Deposits	Immediately available for lending	Go to idle pool first
Underlying	Base assets + manager positions	Shares in other FluxVaults
Withdrawals	Subject to manager liquidity	Limited by idle balance

Architecture Hierarchy

LPs → MetaVault
       ├── Idle Pool (base assets)
       └── Underlying FluxVaults (shares)
           ├── Idle Pool
           └── Manager Positions

Why This Design?

1. Prevents liquidity deadlocks - LPs can always exit via forceDeallocate (with penalty)

2. Separates concerns - Asset custody (MetaVault) is separate from allocation logic (Allocator)

3. Flexible strategies - Different allocator implementations (SimpleAllocator, rule-based allocators) can be plugged in

4. Economic incentives - Force deallocate penalties benefit remaining LPs (share price increases)