feat(kyc-controller): Iron Money KYC path + status polling by amitabh94 · Pull Request #9852 · MetaMask/core

amitabh94 · 2026-08-12T21:18:01Z

Summary

Adds vendor: 'iron' KYC flow for MetaMask Money: idle → terms → session → submit(SumSub) → done/error with no MoonPay Check/Auth frames.
Extends KycService with Milestone 1 contract clients (mocked in tests): POST /vendors/iron/customers, GET /vendors/iron/disclaimers, POST /vendors/iron/kyc-required, POST /consents, GET /kyc/status, plus createUkycSession({ vendorId: 'iron' }) without MoonPay metadata.
Adds createIronCustomer, refreshKycStatus, KycController:statusChanged, persisted userStatus* fields, and maps session_not_in_valid_state → completed.

Stacking

Base: feat/kyc-controller (feat: KYC controller #9615)
Depends on Milestone 1 API endpoints landing on va-mmcx-kyc-api (not merged yet). Clients are implemented against the planned contract; tests mock fetch.

Deferred (follow-ups)

Full 3-state error UX wiring beyond status fields (need-more-information / terminal-failure / retryable SumSub session id)
Mobile Money navigator + toast rendering (Milestone 3)
Live integration once Milestone 1 is on shared-dev

Test plan

yarn workspace @metamask/kyc-controller run test (100% coverage)
yarn workspace @metamask/kyc-controller run messenger-action-types:check
Smoke against local/dev KYC API once Iron routes + /consents + /kyc/status exist

Made with Cursor

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

…b flow opening Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

… been reset Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

Introduce vendor:'iron' flow (no MoonPay Check/Auth frames) with KycService clients for Iron customers/disclaimers/consents and user-keyed GET /kyc/status, so Money can drive toast state against the planned Milestone 1 API contract.

Add PR link and formatting for changelog, fix JSDoc/restricted-syntax/jest matcher lint errors, and apply Prettier to the package. Co-authored-by: Cursor <cursoragent@cursor.com>

Use oxfmt (not Prettier) so import order and markdown alignment match the monorepo misc formatter. Co-authored-by: Cursor <cursoragent@cursor.com>

amitabh94 · 2026-08-12T22:17:31Z

Demo topology update (for reviewers): Iron feature commit a40fa2fc3f is already on neobank-demo (merged by @georgeweiler into the demo integration branch; umbrella #9853). Remaining CI lint/oxfmt fixes from this PR are synced via #9855 → neobank-demo.

This PR (#9852) should stay targeting feat/kyc-controller for the mainline stack (#9615). Do not retarget to main / neobank-demo.

@georgeweiler

## Summary - `neobank-demo` already includes Sébastien’s `feat/kyc-controller` stack and the Iron feature commit from #9852 (`a40fa2fc3f`, merged by George). - This PR cherry-picks the remaining #9852 CI fixes (`lint` / changelog PR link / `oxfmt`) so the demo branch matches the Iron tip for package publish/preview and mobile consumption. - Keeps #9852 targeting `feat/kyc-controller` for the eventual mainline path via #9615. Does **not** merge to `main`. ## Context (demo topology) - Integration branch: `neobank-demo` (owner: @georgeweiler) — umbrella PR #9853 → `main` - Iron feature PR (mainline stack): #9852 → `feat/kyc-controller` - KYC controller PR: #9615 → `main` ## Test plan - [ ] Confirm diff is formatting/lint/changelog only (no Iron behavior change) - [ ] CI green on this PR - [ ] After merge, `@metamaskbot publish-preview` on #9853 (or this PR) if mobile needs a preview pin of `@metamask/kyc-controller` Made with [Cursor](https://cursor.com) --------- Co-authored-by: Cursor <cursoragent@cursor.com>

jiexi · 2026-08-17T22:31:21Z

      // Ignore; disclaimers loading will surface a country error if needed.
    }

+    // Iron: create the empty-shell customer before T&C (offsite decision).


what is the reasoning for the KycController to explicitly handle this bit of the vendor onboarding lifecycle?

We need to be able to create a customer before signing the T&C.
Where do you think this logic is best placed?

Sorry, I meant more that it is odd for the KycController to have to concern itself with specifics of Iron onboarding, in this case creation of a customer with the user's email. Previously this was combined with the Moonpay flow under the notion of a "session". I agree that this step still must happen before Iron signings can be submitted, but i think we should abstract this into the same idea of a "session", hiding the fact that that really just means a customer must be created/exist to the KycController itself

jiexi · 2026-08-17T22:38:03Z

+        sumsubTncSigned: params?.sumsubTncSigned ?? true,
+        idosTncSigned: params?.idosTncSigned ?? true,


defaulting to true seems to make it more possible that the disclaimers are not actually shown to the user

Yes that sounds correct. Should we default it to false then ?

jiexi · 2026-08-17T22:50:21Z

+          vendorId: isIron ? 'iron' : 'moonpay',
+          ...(isIron
+            ? {}
+            : {
+                vendorMetadata: {
+                  moonPayAccessToken: this.state.accessToken,
+                  moonPayUserId: this.state.moonpayCustomerId,
+                },
+              }),


feels written a little oddly. Perhaps we just pass state.activeVendor straight through to vendorId and then add a helper to generate the extra vendorMetadata bit

That is a definitely a clean and better approach.

jiexi · 2026-08-17T22:55:11Z

      return result;
    } catch (error) {
+      // Applicant already finished KYC — treat as completed for Money toast.
+      if (String(error).includes(SESSION_NOT_IN_VALID_STATE)) {


would be nice to abstract this into a helper

jiexi · 2026-08-17T23:02:53Z

    this.#stopPolling();
+    this.#stopUserStatusPolling();


TODO(jiexi): verify the difference between these two poll loops

not certain we need both polling loops

jiexi · 2026-08-17T23:13:32Z

+  /**
+   * Creates (or resumes) an Iron empty-shell customer for the authenticated
+   * canonical user. Must run before showing Iron T&C so the customer exists in
+   * `SigningsRequired` and resume logic can key off Iron status.


doesn't need to exist before showing T&C, only before submitting signing contentIds to Iron

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 47840d7. Configure here.}

…igned booleans

georgeweiler · 2026-08-19T01:58:13Z

An architectural suggestion: right now Iron Money onboarding is exposed as public KYC APIs (createIronCustomer, Iron-named KycService methods, vendor: 'iron' on the consumer surface). It is a bit awkward IMO.

I am imagining something like this instead, where ramps-controller can pass a "vendor" (like iron) to some generic methods:

createVendorCustomer({ vendor, email })
fetchDisclaimers({ vendor })
checkKycRequired({ vendor })

Akaryatrh and others added 30 commits July 24, 2026 12:26

feat: init KYC controller and add logic from mobile repo

1166c0c

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

feat: update readme with architecture doc

18c67ef

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

feat: add product support + automatic calls to kyc required and sumsu…

400b874

…b flow opening Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

fix: geoCountry not updated issue

9b3de4c

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

fix: previously selected product is not reset

133fa9b

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

fix: issue with sumsub complete status

89ac0b4

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

feat: update lock file

3392d00

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

fix: issue with old accessToken and state update while controller has…

3de6713

… been reset Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

fix: another race condition

49ec4f1

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

fix: add links in changelog

20cff98

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

fix: lint issue

abc47a6

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

fix: dedupe dependencies

461473d

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

fix: cursor comments + state management

41275fc

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

fix: session state issue

cb246ed

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

fix: lockfile after rebase

194d216

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

fix: review again state management

85a764f

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

feat: update architecture section of readme

ed8497c

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

feat: update codeowner files

3d2cf99

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

fix: lint issues

2c4805d

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

replace idosSessionId with sessionId

1983026

Initial key derivation, wrapping, and submission

a1fcb5b

add ukycCapabilityToken submission

b9bc735

WIP

02afb3a

Merge branch 'main' into feat/kyc-controller

cf28727

Fix key wrapping. Fix idosSessionId param

966ca62

Merge branch 'jl/kyc-controller-fix-nonce' into feat/kyc-controller

9c0dee1

rename fetchApplicantAccessToken to createJourney

8eee01d

polling status

40bb435

Merge remote-tracking branch 'origin/main' into feat/kyc-controller

9b99126

feat: update lockfile after merge with main

54b16fd

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

Akaryatrh and others added 4 commits August 8, 2026 01:43

fix: missing entry in readme

ece1fef

Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>

Adjusting the storage token to the spec

81246f6

Creating a test token script

e57e5c3

amitabh94 requested review from a team as code owners August 12, 2026 21:18

cursor Bot reviewed Aug 12, 2026

View reviewed changes

Comment thread packages/kyc-controller/src/KycController.ts Outdated

Comment thread packages/kyc-controller/src/KycController.ts

Comment thread packages/kyc-controller/src/KycController.ts

amitabh94 and others added 2 commits August 12, 2026 15:37

fix(kyc-controller): resolve CI lint and changelog failures

633f53f

Add PR link and formatting for changelog, fix JSDoc/restricted-syntax/jest matcher lint errors, and apply Prettier to the package. Co-authored-by: Cursor <cursoragent@cursor.com>

fix(kyc-controller): apply oxfmt for lint:misc:check

689dde0

Use oxfmt (not Prettier) so import order and markdown alignment match the monorepo misc formatter. Co-authored-by: Cursor <cursoragent@cursor.com>

amitabh94 mentioned this pull request Aug 12, 2026

fix(kyc-controller): sync Iron CI lint fixes onto neobank-demo #9855

Merged

3 tasks

bring over missing changes from neobank-demo

c31e4d6

jiexi reviewed Aug 17, 2026

View reviewed changes

Base automatically changed from feat/kyc-controller to main August 17, 2026 23:45

Merge branch 'main' into feat/iron-kyc-controller-m2

47840d7

cursor Bot reviewed Aug 18, 2026

View reviewed changes

Comment thread packages/kyc-controller/src/KycController.ts

jiexi reviewed Aug 18, 2026

View reviewed changes

Comment thread packages/kyc-controller/ARCHITECTURE.md Outdated

jiexi added 5 commits August 18, 2026 10:12

fetch should default to native

e2ea7f6

controller.acceptTermsAndStartSession no longer default true for tncS…

5f79bfc

…igned booleans

add #buildUkycSessionVendorFields

72b694b

abstract error check into isSessionAlreadyCompletedError

2d1d314

Fix polling loop double polling

f510117

georgeweiler mentioned this pull request Aug 19, 2026

feat(kyc-controller): generalize UKYC vendor APIs and add status polling #9908

Open

5 tasks

		sumsubTncSigned: params?.sumsubTncSigned ?? true,
		idosTncSigned: params?.idosTncSigned ?? true,

Uh oh!

Uh oh!

Conversation

amitabh94 commented Aug 12, 2026

Summary

Stacking

Deferred (follow-ups)

Test plan

Uh oh!

Uh oh!

Uh oh!

Uh oh!

amitabh94 commented Aug 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

georgeweiler commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

georgeweiler commented Aug 19, 2026 •

edited

Loading