Skip to content

feat(kyc-controller): throw on previously silently handled errors - #10214

Open
jiexi wants to merge 4 commits into
mainfrom
jl/kyc-controller-do-not-throw-silently
Open

jiexi wants to merge 4 commits into
mainfrom
jl/kyc-controller-do-not-throw-silently

Conversation

@jiexi

@jiexi jiexi commented Sep 11, 2026

Copy link
Copy Markdown
Member

Explanation

  • BREAKING: checkKycRequired and the consents-path session (#startConsentsSession via acceptTermsAndStartSession / a resumed initialize) now rethrow the original error after writing it to controller state.
  • A product-scoped MoonPay auto-run therefore rejects handleFrameMessage / onAuthenticated when the KYC-required check fails, instead of only setting phase: 'error'.
  • In-flight failures after reset() still do not write state or rethrow. Validation #fail + return (missing email/token/country) is 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

Note

Medium Risk
Breaking promise semantics for KYC entry points (checkKycRequired, consents session) require consumer updates; failures still update controller state before throw, so callers must handle both rejection and state.

Overview
Breaking change: several KYC controller paths still write failures to state, but now rethrow the original error instead of resolving quietly.

checkKycRequired sets phase: 'error' on a failed service call and then throws (it previously returned false). For product-scoped MoonPay flows, that means onAuthenticated / frame-message handling can reject when the auto-run KYC-required check fails, not only update state.

The consents-path session (acceptTermsAndStartSession, resumed initialize, and #startConsentsSession) still rewinds to terms and records a consents failure, then rethrows so callers can catch the underlying error. JSDoc, generated action types, tests, and the changelog document the new @throws behavior.

Unchanged: validation-style #fail + return (missing token/email/country), and in-flight work superseded by reset() still avoids updating state or rethrowing. startSumSub failures remain swallowed in #continueAfterAuthentication so the frame handler can await safely.

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

@jiexi
jiexi requested review from a team as code owners September 11, 2026 18:26
@jiexi
jiexi deployed to default-branch September 11, 2026 18:26 — with GitHub Actions Active
@jiexi

jiexi commented Sep 11, 2026

Copy link
Copy Markdown
Member Author

@metamaskbot publish-previews

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

jiexi commented Sep 11, 2026

Copy link
Copy Markdown
Member Author

@metamaskbot publish-preview

@Akaryatrh

Copy link
Copy Markdown
Contributor

@metamaskbot publish-preview

1 similar comment
@cryptodev-2s

Copy link
Copy Markdown
Contributor

@metamaskbot publish-preview

@github-actions

Copy link
Copy Markdown
Contributor

Preview builds have been published. Learn how to use preview builds in other projects.

Expand for full list of packages and versions.
@metamask-previews/account-tree-controller@10.0.1-preview-0a8ce9948
@metamask-previews/accounts-controller@40.0.0-preview-0a8ce9948
@metamask-previews/address-book-controller@8.0.0-preview-0a8ce9948
@metamask-previews/ai-controllers@2.0.0-preview-0a8ce9948
@metamask-previews/analytics-controller@3.0.0-preview-0a8ce9948
@metamask-previews/analytics-data-regulation-controller@0.0.0-preview-0a8ce9948
@metamask-previews/announcement-controller@9.0.0-preview-0a8ce9948
@metamask-previews/app-metadata-controller@3.0.0-preview-0a8ce9948
@metamask-previews/approval-controller@10.0.0-preview-0a8ce9948
@metamask-previews/assets-controller@16.0.0-preview-0a8ce9948
@metamask-previews/assets-controllers@112.0.1-preview-0a8ce9948
@metamask-previews/authenticated-user-storage@4.0.0-preview-0a8ce9948
@metamask-previews/base-controller@10.0.0-preview-0a8ce9948
@metamask-previews/base-data-service@2.0.0-preview-0a8ce9948
@metamask-previews/bitcoin-regtest-up@2.0.0-preview-0a8ce9948
@metamask-previews/bridge-controller@81.1.0-preview-0a8ce9948
@metamask-previews/bridge-status-controller@76.2.0-preview-0a8ce9948
@metamask-previews/build-utils@4.0.0-preview-0a8ce9948
@metamask-previews/chain-agnostic-permission@2.0.0-preview-0a8ce9948
@metamask-previews/chomp-api-service@5.0.0-preview-0a8ce9948
@metamask-previews/claims-controller@1.0.1-preview-0a8ce9948
@metamask-previews/client-controller@2.0.0-preview-0a8ce9948
@metamask-previews/client-utils@3.0.0-preview-0a8ce9948
@metamask-previews/compliance-controller@3.0.0-preview-0a8ce9948
@metamask-previews/composable-controller@13.0.0-preview-0a8ce9948
@metamask-previews/config-registry-controller@4.0.0-preview-0a8ce9948
@metamask-previews/connectivity-controller@1.0.0-preview-0a8ce9948
@metamask-previews/controller-utils@13.0.0-preview-0a8ce9948
@metamask-previews/core-backend@10.0.1-preview-0a8ce9948
@metamask-previews/cryptography@0.0.0-preview-0a8ce9948
@metamask-previews/delegation-controller@4.0.0-preview-0a8ce9948
@metamask-previews/earn-controller@13.0.0-preview-0a8ce9948
@metamask-previews/eip-5792-middleware@4.0.0-preview-0a8ce9948
@metamask-previews/eip-7702-internal-rpc-middleware@1.0.0-preview-0a8ce9948
@metamask-previews/eip1193-permission-middleware@3.0.0-preview-0a8ce9948
@metamask-previews/eth-block-tracker@16.0.0-preview-0a8ce9948
@metamask-previews/eth-json-rpc-middleware@25.0.0-preview-0a8ce9948
@metamask-previews/eth-json-rpc-provider@7.0.0-preview-0a8ce9948
@metamask-previews/foundryup@2.0.0-preview-0a8ce9948
@metamask-previews/gas-fee-controller@27.0.0-preview-0a8ce9948
@metamask-previews/gator-permissions-controller@6.0.0-preview-0a8ce9948
@metamask-previews/geolocation-controller@2.0.0-preview-0a8ce9948
@metamask-previews/java-tron-up@2.0.0-preview-0a8ce9948
@metamask-previews/json-rpc-engine@11.0.0-preview-0a8ce9948
@metamask-previews/json-rpc-middleware-stream@9.0.0-preview-0a8ce9948
@metamask-previews/keyring-controller@28.0.0-preview-0a8ce9948
@metamask-previews/kyc-controller@0.3.0-preview-0a8ce9948
@metamask-previews/local-node-utils@2.0.0-preview-0a8ce9948
@metamask-previews/logging-controller@10.0.0-preview-0a8ce9948
@metamask-previews/message-manager@15.0.0-preview-0a8ce9948
@metamask-previews/messenger@3.0.0-preview-0a8ce9948
@metamask-previews/messenger-cli@1.0.0-preview-0a8ce9948
@metamask-previews/money-account-api-data-service@1.0.0-preview-0a8ce9948
@metamask-previews/money-account-balance-service@3.0.0-preview-0a8ce9948
@metamask-previews/money-account-controller@2.0.0-preview-0a8ce9948
@metamask-previews/money-account-upgrade-controller@5.0.0-preview-0a8ce9948
@metamask-previews/money-account-utils@2.0.0-preview-0a8ce9948
@metamask-previews/multichain-account-service@14.0.0-preview-0a8ce9948
@metamask-previews/multichain-api-middleware@5.0.0-preview-0a8ce9948
@metamask-previews/multichain-network-controller@4.0.0-preview-0a8ce9948
@metamask-previews/multichain-transactions-controller@8.0.0-preview-0a8ce9948
@metamask-previews/name-controller@10.0.0-preview-0a8ce9948
@metamask-previews/network-connection-banner-controller@1.0.0-preview-0a8ce9948
@metamask-previews/network-controller@37.0.0-preview-0a8ce9948
@metamask-previews/network-enablement-controller@7.0.0-preview-0a8ce9948
@metamask-previews/notification-services-controller@28.0.1-preview-0a8ce9948
@metamask-previews/passkey-controller@4.0.0-preview-0a8ce9948
@metamask-previews/permission-controller@14.0.0-preview-0a8ce9948
@metamask-previews/permission-log-controller@6.0.0-preview-0a8ce9948
@metamask-previews/perps-controller@17.1.0-preview-0a8ce9948
@metamask-previews/phishing-controller@18.0.0-preview-0a8ce9948
@metamask-previews/platform-api-docs@0.2.0-preview-0a8ce9948
@metamask-previews/polling-controller@17.0.0-preview-0a8ce9948
@metamask-previews/preferences-controller@24.0.0-preview-0a8ce9948
@metamask-previews/profile-metrics-controller@5.1.0-preview-0a8ce9948
@metamask-previews/profile-sync-controller@32.1.1-preview-0a8ce9948
@metamask-previews/ramps-controller@22.0.0-preview-0a8ce9948
@metamask-previews/rate-limit-controller@8.0.0-preview-0a8ce9948
@metamask-previews/react-data-query@2.0.0-preview-0a8ce9948
@metamask-previews/remote-feature-flag-controller@7.0.0-preview-0a8ce9948
@metamask-previews/sample-controllers@6.0.0-preview-0a8ce9948
@metamask-previews/seedless-onboarding-controller@11.0.0-preview-0a8ce9948
@metamask-previews/selected-network-controller@27.0.0-preview-0a8ce9948
@metamask-previews/sentinel-api-service@2.0.0-preview-0a8ce9948
@metamask-previews/shield-controller@7.0.1-preview-0a8ce9948
@metamask-previews/signature-controller@40.0.0-preview-0a8ce9948
@metamask-previews/smart-transactions-controller@27.0.1-preview-0a8ce9948
@metamask-previews/snap-account-service@3.0.0-preview-0a8ce9948
@metamask-previews/social-controllers@3.0.1-preview-0a8ce9948
@metamask-previews/solana-test-validator-up@2.0.0-preview-0a8ce9948
@metamask-previews/stellar-quickstart-up@0.0.0-preview-0a8ce9948
@metamask-previews/storage-service@2.0.0-preview-0a8ce9948
@metamask-previews/subscription-controller@9.0.1-preview-0a8ce9948
@metamask-previews/transaction-controller@70.0.0-preview-0a8ce9948
@metamask-previews/transaction-pay-controller@28.0.2-preview-0a8ce9948
@metamask-previews/user-operation-controller@42.0.0-preview-0a8ce9948
@metamask-previews/utils@12.0.0-preview-0a8ce9948
@metamask-previews/wallet@13.0.0-preview-0a8ce9948
@metamask-previews/wallet-cli@0.0.0-preview-0a8ce9948

@Akaryatrh Akaryatrh 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.

LGTM

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.

3 participants