Skip to content

feat(kyc): adopt per-vendor KYC sessions - #38814

Draft
georgeweiler wants to merge 5 commits into
mainfrom
gw/kyc-per-vendor-sessions
Draft

georgeweiler wants to merge 5 commits into
mainfrom
gw/kyc-per-vendor-sessions

Conversation

@georgeweiler

@georgeweiler georgeweiler commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Description

Adopts per-vendor KYC sessions from MetaMask/core#11399. KycController used to hold one session for everything. It now holds sessions, keyed by vendor, so a second feature (e.g. Kalshi in Predict) can hold its own session next to VBA's Iron one.

  • Migration 161 moves the flat KycController state into sessions[vendor]. It keeps providerFlowStatus, which is the only record that a user already submitted SumSub and is waiting. Migrated Iron terms are marked submitted, because they were only ever written after Iron recorded them. email, vendor and geoCountry are dropped.
  • Selectors take a vendor. VBA passes iron.
  • Vendor terms acceptance is stored on the KYC controller (acceptVendorDisclaimers) instead of VBA's wallet-keyed storage. The email step submits it with recordVendorDisclaimers({ vendor }). vbaVendorTermsStorage is deleted. A user who accepted Iron's terms but never started a session sees the terms once more.
  • Other call sites now pass the vendor: the SumSub launch, status redirect, home card, microdeposits and analytics readers.
Screenshot 2026-11-10 at 11 18 30 AM

Changelog

CHANGELOG entry: null

Related issues

Refs: MetaMask/core#11399

Manual testing steps

Run against locally built core packages copied over node_modules/@metamask/{kyc,ramps}-controller, since the new versions aren't published.

Feature: per-vendor KYC sessions

  Scenario: existing wallet upgrades
    Given a wallet with KycController state from before this change
    When the app starts
    Then persisted state is at version 161
    And KycController state is { sessions: { iron: … } } with providerFlowStatus kept

  Scenario: user accepts VBA vendor terms before a session exists
    Given a wallet with no KYC session
    When user opens VBA onboarding and agrees to the vendor terms
    Then sessions.iron.vendorDisclaimersAccepted is stored with submitted: false
    And onboarding continues to the email step

Verified locally on the iOS simulator: Engine loads, migration 161 runs, VBA hydrate reads the new state, and accepted terms land on sessions.iron and carry the flow to the email step.

Screenshots/Recordings

N/A — no UI change.

Before

N/A

After

N/A

Pre-merge author checklist

Pre-merge reviewer checklist

  • I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
  • I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.

🤖 Generated with Claude Code

Description

Adopts per-vendor KYC sessions from MetaMask/core#11399. KycController used to hold one session for everything. It now holds sessions, keyed by vendor, so a second feature (e.g. Kalshi in Predict) can hold its own session next to VBA's Iron one.

  • Migration 162 moves the flat KycController state into sessions[vendor]. It keeps providerFlowStatus, which is the only record that a user already submitted SumSub and is waiting. Migrated Iron terms are marked submitted, because they were only ever written after Iron recorded them. email, vendor and geoCountry are dropped.
  • Selectors take a vendor. VBA passes iron.
  • Vendor terms acceptance is stored on the KYC controller (acceptVendorDisclaimers) instead of VBA's wallet-keyed storage. The email step submits it with recordVendorDisclaimers({ vendor }). vbaVendorTermsStorage is deleted. A user who accepted Iron's terms but never started a session sees the terms once more.
  • Other call sites now pass the vendor: the SumSub launch, status redirect, home card, microdeposits and analytics readers.
  • vbaKycSession (from main) is deleted. startSession no longer throws on a country mismatch, so the reset-and-retry helper has nothing to catch. The SumSub launch and the terms catalog read the residence country from sessions.iron.
  • Requires @metamask/kyc-controller ^0.17.0 and @metamask/ramps-controller ^30.0.0, so CI stays red until core releases them. Bumping ramps to 30 also brings the BaseDataService migrations for RampsService, NeoBankService and TransakService (core#11214, core#11216, core#10882). Their service messengers here will need an update when that release lands.
Screenshot 2026-11-10 at 11 18 30 AM

Changelog

CHANGELOG entry: null

Related issues

Refs: MetaMask/core#11399

Manual testing steps

Run against locally built core packages copied over node_modules/@metamask/{kyc,ramps}-controller, since the new versions aren't published.

Feature: per-vendor KYC sessions

  Scenario: existing wallet upgrades
    Given a wallet with KycController state from before this change
    When the app starts
    Then persisted state is at version 162
    And KycController state is { sessions: { iron: … } } with providerFlowStatus kept

  Scenario: user accepts VBA vendor terms before a session exists
    Given a wallet with no KYC session
    When user opens VBA onboarding and agrees to the vendor terms
    Then sessions.iron.vendorDisclaimersAccepted is stored with submitted: false
    And onboarding continues to the email step

Verified locally on the iOS simulator before the rebase onto main (the migration was numbered 161 then): Engine loads, the migration runs, VBA hydrate reads the new state, and accepted terms land on sessions.iron and carry the flow to the email step.

Screenshots/Recordings

N/A — no UI change.

Before

N/A

After

N/A

Pre-merge author checklist

Pre-merge reviewer checklist

  • I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
  • I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.

🤖 Generated with Claude Code

Open in Web Open in Cursor 

@github-actions

github-actions Bot commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes.

@metamask-ci

metamask-ci Bot commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

PR template — items to address before "Ready for review"

Warnings — informational, address before merging:

  • Pre-merge author checklist has only 5 of the required 8 items. Every checklist row must be present and consciously checked — do not delete rows.

See docs/readme/ready-for-review.md for the full Definition of Ready for Review.

@github-actions

github-actions Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Smart E2E Test Selection

Selected E2E tags: ALL

AI Confidence: 100

E2E reasoning

Expand to read

I kept the hard-rule seed (ALL). The PR bumps @metamask/kyc-controller (0.16 to 0.17) and @metamask/ramps-controller (29 to 30, a major version). It adds persisted-state migration 162, registered in migrations/index.ts, which restructures KycController state into a sessions map. It changes the Engine KYC messenger by removing the delegated action KycService:createMoonpaySession. It also rewrites the KycController section of the shared default-fixture.json, which is used by all fixture-based E2E specs, so the new state shape affects every spec. The rest is KYC and Virtual Bank Account UI hooks, selectors and tests, which mainly affect Money/Ramps flows. Because the migration runs at startup, the controller state shape changed, and the shared fixture was modified, the blast radius is wide, so I'm running all smoke tags.

View run

georgeweiler and others added 5 commits November 10, 2026 18:18
Adopts @metamask/kyc-controller with one session per vendor and the
matching @metamask/ramps-controller.

- Migration 161 moves the flat KycController state into sessions[vendor],
  keeping providerFlowStatus and marking migrated Iron terms as submitted
- KYC selectors take a vendor; VBA passes iron
- Vendor terms acceptance is stored on the KYC controller
  (acceptVendorDisclaimers) instead of VBA's wallet-keyed storage, and the
  email step submits it with recordVendorDisclaimers({ vendor })
- Remove vbaVendorTermsStorage

CI will fail until the new core versions are released; the lockfile is not
updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Update unit tests and Engine fixtures for the per-vendor KycController
state, and the terms flow that now stores acceptance on the controller.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…gation

MetaMask/core#11399 removes KycService:createMoonpaySession, so the KYC
controller messenger must no longer delegate it.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The component-view Engine mock now keeps per-vendor session entries and
stores accepted vendor terms like the real controller, and the
KycPending view test seeds sessions.iron.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Drop vbaKycSession (startSession no longer throws on a geoCountry
mismatch), read the residence country from the Iron session entry,
renumber the KYC migration to 162 and require kyc-controller ^0.17.0 and
ramps-controller ^30.0.0.

Co-authored-by: george.weiler <george.weiler@consensys.net>
@cursor
cursor Bot force-pushed the gw/kyc-per-vendor-sessions branch from a559e5b to 66a629e Compare November 10, 2026 18:54

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size-XL team-money-movement issues related to Money Movement features

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants