[georgeweiler]

Description

Stack position: 1 of 4 remaining VBA onboarding PRs.

This PR has no UI. It is the coordinator that decides where a Virtual Bank Account user should be in onboarding.

Previously, each screen knew what came next. Resume was guesswork, and inserting or reordering steps required changing every screen.

Now one snapshot from hydrateVbaOnboarding is the source of truth. getVbaDestinationForSnapshot walks three client-owned modules — vendor terms, email, identity verification — and returns the first incomplete one. If all are complete, it maps controller status to pending, rejected, complete, or a provisioning error.

Everything goes through useOpenVbaOnboarding: entry, retry, and module completion all re-read facts and open the first incomplete destination. VBA screens live behind one feature-local navigator.

Changelog

CHANGELOG entry: null

Related issues

Refs: MetaMask/core#10354

Manual testing steps

Feature: Modular VBA onboarding coordination

  Scenario: onboarding resumes from persisted facts
    Given a hydrated VBA onboarding snapshot
    When the coordinator resolves the first incomplete module
    Then it selects the corresponding feature-local route

Screenshots/Recordings

N/A — architecture-only stack layer covered by unit tests.

Before

N/A

After

N/A

Pre-merge author checklist

• I've followed MetaMask contributor and mobile coding standards.
• I've completed the PR template to the best of my ability.
• I've included tests if applicable.
• I've documented the code where applicable.
• I've applied the appropriate labels.

Performance checks (if applicable)

• Android testing assessed — N/A for this architecture-only stack layer.
• Power-user testing assessed — N/A for this architecture-only stack layer.
• Performance tracing assessed — N/A; no performance-sensitive operation was added.

Pre-merge reviewer checklist

• I've manually tested the PR.
• I confirm that this PR addresses its stated scope and includes appropriate testing evidence.

Made with Cursor

[github-actions]

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.

[github-actions]

Smart E2E Test Selection

Selected E2E tags: SmokeMoney

AI Confidence: 85

E2E reasoning

Expand to read

The PR modifies the Virtual Bank Account (VBA) onboarding flow within the Ramp/Card feature area:

1. New route file (routes.ts): Defines VbaOnboardingParamList and VbaOnboardingRoutes constants for the VBA onboarding navigator stack.
2. New types file (modules/types.ts): Adds completion interfaces for VBA email and identity verification modules.
3. Funnel refactor (vbaOnboardingFunnel.ts): Renames VbaOnboardingRoute → VbaOnboardingDestinationId, VBA_FUNNEL → VBA_ONBOARDING_MODULES, and getVbaRouteForSnapshot → getVbaDestinationForSnapshot. Changes return values from direct route strings to abstract destination IDs. This is a behavioral refactor of VBA onboarding routing logic.
4. Hook update (useVbaOnboardingRouting.ts): Adapts to use new destination IDs and VbaOnboardingRoutes.
5. NavigationService/types.ts (CRITICAL): Adds RampVbaOnboarding: NavigatorScreenParams<VbaOnboardingParamList> to RootStackParamList — a new nested navigator entry.
6. Routes.ts: Adds VBA_ONBOARDING: 'RampVbaOnboarding' route constant.
7. Test files: Updated unit tests reflecting the refactored API.
8. vbaOnboardingSnapshot.ts: Cosmetic comment change only.

All changes are scoped to the Ramp/VBA/Card onboarding flow, which maps directly to SmokeMoney. The open PR review comment flags a potential bug where approved KYC with in-progress account provisioning could incorrectly route to the error screen — this makes running SmokeMoney smoke tests important to validate the routing behavior.

No changes affect swap execution, transaction confirmations, accounts, networks, or other flows, so no other tags are warranted. The SmokeMoney description covers Card and Ramps flows including onboarding paths.

Performance reasoning

Expand to read

No performance-sensitive code paths are modified. The changes are purely routing/navigation type definitions and a refactor of the VBA onboarding funnel logic (renaming types and abstracting destination IDs). No rendering, state management, asset loading, or app launch paths are affected.

View run

[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 b617f00. Configure here.}

[cursor]

Approved KYC treats in-progress as error

Medium Severity

When kycStatus is approved, any autorampStatus other than ready maps to accountProvisioningError. That includes the default not_ready in-progress value, not just retryable_failure. Users whose KYC just cleared while account provisioning is still running can land on the error screen instead of a waiting state.

 

^{Reviewed by Cursor Bugbot for commit b617f00. Configure here.}

[georgeweiler]

Fixed. Approved KYC now maps ready to complete, retryable_failure to the provisioning error, and both not_ready and in_progress to the pending destination. Added coverage for both non-terminal statuses.

[weitingsun]

navigation files LGTM

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
93.6% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud