Interface Reference

Complete API documentation for all Flux Protocol contract interfaces.

Table of Contents

• IFluxVault - Core vault interface

• IAsset - Asset wrapper interface

• IStrategy - Strategy interface

• IFluxVaultFactory - Factory interface

• IFluxVaultLens - Read-only lens

• IOracleRegistry - Oracle interface

---

IFluxVault

The core vault contract implementing ERC4626 with position management.

Inherits: IERC4626

Location: src/interfaces/IFluxVault.sol

Main Entry Points

unlock(bytes calldata data)

Triggers the unlock callback for manager to execute strategy.

function unlock(bytes calldata data) external;

Parameters:

• data: Arbitrary data passed to executor's fluxUnlockCallback

Access: Anyone (but requires registered executor)

Flow:

1. Accrue interest

2. Verify caller has registered executor

3. Set lock to caller

4. Call executor's fluxUnlockCallback(data)

5. Verify position health after callback

6. Release lock

Example:

// Manager opens position
vault.unlock(abi.encodeCall(executor.createPosition, (borrowAmount, bondAmount)));

// Manager closes position
vault.unlock(abi.encodeCall(executor.closePosition, ()));

Reverts:

• NoExecutorRegistered() - Caller hasn't registered executor

• PositionNotHealthy() - Position unhealthy after callback

---

liquidate(address manager, IAsset[] calldata additionalWrappers, bytes calldata data)

Liquidate an unhealthy manager position.

function liquidate(
    address manager,
    IAsset[] calldata additionalWrappers,
    bytes calldata data
) external;

Parameters:

• manager: Address of manager to liquidate

• additionalWrappers: Extra wrappers that may hold positions

• data: Arbitrary data for liquidator's callback

Access: Anyone (permissionless)

Flow:

1. Accrue interest

2. Verify position is liquidatable

3. Transfer all manager positions to liquidator

4. Call liquidator's fluxUnlockCallback with (minPayment, trueDebt, data)

5. Verify liquidator prepared minimum payment

6. Take payment, record any bad debt

7. Delete manager position

Example:

// Simple liquidation
vault.liquidate(unhealthyManager, new IAsset[](0), "");

// With additional wrappers
IAsset[] memory wrappers = new IAsset[](1);
wrappers[0] = customWrapper;
vault.liquidate(manager, wrappers, abi.encode("liquidation_data"));

Reverts:

• PositionNotActive() - Manager has no position

• PositionNotLiquidatable() - Position is healthy

• InsufficientPayment() - Liquidator didn't prepare enough

---

Locked Operations

Called only during unlock/liquidation callback (when vault lock is held).

locked_borrow(uint256 amount)

Borrow capital from vault.

function locked_borrow(uint256 amount) external;

Parameters:

• amount: Amount to borrow in base asset

Access: Lock holder only

Effects:

• Increases manager's principal debt

• Deposits borrowed amount to manager's working capital (base wrapper)

• Emits Borrowed(manager, amount, newDebt)

Example:

// In unlock callback
function fluxUnlockCallback(bytes calldata data) external {
    vault.locked_borrow(100_000e18);  // Borrow 100K
    // Use borrowed capital...
}

Reverts:

• InsufficientIdleLiquidity() - Vault doesn't have enough liquidity

---

locked_repay(uint256 amount)

Repay borrowed capital.

function locked_repay(uint256 amount) external;

Parameters:

• amount: Amount to repay in base asset

Access: Lock holder only

Effects:

• Withdraws from manager's working capital (base wrapper)

• Reduces manager's principal debt

• Emits Repaid(manager, amount, remainingDebt)

Example:

// Repay full debt
uint256 debt = vault.getManagerTrueDebt(lockHolder);
vault.locked_repay(debt);

// Partial repay
vault.locked_repay(50_000e18);

---

locked_depositBond(uint256 amount)

Post bond collateral.

function locked_depositBond(uint256 amount) external;

Parameters:

• amount: Amount of base asset to post as bond

Access: Lock holder only

Effects:

• Transfers base asset from caller

• Deposits to manager's bond position (base wrapper)

• Updates manager's bond balance

Example:

