Asset Wrappers

Asset Wrappers provide a unified interface for managing heterogeneous assets within Flux vaults. They enable managers to hold positions in any tokenized asset—from standard ERC20 tokens to Uniswap V3 NFTs to yield-bearing vaults.

What is an Asset Wrapper?

An Asset Wrapper is a smart contract that:

• Implements the IAsset interface

• Manages positions for multiple vaults and managers

• Integrates with the Oracle Registry for pricing

• Provides a consistent API regardless of underlying asset type

Think of wrappers as "adapters" that translate diverse asset types into a common position tracking format that Flux vaults understand.

---

Why Asset Wrappers?

Traditional lending protocols are limited to simple ERC20 tokens. Flux's wrapper architecture enables:

Heterogeneous Asset Support

• ✓ ERC20 tokens (USDC, WETH, etc.)

• ✓ ERC4626 vaults (Aave aTokens, Compound cTokens, etc.)

• ✓ Uniswap V3 LP positions (NFTs)

• ✓ Aerodrome LP positions

• ✓ Any custom asset type with proper wrapper

Unified Position Management

Managers interact with all assets through the same interface:

// Same pattern for any asset type
vault.locked_depositToWrapper(wrapper, positionId, amount);
vault.locked_withdrawFromWrapper(wrapper, positionId, amount);

Permissionless Deployment

Anyone can deploy vanilla wrappers via AssetWrapperFactory:

// Deploy ERC20 wrapper
address wrapper = factory.deployERC20Wrapper(tokenAddress);

// Deploy ERC4626 wrapper
address wrapper = factory.deployERC4626Wrapper(vaultAddress);

---

The IAsset Interface

All wrappers implement the IAsset interface:

interface IAsset {
    // Deposit assets into position
    function deposit(
        address account,
        address subaccount,
        bytes32 positionId,
        uint256 amount
    ) external;

    // Claim pre-received assets
    function claim(
        address account,
        address subaccount,
        bytes32 positionId,
        uint256 amount
    ) external;

    // Withdraw assets from position
    function withdraw(
        address account,
        address subaccount,
        bytes32 positionId,
        address recipient,
        uint256 amount
    ) external;

    // Get position value (USD or base asset units)
    function getValue(
        address account,
        address subaccount,
        bytes32 positionId
    ) external view returns (uint256);

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

    // Get underlying asset address
    function underlyingAsset() external view returns (address);
}

---

The 3-Layer Position Model

Asset wrappers track positions using three layers:

account (vault address)
  └─ subaccount (manager address)
      └─ positionId (semantic identifier or token ID)

Example:

// Vault 0x123... tracking Manager 0xabc...'s WETH position
account = 0x123...      // Vault address
subaccount = 0xabc...   // Manager address
positionId = 0x00       // Generic WETH position

// Balance stored as:
balances[0x123...][0xabc...][0x00] = 10e18  // 10 WETH

Why Three Layers?

Isolation: Each vault's positions are completely isolated

// VaultA and VaultB use same wrapper but track separately
balances[vaultA][manager1][positionId] = 100e18
balances[vaultB][manager1][positionId] = 200e18
// No interference between vaults

Flexibility: Position IDs can represent:

• Generic positions (0x00 for fungible assets)

• Specific token IDs (for NFTs)

• Semantic groupings (separate position IDs for different strategies)

Security: Only the account (vault) can modify its own positions

function deposit(...) external {
    require(msg.sender == account, "Unauthorized");
    // Only vault can modify its positions
}

---

Built-In Wrapper Types

1. ERC20AssetWrapper

Wraps standard ERC20 tokens for use in Flux vaults.

Example Usage:

// Deploy WETH wrapper
address wethWrapper = assetWrapperFactory.deployERC20Wrapper(WETH);

// Inside manager callback:
// Deposit WETH to position
vault.locked_depositToWrapper(
    IAsset(wethWrapper),
    bytes32(0),  // Generic position ID
    10e18        // 10 WETH
);

How It Works:

1. Manager approves wrapper for WETH

2. Wrapper transfers WETH from manager

3. Wrapper updates balances[vault][manager][positionId]

4. Position value queried via Oracle Registry

Price Valuation:

function getValue(address account, address subaccount, bytes32 positionId)
    external view returns (uint256)
{
    uint256 balance = balances[account][subaccount][positionId];

    // Query factory's oracle registry
    IOracleRegistry registry = factory.oracleRegistry();

    // Get USD value from oracle
    return registry.getValueUSD(underlyingAsset, balance);
}

2. ERC4626AssetWrapper

Wraps ERC4626 yield-bearing vaults (Aave, Compound, etc.).

Example Usage:

// Deploy aUSDC wrapper
address aUsdcWrapper = assetWrapperFactory.deployERC4626Wrapper(aUSDC);

// Deposit to aUSDC position
vault.locked_depositToWrapper(
    IAsset(aUsdcWrapper),
    bytes32(0),
    100_000e6  // 100K USDC worth of aUSDC
);

How It Works:

1. Manager has aUSDC shares

2. Wrapper transfers aUSDC shares from manager

3. Wrapper tracks shares in balances[vault][manager][positionId]

4. Value calculated as: shares × sharePrice (via convertToAssets)

Auto-Compounding:

function getValue(address account, address subaccount, bytes32 positionId)
    external view returns (uint256)
{
    uint256 shares = balances[account][subaccount][positionId];

    // ERC4626 vault converts shares to underlying assets
    uint256 assets = IERC4626(underlyingAsset).convertToAssets(shares);

    // Query oracle for USD value
    address baseAsset = IERC4626(underlyingAsset).asset();
    return registry.getValueUSD(baseAsset, assets);
}

Automatically captures yield growth without manager action.

3. Custom Wrappers

For specialized assets (NFTs, LP positions, etc.), deploy custom wrappers.

Example: Uniswap V3 Wrapper

contract UniswapV3Wrapper is IAsset, BaseAssetWrapper {
    INonfungiblePositionManager public immutable positionManager;

    function deposit(
        address account,
        address subaccount,
        bytes32 positionId,
        uint256 tokenId  // NFT token ID
    ) external {
        require(msg.sender == account, "Unauthorized");

        // Transfer NFT to wrapper
        positionManager.transferFrom(subaccount, address(this), tokenId);

        // Store position (positionId = tokenId for NFTs)
        positions[account][subaccount][positionId] = Position({
            tokenId: tokenId,
            exists: true
        });
    }

    function getValue(
        address account,
        address subaccount,
        bytes32 positionId
    ) external view returns (uint256) {
        Position memory pos = positions[account][subaccount][positionId];

        // Get position liquidity and tick range
        (,,,,,,, liquidity, , , ,) = positionManager.positions(pos.tokenId);

        // Calculate value based on current price and liquidity
        return calculatePositionValue(pos.tokenId, liquidity);
    }
}

---

Wrapper Security Model

Isolated Namespaces

Each vault operates in its own namespace:

// VaultA cannot access VaultB's positions
balances[vaultA][manager][positionId] = 100e18  // VaultA's tracking
balances[vaultB][manager][positionId] = 200e18  // VaultB's tracking (separate)

// Enforced by access control
function deposit(...) external {
    require(msg.sender == account);  // Only vault can modify its positions
}

Why This Matters:

• One wrapper deployment serves unlimited vaults

• Vaults cannot interfere with each other

• Zero trust assumptions between vaults

Access Control

Wrappers enforce strict access control:

modifier onlyAccount(address account) {
    require(msg.sender == account, "Unauthorized");
    _;
}

function deposit(address account, ...) external onlyAccount(account) {
    // Only the vault (account) can deposit to its positions
}

Security Guarantee: Only the vault can modify positions in its namespace.

Factory Integration

All wrappers are linked to the FluxVaultFactory:

contract ERC20AssetWrapper {
    IFluxVaultFactory public immutable factory;

    function getValue(...) external view returns (uint256) {
        // Query factory's oracle registry
        IOracleRegistry registry = factory.oracleRegistry();
        return registry.getValueUSD(asset, balance);
    }
}

This ensures:

• Consistent oracle pricing across all vaults

• Governance can update oracle registry

• Wrappers stay synchronized with protocol

---

Asset Wrapper Factory

The AssetWrapperFactory enables permissionless wrapper deployment:

Deploying Vanilla Wrappers

interface IAssetWrapperFactory {
    // Deploy ERC20 wrapper
    function deployERC20Wrapper(address token)
        external returns (address wrapper);

    // Deploy ERC4626 wrapper
    function deployERC4626Wrapper(address vault)
        external returns (address wrapper);

    // Get wrapper for asset (if exists)
    function getWrapper(address asset)
        external view returns (address wrapper);
}

Duplicate Prevention

Factory prevents duplicate wrappers:

function deployERC20Wrapper(address token) external returns (address) {
    require(wrappers[token] == address(0), "Wrapper already exists");

    address wrapper = address(new ERC20AssetWrapper(token, factory));
    wrappers[token] = wrapper;

    emit WrapperDeployed(token, wrapper);
    return wrapper;
}

Why: Prevents fragmentation, ensures consistent pricing.

Whitelisting Flow

After deployment, wrappers must be whitelisted:

1. Deploy: Anyone deploys wrapper via factory

2. Whitelist: Governance whitelists via FluxVaultFactory.whitelistAsset(wrapper)

3. Use: Strategies can include wrapper in allowed assets

// 1. Deploy
address wethWrapper = assetWrapperFactory.deployERC20Wrapper(WETH);

// 2. Governance whitelists
fluxVaultFactory.whitelistAsset(wethWrapper);

// 3. Strategy allows it
strategyFactory.deployImmutableStrategy(
    [wethWrapper, usdcWrapper],  // Allowed assets
    params
);

---

Oracle Integration

Wrappers don't store prices - they query the Oracle Registry:

How It Works

contract ERC20AssetWrapper {
    function getValue(address account, address subaccount, bytes32 positionId)
        external view returns (uint256)
    {
        uint256 balance = balances[account][subaccount][positionId];

        // Step 1: Get oracle registry from factory
        IOracleRegistry registry = factory.oracleRegistry();

        // Step 2: Query USD value for this asset
        return registry.getValueUSD(underlyingAsset, balance);
    }
}

Oracle Registry Flow

Wrapper
  └─ Query Factory
      └─ Get Oracle Registry
          └─ Query Asset Price
              └─ Return USD Value

Benefits:

• Wrappers don't need oracle logic

• Oracle sources can be upgraded without redeploying wrappers

• Centralized price governance

• Consistent pricing across all vaults

---

Working with Wrappers

As a Manager

Register Wrapper

// Inside unlock callback
vault.locked_registerWrapper(wethWrapper);

Adds wrapper to manager's allowed list for this vault.

Deposit to Wrapper

// Approve wrapper for token
WETH.approve(wethWrapper, amount);

// Inside unlock callback
vault.locked_depositToWrapper(
    IAsset(wethWrapper),
    bytes32(0),  // Position ID
    amount
);

Withdraw from Wrapper

// Inside unlock callback
vault.locked_withdrawFromWrapper(
    IAsset(wethWrapper),
    bytes32(0),  // Position ID
    amount       // Or type(uint256).max for all
);

Token is sent to manager (subaccount).

Claim Assets

For pre-received assets (e.g., airdrops, rewards):

// Manager received 10 WETH directly
// Claim into position without transferring

vault.locked_claimFromWrapper(
    IAsset(wethWrapper),
    bytes32(0),
    10e18
);

Wrapper checks its balance increased and credits position.

As a Liquidator

During liquidation, access seized collateral:

// Inside liquidation callback
function fluxUnlockCallback(bytes calldata data) external {
    // Extract manager's WETH position
    vault.locked_withdrawFromWrapper(
        IAsset(wethWrapper),
        bytes32(0),
        type(uint256).max  // All of it
    );

    // WETH sent to liquidator (us)
    // Swap for base asset + profit
}

---

Wrapper Lifecycle

1. Deployment

// Anyone deploys via factory
address wrapper = assetWrapperFactory.deployERC20Wrapper(WETH);

2. Whitelisting

// Governance whitelists
fluxVaultFactory.whitelistAsset(wrapper);

3. Strategy Inclusion

// Vault creator includes in strategy
strategyFactory.deployImmutableStrategy(
    [wrapper, ...],
    params
);

4. Manager Usage

// Manager registers and uses
vault.locked_registerWrapper(wrapper);
vault.locked_depositToWrapper(wrapper, positionId, amount);

5. Oracle Pricing

// Vault queries value during health checks
uint256 value = wrapper.getValue(vault, manager, positionId);

6. Liquidation

// Liquidator extracts if manager unhealthy
vault.locked_withdrawFromWrapper(wrapper, positionId, amount);

---

Advanced Wrapper Features

Custom Position IDs

Managers can use multiple position IDs per wrapper:

// Separate positions for different strategies
bytes32 strategyA = keccak256("strategy-a");
bytes32 strategyB = keccak256("strategy-b");

vault.locked_depositToWrapper(wethWrapper, strategyA, 10e18);
vault.locked_depositToWrapper(wethWrapper, strategyB, 20e18);

// Query separately
uint256 valueA = wethWrapper.getValue(vault, manager, strategyA);  // 10 WETH
uint256 valueB = wethWrapper.getValue(vault, manager, strategyB);  // 20 WETH

Batch Operations

Wrappers support efficient batch queries:

// Query all registered wrappers for manager
IAsset[] memory wrappers = vault.getRegisteredWrappers(manager);

// Calculate total position value
uint256 total = 0;
for (uint i = 0; i < wrappers.length; i++) {
    total += wrappers[i].getValue(vault, manager, positionId);
}

Position Transfer (Liquidation)

During liquidation, entire subaccounts can be transferred:

// Called by vault during liquidation
function ledgerTransferSubaccount(
    address fromSubaccount,
    address toSubaccount
) external {
    require(msg.sender == account, "Only vault");

    // Transfer all positions from manager to liquidator
    // Implementation varies by wrapper type
}

---

Wrapper Best Practices

For Wrapper Developers

1. Implement IAsset Fully: All functions must be implemented correctly

2. Use Factory Pattern: Link to FluxVaultFactory for oracle access

3. Enforce Access Control: Only account (vault) can modify positions

4. Handle Edge Cases: Zero amounts, non-existent positions, etc.

5. Optimize Gas: Minimize storage, use efficient data structures

6. Document Behavior: Clearly document position ID semantics

For Vault Creators

1. Vet Wrappers: Only include audited, trusted wrappers in strategies

2. Check Oracle Support: Ensure Oracle Registry supports the asset

3. Understand Risks: Custom wrappers may have unique risks

4. Test Integration: Verify wrapper works correctly with vaults

5. Monitor Whitelisting: Track governance whitelist updates

For Managers

1. Register Before Use: Call locked_registerWrapper() before depositing

2. Track Position IDs: Use consistent position IDs for accounting

3. Monitor Valuations: Understand how wrappers are priced

4. Handle Failures: Wrapper interactions can fail (e.g., paused)

5. Optimize Routes: Some wrappers may be more gas-efficient than others

---

Comparison with Other Protocols

Feature	Flux Wrappers	Morpho Markets	Aave V3
Asset Types	Any (NFT, ERC20, ERC4626, custom)	ERC20, ERC4626	ERC20 only
Deployment	Permissionless (factory)	Permissionless	Governance approval
Pricing	Oracle Registry	Per-market oracle	Shared oracle
Position Model	3-layer (account/subaccount/positionId)	Per-market balances	Per-pool balances
Isolation	Vault-level namespaces	Market-level	Pool-level
Custom Assets	✓ Full support	Limited	Not supported