Custom Wrapper Development

Table of Contents

1. Architecture Overview

2. Understanding the IAsset Interface

3. Base Contracts

4. Wrapper Development Patterns

5. Position ID Semantics

6. Oracle Integration

7. Security Model

8. Example Implementations

9. Testing Your Wrapper

10. Deployment & Integration

11. Best Practices

---

Architecture Overview

Asset wrappers in Flux provide a unified interface for managing heterogeneous assets. They enable vaults to support:

• Standard fungible tokens (ERC20)

• Yield-bearing tokens (ERC4626 vaults like Aave, Compound)

• NFT positions (Uniswap V3 LP NFTs)

• LP tokens (Aerodrome, Curve, Balancer)

• Any custom asset type you can imagine

Key Principles

1. Three-Layer Position Model: account (vault) → subaccount (manager) → positionId

2. Isolated Namespaces: Each vault operates independently

3. Permissionless: One wrapper deployment serves unlimited vaults

4. Oracle Pricing: Wrappers query the Oracle Registry for valuations

5. Access Control: Only the vault can modify its positions

---

Understanding the IAsset Interface

All wrappers must implement IAsset (src/interfaces/IAsset.sol:9):

interface IAsset {
    // Core position management
    function deposit(address account, address subaccount, bytes32 positionId, uint256 amount) external;
    function claim(address account, address subaccount, bytes32 positionId, uint256 amount) external;
    function withdraw(address account, address subaccount, bytes32 positionId, address recipient, uint256 amount) external;
    function transfer(address fromAccount, address fromSubaccount, bytes32 fromPositionId,
                     address toAccount, address toSubaccount, bytes32 toPositionId, uint256 amount) external;
    
    // Position queries
    function getValue(address account, address subaccount, bytes32 positionId) external view returns (uint256);
    function getBalance(address account, address subaccount, bytes32 positionId) external view returns (uint256);
    
    // Metadata
    function underlyingAsset() external view returns (address);
    
    // Liquidation support
    function ledgerTransferSubaccount(address fromSubaccount, address toSubaccount) external;
    
    // Optional custom interactions
    function customInteraction(address account, address subaccount, bytes calldata data) external returns (bytes memory);
}

Function Responsibilities

Function	Purpose	Called By
deposit()	Transfer assets from manager to wrapper	Vault during locked_depositToWrapper()
claim()	Claim pre-received assets (airdrops, rewards)	Vault during locked_claimFromWrapper()
withdraw()	Transfer assets from wrapper to recipient	Vault during locked_withdrawFromWrapper()
transfer()	Move position between accounts	Vault during internal transfers
getValue()	Get USD value of position	Strategy during health checks
getBalance()	Get raw balance (shares, NFT count, etc.)	Vault for accounting
underlyingAsset()	Get underlying token address	Oracle registry for pricing
ledgerTransferSubaccount()	Transfer all positions during liquidation	Vault during liquidation
customInteraction()	Execute custom logic (optional)	Vault during locked_interactWithWrapper()

---

Base Contracts

Flux provides two base contracts to simplify wrapper development:

1. BaseAssetWrapper (src/base/BaseAssetWrapper.sol:22)

Provides access control and security enforcement:

abstract contract BaseAssetWrapper is IAsset {
    // Access control modifier
    modifier onlyAuthorized(address account) {
        if (msg.sender != account) revert UnauthorizedCaller(msg.sender, account);
        _;
    }
    
    // Public functions with access control
    function deposit(...) external onlyAuthorized(account) { _deposit(...); }
    function claim(...) external onlyAuthorized(account) { _claim(...); }
    function withdraw(...) external onlyAuthorized(account) { _withdraw(...); }
    
    // Abstract functions to implement
    function _deposit(...) internal virtual;
    function _claim(...) internal virtual;
    function _withdraw(...) internal virtual;
    // ... etc
}

Benefits:

• Access control handled automatically

• Focus on business logic in _internal functions

• Secure by default

2. SimpleFungibleWrapper (src/base/SimpleFungibleWrapper.sol:18)

Extends BaseAssetWrapper for simple 2-position model:

abstract contract SimpleFungibleWrapper is BaseAssetWrapper {
    // Implements ledgerTransferSubaccount for 2 positions
    function _ledgerTransferSubaccount(address account, address from, address to) internal override {
        bytes32[2] memory positions = [WORKING_CAPITAL_POS_ID, BOND_POS_ID];
        for (uint256 i = 0; i < 2; i++) {
            uint256 balance = _getPositionBalance(account, from, positions[i]);
            if (balance > 0) {
                _transferPosition(account, from, positions[i], account, to, positions[i], balance);
            }
        }
    }
    
    // Abstract helpers
    function _getPositionBalance(...) internal virtual returns (uint256);
    function _transferPosition(...) internal virtual;
}

Use SimpleFungibleWrapper for:

• ERC20 tokens

• ERC4626 vaults

• Any fungible asset with working capital + bond positions

Use BaseAssetWrapper for:

• NFT positions (Uniswap V3, etc.)

• Complex multi-position assets

• Assets requiring custom position enumeration

---

Wrapper Development Patterns

Pattern 1: Simple Fungible Token Wrapper

Best for: ERC20 tokens, simple yield-bearing tokens

contract MyTokenWrapper is SimpleFungibleWrapper {
    address public immutable asset;
    IFluxVaultFactory public immutable factory;
    
    mapping(address => mapping(address => mapping(bytes32 => uint256))) public balances;
    
    constructor(address _asset, IFluxVaultFactory _factory) {
        asset = _asset;
        factory = _factory;
    }
    
    function _deposit(address account, address subaccount, bytes32 positionId, uint256 amount) internal override {
        // Validate position ID if needed
        _validatePositionId(positionId);
        
        // Transfer tokens
        SafeERC20.safeTransferFrom(IERC20(asset), msg.sender, address(this), amount);
        
        // Update balance
        balances[account][subaccount][positionId] += amount;
        
        emit Deposited(account, subaccount, positionId, amount, balances[account][subaccount][positionId]);
    }
    
    function _withdraw(address account, address subaccount, bytes32 positionId, address recipient, uint256 amount) internal override {
        uint256 balance = balances[account][subaccount][positionId];
        
        // Handle type(uint256).max for "withdraw all"
        if (amount == type(uint256).max) {
            amount = balance;
        }
        
        require(balance >= amount, "Insufficient balance");
        
        balances[account][subaccount][positionId] = balance - amount;
        SafeERC20.safeTransfer(IERC20(asset), recipient, amount);
        
        emit Withdrawn(account, subaccount, positionId, recipient, amount, balances[account][subaccount][positionId]);
    }
    
    function getValue(address account, address subaccount, bytes32 positionId) external view override returns (uint256) {
        uint256 balance = balances[account][subaccount][positionId];
        if (balance == 0) return 0;
        
        // Query oracle registry
        IOracleRegistry registry = factory.oracleRegistry();
        return registry.getValueUSD(asset, balance);
    }
    
    // ... implement other required functions
}

Pattern 2: NFT Position Wrapper

Best for: Uniswap V3 positions, ERC721-based assets

contract UniswapV3Wrapper is BaseAssetWrapper {
    struct Position {
        uint256 tokenId;
        bool exists;
    }
    
    INonfungiblePositionManager public immutable positionManager;
    IFluxVaultFactory public immutable factory;
    
    // account => subaccount => positionId => Position
    mapping(address => mapping(address => mapping(bytes32 => Position))) public positions;
    
    constructor(address _positionManager, IFluxVaultFactory _factory) {
        positionManager = INonfungiblePositionManager(_positionManager);
        factory = _factory;
    }
    
    function _deposit(address account, address subaccount, bytes32 positionId, uint256 tokenId) internal override {
        require(!positions[account][subaccount][positionId].exists, "Position already exists");
        
        // Transfer NFT to wrapper
        positionManager.transferFrom(msg.sender, address(this), tokenId);
        
        // Store position (use tokenId as positionId for NFTs)
        positions[account][subaccount][positionId] = Position({
            tokenId: tokenId,
            exists: true
        });
        
        emit Deposited(account, subaccount, positionId, 1, 1);
    }
    
    function _withdraw(address account, address subaccount, bytes32 positionId, address recipient, uint256) internal override {
        Position storage pos = positions[account][subaccount][positionId];
        require(pos.exists, "Position not found");
        
        uint256 tokenId = pos.tokenId;
        
        // Clear position
        delete positions[account][subaccount][positionId];
        
        // Transfer NFT
        positionManager.transferFrom(address(this), recipient, tokenId);
        
        emit Withdrawn(account, subaccount, positionId, recipient, 1, 0);
    }
    
    function getValue(address account, address subaccount, bytes32 positionId) external view override returns (uint256) {
        Position storage pos = positions[account][subaccount][positionId];
        if (!pos.exists) return 0;
        
        // Get position data from Uniswap
        (,,address token0, address token1,,,, uint128 liquidity,,,,) = positionManager.positions(pos.tokenId);
        
        // Calculate value based on liquidity and current tick
        return _calculatePositionValue(pos.tokenId, token0, token1, liquidity);
    }
    
    function _ledgerTransferSubaccount(address account, address fromSubaccount, address toSubaccount) internal override {
        // NFT wrappers need custom enumeration
        // Option 1: Track position IDs per subaccount
        // Option 2: Iterate through known positions
        // Implementation depends on your position tracking strategy
    }
    
    // Helper function to calculate position value
    function _calculatePositionValue(uint256 tokenId, address token0, address token1, uint128 liquidity) 
        internal view returns (uint256) 
    {
        // Get current tick and calculate token amounts
        // Query oracle for token prices
        // Return total USD value
        // (Implementation details omitted for brevity)
    }
}

Pattern 3: LP Token Wrapper with Rewards

Best for: Curve, Balancer, Aerodrome LP positions with reward claiming

contract AerodromeLPWrapper is SimpleFungibleWrapper {
    address public immutable lpToken;
    address public immutable gauge;  // Staking contract
    IFluxVaultFactory public immutable factory;
    
    mapping(address => mapping(address => mapping(bytes32 => uint256))) public stakedBalances;
    
    constructor(address _lpToken, address _gauge, IFluxVaultFactory _factory) {
        lpToken = _lpToken;
        gauge = _gauge;
        factory = _factory;
    }
    
    function _deposit(address account, address subaccount, bytes32 positionId, uint256 amount) internal override {
        // Transfer LP tokens from manager
        SafeERC20.safeTransferFrom(IERC20(lpToken), msg.sender, address(this), amount);
        
        // Stake in gauge
        IERC20(lpToken).approve(gauge, amount);
        IAerodromeGauge(gauge).deposit(amount);
        
        // Update balance
        stakedBalances[account][subaccount][positionId] += amount;
        
        emit Deposited(account, subaccount, positionId, amount, stakedBalances[account][subaccount][positionId]);
    }
    
    function _withdraw(address account, address subaccount, bytes32 positionId, address recipient, uint256 amount) internal override {
        uint256 balance = stakedBalances[account][subaccount][positionId];
        
        if (amount == type(uint256).max) {
            amount = balance;
        }
        
        require(balance >= amount, "Insufficient balance");
        
        // Unstake from gauge
        IAerodromeGauge(gauge).withdraw(amount);
        
        // Update balance
        stakedBalances[account][subaccount][positionId] = balance - amount;
        
        // Transfer LP tokens
        SafeERC20.safeTransfer(IERC20(lpToken), recipient, amount);
        
        emit Withdrawn(account, subaccount, positionId, recipient, amount, stakedBalances[account][subaccount][positionId]);
    }
    
    function getValue(address account, address subaccount, bytes32 positionId) external view override returns (uint256) {
        uint256 lpBalance = stakedBalances[account][subaccount][positionId];
        if (lpBalance == 0) return 0;
        
        // Calculate LP token value
        uint256 lpValue = _calculateLPValue(lpBalance);
        
        // Add pending rewards value
        uint256 rewardsValue = _calculatePendingRewards(account, subaccount, positionId);
        
        return lpValue + rewardsValue;
    }
    
    // Custom interaction: claim rewards
    function customInteraction(address account, address subaccount, bytes calldata data) 
        external override onlyAuthorized(account) returns (bytes memory) 
    {
        bytes4 selector = bytes4(data);
        
        if (selector == this.claimRewards.selector) {
            // Decode position ID from data
            bytes32 positionId = abi.decode(data[4:], (bytes32));
            
            // Claim rewards from gauge
            address[] memory rewards = IAerodromeGauge(gauge).getReward(address(this));
            
            // Return claimed amounts
            return abi.encode(rewards);
        }
        
        revert CustomInteractionNotSupported(account, subaccount, data);
    }
    
    function claimRewards(bytes32) external pure returns (address[] memory) {
        // Placeholder for ABI generation
        revert("Use customInteraction");
    }
}

---

Position ID Semantics

Position IDs serve different purposes depending on asset type:

Fungible Assets (ERC20/ERC4626)

Standard 2-position model:

// From FluxConstants
bytes32 constant WORKING_CAPITAL_POS_ID = bytes32(0);  // Active trading capital
bytes32 constant BOND_POS_ID = bytes32(1);             // Posted collateral

Strict enforcement in ERC20AssetWrapper and ERC4626AssetWrapper:

function _validatePositionId(bytes32 positionId) private pure {
    if (positionId != WORKING_CAPITAL_POS_ID && positionId != BOND_POS_ID) {
        revert InvalidPositionId();
    }
}

Why? Prevents "ghost collateral" - assets deposited to positions not valued by strategies.

NFT Assets (Uniswap V3, etc.)

Use token ID as position ID:

// Deposit NFT with tokenId = 12345
bytes32 positionId = bytes32(uint256(12345));
vault.locked_depositToWrapper(uniV3Wrapper, positionId, 1);

Multi-Position Assets

Use semantic identifiers:

// Different LP pools
bytes32 usdcEthPool = keccak256("aerodrome-usdc-eth");
bytes32 daiEthPool = keccak256("aerodrome-dai-eth");

vault.locked_depositToWrapper(aeroWrapper, usdcEthPool, lpAmount1);
vault.locked_depositToWrapper(aeroWrapper, daiEthPool, lpAmount2);

Best Practices

1. Document position ID semantics clearly in your wrapper

2. Validate position IDs if using restricted model

3. Use descriptive IDs for multi-position wrappers

4. Ensure strategies understand your position ID scheme

---

Oracle Integration

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

Standard Pattern

contract MyWrapper {
    IFluxVaultFactory public immutable factory;
    
    function getValue(address account, address subaccount, bytes32 positionId) 
        external view returns (uint256) 
    {
        uint256 balance = balances[account][subaccount][positionId];
        if (balance == 0) return 0;
        
        // Get oracle registry from factory
        IOracleRegistry registry = factory.oracleRegistry();
        
        // Query USD value
        return registry.getValueUSD(underlyingAsset, balance);
    }
}

Multi-Asset Valuation

For positions with multiple underlying assets:

function getValue(address account, address subaccount, bytes32 positionId) 
    external view returns (uint256) 
{
    Position storage pos = positions[account][subaccount][positionId];
    
    IOracleRegistry registry = factory.oracleRegistry();
    
    // Calculate individual token amounts
    (uint256 amount0, uint256 amount1) = _getTokenAmounts(pos);
    
    // Price each asset
    uint256 value0 = registry.getValueUSD(token0, amount0);
    uint256 value1 = registry.getValueUSD(token1, amount1);
    
    return value0 + value1;
}

ERC4626 Pattern

Convert shares to underlying before pricing:

function getValue(address account, address subaccount, bytes32 positionId) 
    external view returns (uint256) 
{
    uint256 shares = balances[account][subaccount][positionId];
    if (shares == 0) return 0;
    
    // Convert shares to underlying (e.g., sDAI → DAI)
    uint256 underlyingAmount = IERC4626(asset).previewRedeem(shares);
    
    // Price underlying asset
    IOracleRegistry registry = factory.oracleRegistry();
    address underlying = IERC4626(asset).asset();
    
    return registry.getValueUSD(underlying, underlyingAmount);
}

---

Security Model

Namespace Isolation

Each vault operates in isolated namespace:

// VaultA's positions are completely separate from VaultB's
balances[vaultA][manager1][positionId] = 100e18
balances[vaultB][manager1][positionId] = 200e18

// Only vaultA can modify its positions
modifier onlyAuthorized(address account) {
    require(msg.sender == account);  // msg.sender must be the vault
    _;
}

Access Control Pattern

// ❌ WRONG - allows anyone to deposit
function deposit(address account, address subaccount, bytes32 positionId, uint256 amount) external {
    balances[account][subaccount][positionId] += amount;
}

// ✅ CORRECT - only vault can deposit to its namespace
function deposit(address account, address subaccount, bytes32 positionId, uint256 amount) external {
    require(msg.sender == account, "Unauthorized");
    balances[account][subaccount][positionId] += amount;
}

Use BaseAssetWrapper to get this right automatically!

Claim Validation

Prevent fake collateral attacks:

function _claim(address account, address subaccount, bytes32 positionId, uint256 amount) internal override {
    // CRITICAL: Verify actual unclaimed tokens exist
    uint256 wrapperBalance = IERC20(asset).balanceOf(address(this));
    uint256 unclaimedBalance = wrapperBalance - _totalTrackedBalance;
    
    require(amount <= unclaimedBalance, "Insufficient unclaimed balance");
    
    balances[account][subaccount][positionId] += amount;
    _totalTrackedBalance += amount;
}

Reentrancy Protection

For complex interactions:

import {ReentrancyGuard} from "@openzeppelin/contracts/security/ReentrancyGuard.sol";

contract MyWrapper is BaseAssetWrapper, ReentrancyGuard {
    function _deposit(...) internal override nonReentrant {
        // Complex interactions with external contracts
    }
}

---

Example Implementations

Example 1: Rebasing Token Wrapper (stETH)

contract StETHWrapper is SimpleFungibleWrapper {
    address public constant STETH = 0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84;
    IFluxVaultFactory public immutable factory;
    
    // Track shares instead of balances (rebasing-resistant)
    mapping(address => mapping(address => mapping(bytes32 => uint256))) public shares;
    
    constructor(IFluxVaultFactory _factory) {
        factory = _factory;
    }
    
    function _deposit(address account, address subaccount, bytes32 positionId, uint256 amount) internal override {
        _validatePositionId(positionId);
        
        // Transfer stETH
        uint256 sharesBefore = IStETH(STETH).sharesOf(address(this));
        SafeERC20.safeTransferFrom(IERC20(STETH), msg.sender, address(this), amount);
        uint256 sharesAfter = IStETH(STETH).sharesOf(address(this));
        
        // Track shares, not tokens (immune to rebasing)
        uint256 receivedShares = sharesAfter - sharesBefore;
        shares[account][subaccount][positionId] += receivedShares;
        
        emit Deposited(account, subaccount, positionId, amount, getBalance(account, subaccount, positionId));
    }
    
    function getBalance(address account, address subaccount, bytes32 positionId) public view returns (uint256) {
        // Convert shares to current token balance
        uint256 posShares = shares[account][subaccount][positionId];
        return IStETH(STETH).getPooledEthByShares(posShares);
    }
    
    function getValue(address account, address subaccount, bytes32 positionId) external view returns (uint256) {
        uint256 ethAmount = getBalance(account, subaccount, positionId);
        if (ethAmount == 0) return 0;
        
        IOracleRegistry registry = factory.oracleRegistry();
        return registry.getValueUSD(STETH, ethAmount);
    }
}

