Factories

Flux Protocol's factory system enables permissionless deployment of vaults, strategies, and asset wrappers. Anyone can create these components, fostering innovation while maintaining safety through validated parameters and governance whitelisting.

Overview

Flux has three main factories:

1. FluxVaultFactory: Deploy vaults, register executors, manage protocol fees

2. StrategyFactory: Deploy strategies (Immutable, Mutable, or Flexible Margin)

3. AssetWrapperFactory: Deploy vanilla ERC20/ERC4626 wrappers

┌─────────────────────────────────────────────────────────┐
│                    Flux Ecosystem                       │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌───────────────────┐      ┌──────────────────────┐  │
│  │ AssetWrapper      │      │ StrategyFactory      │  │
│  │ Factory           │      │                      │  │
│  ├───────────────────┤      ├──────────────────────┤  │
│  │ deployERC20()     │      │ deployImmutable()    │  │
│  │ deployERC4626()   │      │ deployMutable()      │  │
│  │                   │      │ deployFlexMargin()   │  │
│  └──────┬────────────┘      └────────┬─────────────┘  │
│         │                            │                 │
│         │ Wrappers            Strategies              │
│         │                            │                 │
│         └────────────┬───────────────┘                 │
│                      ▼                                 │
│         ┌─────────────────────────┐                   │
│         │ FluxVaultFactory        │                   │
│         ├─────────────────────────┤                   │
│         │ createVault()            │                   │
│         │ registerExecutor()       │                   │
│         │ whitelistAsset()         │◄─── Governance   │
│         │ setProtocolFeeRate()     │                   │
│         └──────────┬──────────────┘                   │
│                    │                                   │
│                    ▼                                   │
│           ┌────────────────┐                          │
│           │  Flux Vaults   │                          │
│           └────────────────┘                          │
└─────────────────────────────────────────────────────────┘

Key Principles:

• Permissionless deployment: Anyone can deploy components

• Parameter validation: Factories validate safety constraints

• Governance whitelisting: Protocol governance approves wrappers

• No upgrades: Deployed components are immutable (unless using Mutable strategy)

• Enumeration: All deployments tracked for discoverability

---

FluxVaultFactory

The central factory for creating vaults and managing protocol-level settings.

Core Responsibilities

1. Vault Creation: Deploy new ERC4626 vaults with custom strategies

2. Executor Registration: Register Weiroll executors for managers

3. Protocol Fees: Set and collect protocol fees across all vaults

4. Oracle Registry: Manage centralized oracle system

5. Asset Whitelisting: Governance approval of wrapper contracts

Interface

interface IFluxVaultFactory {
    // ========== Vault Creation ==========

    function createVault(
        address asset,            // Base asset (USDC, WETH, etc.)
        address baseAssetWrapper, // Wrapper for base asset
        address strategy,         // Strategy contract
        address accessPolicy,     // Access control (address(0) = permissionless)
        string memory name,       // Vault name
        string memory symbol      // Share symbol
    ) external returns (address vault);

    function createVaultWithDepositPolicy(
        address asset,
        address baseAssetWrapper,
        address strategy,
        address accessPolicy,
        GraduatedCapDepositPolicyTier[] memory tiers,
        uint256 minTotalAssets,
        string memory name,
        string memory symbol
    ) external returns (address vault, address policy);

    // ========== Executor Management ==========

    function deployWeirollExecutor() external returns (address executor);
    function registerExecutor(address manager, address executor) external;
    function getExecutor(address manager) external view returns (address);

    // ========== Asset Whitelisting (Governance Only) ==========

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

    // ========== Protocol Fees (Governance Only) ==========

    function protocolFeeRate() external view returns (uint256);
    function setProtocolFeeRate(uint256 newRate) external;
    function protocolFeeCollector() external view returns (address);
    function setProtocolFeeCollector(address collector) external;
    function collectFeesFromVaults(address[] calldata vaults) external;

    // ========== Oracle Registry (Governance Only) ==========

    function oracleRegistry() external view returns (IOracleRegistry);
    function setOracleRegistry(IOracleRegistry registry) external;

    // ========== Vault Registry ==========

    function isVault(address vault) external view returns (bool);
}

Creating a Vault

Basic Vault (Permissionless Deposits)

// Step 1: Deploy or choose strategy
address strategy = strategyFactory.deployImmutableStrategy(
    allowedAssets,
    StrategyParams({
        minBondRatio: 0.2e18,            // 20% bond
        liquidationBuffer: 0.1e18,        // 10% buffer
        adlBuffer: 0.1e18,                // 10% ADL buffer
        adlUtilizationThreshold: 0.95e18, // 95% utilization for ADL
        annualRate: 0.1e18,               // 10% APR
        curatorFeeRate: 1000,             // 10% curator fee
        liquidationProfitMargin: 0.01e18  // 1% liquidator profit
    })
);

