HyperCore Execution

This section covers the HyperEVM execution contracts used by the V2 HLP product: the Allocator and the Router. It does not describe the per-user GHO Staking architecture.

Before integration or administration, verify the listed signatures and permissions against the deployed implementation and its verified source. See Documentation scope and verification.

HyperCoreAllocator

Source: src/strategies/hyperevm/HyperCoreAllocator.sol

The Allocator resides on the HyperEVM. It receives bridged assets via CCTP, mints internal shares to track the source chain's ownership, and distributes capital to routers.

Public And External Functions

Function	Access	Description
`initialize(...)`	initializer	Initializes allocator proxy, stores asset, receiver domain, receiver, manager, CCTP contracts, decimals offset.
`asset()`	public view	Returns HyperEVM asset.
`receiver()`	public view	Returns source-chain CCTP receiver domain and address.
`manager()`	public view	Returns harvest/exit recipient.
`totalAssets()`	public view	Returns allocator idle asset plus all router assets.
`idleAssets()`	public view	Returns asset balance held by allocator.
`totalSupply()`	public view	Returns allocator internal share supply.
`pendingRedeemShares()`	public view	Returns shares queued for cross-chain redemption.
`pendingRedeemAssets()`	public view	Converts pending redeem shares to assets.
`routers()`	public view	Returns registered router list.
`addRouter(address router)`	Developer	Registers router. Emits `RouterAdded`.
`setCctpMaxFee(uint256 maxFee)`	Keeper	Sets max CCTP fee.
`allocate(uint256 routerIdx, uint256 amount)`	Keeper	Transfers idle asset to router.
`collect(uint256 routerIdx, uint256 amount)`	Keeper	Pulls asset back from router after router approval.
`executeRedeem(uint256 sharesToRedeem)`	Keeper	Burns queued internal shares and bridges assets back to source chain with state hook.
`sendState()`	Keeper	Sends current allocator state to source chain.
`handleInvestMessage(bytes message, bytes attestation)`	Keeper	Receives CCTP invest mint, mints internal shares, sends state response.
`handleDivestMessage(bytes message, bytes attestation)`	Keeper	Relays the CCTP redemption-request message; the finalized handler queues the requested internal shares. This request does not mint USDC.
`handleReceiveFinalizedMessage(...)`	CCTP MessageTransmitter only	Queues `RedeemMessage.shares` into pending redeem shares.
`handleReceiveUnfinalizedMessage(...)`	external pure	Accepts unfinalized message path and returns true.
`exit()`	Keeper	Transfers allocator idle asset to manager; does not unwind Router or HLP positions.
`harvest(IERC20 asset_)`	Keeper	Sweeps non-primary token to manager. Emits `Harvested`.

Internal Functions

Function	Description
`_getHyperCoreAllocatorStorage()`	Returns HyperCoreAllocator's ERC-7201 namespaced storage pointer.
`_authorizeUpgrade(address)`	UUPS authorization, Admin only.
`_sendState(uint256 processedAssets)`	Sends `UpdatedStateMessage` to source chain.
`_encodeStateMessage(...)`	Encodes nonce, timestamp, totals, processed assets/shares.
`_validateSource(...)`	Validates CCTP source domain and sender.
`_convertToShares(uint256 assets, Math.Rounding rounding)`	ERC-4626-style conversion for allocator internal shares.
`_convertToAssets(uint256 shares, Math.Rounding rounding)`	ERC-4626-style conversion for allocator internal shares.
`_addressToBytes32(address)`	Converts address to bytes32.
`_bytes32ToAddress(bytes32)`	Converts bytes32 to address.

HyperCoreRouter

Source: src/strategies/hyperevm/HyperCoreRouter.sol

The Router is deployed on HyperEVM. It reads balances and HLP equity through HyperCore read precompiles, and submits asset-movement actions through the CoreWriter system contract. A successful HyperEVM transaction does not by itself confirm that the corresponding HyperCore action has completed; operators must verify the resulting balances before continuing the allocation or withdrawal flow.

HLP withdrawals are subject to the underlying account's lockup, measured from its most recent HLP deposit. The Hyperliquid HLP documentation specifies a four-day lockup. This is not a guaranteed end-to-end withdrawal time for a King's Vault investor: Router execution, available liquidity, CCTP attestation, and relaying must also complete. See Cross-chain flow and HyperCore interaction timing.

Public And External Functions

Function	Access	Description
`receiver()`	public view	Returns parent allocator.
`asset()`	public view	Returns HyperEVM asset.
`totalAssets()`	public view	Returns router ERC-20 balance, spot balance, perp withdrawable balance, and HLP equity minus reserved fee.
`balance()`	public view	Returns ERC-20 asset held by router.
`balanceSpot()`	public view	Reads HyperCore spot balance precompile and converts wei to USD units.
`balancePerp()`	public view	Reads HyperCore withdrawable precompile.
`vaultEquity()`	public view	Reads HLP vault equity precompile and returns unlock status.
`depositToSpot(uint256 amount)`	Keeper	Deposits ERC-20 asset to CoreDepositWallet.
`spotToPerp(uint64 amount)`	Keeper	Submits a USD class transfer from spot to perp margin.
`perpToVault(uint64 amount)`	Keeper	Submits an HLP deposit action from perp margin.
`vaultToPerp(uint64 amount)`	Keeper	Submits an HLP withdrawal action to perp margin, subject to HyperCore withdrawal conditions.
`perpToSpot(uint64 amount)`	Keeper	Submits a USD class transfer from perp margin to spot.
`withdrawFromSpot(uint64 amount)`	Keeper	Submits a spot-send action to the asset's system address; verify the Router's ERC-20 receipt before collection.
`harvest(IERC20 asset_)`	Keeper	Sweeps non-primary token to allocator.
`approveOnlyForAllocator()`	Allocator only	Approves allocator to pull router's ERC-20 asset balance.

Internal Functions

Function	Description
`_transferUsdClass(uint64 ntl, bool toPerp)`	Sends HyperCore USD class transfer raw action.
`_spotSend(address to, uint64 token, uint64 amountWei)`	Sends HyperCore spot send raw action.
`_vaultTransfer(address vault, bool isDeposit, uint64 amountUsd)`	Sends HyperCore vault transfer raw action.
`_weiToUsd(uint64 amountWei)`	Converts HyperCore wei-style amount to 6-decimal USD unit.
`_usdToWei(uint64 amountUsd)`	Converts 6-decimal USD unit to HyperCore wei-style amount.