Integration Guide

This guide provides everything you need to integrate Flux vaults as a liquidity provider, whether you're building a DeFi aggregator, a wallet, or simply depositing directly.

Overview

As an LP in Flux, you:

Deposit base assets (USDC, WETH, etc.) into ERC4626-compliant vaults
Receive vault shares representing your claim on vault assets
Earn yield from manager interest and fees
Can withdraw anytime (subject to vault liquidity)

Key Difference from "Trust-Me" Yield Models: Every Flux vault shows you exactly where your capital goes, what managers can do with it, and how you're protected.

Understanding Vault Safety

Before depositing, verify these safety mechanisms:

1. Collateralization Requirements

Check the vault's strategy to see minimum bond ratio:

IStrategy strategy = vault.STRATEGY();
uint256 minBondRatio = strategy.minBondRatio();

// Example: 0.2e18 = 20% bond required
// This means managers must post $20K bond to borrow $100K
// Bonds ensure managers have skin in the game

Higher bond ratio = More manager collateral = Safer for LPs.

2. Whitelisted Assets

See exactly what assets managers can hold:

// Get allowed assets from strategy
// These are the ONLY assets managers can deposit to

IAsset[] memory allowedWrappers = getStrategyAllowedAssets(strategy);

for (uint i = 0; i < allowedWrappers.length; i++) {
    address asset = allowedWrappers[i].underlyingAsset();
    console.log("Managers can hold:", asset);
}

No surprise exposure to risky assets. Everything is transparent.

3. Liquidation Parameters

Understand when positions get liquidated:

uint256 liquidationThreshold = strategy.liquidationThreshold();
// Example: 1.1e18 = 110%
// Managers get liquidated if their collateral drops below 110% of debt

uint256 liquidationProfitMargin = strategy.liquidationProfitMargin();
// Example: 0.01e18 = 1%
// Liquidators get 1% profit, minimizing LP losses from bad debt

Lower liquidation threshold = Earlier liquidations = Less LP risk.

4. Strategy Immutability

Check if strategy parameters can change:

// Immutable strategies: parameters locked forever
// Mutable strategies: parameters can change with 7-day timelock

// Check strategy type by trying to call owner()
try IOwnable(address(strategy)).owner() returns (address owner) {
    if (owner != address(0)) {
        console.log("Mutable strategy, owner can update params");
    }
} catch {
    console.log("Immutable strategy, params locked forever");
}

Immutable = No governance risk. Mutable = Flexibility with timelock protection.

Depositing to a Vault

Standard Deposit (ERC4626)

import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {IFluxVault} from "flux-v1-contracts/interfaces/IFluxVault.sol";

contract LPIntegration {
    IFluxVault public vault;
    IERC20 public baseAsset;

    function deposit(uint256 assets) external {
        // 1. Check vault isn't paused or having issues
        require(vault.totalAssets() > 0, "Vault inactive");

        // 2. Approve vault to spend your tokens
        baseAsset.approve(address(vault), assets);

        // 3. Deposit and receive shares
        uint256 shares = vault.deposit(assets, msg.sender);

        // shares = assets * totalShares / totalAssets
        // Your shares represent pro-rata claim on all vault assets
    }
}

function previewDeposit(uint256 assets) public view returns (uint256 shares) {
    // See how many shares you'll get before depositing
    shares = vault.previewDeposit(assets);

    // Calculate effective share price
    uint256 sharePrice = vault.convertToAssets(1e18); // Price of 1 share
    console.log("Share price:", sharePrice);
}

Deposit with Slippage Protection

function depositWithSlippage(
    uint256 assets,
    uint256 minShares
) external returns (uint256 shares) {
    baseAsset.approve(address(vault), assets);

    // Preview expected shares
    uint256 expectedShares = vault.previewDeposit(assets);
    require(expectedShares >= minShares, "Slippage too high");

    // Execute deposit
    shares = vault.deposit(assets, msg.sender);

    require(shares >= minShares, "Received too few shares");
}

Mint Specific Shares

function mintExactShares(uint256 shares) external {
    // Instead of depositing exact assets, mint exact shares
    uint256 assetsNeeded = vault.previewMint(shares);

    baseAsset.approve(address(vault), assetsNeeded);
    uint256 assetsUsed = vault.mint(shares, msg.sender);

    // assetsUsed should equal assetsNeeded (may vary by 1 wei due to rounding)
}

Monitoring Your Position

Check Your Balance

function checkBalance() external view returns (
    uint256 shares,
    uint256 assets,
    uint256 sharePrice
) {
    // Your shares
    shares = vault.balanceOf(msg.sender);

    // Current value of your shares
    assets = vault.convertToAssets(shares);

    // Current share price (value of 1 share in base asset)
    sharePrice = vault.convertToAssets(1e18);
}

