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
    }
}

Preview Deposit (Check Share Price)

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)
}

See also: Depositing & Withdrawing.

---

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;
}

See also: Depositing & Withdrawing.

---

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

• ADL (Auto-Deleveraging) 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)

• ADL (Auto-Deleveraging) 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:

• Vault Concepts

• Strategies

• Risk Management