Preserve Hyperliquid Asset IDs Through Numeric Conversion
By DX Research Group · · Market data
An integer-width fixture and metadata binding check prevent valid JSON from routing an action to the wrong asset.
Treat a Hyperliquid action asset ID as an exact integer with a validated mapping, rather than a display number. The relevant precision failure can occur in database width, serialization, or a cast long before ordinary floating-point limits matter. We would test the complete round trip from metadata lookup to the action payload and back into the trace.
Hyperliquid's asset-ID documentation specifies integer encodings for native perps, spot, and builder-deployed perps. For builder-deployed perps it gives 100000 + perp_dex_index × 10000 + index_in_meta. The implementation must retain the inputs to that mapping.
A small integer can still overflow a narrow column
Assume a synthetic builder-deployed market with dex index 1 and metadata index 0. Its encoded asset value is 100000 + 1 × 10000 + 0 = 110000. This is a formula fixture, rather than a statement about which market currently occupies that position.
An unsigned 16-bit storage field permits values through 65,535. If an unsafe cast wraps modulo 65,536, 110,000 becomes 110000 - 65536 = 44464. Both values are integers, and both serialize as valid JSON numbers. Only the first preserves the intended encoding. A checked cast should reject the overflow instead of manufacturing a different asset.
| Conversion stage | Expected value | Required check |
|---|---|---|
| Metadata mapping | 110000 | Correct namespace and indices |
| Persistent storage | 110000 | Sufficient integer range |
| Action serialization | 110000 | Integer equality |
| Trace reconstruction | 110000 | Same mapping version |
Distinguish exactness from correct routing
The value 110000 is exactly representable in common double-precision arithmetic. That fact says little about whether the mapping refers to the intended network, dex, or metadata version. Numeric round-trip checks and semantic mapping checks should therefore remain separate.
Reject fractional IDs, exponential strings that a parser interprets inconsistently, and values outside the supported action schema. Preserve the validated integer and the metadata evidence used to resolve it. A formatted UI label can help the operator, but its string should never become the sole source for rebuilding an action ID.
Where an adapter receives numeric identifiers as strings, parse through an exact integer path and compare the serialized result to the original validated value. Avoid rounding a fractional input into an apparently admissible ID. Log the rejected value with an appropriate privacy policy so the failure can be reproduced.
Bind the identifier before policy checks
Policy should inspect the same market mapping and integer that execution will submit. A later cast or lookup can otherwise change the target after authorization. The proposed regression fixture would test 110000 through each storage and language boundary, plus deliberate fractional and overflow cases.
Our instrument-key note covers the semantic namespace. Our typed-action note covers validation before submission. This contribution is narrower: exact integer preservation across implementation boundaries, with a checked overflow example. It establishes an action-routing contract, leaving venue acceptance and actual execution to their own receipts.