State Management & Operations

1. Request States

State Mappings

// Deposit States
mapping(address => ERC7540_Request) private _pendingDepositRequest;
mapping(address => ERC7540_FilledRequest) private _claimableDepositRequest;

// Withdrawal States
mapping(address => ERC7540_Request) private _pendingRedeemRequest;
mapping(address => ERC7540_FilledRequest) private _claimableRedeemRequest;

// Locks & Tracking
mapping(address => bool) public redeemLocked;
mapping(address => uint256) internal _depositLockCheckPoint;

State Transitions

2. Deposit Flow (Atomic)

Process Detail

// 1. Request Creation
function requestDeposit(
    uint256 assets,
    address controller,
    address owner
) public returns (uint256 requestId) {
    // Validate conditions
    require(!emergencyShutdown, "Shutdown");
    require(assets > 0, "Zero amount");
    
    // Transfer assets
    asset().safeTransferFrom(owner, address(this), assets);
    
    // Create request (immediately fulfilled)
    _fulfillDepositRequest(controller, assets, convertToShares(assets));
}

// 2. Deposit Execution
function deposit(
    uint256 assets,
    address to,
    address controller
) public returns (uint256 shares) {
    // Validate claimable amount
    require(assets <= maxDeposit(controller), "Exceeds max");
    
    // Process deposit
    shares = _processDeposit(assets, to, controller);
    
    // Update accounting
    _afterDeposit(assets, shares);
}

Atomic Execution Benefits

1. Prevents front-running

2. Ensures consistent state

3. Reduces gas costs

4. Simplifies error handling

3. Withdrawal Flow (4-Step)

Step 1: Request Creation

function requestRedeem(
    uint256 shares,
    address controller,
    address owner
) public returns (uint256 requestId) {
    // Validate lock status
    _checkSharesLocked(controller);
    
    // Create pending request
    _pendingRedeemRequest[controller] = 
        _pendingRedeemRequest[controller].add(shares);
    
    // Lock redemption
    redeemLocked[controller] = true;
    
    // Transfer shares to vault
    _transfer(owner, address(this), shares);
}

Step 2: Request Processing

function processRedeemRequest(
    address controller,
    /*withdraw configs*/
) external {
    // Load cache
    ProcessRedeemRequestCache memory cache;
    cache.assets = convertToAssets(shares);
    
    // Check idle assets
    if (_totalIdle >= cache.assets) {
        // Direct fulfillment
        cache.totalClaimableWithdraw = cache.assets;
    } else {
        // Calculate withdrawal route
        cache.amountToWithdraw = cache.assets - _totalIdle;
        _prepareWithdrawalRoute(cache);
        
        // Process withdrawals
        _processWithdrawals(cache);
    }
    
    // Update states
    _updateRedeemStates(controller, cache);
}

Step 3: Settlement

function settleLiquidation(
    address controller,
    uint256[] calldata superformIds
) external {
    // Receive assets
    uint256 settledAssets = _receiveAssets();
    
    // Move to claimable state
    _moveToClaimable(controller, settledAssets);
    
    // Update accounting
    _updateVaultAccounting(settledAssets);
}

Step 4: Final Redemption

function redeem(
    uint256 shares,
    address receiver,
    address controller
) public returns (uint256 assets) {
    // Verify processing complete
    require(!redeemLocked[controller], "Not processed");
    
    // Check claimable amount
    require(shares <= maxRedeem(controller), "Exceeds max");
    
    // Process redemption
    assets = _processRedemption(shares, receiver, controller);
    
    // Clear state
    _clearRedeemRequest(controller);
}

4. Investment Operations

Local Investment State Management

struct InvestmentState {
    uint128 totalIdle;      // Unallocated assets
    uint128 totalDebt;      // Allocated assets
    mapping(uint256 => VaultData) vaultData;
}

Direct Investment Flow

Cross-Chain Investment State Tracking

// Gateway State Tracking
mapping(uint256 => uint256) public pendingXChainInvests;
uint256 public totalpendingXChainInvests;

// Investment Processing
function investSingleXChainSingleVault(
    SingleXChainSingleVaultStateReq memory req
) external payable {
    // Pre-investment state
    uint256 preInvestIdle = _totalIdle;
    
    // Track pending investment
    pendingXChainInvests[req.superformData.superformId] += amount;
    totalpendingXChainInvests += amount;
    
    // Update vault state
    _totalIdle -= amount;
    
    // Initiate cross-chain transfer
    gateway.investSingleXChainSingleVault{value: msg.value}(req);
}

5. Cross-Chain Management

Bridge Communication Flow

Settlement Processing

function settleXChainInvest(
    uint256 superformId, 
    uint256 bridgedAssets
) public {
    // Verify caller
    require(msg.sender == address(gateway), "Only Gateway");
    
    // Update accounting
    _totalDebt += bridgedAssets;
    vaults[superformId].totalDebt += bridgedAssets;
    
    // Clear pending state
    pendingXChainInvests[superformId] = 0;
    totalpendingXChainInvests -= bridgedAssets;
    
    emit SettleXChainInvest(superformId, bridgedAssets);
}

Cross-Chain Position Management

// NFT (Superform Position) Handling
interface ISuperPositions {
    function balanceOf(address, uint256) external view returns (uint256);
    function safeTransferFrom(address, address, uint256, uint256, bytes calldata) external;
}

// Position Tracking
function _sharesBalance(VaultData memory data) internal view returns (uint256) {
    if (data.chainId == THIS_CHAIN_ID) {
        return ERC4626(data.vaultAddress).balanceOf(address(this));
    } else {
        return gateway.balanceOf(address(this), data.superformId);
    }
}

6. Error Handling & Recovery

Error States

error InsufficientAssets();
error InsufficientGas();
error VaultNotListed();
error RequestNotSettled();
error SharesLocked();
error VaultShutdown();

Recovery Mechanisms

// Emergency Controls
function setEmergencyShutdown(bool _emergencyShutdown) external {
    require(hasRole(EMERGENCY_ADMIN_ROLE, msg.sender), "Not admin");
    emergencyShutdown = _emergencyShutdown;
    emit EmergencyShutdown(_emergencyShutdown);
}

// Asset Recovery
function recoverAssets(
    address token,
    address recipient,
    uint256 amount
) external {
    require(hasRole(ADMIN_ROLE, msg.sender), "Not admin");
    require(recipient == recoveryAddress, "Invalid recipient");
    
    if (token == address(0)) {
        payable(recipient).transfer(amount);
    } else {
        IERC20(token).safeTransfer(recipient, amount);
    }
}

Cross-Chain Failure Handling

// Gateway Recovery
function handleFailedMessage(
    uint256 superformId,
    bytes memory failureData
) external {
    require(msg.sender == address(gateway), "Only Gateway");
    
    // Reverse pending states
    uint256 failedAmount = pendingXChainInvests[superformId];
    pendingXChainInvests[superformId] = 0;
    totalpendingXChainInvests -= failedAmount;
    
    // Return assets to idle
    _totalIdle += failedAmount;
    
    emit CrossChainFailure(superformId, failedAmount);
}

7. Security Considerations

State Consistency

• Atomic state updates

• Lock mechanisms

• Balance reconciliation

Cross-Chain Security

• Message verification

• Timeout handling

• Slippage protection

Access Control

• Role-based permissions

• Time locks

• Emergency procedures