feat(hyperliquid-composer): update docs and contract NatSpec (LayerZero-Labs#1929)

Signed-off-by: shankar <shankar@layerzerolabs.org>

Author: shankars99

.changeset/eight-actors-grow.md

@@ -0,0 +1,6 @@
+---
+"@layerzerolabs/hyperliquid-composer": patch
+"@layerzerolabs/oft-hyperliquid-example": patch
+---
+
+docs update and natspec

examples/oft-hyperliquid/HYPERLIQUID.CHECKLIST.md

@@ -34,7 +34,7 @@ Block switching is not present in the default oft deploy script.
 | Purchase Spot | CoreSpot Deployer | <https://app.hyperliquid.xyz/deploySpot> | HyperCore    |
 | Blocked by    | none              | none                                     | Step 2       |
 
-- [ ] Purchase your HyperCore Spot engaging in the [auction](https://github.com/LayerZero-Labs/devtools/blob/main/examples/oft-hyperliquid/HYPERLIQUID.README.md#step-16-purchase-the-ticker)
+- [ ] Purchase your HyperCore Spot engaging in the [auction](https://github.com/LayerZero-Labs/devtools/blob/main/examples/oft-hyperliquid/HYPERLIQUID.README.md#step-0-purchase-the-ticker-prerequisite)
 
 ## Step 2 : Deploy the CoreSpot
 
@@ -54,7 +54,7 @@ Block switching is not present in the default oft deploy script.
 | Blocked by                       | OFT Deployer      | Step 0                                    | Step 3       |
 | Blocked by                       | CoreSpot Deployer | Step 1                                    | Step 2.2     |
 
-- [ ] Follow the [guide](https://github.com/LayerZero-Labs/devtools/blob/main/examples/oft-hyperliquid/HYPERLIQUID.README.md#step-0-purchase-the-ticker)
+- [ ] Follow the [guide](https://github.com/LayerZero-Labs/devtools/blob/main/examples/oft-hyperliquid/HYPERLIQUID.README.md#step-0-purchase-the-ticker-prerequisite)
 - [ ] Core spot deployer needs OFT address and deployed transaction hash
 
 ### Step 2.2 : Enable freeze privilege (Optional)
@@ -64,7 +64,7 @@ Block switching is not present in the default oft deploy script.
 | Enable Freeze Privilege | CoreSpot Deployer | `npx @layerzerolabs/hyperliquid-composer` | HyperCore    |
 | Blocked by              | CoreSpot Deployer | Step 2.1                                  | Step 2.2     |
 
-- [ ] Follow the [guide](https://github.com/LayerZero-Labs/devtools/blob/main/examples/oft-hyperliquid/HYPERLIQUID.README.md#step-16-enablefreezeprivilege-optional)
+- [ ] Follow the [guide](https://github.com/LayerZero-Labs/devtools/blob/main/examples/oft-hyperliquid/HYPERLIQUID.README.md#step-18-enablefreezeprivilege-optional)
 - [ ] **MUST be done before genesis** if you want freeze capability
 - [ ] Enables post-launch user freeze/unfreeze operations
 - [ ] Once set, can only be revoked (irreversible)
@@ -76,7 +76,7 @@ Block switching is not present in the default oft deploy script.
 | Set User Genesis | CoreSpot Deployer | `npx @layerzerolabs/hyperliquid-composer` | HyperCore    |
 | Blocked by       | CoreSpot Deployer | Step 2.1                                  | Step 2.3     |
 
-- [ ] Follow the [guide](https://github.com/LayerZero-Labs/devtools/blob/main/examples/oft-hyperliquid/HYPERLIQUID.README.md#step-26-usergenesis)
+- [ ] Follow the [guide](https://github.com/LayerZero-Labs/devtools/blob/main/examples/oft-hyperliquid/HYPERLIQUID.README.md#step-28-usergenesis)
 - [ ] HyperCore balances are u64 - the max balance is `2.pow(64) - 1 = 18446744073709551615`
 - [ ] Make sure the total balances in the json does not exceed this value.
 - [ ] Re-runnable until the next step is executed.
@@ -91,7 +91,7 @@ Block switching is not present in the default oft deploy script.
 | Confirm User Genesis | CoreSpot Deployer | `npx @layerzerolabs/hyperliquid-composer` | HyperCore    |
 | Blocked by           | CoreSpot Deployer | Step 2.2                                  | Step 2.4     |
 
-- [ ] Follow the [guide](https://github.com/LayerZero-Labs/devtools/blob/main/examples/oft-hyperliquid/HYPERLIQUID.README.md#step-36-genesis)
+- [ ] Follow the [guide](https://github.com/LayerZero-Labs/devtools/blob/main/examples/oft-hyperliquid/HYPERLIQUID.README.md#step-38-genesis)
 - [ ] Locks in the user genesis step and is now immutable.
 
 ### Step 2.5 : Create spot deployment
@@ -101,7 +101,7 @@ Block switching is not present in the default oft deploy script.
 | Create Spot Deployment | CoreSpot Deployer | `npx @layerzerolabs/hyperliquid-composer` | HyperCore    |
 | Blocked by             | CoreSpot Deployer | Step 2.3                                  | Step 2.5     |
 
-- [ ] Follow the [guide](https://github.com/LayerZero-Labs/devtools/blob/main/examples/oft-hyperliquid/HYPERLIQUID.README.md#step-46-createspotdeployment)
+- [ ] Follow the [guide](https://github.com/LayerZero-Labs/devtools/blob/main/examples/oft-hyperliquid/HYPERLIQUID.README.md#step-58-createspotdeployment)
 - Step MUST be run even though we set `noHyperliquidity=true` in genesis
 - This can be run even after deployment and linking
 
@@ -112,7 +112,7 @@ Block switching is not present in the default oft deploy script.
 | Register Spot | CoreSpot Deployer | `npx @layerzerolabs/hyperliquid-composer` | HyperCore    |
 | Blocked by    | CoreSpot Deployer | Step 2.4                                  | Step 3       |
 
-- [ ] Follow the [guide](https://github.com/LayerZero-Labs/devtools/blob/main/examples/oft-hyperliquid/HYPERLIQUID.README.md#step-56-registerspot)
+- [ ] Follow the [guide](https://github.com/LayerZero-Labs/devtools/blob/main/examples/oft-hyperliquid/HYPERLIQUID.README.md#step-48-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.3. Partial funding is not supported.
 - The final step to be executed after which the token will be listed on the spot order book.
@@ -125,11 +125,11 @@ Block switching is not present in the default oft deploy script.
 | Blocked by             | OFT Deployer      | Step 0                                    | none         |
 | Blocked by             | CoreSpot Deployer | Step 2.1                                  | none         |
 
-- [ ] Follow the [guide](https://github.com/LayerZero-Labs/devtools/blob/main/examples/oft-hyperliquid/HYPERLIQUID.README.md#step-67-setdeployertradingfeeshare-optional)
+- [ ] Follow the [guide](https://github.com/LayerZero-Labs/devtools/blob/main/examples/oft-hyperliquid/HYPERLIQUID.README.md#step-68-setdeployertradingfeeshare-optional)
 - [ ] 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.
-- [ ] **Important**: If you plan to enable quote token capability (Step 2.8), read the [Permissionless Spot Quote Assets](https://hyperliquid.gitbook.io/hyperliquid-docs/hypercore/permissionless-spot-quote-assets) documentation before setting this value as it requires a specific trading fee share.
+- [ ] **Important**: If you plan to enable quote token capability (Step 2.8), read the [Permissionless Spot Quote Assets](https://hyperliquid.gitbook.io/hyperliquid-docs/hypercore/permissionless-spot-quote-assets) documentation before setting this value as it requires a specific trading fee share
 - Even though the default value is 100%, it is recommended that you set it
 - This can be run even after deployment and linking
 
@@ -142,7 +142,7 @@ Block switching is not present in the default oft deploy script.
 
 - [ ] **Review requirements first**: Read [Permissionless Spot Quote Assets](https://hyperliquid.gitbook.io/hyperliquid-docs/hypercore/permissionless-spot-quote-assets) for all requirements
 - [ ] Requires specific trading fee share value (see Step 2.7 above)
-- [ ] Follow the [guide](https://github.com/LayerZero-Labs/devtools/blob/main/examples/oft-hyperliquid/HYPERLIQUID.README.md#step-657-enablequotetoken-optional)
+- [ ] Follow the [guide](https://github.com/LayerZero-Labs/devtools/blob/main/examples/oft-hyperliquid/HYPERLIQUID.README.md#step-78-enablequotetoken-optional)
 - [ ] Enables the token to be used as a quote asset for trading pairs (e.g., OTHER_TOKEN/YOUR_TOKEN)
 - [ ] Can be executed after trading fee share is set
 - [ ] This can be run even after deployment and linking are complete

examples/oft-hyperliquid/HYPERLIQUID.README.md

@@ -364,15 +364,17 @@ The current architecture has certain error handling AND checks (because hyperliq
 
 #### Transfer exceeding u64.max
 
-HyperCore's spot send only allows for a maximum of `u64` tokens to be transferred across. This means (in the unlikely event) that the user sends across greater than `u64` the difference would be returned the the `receiver` address on `HyperEVM`.
+HyperCore's spot send only allows for a maximum of `u64` tokens to be transferred across. This means (in the unlikely event) that the user sends across greater than `u64` we revert since the bridge can not send that amount.
 
-#### Transfer exceeding HyperCore Bridge Capactiy
+#### Transfer exceeding HyperCore Bridge Capacity
 
-HyperCore's core spots support a maximum of `u64` tokens on the core spot, and this is scaled by the decimal difference between the core spot and the evm spot. It is thus possible that the asset bridge on hypercore has been consumed to the point where the entire transfer can't be sent over. In this event we split the `amount` capping it by `amount * 10.pow(ERC20.decimals() - HyperCore.decimals())` which is the maximum possible core spot tokens that can be consumed at the bridge at any given instant and compute the difference between the computed max core amount converted to evm amount (unscaling) and removing that from the incoming evm amount. We now have `dust` which is the difference between the two and return this to the `receiver` address.
+HyperCore's Core Spots support a maximum of `u64` tokens on the Core Spot, and this is scaled by the decimal difference between the Core Spot and the EVM Spot. It is thus possible that the asset bridge on HyperCore has been consumed to the point where the entire transfer can't be sent over. In this event the composer reverts with `TransferAmtExceedsAssetBridgeBalance` — this revert is caught by the try/catch in `lzCompose` and the full amount is refunded to the receiver on HyperEVM.
+
+> Note: The composer does NOT refund dust to the receiver on HyperEVM because we do not expect any due to truncation of `sharedDecimals` in OFT transfers. If your implementation produces dust you would need to add dust refund logic to `_transferERC20ToHyperCore` and `_transferNativeToHyperCore`.
 
 #### Malformed `composeMsg` - unable to abi.decode(composeMsg) into address
 
-The above cases only occur in the stae when the compose payload is valid. In the event that developers write their own front end or try to interact with the composer with their own encoding and aren't careful it is possible that the message contains a `composeMsg` that can not be decoded to an `address`, as such we do not have the `receiver` address. In this event we try returning the tokens to the `sender` on HyperEVM where the sender is the `msg.sender` of the layerzero tx on the source chain.
+The above cases only occur in the state when the compose payload is valid. In the event that developers write their own front end or try to interact with the composer with their own encoding and aren't careful it is possible that the message contains a `composeMsg` that can not be decoded to an `address`, as such we do not have the `receiver` address. In this event we try returning the tokens to the `sender` on HyperEVM where the sender is the `msg.sender` of the layerzero tx on the source chain.
 
 #### Malformed `composeMsg` - unable to abi.decode(composeMsg) into address and non-evm sender
 
@@ -402,7 +404,7 @@ Wire the OFTs together with the standard layerzero wire command (or any other wa
 npx hardhat lz:oapp:wire --oapp-config <layerzero.config.ts>
 ```
 
-Test the OFTs qith `quoteSend()` or by sending a test lzTransaction across the networks.
+Test the OFTs with `quoteSend()` or by sending a test lzTransaction across the networks.
 
 ## Deploy the Core Spot
 
@@ -428,7 +430,7 @@ You will have to buy a ticker from the Hyperliquid UI - <https://app.hyperliquid
 
 > ⚠️ note: Unless you buy the ticker you will not be able to deploy the Core Spot.
 
-After this we can use the `core-spot create` command to 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. It is crucial to the functioning of the token deployment after which it really is not needed.
+After this we can use the `core-spot create` command to 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 is important — the subsequent deployment steps read from it.
 
 ```bash
 npx @layerzerolabs/hyperliquid-composer core-spot \
@@ -438,7 +440,7 @@ npx @layerzerolabs/hyperliquid-composer core-spot \
     [--log-level {info | verbose}]
 ```
 
-### Step 1/7 `enableFreezePrivilege` (Optional)
+### Step 1/8 `enableFreezePrivilege` (Optional)
 
 **Must be done before genesis if you want freeze capability.**
 
@@ -450,7 +452,7 @@ npx @layerzerolabs/hyperliquid-composer enable-freeze-privilege \
     [--log-level {info | verbose}]
 ```
 
-### Step 2/7 `userGenesis`
+### Step 2/8 `userGenesis`
 
 This is the part where you set the genesis balances for the deployer and the users. Since `HyperCore` tokens are of uint type `u64` the most tokens possible are `18446744073709551615`.
 
@@ -491,9 +493,9 @@ npx @layerzerolabs/hyperliquid-composer user-genesis \
     [--log-level {info | verbose}]
 ```
 
-> ⚠️ Note: There is no limit to the number of time you can re-run this command.
+> ⚠️ Note: There is no limit to the number of times you can re-run this command.
 
-### Step 3/7 `genesis`
+### Step 3/8 `genesis`
 
 This is the step that registers the above genesis balances on `HyperCore`.
 
@@ -507,7 +509,7 @@ npx @layerzerolabs/hyperliquid-composer set-genesis \
     [--log-level {info | verbose}]
 ```
 
-### Step 4/7 `registerSpot`
+### Step 4/8 `registerSpot`
 
 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.
 
@@ -540,7 +542,7 @@ NEXT STEP: Finalize the spot pair with:
 
 **Note:** For additional spot pairs (beyond the first), this command participates in the spot pair deployment Dutch auction.
 
-### Step 5/7 `createSpotDeployment`
+### Step 5/8 `createSpotDeployment`
 
 This step finalizes a spot deployment by setting hyperliquidity parameters. Required after `register-spot` to make the trading pair live on HyperCore.
 
@@ -589,15 +591,15 @@ curl -X POST "https://api.hyperliquid.xyz/info" \
      -d '{ "type": "tokenDetails", "tokenId": "<YOUR_TOKEN_ID>"}'
 ```
 
-### Step 6/7: `setDeployerTradingFeeShare` (Optional)
+### Step 6/8: `setDeployerTradingFeeShare` (Optional)
 
 This is the step where you set the trading fee share for the deployer. It can be in the range of `[0%,100%]`.
 
 A deployer fee share <https://hyperliquid.gitbook.io/hyperliquid-docs/trading/fees> is claimed per transaction on HyperCore. Half of the base rate (50%) is allocated as the deployer fee share. The deployer can choose to forgo this fee share by setting the share to `0%`. This causes the deployer's fee share part to be burnt. If it were to be set to `100%`, the deployer would receive the full fee share part of the fee.
 
 > ⚠️ Note: The trading fee can be reset as long as the new share is lower than the previous share.
 > ⚠️ Note: This step can also be run after the core spot is deployed.
-> ⚠️ **Important**: If you plan to enable quote token capability (Step 6.5/7), read the [Permissionless Spot Quote Assets](https://hyperliquid.gitbook.io/hyperliquid-docs/hypercore/permissionless-spot-quote-assets) documentation before setting this value as it requires a specific trading fee share.
+> ⚠️ **Important**: If you plan to enable quote token capability (Step 7/8), read the [Permissionless Spot Quote Assets](https://hyperliquid.gitbook.io/hyperliquid-docs/hypercore/permissionless-spot-quote-assets) documentation before setting this value as it requires a specific trading fee share.
 
 ```bash
 npx @layerzerolabs/hyperliquid-composer trading-fee \
@@ -608,7 +610,7 @@ npx @layerzerolabs/hyperliquid-composer trading-fee \
     [--log-level {info | verbose}]
 ```
 
-### Step 6.5/7 `enableQuoteToken` (Optional)
+### Step 7/8 `enableQuoteToken` (Optional)
 
 This step enables the token to be used as a quote asset for trading pairs. This allows other tokens to form trading pairs against your token (e.g., TOKEN/YOUR_TOKEN instead of only YOUR_TOKEN/USDC).
 
@@ -630,7 +632,7 @@ npx @layerzerolabs/hyperliquid-composer enable-quote-token \
 
 **Prerequisites:**
 
-- Trading fee share must be set (see Step 6/7 above)
+- Trading fee share must be set (see Step 6/8 above)
 - **Testnet**: 50 HYPE staked + active BUY and SELL limit orders on your token's order book
 - **Mainnet**: All requirements per [Hyperliquid's documentation](https://hyperliquid.gitbook.io/hyperliquid-docs/hypercore/permissionless-spot-quote-assets)
 
@@ -640,7 +642,7 @@ npx @layerzerolabs/hyperliquid-composer enable-quote-token \
 - You must maintain order book requirements for the new `HYPE/ASSET` pair
 - Verify quote asset status with the `list-quote-asset` command
 
-### Step 6.7/7 `enableAlignedQuoteToken` (Optional)
+### Step 8/8 `enableAlignedQuoteToken` (Optional)
 
 This step enables the token to be used as an aligned quote asset for trading pairs. Aligned quote tokens have special properties and requirements different from regular quote tokens.
 
@@ -708,13 +710,13 @@ This will output the calldata and a ready-to-use `cast send` command that you ca
 
 ## Deploy the Composer
 
-While the composer could have been deployed at any point in time due to its statelessness, it is technically the final step of the deployment process. The following script automatically handles the block switching for you.
+While the base composer could have been deployed at any point in time since its constructor only requires immutable values, it is technically the final step of the deployment process. Note that some extensions (e.g. `PreFundedFeeAbstraction`) have mutable state such as `maxUsersPerBlock` and `feeWithdrawalBlockNumber`. The following script automatically handles the block switching for you.
 
 ```bash
 npx hardhat lz:deploy --tags MyHyperLiquidComposer
 ```
 
-> ⚠️ Note: You would need to activate the composer's address on hypercore by transferring any amount of tokens from a wallet that has at least $1 in quote tokens. This $1 will be automatically debited from your accoutn to cover an activation fee.
+> ⚠️ Note: You would need to activate the composer's address on hypercore by transferring any amount of tokens from a wallet that has at least $1 in quote tokens. This $1 will be automatically debited from your account to cover an activation fee.
 
 ## Advanced: Creating Custom Scripts
 

examples/oft-hyperliquid/contracts/MyHyperLiquidComposer.sol

@@ -17,8 +17,7 @@ contract MyHyperLiquidComposer is HyperLiquidComposer {
     ///
     /// @param _oft The address of the OFT
     /// @param _hlIndexId The HyperLiquid core spot's index value
-    /// @param _assetDecimalDiff The difference in decimals between the HyperEVM's ERC20 and the HyperLiquid HIP-1 token
-    ///                 (i.e. 18 decimals on evm and 6 on HyperLiquid would be 18 - 6 = 12)
+    /// @param _assetDecimalDiff The decimal difference: ERC20.decimals() - HIP1.weiDecimals() (must be in [-2, 18])
     constructor(
         address _oft,
         uint64 _hlIndexId,

examples/oft-hyperliquid/contracts/extensions/MyHyperLiquidComposer_FeeAbstraction.sol

@@ -15,7 +15,7 @@ import { PreFundedFeeAbstraction } from "@layerzerolabs/hyperliquid-composer/con
 contract MyHyperLiquidComposer_FeeAbstraction is PreFundedFeeAbstraction {
     /// @param _oft The OFT address
     /// @param _hlIndexId The HyperLiquid core spot index
-    /// @param _assetDecimalDiff EVM - HyperLiquid decimal difference
+    /// @param _assetDecimalDiff The decimal difference: ERC20.decimals() - HIP1.weiDecimals() (must be in [-2, 18])
     /// @param _spotId The spot pair ID (e.g., 107 for HYPE/USDC)
     /// @param _activationOverheadFee Overhead fee in cents on top of $1 base
     /// @param _recoveryAddress Address for fee recovery