Integration Guide

This guide covers everything you need to integrate with Flux as a manager—from registering your executor to executing complex multi-protocol strategies with automated risk management.

Overview

As a manager in Flux, you get:

• Automated Liquidation Protection: Continuous monitoring and liquidation management

• Atomic Flexibility: Execute complex, multi-leg strategies in single transaction

• Permissionless Execution: Swap, farm, LP, hedge—any on-chain action

• Leveraged Capital: Access 5-10x your posted bond

• Verifiable Collateral: Build trust through transparent bond requirements

The Only Rule: Return the vault's whitelisted assets by end of callback.

---

Getting Started

Step 1: Register an Executor

Before borrowing from any vault, you must register an executor that implements the callback interface. Once you have registered an executor, you can use it for all subsequent vault interactions.

Option A: Deploy Weiroll Executor (Recommended)

import {IFluxVaultFactory} from "flux-v1-contracts/interfaces/IFluxVaultFactory.sol";

contract ManagerSetup {
    IFluxVaultFactory public factory;

    function deployExecutor() external returns (address executor) {
        // Deploy a Weiroll executor owned by you
        executor = factory.deployWeirollExecutor();

        // Automatically registered to msg.sender
        // Can now borrow from any vault
    }
}

Option B: Deploy Custom Executor

import {IFluxUnlockCallback} from "flux-v1-contracts/interfaces/IFluxUnlockCallback.sol";

contract MyCustomExecutor is IFluxUnlockCallback {
    address public immutable owner;

    constructor(address _owner) {
        owner = _owner;
    }

    function fluxUnlockCallback(bytes calldata data) external override {
        // Your custom callback logic
        // Must be called by a FluxVault
        // Must be owned by the manager
    }
}

// Deploy and register
MyCustomExecutor executor = new MyCustomExecutor(msg.sender);
factory.registerExecutor(msg.sender, address(executor));

Step 2: Choose a Vault

Select a vault based on:

function evaluateVault(IFluxVault vault) public view returns (
    bool suitable,
    uint256 maxLeverage,
    uint256 interestRate,
    address[] memory allowedAssets
) {
    IStrategy strategy = vault.STRATEGY();

    // Check interest rate
    interestRate = strategy.annualRate();
    if (interestRate > 0.15e18) return (false, 0, 0, new address[](0)); // >15% too high

    // Calculate max leverage
    uint256 minBondRatio = strategy.minBondRatio();
    maxLeverage = 1e18 / minBondRatio; // e.g., 20% bond = 5x leverage

    // Check allowed assets match your strategy
    allowedAssets = getStrategyAllowedAssets(strategy);

    suitable = true;
}

---

Understanding the Unlock Pattern

All manager operations use the unified unlock() callback:

// 1. Manager calls unlock
vault.unlock(encodedData);

// 2. Vault calls your executor
function fluxUnlockCallback(bytes calldata data) external {
    // 3. You have temporary "unlocked" access to perform operations

    vault.locked_borrow(amount);           // Borrow capital
    vault.locked_repay(amount);            // Repay debt
    vault.locked_depositBond(amount);      // Add collateral
    vault.locked_withdrawBond(amount);     // Remove collateral

    vault.locked_registerWrapper(wrapper); // Enable asset
    vault.locked_depositToWrapper(...);    // Deposit to position
    vault.locked_withdrawFromWrapper(...); // Withdraw from position

    // 4. At end: vault automatically checks your health
    //    Reverts entire transaction if unhealthy
}

This is atomic: Either everything succeeds or everything reverts.

---

Borrowing Capital

Initial Borrow

function initialBorrow(
    IFluxVault vault,
    uint256 borrowAmount,
    uint256 bondAmount
) external {
    // Encode operation data
    bytes memory data = abi.encode("INITIAL_BORROW", borrowAmount, bondAmount);

    // Call unlock
    vault.unlock(data);
}

