feat(perps-controller): add Lighter perps venue (initial implementation, flag-gated)

[abretonc7s]

Explanation

TAT-3766: add Lighter as a second perps venue. Started as a spike, now a full LighterProvider in @metamask/perps-controller, hardened through 23 rounds of adversarial cross-review and validated end-to-end against live Lighter testnet.

What's in it

• Full trading surface behind the PerpsProvider interface: place/cancel/close orders, venue-linked OCO TP/SL (grouped trigger orders), isolated margin add/remove, leverage updates, signed L2 withdraw, historical orders/fills/funding/ledger, and live streams (prices, account, positions, orders, fills, order book, candles) over a shared WebSocket with REST-polling fallback.
• Signer model: deterministic venue-key derivation via personal_sign (raw EVM key never leaves the keyring — hardware-wallet compatible). The Go/WASM signer is injected through a LighterSignerBridge seam so mobile's WebView bridge and the headless Node adapter are interchangeable.
• Financial-safety architecture (the bulk of the review rounds): a durable nonce-dispatch ledger with exact tx-hash reconciliation — an ambiguous dispatch is never blindly retried; proven-committed outcomes are quarantined until explicitly acknowledged per-outcome (getRecoveredDispatches/acknowledgeRecoveredDispatch); a TP/SL settlement journal that survives crashes and restores nothing it cannot prove, parking unprovable protection as durable manual recovery (getPendingManualRecoveries); process-wide serialization of venue writes, the ledger, and the bridge's singleton WASM client; session fences on every account switch.
• Controller wiring behind a flag: PerpsProviderType gains 'lighter'; enablement via providerCredentials.lighter.enabled or the perpsLighterProviderEnabled remote flag. New controller actions expose the safety states to clients.

How it was validated

• Unit: 213 provider tests (3,031 package-wide), including deterministic fault-injection proofs for response loss, masked commits, restarts, account switches mid-flight, concurrent providers, and storage failures. Every review-round fix was proven RED against the prior commit before landing.
• Live testnet e2e (real venue, real WASM signer built from source): sign-only 9/9 (pinned WASM identity contract), key registration, order-lifecycle 7/7, TP/SL 12/12 (including a real venue-linked OCO pair), close-position 5/5 with both fills observed on the trades stream, margin/leverage 7/7 on a fresh faucet account.
• Mainnet read path: 227 active perp markets, full-catalog WS snapshot, candles.
• On-device (iOS simulator): live prices/candles/positions over WS-only transport; WASM signer mount→ready ~2.1 s, round-trip 32–78 ms.

Open items

• editOrder deliberately returns an error: Lighter accepts ModifyOrder submissions without executing the reprice — raised with the venue; cancel + re-place instead.
• Mobile client integration (WebView signer bridge + recovery-state UI): feat(perps): Lighter venue POC — WebView WASM signer bridge and recovery surface metamask-mobile#34865 (draft, consumes this package).

References

• https://consensyssoftware.atlassian.net/browse/TAT-3766
• Signer reference: https://github.com/elliottech/lighter-go/tree/web-wasm
• Risk context: https://l2beat.com/scaling/projects/lighter

Checklist

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
• I've communicated my changes to consumers by updating changelogs for packages I've changed
• I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them — not applicable: no breaking changes

---

Note

High Risk
Introduces a new trading venue with signer-bridge auth, L2 dispatch recovery, and aggregated routing changes that affect leverage and margin calculations across providers.

Overview
Adds Lighter as an opt-in perps venue ('lighter' on PerpsProviderType), wired like MYX via dynamic LighterProvider import, #isLighterProviderEnabled() (local providerCredentials.lighter.enabled or remote perpsLighterProviderEnabled only when a client signerBridge is mounted), registration, and direct/aggregated routing. Ships lighterConfig.ts and public Lighter constants/types exports; PROVIDER_CONFIG.LIGHTER_TESTNET_ONLY and buildProviderCacheKey treat Lighter network pinning like MYX.

Exposes durable-settlement flows on the controller and aggregated provider: getPendingManualRecoveries, getRecoveredDispatches, and acknowledgeRecoveredDispatch, with PerpsPendingManualRecovery / PerpsRecoveredDispatch exported for clients (providers without durable state return empty lists or throw on acknowledge).

For multi-venue math, getMaxLeverage gains an optional providerId, and AggregatedPerpsProvider routes calculateLiquidationPrice, calculateMaintenanceMargin, and getMaxLeverage to the owning provider instead of always using the default.

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

[geositta]

Thank you for the extensive failure-injection coverage and the work to make ambiguous financial dispatches fail closed. I am requesting changes because two remaining boundary defects can present incorrect venue state or allow malformed venue data into signing and trading paths.

Required before merge:

• Enforce Lighter order-book begin_nonce/nonce continuity and obtain a fresh snapshot after a gap. Without this, a dropped delta leaves pro traders looking at a silently corrupted depth book, spread, and mid-price.
• Decode REST responses from unknown with endpoint-specific runtime validators before assigning TypeScript response types. The current generic assertion makes untrusted JSON appear valid and permits missing or malformed nonce, account, market, and transaction fields to reach financial logic.
• Stop accepting private keys through command-line arguments in the e2e driver; process arguments and shell history expose them.

I also left a non-blocking design comment on the 8,149-line provider. Its signer, persistence, recovery, REST, WebSocket, validation, and trading state machines should be separated behind explicit typed interfaces so future venue changes can be reviewed and tested in isolation.

yarn workspace @metamask/perps-controller run test passes locally. Current CI checks are green. This PR does not change React or React Native components, so there are no component-level React findings. All findings are in files introduced by this branch relative to origin/main.

[geositta]

Follow-up review identified additional correctness blockers after the initial submission. The highest-risk items are the Lighter mainnet deposit transaction construction, transaction-status decoding, and automatic venue-key replacement after a failed key lookup. These need resolution before the earlier change request can be cleared. The comments below are limited to behavior introduced by this branch and verified against the current Lighter documentation.

[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 a95b9b5. Configure here.}

[cursor]

Unknown order status empties orders

Medium Severity

Unknown venue order statuses now throw a data-integrity error, but getOpenOrders and getOrders still swallow that into [], and the orders stream clears #wsOrders before adapting. One unrecognized status can hide every open order or emit a partial book after the dropped frame.

Additional Locations (2)

• packages/perps-controller/src/providers/LighterProvider.ts#L4736-L4751
• packages/perps-controller/src/providers/LighterProvider.ts#L7613-L7635

 

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