// Step 2: Deploy vault
address vault = fluxFactory.createVault(
    USDC,                    // Base asset
    usdcWrapper,             // Base asset wrapper (must be whitelisted)
    strategy,                // Strategy from step 1
    address(0),              // No access policy = permissionless
    "Flux USDC Vault",       // Name
    "fUSDC"                  // Symbol
);

emit VaultCreated(vault);

Vault with Whitelist Access

// Deploy access policy
WhitelistAccessPolicy accessPolicy = new WhitelistAccessPolicy(msg.sender);
accessPolicy.setWhitelistedLP(trustedLP, true);
accessPolicy.setWhitelistedManager(trustedManager, true);

// Create vault with access control
address vault = fluxFactory.createVault(
    WETH,
    wethWrapper,
    strategy,
    address(accessPolicy),  // Only whitelisted users
    "Private WETH Vault",
    "pWETH"
);

Vault with Graduated Deposit Caps

For vaults that want to start small and scale gradually:

// Define tiers based on utilization
GraduatedCapDepositPolicyTier[] memory tiers = new GraduatedCapDepositPolicyTier[](3);

// Tier 1: Low utilization (0-50%) → No cap
tiers[0] = GraduatedCapDepositPolicyTier({
    minUtilizationBps: 0,        // 0% utilization
    maxDepositBps: type(uint64).max  // Unlimited deposits
});

// Tier 2: Medium utilization (50-80%) → 10% of vault size per deposit
tiers[1] = GraduatedCapDepositPolicyTier({
    minUtilizationBps: 5000,     // 50% utilization
    maxDepositBps: 1000          // Max 10% of vault per deposit
});

// Tier 3: High utilization (80%+) → 5% of vault size per deposit
tiers[2] = GraduatedCapDepositPolicyTier({
    minUtilizationBps: 8000,     // 80% utilization
    maxDepositBps: 500           // Max 5% of vault per deposit
});

// Create vault with deposit policy
(address vault, address policy) = fluxFactory.createVaultWithDepositPolicy(
    USDC,
    usdcWrapper,
    strategy,
    address(0),        // Permissionless
    tiers,             // Graduated caps
    100_000e6,         // $100K bootstrap threshold (no caps until reached)
    "Graduated USDC Vault",
    "gUSDC"
);

// Later: Adjust tiers if needed
GraduatedCapDepositPolicy(policy).updateTiers(newTiers);

Use Cases for Deposit Caps:

• New Vaults: Limit large deposits initially to test strategies

• Risk Management: Cap exposure during high utilization

• Bootstrap Phase: No caps until vault reaches minimum size

• Gradual Scaling: Increase caps as vault proves itself

Executor Registration

Managers must register an executor before borrowing. Two options:

Option 1: Deploy Weiroll Executor (Recommended)

// Deploy a fresh Weiroll executor
address executor = fluxFactory.deployWeirollExecutor();

// Automatically registered to msg.sender
// Can now use vault.unlock() from this executor

Advantages:

• Battle-tested executor implementation

• Supports complex multi-step strategies via Weiroll

• Composable with Weiroll recipes

• No custom development needed

Option 2: Register Custom Executor

// Deploy your custom executor
MyCustomExecutor executor = new MyCustomExecutor();

// Register it
fluxFactory.registerExecutor(msg.sender, address(executor));

Requirements for Custom Executors:

• Must implement IFluxUnlockCallback

• Must call vault.unlock() from the executor address

• Cannot be shared across multiple managers

• Cannot be changed after registration

Example Custom Executor:

contract MyCustomExecutor is IFluxUnlockCallback {
    address public immutable manager;
    IFluxVault public immutable vault;

    constructor(address _vault) {
        manager = msg.sender;
        vault = IFluxVault(_vault);
    }

    function executeStrategy(bytes calldata data) external {
        require(msg.sender == manager, "Only manager");

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

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

        // Decode strategy
        (uint256 borrowAmount, address[] memory wrappers) =
            abi.decode(data, (uint256, address[]));

        // Execute your custom logic
        vault.locked_borrow(borrowAmount);

        for (uint256 i = 0; i < wrappers.length; i++) {
            vault.locked_registerWrapper(wrappers[i]);
            // ... custom trading logic ...
        }
    }
}

Vault Registry

Check if an address is a Flux vault:

bool isFluxVault = fluxFactory.isVault(vaultAddress);

if (isFluxVault) {
    // Safe to cast to IFluxVault
    IFluxVault vault = IFluxVault(vaultAddress);
}

Protocol Fees

Governance Functions (only governance multisig):

// Set protocol fee rate (max 10%)
fluxFactory.setProtocolFeeRate(1000);  // 10% of interest

// Set fee collector
fluxFactory.setProtocolFeeCollector(treasuryAddress);

// Collect fees from specific vaults
address[] memory vaults = new address[](2);
vaults[0] = vault1;
vaults[1] = vault2;
fluxFactory.collectFeesFromVaults(vaults);

Fee Distribution:

Total Interest Earned: 100 USDC
├── Protocol Fee (10%): 10 USDC → Protocol Treasury
├── Curator Fee (10%): 10 USDC → Vault Creator
└── LP Share (80%): 80 USDC → LPs

Asset Whitelisting

Why Whitelisting?

Even though anyone can deploy wrappers via AssetWrapperFactory, governance must approve them before they can be used in vaults. This prevents:

• Malicious wrappers that steal funds

• Wrappers with incorrect oracle integration

• Wrappers for extremely illiquid assets

• Wrappers that don't follow IAsset spec

Governance Workflow:

// 1. Developer deploys wrapper via AssetWrapperFactory
address wethWrapper = assetWrapperFactory.deployERC20Wrapper(WETH);

// 2. Developer submits governance proposal to whitelist wrapper
// Proposal includes:
// - Wrapper address
// - Audit report
// - Oracle configuration
// - Liquidity analysis

// 3. Governance approves and whitelists
fluxFactory.whitelistAsset(wethWrapper);

// 4. Vault creators can now include this wrapper in strategies
address[] memory allowedAssets = new address[](1);
allowedAssets[0] = wethWrapper;
address strategy = strategyFactory.deployImmutableStrategy(
    allowedAssets,
    params
);

Checking Whitelist Status:

bool isWhitelisted = fluxFactory.isAssetWhitelisted(wrapperAddress);

if (!isWhitelisted) {
    revert("Wrapper not approved by governance");
}

---

StrategyFactory

Deploy economic parameter sets for vaults. Three strategy types available.

Strategy Types Comparison

Feature	Immutable	Mutable	Flexible Margin
Parameter Updates	Never	Via 7-day timelock	Via 7-day timelock
Liquidation Threshold	Derived (>100%)	Derived (>100%)	Direct (50-200%)
Minimum Bond Ratio	Fixed at deployment	Fixed at deployment	Can be minimal
Interest Rate	Fixed at deployment	Updatable	Updatable
Curator Fee	Fixed at deployment	Updatable	Updatable
Asset Allowlist	Fixed at deployment	Can add assets	Can add assets
ADL (Auto-Deleveraging)	Enabled	Enabled	Disabled
Best For	Conservative LPs	Active management	Single-user vaults

Interface

contract StrategyFactory {
    // ========== Immutable Strategy ==========

    function deployImmutableStrategy(
        address[] memory allowedAssets,
        StrategyParams memory params
    ) external returns (address strategy);

    // ========== Mutable Strategy ==========

    function deployMutableStrategy(
        address[] memory initialAssets,
        StrategyParams memory params,
        address owner
    ) external returns (address strategy);

    // ========== Flexible Margin Strategy ==========

    function deployFlexibleMarginStrategy(
        address[] memory initialAssets,
        FlexibleMarginParams memory params,
        address owner
    ) external returns (address strategy);

    // ========== Validation Helpers ==========

    function validateParams(StrategyParams memory params)
        external pure returns (bool);

    function validateFlexibleMarginParams(FlexibleMarginParams memory params)
        external pure returns (bool);

    // ========== Enumeration ==========

    function getStrategyCount() external view returns (uint256);
    function getStrategyAtIndex(uint256 index) external view returns (address);
    function getStrategiesRange(uint256 offset, uint256 limit)
        external view returns (address[] memory);
}

Strategy Parameters

Standard Strategy Parameters

struct StrategyParams {
    uint256 minBondRatio;            // 0-100%, minimum bond required
    uint256 liquidationBuffer;       // Must be < minBondRatio
    uint256 adlBuffer;               // Buffer above liquidation for ADL
    uint256 adlUtilizationThreshold; // Utilization % to enable ADL
    uint256 annualRate;              // Interest rate (no max)
    uint256 curatorFeeRate;          // Basis points (max 50%)
    uint256 liquidationProfitMargin; // 0-20% liquidator profit
}

Derived Values:

liquidationThreshold = 1.0 + minBondRatio - liquidationBuffer
adlThreshold = liquidationThreshold + adlBuffer

Example:
minBondRatio = 0.2 (20%)
liquidationBuffer = 0.1 (10%)
→ liquidationThreshold = 1.1 (110%)

adlBuffer = 0.05 (5%)
→ adlThreshold = 1.15 (115%)

Flexible Margin Parameters

struct FlexibleMarginParams {
    uint256 liquidationThreshold;    // Direct value (50-200%)
    uint256 minBondRatio;            // 0-100%, can be very low
    uint256 adlThreshold;            // Not used (ADL disabled)
    uint256 adlUtilizationThreshold; // Not used (ADL disabled)
    uint256 annualRate;              // Interest rate
    uint256 curatorFeeRate;          // Basis points (max 50%)
    uint256 liquidationProfitMargin; // 0-20% liquidator profit
}

Key Difference: Liquidation threshold is set directly, not derived. This allows:

• Sub-100% thresholds: Liquidate at 90% = stop-loss at -10% loss

• Minimal bonds: minBondRatio = 0.01% for self-managed vaults

• Custom guardrails: Set liquidation at any health ratio you want

Deploying Strategies

1. Immutable Strategy (Maximum Trust)

Best for conservative vaults prioritizing LP trust.

// Define allowed assets (cannot be changed later!)
address[] memory allowedAssets = new address[](3);
allowedAssets[0] = wethWrapper;
allowedAssets[1] = wbtcWrapper;
allowedAssets[2] = usdcWrapper;

// Define parameters (cannot be changed later!)
StrategyParams memory params = StrategyParams({
    minBondRatio: 0.25e18,           // 25% bond (4x leverage)
    liquidationBuffer: 0.15e18,       // 15% buffer
    adlBuffer: 0.1e18,                // 10% ADL buffer
    adlUtilizationThreshold: 0.95e18, // 95% utilization for ADL
    annualRate: 0.06e18,              // 6% APR
    curatorFeeRate: 500,              // 5% curator fee
    liquidationProfitMargin: 0.01e18  // 1% liquidator profit
});

// Deploy (permissionless!)
address strategy = strategyFactory.deployImmutableStrategy(
    allowedAssets,
    params
);

// Liquidation threshold = 1.0 + 0.25 - 0.15 = 1.1 (110%)
// ADL threshold = 1.1 + 0.1 = 1.2 (120%)

Characteristics:

• ✅ No governance risk - LPs know exactly what they're getting

• ✅ Predictable economics forever

• ❌ Cannot adapt to market changes

• ❌ Cannot add new assets even if audited

• ❌ Cannot adjust rates to stay competitive

2. Mutable Strategy (Flexible Management)

Best for active vault curators who want to stay competitive.

// Initial allowed assets (can add more later)
address[] memory initialAssets = new address[](2);
initialAssets[0] = wethWrapper;
initialAssets[1] = usdcWrapper;

// Initial parameters (can be updated via timelock)
StrategyParams memory params = StrategyParams({
    minBondRatio: 0.2e18,            // 20% bond (5x leverage)
    liquidationBuffer: 0.1e18,        // 10% buffer
    adlBuffer: 0.1e18,                // 10% ADL buffer
    adlUtilizationThreshold: 0.95e18, // 95% utilization for ADL
    annualRate: 0.1e18,               // 10% APR
    curatorFeeRate: 1000,             // 10% curator fee
    liquidationProfitMargin: 0.02e18  // 2% liquidator profit
});

// Deploy with owner (typically multisig)
address strategy = strategyFactory.deployMutableStrategy(
    initialAssets,
    params,
    multisigOwner  // Can update params via timelock
);

What Can Be Updated (via 7-day timelock):

• ✅ Annual interest rate

• ✅ Curator fee rate

• ✅ Allowed assets (can add, cannot remove)

What CANNOT Be Updated (set at deployment):

• ❌ Minimum bond ratio

• ❌ Liquidation buffer

• ❌ ADL buffer

• ❌ ADL utilization threshold

• ❌ Liquidation profit margin

Updating Parameters:

// As strategy owner (via timelock contract)
IMutableStrategy(strategy).setAnnualRate(0.12e18);  // Increase to 12% APR

// LPs have 7 days to exit if they disagree
// After 7 days, new rate takes effect

Adding Assets:

// Add newly whitelisted wrapper
IMutableStrategy(strategy).addAllowedAsset(newWrapperAddress);

// Cannot remove assets (managers may have positions)

3. Flexible Margin Strategy (Single-User Vaults)

Best for self-managed vaults with custom liquidation logic.

// Initial allowed assets
address[] memory initialAssets = new address[](5);
initialAssets[0] = wethWrapper;
initialAssets[1] = wbtcWrapper;
initialAssets[2] = usdcWrapper;
initialAssets[3] = stethWrapper;
initialAssets[4] = daiWrapper;

// Flexible margin parameters
FlexibleMarginParams memory params = FlexibleMarginParams({
    liquidationThreshold: 0.9e18,     // Liquidate at 90% (stop-loss at -10%)
    minBondRatio: 0.001e18,           // 0.1% bond (minimal since self-managed)
    adlThreshold: 0,                  // Not used (ADL disabled)
    adlUtilizationThreshold: 0,       // Not used (ADL disabled)
    annualRate: 0,                    // 0% (self-funding)
    curatorFeeRate: 0,                // 0% (self-managed)
    liquidationProfitMargin: 0.02e18  // 2% profit for liquidators
});

// Deploy
address strategy = strategyFactory.deployFlexibleMarginStrategy(
    initialAssets,
    params,
    selfManagedOwner  // Typically the only LP and manager
);

Use Cases:

1. Stop-Loss Automation:

   liquidationThreshold = 0.95e18  // Auto-exit at -5% loss

Leveraged Long with Tight Stop:

liquidationThreshold = 0.98e18  // Liquidate at -2% to protect capital

Delta-Neutral Strategy:

liquidationThreshold = 1.5e18   // Wide range, ADL disabled

Personal Capital Efficiency:

minBondRatio = 0.0001e18        // 0.01% bond for maximum leverage
liquidationThreshold = 0.8e18   // Liquidate at 80% (willing to accept losses)

Restrictions:

• Liquidation threshold must be 50-200% (0.5e18 to 2e18)

• Min bond ratio can be 0-100%

• ADL is always disabled

• Typically used with access policies (single LP/manager)

Parameter Validation

Before deploying, you can validate parameters:

// Standard strategy validation
try strategyFactory.validateParams(params) {
    // Parameters valid, proceed with deployment
    address strategy = strategyFactory.deployImmutableStrategy(assets, params);
} catch {
    // Invalid parameters, handle error
    revert("Invalid strategy parameters");
}

// Flexible margin validation
try strategyFactory.validateFlexibleMarginParams(flexParams) {
    address strategy = strategyFactory.deployFlexibleMarginStrategy(
        assets,
        flexParams,
        owner
    );
} catch {
    revert("Invalid flexible margin parameters");
}

Common Validation Errors:

// ❌ Bond ratio > 100%
params.minBondRatio = 1.5e18;  // INVALID

// ❌ Liquidation buffer >= minBondRatio
params.minBondRatio = 0.2e18;
params.liquidationBuffer = 0.25e18;  // INVALID (must be < 0.2)

// ❌ Curator fee > 50%
params.curatorFeeRate = 6000;  // INVALID (max 5000 = 50%)

// ❌ Liquidation profit margin > 20%
params.liquidationProfitMargin = 0.25e18;  // INVALID (max 0.2e18)

// ❌ Flexible margin threshold out of range
flexParams.liquidationThreshold = 0.3e18;  // INVALID (min 0.5e18)

Strategy Enumeration

Discover all deployed strategies:

// Get total count
uint256 count = strategyFactory.getStrategyCount();

// Get strategies in pages
address[] memory strategies = strategyFactory.getStrategiesRange(0, 100);

for (uint256 i = 0; i < strategies.length; i++) {
    IStrategy strategy = IStrategy(strategies[i]);

    // Query parameters
    uint256 annualRate = strategy.annualRate();
    uint256 minBond = strategy.minBondRatio();

    console.log("Strategy", i, "APR:", annualRate / 1e18);
}

---

AssetWrapperFactory

Permissionless deployment of vanilla ERC20 and ERC4626 wrappers.

Why a Wrapper Factory?

Problem: Every asset needs a wrapper to be used in Flux vaults. Manually deploying wrappers for every token doesn't scale.

Solution: Anyone can deploy a vanilla wrapper for any asset. Governance then whitelists vetted wrappers.

Developer Deploys → Governance Reviews → Governance Whitelists → Vaults Can Use
    (permissionless)     (audit/test)       (FluxVaultFactory)    (strategy config)

Interface

contract AssetWrapperFactory {
    // ========== Deployment ==========

    function deployERC20Wrapper(address asset)
        external returns (address wrapper);

    function deployERC4626Wrapper(address vault)
        external returns (address wrapper);

    // ========== Lookups ==========

    function getERC20Wrapper(address asset)
        external view returns (address wrapper);

    function getERC4626Wrapper(address vault)
        external view returns (address wrapper);

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

    function hasERC4626Wrapper(address vault)
        external view returns (bool);

    // ========== Enumeration ==========

    function getERC20WrapperCount() external view returns (uint256);
    function getERC20WrapperAtIndex(uint256 index) external view returns (address);
    function getERC20WrappersRange(uint256 offset, uint256 limit)
        external view returns (address[] memory);

    function getERC4626WrapperCount() external view returns (uint256);
    function getERC4626WrapperAtIndex(uint256 index) external view returns (address);
    function getERC4626WrappersRange(uint256 offset, uint256 limit)
        external view returns (address[] memory);
}

Deploying Wrappers

ERC20 Wrapper

One wrapper per token (singleton pattern).

// Check if wrapper already exists
address existingWrapper = assetWrapperFactory.getERC20Wrapper(WETH);

if (existingWrapper == address(0)) {
    // Deploy new wrapper
    address wethWrapper = assetWrapperFactory.deployERC20Wrapper(WETH);

    emit WrapperDeployed(WETH, wethWrapper, "ERC20");

    // Now request governance whitelisting
    // submitGovernanceProposal(wethWrapper);
} else {
    // Wrapper already exists, use it
    wethWrapper = existingWrapper;
}

// Attempting to deploy duplicate will revert
try assetWrapperFactory.deployERC20Wrapper(WETH) {
    // Won't reach here
} catch {
    // Reverts with WrapperAlreadyExists()
}

ERC4626 Wrapper

One wrapper per vault token.

// Deploy wrapper for Aave USDC (aUSDC)
address aUSDC = 0x...; // Aave USDC vault
address aUsdcWrapper = assetWrapperFactory.deployERC4626Wrapper(aUSDC);

// Deploy wrapper for Compound USDC (cUSDCv3)
address cUSDCv3 = 0x...; // Compound v3 USDC vault
address cUsdcWrapper = assetWrapperFactory.deployERC4626Wrapper(cUSDCv3);

// Both wrap USDC underneath, but different yield strategies
// Flux vault managers can choose which to use

Benefits of ERC4626 Wrappers:

• Auto-compound yield while used as collateral

• Managers earn yield on idle capital

• Vault supports heterogeneous USDC sources (Aave, Compound, etc.)

Wrapper Lifecycle

Full Flow:

// 1. Developer identifies need for new wrapper
address USDT = 0xdAC17F958D2ee523a2206206994597C13D831ec7;

// 2. Deploy wrapper (permissionless)
address usdtWrapper = assetWrapperFactory.deployERC20Wrapper(USDT);

// 3. Test wrapper thoroughly
// - Verify IAsset implementation
// - Test deposit/withdraw
// - Verify oracle integration
// - Check edge cases (reentrant tokens, fee-on-transfer, etc.)

// 4. Submit governance proposal
GovernanceProposal memory proposal = GovernanceProposal({
    action: "Whitelist USDT Wrapper",
    wrapper: usdtWrapper,
    auditReport: "ipfs://...",
    testResults: "ipfs://...",
    reasoning: "USDT is 3rd largest stablecoin, high demand from LPs and managers"
});

// 5. Governance reviews and approves
// After passing vote:
fluxFactory.whitelistAsset(usdtWrapper);

// 6. Vault creators can now use it
address[] memory allowedAssets = new address[](1);
allowedAssets[0] = usdtWrapper;
address strategy = strategyFactory.deployImmutableStrategy(
    allowedAssets,
    params
);

// 7. Managers can use USDT as collateral
vault.locked_registerWrapper(usdtWrapper);
USDT.approve(usdtWrapper, amount);
vault.locked_depositToWrapper(usdtWrapper, positionId, amount);

Custom Wrappers

For specialized assets (Uniswap V3 positions, Aerodrome LP tokens, etc.), deploy custom wrappers outside the factory:

// Custom Uniswap V3 wrapper (not via factory)
UniswapV3Wrapper customWrapper = new UniswapV3Wrapper(
    nonfungiblePositionManager,
    fluxFactory
);

// Submit to governance for whitelisting
// If approved:
fluxFactory.whitelistAsset(address(customWrapper));

// Now usable in strategies

Custom Wrapper Requirements:

1. Implement IAsset interface correctly

2. Integrate with oracle registry

3. Handle 3-layer position model (account/subaccount/positionId)

4. Pass comprehensive audit

5. No token approval vulnerabilities

6. Reentrancy protection

7. Correct decimal handling

See Asset Wrappers Concept for full IAsset specification.

Preventing Duplicates

The factory enforces singleton pattern:

// First deployment succeeds
address wrapper1 = assetWrapperFactory.deployERC20Wrapper(DAI);

// Second deployment fails
try assetWrapperFactory.deployERC20Wrapper(DAI) {
    // Won't execute
} catch {
    // Reverts with WrapperAlreadyExists()
}

// Query existing wrapper instead
address existingWrapper = assetWrapperFactory.getERC20Wrapper(DAI);
assert(existingWrapper == wrapper1);

Why Prevent Duplicates?

• Avoids confusion about which wrapper is "official"

• Prevents governance from having to whitelist multiple identical wrappers

• Reduces surface area for attacks (only one wrapper to audit)

• Simplifies discovery and enumeration

Enumerating Wrappers

Discover all deployed wrappers:

// Get all ERC20 wrappers (paginated)
uint256 totalERC20 = assetWrapperFactory.getERC20WrapperCount();
address[] memory erc20Wrappers = assetWrapperFactory.getERC20WrappersRange(0, 100);

for (uint256 i = 0; i < erc20Wrappers.length; i++) {
    address wrapper = erc20Wrappers[i];

    // Check if whitelisted
    bool whitelisted = fluxFactory.isAssetWhitelisted(wrapper);

    if (whitelisted) {
        // Safe to use in strategies
        console.log("Whitelisted wrapper:", wrapper);
    }
}

// Get all ERC4626 wrappers
uint256 totalERC4626 = assetWrapperFactory.getERC4626WrapperCount();
address[] memory erc4626Wrappers = assetWrapperFactory.getERC4626WrappersRange(0, 100);

---

Factory Architecture

Design Principles

1. Permissionless Innovation

Anyone can deploy:

• Asset wrappers for any token

• Strategies with custom parameters

• Vaults with any combination of assets/strategy

No gatekeeping at deployment level.

2. Governance Safety

Deployment ≠ Approval:

• Asset wrappers must be whitelisted by governance

• Strategies are permissionless but validate parameters

• Vaults can only use whitelisted wrappers

3. Discoverability

All deployments tracked:

• Enumerate all strategies

• Enumerate all wrappers (ERC20 and ERC4626)

• Check if address is a Flux vault

• Query wrapper for specific token

4. No Upgrades

Deployed components are immutable:

• Vaults use EIP-1167 minimal proxies (immutable logic)

• Immutable strategies locked forever

• Wrappers are not upgradeable

• Only Mutable/Flexible strategies allow parameter changes (via timelock)

5. Composability

Mix and match:

• Any vault + any strategy + any whitelisted wrappers

• Executor registry shared across all vaults

• Oracle registry shared across all assets

Security Model

Layer 1: Permissionless Deployment
├── Anyone can deploy wrappers
├── Anyone can deploy strategies
└── Anyone can deploy vaults

Layer 2: Parameter Validation
├── Strategy factory validates safety bounds
├── Vault factory checks wrapper whitelist status
└── Reverts on invalid configurations

Layer 3: Governance Whitelisting
├── Only whitelisted wrappers usable in vaults
├── Governance reviews audits and tests
└── Timelock for parameter changes (Mutable strategies)

Layer 4: Vault-Level Controls
├── Access policies (optional)
├── Deposit policies (optional)
└── Strategy enforcement (bond ratios, liquidation thresholds)

Threat Mitigation:

Threat	Mitigation
Malicious wrapper steals funds	Governance whitelisting
Strategy with unsafe parameters	Factory validation
Vault using unvetted wrapper	Factory checks whitelist
Manager registers malicious executor	One executor per manager, non-transferable
Governance compromise	Timelock on parameter updates
Oracle manipulation	Centralized oracle registry, governance-controlled

---

Integration Examples

For Vault Creators

// Complete vault deployment from scratch
contract VaultDeploymentHelper {
    IFluxVaultFactory public immutable fluxFactory;
    StrategyFactory public immutable strategyFactory;
    AssetWrapperFactory public immutable assetWrapperFactory;

    function deployCompleteVault(
        address baseAsset,
        address[] memory tradingAssets,
        StrategyParams memory params,
        string memory name,
        string memory symbol
    ) external returns (address vault, address strategy) {
        // 1. Deploy wrappers if needed
        address baseWrapper = _getOrDeployWrapper(baseAsset);

        address[] memory allowedAssets = new address[](tradingAssets.length + 1);
        allowedAssets[0] = baseWrapper;

        for (uint256 i = 0; i < tradingAssets.length; i++) {
            allowedAssets[i + 1] = _getOrDeployWrapper(tradingAssets[i]);
        }

        // 2. Deploy strategy
        strategy = strategyFactory.deployImmutableStrategy(
            allowedAssets,
            params
        );

        // 3. Deploy vault
        vault = fluxFactory.createVault(
            baseAsset,
            baseWrapper,
            strategy,
            address(0),  // Permissionless
            name,
            symbol
        );
    }

    function _getOrDeployWrapper(address asset) internal returns (address wrapper) {
        // Check if wrapper exists
        wrapper = assetWrapperFactory.getERC20Wrapper(asset);

        if (wrapper == address(0)) {
            // Deploy new wrapper
            wrapper = assetWrapperFactory.deployERC20Wrapper(asset);

            // Note: Governance must whitelist before vault can use it
            emit WrapperDeployedAwaitingWhitelist(asset, wrapper);
        }

        // Verify whitelisted
        require(
            fluxFactory.isAssetWhitelisted(wrapper),
            "Wrapper not whitelisted"
        );
    }
}

For Protocol Developers

// Build a vault discovery and analytics system
contract FluxAnalytics {
    IFluxVaultFactory public immutable factory;
    StrategyFactory public immutable strategyFactory;

    struct VaultInfo {
        address vault;
        address asset;
        uint256 tvl;
        uint256 utilization;
        uint256 apy;
        address strategy;
        uint256 annualRate;
    }

    function getAllVaults() external view returns (VaultInfo[] memory) {
        // In production, track vault deployments via events
        // This is pseudocode for concept demonstration

        address[] memory vaults = _getTrackedVaults();
        VaultInfo[] memory infos = new VaultInfo[](vaults.length);

        for (uint256 i = 0; i < vaults.length; i++) {
            IFluxVault vault = IFluxVault(vaults[i]);
            IStrategy strategy = vault.strategy();

            infos[i] = VaultInfo({
                vault: address(vault),
                asset: address(vault.asset()),
                tvl: vault.totalAssets(),
                utilization: _calculateUtilization(vault),
                apy: _calculateAPY(vault),
                strategy: address(strategy),
                annualRate: strategy.annualRate()
            });
        }

        return infos;
    }

    function getTopStrategies(uint256 limit)
        external
        view
        returns (address[] memory)
    {
        uint256 count = strategyFactory.getStrategyCount();
        // Sort by TVL across vaults using this strategy
        // Return top N
    }
}

For Governance

// Governance operations contract
contract FluxGovernance {
    IFluxVaultFactory public immutable factory;
    address public immutable multisig;

    modifier onlyMultisig() {
        require(msg.sender == multisig, "Only multisig");
        _;
    }

    // Whitelist multiple wrappers in one tx
    function batchWhitelistAssets(address[] calldata wrappers)
        external
        onlyMultisig
    {
        for (uint256 i = 0; i < wrappers.length; i++) {
            factory.whitelistAsset(wrappers[i]);
        }
    }

    // Collect fees from all vaults
    function collectAllFees(address[] calldata vaults)
        external
        onlyMultisig
    {
        factory.collectFeesFromVaults(vaults);
    }

    // Update protocol fee with timelock
    function proposeProtocolFeeUpdate(uint256 newRate) external onlyMultisig {
        // Submit to timelock governance contract
        // After timelock: factory.setProtocolFeeRate(newRate);
    }
}

---

Best Practices

For Wrapper Deployers

Do:

• Deploy wrappers for widely-used assets

• Test thoroughly before governance submission

• Include audit reports in governance proposal

• Verify oracle support exists

• Check for existing wrapper first

Don't:

• Deploy duplicate wrappers

• Deploy for illiquid or experimental tokens

• Deploy without testing on testnet

• Assume governance will whitelist automatically

For Strategy Creators

Do:

• Start with conservative parameters

• Validate parameters before deployment

• Consider LP risk tolerance

• Research competitive rates

• Document strategy reasoning

Don't:

• Use extreme parameters without justification

• Ignore liquidation buffer requirements

• Set fees higher than market standard

• Deploy immutable strategy without thorough testing

For Vault Creators

Do:

• Verify all wrappers are whitelisted

• Choose strategy matching your LP base

• Set clear access policies if restricting

• Monitor vault health regularly

• Communicate with LPs about changes (if mutable)

Don't:

• Use unwhitelisted wrappers

• Change mutable strategy parameters frequently

• Ignore LP feedback on governance decisions

• Deploy without testing complete flow

For Governance

Do:

• Require audits for wrapper whitelisting

• Test wrappers on testnet first

• Verify oracle availability before approving

• Check liquidity for liquidation scenarios

• Use timelock for protocol changes

Don't:

• Whitelist unaudited wrappers

• Approve wrappers for illiquid assets

• Change protocol fees without community discussion

• Whitelist wrappers without oracle support

---

Summary

Flux's factory system provides:

• Permissionless Innovation: Anyone can deploy vaults, strategies, and wrappers

• Safety Through Validation: Parameter checks prevent unsafe configurations

• Governance Oversight: Whitelisting ensures only vetted wrappers are used

• Composability: Mix and match components freely

• Discoverability: Enumerate all deployments for analytics

• No Lock-In: Immutable contracts, no upgrade risk

Three Factories:

1. FluxVaultFactory: Deploy vaults, manage protocol settings

2. StrategyFactory: Deploy economic parameter sets (Immutable/Mutable/Flexible)

3. AssetWrapperFactory: Deploy vanilla wrappers for ERC20/ERC4626 tokens

Key Flows:

New Asset:
  Deploy Wrapper → Submit Proposal → Governance Whitelists → Use in Vaults

New Vault:
  Deploy Strategy → Create Vault → LPs Deposit → Managers Borrow

Manager Onboarding:
  Deploy/Register Executor → Borrow from Vault → Trade Assets