// In your executor's callback:
function fluxUnlockCallback(bytes calldata data) external {
    (string memory op, uint256 borrowAmount, uint256 bondAmount) =
        abi.decode(data, (string, uint256, uint256));

    if (keccak256(bytes(op)) == keccak256("INITIAL_BORROW")) {
        // 1. Deposit bond (collateral)
        baseAsset.approve(address(vault), bondAmount);
        vault.locked_depositBond(bondAmount);

        // 2. Borrow capital
        vault.locked_borrow(borrowAmount);

        // 3. Now you have borrowAmount in your WORKING_CAPITAL position
        //    This is tracked in the vault's base asset wrapper

        // Position health checked automatically at end
    }
}

Check Borrowing Capacity

function checkBorrowCapacity(address vault, address manager) public view returns (
    uint256 maxBorrow,
    uint256 currentDebt,
    uint256 availableCredit
) {
    IFluxVault v = IFluxVault(vault);
    IStrategy strategy = v.STRATEGY();

    // Get current position
    currentDebt = v.getManagerTrueDebt(manager);
    uint256 bondBalance = v.getBondBalance(manager);

    // Calculate max based on bond
    uint256 minBondRatio = strategy.minBondRatio();
    maxBorrow = (bondBalance * 1e18) / minBondRatio;

    // Available credit
    availableCredit = maxBorrow > currentDebt ? maxBorrow - currentDebt : 0;
}

---

Trading Assets

Register Asset Wrapper

Before depositing to a wrapper, register it:

function enableAsset(IFluxVault vault, IAsset wrapper) external {
    bytes memory data = abi.encode("REGISTER_WRAPPER", address(wrapper));
    vault.unlock(data);
}

// In callback:
function fluxUnlockCallback(bytes calldata data) external {
    (string memory op, address wrapper) = abi.decode(data, (string, address));

    if (keccak256(bytes(op)) == keccak256("REGISTER_WRAPPER")) {
        vault.locked_registerWrapper(wrapper);
        // Wrapper now enabled for this manager in this vault
    }
}

Execute Trade (Swap + Deposit)

struct TradeParams {
    IAsset fromWrapper;
    bytes32 fromPositionId;
    uint256 fromAmount;
    IAsset toWrapper;
    bytes32 toPositionId;
    bytes swapData;
}

function executeTrade(IFluxVault vault, TradeParams memory params) external {
    bytes memory data = abi.encode("TRADE", params);
    vault.unlock(data);
}

// In callback:
function fluxUnlockCallback(bytes calldata data) external {
    (string memory op, TradeParams memory params) =
        abi.decode(data, (string, TradeParams));

    if (keccak256(bytes(op)) == keccak256("TRADE")) {
        // 1. Withdraw from source position
        vault.locked_withdrawFromWrapper(
            params.fromWrapper,
            params.fromPositionId,
            params.fromAmount
        );
        // Assets sent to executor (this contract)

        // 2. Execute swap (example: Uniswap)
        address fromAsset = params.fromWrapper.underlyingAsset();
        address toAsset = params.toWrapper.underlyingAsset();

        uint256 outputAmount = executeSwap(
            fromAsset,
            toAsset,
            params.fromAmount,
            params.swapData
        );

        // 3. Deposit to destination position
        IERC20(toAsset).approve(address(params.toWrapper), outputAmount);
        vault.locked_depositToWrapper(
            params.toWrapper,
            params.toPositionId,
            outputAmount
        );

        // Position health checked automatically
    }
}

function executeSwap(
    address tokenIn,
    address tokenOut,
    uint256 amountIn,
    bytes memory swapData
) internal returns (uint256 amountOut) {
    // Example: Uniswap V3 swap
    // Decode swapData for pool, slippage, etc.
    // Execute swap
    // Return amount received
}

Complex Multi-Protocol Strategy

Here's a real example of delta-neutral farming:

struct DeltaNeutralParams {
    uint256 usdcAmount;      // Amount to allocate
    uint256 wethToBuy;       // WETH to buy for hedge
    address curvePool;       // Curve pool to LP
    address uniV3Pool;       // Uniswap V3 pool for hedge
}

