Hyperliquid & LayerZero Composer - Core Concepts

​

1. Introduction to Hyperliquid

​

HyperCore

​

HyperEVM

​

Block Explorers:

​

2. Hyperliquid API

curl -X POST https://api.hyperliquid-testnet.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type": "spotMeta"}'

{
  "universe": [
    {
      "name": "ALICE",
      "szDecimals": 0,
      "weiDecimals": 6,
      "index": 1231,
      "tokenId": "0x503e1e612424896ec6e7a02c7350c963",
      "isCanonical": false,
      "evmContract": null,
      "fullName": null,
      "deployerTradingFeeShare": "1.0"
    }
  ]
}

• The tokenId is the address of the token on HyperCore.
• The evmContract is the address of the ERC20 token on HyperEVM.
• The deployerTradingFeeShare is the fee share for the deployer of the token.

​

3. HyperCore Actions

# add ethers-v6 to your project as an alias for ethers@^6.13.5
pnpm add ethers-v6@npm:ethers@^6.13.5

import {Wallet} from 'ethers'; // ethers-v5 wallet
import {Wallet as ethersV6Wallet} from 'ethers-v6'; // ethers-v6 wallet

const signerv6 = new ethersV6Wallet(wallet.privateKey); // where wallet is an ethers.Wallet from ethers-v5
const signature = await signerv6.signTypedData(domain, types, message);

Experimental feature (this method name will change) This is still an experimental feature. If using it, please specify the exact version of ethers you are using (e.g. spcify “5.0.18”, not “^5.0.18”) as the method name will be renamed from _signTypedData to signTypedData once it has been used in the field a bit.

​

4. Accounts

​

5. Multi-Block Architecture

​

HyperEVM Blocks

• Small Blocks: Default, 1-second block time, 2M gas limit. For high throughput transactions. OFT deployments are typically larger than 2M gas.
• Big Blocks: 1 transaction per block, 1 block per minute, 30M gas limit. For deploying large contracts.

{"type": "evmUserModify", "usingBigBlocks": true}

npx @layerzerolabs/hyperliquid-composer set-block --size big --network mainnet --private-key $PRIVATE_KEY

​

HyperCore Blocks

[Core] → [Core] → [EVM-small] → [Core] → [Core] → [EVM-small] → [Core] → [EVM-large] → [Core] → [EVM-small]

​

6. Precompiles and System Contracts

• 0x2222222222222222222222222222222222222222: System contract address for the HYPE token.
• 0x200000000000000000000000000000000000abcd: System contract address for a created Core Spot token (asset bridge).
• 0x3333333333333333333333333333333333333333: The CoreWriter for sending transactions to HyperCore.

• 0x0000000000000000000000000000000000000801: SpotBalance precompile for reading token balances
• 0x0000000000000000000000000000000000000810: CoreUserExists precompile for checking account activation

• spotBalance(address user, uint64 token): Returns balance information for a user’s token holdings on HyperCore
• coreUserExists(address user): Checks if a user account is activated on HyperCore
• CoreWriter: Writes to the first produced HyperCore block after the production of the EVM block

​

7. Token Standards

• Token standard on HyperEVM: ERC20 (EVM Spot)
• Token standard on HyperCore: HIP-1 (Core Spot)

​

8. The Asset Bridge: Linking EVM Spot (ERC20) and Core Spot (HIP-1)

1. requestEvmContract: Initiated by the HyperCore deployer, signaling intent to link HIP-1 to an ERC20.
2. finalizeEvmContract: Initiated by the HyperEVM deployer (EOA) to confirm the link.

• To send tokens from HyperEVM to HyperCore: Transfer ERC20 tokens to its asset bridge address on HyperEVM.
• To send tokens from HyperCore to HyperEVM: Use the spotSend L1 action, targeting the asset bridge address on HyperCore.

1. Initial state: [AssetBridgeEVM: 0 | AssetBridgeCore: 0]
2. Fund HyperCore bridge: [AssetBridgeEVM: 0 | AssetBridgeCore: X]
3. User bridges X*scale tokens from EVM to Core: User sends X*scale ERC20 to EVM bridge.
4. New state: [AssetBridgeEVM: X*scale | AssetBridgeCore: 0]

​

9. Communication between HyperEVM and HyperCore

• HyperEVM reads state from HyperCore: Via precompiles (e.g., perp positions).
• HyperEVM writes to HyperCore: Via events at specific precompile addresses AND by transferring tokens through the asset bridge.

​

10. Transfers between HyperEVM and HyperCore

1. Send tokens to the asset bridge address (0x2000...abcd) on the source network (HyperEVM or HyperCore).
   • On HyperEVM, this is an ERC20::transfer(assetBridgeAddress, value)
   • The event emitted is Transfer(address from, address to, uint256 value) → Transfer(_from, assetBridgeAddress, value);
   • The Transfer event is picked up by Hyperliquid’s backend.