Example 2: Synthetic Asset Wrapper (Synthetix sUSD)

contract SynthetixWrapper is SimpleFungibleWrapper {
    ISynthetix public immutable synthetix;
    bytes32 public immutable currencyKey;  // e.g., "sUSD", "sETH"
    IFluxVaultFactory public immutable factory;
    
    mapping(address => mapping(address => mapping(bytes32 => uint256))) public balances;
    
    constructor(address _synthetix, bytes32 _currencyKey, IFluxVaultFactory _factory) {
        synthetix = ISynthetix(_synthetix);
        currencyKey = _currencyKey;
        factory = _factory;
    }
    
    function _deposit(address account, address subaccount, bytes32 positionId, uint256 amount) internal override {
        address synth = synthetix.synths(currencyKey);
        SafeERC20.safeTransferFrom(IERC20(synth), msg.sender, address(this), amount);
        balances[account][subaccount][positionId] += amount;
        emit Deposited(account, subaccount, positionId, amount, balances[account][subaccount][positionId]);
    }
    
    function getValue(address account, address subaccount, bytes32 positionId) external view returns (uint256) {
        uint256 balance = balances[account][subaccount][positionId];
        if (balance == 0) return 0;
        
        // Synthetix tracks its own prices
        uint256 synthPrice = synthetix.exchangeRates().rateForCurrency(currencyKey);
        
        // Convert to USD (assuming USD is base unit)
        return balance * synthPrice / 1e18;
    }
    
    // Custom interaction: exchange between synths
    function customInteraction(address account, address subaccount, bytes calldata data) 
        external override onlyAuthorized(account) returns (bytes memory) 
    {
        bytes4 selector = bytes4(data);
        
        if (selector == this.exchange.selector) {
            (bytes32 positionId, bytes32 destCurrency, uint256 amount) = 
                abi.decode(data[4:], (bytes32, bytes32, uint256));
            
            // Exchange synth within wrapper
            uint256 received = synthetix.exchange(currencyKey, amount, destCurrency);
            
            return abi.encode(received);
        }
        
        revert CustomInteractionNotSupported(account, subaccount, data);
    }
}

---

Testing Your Wrapper

Unit Test Template

contract MyWrapperTest is Test {
    MyWrapper wrapper;
    MockERC20 asset;
    MockVault vault;
    address manager;
    
    function setUp() public {
        asset = new MockERC20("Test", "TEST", 18);
        wrapper = new MyWrapper(address(asset), factory);
        vault = new MockVault();
        manager = makeAddr("manager");
    }
    
    function test_deposit_success() public {
        uint256 amount = 100e18;
        bytes32 positionId = bytes32(0);
        
        // Setup
        asset.mint(address(vault), amount);
        vm.startPrank(address(vault));
        asset.approve(address(wrapper), amount);
        
        // Deposit
        wrapper.deposit(address(vault), manager, positionId, amount);
        
        // Verify
        assertEq(wrapper.getBalance(address(vault), manager, positionId), amount);
        assertEq(asset.balanceOf(address(wrapper)), amount);
    }
    
    function test_deposit_unauthorized() public {
        vm.expectRevert();
        vm.prank(manager);  // manager tries to deposit directly
        wrapper.deposit(address(vault), manager, bytes32(0), 100e18);
    }
    
    function test_withdraw_success() public {
        // Deposit first
        test_deposit_success();
        
        // Withdraw
        vm.prank(address(vault));
        wrapper.withdraw(address(vault), manager, bytes32(0), manager, 50e18);
        
        // Verify
        assertEq(wrapper.getBalance(address(vault), manager, bytes32(0)), 50e18);
        assertEq(asset.balanceOf(manager), 50e18);
    }
    
    function test_getValue_withOracle() public {
        // Setup oracle
        vm.mockCall(
            address(oracleRegistry),
            abi.encodeWithSelector(IOracleRegistry.getValueUSD.selector),
            abi.encode(1000e18)  // $1000 per token
        );
        
        // Deposit
        test_deposit_success();
        
        // Check value
        uint256 value = wrapper.getValue(address(vault), manager, bytes32(0));
        assertEq(value, 100_000e18);  // 100 tokens * $1000 = $100k
    }
}