Track Yield Growth

struct DepositRecord {
    uint256 shares;
    uint256 depositedAssets;
    uint256 timestamp;
}

mapping(address => DepositRecord) public deposits;

function recordDeposit(uint256 assets, uint256 shares) internal {
    deposits[msg.sender] = DepositRecord({
        shares: shares,
        depositedAssets: assets,
        timestamp: block.timestamp
    });
}

function checkYield(address user) public view returns (
    uint256 currentValue,
    uint256 profit,
    uint256 profitPercent,
    uint256 apy
) {
    DepositRecord memory record = deposits[user];

    currentValue = vault.convertToAssets(record.shares);
    profit = currentValue - record.depositedAssets;
    profitPercent = (profit * 100e18) / record.depositedAssets;

    // Calculate APY
    uint256 timeElapsed = block.timestamp - record.timestamp;
    uint256 yearlyProfit = (profit * 365 days) / timeElapsed;
    apy = (yearlyProfit * 100e18) / record.depositedAssets;
}

Monitor Vault Health

function checkVaultHealth() external view returns (
    uint256 totalAssets,
    uint256 utilization,
    uint256 idleLiquidity,
    bool canWithdrawNow
) {
    totalAssets = vault.totalAssets();
    uint256 totalDebt = vault.totalPrincipalDebt();
    idleLiquidity = vault.getIdleLiquidity();

    utilization = (totalDebt * 1e18) / totalAssets;

    // Can you withdraw immediately?
    uint256 yourAssets = vault.convertToAssets(vault.balanceOf(msg.sender));
    canWithdrawNow = idleLiquidity >= yourAssets;
}

Withdrawing from a Vault

Standard Withdrawal (When Liquidity Available)

function withdraw(uint256 assets) external {
    // Check if vault has enough idle liquidity
    require(vault.getIdleLiquidity() >= assets, "Insufficient liquidity");

    // Withdraw exact asset amount
    uint256 shares = vault.withdraw(
        assets,
        msg.sender,  // receiver
        msg.sender   // owner
    );

    // Your shares are burned, assets are transferred to you
}

Redeem Shares

function redeemShares(uint256 shares) external {
    // Redeem all your shares
    uint256 assets = vault.redeem(
        shares,
        msg.sender,  // receiver
        msg.sender   // owner
    );

    console.log("Redeemed", shares, "shares for", assets, "assets");
}

Redeem All (Exit Completely)

function redeemAll() external {
    uint256 shares = vault.balanceOf(msg.sender);
    uint256 assets = vault.redeem(shares, msg.sender, msg.sender);

    console.log("Exited with", assets, "assets");
}

Preview Withdrawal

function previewWithdrawal(uint256 shares) public view returns (
    uint256 assets,
    bool canWithdrawNow
) {
    // How many assets will you get?
    assets = vault.previewRedeem(shares);

    // Can you withdraw now?
    canWithdrawNow = vault.getIdleLiquidity() >= assets;
}

When Withdrawals Fail (High Utilization)

When vault has high utilization, withdrawals may fail due to insufficient liquidity. See Emergency Withdrawals for details on:

Waiting for natural repayments
ADA (Auto-Deallocating) protection
Selling shares OTC

Emergency Withdrawal (Force Liquidate Manager)

Note: Flux does not have a traditional "emergency withdrawal" mechanism. If withdrawals fail due to insufficient liquidity, you must wait for:

Manager repayments (natural deleveraging)
ADA (Auto-Deallocating) to free up liquidity
Or sell your shares OTC

See Emergency Withdrawals for complete details on handling withdrawal failures.

Integration Best Practices

1. Always Check Vault Safety Before Depositing

function safetyChecklist(IFluxVault vault) public view returns (bool safe) {
    IStrategy strategy = vault.STRATEGY();

    // 1. Check minimum bond ratio (prefer >= 20%)
    uint256 minBondRatio = strategy.minBondRatio();
    if (minBondRatio < 0.2e18) return false;

    // 2. Check liquidation threshold (prefer >= 110%)
    uint256 liquidationThreshold = strategy.liquidationThreshold();
    if (liquidationThreshold < 1.1e18) return false;

    // 3. Check vault has activity
    if (vault.totalAssets() == 0) return false;

    // 4. Check utilization isn't too high (prefer < 90%)
    uint256 utilization = (vault.totalPrincipalDebt() * 1e18) / vault.totalAssets();
    if (utilization > 0.9e18) return false;

    return true;
}

2. Monitor for Parameter Changes (Mutable Strategies)

event StrategyParameterChanged(address indexed vault, string parameter, uint256 newValue);

function monitorStrategyChanges(IFluxVault vault) external {
    // If mutable strategy, watch for queued changes
    // Set up event listeners for:
    // - annualRate changes
    // - curatorFeeRate changes
    // - asset additions

    // React by exiting if you disagree with new parameters
}

3. Diversify Across Vaults

contract VaultAggregator {
    struct VaultAllocation {
        IFluxVault vault;
        uint256 targetPercent;  // e.g., 25e18 = 25%
    }

    VaultAllocation[] public allocations;

    function depositAcrossVaults(uint256 totalAssets) external {
        for (uint i = 0; i < allocations.length; i++) {
            uint256 vaultAssets = (totalAssets * allocations[i].targetPercent) / 100e18;

            baseAsset.approve(address(allocations[i].vault), vaultAssets);
            allocations[i].vault.deposit(vaultAssets, address(this));
        }
    }
}

4. Set Up Automated Monitoring

// Off-chain monitoring script
async function monitorVaults() {
  for (const vault of myVaults) {
    // Check share price hasn't dropped unexpectedly
    const currentPrice = await vault.convertToAssets(ethers.parseEther("1"));
    if (currentPrice < previousPrice * 0.95) {
      alert(`Vault ${vault.address} share price dropped 5%!`);
    }

    // Check utilization
    const utilization = await getUtilization(vault);
    if (utilization > 0.95e18) {
      alert(`Vault ${vault.address} utilization over 95%`);
    }

    // Check for bad debt
    const badDebt = await vault.totalBadDebt();
    if (badDebt > 0) {
      alert(`Vault ${vault.address} has ${badDebt} bad debt`);
    }
  }
}

Understanding Risks

1. Manager Default Risk

What: Manager's positions lose value faster than they can be liquidated.

Protection:

Manager bonds provide collateral buffer
Automated liquidations minimize lag
Strategy-aware risk engine catches issues early

Your Risk: Only if manager's bond is insufficient AND liquidation is delayed.

2. Oracle Failure Risk

What: Oracle provides incorrect prices, preventing accurate liquidations.

Protection:

Vaults use reputable oracles (Chainlink, etc.)
Multiple oracle sources where possible
Oracle staleness checks

Your Risk: If oracle fails completely, positions may not liquidate properly.

3. Smart Contract Risk

What: Bug in vault, strategy, or wrapper contracts.

Protection:

Audited contracts
Immutable core logic
Battle-tested on testnet

Your Risk: Always present in DeFi. Mitigate by checking audits and starting small.

4. Liquidity Risk

What: Cannot withdraw immediately when vault is fully utilized.

Protection:

Queued withdrawals
Emergency withdrawal option (with penalty)
Vault utilization monitoring

Your Risk: May need to wait for liquidity or pay penalty for emergency exit.

Vault Selection Criteria

When choosing a vault, consider:

Conservative (Low Risk, Lower Yield)

Immutable strategy
High bond ratio (25-30%)
High liquidation buffer (15-20%)
Well-known assets only (WETH, WBTC, USDC)
Low utilization (<70%)
Established vault with track record

Moderate (Balanced Risk/Yield)

Mutable or immutable strategy
Medium bond ratio (20-25%)
Medium liquidation buffer (10-15%)
Mix of established and newer assets
Medium utilization (70-85%)
Some track record

Aggressive (Higher Risk, Higher Yield)

Mutable strategy
Low bond ratio (15-20%)
Low liquidation buffer (5-10%)
Includes newer/riskier assets
High utilization (85-95%)
Newer vault

Sample Integration

Here's a complete LP integration example:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {IFluxVault} from "flux-v1-contracts/interfaces/IFluxVault.sol";
import {IStrategy} from "flux-v1-contracts/interfaces/IStrategy.sol";