2. The tokens are credited to your account on the destination network.
3. Then, on the destination network, send tokens from your address to the final receiver’s address.

​

11. Hyperliquid Composer

1. A LayerZero message sends tokens to Hyperliquid. lzReceive on the OFT on HyperEVM mints tokens to the HyperLiquidComposer contract address.
2. The composeMsg in SendParam (from the source chain call) contains the actual receiver’s address on Hyperliquid.
3. The HyperLiquidComposer’s lzCompose function is triggered.
4. The Composer:
   • Transfers the received EVM Spot tokens (ERC20) from itself to the token’s asset bridge address (0x2000...abcd). This Transfer event signals Hyperliquid’s backend to credit the tokens on HyperCore.
   • Performs an CoreWriter transaction (to 0x33...33) instructing HyperCore to execute a spot transfer of the corresponding HIP-1 tokens from the Composer’s implied Core address (derived from its EVM address) to the actual receiver’s address (from composeMsg) on HyperCore.

struct SendParam {
    uint32 dstEid;
    bytes32 to; // OFT address (so that the OFT can execute the `compose` call)
    uint256 amountLD;
    uint256 minAmountLD;
    bytes extraOptions;
    bytes composeMsg; // token receiver address (msg.sender if you want your address to receive the token)
    bytes oftCmd;
}

contract HyperLiquidComposer is HyperLiquidCore, ReentrancyGuard, IHyperLiquidComposer, IOAppComposer {
    constructor(
        address _oft,           // The OFT contract address
        uint64 _coreIndexId,    // Core Spot token's index ID
        int8 _assetDecimalDiff  // Decimal difference: EVM decimals - Core decimals
    ) {
        // Automatically configures both ERC20 and native HYPE support
        // Uses precompiles for direct HyperCore interaction
    }

    function lzCompose(address _oft, bytes32 _guid, bytes calldata _message, address _executor, bytes calldata _extraData) external payable override {
        // Error handling with failedMessages mapping
        // Direct precompile calls for HyperCore interaction
        // Built-in activation checks and refund mechanisms
    }
}

​

12. LayerZero Transaction on HyperEVM

1. OFT Delivery: The LayerZero message delivers tokens to the HyperLiquidComposer contract address on HyperEVM
2. Compose Message: The SendParam.composeMsg contains the final recipient’s address and any native HYPE amount needed
3. Automatic Bridging: The Composer’s lzCompose function automatically bridges tokens from HyperEVM to HyperCore and transfers them to the final recipient

// Encode the final recipient and optional HYPE amount
bytes memory composeMsg = abi.encode(
    uint256 minMsgValue,  // Minimum HYPE amount to send to recipient (0 if none)
    address receiver      // Final recipient address on HyperCore
);

1. Activation Check: Uses coreUserExists() precompile to verify receiver is activated on HyperCore
2. Bridge Capacity Check: Uses spotBalance() precompile to check asset bridge capacity
3. Dual Asset Support: Handles both ERC20 tokens and native HYPE transfers
4. Error Recovery: Failed messages are stored in failedMessages mapping for later refund

// Precompile-based approach
function lzCompose(address _oft, bytes32 _guid, bytes calldata _message, ...) external payable {
    // 1. Decode message with enhanced validation
    (uint256 minMsgValue, address receiver) = abi.decode(composeMsg, (uint256, address));

    // 2. Check activation status via precompile
    if (!coreUserExists(receiver).exists) revert CoreUserNotActivated();

    // 3. Check bridge capacity via precompile
    uint64 bridgeBalance = spotBalance(assetBridge, coreIndex).total;

    // 4. Transfer to asset bridge
    IERC20(token).safeTransfer(assetBridge, amounts.evm);

    // 5. Use CoreWriter precompile for HyperCore transfer
    _submitCoreWriterTransfer(receiver, coreIndex, amounts.core);
}

// Precompile-based CoreWriter call
function _submitCoreWriterTransfer(address _to, uint64 _coreIndex, uint64 _coreAmount) internal {
    bytes memory action = abi.encode(_to, _coreIndex, _coreAmount);
    bytes memory payload = abi.encodePacked(SPOT_SEND_HEADER, action); // Pre-computed header
    ICoreWriter(HLP_CORE_WRITER).sendRawAction(payload);
}

• Failed Message Storage: Messages that fail decoding are stored for crosschain refund
• Automatic Refunds: Failed transfers refund tokens to receiver on HyperEVM
• Gas Protection: Minimum gas requirements prevent out-of-gas failures
• Bridge Capacity Protection: Prevents token locking when bridge capacity is insufficient