Integration Test with Real Vault

function test_integration_withRealVault() public {
    // Deploy real vault
    FluxVault vault = fluxVaultFactory.createVault(
        baseAsset,
        baseAssetWrapper,
        strategy,
        accessPolicy,
        "Test Vault",
        "TV"
    );
    
    // Manager deposits via vault
    vm.startPrank(manager);
    vault.unlock(abi.encode("deposit", address(wrapper), 100e18));
    vm.stopPrank();
    
    // Verify position tracked correctly
    assertGt(wrapper.getValue(address(vault), manager, WORKING_CAPITAL_POS_ID), 0);
}

---

Deployment & Integration

Step 1: Deploy Wrapper

For vanilla wrappers, use AssetWrapperFactory:

// Deploy via factory (for standard ERC20/ERC4626)
address wrapper = assetWrapperFactory.deployERC20Wrapper(tokenAddress);

For custom wrappers, deploy directly:

// Deploy custom wrapper
MyCustomWrapper wrapper = new MyCustomWrapper(asset, factory);

Step 2: Whitelist with Governance

// Governance whitelists the wrapper
fluxVaultFactory.whitelistAsset(address(wrapper));

Step 3: Include in Strategy

// Strategy creator includes wrapper in allowlist
address[] memory allowedAssets = [
    wethWrapper,
    usdcWrapper,
    myCustomWrapper  // Your new wrapper
];

address strategy = strategyFactory.deployImmutableStrategy(
    allowedAssets,
    params,
    factory
);

Step 4: Test with Real Vault

// Create vault using strategy with your wrapper
address vault = fluxVaultFactory.createVault(
    baseAsset,
    baseAssetWrapper,
    strategy,
    accessPolicy,
    "My Vault",
    "MV"
);

// Manager can now use your wrapper

---

Best Practices

DO

1. Extend BaseAssetWrapper - Don't reimplement access control

2. Use SimpleFungibleWrapper for standard fungible assets

3. Validate position IDs if using restricted model

4. Handle type(uint256).max in withdraw for "withdraw all"

5. Measure actual balance changes for fee-on-transfer tokens

6. Track shares for rebasing tokens (stETH, aTokens)

7. Validate claim amounts against actual unclaimed balance

8. Document position ID semantics clearly

9. Test thoroughly with unit and integration tests

10. Gas optimize - wrappers are called frequently

DON'T

1. Don't skip access control - use onlyAuthorized modifier

2. Don't store prices - always query Oracle Registry

3. Don't allow cross-account transfers without authorization

4. Don't assume token balances - always measure actual transfers

5. Don't ignore rebasing - use shares for rebasing tokens

6. Don't hardcode decimals - query from token contract

7. Don't skip edge cases - test zero amounts, max withdrawals

8. Don't forget events - emit for all state changes

9. Don't implement custom oracles in wrapper - use registry

10. Don't make upgradeable - wrappers should be immutable

Security Checklist

• Access control on all state-changing functions

• Namespace isolation enforced (msg.sender == account)

• Claim validation against actual wrapper balance

• Reentrancy protection for external calls

