Skip to content

Gw/kyc generalized demo - #11277

Closed
georgeweiler wants to merge 3 commits into
mainfrom
gw/kyc-generalized-demo
Closed

georgeweiler wants to merge 3 commits into
mainfrom
gw/kyc-generalized-demo

Conversation

@georgeweiler

@georgeweiler georgeweiler commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Explanation

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

Note

High Risk
Large breaking API and persisted-state shape changes in identity/KYC orchestration, with downstream ramps integration; clients must migrate stored state and every KycController call site.

Overview
BREAKING: @metamask/kyc-controller replaces the single active session with a persisted sessions map keyed by identity vendor. Top-level email, vendor, and geoCountry are removed; each entry holds that vendor's sessionStatus, disclaimer acceptance, provider flow state, and residenceCountry. Session APIs now take { vendor }, startSession no longer rejects vendor/email/country mismatches, and vendor is required on KycService.fetchVendorDisclaimers / createUkycSession (no default moonpay).

New flows split vendor T&Cs into acceptVendorDisclaimers (local, pre-session, submitted: false) and recordVendorDisclaimers (POST stored acceptance once a session exists). getSessionDecision({ vendor }) (plus exported getKycSessionDecision) collapses session + provider flow into none | new | pending | approved | rejected | retry. Selectors become selectKycSession(state, vendor) and selectKycSessionStatus(state, vendor); KycPhase, KycProduct, and related legacy types are dropped. launchProviderFlow only allows one SumSub UI at a time; per-vendor status polling and clearState/reset clear all vendors.

@metamask/ramps-controller adopts the new messenger contract for Iron VBA onboarding: KYC calls pass { vendor: 'iron' }, KycController:getSessionDecision is required, and hydrateVbaOnboarding uses that action instead of local resolveVbaKycStatus.

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

georgeweiler and others added 3 commits November 3, 2026 15:56
Replace the single-session KycController state with `sessions`, keyed by
vendor, so a second vendor (e.g. Kalshi) can hold its own session next to
Iron. Every session method takes `{ vendor }`; there is no active vendor.

- Add getSessionDecision (none/new/pending/approved/rejected/retry), moved
  from RampsController's resolveVbaKycStatus
- Add acceptVendorDisclaimers so vendor terms accepted before a session
  exists are stored on the controller, then submitted by
  recordVendorDisclaimers({ vendor })
- Drop the stored email/vendor/geoCountry and their 'different X' guards;
  email is only required when creating a session
- One SumSub flow on screen at a time; per-vendor polling loops
- Make vendor required on KycService.fetchVendorDisclaimers and
  createUkycSession
- Remove dead KycPhase / KycProduct types
- RampsController passes vendor 'iron' and reads getSessionDecision

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

Also require a session id in the controller's session lookup, stop
recordVendorDisclaimers recreating an entry cleared mid-request, and update
ARCHITECTURE.md's state and selectors sections.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@georgeweiler
georgeweiler requested review from a team as code owners November 4, 2026 02:51

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

Fix All in Cursor

❌ 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 7cf90a1. Configure here.