function executeDeltaNeutralStrategy(
    IFluxVault vault,
    DeltaNeutralParams memory params
) external {
    bytes memory data = abi.encode("DELTA_NEUTRAL", params);
    vault.unlock(data);
}

// In callback - all atomic, all in one transaction:
function fluxUnlockCallback(bytes calldata data) external {
    (string memory op, DeltaNeutralParams memory params) =
        abi.decode(data, (string, DeltaNeutralParams));

    if (keccak256(bytes(op)) == keccak256("DELTA_NEUTRAL")) {
        // 1. Withdraw USDC from working capital
        vault.locked_withdrawFromWrapper(
            baseAssetWrapper,
            WORKING_CAPITAL,
            params.usdcAmount
        );

        // 2. Buy WETH on Uniswap (half of USDC)
        uint256 halfUSDC = params.usdcAmount / 2;
        uint256 wethBought = swapUSDCForWETH(halfUSDC);

        // 3. Provide liquidity to Curve (USDC + WETH)
        uint256 lpTokens = addCurveLiquidity(
            params.curvePool,
            halfUSDC,
            wethBought
        );

        // 4. Deposit Curve LP tokens to wrapper
        vault.locked_depositToWrapper(
            curveLPWrapper,
            bytes32(0),
            lpTokens
        );

        // 5. Short WETH on another protocol to hedge
        // (This maintains delta-neutral exposure)
        openShortPosition(params.uniV3Pool, params.wethToBuy);

        // All done atomically!
        // If any step fails, entire transaction reverts
        // Health check at end ensures position is safe
    }
}

---

Managing Collateral

Add Collateral (Improve Health)

function addCollateral(IFluxVault vault, uint256 amount) external {
    bytes memory data = abi.encode("ADD_COLLATERAL", amount);
    vault.unlock(data);
}

// In callback:
function fluxUnlockCallback(bytes calldata data) external {
    (string memory op, uint256 amount) = abi.decode(data, (string, uint256));

    if (keccak256(bytes(op)) == keccak256("ADD_COLLATERAL")) {
        // Transfer bond to vault
        baseAsset.transferFrom(owner, address(this), amount);
        baseAsset.approve(address(vault), amount);

        vault.locked_depositBond(amount);

        // Health ratio improves:
        // New Health = (Old Bond + amount + other assets) / debt
    }
}

Remove Collateral (If Health Allows)

function removeCollateral(IFluxVault vault, uint256 amount) external {
    bytes memory data = abi.encode("REMOVE_COLLATERAL", amount);
    vault.unlock(data);
}

// In callback:
function fluxUnlockCallback(bytes calldata data) external {
    (string memory op, uint256 amount) = abi.decode(data, (string, uint256));

    if (keccak256(bytes(op)) == keccak256("REMOVE_COLLATERAL")) {
        vault.locked_withdrawBond(amount);
        // Bond sent to executor (this contract)

        // Transfer to owner
        baseAsset.transfer(owner, amount);

        // Health check ensures you still have enough collateral
    }
}

---

Repaying Debt

Partial Repayment

function repayDebt(IFluxVault vault, uint256 amount) external {
    bytes memory data = abi.encode("REPAY", amount);
    vault.unlock(data);
}

// In callback:
function fluxUnlockCallback(bytes calldata data) external {
    (string memory op, uint256 amount) = abi.decode(data, (string, uint256));

    if (keccak256(bytes(op)) == keccak256("REPAY")) {
        // Transfer repayment amount to executor
        baseAsset.transferFrom(owner, address(this), amount);
        baseAsset.approve(address(vault), amount);

        vault.locked_repay(amount);

        // Debt reduced, health improves
    }
}

Full Exit

function fullExit(IFluxVault vault) external {
    bytes memory data = abi.encode("FULL_EXIT");
    vault.unlock(data);
}

