HyperEVM Cross-chain Flow

This document details the cross-chain bridging process from the source chain (Ethereum) to HyperEVM using HyperStrategy and Circle CCTP V2, as well as the internal allocation inside HyperEVM.

Cross-chain Invest: Source Chain To HyperEVM

sequenceDiagram
    participant Controller
    participant HyperStrategy
    participant CCTP
    participant Allocator as HyperCoreAllocator

    Controller->>HyperStrategy: invest(amount)
    HyperStrategy->>CCTP: depositForBurn(amount, HyperEVM, allocator)
    HyperStrategy->>HyperStrategy: processingAssets += amount
    Allocator->>Allocator: handleInvestMessage(message, attestation)
    Allocator->>CCTP: receiveMessage()
    Allocator->>Allocator: mint internal shares
    Allocator->>CCTP: send state message back
    HyperStrategy->>HyperStrategy: completeInvest/updateRemoteState

Key State Tracking

Contract	Field	Meaning
HyperStrategy	_processingAssets	Source-chain assets burned and waiting for HyperEVM confirmation.
HyperCoreAllocator	totalSupply	Internal shares representing source-chain ownership of HyperEVM assets.
HyperStrategy	_totalAssets, _totalSupply	Latest confirmed remote allocator state.

Cross-chain Divest: HyperEVM To Source Chain

sequenceDiagram
    participant Controller
    participant HyperStrategy
    participant CCTP
    participant Allocator

    Controller->>HyperStrategy: divest(amount)
    HyperStrategy->>HyperStrategy: convert amount to remote shares
    HyperStrategy->>CCTP: sendMessage(RedeemMessage(shares))
    Allocator->>Allocator: queue pendingRedeemShares
    Keeper->>Allocator: executeRedeem(sharesToRedeem)
    Allocator->>CCTP: depositForBurnWithHook(amount, source, state hook)
    Keeper->>HyperStrategy: completeDivest(message, attestation)
    HyperStrategy->>HyperStrategy: update remote state from hook
    HyperStrategy-->>Vault: transfer source-chain assets to receiver

[!NOTE] HyperStrategy.replenish() is intentionally unsupported and always reverts with FunctionNotSupported(). This means the synchronous vault liquidity waterfall cannot pull partial liquidity from HyperStrategy. HyperStrategy divestment is fully asynchronous through CCTP.

HyperCore Allocation Flow

HyperCoreAllocator (on HyperEVM) can hold idle HyperEVM assets and allocate assets to registered routers. A router is responsible for actual HyperCore L1/HLP precompile operations.

sequenceDiagram
    participant Keeper
    participant Allocator
    participant Router
    participant HyperCore

    Keeper->>Allocator: allocate(routerIdx, amount)
    Allocator-->>Router: transfer asset
    Keeper->>Router: depositToSpot(amount)
    Router->>HyperCore: CoreDepositWallet.deposit
    Keeper->>Router: spotToPerp(amount)
    Router->>HyperCore: USD_CLASS_TRANSFER
    Keeper->>Router: perpToVault(amount)
    Router->>HyperCore: VAULT_TRANSFER into HLP

Reverse Allocation (Collection)

1. The Keeper calls router.vaultToPerp(amount).
2. The Keeper calls router.perpToSpot(amount).
3. The Keeper calls router.withdrawFromSpot(amount).
4. After the ERC-20 asset is back on the router, the Keeper calls allocator.collect(routerIdx, amount).
5. The Router approves the allocator via approveOnlyForAllocator().
6. The Allocator pulls the assets back.