// Post 20K bond
asset.approve(address(vault), 20_000e18);
vault.locked_depositBond(20_000e18);

---

locked_withdrawBond(uint256 amount)

Withdraw bond collateral.

function locked_withdrawBond(uint256 amount) external;

Parameters:

• amount: Amount to withdraw

Access: Lock holder only

Constraints:

• Can only withdraw if position remains healthy

• Bond ratio must stay above minimum

Example:

// Withdraw excess bond
uint256 bondBalance = vault.getBondBalance(manager);
vault.locked_withdrawBond(5_000e18);

---

locked_registerWrapper(address wrapper)

Register an asset wrapper for use.

function locked_registerWrapper(address wrapper) external;

Parameters:

• wrapper: Address of wrapper contract

Access: Lock holder only

Constraints:

• Wrapper must be whitelisted by factory

• Wrapper must be allowed in vault's strategy

• Cannot register same wrapper twice

Example:

// Register WETH wrapper
vault.locked_registerWrapper(wethWrapperAddress);

// Now can deposit WETH
vault.locked_depositToWrapper(IAsset(wethWrapperAddress), posId, amount);

Reverts:

• WrapperNotWhitelisted() - Wrapper not approved by governance

• WrapperNotAllowed() - Strategy doesn't allow this wrapper

• WrapperAlreadyRegistered() - Already registered

---

locked_depositToWrapper(IAsset wrapper, bytes32 positionId, uint256 amount)

Deposit assets into a wrapper position.

function locked_depositToWrapper(
    IAsset wrapper,
    bytes32 positionId,
    uint256 amount
) external;

Parameters:

• wrapper: Wrapper contract address

• positionId: Position identifier (use bytes32(0) for working capital)

• amount: Amount to deposit

Access: Lock holder only

Flow:

1. Approve wrapper to spend tokens

2. Call wrapper.deposit(vault, manager, positionId, amount)

Example:

// Deposit to working capital
vault.locked_depositToWrapper(
    wethWrapper,
    bytes32(0),  // WORKING_CAPITAL
    10e18       // 10 WETH
);

// Deposit to custom position
vault.locked_depositToWrapper(
    uniV3Wrapper,
    bytes32(uint256(positionId)),
    1  // NFT
);

---

locked_withdrawFromWrapper(IAsset wrapper, bytes32 positionId, uint256 amount)

Withdraw assets from wrapper position.

function locked_withdrawFromWrapper(
    IAsset wrapper,
    bytes32 positionId,
    uint256 amount
) external;

Parameters:

• wrapper: Wrapper contract address

• positionId: Position identifier

• amount: Amount to withdraw (type(uint256).max for all)

Access: Lock holder only

Effects:

• Calls wrapper.withdraw(vault, manager, positionId, recipient, amount)

• Assets sent to lock holder

Example:

// Withdraw all from working capital
vault.locked_withdrawFromWrapper(
    wethWrapper,
    bytes32(0),
    type(uint256).max
);

// Withdraw specific amount
vault.locked_withdrawFromWrapper(
    wbtcWrapper,
    bytes32(0),
    5e8  // 5 WBTC
);

---

locked_claimFromWrapper(IAsset wrapper, bytes32 positionId, uint256 amountOrTokenId)

Claim pre-received assets.

function locked_claimFromWrapper(
    IAsset wrapper,
    bytes32 positionId,
    uint256 amountOrTokenId
) external;

Use Case: Claim airdrops, rewards, or assets already sent to wrapper

Example:

// Claim airdropped tokens
vault.locked_claimFromWrapper(tokenWrapper, bytes32(0), 1000e18);

---

locked_interactWithWrapper(address wrapper, bytes calldata data)

Call arbitrary function on wrapper.

function locked_interactWithWrapper(
    address wrapper,
    bytes calldata data
) external returns (bytes memory);

Parameters:

• wrapper: Wrapper address

• data: Encoded function call

Use Case: Advanced wrapper interactions (staking, voting, etc.)

Example:

// Stake via wrapper
bytes memory data = abi.encodeCall(
    stakingWrapper.stake,
    (amount, duration)
);
vault.locked_interactWithWrapper(address(stakingWrapper), data);

---

View Functions - Vault/LP

getIdleLiquidity()

Get available liquidity for borrowing.

function getIdleLiquidity() external view returns (uint256);

Returns: Amount of base asset in vault (not borrowed)

Example:

const idle = await vault.getIdleLiquidity();
console.log(`Available to borrow: ${idle / 1e18}`);

---

getProjectedLpIndex()

Calculate current LP index including accrued interest.

function getProjectedLpIndex() external view returns (
    uint256 newIndex,
    uint256 totalGrowth,
    uint256 protocolCut,
    uint256 protocolFeeEarned,
    uint256 creatorCut,
    uint256 creatorFeeEarned
);

Returns:

• newIndex: Projected LP index (1e18 scale)

• totalGrowth: Total interest growth since last checkpoint

• protocolCut: Protocol's share of growth

• protocolFeeEarned: Protocol fee in asset terms

• creatorCut: Creator's share of growth

• creatorFeeEarned: Creator fee in asset terms

Example:

const { newIndex, protocolFeeEarned, creatorFeeEarned } =
    await vault.getProjectedLpIndex();

const totalFees = protocolFeeEarned + creatorFeeEarned;
console.log(`Accrued fees: ${totalFees / 1e18}`);

---

View Functions - Manager/Position

getManagerTrueDebt(address manager)

Get manager's current debt including accrued interest.

function getManagerTrueDebt(address manager) external view returns (uint256);

Returns: Current debt in base asset

Formula: principalDebt * currentLpIndex / snapshotLpIndex

Example:

const debt = await vault.getManagerTrueDebt(managerAddress);
console.log(`Manager owes: ${debt / 1e18} USDC`);

---

getManagerPosition(address manager)

Get manager's position details.

function getManagerPosition(address manager) external view returns (
    uint256 principalDebt,
    uint256 bondAmount,
    uint256 lastLpIndexSnapshot
);

Returns:

• principalDebt: Original borrowed amount

• bondAmount: Bond balance (in base wrapper)

• lastLpIndexSnapshot: LP index when position was created/updated

Example:

(uint256 principal, uint256 bond, uint256 snapshot) =
    vault.getManagerPosition(manager);

// Calculate accrued interest
uint256 currentIndex = vault.lastLpIndex();
uint256 trueDebt = principal * currentIndex / snapshot;
uint256 interest = trueDebt - principal;

---

getBondBalance(address manager)

Get manager's bond amount (in base wrapper).

function getBondBalance(address manager) external view returns (uint256);

Example:

const bond = await vault.getBondBalance(manager);
const minRequired = await strategy.minBondRatio() * debt / 1e18;
console.log(`Has bond: ${bond / 1e18}, needs: ${minRequired / 1e18}`);

---

getWorkingCapital(address manager)

Get manager's working capital (in base wrapper).

function getWorkingCapital(address manager) external view returns (uint256);

Use: Check how much base asset manager can use for operations

---

getRegisteredWrappers(address manager)

Get all wrappers registered by manager.

function getRegisteredWrappers(address manager)
    external view returns (IAsset[] memory);

Example:

const wrappers = await vault.getRegisteredWrappers(manager);
for (const wrapper of wrappers) {
    const value = await wrapper.getValue(vault, manager, WORKING_CAPITAL);
    console.log(`Wrapper ${wrapper}: $${value / 1e18}`);
}

---

isPositionHealthy(address manager)

Quick check if position is healthy.

function isPositionHealthy(address manager) external view returns (bool);

Returns: true if health ratio >= liquidation threshold

Example:

const healthy = await vault.isPositionHealthy(manager);
if (!healthy) {
    console.log('Position can be liquidated!');
}

---

Immutable Constants

STRATEGY()

function STRATEGY() external view returns (IStrategy);

Returns vault's strategy contract (immutable).

---

FACTORY()

function FACTORY() external view returns (IFluxVaultFactory);

Returns factory that deployed this vault (immutable).

---

BASE_ASSET_WRAPPER()

function BASE_ASSET_WRAPPER() external view returns (IAsset);

Returns wrapper for vault's base asset (immutable).

---

VAULT_CREATOR()

function VAULT_CREATOR() external view returns (address);

Returns address that created the vault (immutable).

---

ERC4626 Functions

Flux vaults implement standard ERC4626:

// Standard ERC4626
function deposit(uint256 assets, address receiver) external returns (uint256 shares);
function mint(uint256 shares, address receiver) external returns (uint256 assets);
function withdraw(uint256 assets, address receiver, address owner) external returns (uint256 shares);
function redeem(uint256 shares, address receiver, address owner) external returns (uint256 assets);

// View functions
function totalAssets() external view returns (uint256);
function convertToShares(uint256 assets) external view returns (uint256);
function convertToAssets(uint256 shares) external view returns (uint256);
function previewDeposit(uint256 assets) external view returns (uint256);
function previewMint(uint256 shares) external view returns (uint256);
function previewWithdraw(uint256 assets) external view returns (uint256);
function previewRedeem(uint256 shares) external view returns (uint256);
function maxDeposit(address) external view returns (uint256);
function maxMint(address) external view returns (uint256);
function maxWithdraw(address owner) external view returns (uint256);
function maxRedeem(address owner) external view returns (uint256);

See ERC4626 Specification for details.

---

IAsset

Universal interface for asset wrappers.

Location: src/interfaces/IAsset.sol

Three-Layer Position Model

Positions are identified by three components:

account (address) → subaccount (address) → positionId (bytes32)

Example:

Vault Address → Manager Address → WORKING_CAPITAL (0x00)
Vault Address → Manager Address → BOND (0x01)
Vault Address → Manager Address → Custom Position (any bytes32)

Core Functions

deposit(address account, address subaccount, bytes32 positionId, uint256 amount)

Deposit assets into position.

function deposit(
    address account,
    address subaccount,
    bytes32 positionId,
    uint256 amount
) external;

Parameters:

• account: Main account (typically vault address)

• subaccount: Subaccount (typically manager address)

• positionId: Position identifier

• amount: Amount to deposit

Access: Typically vault only

Example:

// Vault deposits to manager's working capital
IERC20(underlying).approve(wrapper, amount);
wrapper.deposit(
    address(this),  // account = vault
    manager,        // subaccount = manager
    bytes32(0),     // positionId = WORKING_CAPITAL
    amount
);

---

withdraw(address account, address subaccount, bytes32 positionId, address recipient, uint256 amount)

Withdraw assets from position.

function withdraw(
    address account,
    address subaccount,
    bytes32 positionId,
    address recipient,
    uint256 amount
) external;

Parameters:

• account: Account to withdraw from

• subaccount: Subaccount to withdraw from

• positionId: Position to withdraw from

• recipient: Address to receive assets

• amount: Amount to withdraw (type(uint256).max for all)

Example:

// Withdraw all from position
wrapper.withdraw(
    vault,
    manager,
    bytes32(0),
    manager,  // Send to manager
    type(uint256).max
);

---

getValue(address account, address subaccount, bytes32 positionId)

Get USD value of position.

function getValue(
    address account,
    address subaccount,
    bytes32 positionId
) external view returns (uint256 value);

Returns: Value in USD with 18 decimals

Implementation: Calls oracle to convert balance to USD

Example:

const value = await wrapper.getValue(vault, manager, WORKING_CAPITAL);
console.log(`Position value: $${value / 1e18}`);

---

getBalance(address account, address subaccount, bytes32 positionId)

Get actual balance held.

function getBalance(
    address account,
    address subaccount,
    bytes32 positionId
) external view returns (uint256 balance);

Returns: Balance in native asset units

Difference from getValue:

• getBalance: Raw balance (e.g., 10 WETH)

• getValue: USD value (e.g., $25,000)

---

underlyingAsset()

Get underlying ERC20 token.

function underlyingAsset() external view returns (address asset);

Example:

const underlying = await wrapper.underlyingAsset();
// underlying = WETH address

---

ledgerTransferSubaccount(address fromSubaccount, address toSubaccount)

Transfer entire subaccount (all positions).

function ledgerTransferSubaccount(
    address fromSubaccount,
    address toSubaccount
) external;