// In callback:
function fluxUnlockCallback(bytes calldata data) external {
    string memory op = abi.decode(data, (string));

    if (keccak256(bytes(op)) == keccak256("FULL_EXIT")) {
        // 1. Withdraw all assets back to base asset
        IAsset[] memory wrappers = vault.getRegisteredWrappers(address(this));

        for (uint i = 0; i < wrappers.length; i++) {
            // Withdraw everything from this wrapper
            vault.locked_withdrawFromWrapper(
                wrappers[i],
                bytes32(0),
                type(uint256).max
            );

            // Swap back to base asset
            // ... swap logic ...
        }

        // 2. Get working capital
        vault.locked_withdrawFromWrapper(
            baseAssetWrapper,
            WORKING_CAPITAL,
            type(uint256).max
        );

        // 3. Repay all debt
        uint256 debt = vault.getManagerTrueDebt(address(this));
        vault.locked_repay(debt);

        // 4. Withdraw bond
        vault.locked_withdrawBond(type(uint256).max);

        // Position fully closed
    }
}

---

Monitoring Position Health

Check Health Ratio

function checkHealth(IFluxVault vault, address manager) public view returns (
    uint256 healthRatio,
    bool isLiquidatable,
    uint256 bufferPercent
) {
    // Get position values
    uint256 totalValue = vault.getTotalPositionValue(manager);
    uint256 trueDebt = vault.getManagerTrueDebt(manager);

    // Calculate health
    healthRatio = (totalValue * 1e18) / trueDebt;

    // Check if liquidatable
    IStrategy strategy = vault.STRATEGY();
    uint256 liquidationThreshold = strategy.liquidationThreshold();

    isLiquidatable = healthRatio < liquidationThreshold;

    // Calculate buffer
    bufferPercent = ((healthRatio - liquidationThreshold) * 100e18) / liquidationThreshold;
}

Set Up Alerts

// Off-chain monitoring
async function monitorHealth(vault: string, manager: string) {
  const healthInfo = await vault.checkHealth(manager);

  if (healthInfo.healthRatio < LIQUIDATION_THRESHOLD) {
    // URGENT: Position liquidatable!
    await emergencyAddCollateral();
  } else if (healthInfo.bufferPercent < 5e18) {
    // WARNING: Less than 5% buffer
    alert("Health ratio low, consider adding collateral");
  }
}

// Run every minute
setInterval(() => monitorHealth(vaultAddress, managerAddress), 60000);

Calculate Interest Owed

function calculateInterest(IFluxVault vault, address manager) public view returns (
    uint256 principalDebt,
    uint256 accruedInterest,
    uint256 totalDebt
) {
    principalDebt = vault.managerPositions(manager).principalDebt;
    totalDebt = vault.getManagerTrueDebt(manager);
    accruedInterest = totalDebt - principalDebt;
}

---

Advanced Patterns

Leveraged Yield Farming

function leveragedFarm(
    IFluxVault vault,
    uint256 bondAmount,
    address yieldVault
) external {
    // Post bond, borrow 5x, farm with 6x capital
    bytes memory data = abi.encode("LEVERAGED_FARM", bondAmount, yieldVault);
    vault.unlock(data);
}

// In callback:
function fluxUnlockCallback(bytes calldata data) external {
    (string memory op, uint256 bondAmount, address yieldVault) =
        abi.decode(data, (string, uint256, address));

    if (keccak256(bytes(op)) == keccak256("LEVERAGED_FARM")) {
        // 1. Deposit bond
        vault.locked_depositBond(bondAmount);

        // 2. Borrow 5x bond
        uint256 borrowAmount = bondAmount * 5;
        vault.locked_borrow(borrowAmount);

        // 3. Withdraw total (bond + borrowed) from working capital
        uint256 totalCapital = bondAmount + borrowAmount;
        vault.locked_withdrawFromWrapper(
            baseAssetWrapper,
            WORKING_CAPITAL,
            totalCapital
        );

        // 4. Deposit everything to yield vault
        IERC20(baseAsset).approve(yieldVault, totalCapital);
        uint256 shares = IERC4626(yieldVault).deposit(totalCapital, address(this));

        // 5. Deposit yield vault shares to wrapper
        vault.locked_depositToWrapper(
            yieldVaultWrapper,
            bytes32(0),
            shares
        );

        // Now earning yield on 6x capital!
    }
}

