> ## Documentation Index > Fetch the complete documentation index at: https://docs.layerzero.network/llms.txt > Use this file to discover all available pages before exploring further. # Deployment Guide - OFT on Hyperliquid with LayerZero Composer > This guide provides a step-by-step process for deploying your Omnichain Fungible Token (OFT) on Hyperliquid (both HyperEVM and HyperCore) using the... This guide provides a step-by-step process for deploying your Omnichain Fungible Token (OFT) on Hyperliquid (both HyperEVM and HyperCore) using the LayerZero Hyperliquid Composer and SDK. ## Prerequisites * **Understanding Core Concepts**: Ensure you've reviewed [Hyperliquid - Core Concepts](./hyperliquid-concepts). * **Software**: * Node.js, pnpm/npm/yarn. * `@layerzerolabs/hyperliquid-composer` SDK installed (`npx @layerzerolabs/hyperliquid-composer -h` to check). * Hardhat or Forge for contract deployment and scripting (examples use Hardhat and Forge). * **Accounts & Funding**: * An EVM-compatible wallet with a private key for deployments. * **Crucially**: Your deployer address must be activated on **HyperCore**. This typically means it needs to have received at least \$1 in `USDC` or `HYPE` on HyperCore. This is required for operations like block switching or deploying Core Spot assets, as these involve L1 actions. If not funded, you might see errors like `L1 error: User or API Wallet does not exist.` * **LayerZero Configuration**: A `layerzero.config.ts` file for your OApp. ## Hyperliquid Composer Deployment Checklist This checklist is a kind of cheat sheet and "table of contents" for anyone deploying to HyperEVM and HyperCore. The full guide is below and the checklist is just a quick reference, with links to sections in the full guide. ### Step 0: Deploy your OFT | Action | Performed by | Actionable with | Recommended for | | ------ | ------------ | ------------------------------------------------------------------------ | ------------------------- | | Path 1 | OFT Deployer | `LZ_ENABLE_EXPERIMENTAL_HYPERLIQUID_EXAMPLE=1 npx create-lz-oapp@latest` | HyperCore deployments | | Path 2 | OFT Deployer | Vanilla OFT repo + `npx @layerzerolabs/hyperliquid-composer` | Only HyperEVM deployments | * [ ] Activate your deployer account on HyperCore without burning a nonce on HyperEVM. Get someone to send at least **\$1** in `USDC` or `HYPE` to your deployer account on HyperCore, or get funds on a burner wallet on HyperEVM, transfer it across, and then transfer it to the deployer account. #### Path 1 - With a new repo * [ ] Create a new Hyperliquid example repo ```bash wrap theme={null} LZ_ENABLE_EXPERIMENTAL_HYPERLIQUID_EXAMPLE=1 npx create-lz-oapp@latest ``` * This comes with the composer and composer deploy script. * Deploy scripts perform block switching operations. * Composer can be deployed after the core spot is deployed ([Step 4](#step-4-deploy-the-hyperliquidcomposer-contract)). It will not work until the two are linked. * Composer has default error handling mentioned in [Modifying OFT/Composer Behavior & Error Handling](#modifying-oftcomposer-behavior--error-handling). #### Path 2 - Existing repo with OFT Block switching is not present in the default OFT deploy script. * [ ] Switch to big block before deploying the OFT ```bash wrap theme={null} npx @layerzerolabs/hyperliquid-composer set-block \ --size big \ --network \ --log-level verbose \ --private-key $PRIVATE_KEY ``` * [ ] Deploy the OFT * [ ] Switch to small block after deploying the OFT ```bash wrap theme={null} npx @layerzerolabs/hyperliquid-composer set-block \ --size small \ --network \ --log-level verbose \ --private-key $PRIVATE_KEY ``` If you are only doing `HyperEVM` deployment, you are done. The rest of the steps are only for `HyperCore` deployments. ### Step 1 (Optional): Purchase your HyperCore Spot | Action | Performed by | Actionable with | Required for | | ------------- | ----------------- | -------------------------------------------------------------------------------- | ------------ | | Purchase Spot | CoreSpot Deployer | [https://app.hyperliquid.xyz/deploySpot](https://app.hyperliquid.xyz/deploySpot) | `HyperCore` | | Blocked by | None | None | Step 2 | * [ ] Purchase your HyperCore Spot [engaging in the auction](https://hyperliquid.gitbook.io/hyperliquid-docs/hyperliquid-improvement-proposals-hips/hip-1-native-token-standard#gas-cost-for-deployment) ### Step 2: Deploy the Core Spot | Action | Performed by | Actionable with | Required for | | --------------- | ----------------- | ----------------------------------------- | ------------ | | Deploy CoreSpot | CoreSpot Deployer | `npx @layerzerolabs/hyperliquid-composer` | `HyperCore` | | Blocked by | OFT Deployer | Step 0 | Step 3 | | Blocked by | CoreSpot Deployer | Step 1 | Step 3 | * [ ] Deploy the CoreSpot following [Step 2: Deploy the Core Spot (HIP-1 Token)](#step-2-deploy-the-core-spot-hip-1-token) #### Step 2.1: Create a HyperCore deployment file | Action | Performed by | Actionable with | Required for | | -------------------------------- | ----------------- | ----------------------------------------- | ------------ | | Create HyperCore Deployment File | CoreSpot Deployer | `npx @layerzerolabs/hyperliquid-composer` | `HyperCore` | | Blocked by | OFT Deployer | Step 0 | Step 3 | | Blocked by | CoreSpot Deployer | Step 1 | Step 2.2 | * [ ] Follow the instuctions in [Step 2.1: Create a HyperCore Deployment File](#step-21-create-a-hypercore-deployment-file-core-spot-create) * [ ] Core spot deployer needs OFT address and deployed transaction hash #### Step 2.2: Set the user genesis | Action | Performed by | Actionable with | Required for | | ---------------- | ----------------- | ----------------------------------------- | ------------ | | Set User Genesis | CoreSpot Deployer | `npx @layerzerolabs/hyperliquid-composer` | `HyperCore` | | Blocked by | CoreSpot Deployer | Step 2.1 | Step 2.4 | * [ ] Follow the instructions in [Step 2.2: Set User Genesis](#step-22-set-user-genesis-usergenesis) * [ ] HyperCore balances are u64 - the max balance is `2^64 - 1 = 18446744073709551615` * [ ] Make sure the total balances in the json does not exceed this value. * [ ] Re-runnable until the next step is executed. * [ ] UserGenesis transactions stack : If you set the balance of address X to `18446744073709551615` and then set the balance of address Y to `18446744073709551615` after removing X from the json, the net effect is that both X and Y will have `18446744073709551615` tokens. * You can either mint the entire amount to the asset bridge address (default) or the deployer address. * If you want to read more about the asset bridge address, see [Modifying OFT/Composer Behavior & Error Handling](#modifying-oftcomposer-behavior--error-handling) #### Step 2.3: Confirm the user genesis | Action | Performed by | Actionable with | Required for | | -------------------- | ----------------- | ----------------------------------------- | ------------ | | Confirm User Genesis | CoreSpot Deployer | `npx @layerzerolabs/hyperliquid-composer` | `HyperCore` | | Blocked by | CoreSpot Deployer | Step 2.2 | Step 2.5 | * [ ] Follow the instructions in [Step 2.3: Confirm User Genesis](#step-23-confirm-user-genesis-setgenesis) * [ ] Locks in the user genesis step and is now immutable. #### Step 2.4: Register the spot | Action | Performed by | Actionable with | Required for | | ------------- | ----------------- | ----------------------------------------- | ------------ | | Register Spot | CoreSpot Deployer | `npx @layerzerolabs/hyperliquid-composer` | `HyperCore` | | Blocked by | CoreSpot Deployer | Step 2.3 | Step 3 | * [ ] Follow the instructions in [Step 2.4: Register the Spot](#step-24-register-the-spot-registerspot) * [ ] Only USDC is supported on HyperCore at the moment - the SDK defaults to USDC. * [ ] Make sure the asset bridge address on HyperCore has all the tokens minted in Step 2.2. Partial funding is not supported. #### Step 2.5: Register Hyperliquidity | Action | Performed by | Actionable with | Required for | | ----------------------- | ----------------- | ----------------------------------------- | ------------ | | Register Hyperliquidity | CoreSpot Deployer | `npx @layerzerolabs/hyperliquid-composer` | `HyperCore` | | Blocked by | OFT Deployer | Step 0 | Step 6 | | Blocked by | CoreSpot Deployer | Step 2.1 | None | * [ ] Follow the instructions in [Step 2.5: Register Hyperliquidity](#step-25-register-hyperliquidity-createspotdeployment) * [ ] `nOrders` MUST be set to 0 as we are not engaging with hyperliquidity * [ ] The other values are token owner choice (is usually non 0) * Step MUST be run even though we set `noHyperliquidity=true` in genesis * This can be run even after deployment and linking * The final step to be executed after which the token will be listed on the spot order book. #### Step 2.6: Set deployer fee share | Action | Performed by | Actionable with | Required for | | ---------------------- | ----------------- | ----------------------------------------- | ------------ | | Set Deployer Fee Share | CoreSpot Deployer | `npx @layerzerolabs/hyperliquid-composer` | `HyperCore` | | Blocked by | OFT Deployer | Step 0 | Step 6 | | Blocked by | CoreSpot Deployer | Step 2.1 | None | * [ ] Follow the instructions in [Step 2.6: Set Deployer Trading Fee Share](#step-26-set-deployer-trading-fee-share-setdeployertradingfeeshare) * [ ] Trading fee share is usually 100% (default value) - this allocates the trading fees to the token deployer instead of burning it. * [ ] Do not lose or burn your deployer address as it collects tokens. * [ ] Step can be re-run as long as the new fee% is lower than the current one. * Even though the default value is 100%, it is recommended that you set it * This can be run even after deployment and linking ### Step 3: Connect the HyperCoreSpot to HyperEVM OFT #### Step 3.1: Create a request to connect the HyperCoreSpot to HyperEVM OFT | Action | Performed by | Actionable with | Required for | | -------------- | ----------------- | ----------------------------------------- | ------------ | | Create Request | CoreSpot Deployer | `npx @layerzerolabs/hyperliquid-composer` | `HyperCore` | | Blocked by | CoreSpot Deployer | Step 0, Step 2 | Step 3.2 | * [ ] Follow the instructions in [Step 3.1: Request EVM Contract Link](#step-31-request-evm-contract-link-core--evm-intention) * [ ] Make sure the core spot deployer has the OFT address. #### Step 3.2: Accept the request to connect the HyperCoreSpot to HyperEVM OFT | Action | Performed by | Actionable with | Required for | | -------------- | ----------------- | ----------------------------------------- | ------------ | | Accept Request | OFT Deployer | `npx @layerzerolabs/hyperliquid-composer` | `HyperCore` | | Blocked by | CoreSpot Deployer | Step 3.1 | Step 4 | * [ ] Follow the instructions in [Step 3.2: Finalize EVM Contract Link](#step-32-finalize-evm-contract-link-evm--core-confirmation) * [ ] Create a deployment file for the core spot before linking. ### Step 4: Deploy the Composer | Action | Performed by | Actionable with | Required for | | --------------- | ----------------- | ----------------------------------------- | ------------ | | Deploy Composer | OFT Deployer | `npx @layerzerolabs/hyperliquid-composer` | `HyperCore` | | Blocked by | CoreSpot Deployer | Step 3 | None | * [ ] Follow the instructions in [Step 4: Deploy the HyperLiquidComposer Contract](#step-4-deploy-the-hyperliquidcomposer-contract) * Deployer script in the OFT repo will deploy the composer - it also handles block switching. * [ ] Make sure the Composer's address is activated on HyperCore (sending it at least \$1 worth of `HYPE` or `USDC`). * Composer is re-deployable and independent of the OFT and does not need to be linked with anything. ### Step 5: Listing on spot order books | Action | Performed by | Actionable with | Required for | | ----------------- | ----------------- | ----------------------------------------- | ------------ | | Spot Book Listing | Automatic | `npx @layerzerolabs/hyperliquid-composer` | HyperCore | | Blocked by | CoreSpot Deployer | Step 2 | none | This is automatically completed when all steps in Step 2 are completed. ### Step 6: Listing on perp order books | Action | Performed by | Actionable with | Required for | | ----------------- | ----------------- | ----------------------------------------- | ------------ | | Perp Book Listing | Automatic | `npx @layerzerolabs/hyperliquid-composer` | HyperCore | | Blocked by | CoreSpot Deployer | Step 2 | none | This is controlled by the Hyperliquid community [(source)](https://hyperliquid.gitbook.io/hyperliquid-docs/trading/perpetual-assets): > Hyperliquid currently supports trading of 100+ assets. Assets are added according to community input. ## Full Hyperliquid OFT Deployment Guide ### Step 0: Deploy Your OFT on HyperEVM You have two main paths depending on your project setup: starting fresh or using an existing OFT project. #### **Path 1: New Project using LayerZero Hyperliquid Example** This path is recommended if you are starting fresh and intend to deploy to HyperCore. 1. **Create a new Hyperliquid example repository:** ```bash wrap theme={null} LZ_ENABLE_EXPERIMENTAL_HYPERLIQUID_EXAMPLE=1 npx create-lz-oapp@latest ``` * This template includes the `HyperLiquidComposer` contract and its deployment script. * The deploy scripts automatically handle HyperEVM block switching (to "big blocks" for deployment and back to "small blocks" after deployment is complete). 2. **Activate Deployer Account on HyperCore:** Ensure your OFT deployer address has a balance (e.g., \$1 USDC or HYPE) on HyperCore *before* deploying. This is needed for the deploy script to perform L1 actions like block switching. 3. **Deploy your OFT and (optionally) the Composer:** The example repository will have `hardhat-deploy` scripts. ```bash wrap theme={null} npx hardhat lz:deploy --tags MyHyperLiquidOFT # Or your OFT's tag # The Composer can be deployed later (Step 4), after the Core Spot is set up. # npx hardhat lz:deploy --tags MyHyperLiquidComposer ``` * The Composer comes with default error handling mechanisms (detailed in the "Modifying OFT/Composer Behavior" section below). #### **Path 2: Existing OFT Project** If you have an existing OFT project and want to add Hyperliquid support: 1. **Activate Deployer Account on HyperCore:** As above, ensure your deployer address is funded on HyperCore for L1 actions. 2. **Manually Switch to Big Blocks on HyperEVM:** Contract deployments on HyperEVM typically require "big blocks" due to gas limits. ```bash wrap theme={null} npx @layerzerolabs/hyperliquid-composer set-block \ --size big \ --network {testnet | mainnet} \ --private-key $PRIVATE_KEY \ [--log-level verbose] ``` *Replace `{testnet | mainnet}` and `$PRIVATE_KEY` accordingly.* 3. **Deploy your OFT:** Use your existing deployment scripts (e.g., `npx hardhat deploy --network hyperliquid_testnet --tags YourOFTTag`). 4. **Manually Switch back to Small Blocks on HyperEVM:** ```bash wrap theme={null} npx @layerzerolabs/hyperliquid-composer set-block \ --size small \ --network {testnet | mainnet} \ --private-key $PRIVATE_KEY \ [--log-level verbose] ``` **Post-Deployment (Both Paths):** * **Wire your OFTs:** Connect your newly deployed OFT on Hyperliquid with its counterparts on other chains. ```bash wrap theme={null} npx hardhat lz:oapp:wire --oapp-config path/to/your/layerzero.config.ts ``` * **Test Basic OFT Transfers:** Verify that standard OFT sends (without composition) work to and from Hyperliquid (HyperEVM). > ⚠️ **If you are only deploying to HyperEVM (i.e., your token will only exist as an ERC20 on HyperEVM and not be bridged to HyperCore), you are done with deployment steps related to Hyperliquid specifics beyond standard OFT deployment.** The following steps are for HyperCore integration. ### Step 1: (Optional) Purchase Your HyperCore Spot Index This step is required if you want your token to exist natively on HyperCore (as a HIP-1 token) and be bridgeable with your HyperEVM OFT. * **Action:** Purchase a Core Spot Index. * **Performed by:** CoreSpot Deployer (can be the same as OFT Deployer). * **Tool:** Hyperliquid UI: * [https://app.hyperliquid.xyz/deploySpot](https://app.hyperliquid.xyz/deploySpot) (for mainnet) * [https://app.hyperliquid-testnet.xyz/deploySpot](https://app.hyperliquid-testnet.xyz/deploySpot) (for testnet) * **Details:** This involves participating in a [Dutch auction for the deployment gas cost](https://hyperliquid.gitbook.io/hyperliquid-docs/hyperliquid-improvement-proposals-hips/hip-1-native-token-standard#gas-cost-for-deployment). The auction duration is 31 hours. ### Step 2: Deploy the Core Spot (HIP-1 Token) This process registers your token natively on HyperCore. **Tool:** `@layerzerolabs/hyperliquid-composer` SDK. **General Notes for CoreSpot Deployment:** ### REMINDER: HYPERLIQUIDITY IS NOT SUPPORTED BY LAYERZERO When deploying a Core Spot, avoid using the "Hyperliquidity" feature often defaulted by the Hyperliquid UI. It is incompatible with the LayerZero asset bridge mechanism as it can lead to uncollateralized states. The SDK commands help you deploy *without* Hyperliquidity. You can monitor the deployment progress using the [Hyperliquid UI](https://app.hyperliquid.xyz/deploySpot) or by querying the API: ```bash wrap theme={null} curl -X POST "https://api.hyperliquid.xyz/info" \ -H "Content-Type: application/json" \ -d '{ "type": "spotDeployState", "user": "" }' ``` This will return a json object with the current state of the spot deployment. #### **Step 2.1: Create a HyperCore Deployment File (`core-spot create`)** This will create a new file under `./deployments/hypercore-{testnet | mainnet}` with the name of the Core Spot token index. This is not a Hyperliquid step but rather something to make the deployment process easier. This file stores configuration for your Core Spot token and is used by subsequent SDK commands. It is crucial to the functioning of the token deployment after which it really is not needed. * **Action:** Create HyperCore Deployment File. * **Command:** ```bash wrap theme={null} npx @layerzerolabs/hyperliquid-composer core-spot \ --action create \ [--oapp-config \ --token-index \ --network {testnet | mainnet} \ [--log-level { info | verbose }] ``` * ``: The index you obtained in Step 1 (or intend to use if the auction allows direct index specification). * If `--oapp-config` is provided and your OFT is defined, it can pre-fill some details. Otherwise, the SDK might prompt for OFT address and deployment transaction hash later, especially during the linking phase. * **Output:** Creates a JSON file at `./deployments/hypercore-{testnet | mainnet}/.json`. #### **Step 2.2: Set User Genesis (`userGenesis`)** Define the initial supply and distribution of your HIP-1 token on HyperCore. * **Action:** Set the genesis balances for the deployer and the users. * **Preparation:** 1. Edit the JSON file created in Step 2.1 (`./deployments/hypercore-{testnet | mainnet}/.json`). 2. Populate the `userAndWei` or `existingTokenAndWei` sections. The file should initially contain entries for the `deployer` and the `asset bridge address` (e.g., `0x2000...`), typically with `0 wei`. 3. **Crucially for the asset bridge**: To enable bridging the *entire* supply, mint the total supply (e.g., `18446744073709551615` for `u64.max`) to the **asset bridge address** corresponding to your token. You can find how to compute this address using `npx @layerzerolabs/hyperliquid-composer to-bridge --token-index `. Example snippet for the JSON: ```json wrap theme={null} "userAndWei": [ { "user": "0xAssetBridgeAddressForYourToken", // Replace with actual bridge address "wei": "18446744073709551615" // Max u64 or your total supply } ], "existingTokenAndWei": [], // Ensure this is empty if not used "blacklistUsers": [] ``` 4. If not using `existingTokenAndWei` or `userAndWei` for other users, ensure their arrays are empty (`[]`) to avoid errors like `Error deploying spot: missing token max_supply`. ```json wrap theme={null} // Change this: "existingTokenAndWei": [ { "token": 0, "wei": "" } ] // To this: "existingTokenAndWei": [] ``` * **Command:** ```bash wrap theme={null} npx @layerzerolabs/hyperliquid-composer user-genesis \ --token-index \ [--action {* | userAndWei | existingTokenAndWei | blacklistUsers}] \ # Default is * (all) --network {testnet | mainnet} \ --private-key $PRIVATE_KEY_HYPERLIQUID \ [--log-level { info | verbose }] ``` * **Details:** * HyperCore HIP-1 tokens use `u64` for balances (max: `18,446,744,073,709,551,615`). Ensure total balances don't exceed this. * This step is re-runnable until Step 2.3 (Confirm User Genesis) is executed. There is no limit to the number of times you can re-run this command. * For in-depth understanding of why full funding of the asset bridge is critical, refer to [The Asset Bridge Mechanics](./hyperliquid-concepts#8-the-asset-bridge-linking-evm-spot-erc20-and-core-spot-hip-1) in Core Concepts. #### **Step 2.3: Confirm User Genesis (`setGenesis`)** This step finalizes the genesis balances set in Step 2.2, making them immutable on HyperCore. ### Warning: This action is irreversible. * **Action:** Confirm User Genesis. * **Command:** ```bash wrap theme={null} npx @layerzerolabs/hyperliquid-composer set-genesis \ --token-index \ --network {testnet | mainnet} \ --private-key $PRIVATE_KEY_HYPERLIQUID \ [--log-level {info | verbose }] ``` #### **Step 2.4: Register the Spot (`registerSpot`)** This registers your Core Spot token on HyperCore and typically creates a trading pair against USDC, which is the only supported quote token as of now. * **Action:** Register Spot. * **Command:** ```bash wrap theme={null} npx @layerzerolabs/hyperliquid-composer register-spot \ --token-index \ --network {testnet | mainnet} \ --private-key $PRIVATE_KEY_HYPERLIQUID \ [--log-level { info | verbose }] ``` * **Details:** * Currently, USDC is the primary quote token on HyperCore; the SDK defaults to this. * Ensure the asset bridge address on HyperCore holds the full token supply intended for bridging (as minted in Step 2.2). **Partial funding of the bridge is not supported and can lead to permanently locked tokens.** * **Verification:** You can check your deployed Core Spot token details: ```bash wrap theme={null} curl -X POST "https://api.hyperliquid-testnet.xyz/info" \ # or mainnet URL -H "Content-Type: application/json" \ -d '{"type": "tokenDetails", "tokenId": ""}' ``` * `` is the onchain identifier for your HIP-1 token (can be found via explorers or API responses). #### **Step 2.5: Register Hyperliquidity (`createSpotDeployment`)** This step creates a spot deployment without hyperliquidity, which is required for LayerZero integration. * **Action:** Create Spot Deployment. * **Command:** ```bash wrap theme={null} npx @layerzerolabs/hyperliquid-composer create-spot-deployment \ --token-index \ --network {testnet | mainnet} \ --private-key $PRIVATE_KEY_HYPERLIQUID \ [--log-level {info | verbose}] ``` * **Prompts:** You will be prompted for the following values: * `startPx`: The starting price for the token. * `orderSz`: The size of each order (as a float, not wei). * `nSeededLevels`: The number of levels the deployer wishes to seed with USDC instead of tokens. You will NOT be prompted for `nOrders` as it is automatically set to 0 because LayerZero does not support Hyperliquidity. See [Hyperliquid Python SDK example](https://github.com/hyperliquid-dex/hyperliquid-python-sdk/blob/master/examples/spot_deploy.py#L97-L104) for reference. * **Details:** * There are tight range bounds on the input values that can be viewed at Hyperliquid's [frontend checks](https://hyperliquid.gitbook.io/hyperliquid-docs/hyperliquid-improvement-proposals-hips/frontend-checks#hyperliquidity). * This step can be executed after the Core Spot is fully deployed and even after linking with the EVM contract. * After completing this step, `spot-deploy-state` queries will fail, which is expected behavior. The SDK does not currently enforce the frontend checks for input validation. Ensure your values comply with Hyperliquid's requirements to avoid deployment issues. #### **Step 2.6: Set Deployer Trading Fee Share (`setDeployerTradingFeeShare`)** Configure the trading fee share for the deployer of the Core Spot token. * **Action:** Set Deployer Fee Share. * **Command:** ```bash wrap theme={null} npx @layerzerolabs/hyperliquid-composer trading-fee \ --token-index \ --share \ # e.g., "100%" or "0%" --network {testnet | mainnet} \ --private-key $PRIVATE_KEY_HYPERLIQUID \ [--log-level { info | verbose }] ``` * **Details:** * A [deployer fee share](https://hyperliquid.gitbook.io/hyperliquid-docs/trading/fees) is claimed per transaction on HyperCore * Share can be `[0%, 100%]`. A `100%` share allocates the deployer's portion of trading fees to the token deployer. `0%` burns it. * The deployer address collects these fees; ensure it's secure. This step can be re-run to lower the fee share but NOT to increase it. It can also be run after the Core Spot is fully deployed, so it might be a good idea to set the fee to 100% and be able to lower it later. ### Step 3: Connect the HyperCoreSpot (HIP-1) to HyperEVM OFT (ERC20) This two-step process establishes the link that allows tokens to be bridged between HyperCore and HyperEVM via the asset bridge precompile. * **Preparation:** If you haven't used `--oapp-config` in previous steps, the SDK might prompt for your OFT contract address (on HyperEVM) and its deployment transaction hash (to get the nonce). Ensure the CoreSpot deployer has access to the OFT address. #### Step 3.1: Request EVM Contract Link (Core → EVM Intention) The Core Spot deployer initiates a request on HyperCore to link the HIP-1 token to a specific ERC20 contract on HyperEVM. * **Action:** Create Link Request. * **Performed by:** CoreSpot Deployer. * **Command:** ```bash wrap theme={null} npx @layerzerolabs/hyperliquid-composer request-evm-contract \ [--oapp-config path/to/your/layerzero.config.ts] \ --token-index \ --network {testnet | mainnet} \ --private-key $PRIVATE_KEY_HYPERLIQUID \ [--log-level verbose] ``` * **Note:** This step can be re-issued multiple times (e.g., if the ERC20 address was initially incorrect) until `finalizeEvmContract` (Step 3.2) is completed. #### Step 3.2: Finalize EVM Contract Link (EVM → Core Confirmation) The OFT (ERC20) deployer on HyperEVM confirms and finalizes the link. * **Action:** Accept/Finalize Link Request. * **Performed by:** OFT Deployer (the EOA that deployed the ERC20 contract on HyperEVM). * **Command:** ```bash wrap theme={null} npx @layerzerolabs/hyperliquid-composer finalize-evm-contract \ [--oapp-config path/to/your/layerzero.config.ts] \ --token-index \ --network {testnet | mainnet} \ --private-key $PRIVATE_KEY_HYPERLIQUID \ # This should be the private key of the OFT deployer on HyperEVM [--log-level verbose] ``` ### This step is final and irreversible for the given token pair. ### Step 4: Deploy the HyperLiquidComposer Contract The Composer contract facilitates the actual bridging of tokens from HyperEVM to HyperCore when receiving LayerZero messages. * **Action:** Deploy Composer. * **Performed by:** OFT Deployer. * **Command (if using the Hyperliquid example repo):** ```bash wrap theme={null} npx hardhat lz:deploy --tags MyHyperLiquidComposer --network hyperliquid_testnet # or your target network ``` * The deployment script in the example repository handles block switching (to "big blocks" and back) automatically. If deploying manually, ensure you are on a "big block". * **Funding Requirement:** * **Crucial**: The deployed `HyperLiquidComposer` contract address **must be activated on HyperCore** by sending it at least \$1 worth of `USDC` or `HYPE` on HyperCore. This is because the Composer uses `CoreWriter` precompiles to transfer tokens directly on HyperCore. * **Features:** * **Activation Checks**: The Composer verifies receiver activation using `coreUserExists()` precompile * **Bridge Capacity Validation**: Uses `spotBalance()` precompile to prevent bridge overflow scenarios * **Failed Message Recovery**: Failed compose messages can be refunded to source chains via `refundToSrc()` * **Dual Asset Support**: Handles both ERC20 tokens and native HYPE transfers in a single contract * **Notes:** * The Composer is stateless regarding individual user balances (it doesn't hold tokens long-term). * It can be deployed at any point, but it's functionally useful only after the OFT and Core Spot are deployed and linked. * It's re-deployable. If re-deployed, ensure any systems pointing to it are updated. ### Step 5: Sending Tokens (from other chains to HyperEVM/Core) After all deployments and linking are complete, you can send tokens from another network through LayerZero to a recipient on Hyperliquid. The Composer will handle the final hop to HyperCore if specified. * **Forge Script Example (from LayerZero devtools):** Ensure your `.env` is populated with `PRIVATE_KEY`, `RPC_URL_BSC_TESTNET` (or your source chain RPC). ```bash wrap theme={null} forge script script/SendScript.s.sol \ --private-key $PRIVATE_KEY \ --rpc-url $RPC_URL_SOURCE_CHAIN \ --sig "exec(uint256,uint128,uint128)" \ \ # Amount of OFT to send in local decimals \ # Gas to forward for HyperCore L1 action (e.g., 100000). If > 0, attempts to send to HyperCore. \ # Value (in HYPE) to send to fund user on HyperCore (e.g., 0). --broadcast ``` * The `SendScript.s.sol` (or your custom sending logic) would prepare a `SendParam` where: * `SendParam.dstEid` points to Hyperliquid. * `SendParam.to` is the OFT address on Hyperliquid. * `SendParam.composeMsg` is `abi.encode(uint256 minMsgValue, address actualReceiverAddressOnHyperliquid)`. * `SendParam.extraOptions` might be used to specify gas for the `lzCompose` call and the subsequent L1 action. ### Error Handling & Recovery The `HyperLiquidComposer` implementation includes comprehensive error handling and recovery mechanisms: #### **Precompile-Based Validation** * **Activation Check**: Uses `coreUserExists()` precompile to verify receiver is activated before attempting transfers * **Bridge Capacity Check**: Uses `spotBalance()` precompile to validate sufficient bridge capacity * **Gas Protection**: Enforces minimum gas requirements (`MIN_GAS()` / `MIN_GAS_WITH_VALUE()`) to prevent execution failures #### **Error Recovery Mechanisms** * **Failed Message Storage**: Messages that fail decoding are stored in `failedMessages[guid]` mapping * **Crosschain Refunds**: Failed messages can be refunded to source chain using `refundToSrc(bytes32 guid)` * **HyperEVM Refunds**: Failed transfers automatically refund tokens to receiver on HyperEVM * **Fallback Protection**: Multiple fallback mechanisms prevent token locking scenarios #### **Dual Asset Support** * **ERC20 Tokens**: Handles OFT token transfers with decimal scaling * **Native HYPE**: Supports native token transfers alongside ERC20 transfers * **Combined Operations**: Can transfer both ERC20 and HYPE in a single compose operation #### **Error Scenarios & Handling** 1. **Malformed Message**: Stored in `failedMessages` for crosschain refund 2. **Inactive Receiver**: Transaction reverts with `CoreUserNotActivated()` error 3. **Insufficient Bridge Capacity**: Transaction reverts to prevent token locking 4. **Gas Exhaustion**: Protected by minimum gas requirements 5. **Precompile Failures**: Automatic refund to HyperEVM receiver address The implementation provides strong safety guarantees while maintaining compatibility with LayerZero OFT workflows.