Am/hypercore node corrections - #1599
Conversation
🔗 Preview Mode
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1664c090b9
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| | `coin` | string | Market symbol for the order. | | ||
| | `side` | string | Side code: A is ask/sell; B is bid/buy. | | ||
| | `limitPx` | string | Limit price for the order. | | ||
| | `sz` | string | Filled size for the order status. | |
There was a problem hiding this comment.
sz as the resting order size
For an L4 snapshot, sz is the order's current resting size, not the amount already filled. This distinction matters after a partial fill: consumers reconstructing liquidity from the documented book_orders payload would otherwise interpret the remaining quantity backwards. Describe it as the current or remaining size; origSz already provides the original quantity.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 771268d. You were right, and it was broader than this page — the same description had been copied to websockets/hypercore/user-order-updates.mdx and builder-order-updates.mdx. All three now read "Current resting size of the order," with origSz unchanged as the original.
Confirmed against node output: freshly-placed open orders show sz equal to origSz, so sz cannot be filled size. Swept every sz description across the HyperCore pages — fills, trades, and book levels were already correct and were left alone.
| | orders[] | object | Order status record. | | ||
| | orders[].time | string | Time the node recorded the order-status event. | | ||
| | orders[].user | string | User identifier. | | ||
| | orders[].hash | string \| null | Populated for `open`; null for every other observed status. Rejected and canceled orders have no submitted transaction. | |
There was a problem hiding this comment.
The event example on this page has status: "filled" and a non-null hash, while this newly added rule says every status other than open has a null hash. A consumer following the table could reject or discard valid filled events matching the example. Either make the example reflect the asserted contract or document the non-open statuses for which the hash can remain populated.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 771268d. The rule is correct — non-null hash count equals the open count exactly across 106,153,367 node order-status events — so the example was the stale half. Changed it to status: "open", which keeps the non-null hash consistent with the documented rule. user-order-updates.mdx already used open and needed no change.
2 participants
Description
Corrections to the HyperCore private-preview documentation, verified against a Hyperliquid node's own output and live probes of the production /info endpoint. Contract work rather than formatting.
Follows #1555. Node verification surfaced errors in what that PR shipped, along with several claims that were wrong about the chain rather than about our own naming. Every change here is measured; where a fact could not be established, the page now says so rather than guessing.
Basis: 106 million order-status events across 86,646 blocks, the full replica_cmds action vocabulary, fills, TWAP, ledger and book-diff streams, the node's own --serve-info server, live probes of all 55 /info types, and the nine appendix sections of the July 30 technical design review that supersede its body.
Pages remain hidden: true. A customer is actively reading them.
Related Issues
No Linear ticket — authored directly rather than through docs-agent, following the branch-and-PR workflow in the Docs Contribution Guide. Follows #1555.
Changes Made
Customer-visible errors
Removed an internal Source tier column from seven WebSocket pages — 151 cells reading Extended-provider, Foundation-native, and Our own choice
Replay depth was stated as "approximately 48 hours" on four pages. Appendix A.4 of the design review removed disk backfill from the client path, so that figure describes infrastructure a customer cannot reach. Rewritten as a short reconnect window, no number published
Two pages said HIP-4 permissionless deployment was testnet-only and mainnet outcome data was empty. HIP-4 went permissionless on mainnet on 2026-08-30; the node returns seven mainnet templates
The REST overview claimed all documented /info reads are "served today." That was false for 21 of them
REST availability
All 44 request-type pages now carry an availability marker: 31 available now, 13 coming with HyperCore. Four generated operations say so in their descriptions
Eight endpoints that return 200 today had no page: exchangeStatus, liquidatable, maxMarketOrderNtls, userToMultiSigSigners, perpsAtOpenInterestCap, marginTable, perpDexs, webData2. Added, with /info schema discriminators updated
Contract corrections
orders[].status had no documented values at all. The node emits 22; badAloPxRejected alone fires 27 million times
hash is null on 64% of order-status events — its non-null count equals the open count exactly
Book diff update carries origSz/newSz, not sz; remove has no payload object
topUpIsolatedMargin does not exist — the action is topUpIsolatedOnlyMargin, documented on four pages as top_up_isolated_margin
Field casing unified to camelCase on four leverage pages, matching the Foundation API and the rest of our surface
L4 snapshot structure corrected in three ways, including an omitted untriggered_orders key
tif nullability, orderType display strings, triggerCondition as prose rather than an enum, ledger delta shape variance, userRateLimit volume scaling, validatorL1Votes response shape
Navigation and links
trades was missing from the stream catalog — 24 listed against 25 in nav
OpenAPI tags removed from all eight operations, eliminating duplicated sidebar family names. Solana, Ethereum, and Base are all flat and untagged
Five "REST snapshot read" links pointed at the REST landing page; each retargeted to the snapshot it means — L2 diff, L4 book, or trigger-order
extra-agents was labeled an enriched composite; it is a native /info type returning 200 today
gRPC Level was referenced on three book pages, defined on one
Known and deliberate
Six items are flagged for engineering rather than resolved, because the evidence does not settle them: txIndex semantics, statusTimestamp provenance, whether l2BookDiff.seq is global across servers, rejected on the TP/SL table, Level.n on the BBO gRPC page, and three undocumented misc_events inner keys.
No connection-lifecycle or rate-limit content was written — the design review contains no heartbeat, timeout, or numeric limit specification and states that rate-limit definitions "remain the real work." No envelope or wire-format field was changed; NOD4-91 is still in progress.
Testing
I have tested these changes locally
I have run the validation scripts (pnpm run validate)
I have checked that the documentation builds correctly
pnpm generate, pnpm generate:rest, pnpm validate, pnpm validate:rest, pnpm validate:docs-yml, and git diff --check all pass.
pnpm lint exits non-zero on a single pre-existing TypeScript error already on main: src/content-indexer/visitors/processors/tests/process-openapi.test.ts(507,32), Property 'path' does not exist on type 'NavItem'. No content failure contributes.
Generated REST URLs were re-verified against the content index after the tag removal, and all retargeted internal links confirmed to resolve. All changes are confined to HyperCore paths plus the HyperCore subtree of content/docs.yml.