Cross-Protocol Arbitrage

function arbitrage(
    IFluxVault vault,
    address tokenA,
    address tokenB,
    address dexA,
    address dexB
) external {
    bytes memory data = abi.encode("ARBITRAGE", tokenA, tokenB, dexA, dexB);
    vault.unlock(data);
}

// In callback:
function fluxUnlockCallback(bytes calldata data) external {
    (string memory op, address tokenA, address tokenB, address dexA, address dexB) =
        abi.decode(data, (string, address, address, address, address));

    if (keccak256(bytes(op)) == keccak256("ARBITRAGE")) {
        // 1. Borrow working capital
        uint256 capital = vault.getWorkingCapital(address(this));
        vault.locked_withdrawFromWrapper(baseAssetWrapper, WORKING_CAPITAL, capital);

        // 2. Buy tokenA on dexA
        uint256 tokenAAmount = buyOnDex(dexA, baseAsset, tokenA, capital);

        // 3. Sell tokenA on dexB for more than we paid
        uint256 profitableAmount = sellOnDex(dexB, tokenA, baseAsset, tokenAAmount);

        require(profitableAmount > capital, "Not profitable");

        // 4. Deposit back to working capital
        baseAsset.approve(address(baseAssetWrapper), profitableAmount);
        vault.locked_depositToWrapper(baseAssetWrapper, WORKING_CAPITAL, profitableAmount);

        // Profit = profitableAmount - capital
    }
}

---

Best Practices

1. Always Monitor Health

// Set up off-chain monitoring
contract HealthMonitor {
    event HealthLow(address indexed vault, address indexed manager, uint256 healthRatio);

    function checkAndAlert(IFluxVault vault, address manager) external {
        uint256 healthRatio = getHealthRatio(vault, manager);
        uint256 threshold = vault.STRATEGY().liquidationThreshold();

        if (healthRatio < threshold * 1.05) { // 5% buffer
            emit HealthLow(address(vault), manager, healthRatio);
        }
    }
}

2. Use Slippage Protection

// Always check output amounts
function swapWithSlippage(
    address tokenIn,
    address tokenOut,
    uint256 amountIn,
    uint256 minAmountOut
) internal returns (uint256 amountOut) {
    amountOut = executeSwap(tokenIn, tokenOut, amountIn);
    require(amountOut >= minAmountOut, "Slippage too high");
}

3. Handle Callback Failures Gracefully

function safeUnlock(IFluxVault vault, bytes memory data) external {
    try vault.unlock(data) {
        // Success
    } catch Error(string memory reason) {
        // Handle revert reason
        handleFailure(reason);
    } catch {
        // Handle unknown error
        revert("Unlock failed");
    }
}

4. Test with Small Amounts First

// Start with minimal leverage
uint256 minBond = 1000e6; // $1000
uint256 minBorrow = 4000e6; // $4000 (4x leverage)

// Test the full flow
testFullCycle(vault, minBond, minBorrow);

// Then scale up

5. Maintain Health Buffer

// Don't max out borrowing capacity
function conservativeBorrow(IFluxVault vault, uint256 bondAmount) external {
    IStrategy strategy = vault.STRATEGY();
    uint256 minBondRatio = strategy.minBondRatio();

    // Borrow only 80% of max
    uint256 maxBorrow = (bondAmount * 1e18) / minBondRatio;
    uint256 safeBorrow = (maxBorrow * 80) / 100;

    vault.locked_borrow(safeBorrow);
}

---

Risk Management

Interest Cost Tracking

function shouldRepay(IFluxVault vault, address manager) public view returns (bool) {
    // Get interest rate
    uint256 annualRate = vault.STRATEGY().annualRate();

    // Calculate daily interest cost
    uint256 debt = vault.getManagerTrueDebt(manager);
    uint256 dailyInterest = (debt * annualRate) / (365 * 1e18);

    // Compare to expected daily yield from strategy
    uint256 expectedYield = calculateExpectedDailyYield(manager);

    // Repay if interest exceeds yield
    return dailyInterest > expectedYield;
}

