Skip to content

fix: check withdrawal account support per venue - #11676

Open
geositta wants to merge 4 commits into
mainfrom
TAT-3752-withdrawal-route-core
Open

geositta wants to merge 4 commits into
mainfrom
TAT-3752-withdrawal-route-core

Conversation

@geositta

@geositta geositta commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Explanation

Clients need to know which venue a withdrawal will use before checking account support. Inferring that venue in Mobile duplicates Core's routing policy: it can ignore a saved default provider or assume Hyperliquid when Core would refuse an ambiguous multi-venue withdrawal. Neither no-argument getAccountSupport() nor the first entry from getWithdrawalRoutes() answers which venue withdraw will sign on.

This adds PerpsController.resolveWithdrawalRoute(params?), its messenger action, and the exported ResolveWithdrawalRouteParams and WithdrawalRoute types:

  • Returns { status: 'resolved', providerId } for a direct provider, an explicit registered aggregated route, or the sole registered aggregated venue, including Lighter.
  • Returns { status: 'route_required', error: 'PROVIDER_ROUTE_REQUIRED' } when multiple aggregated venues are registered and no route is supplied. This refusal is a value rather than a thrown error because the client's account-support error handler can fail open.
  • Checks for an ambiguous route both before and after provider readiness, including cold-start migration from direct to aggregated mode.
  • Throws PROVIDER_NOT_FOUND for an unknown explicit aggregated route or a route that conflicts with the active direct provider. withdraw now rejects direct-provider conflicts before withdrawal tracking or signing begins.

No-argument getAccountSupport() continues to check the aggregated routing default, even when an unrouted withdrawal would be refused. Withdrawal-record venue stamping is unchanged. Unknown aggregated routes retain the existing withdrawal error handling: the query throws, while AccountService returns a failed withdrawal result.

Consumers should resolve the route, stop on route_required, then check getAccountSupport({ providerId }) and pass that same venue to withdraw. Preflight results must be discarded when the account, network, or provider context changes.

Compatibility for other consumers: Extension and Terminal need no adoption for this change — the method, action and types are purely additive and no existing messenger surface changes behavior for valid input, so both clients keep working unchanged; they can adopt resolveWithdrawalRoute later for the same routing-policy parity as Mobile.

Mobile adoption, pending-check retirement on provider switches, and venue-specific quote/validation changes remain separate client work; this PR does not change Mobile or publish the package.

The implementation is ported from 473ae0148c0 onto perps-controller 25.0.0, based on 2d56e38b3e5958d7129a7b8b4a3b02fe6c0014ac. All functional source hunks remain necessary. The README insertion preserves the newer batch-routing documentation, and the aggregated-route tests now exercise withdrawal behavior against the same fixtures as the query.

Validation

  • Requested operations, default-provider, and public-API suites: 347 passed.
  • Full package coverage run: 8,455 passed, 40 skipped; coverage thresholds passed.
  • Changed-file Oxlint and formatting checks, messenger-action generation check, and package changelog validation passed.
  • yarn lint:tsc:check passed with existing suppressions unchanged.

References

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: the query is additive; the withdrawal change rejects an invalid direct-provider route rather than silently executing on another venue. No consumer migration is included.

Note

Medium Risk
Changes withdrawal routing validation on a funds-moving path, though behavior is mostly additive preflight API plus earlier rejection of invalid provider routes.

Overview
Adds resolveWithdrawalRoute (plus messenger action and WithdrawalRoute / ResolveWithdrawalRouteParams types) so clients can see which venue withdraw would sign on using the same aggregated routing rules. A resolved providerId is returned when the route is unambiguous; when multiple venues are registered and no route is given, callers get { status: 'route_required', error: 'PROVIDER_ROUTE_REQUIRED' } as a value instead of an exception, avoiding fail-open handling in account-support UIs. Unknown explicit routes or routes that conflict with the active direct provider still throw PROVIDER_NOT_FOUND, aligned with getAccountSupport.

withdraw now applies that same direct-provider conflict check before delegation to AccountService, so invalid providerId values fail before tracking or signing. Docs and changelog describe using resolve → getAccountSupport({ providerId }) → withdraw rather than inferring the venue from getAccountSupport() or getWithdrawalRoutes().

Reviewed by Cursor Bugbot for commit 6e7a6ff. Bugbot is set up for automated code reviews on this repo. Configure here.

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

🛑 Files requiring codeowner review

To merge this PR, you'll need to get approvals from the following owners.

@MetaMask/perps (11 files)
  • packages/perps-controller/CHANGELOG.md
  • packages/perps-controller/docs/architecture.md
  • packages/perps-controller/README.md
  • packages/perps-controller/src/index.ts
  • packages/perps-controller/src/PerpsController-method-action-types.ts
  • packages/perps-controller/src/PerpsController.ts
  • packages/perps-controller/src/types/index.ts
  • packages/perps-controller/tests/public-api-types.ts
  • packages/perps-controller/tests/public-api.test.ts
  • packages/perps-controller/tests/src/PerpsController.default-provider.test.ts
  • packages/perps-controller/tests/src/PerpsController.operations.test.ts

ℹ️ Files co-owned by @MetaMask/core-platform (expand for more)

[!NOTE]
For convenience in maintaining this repo, @MetaMask/core-platform co-owns
the following files. It is not required to seek approval from
@MetaMask/core-platform to change these files. This section is purely
informational.

  • packages/perps-controller/CHANGELOG.md

@geositta geositta changed the title fix: add resolveWithdrawalRoute, its public types, messenger action, … fix: check withdrawal account support per venue Nov 20, 2026
@geositta
geositta marked this pull request as ready for review November 20, 2026 02:22
@geositta
geositta requested review from a team as code owners November 20, 2026 02:22
@geositta
geositta deployed to default-branch November 20, 2026 02:22 — with GitHub Actions Active
@geositta
geositta force-pushed the TAT-3752-withdrawal-route-core branch from 99be726 to 6e7a6ff Compare November 20, 2026 04:11
@geositta
geositta enabled auto-merge November 20, 2026 04:26

This branch was successfully deployed

1 active (outdated) deployment
default-branch — 6798ae7e Deployed Nov 20, 2026 by geositta via Determine whether this PR is a release PR #7412
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant