> For the complete documentation index, see [llms.txt](https://docs.useflux.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.useflux.xyz/build/quickstart.md).

# 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](#for-liquidity-providers)

Earn yield by depositing assets into Flux vaults

#### [I want to borrow and trade](/build/quickstart.md#for-managers)

Access leveraged capital to trade diverse assets

#### [I want to run a liquidation bot](https://github.com/nexuslabsdev/flux-v1-contracts/blob/41f3a7cd3a69a78e3f9999fa7acb8bc53ae4e5e6/docs/build/QUICK_START.md#for-liquidators)

Earn profits by liquidating unhealthy positions

#### [I want to create a vault](/build/quickstart.md#for-vault-creators)

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](/build/managers/integration-guide.md) Learn: [Position Management](/build/managers/position-management.md) Understand: [Risk Management](/build/managers/risk-management.md)

***

### 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](/build/liquidators/liquidator-bot-guide.md) Learn: [Profit Optimization](/build/liquidators/profit-optimization.md)

***

### 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](/curate/vault-creation/creating-a-vault.md) Learn: [Strategy Selection](/curate/vault-creation/choosing-a-strategy.md) Understand: [Risk Management](/curate/risk-management/understanding-vault-risks.md)

***

### 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](/resources/addresses.md) 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](https://github.com/nexus-labs/flux-v1-contracts)
* **Twitter**: [@usefluxdotxyz](https://x.com/usefluxdotxyz)