• Integer overflow protection (Solidity 0.8+)

• Position existence checks before operations

• Proper event emission for indexing

• Gas optimization for frequent operations

• Comprehensive test coverage (>90%)

• Oracle integration tested with mocks

Gas Optimization Tips

// ✅ GOOD: Pack storage
struct Position {
    uint128 balance;     // Pack multiple values in one slot
    uint64 lastUpdate;
    uint64 reserved;
}

// ✅ GOOD: Cache storage reads
function _withdraw(...) internal {
    uint256 balance = balances[account][subaccount][positionId];  // Cache
    if (amount == type(uint256).max) amount = balance;
    balances[account][subaccount][positionId] = balance - amount;  // Write once
}

// ❌ BAD: Multiple storage reads
function _withdraw(...) internal {
    if (amount == type(uint256).max) amount = balances[...];
    balances[...] = balances[...] - amount;  // Read twice, write once
}

// ✅ GOOD: Use immutable for constants
IFluxVaultFactory public immutable factory;

// ❌ BAD: Use storage for constants
IFluxVaultFactory public factory;

---

Common Pitfalls & Solutions

Pitfall 1: Ghost Collateral

Problem: Manager deposits to non-standard position ID, strategy doesn't value it

// Manager deposits to custom position
vault.locked_depositToWrapper(wrapper, keccak256("my-position"), 100e18);

// Strategy only values WORKING_CAPITAL and BOND positions → 0 value!

Solution: Validate position IDs in fungible wrappers

function _validatePositionId(bytes32 positionId) private pure {
    if (positionId != WORKING_CAPITAL_POS_ID && positionId != BOND_POS_ID) {
        revert InvalidPositionId();
    }
}

Pitfall 2: Rebasing Token Accounting

Problem: Token balance changes without transfers (stETH, aTokens)

// ❌ BAD: Track balances directly
balances[account][subaccount][positionId] = amount;  // Will drift!

Solution: Track shares, not balances

// ✅ GOOD: Track shares
uint256 sharesBefore = IStETH(token).sharesOf(address(this));
// ... transfer ...
uint256 sharesAfter = IStETH(token).sharesOf(address(this));
shares[account][subaccount][positionId] += sharesAfter - sharesBefore;

// Convert shares to balance when needed
function getBalance(...) public view returns (uint256) {
    return IStETH(token).getPooledEthByShares(shares[...]);
}

Pitfall 3: Fee-on-Transfer Tokens

Problem: safeTransferFrom(amount) doesn't guarantee amount received

// BAD: Assume amount received
SafeERC20.safeTransferFrom(token, from, to, amount);
balances[...] += amount;  // Wrong if token has transfer fee!

Solution: Measure actual balance change

// GOOD: Measure actual received
uint256 balanceBefore = IERC20(token).balanceOf(address(this));
SafeERC20.safeTransferFrom(token, from, address(this), amount);
uint256 balanceAfter = IERC20(token).balanceOf(address(this));
uint256 actualReceived = balanceAfter - balanceBefore;
balances[...] += actualReceived;

Pitfall 4: Unimplemented ledgerTransferSubaccount

Problem: Liquidations fail because subaccount can't be transferred

Solution: Implement proper subaccount enumeration

// For SimpleFungibleWrapper: automatically handled
// For custom wrappers: implement enumeration logic

function _ledgerTransferSubaccount(address account, address from, address to) internal override {
    // Option 1: Track position IDs per subaccount
    bytes32[] storage positionIds = subaccountPositions[account][from];
    for (uint i = 0; i < positionIds.length; i++) {
        _transferPosition(account, from, positionIds[i], account, to, positionIds[i], type(uint256).max);
    }
    
    // Option 2: Iterate known positions (if finite)
    // Option 3: Use events to reconstruct position list off-chain
}

---

Further Reading

• Wrapper Concepts

• Deploying Wrappers

• Oracle Integration

• Strategy Integration