Position Sizing

function calculateOptimalLeverage(
    uint256 bondAmount,
    uint256 expectedYieldAPR,
    uint256 borrowCostAPR
) public pure returns (uint256 optimalLeverage) {
    // Optimal leverage = (expectedYield - borrowCost) / riskTolerance
    if (expectedYieldAPR <= borrowCostAPR) {
        return 1e18; // No leverage if not profitable
    }

    uint256 spreadAPR = expectedYieldAPR - borrowCostAPR;

    // Conservative: 2-3x
    // Moderate: 3-5x
    // Aggressive: 5-10x

    // Example: 2x leverage for conservative
    optimalLeverage = 2e18;
}

Read more about managing risk as a manager.

---

Complete Manager Integration Example

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

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

contract FluxManagerIntegration is IFluxUnlockCallback {
    address public immutable owner;
    IFluxVault public vault;
    IERC20 public baseAsset;

    enum Operation {
        BORROW,
        REPAY,
        TRADE,
        ADD_COLLATERAL,
        EXIT
    }

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

    modifier onlyOwner() {
        require(msg.sender == owner, "Not owner");
        _;
    }

    // Initial borrow
    function borrow(uint256 bondAmount, uint256 borrowAmount) external onlyOwner {
        bytes memory data = abi.encode(Operation.BORROW, bondAmount, borrowAmount);
        vault.unlock(data);
    }

    // Callback handler
    function fluxUnlockCallback(bytes calldata data) external override {
        require(msg.sender == address(vault), "Only vault");

        (Operation op, ) = abi.decode(data, (Operation, bytes));

        if (op == Operation.BORROW) {
            _handleBorrow(data);
        } else if (op == Operation.REPAY) {
            _handleRepay(data);
        } else if (op == Operation.TRADE) {
            _handleTrade(data);
        } else if (op == Operation.ADD_COLLATERAL) {
            _handleAddCollateral(data);
        } else if (op == Operation.EXIT) {
            _handleExit(data);
        }
    }

    function _handleBorrow(bytes calldata data) internal {
        (, uint256 bondAmount, uint256 borrowAmount) =
            abi.decode(data, (Operation, uint256, uint256));

        // Deposit bond
        baseAsset.transferFrom(owner, address(this), bondAmount);
        baseAsset.approve(address(vault), bondAmount);
        vault.locked_depositBond(bondAmount);

        // Borrow capital
        vault.locked_borrow(borrowAmount);
    }

    function _handleRepay(bytes calldata data) internal {
        (, uint256 amount) = abi.decode(data, (Operation, uint256));

        baseAsset.transferFrom(owner, address(this), amount);
        baseAsset.approve(address(vault), amount);
        vault.locked_repay(amount);
    }

    function _handleTrade(bytes calldata data) internal {
        // Implement trade logic
    }

    function _handleAddCollateral(bytes calldata data) internal {
        (, uint256 amount) = abi.decode(data, (Operation, uint256));

        baseAsset.transferFrom(owner, address(this), amount);
        baseAsset.approve(address(vault), amount);
        vault.locked_depositBond(amount);
    }

    function _handleExit(bytes calldata data) internal {
        // Close all positions and exit
    }

    // View functions
    function getHealthRatio() public view returns (uint256) {
        uint256 totalValue = vault.getTotalPositionValue(address(this));
        uint256 debt = vault.getManagerTrueDebt(address(this));

        return (totalValue * 1e18) / debt;
    }

    function isHealthy() public view returns (bool) {
        uint256 healthRatio = getHealthRatio();
        uint256 threshold = vault.STRATEGY().liquidationThreshold();

        return healthRatio >= threshold;
    }
}

Learn More

• Vault Concepts

• Asset Wrappers

• Liquidation Protection