hlp/secondary-spot-markets (#1904)

Signed-off-by: shankar <shankar@layerzero.org>
Co-authored-by: shankar <shankar@layerzero.org>

Author: shankars99

.changeset/sixty-readers-talk.md

@@ -0,0 +1,6 @@
+---
+"@layerzerolabs/hyperliquid-composer": patch
+"@layerzerolabs/oft-hyperliquid-example": patch
+---
+
+improved cli and docs on expansion spot market pairs

examples/oft-hyperliquid/HYPERLIQUID.README.md

@@ -90,6 +90,8 @@ npx @layerzerolabs/hyperliquid-composer set-genesis \
 
 ### 4. Register Trading Spot
 
+Registers a trading pair between your token and a quote asset (USDC, HYPE, or custom quote token).
+
 ```bash
 npx @layerzerolabs/hyperliquid-composer register-spot \
     --token-index <coreIndex> \
@@ -98,16 +100,54 @@ npx @layerzerolabs/hyperliquid-composer register-spot \
     [--log-level {info | verbose}]
 ```
 
+On success, this command outputs the allocated **spot index** and the exact command to run for finalization:
+
+```
+============================================================
+SPOT REGISTRATION SUCCESSFUL
+============================================================
+Allocated Spot Index: 1421
+Base Token: 1502
+Quote Token: USDC (0)
+
+NEXT STEP: Finalize the spot pair with:
+  npx @layerzerolabs/hyperliquid-composer create-spot-deployment \
+      --token-index 1502 \
+      --network testnet \
+      --spot-index 1421 \
+      --private-key $PRIVATE_KEY
+============================================================
+```
+
+**Note:** For additional spot pairs (beyond the first), this command participates in the spot pair deployment Dutch auction.
+
 ### 5. Create Spot Deployment
 
+Finalizes a spot pair by setting hyperliquidity parameters. Required after `register-spot` to make the trading pair live.
+
 ```bash
 npx @layerzerolabs/hyperliquid-composer create-spot-deployment \
     --token-index <coreIndex> \
     --network {testnet | mainnet} \
     --private-key $PRIVATE_KEY_HYPERLIQUID \
+    [--spot-index <spotIndex>] \
     [--log-level {info | verbose}]
 ```
 
+**Options:**
+
+- `--spot-index <id>`: Directly specify the spot index to finalize (recommended). Use the spot index from the `register-spot` output.
+
+**Example:**
+
+```bash
+npx @layerzerolabs/hyperliquid-composer create-spot-deployment \
+    --token-index 1502 \
+    --network testnet \
+    --spot-index 1421 \
+    --private-key $PRIVATE_KEY
+```
+
 ### 6. Set Trading Fee Share (Optional)
 
 Can be done at any time after deployment. **Note:** If you plan to enable quote token capability, read the [Permissionless Spot Quote Assets](https://hyperliquid.gitbook.io/hyperliquid-docs/hypercore/permissionless-spot-quote-assets) documentation before setting this value.
@@ -469,7 +509,7 @@ npx @layerzerolabs/hyperliquid-composer set-genesis \
 
 ### Step 4/7 `registerSpot`
 
-This is the step that registers the Core Spot on `HyperCore` and creates a base-quote pair. You can now choose between USDC, USDT0, or custom quote tokens.
+This is the step that registers the Core Spot on `HyperCore` and creates a base-quote pair. You can choose between USDC, USDT0, HYPE, or custom quote tokens.
 
 ```bash
 npx @layerzerolabs/hyperliquid-composer register-spot \
@@ -479,9 +519,32 @@ npx @layerzerolabs/hyperliquid-composer register-spot \
     [--log-level {info | verbose}]
 ```
 
+On success, this command outputs the allocated **spot index** and the exact command for finalization:
+
+```
+============================================================
+SPOT REGISTRATION SUCCESSFUL
+============================================================
+Allocated Spot Index: 1421
+Base Token: 1502
+Quote Token: USDC (0)
+
+NEXT STEP: Finalize the spot pair with:
+  npx @layerzerolabs/hyperliquid-composer create-spot-deployment \
+      --token-index 1502 \
+      --network testnet \
+      --spot-index 1421 \
+      --private-key $PRIVATE_KEY
+============================================================
+```
+
+**Note:** For additional spot pairs (beyond the first), this command participates in the spot pair deployment Dutch auction.
+
 ### Step 5/7 `createSpotDeployment`
 
-This is the step that creates a spot deployment without hyperliquidity. This step is meant for tokens deployed with Hyperliquidity but is also required for tokens deployed without Hyperliquidity to be listed on Spot trading, as such the values for `startPx` and `orderSz` are not required as they are set by the market and the value set does not matter. The value for `nOrders` however MUST be 0 as we do not support Hyperliquidity - <https://github.com/hyperliquid-dex/hyperliquid-python-sdk/blob/master/examples/spot_deploy.py#L97-L104>
+This step finalizes a spot deployment by setting hyperliquidity parameters. Required after `register-spot` to make the trading pair live on HyperCore.
+
+For tokens deployed without Hyperliquidity, the values for `startPx` and `orderSz` are not significant as they are set by the market. The value for `nOrders` MUST be 0 as we do not support Hyperliquidity - <https://github.com/hyperliquid-dex/hyperliquid-python-sdk/blob/master/examples/spot_deploy.py#L97-L104>
 
 You will NOT be prompted for the following and instead the values will be set to 0:
 
@@ -497,9 +560,24 @@ npx @layerzerolabs/hyperliquid-composer create-spot-deployment \
     --token-index <coreIndex> \
     --network {testnet | mainnet} \
     --private-key $PRIVATE_KEY_HYPERLIQUID \
+    [--spot-index <spotIndex>] \
     [--log-level {info | verbose}]
 ```
 
+**Options:**
+
+- `--spot-index <id>`: Directly specify the spot index to finalize. Use the spot index from `register-spot` output. This is the recommended approach.
+
+**Example:**
+
+```bash
+npx @layerzerolabs/hyperliquid-composer create-spot-deployment \
+    --token-index 1502 \
+    --network testnet \
+    --spot-index 1421 \
+    --private-key $PRIVATE_KEY
+```
+
 > ⚠️ Note: `spot-deploy-state` should fail after completing this step.
 
 Your Core Spot (that does not use Hyperliquidity) has now been deployed and registered on `HyperCore`.

packages/hyperliquid-composer/HYPERLIQUID.README.md

@@ -490,6 +490,8 @@ npx @layerzerolabs/hyperliquid-composer set-genesis \
 
 ### 4. Register Trading Spot
 
+Registers a trading pair between your token and a quote asset (USDC, HYPE, or custom quote token).
+
 ```bash
 npx @layerzerolabs/hyperliquid-composer register-spot \
     --token-index <coreIndex> \
@@ -498,16 +500,53 @@ npx @layerzerolabs/hyperliquid-composer register-spot \
     [--log-level {info | verbose}]
 ```
 
+On success, this command outputs the allocated **spot index** and the exact command to run for finalization:
+
+```
+============================================================
+SPOT REGISTRATION SUCCESSFUL
+============================================================
+Allocated Spot Index: 1421
+Base Token: 1502
+Quote Token: USDC (0)
+
+NEXT STEP: Finalize the spot pair with:
+  npx @layerzerolabs/hyperliquid-composer create-spot-deployment \
+      --token-index 1502 \
+      --network testnet \
+      --spot-index 1421 \
+      --private-key $PRIVATE_KEY
+============================================================
+```
+
+**Note:** For additional spot pairs (beyond the first), this command participates in the spot pair deployment Dutch auction. Check the current auction status with `spot-auction-status`.
+
 ### 5. Create Spot Deployment
 
+Finalizes a spot pair by setting hyperliquidity parameters. This step is required after `register-spot` to make the trading pair live.
+
 ```bash
 npx @layerzerolabs/hyperliquid-composer create-spot-deployment \
     --token-index <coreIndex> \
     --network {testnet | mainnet} \
     --private-key $PRIVATE_KEY_HYPERLIQUID \
+    [--spot-index <spotIndex>] \
     [--log-level {info | verbose}]
 ```
 
+**Options:**
+- `--spot-index <id>`: Directly specify the spot index to finalize (recommended). This skips discovery and uses the spot index provided by `register-spot`.
+
+**Example (using spot index from register-spot output):**
+
+```bash
+npx @layerzerolabs/hyperliquid-composer create-spot-deployment \
+    --token-index 1502 \
+    --network testnet \
+    --spot-index 1421 \
+    --private-key $PRIVATE_KEY
+```
+
 ### 6. Set Trading Fee Share (Optional)
 
 Can be done at any time after deployment. **Note:** If you plan to enable quote token capability, read the [Permissionless Spot Quote Assets](https://hyperliquid.gitbook.io/hyperliquid-docs/hypercore/permissionless-spot-quote-assets) documentation before setting this value.
@@ -917,7 +956,9 @@ npx @layerzerolabs/hyperliquid-composer register-spot \
 
 ### Step 5/7 `createSpotDeployment`
 
-This is the step that creates a spot deployment without hyperliquidity. This step is meant for tokens deployed with Hyperliquidity but is also required for tokens deployed without Hyperliquidity to be listed on Spot trading, as such the values for `startPx` and `orderSz` are not required as they are set by the market and the value set does not matter. The value for `nOrders` however MUST be 0 as we do not support Hyperliquidity - <https://github.com/hyperliquid-dex/hyperliquid-python-sdk/blob/master/examples/spot_deploy.py#L97-L104>
+This step finalizes a spot deployment by setting hyperliquidity parameters. It is required after `register-spot` to make the trading pair live on HyperCore.
+
+For tokens deployed without Hyperliquidity, the values for `startPx` and `orderSz` are not significant as they are set by the market. The value for `nOrders` MUST be 0 as we do not support Hyperliquidity - <https://github.com/hyperliquid-dex/hyperliquid-python-sdk/blob/master/examples/spot_deploy.py#L97-L104>
 
 You will NOT be prompted for the following and instead the values will be set to 0:
 
@@ -933,9 +974,24 @@ npx @layerzerolabs/hyperliquid-composer create-spot-deployment \
     --token-index <coreIndex> \
     --network {testnet | mainnet} \
     --private-key $PRIVATE_KEY_HYPERLIQUID \
+    [--spot-index <spotIndex>] \
     [--log-level {info | verbose}]
 ```
 
+**Options:**
+- `--spot-index <id>`: Directly specify the spot index to finalize. Use the spot index output from the `register-spot` command. This is the recommended approach as it skips network-wide discovery.
+
+**Example:**
+
+```bash
+# Using the spot index from register-spot output
+npx @layerzerolabs/hyperliquid-composer create-spot-deployment \
+    --token-index 1502 \
+    --network testnet \
+    --spot-index 1421 \
+    --private-key $PRIVATE_KEY
+```
+
 > ⚠️ Note: `spot-deploy-state` should fail after completing this step.
 
 Your Core Spot (that does not use Hyperliquidity) has now been deployed and registered on `HyperCore`.

packages/hyperliquid-composer/src/cli.ts

@@ -170,6 +170,7 @@ optionGroups
         program
             .command(CLI_COMMANDS.CREATE_SPOT_DEPLOYMENT)
             .description('HIP-1 Deployment 4. Create spot deployment without hyperliquidity')
+            .option('-s, --spot-index <spot-index>', 'Directly specify spot index to finalize (skips discovery)')
     )
     .action(withNormalizedNetwork(createSpotDeployment))
 

packages/hyperliquid-composer/src/commands/spot-deploy.ts

@@ -95,10 +95,15 @@ export async function createSpotDeployment(args: CreateSpotDeploymentArgs): Prom
     const signer = await getHyperliquidSigner(args.privateKey)
     const isTestnet = args.network === 'testnet'
     const tokenIndex: number = parseInt(args.tokenIndex)
+    const spotIndex: number | undefined = args.spotIndex ? parseInt(args.spotIndex) : undefined
 
-    logger.info(`Setting no hyperliquidity for token ${tokenIndex}`)
+    if (spotIndex !== undefined) {
+        logger.info(`Finalizing spot ${spotIndex} for token ${tokenIndex}`)
+    } else {
+        logger.info(`Setting no hyperliquidity for token ${tokenIndex}`)
+    }
 
-    await setNoHyperliquidity(signer, isTestnet, tokenIndex, args.logLevel)
+    await setNoHyperliquidity(signer, isTestnet, tokenIndex, args.logLevel, spotIndex)
 }
 
 export async function registerTradingSpot(args: RegisterTradingSpotArgs): Promise<void> {