contract FluxLPIntegration {
    IERC20 public immutable baseAsset;
    IFluxVault public immutable vault;

    event Deposited(address indexed user, uint256 assets, uint256 shares);
    event Withdrawn(address indexed user, uint256 assets, uint256 shares);

    constructor(address _vault) {
        vault = IFluxVault(_vault);
        baseAsset = IERC20(vault.asset());
    }

    // Deposit with safety checks
    function safeDeposit(uint256 assets, uint256 minShares) external returns (uint256 shares) {
        // Safety checks
        require(checkVaultSafe(), "Vault safety check failed");

        // Preview
        uint256 expectedShares = vault.previewDeposit(assets);
        require(expectedShares >= minShares, "Slippage too high");

        // Execute
        baseAsset.transferFrom(msg.sender, address(this), assets);
        baseAsset.approve(address(vault), assets);

        shares = vault.deposit(assets, msg.sender);

        emit Deposited(msg.sender, assets, shares);
    }

    // Withdraw with liquidity check
    function safeWithdraw(uint256 shares) external returns (uint256 assets) {
        // Check liquidity
        uint256 expectedAssets = vault.previewRedeem(shares);
        uint256 idleLiquidity = vault.getIdleLiquidity();

        require(idleLiquidity >= expectedAssets, "Insufficient liquidity - try again later");

        // Withdraw
        assets = vault.redeem(shares, msg.sender, msg.sender);

        emit Withdrawn(msg.sender, assets, shares);
    }

    // Safety checklist
    function checkVaultSafe() public view returns (bool) {
        IStrategy strategy = vault.STRATEGY();

        // Check bond ratio >= 20%
        if (strategy.minBondRatio() < 0.2e18) return false;

        // Check liquidation threshold >= 110%
        if (strategy.liquidationThreshold() < 1.1e18) return false;

        // Check vault active
        if (vault.totalAssets() == 0) return false;

        // Check utilization < 90%
        uint256 util = (vault.totalPrincipalDebt() * 1e18) / vault.totalAssets();
        if (util > 0.9e18) return false;

        return true;
    }

    // Get comprehensive vault info
    function getVaultInfo() external view returns (
        uint256 totalAssets,
        uint256 sharePrice,
        uint256 utilization,
        uint256 idleLiquidity,
        uint256 apy
    ) {
        totalAssets = vault.totalAssets();
        sharePrice = vault.convertToAssets(1e18);

        uint256 totalDebt = vault.totalPrincipalDebt();
        utilization = (totalDebt * 1e18) / totalAssets;

        idleLiquidity = vault.getIdleLiquidity();

        // Approximate APY from interest rate
        IStrategy strategy = vault.STRATEGY();
        apy = strategy.annualRate();
    }
}

Next Steps

Learn More:

PreviousQuickstart NextDepositing & Withdrawing

Last updated 1 month ago

hashtagOverview

hashtagUnderstanding Vault Safety

hashtag1. Collateralization Requirements

hashtag2. Whitelisted Assets

hashtag3. Liquidation Parameters

hashtag4. Strategy Immutability

hashtagDepositing to a Vault

hashtagStandard Deposit (ERC4626)

hashtagPreview Deposit (Check Share Price)

hashtagDeposit with Slippage Protection

hashtagMint Specific Shares

hashtagMonitoring Your Position

hashtagCheck Your Balance

hashtagTrack Yield Growth

hashtagMonitor Vault Health

hashtagWithdrawing from a Vault

hashtagStandard Withdrawal (When Liquidity Available)

hashtagRedeem Shares

hashtagRedeem All (Exit Completely)

hashtagPreview Withdrawal

hashtagWhen Withdrawals Fail (High Utilization)

hashtagEmergency Withdrawal (Force Liquidate Manager)

hashtagIntegration Best Practices

hashtag1. Always Check Vault Safety Before Depositing

hashtag2. Monitor for Parameter Changes (Mutable Strategies)

hashtag3. Diversify Across Vaults

hashtag4. Set Up Automated Monitoring

hashtagUnderstanding Risks

hashtag1. Manager Default Risk

hashtag2. Oracle Failure Risk

hashtag3. Smart Contract Risk

hashtag4. Liquidity Risk

hashtagVault Selection Criteria

hashtagConservative (Low Risk, Lower Yield)

hashtagModerate (Balanced Risk/Yield)

hashtagAggressive (Higher Risk, Higher Yield)

hashtagSample Integration

hashtagNext Steps

Overview

Understanding Vault Safety

1. Collateralization Requirements

2. Whitelisted Assets

3. Liquidation Parameters

4. Strategy Immutability

Depositing to a Vault

Standard Deposit (ERC4626)

Preview Deposit (Check Share Price)

Deposit with Slippage Protection

Mint Specific Shares

Monitoring Your Position

Check Your Balance

Track Yield Growth

Monitor Vault Health

Withdrawing from a Vault

Standard Withdrawal (When Liquidity Available)

Redeem Shares

Redeem All (Exit Completely)

Preview Withdrawal

When Withdrawals Fail (High Utilization)

Emergency Withdrawal (Force Liquidate Manager)

Integration Best Practices

1. Always Check Vault Safety Before Depositing

2. Monitor for Parameter Changes (Mutable Strategies)

3. Diversify Across Vaults

4. Set Up Automated Monitoring

Understanding Risks

1. Manager Default Risk

2. Oracle Failure Risk

3. Smart Contract Risk

4. Liquidity Risk

Vault Selection Criteria

Conservative (Low Risk, Lower Yield)

Moderate (Balanced Risk/Yield)

Aggressive (Higher Risk, Higher Yield)

Sample Integration

Next Steps