feat(perps): sync controller from mobile — balance split + mode-aware spot fold

[michalconsensys]

Explanation

Syncs app/controllers/perps/ from MetaMask Mobile commit 355c9b656b to packages/perps-controller/src/.

Key changes

• BREAKING: AccountState balance rename — availableBalance → spendableBalance, availableToTradeBalance → withdrawableBalance for clearer semantics across HL abstraction modes (Unified, Standard, Portfolio)
• Mode-aware spot fold — addSpotBalanceToAccountState now folds free spot USDC into both spendableBalance and withdrawableBalance for Unified/Portfolio modes, while Standard/DEX-abstraction modes keep spot separate
• Throttled WS-driven userAbstraction refresh — HL-web mode flips (Unified ↔ Standard) now propagate back without requiring a restart or account switch

Mobile PRs included

• refactor(perps): split AccountState balances + mode-aware spot fold (#29303)
• feat(perps): force unified account (#29492)

Files changed (12 source files)

• constants/hyperLiquidConfig.ts — minor config tweak
• constants/perpsConfig.ts — add ABSTRACTION_MODE_REFRESH_THROTTLE_MS
• providers/HyperLiquidProvider.ts — balance field renames, mode-aware fold
• providers/MYXProvider.ts — balance field renames
• services/HyperLiquidSubscriptionService.ts — per-user abstraction mode maps, throttled WS refresh, balance renames
• types/hyperliquid-types.ts — new types for abstraction mode handling
• types/index.ts — AccountState field renames with JSDoc
• utils/accountUtils.ts — addSpotBalanceToAccountState refactor with resolveFoldedBalance helper
• utils/hyperLiquidAdapter.ts — balance field renames
• utils/hyperLiquidValidation.ts — balance field renames
• utils/myxAdapter.ts — balance field renames
• utils/orderCalculations.ts — balance field renames

Suppressions

1 new ESLint suppression: @typescript-eslint/no-unused-vars in HyperLiquidSubscriptionService.ts — caused by core's no-unnecessary-type-assertion rule removing a as Promise<UserAbstractionResponse> cast that mobile has, leaving the import unused. Total perps suppression count: 9.

References

• Sync state: .sync-state.json updated to mobile commit 355c9b656b
• Sync script: scripts/perps/validate-core-sync.sh

Changelog

See packages/perps-controller/CHANGELOG.md — entries added under ## [Unreleased].

Note: CHANGELOG PR links use #NNNN placeholder — will be updated with this PR's number after creation.

Made with Cursor

---

Note

Medium Risk
Medium risk because it introduces breaking changes to the AccountState contract and adjusts HyperLiquid balance/withdraw validation and spot-collateral folding based on abstraction mode, which can directly affect displayed balances and allowed withdrawals/orders.

Overview
BREAKING: Renames AccountState balance fields to spendableBalance and withdrawableBalance and updates all perps providers/adapters/calculations/validation to use the new semantics (including per-subaccount breakdown and cache hashing).

Makes spot USDC folding mode-aware: addSpotBalanceToAccountState now always impacts totalBalance, and only contributes to spendableBalance/withdrawableBalance when userAbstraction indicates Unified/Portfolio mode; disk cache key is bumped to PERPS_DISK_CACHE_USER_DATA_V2 to avoid stale legacy payloads.

Improves live mode handling by adding a throttled, per-user WS-triggered userAbstraction refresh in HyperLiquidSubscriptionService so HL-web mode flips propagate without restart/account switch, and adds a guard in HyperLiquidProvider.updateIsolatedMargin to ensure spendableBalance covers margin additions.

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

[mcmire]

A couple of minor things.

[mcmire]

LGTM.