session = await this.messenger.call(
'KycController:fetchSessionStatusOnce',
session.id,
vendorParams,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

KYC reset wipes every vendor

Medium Severity

VBA hydration still calls KycController:clearState when the Iron session is from another profile or the status GET returns 404. That action now deletes every vendor entry and stops every poll loop, so a valid MoonPay session, its accepted terms, and in-flight polling are discarded even though only the Iron session is invalid.

Additional Locations (1)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 7cf90a1. Configure here.

weitingsun pushed a commit to Poovarasan-Sandhanam/metamask-mobile that referenced this pull request Nov 10, 2026
…etaMask#39271)

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
## **Description**

<!-- mms-check: type=text required=true -->

KYC still borrowed its analytics names, screen-trace tags, logger
feature, and MetaMask and SumSub legal URLs from the virtual bank
account flow. This is the first step in giving KYC its own module: those
values now live with KYC, and the screens that used them no longer
import the bank-account flow.

- MetaMask and SumSub URLs move to `app/components/UI/KYC/constants.ts`.
- `app/components/UI/KYC/vendors/iron.ts` holds Iron's current analytics
names (`vba_onboarding`, `add_funds_bank_account`, `moonpay`, `sumsub`),
trace flow (`vba`), and logger feature (`vba-kyc`).
- `trackKycEvent` sends KYC events. Identity terms, result viewed,
verification updated, and status updated all use it. Successful event
properties are unchanged.
- Screen-performance config and the SumSub launch error log read the
Iron definition.
- The Engine analytics handler still forwards controller events through
`buildKycBaseProperties`, which now reads that definition.

Iron's screen traces still call the bank-account flow's shared lifecycle
helper, so a KYC screen opened inside that journey reports the same
`lifecycle_context`. That import lives only in the vendor file.

One error-path change: identity-terms and result-viewed failures used to
log as `vba-onboarding`, because they went through `trackVbaEvent`. They
now log as `vba-kyc`, the same tag as the other KYC trackers. The events
themselves are unchanged when tracking succeeds.

## Test layer placement

<!-- mms-check: type=text required=false -->

Unit tests. The change is a move of constants and a shared tracker.
`trackKycEvent.test.ts` locks the properties object that is sent, and
the existing analytics, terms, and screen-performance tests still assert
the same values.

## **Changelog**

<!-- mms-check: type=changelog required=true blocking=true -->

CHANGELOG entry: null

## **Related issues**

<!-- mms-check: type=issue-link required=true -->

Refs: No ticket. First mobile PR in the VBA/KYC decoupling stack, ahead
of MetaMask/core#11277.

## **Manual testing steps**

<!-- mms-check: type=manual-testing required=true -->

N/A — no screen, copy, or successful analytics payload changes. Covered
by unit tests.

## **Screenshots/Recordings**

<!-- mms-check: type=screenshot required=true -->

N/A — no user-visible change.

### **Before**

### **After**

## **Pre-merge author checklist**

<!-- mms-check: type=checklist required=true -->

- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile
Coding
Standards](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/CODING_GUIDELINES.md).
- [x] I've completed the PR template to the best of my ability
- [x] I've included tests if applicable
- [x] I've documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [x] I've applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

#### Performance checks (if applicable)

- [x] I've tested on Android
  - Ideally on a mid-range device; emulator is acceptable
- [x] I've tested with a power user scenario
- Use these [power-user
SRPs](https://consensyssoftware.atlassian.net/wiki/spaces/TL1/pages/edit-v2/401401446401?draftShareId=9d77e1e1-4bdc-4be1-9ebb-ccd916988d93)
to import wallets with many accounts and tokens
- [x] I've instrumented key operations with Sentry traces for production
performance metrics
- See [`trace()`](/app/util/trace.ts) for usage and
[`addToken`](/app/components/Views/AddAsset/components/AddCustomToken/AddCustomToken.tsx#L274)
for an example

For performance guidelines and tooling, see the [Performance
Guide](https://consensyssoftware.atlassian.net/wiki/spaces/TL1/pages/400085549067/Performance+Guide+for+Engineers).

## **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.

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a
href="https://cursor.com/agents/bc-8c738e76-8169-5ed9-96da-b58f68b962bb?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/background-agent?bcId=bc-8c738e76-8169-5ed9-96da-b58f68b962bb&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img
alt="Open in Cursor" width="131" height="28"
src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a>&nbsp;</div>

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Refactor with no user-visible or successful analytics payload changes;
only import paths, shared tracking helper, and error-log feature tags
differ.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
74d8a8d. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

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

This branch was previously deployed

1 inactive deployment
default-branch — 7cf90a17 Deployed Nov 4, 2026 by georgeweiler via Determine whether this PR is a release PR #6446
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