[docs-agent] HyperCore private-preview docs: contract-only update - #1510
Conversation
Apply docs-repo-overlay/content/ from abdulmanan-creator/alchemy-hypercore-docs@92a2d56. Contract work, not formatting: * gRPC contracts corrected and narrowed * WebSocket contracts expanded with concrete parameter/payload semantics * Shared HyperCore semantics consolidated into concepts pages 26 files changed under content/api-reference/ (25 modifications + one new shared include, content/api-reference/websockets/hypercore/ledger-delta-types.mdx). No docs.yml change; no OpenAPI/OpenRPC spec changes. Refs DOCS-180 Requested-by: @abdulmanan-creator
🔗 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: df8df1a2d1
ℹ️ 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".
| 4. Subscribe to `l2BookDiff` for the same coin scope and apply only diffs that follow the installed snapshot once the ordering contract is confirmed. | ||
| 5. If replay reports a gap, or a cursor is rejected, discard local state and start again from a fresh snapshot. | ||
| 2. The snapshot establishes the local book state. | ||
| 3. Subscribe to `l2BookDiff` for the same coin scope and apply its diffs to that state. |
There was a problem hiding this comment.
When clients follow this bootstrap, an update can occur between the l2Book snapshot and the later l2BookDiff subscription, but the l2Book snapshot has no seq/prev_seq or cursor position to prove which diffs follow it. That means consumers can apply diffs to a stale snapshot and silently build an invalid local book; the procedure should start from a diff-stream isSnapshot message or document a snapshot position that can be checked against the first diff.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Deferred — flagging to <@abdulmanan-creator> for a design call. The finding is real: the l2Book snapshot has no cursor or per-market seq, so the current bootstrap flow (subscribe to l2Book, then subscribe to l2BookDiff) has a race where diffs between the two subscriptions can be silently lost. Two directions from your comment: (a) start from the diff stream's isSnapshot: true message (matches this file's own Recovery section, but assumes the server pushes an initial snapshot on subscribe — needs confirmation from the HyperCore team), or (b) surface a snapshot position on l2Book that a client can check against the first diff's prev_seq (larger contract change). Not applying unilaterally here since it re-shapes the intended bootstrap flow; posted this in Slack for Abdul to weigh in.
Four internal-contradiction fixes flagged by codex on PR #1510: * content/api-reference/websockets/hypercore/l4-book-updates.mdx — Recovery bullets told clients to persist per-market `seq` and check `prev_seq`, but the payload table has neither. The shared concepts page (`timestamps-cursors-and-replay#detecting-gaps`) classifies this stream as server-side gap detection with no client sequence bookkeeping. Dropped the seq/prev_seq bullets, kept cursor-based persistence + isSnapshot handling, and added a one-line pointer to the shared model. * content/api-reference/websockets/hypercore/tpsl-updates.mdx — Same fix as above (`tpslUpdates` is also classified as server-side detection). * content/api-reference/hypercore-grpc/stream-bbo-book.mdx — Key-fields section documented a `bbo` tuple, but the `BboBookUpdate` proto right above it defines separate `bid` and `ask` `Level` fields. Split the entry to match the proto. * content/api-reference/hypercore-grpc/stream-l2-book.mdx — Key-fields section documented a `levels` tuple, but the `L2BookUpdate` proto defines separate `bids` and `asks` repeated-`Level` arrays. Split the entry to match the proto. Refs DOCS-180 Requested-by: @abdulmanan-creator
2 participants
Summary
Apply the latest HyperCore private-preview overlay from
abdulmanan-creator/alchemy-hypercore-docs@92a2d56(docs-repo-overlay/content/) ontoalchemyplatform/docs. This is a straight follow-up to PR #1488 (DOCS-167, already merged); all pages continue to sit underhidden: truesections, so nothing on the live site becomes visible in nav or search from this change.The change is contract work, not formatting:
content/api-reference/hypercore-grpc/)content/api-reference/websockets/hypercore/)content/api-reference/data/hypercore/andcontent/api-reference/hyperliquid/hypercore/)Diff shape
26 files under
content/api-reference/change:content/api-reference/websockets/hypercore/ledger-delta-types.mdx, referenced byuser-non-funding-ledger-updates.mdxandall-user-non-funding-ledger-updates.mdxvia<Markdown src="./ledger-delta-types.mdx" />No
content/docs.ymlchange. No OpenAPI/OpenRPC spec changes (overlaysrc/matches the current repo state bit-for-bit).Repo checks
pnpm run lint— only pre-existing baseline warnings onMDX_FEATURES.mdandcontent/wallets/pages/smart-wallets/session-keys/legacy-session-keys.mdx; no warnings or errors on the HyperCore diff.pnpm run validate:docs-yml— passes.pnpm run generate:rest/pnpm run generate:rpc/validate:rest/validate:rpc— skipped intentionally;src/openapi/andsrc/openrpc/are unchanged.-list markers in the HyperCore diff — none present.docs.alchemy.com/reference/legacy URLs and bare/wallets/…links in the HyperCore diff — none present.Linear
DOCS-180 — HyperCore private-preview docs: contract-only update
Requested by
@abdulmanan-creator (via Slack thread)