Quickstart

This guide will help you quickly get started with Flux Protocol, whether you're a liquidity provider, manager, liquidator, or vault creator.

Choose Your Role

Select the path that matches your use case:

I want to provide liquidity

Earn yield by depositing assets into Flux vaults

I want to borrow and trade

Access leveraged capital to trade diverse assets

I want to run a liquidation bot

Earn profits by liquidating unhealthy positions

I want to create a vault

Deploy and manage your own lending vault

---

For Liquidity Providers

1. Find a Vault

Browse available vaults:

• Visit the Flux app (link TBD)

• Check vault parameters (interest rate, strategy, TVL)

• Review vault creator and strategy safety

2. Deposit Assets

// Approve vault to spend your tokens
IERC20(baseAsset).approve(address(vault), depositAmount);

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

3. Monitor Your Position

• Track share value over time

• Monitor vault utilization

• Check accrued interest

4. Withdraw

Standard Withdrawal (if liquidity available):

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

Queued Withdrawal (if vault fully utilized):

// Queue withdrawal
uint256 requestId = vault.queueWithdrawal(shares);

// Claim later when liquidity available
vault.claimWithdrawals([requestId]);

Emergency Withdrawal (force liquidate manager):

vault.withdrawWithPenalty(
    shares,
    managerToLiquidate,
    assetIndices,
    liquidationPercentages,
    minAmountOut
);

---

For Managers

1. Register an Executor

Before borrowing, deploy and register an executor:

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

// Option 2: Register custom executor
factory.registerExecutor(msg.sender, customExecutorAddress);

2. Find a Vault

Choose a vault based on:

• Base asset (USDC, WETH, etc.)

• Interest rate

• Allowed asset wrappers

• Liquidation parameters

3. Borrow Capital

// Prepare bond and borrow via unlock callback
vault.unlock(abi.encode(borrowAmount, bondAmount));

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

    // Deposit bond
    vault.locked_depositBond(bondAmount);

    // Borrow capital
    vault.locked_borrow(borrowAmount);

    // Now you have capital in working capital position
}

4. Trade Assets

// Register asset wrapper
vault.locked_registerWrapper(wethWrapper);

// Withdraw USDC from working capital
vault.locked_withdrawFromWrapper(
    baseAssetWrapper,
    WORKING_CAPITAL,
    amountToTrade
);

// Swap USDC → WETH (off-chain)
// ... swap logic ...

// Deposit WETH to wrapper
WETH.approve(wethWrapper, wethAmount);
vault.locked_depositToWrapper(wethWrapper, bytes32(0), wethAmount);

// Position health checked automatically at end of callback

5. Monitor Health

// Check your health ratio
uint256 healthRatio = lens.getHealthRatio(vault, manager);

// healthRatio >= 1.1e18 → Healthy
// healthRatio < 1.1e18 → Liquidatable!

// Add collateral if needed
vault.unlock(addCollateralData);
// Inside callback:
vault.locked_depositBond(additionalBond);

6. Repay and Exit

// Inside unlock callback:

// Withdraw all assets back to working capital
vault.locked_withdrawFromWrapper(wethWrapper, positionId, type(uint256).max);

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

// Repay debt
vault.locked_repay(debtAmount);

// Withdraw bond
vault.locked_withdrawBond(bondAmount);

Next Steps

📖 Read: Manager Integration Guide 🎓 Learn: Position Management ⚠️ Understand: Risk Management

---

For Liquidators

1. Monitor Positions

Set up monitoring to detect liquidatable positions:

// Check all managers in a vault
const managers = await getAllManagers(vault);

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

  if (canLiquidate) {
    const profit = await estimateProfit(manager, minPayment);

    if (profit > gasCost) {
      await liquidate(vault, manager);
    }
  }
}

2. Execute Liquidation

// Prepare liquidation data
bytes memory liquidationData = prepareLiquidationData(manager);

// Call liquidate
vault.liquidate(manager, additionalWrappers, liquidationData);

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

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

    // 3. Extract collateral (auto-transferred by vault)
    vault.locked_withdrawFromWrapper(wrapper, positionId, type(uint256).max);

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

    // 5. Repay borrowed amount
    vault.locked_repay(minPayment);

    // 6. Keep profit!
}

3. Optimize Strategy

• Batch liquidations: Process multiple managers per transaction

• Gas optimization: Use efficient swap routes

• MEV protection: Use Flashbots/private mempools

• Profit calculation: Account for gas and slippage

Next Steps

Read: Liquidator Bot Guide Learn: Profit Optimization

---

For Vault Creators (Curators)

1. Choose Strategy

Deploy a strategy via StrategyFactory:

// Immutable strategy (no governance risk)
address strategy = strategyFactory.deployImmutableStrategy(
    allowedAssets,  // Array of wrapper addresses
    StrategyParams({
        minBondRatio: 0.2e18,            // 20% bond required
        liquidationBuffer: 0.1e18,        // 10% buffer
        annualRate: 0.1e18,               // 10% APR
        curatorFeeRate: 1000,             // 10% curator fee
        liquidationProfitMargin: 0.01e18  // 1% liquidator profit
    })
);

// OR mutable strategy (7-day timelock)
address strategy = strategyFactory.deployMutableStrategy(
    initialAssets,
    params,
    owner
);

2. Choose Access Policy

// Option 1: Permissionless (anyone can deposit/borrow)
IAccessPolicy policy = IAccessPolicy(address(0));

// Option 2: Whitelist (restricted access)
WhitelistAccessPolicy policy = new WhitelistAccessPolicy(owner);
policy.setWhitelistedLP(lpAddress, true);
policy.setWhitelistedManager(managerAddress, true);

3. Create Vault

address vault = fluxVaultFactory.createVault(
    IERC20(USDC),              // Base asset
    baseAssetWrapper,          // Wrapper for USDC
    IStrategy(strategy),       // Strategy from step 1
    policy,                    // Access policy
    "My Flux Vault",           // Vault name
    "MFV"                      // Share symbol
);

4. Manage Vault

• Monitor vault health and utilization

• Collect creator fees: vault.transferCreatorFees()

• Update parameters (if using mutable strategy)

• Communicate with LPs about strategy

Next Steps

Read: Creating a Vault 🎯 Learn: Strategy Selection Understand: Risk Management

---

Common Operations

Query Vault Information

// Get vault stats
uint256 totalAssets = vault.totalAssets();
uint256 totalShares = vault.totalSupply();
uint256 sharePrice = vault.convertToAssets(1e18);  // Price of 1 share

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

Query Manager Position

// Get manager details via lens
ManagerDetails memory details = lens.getManagerDetails(vault, manager);

console.log("Principal Debt:", details.principalDebt);
console.log("True Debt:", details.trueDebt);
console.log("Bond Value:", details.bondValue);
console.log("Total Collateral:", details.totalCollateralValue);
console.log("Health Ratio:", details.health);
console.log("Can Liquidate:", details.canLiquidate);

Calculate Interest

// Get projected LP index (includes accrued interest)
(uint256 newIndex,,,,) = vault.getProjectedLpIndex();

// Calculate manager's true debt
uint256 principalDebt = vault.managerPositions(manager).principalDebt;
uint256 lastSnapshot = vault.managerPositions(manager).lastLpIndexSnapshot;
uint256 trueDebt = (principalDebt * newIndex) / lastSnapshot;

// Interest owed
uint256 interest = trueDebt - principalDebt;

---

Development Setup

Install Dependencies

# Clone repository
git clone https://github.com/nexus-labs/flux-v1-contracts
cd flux-v1-contracts

# Install Foundry dependencies
forge install

# Build contracts
forge build

# Run tests
forge test

Deploy Locally

# Start local node
anvil

# Deploy contracts
forge script script/Deploy.s.sol --broadcast --rpc-url localhost

Integration Testing

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

contract MyIntegration {
    IFluxVault public vault;

    function deposit(uint256 amount) external {
        // Your integration logic
        vault.deposit(amount, msg.sender);
    }
}

Testnet Deployment

Flux is deployed on the following testnets:

• Sepolia: 0x... (coming soon)

• Base Sepolia: 0x... (coming soon)

See Contract Addresses for full list.

---

Additional Resources

Tools

• Flux App: app.useflux.xyz (coming soon)

• Analytics: Dune dashboards (coming soon)

• SDK: JavaScript/TypeScript SDK (coming soon)

Community

• Discord: Join our community (link TBD)

• GitHub: nexus-labs/flux-v1-contracts

• Twitter: @usefluxdotxyz