Use: Liquidations (transfer all manager positions to liquidator)

Access: Vault only

---

IStrategy

Strategy interface defining economic parameters and risk evaluation.

Location: src/interfaces/IStrategy.sol

Risk Evaluation

evaluateLiquidation(address vault, address manager)

Check if position can be liquidated.

function evaluateLiquidation(address vault, address manager)
    external view returns (
        bool canLiquidate,
        uint256 minPayment,
        OraclePrice[] memory oraclePrices
    );

Returns:

• canLiquidate: Whether position is unhealthy

• minPayment: Minimum payment liquidator must provide

• oraclePrices: Oracle prices used (for event logging)

Example:

const { canLiquidate, minPayment } =
    await strategy.evaluateLiquidation(vault, manager);

if (canLiquidate) {
    console.log(`Liquidatable! Min payment: ${minPayment / 1e18}`);
    await vault.liquidate(manager, [], "0x");
}

---

evaluateADL(address vault, address manager)

Check if position can be ADL'd.

function evaluateADL(address vault, address manager)
    external view returns (
        bool canADL,
        uint256 managerNetEquityUSD
    );

Returns:

• canADL: Whether position is eligible for ADL

• managerNetEquityUSD: Manager's net equity to return

Example:

const { canADL, managerNetEquityUSD } =
    await strategy.evaluateADL(vault, manager);

if (canADL) {
    console.log(`ADL-able! Net equity: $${managerNetEquityUSD / 1e18}`);
}

---

Rate Parameters

annualRate()

function annualRate() external view returns (uint64);

Returns: Annual interest rate (18 decimals, e.g., 0.1e18 = 10%)

---

vaultCreatorFeeRate()

function vaultCreatorFeeRate() external view returns (uint16);

Returns: Creator fee in basis points (e.g., 1000 = 10%)

---

Risk Parameters

minBondRatio()

function minBondRatio() external view returns (uint64);

Returns: Minimum bond ratio (18 decimals, e.g., 0.2e18 = 20%)

---

liquidationThreshold()

function liquidationThreshold() external view returns (uint64);

Returns: Health ratio below which position is liquidatable (18 decimals)

Example: 1.1e18 = 110% (position liquidatable when health < 110%)

---

adlThreshold()

function adlThreshold() external view returns (uint64);

Returns: Health ratio below which position can be ADL'd (18 decimals)

Example: 1.2e18 = 120%

---

adlUtilizationThreshold()

function adlUtilizationThreshold() external view returns (uint64);

Returns: Vault utilization required for ADL (18 decimals)

Example: 0.95e18 = 95% utilization

---

isAssetAllowed(address wrapper)

function isAssetAllowed(address wrapper) external view returns (bool);

Returns: Whether wrapper can be used in this strategy

---

IFluxVaultFactory

Factory for deploying vaults and managing protocol.

Location: src/interfaces/IFluxVaultFactory.sol

Vault Creation

createVault(...)

function createVault(
    address asset,
    address baseAssetWrapper,
    address strategy,
    address accessPolicy,
    string memory name,
    string memory symbol
) external returns (address vault);

Parameters:

• asset: Base asset (USDC, WETH, etc.)

• baseAssetWrapper: Wrapper for base asset

• strategy: Strategy contract

• accessPolicy: Access control (address(0) = permissionless)

• name: Vault name

• symbol: Share symbol

Returns: Deployed vault address

---

Executor Management

deployWeirollExecutor()

function deployWeirollExecutor() external returns (address executor);

Returns: Deployed executor address (auto-registered to caller)

---

registerExecutor(address manager, address executor)

function registerExecutor(address manager, address executor) external;

Parameters:

• manager: Manager address

• executor: Executor contract address

---

getExecutor(address manager)

function getExecutor(address manager) external view returns (address);

Returns: Executor for given manager

---

Asset Whitelisting

whitelistAsset(address asset)

function whitelistAsset(address asset) external;

Access: Governance only

Effect: Approve wrapper for use in vaults

---

isAssetWhitelisted(address asset)

function isAssetWhitelisted(address asset) external view returns (bool);

Returns: Whether asset wrapper is whitelisted

---

Fee Management

protocolFeeRate()

function protocolFeeRate() external view returns (uint256);

Returns: Protocol fee in basis points

---

setProtocolFeeRate(uint256 newRate)

function setProtocolFeeRate(uint256 newRate) external;

Access: Governance only

Constraints: Max 10% (1000 bps)

---

IFluxVaultLens

Read-only aggregation contract for batch queries.

Location: src/interfaces/IFluxVaultLens.sol

Manager Queries

getManagerPositionValue(address vault, address manager)

Get total collateral value.

function getManagerPositionValue(address vault, address manager)
    external view returns (uint256 totalValue);

Returns: Total value in USD (18 decimals)

Aggregates:

• Bond value

• Working capital value

• All wrapper positions

Example:

const collateral = await lens.getManagerPositionValue(vault, manager);
const debt = await vault.getManagerTrueDebt(manager);
const health = collateral * 1e18 / debt;
console.log(`Health: ${health / 1e16}%`);

---

getManagerHealth(address vault, address manager)

Get health ratio.

function getManagerHealth(address vault, address manager)
    external view returns (uint256 health);

Returns: Health ratio (18 decimals, e.g., 1.5e18 = 150%)

---

getManagerDetails(address vault, address manager)

Get comprehensive position data.

function getManagerDetails(address vault, address manager)
    external view returns (ManagerDetails memory details);

Returns (ManagerDetails struct):

• Position data (debt, bond, timestamp)

• Collateral breakdown by wrapper

• Health ratio

• Liquidation status

• Wrapper addresses

Use: Single call to populate full UI

---

Vault Queries

getVaultStats(address vault)

Get vault overview.

function getVaultStats(address vault)
    external view returns (VaultStats memory stats);

Returns (VaultStats struct):

• Total assets

• Idle liquidity

• Utilization %

• Bad debt

• Share price

• LP index

• Interest accrued

---

Liquidation Preview

previewLiquidation(address vault, address manager)

Preview liquidation profitability.

function previewLiquidation(address vault, address manager)
    external view returns (LiquidationPreview memory preview);

Returns (LiquidationPreview struct):

• Can liquidate?

• Min payment required

• Estimated collateral seized

• Estimated profit

• Health ratio

Use: Liquidator bots to evaluate opportunities

---

IOracleRegistry

Centralized oracle system.

Location: src/interfaces/IOracleRegistry.sol

Price Queries

getValueUSD(address asset, uint256 amount)

Convert amount to USD value.

function getValueUSD(address asset, uint256 amount)
    external view returns (uint256 valueUSD);

Parameters:

• asset: Token address

• amount: Amount in token's decimals

Returns: Value in USD (18 decimals)

Example:

// Get value of 10 WETH
const value = await oracle.getValueUSD(WETH, ethers.parseEther("10"));
console.log(`10 WETH = $${value / 1e18}`);

---

getPrice(address asset)

Get price of 1 unit.

function getPrice(address asset) external view returns (uint256 price);

Returns: Price in USD (18 decimals) for 1 unit of asset

---

Oracle Management

addOracle(address asset, address feed)

Add price feed for asset.

function addOracle(address asset, address feed) external;

Access: Governance only

---

getLastUpdate(address asset)

Get timestamp of last oracle update.

function getLastUpdate(address asset) external view returns (uint256);

Use: Check oracle freshness

---

Summary

Key Interfaces:

Interface	Purpose	Main Functions
IFluxVault	Core vault operations	unlock, liquidate, locked_* operations
IAsset	Asset wrapper standard	deposit, withdraw, getValue
IStrategy	Risk parameters	evaluateLiquidation, evaluateADL, param getters
IFluxVaultFactory	Vault deployment	createVault, registerExecutor, whitelistAsset
IFluxVaultLens	Batch queries	getManagerDetails, getVaultStats, previewLiquidation
IOracleRegistry	Price feeds	getValueUSD, getPrice

ABI Locations:

• npm: @flux-protocol/contracts/abi/*.json

• GitHub: out/[Contract].sol/[Contract].json

• Block Explorer: Contract page → Download ABI

---

Related Documentation

• Event Reference

• Interface Reference

• Contract Addresses