feat(ramps): add VBA onboarding stage hydration by georgeweiler · Pull Request #10278 · MetaMask/core

georgeweiler · 2026-09-17T01:41:03Z

Summary

add a persisted seven-stage vbaOnboardingStage contract for Mobile routing
hydrateVbaOnboarding refreshes KYC state from the customer's account via KycController:refreshVbaOnboardingStatus before reading the stage gates, then maps Iron/SumSub getters (KycVendor / KycProvider / KycStatus from feat(kyc-controller): add VBA onboarding KYC getters #10279) to a routable stage
the refresh action is delegated via a local structural messenger-action type, so this package compiles without a kyc-controller release that already exports it (KYC PR merges first)
load authoritative autoramp accounts through the new NeoBankService:getAutoramps action before deciding whether account creation is needed
automatically register the Money Account wallet and create an autoramp after KYC acceptance
coalesce overlapping hydration polls to avoid duplicate signatures and account creation

This is a simplified replacement for #10116. KYC flow interpretation stays in KycController; this PR imports the shared enums/action types from @metamask/kyc-controller rather than declaring them locally.

Depends on: #10279 (KYC getters + VBA status refresh). Until that lands, this branch is expected not to typecheck against main's kyc-controller package — that is intentional.

The proxy is expected to support authenticated GET /neobank/autoramps requests.

Testing

yarn jest src/NeoBankService.test.ts src/RampsController.test.ts --runInBand --no-coverage
yarn workspace @metamask/ramps-controller run test
yarn build (may fail until feat(kyc-controller): add VBA onboarding KYC getters #10279 merges)
yarn workspace @metamask/ramps-controller run messenger-action-types:check
targeted ESLint for changed files
yarn changelog:validate

🤖 Generated with Claude Code

Note

Medium Risk
Touches KYC-gated money-account activation (wallet signing and autoramp creation) and expands the required messenger surface, so host wiring mistakes or race bugs could affect onboarding.

Overview
Adds Mobile VBA onboarding routing via a persisted vbaOnboardingStage and RampsController:hydrateVbaOnboarding, which derives the next screen from Iron/SumSub KYC session state (email OTP, vendor/provider terms, SumSub, pending/rejected, or completed).

After KYC is approved, hydration registers the Money Account wallet, loads the customer’s autoramps through new NeoBankService:getAutoramps (GET /neobank/autoramps), syncs local autoramp state, and creates an autoramp only when none is usable for the wallet; transient neobank failures keep the user on KycPending instead of completing. Overlapping hydration calls are coalesced to avoid duplicate signatures or autoramp creation during polling.

Breaking: integrators must wire four new KycController messenger actions (getSessionStatusForVendor, refreshSessionStatus, and the two disclaimer checks). Action types are declared structurally in ramps-controller so it does not add a @metamask/kyc-controller dependency.

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

Co-authored-by: Cursor <cursoragent@cursor.com>

cursor

Stale Bugbot comment from a previous run.

Co-authored-by: Cursor <cursoragent@cursor.com>

cursor

Stale Bugbot comment from a previous run.

Drop local KycVendor/KycProvider/KycStatus stubs and action types in favor of the package exports introduced in #10279. Co-authored-by: Cursor <cursoragent@cursor.com>

…t on hydrate Before reading the VBA stage gates, hydrateVbaOnboarding now calls KycController:refreshVbaOnboardingStatus so each stage reflects the vendor account (vendor-terms re-signing, KYC status) rather than only device-local state. The action is declared as a local structural messenger-action type so the ramps package does not require a kyc-controller release that already exports it (the KYC PR merges first). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

… 0.4.0 session API

…not finalStatus finalStatus is already 'pending' once the session + consents exist (pre-SumSub), so route to KycRequired until vendorStatus/kycStatus leaves 'new'/'retry'; only show KycPending once the applicant has actually submitted. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

cursor

Stale Bugbot comment from a previous run.

georgeweiler · 2026-09-21T16:23:10Z

@metamaskbot release previews

…, registration) - Read session status from refreshSessionStatus (in-memory) so the SumSub outcome is seen immediately; the backend latest-status endpoint lags. - Gate KycRequired on kycStatus 'new'/'retry'; KycPending once submitted. - Treat a 404 'no session' from getSessionStatusForVendor as start-at-email. - Money-account registration failure after approval keeps the user on 'verification in progress' (retryable) instead of the error screen. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

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 0c50d9f. Configure here.}

