Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
f3c03e8
feat(perps-controller): give each exchange its own balance, positions…
geositta Nov 13, 2026
9d73bfd
chore: linting
geositta Nov 13, 2026
b5d0b35
fix(perps-controller): honor venue targets in closes, deposits and ac…
geositta Nov 13, 2026
340d2d0
fix(perps-controller): enforce strict aggregated account reads and co…
geositta Nov 13, 2026
372a203
fix(perps-controller): price batch closes per venue and isolate balan…
geositta Nov 13, 2026
67e34fd
fix: lighter provider #readCrossMarginSummary is now best-effort
geositta Nov 13, 2026
d9d0971
fix: distinguish no verdict yet from known gone
geositta Nov 13, 2026
a016fd6
chore: linting
geositta Nov 13, 2026
d3b2c4a
fix: review finding changes (#11552)
geositta Nov 16, 2026
e56fafd
fix: account scope, close-fee venue, cancellation fallback
geositta Nov 17, 2026
4e60210
fix: close all, account streams and cancellation issues
geositta Nov 17, 2026
06ab15e
fix: direct cancel should report, HIP-3 outage blocks main-DEX cancels
geositta Nov 17, 2026
0c73fa9
fix: stale venue balances stay live
geositta Nov 17, 2026
c8f83c4
docs(perps-controller): changelog entry for HIP-3 open-order fixes
geositta Nov 17, 2026
e59b106
fix: review findings
geositta Nov 17, 2026
96fcaaf
fix: followup review findings
geositta Nov 17, 2026
d641017
fix(perps-controller): add missing selection helpers, tidy changelog
geositta Nov 17, 2026
a4832b1
strict HyperLiquid account reads now fail closed, and the README, JSD…
geositta Nov 17, 2026
e2b6e32
fix(perps-controller): strict HyperLiquid account streams, empty clos…
geositta Nov 17, 2026
5f7e203
refactor(perps-controller): narrow stream-route and aggregation types…
geositta Nov 18, 2026
c84ea66
fix(perps-controller): keep other-account streams and stale DEX slice…
geositta Nov 18, 2026
e30bcb8
docs(perps-controller): describe per-venue account data and batch rou…
geositta Nov 18, 2026
6b052f9
fix(perps-controller): resolve TP/SL sizes on partial order discovery…
geositta Nov 18, 2026
22b46f8
chore: merge ci
geositta Nov 18, 2026
d36e9ad
fix: discovery failures should reject through the existing error path
geositta Nov 18, 2026
8e0e901
fix: capture the account address each time the provider subscription …
geositta Nov 18, 2026
84eb43c
fix: reconstruct combined totals using the existing aggregation helpe…
geositta Nov 18, 2026
5fa1352
fix: deposit service should return providerId
geositta Nov 18, 2026
ad77918
docs(perps-controller): fix changelog section ordering
geositta Nov 18, 2026
e80f01d
chore(perps-controller): fix import ordering in AggregatedPerpsProvider
geositta Nov 18, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 53 additions & 2 deletions packages/perps-controller/CHANGELOG.md

Large diffs are not rendered by default.

120 changes: 115 additions & 5 deletions packages/perps-controller/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,11 +78,121 @@ registered venue, including HyperLiquid-only fallback when Lighter is
unavailable, accepts these writes without an explicit route because there is
only one destination.

`cancelOrders` and `closePositions` cannot name a venue yet, so while multiple
venues are registered they always return `PROVIDER_ROUTE_REQUIRED` instead of
reaching the default venue. Cancel-all and close-all therefore stay unavailable
in multi-venue aggregated mode until a release routes each order or position to
its own venue and Lighter implements `cancelOrders` and `closePositions`.
`cancelOrders` and `closePositions` are venue-attributed rather than refused.
`cancelOrders({ orders: [{ orderId, providerId }] })` matches both fields,
so a colliding ID on another venue is not cancelled. Non-empty legacy `orderIds`
or `symbols` filters without scoped `orders` return `PROVIDER_ROUTE_REQUIRED`
when multiple venues are registered; use `orders` to identify the intended venue. Cancel-all batches reach every venue holding an order. An empty
`orders`, `orderIds` or `symbols` filter selects no orders. `closePositions` takes either `closeAll` (fans out to every enabled
venue) or explicit `targets` of `{ symbol, providerId }`. A supplied
`targets` list wins over `closeAll` and `symbols`, so an empty one closes
nothing. A legacy symbols-only close without venue identity still returns
`PROVIDER_ROUTE_REQUIRED` while multiple venues are registered, because closing
a symbol that exists on both venues is ambiguous. Results carry a `providerId`
per item, so identical symbols or order ids on different venues are never
conflated: each venue's successes and failures are reported
separately and one venue's failure never hides another venue's success.

Batch cancellation uses strict discovery: an unavailable venue is not an empty
venue. `CancelOrdersResult.discoveryFailures` names each failed venue and, for
ID-filtered requests, its unresolved `orderIds`. These targets have no discovered
symbol, so they are separate from `results`. `failureCount` includes unresolved
IDs, or one failure per unavailable venue when the order count is unknown;
`error` is the stable `BATCH_INCOMPLETE` code even when `success` is true.
Already discovered scoped targets are not counted as discovery failures, even
when another DEX on the same venue is unavailable. Before presenting a batch as
complete, clients must inspect `failureCount` and per-item `results` as well as
`error`, `discoveryFailures` and `failures`.
A complete direct-venue discovery failure uses the same code and attributes
its unresolved targets to the provider's validated protocol identity, never a
tracing tag. If an unknown protocol cannot be attributed safely, the result
still returns `BATCH_INCOMPLETE` without inventing a venue.

Both multi-venue cancel and close execution batches return `BATCH_INCOMPLETE`
when a venue throws or returns a batch error. `CancelOrdersResult.failures` and
`ClosePositionsResult.failures` retain every venue detail as
`{ providerId, error }[]`; discovery failures remain separate from execution
failures and per-item `results`. Successful work on other venues is preserved.
For close-all, a venue whose position discovery throws contributes one failure
when the number
of unclosed positions is unknown. Direct single-venue batch errors are preserved.

Batch closes resolve fees only for venues that consume fee resolutions or
discounts, exposed by `PerpsProvider.supportsFeeResolution(providerId)`.
Resolutions are computed sequentially: subscription notional allocated to an
earlier venue is subtracted from the allowance available to later venues.
Unused allowance is not persisted locally; the backend remains its source of truth.

Existing lenient reads remain unchanged. `getPositions` and
`getOpenOrders` (both venues, including standalone reads) accept `{ throwOnUnavailable: true }` for callers
that must distinguish failed discovery from an empty venue. Strict aggregated
open-order reads throw the exported `OrderDiscoveryError`, whose `orders` retain
successful reads and whose `failures` identify unavailable venues. These are
additive contracts: no state migration or existing call-site changes are needed,
but consumers of batch results should handle partial discovery before rollout.

## Per-exchange account data

In aggregated mode, `getAccountState` and `subscribeToAccount` query every
enabled venue. The result keeps the top-level `AccountState` numeric fields as
combined totals — `totalBalance`, `spendableBalance`, `withdrawableBalance`,
`marginUsed` and `unrealizedPnl` are decimal-safe sums over the venues that
reported data, and `returnOnEquity` is the margin-weighted combined rate
(`100 × Σ unrealizedPnl ÷ Σ marginUsed`; `0` when no margin is used).

Each venue's own snapshot is in `providerStates[providerId]`: either
`{ status: 'available', state, providerId }` with that venue's balances,
`crossMarginSummary` and `subAccountBreakdown` (never merged into the top
level — cross-venue collateral is not mutually usable), or
`{ status: 'unavailable', error?, providerId }` for a venue whose read failed
or whose snapshot has a missing or non-finite additive field. Aggregated
account reads request that failure strictly: a HyperLiquid DEX clearinghouse
read or spot clearinghouse read that fails rejects the venue, so the combined
total is `partial` instead of a complete portfolio value. Aggregated account
streams ask each venue for `requireCompleteAccount`: HyperLiquid emits `null`
until every configured DEX has published and its spot balance has loaded, so a
failed DEX subscription keeps the total `partial` too. A stream venue
is `{ status: 'pending', providerId }` until its first snapshot, even if it
emits `null`. A rejected subscription setup is immediately `unavailable` instead
of pending. Lighter can only serve the selected wallet: requesting another
`accountId` excludes Lighter rather than mixing wallets, and a scoped stream
never starts emitting another wallet's balances after selection changes.
After a snapshot, `null` makes it unavailable. `aggregate`
metadata (`{ status: 'complete' | 'partial', availableProviders,
unavailableProviders, pendingProviders? }`) says whether the totals cover
every enabled venue. A `partial` total is a
subtotal: never present it as the user's complete portfolio value. A failed
read is never shown as a zero balance; a confirmed zero or nonexistent venue
account is an `available` entry with zero balances. When no venue has usable
data the read throws (REST) or the stream emits `null`. The account callback's
optional second argument carries this completeness metadata even when the
state is `null`, so pending and unavailable venues remain distinguishable.

The controller writes `perpsBalances[providerId]` from live account updates —
one entry per available venue with `totalBalance`, `unrealizedPnl` and
`lastUpdated`. Live updates leave `accountValue1dAgo` unset. A venue whose
data becomes unavailable has its entry removed rather than left looking live.
A pending venue keeps its stored entry until it reports a snapshot, including
when the first stream update is `null`. A `null` total clears `accountState`
and removes only explicitly unavailable venues' entries. Every balance entry
is cleared when the selected account changes or the network is toggled, and a
stream for an explicit `accountId` other than the selected account only
reaches its own callback: it neither writes nor clears `accountState` or
balance entries.
Combined `spendableBalance` and `withdrawableBalance` span venues: neither is
a limit any single venue will enforce on a new order or a withdrawal.

Market streams (`subscribeToCandles`, `subscribeToOICaps`,
`subscribeToOrderBook`) take an optional `providerId`. An explicit route
reaches that venue — required when both venues list the same symbol — and
stays pinned when the routing default changes. Omitting it keeps the
default-routed behavior. `getDepositRoutes` and `getWithdrawalRoutes` return
every active venue's routes, each tagged with a `providerId`; identical
asset/chain routes from different venues are distinct entries.
`depositWithConfirmation` funds the route for its `providerId`, or the
routing default when that is omitted, and fails closed when that venue has
no route. The chosen route's venue is captured on the deposit or withdrawal
record it initiates.

## Rewards discounts and fee previews

Expand Down
Loading
Loading