fix(perps): reject incomplete order reads and preserve protection IDs

[abretonc7s]

Explanation

Failed or incomplete open-order reads could appear successfully empty. HyperLiquid now rejects failed DEX discovery, order requests and required position context; Lighter and aggregated reads preserve failures. Genuine empty results remain successful, and nonempty orders use complete position context for the requested account.

Successful HyperLiquid TP/SL updates now return confirmed venue IDs in childOrderIds. Each submitted leg receives a CLOID; acknowledgements without IDs get an exact CLOID lookup. Unresolved IDs stay absent without changing accepted placement to failure. Existing failure/restoration behavior remains unchanged.

Breaking changes: callers must handle rejected open-order reads and retain prior state. TP/SL success no longer returns the placeholder orderId string; consumers use childOrderIds, whose presence does not prove protection is still live.

Validation

• Read-safety changes: 1,061 existing checks passed, one skipped. TP/SL follow-up: 25 existing scoped checks passed.
• TypeScript/package build, ESLint, formatting and changelog validation passed. Private archives passed entrypoint and dependency checks.
• Mobile 8.12 controlled transport-fault checks confirmed real empty results, partial/all-DEX rejection, and retention of an accepted order in controller cache through errors. A subsequent real read returned the same ID; exact-order cancellation completed later. No paired screenshot UI-retention claim.
• Mobile 8.12 protected BTC market-order proof passed: the entry filled, returned childOrderIds identified the exact TP limit and SL market triggers, and both configured protections were verified. Exact protections were cancelled and the position closed. Independent final reads showed no orders, positions, pending entries or owned unsigned requests. Mismatched-account cleanup was refused before mutation.

References

No linked issue found. Locally retained evidence, not committed Core files:

• Mobile: temp/provider-read-safety/normal-read-fault.result.json, http-read-fault.result.json, normal-read-fault-nonempty-59587470472.result.json.
• Harness narratives: temp/limit-receipt-device/report.md and temp/protected-receipt-device/report.md.

Checklist

• I've updated existing tests for the changed behavior.
• I've updated relevant documentation.
• I've updated the package changelog.
• I've completed consumer migration and validation for the breaking changes.

---

Note

Medium Risk
Breaking API behavior for open-order reads and TP/SL success payloads requires consumer migration; changes affect trading UI state retention and order classification across multi-DEX HyperLiquid paths.

Overview
Breaking read safety: getOpenOrders no longer masks transport or partial multi-DEX failures as an empty book. HyperLiquid, Lighter, standalone HIP-3 helpers, and the aggregated provider now reject failed or incomplete fetches so callers should catch errors and keep showing prior order state. On HyperLiquid, open orders are classified only after a complete per-account position snapshot across the same validated DEX set (via clearinghouseState), not a best-effort getPositions that could silently drop a DEX.

Breaking TP/SL receipts: Successful HyperLiquid updatePositionTPSL no longer returns the placeholder success string in orderId. It returns confirmed venue IDs in OrderResult.childOrderIds, assigning client order IDs (CLOIDs) to each TP/SL leg and backfilling missing acknowledgement IDs with an exact orderStatus lookup when possible. Accepted placement can still succeed with an empty or partial childOrderIds list when the index has not caught up.

Tests and changelog document the new reject-vs-empty behavior and updated success shapes.

^{Reviewed by Cursor Bugbot for commit c69d98a. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c69d98a. Configure here.}

[cursor]

getOrders loses history on read failure

Medium Severity

getOrders already fetched historical orders, then calls getOpenOrders. Because getOpenOrders now throws instead of returning [], that failure hits the existing catch and returns an empty list, dropping the historical results. Callers can see a successful empty history instead of the open-order error or the data already in hand.

 

^{Reviewed by Cursor Bugbot for commit c69d98a. Configure here.}