…esh changelog + lockfile Declare the KYC messenger action types and KycVendor structurally in the ramps package instead of importing from @metamask/kyc-controller, dropping the dependency (which was pinned to ^0.3.0 while the monorepo moved to 0.4.0 and broke the immutable-lockfile check). Update the changelog to the session-status based hydration API. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…p removal Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…tus API Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

## Explanation Cut `@metamask/ramps-controller@24.0.0` so Mobile can consume VBA onboarding hydration from MetaMask#10278, plus a required patch of `@metamask/transaction-pay-controller@29.0.1` because it is a workspace dependent of that major bump. Ramps is a **major** because hosts must wire four new `KycController` messenger actions on `RampsControllerMessenger`. ## References - Core feature: MetaMask#10278 - Mobile consumer (draft): MetaMask/metamask-mobile#36522 ## Checklist - [x] I've updated the test suite for new or updated code as appropriate - [x] I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate - [x] I've communicated my changes to consumers by [updating changelogs for packages I've changed](https://github.com/MetaMask/core/tree/main/docs/processes/updating-changelogs.md) - [x] I've introduced [breaking changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md) in this PR and have prepared draft pull requests for clients and consumer packages to resolve them ## Test plan - [ ] Changelog for `@metamask/ramps-controller` 24.0.0 looks correct (no Uncategorized) - [ ] Changelog for `@metamask/transaction-pay-controller` 29.0.1 looks correct (no Uncategorized) - [ ] Published packages: ramps-controller `23.0.0` → `24.0.0`, transaction-pay-controller `29.0.0` → `29.0.1` - [ ] After merge, confirm GitHub release tags and npm publish of both packages  --- > [!NOTE] > **Medium Risk** > The major ramps release forces client messenger wiring for KYC hydration; this PR only cuts versions but downstream apps must upgrade integrations before adopting 24.0.0. > > **Overview** > Release **1268.0.0** publishes **`@metamask/ramps-controller@24.0.0`**, packaging the VBA onboarding and NeoBank autoramp work from MetaMask#10278 that was previously under `[Unreleased]`. The changelog section is finalized (including a minor formatting fix on an older breaking-change bullet), and compare links are updated for the new tag. > > The ramps bump is a **major** because consumers must delegate four **`KycController`** messenger actions on **`RampsControllerMessenger`** for VBA onboarding hydration (along with the other 24.0.0 API additions already documented there). > > **`@metamask/transaction-pay-controller`** is patched to **`29.0.1`** so its dependency moves from **`@metamask/ramps-controller@^23.0.0`** to **`^24.0.0`**, with matching **`package.json`**, changelog, and **`yarn.lock`** updates. No application logic changes appear in this diff—only versioning and release metadata. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 20f97cc. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>  --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Amitabh Aggarwal <aggarwal.amitabh@gmail.com> Co-authored-by: Cursor <cursoragent@cursor.com>

