…lance

Problem
-------

HyperLiquid's spot clearinghouse state (per-coin total + hold) changes on
every on-chain event — local trades, external-client trades, hourly
funding, liquidations, deposits, transfers, usdClassTransfer — but none
of those are surfaced through webData2/webData3/clearinghouseState. The
existing REST path (#refreshSpotState -> infoClient.spotClearinghouseState)
only runs on cold-start or standalone getAccountState calls, so the cached
spot snapshot goes stale the moment anything moves it. UI surfaces that
read availableToTradeBalance or totalBalance see stale values until the
next account-state screen refresh.

Fix
---

Subscribe to HL's existing `spotState` WebSocket feed alongside the
webData2/webData3 user-data subscriptions already established in
subscribeToAccount. The push handler:

- updates #cachedSpotState + #cachedSpotStateUserAddress with the pushed
  SpotClearinghouseStateResponse
- bumps #spotStateGeneration so any in-flight REST #refreshSpotState
  drops its result rather than overwriting the fresh WS snapshot
- re-runs #aggregateAndNotifySubscribers when #dexAccountCache is
  populated, so subscribers see the spot-folded totalBalance /
  availableToTradeBalance immediately

REST fallback is left in place: #refreshSpotState still covers cold
start before the first WS tick and the standalone getAccountState path
that does not own a subscription.

Shape
-----

- #spotStateSubscriptions: Map<userAddress, ISubscription> — one sub
  per user, mirrors the per-user lifecycle of #orderFillSubscriptions.
- #spotStateSubscriptionPromises: Map<userAddress, Promise<void>> —
  in-flight guard so two concurrent subscribeToAccount calls share a
  single WS handshake.
- Cleanup in both #cleanupSharedWebData3ISubscription (ref-counted)
  and clearAll (shutdown).

Test coverage
-------------

Five new tests in the "spotState WebSocket Subscription" block cover:
establishment on subscribeToAccount, de-duplication across concurrent
subscribes, re-notification on push, user-filter guarding cross-account
events, and unsubscribe on last-subscriber removal.

Notes
-----

No change to #ensureSpotState, #refreshSpotState, #spotStateGeneration,
or #cachedSpotState semantics — those remain authoritative for the
REST-driven cold-start and standalone paths. This commit adds a push
source for the same cache without touching the REST writers.

Adds a public `getExchangeClient()` method on HyperLiquidProvider that
delegates to HyperLiquidClientService.getExchangeClient(). Not part of
the PerpsProvider interface — documented as an escape hatch for agentic
validation flows and test harnesses that need to drive HL mutations
directly (order, usdClassTransfer, userSetAbstraction, etc.) while
bypassing TradingService, metrics, error-handler wrappers, and cache
invalidation.

Needed by the upcoming tat-3016 regression recipe to probe that a
mutation originating outside TradingService still propagates through
the spotState WebSocket subscription added in the previous commit.
Production code paths continue to go through the provider's own methods.

Tests cover delegation and error propagation.

…ance-validation recipe

Withdraw-path non-regression anchor for the hl-balance-validation flow
on main. The agentic flow asserts that the text rendered at this testID
matches AccountState.availableBalance (withdrawable) and never leaks the
availableToTradeBalance spot fold — the invariant TAT-3016 hinges on.
Previously the flow's settle-withdraw wait_for timed out because the
testID was only referenced in flow JSON, not rendered by the view.

Spot-funded Unified-mode accounts were auto-steered onto external USDC
pay-token because useDefaultPayWithTokenWhenNoPerpsBalance gated on raw
availableBalance (= withdrawable = 0 on Unified). With the field now
populated end-to-end, switch the gate to
availableToTradeBalance ?? availableBalance so the order form defaults
to Perps balance when spot collateral is available.

Caught by evidence/recipe.json: capture-order-form step showed
paySymbol USDC instead of Perps on the Trading fixture.

PerpsMarketDetailsView.hasDirectOrderFundingPath only checked raw
availableBalance (= withdrawable = 0 on Unified-mode spot-funded) plus
the external pay-token fallback. After the pay-token hook learned to
skip the external steer when availableToTradeBalance is non-zero, the
gate flipped false and the Long/Short buttons disappeared, leaving
Add-Funds as the only CTA on Unified-mode accounts with spot collateral.

Add tradeableBalance (availableToTradeBalance ?? availableBalance) as
the primary direct-funding signal. Original availableBalance check
kept for provider/mode compatibility.

… TAT-3050 state

Recipe adjustments after first run:
- Reset leaked selectedPaymentToken + pending BTC trade config as the
  first node so baseline starts from a clean state (TAT-3050 sidestep).
- Focus the graph on the hl-balance-validation pass which already
  covers: fold invariant, market-list balance text, withdraw non-regression
  (fold must NOT leak), and Pay-with row defaulting to Perps balance
  when availableToTradeBalance > 0.
- External-client usdClassTransfer probe + UI-driven trade-open-market
  cycle deferred to a follow-up recipe — usdClassTransfer is abstraction-
  sensitive on Unified accounts and trade-open-market has a pre-existing
  gap on the RedesignedConfirmations route. Scope kept to what the
  current PR affects.

Pre-conditions:
- perps.sufficient_balance now gates on availableToTradeBalance
  (fallback: availableBalance). Previously read raw availableBalance
  which is 0 on HL Unified mode even when spot collateral covers orders
  — recipe pre-condition failed on accounts the product considers
  tradeable.

PerpsOrderView showed 'Insufficient balance. Required: $3.37, Available: $0'
on Unified-mode accounts with spot-only collateral because usePerpsOrderForm
fed availableBalance (= withdrawable = 0) into balanceForValidation,
maxPossibleAmount, and initialBalancePercent. With the field now populated,
prefer availableToTradeBalance when no external pay-token is selected.

Consumer surfaces fixed in this commit:
- perps-order-view slider/keypad max amount
- perps-order-view percentage buttons
- perps-order-view margin-vs-required gate
- 'Insufficient funds' red text at the bottom of the form
- Place Order button enablement

…on Unified mode

Symptom
-------

On HyperLiquid Unified/Portfolio Margin accounts opening a position
caused totalBalance to increase by the position margin, not by the
unrealized PnL. Example: $106 spot, 0 perps, no position → total $106.
Open a $11 long (~$3.37 margin): spot stays $106, spot.hold becomes
$3.37, perps accountValue becomes $3.37 — previous formula
`perpsBalance + spotBalance` reported $109.37. No wealth changed hands
but the displayed total went up.

Root cause
----------

marginSummary.accountValue on Unified/PM equals marginUsed +
unrealizedPnl + withdrawable_perps, where marginUsed is the margin
reserved from spot (reported by HL as spot.hold). Adding accountValue
to spotBalance double-counts that reservation.

Fix
---

Subtract spotHold from the totalBalance sum in both the single-DEX
adapter (adaptAccountStateFromSDK) and the aggregated fold
(addSpotBalanceToAccountState):

  totalBalance = perpsBalance + spotBalance - spotHold

On Standard mode spotHold = 0, so the formula reduces to the previous
`perpsBalance + spotBalance` and no behaviour changes. On Unified/PM
the subtraction cancels the held-margin double-count, so totalBalance
now moves only with unrealizedPnl — matching HL's own "Perp Equity"
semantics.

availableToTradeBalance is unaffected: it already computes
`availableBalance + (spotTotal - spotHold)` which correctly nets the
reservation out of the tradeable pool.

…recipe

HyperLiquidProvider.getExchangeClient() now returns Promise<ExchangeClient>
to match the shape hl-provision-fixture already assumes (it chains .then
on the return value). The underlying client-service call stays sync; the
wrapper is async so callers await a single pattern.

Recipe overhauled to cycle abstraction modes:
- setup captures initial state + resets payment-token
- workflow: set Standard → validate + parity → set Unified → validate +
  parity + order-form wiring → manual gate
- teardown restores Unified

Runs on both testnet and mainnet.

…ardown cleanup

Scenario from a reviewer report: open limit orders, 'cancel all',
balance stuck in pre-cancel state. Adds limit-cycle block that:
- seeds baseline (tradeable ≈ total)
- places a BTC limit at 50% of mid (won't fill)
- asserts tradeable drops below total (hold reserved)
- calls cancelOrders({cancelAll:true})
- asserts tradeable returns within $0.20 of total (hold released)

Recipe now also pre/post cancels any leftover orders so abstraction
mode switches don't fail on 'cannot disable unified account with open
orders'.

Removing three files that will be shared/reviewed separately, not as
part of this spotState subscription PR:
- docs/perps/tat-3016-clarity.md — incident brief + architectural
  rationale. Lives better as a team doc than in the PR diff.
- evidence/recipe.json — regression recipe. Will be committed through
  a separate agentic-validation track.
- scripts/perps/agentic/teams/perps/pre-conditions.js — reverted to
  main. The availableToTradeBalance fallback in perps.sufficient_balance
  was needed to run the recipe; now that the recipe is out of scope,
  leave main's version untouched.

This PR is now strictly: HL spotState subscription wiring,
AccountState.availableToTradeBalance population, UI consumer rewiring,
and supporting unit tests.