…en stage (MetaMask#10354) ## Explanation `RampsController:hydrateVbaOnboarding` currently returns a linear `VbaOnboardingStage` and persists it. That encodes product funnel order in Core, so a design change such as putting vendor terms before email requires a controller release. This PR keeps Core responsible for backend onboarding facts and money-account activation while removing screen and route concepts: - `hydrateVbaOnboarding` returns a `VbaOnboardingSnapshot` containing `sessionExists`, disclaimer completion flags, `kycStatus`, `finalStatus`, and `activation`. - The persisted `vbaOnboardingStage` state field and `VbaOnboardingStage` enum are removed. - After `finalStatus === 'approved'`, wallet registration and autoramp creation still run as a coalesced operation. - Activation failures return `activation: 'retryable_failure'` instead of turning hydration into a fatal error. - A persisted KYC session owned by a previous identity is cleared and represented as an empty snapshot. Mobile owns the funnel in MetaMask/metamask-mobile#36522. Its current sequence is MoonPay Terms 1 → Iron email → session Terms 2 → SumSub. Entry and resume points hydrate this snapshot, while successful local actions advance optimistically. ## References - Replaces the stage contract introduced by MetaMask#10278 - Mobile consumer: MetaMask/metamask-mobile#36522 - Overlaps the foreign-session discard in MetaMask#10337; that PR will need to rebase onto this snapshot return type if both land ## Testing - Updated `RampsController` unit coverage for every snapshot branch, including empty, pending, approved, rejected, retryable activation failure, and foreign-session reset states. - Verified the locally built package in MetaMask Mobile through a dist overlay; Mobile resolves `hydrateVbaOnboarding` as `Promise<VbaOnboardingSnapshot>` with no remaining stage API references. ## Checklist - [x] I've updated the test suite for new or updated code as appropriate - [x] I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate - [x] I've communicated my changes to consumers by [updating changelogs for packages I've changed](https://github.com/MetaMask/core/tree/main/docs/processes/updating-changelogs.md) - [x] I've introduced [breaking changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md) in this PR and have prepared draft pull requests for clients and consumer packages to resolve them Made with [Cursor](https://cursor.com) --------- Co-authored-by: Cursor <cursoragent@cursor.com>

feat: add VBA onboarding hydration

179f7c8

Co-authored-by: Cursor <cursoragent@cursor.com>

georgeweiler requested a review from a team as a code owner September 17, 2026 01:41

georgeweiler temporarily deployed to default-branch September 17, 2026 01:41 — with GitHub Actions Inactive

docs: document VBA onboarding hydration

f028185

Co-authored-by: Cursor <cursoragent@cursor.com>

georgeweiler requested a review from a team as a code owner September 17, 2026 01:42

cursor Bot reviewed Sep 17, 2026

View reviewed changes

Comment thread packages/ramps-controller/src/RampsController.ts Resolved

Comment thread packages/ramps-controller/src/RampsController.ts Resolved

feat: load autoramps during VBA hydration

ca442a3

Co-authored-by: Cursor <cursoragent@cursor.com>

cursor Bot reviewed Sep 17, 2026

View reviewed changes

Comment thread packages/ramps-controller/src/RampsController.ts Resolved

georgeweiler mentioned this pull request Sep 17, 2026

feat(kyc-controller): add VBA onboarding KYC getters #10279

Closed

georgeweiler and others added 2 commits September 16, 2026 20:20

refactor(ramps-controller): import VBA KYC contracts from kyc-controller

94c5395

Drop local KycVendor/KycProvider/KycStatus stubs and action types in favor of the package exports introduced in #10279. Co-authored-by: Cursor <cursoragent@cursor.com>

georgeweiler mentioned this pull request Sep 17, 2026

feat(ramps): route VBA entrypoints and KYC continuations by stage MetaMask/metamask-mobile#36391

Closed

8 of 10 tasks

refactor(ramps-controller): hydrate VBA onboarding via kyc-controller…

117861f

… 0.4.0 session API

georgeweiler mentioned this pull request Sep 19, 2026

feat(ramps/vba): move onboarding funnel routing to Mobile MetaMask/metamask-mobile#36522

Closed

8 of 10 tasks

cursor Bot reviewed Sep 19, 2026

View reviewed changes

Comment thread packages/ramps-controller/src/RampsController.ts Resolved

cursor Bot reviewed Sep 21, 2026

View reviewed changes

Comment thread packages/ramps-controller/src/RampsController.ts Resolved

georgeweiler and others added 4 commits September 21, 2026 10:43

chore(ramps-controller): fix jsdoc lint on local KycVendor type

44a2a0d

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

chore(ramps-controller): prettier format + regenerate README after de…

b84dac1

…p removal Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(ramps-controller): update VBA hydration tests to the session-sta…

6e0eb4b

…tus API Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

georgeweiler changed the title ~~Add VBA onboarding stage hydration~~ feat(ramps): add VBA onboarding stage hydration Sep 21, 2026

georgeweiler enabled auto-merge September 21, 2026 17:02

roz0n approved these changes Sep 21, 2026

View reviewed changes

georgeweiler added this pull request to the merge queue Sep 21, 2026

Merged via the queue into main with commit 9e3e44a Sep 21, 2026
45 checks passed

georgeweiler deleted the vba-onboarding-stage branch September 21, 2026 17:39

roz0n mentioned this pull request Sep 21, 2026

Release/1268.0.0 #10326

Merged

4 of 8 tasks

georgeweiler mentioned this pull request Sep 22, 2026

feat(ramps-controller): return VBA onboarding facts instead of a screen stage #10354

Merged

4 tasks done

Navigation Menu

Repository navigation

feat(ramps): add VBA onboarding stage hydration - #10278

feat(ramps): add VBA onboarding stage hydration#10278
georgeweiler merged 12 commits into
mainfrom
vba-onboarding-stage

georgeweiler commented Sep 17, 2026 •

edited by cursor Bot

Loading

Uh oh!

cursor Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

cursor Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

georgeweiler commented Sep 21, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

georgeweiler commented Sep 17, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Testing

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

georgeweiler commented Sep 21, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

georgeweiler commented Sep 17, 2026 •

edited by cursor Bot

Loading

cursor Bot left a comment •

edited

Loading

cursor Bot left a comment •

edited

Loading

cursor Bot left a comment •

edited

Loading