Skip to content

feat(ramp): track Money VBA Transaction Updated - #38078

Merged
georgeweiler merged 7 commits into
mainfrom
cursor/vba-transaction-analytics-b4a1
Oct 28, 2026
Merged

georgeweiler merged 7 commits into
mainfrom
cursor/vba-transaction-analytics-b4a1

Conversation

@georgeweiler

@georgeweiler georgeweiler commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Explanation

When the VBA details screen loads an approved autoramp, it calls RampsController.refreshAutorampTransactions. The controller calls trackAutorampTransactionStatusChanged for a new transaction or a status change. Mobile passes that callback from rampsControllerInit and tracks Money VBA Transaction Updated.

This matches the schema merged in Consensys/segment-schema#785 and the callback on MetaMask/core#11017:

  • status is pending for FundsReviewInProgress, ConversionInProgress, and PayoutInProgress; completed for Completed; failed for Failed, RejectedAml, RejectedFraud, and RejectedMinAmount. A vendor status outside that enum is not tracked, because status and transaction_status are required closed enums.
  • The raw vendor value stays on transaction_status. previous_status is omitted for a new id and when the previous value is outside the enum.
  • failure_reason is not sent. The schema's known quirk is that a failed transaction is status: failed plus the raw transaction_status. failure_reason is the onboarding failure enum.
  • kyc_status and provider_flow_status are always sent. Missing state uses none and not_started.
  • entry_point (add_funds_bank_account), vendor (moonpay), autoramp_status (ready), currency_destination_symbol (mUSD), and token_chain_id (eip155:143) are constants. screen_name is omitted because this fires from the fetch, not from a screen.
  • region is the lowercase alpha-2 country and is omitted while geolocation is unknown. The schema marks it required and has no unknown value, so an invented country is not sent.
  • currency_source is sent when the autoramp deposit rail has one. Amounts are numbers and are omitted when not numeric. seconds_since_created is computed when the callback runs and is never negative.

orderStatusChanged stays a messenger subscription. It is still used for notifications and order analytics. There is no transaction-status messenger event.

Production fetches transactions once per autoramp while the details screen is open. Debug builds keep refreshing on the existing details poll so the debug sheet can show the latest status. A failed transaction refresh does not hide deposit details. There is no new background poller.

Package bump

Depends on MetaMask/core#11017. This compiles against the published @metamask/ramps-controller by declaring AutorampTransactionStatusChangedPayload locally and attaching trackAutorampTransactionStatusChanged through a constructor-options intersection. After @metamask/ramps-controller includes refreshAutorampTransactions and AutorampTransactionStatusChangedPayload:

  • Bump @metamask/ramps-controller.
  • Import AutorampTransactionStatusChangedPayload from the package and delete the local copy in vbaTransactionAnalytics.ts.
  • Drop the intersection on the constructor options.

Until that bump, refreshAutorampTransactions is optional on the controller, so an older package skips the refresh instead of crashing. The new NeoBankService:listAutorampTransactions action is already covered by spreading RAMPS_CONTROLLER_REQUIRED_SERVICE_ACTIONS once that list includes it.

Checklist


Note

Medium Risk
Touches money/VBA deposit flows and analytics emission on transaction refresh; behavior is guarded when the ramps package lacks refreshAutorampTransactions, but incorrect mapping could skew funnel metrics.

Overview
Adds Money VBA Transaction Updated analytics when autoramp deposit transaction statuses change, aligned with the Segment VBA schema.

rampsControllerInit passes trackAutorampTransactionStatusChanged into RampsController, which maps vendor statuses to pending / completed / failed, enriches events from Redux (KYC, region, fiat source), and skips unknown statuses. A shared toAnalyticsRegion helper normalizes geolocation for region.

VBA details now triggers RampsController.refreshAutorampTransactions (once per autoramp in production, on the existing poll in debug) instead of calling NeoBankService.listAutorampTransactions. Deposit instruction loading stays separate so a failed transaction refresh does not hide PIX details; debug UI still shows the latest deposit status from the refresh result.

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

@metamask-ci metamask-ci Bot added the team-money-movement issues related to Money Movement features label Oct 22, 2026
@metamask-ci metamask-ci Bot added the INVALID-PR-TEMPLATE PR's body doesn't match template label Oct 22, 2026
@metamask-ci

metamask-ci Bot commented Oct 22, 2026

Copy link
Copy Markdown
Contributor

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

Warnings — informational, address before merging:

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

@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Smart E2E Test Selection

Selected E2E tags: SmokeMoney

AI Confidence: 90

E2E reasoning

Expand to read

All changes are scoped to the Ramps/Money VBA (Virtual Bank Account) feature:

  1. VbaDetails.tsx: Refactors transaction fetching from neoBank.listAutorampTransactions() to ramps.refreshAutorampTransactions() and adds a deduplication guard (transactionsFetchedForRef). This is a behavioral change in the VBA details screen — a core SmokeMoney flow.

  2. ramps-controller-init.ts: Wires a new trackAutorampTransactionStatusChanged callback into the RampsController constructor. This is a controller init change that could affect ramps controller startup behavior.

  3. vbaTransactionAnalytics.ts (new): Analytics event handler for VBA transaction status changes — fires MONEY_VBA_TRANSACTION_UPDATED events. Pure analytics addition.

  4. MetaMetrics.events.ts: Adds MONEY_VBA_TRANSACTION_UPDATED analytics event constant.

  5. analyticsRegion.ts (new): Utility for reading geolocation region for analytics — used by the VBA analytics handler.

  6. Test files: Unit/component tests for the above changes.

The changes are entirely within the Money/Ramps domain (VBA/PIX fiat on-ramp flow). The ramps controller init change is the highest-risk item as it modifies how the RampsController is instantiated, but the change is additive (adding a new callback option). No changes to shared infrastructure, authentication, navigation, or other feature areas. SmokeMoney covers the ramps/fiat flows including VBA. No confirmation flows are directly modified (the VBA flow doesn't go through standard transaction confirmations), so SmokeConfirmations is not required per the tag descriptions.

View run

@github-actions

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.

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

Property fixes look good. One gap before RC: transactions only refresh when VbaDetails mounts. A user who deposits and returns to Money home never fires Transaction Updated (completed). Can we also call refreshAutorampTransactions where the Money home VBA card loads? The thin record from core#11017 already dedupes.

Nit: failure_reason: vendor_error on failed transactions contradicts the 785 note. Drop it or update the note.

@georgeweiler
georgeweiler marked this pull request as ready for review October 27, 2026 20:23
@georgeweiler
georgeweiler requested review from a team as code owners October 27, 2026 20:23
cursoragent and others added 6 commits October 27, 2026 20:25
Subscribe to autoramp transaction status changes and refresh that list from the VBA details screen instead of the debug-only fetch.

Co-authored-by: george.weiler <george.weiler@consensys.net>
- Send currency_source instead of fiat_code
- Send source_amount and destination_amount as numbers; omit a non-numeric amount
- Report every failed or rejected status with the schema failure_reason vendor_error (raw status stays on transaction_status)
- Normalize region to lowercase alpha-2
- Send the constant required properties: entry_point, vendor moonpay, autoramp_status ready, and the mUSD / eip155:143 destination

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Money VBA Transaction Updated follows the injected tracker and the merged schema: status defaults are always sent, failure_reason is omitted, and an unknown vendor status is not tracked.

Co-authored-by: Cursor <cursoragent@cursor.com>
Review follow-up on the VBA/KYC analytics PRs.

- region is always sent, unknown while geolocation is unresolved. The
  schema marks it required, so omitting it put every pre-geolocation event
  off contract. Normalization moves to the shared
  app/util/analytics/analyticsRegion.ts that the two sibling PRs add with
  identical content.
- readVbaTransactionBaseProperties is typed Partial, which is what it
  already returned; the previous Pick annotation claimed required fields
  the empty-state branch does not produce.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Committed by mistake in 8eac4ba. The worktree symlinks node_modules at the
main checkout, and .gitignore's "node_modules/" pattern matches a directory
but not a symlink, so git add -A picked it up. Checking this branch out over
a real node_modules directory replaces it with a dangling symlink.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@cursor
cursor Bot force-pushed the cursor/vba-transaction-analytics-b4a1 branch from 6610f5f to a4198d7 Compare October 27, 2026 20:27
amitabh94
amitabh94 previously approved these changes Oct 27, 2026
gaohan1994 pushed a commit to gaohan1994/core that referenced this pull request Oct 28, 2026
…11017)

## Explanation

The app needs to know when a virtual bank account transaction is new or
has changed status, without storing amounts or bank details and without
reporting the same change twice.

`RampsController` persists `autorampTransactionRecords`: for each
autoramp, the epoch ms of the first successful fetch and the last seen
status string per transaction id. `diffAutorampTransactions` is pure.
The first successful fetch (including an empty one) seeds the record and
calls nothing. Later fetches report a new id or a different status
string, including a status that moved backwards or skipped intermediate
values. A transaction missing from the page stays in the record.

`refreshAutorampTransactions` loads the newest page (`sort_order=desc`,
`page_size` 50, no pagination), writes the next record, then calls the
optional `trackAutorampTransactionStatusChanged` constructor callback
once per change. `previousStatus` is omitted for a new id. A failed
fetch writes nothing. Concurrent calls for the same autoramp share one
request. Removing an autoramp, replacing the autoramp cursor, or
discarding a foreign VBA session clears the matching records. A fetch
still in flight when that autoramp leaves the cursor does not write the
record or call the callback.

This is an analytics signal, so it is a callback rather than a
`RampsController` messenger event. `orderStatusChanged` and
`autorampStatusChanged` stay messenger events because the client uses
them for more than tracking.

`NeoBankService.listAutorampTransactions` accepts an optional
`pageSize`. Omitting it keeps the previous query.

## References

* Mobile adoption:
MetaMask/metamask-mobile#38078

## Checklist

- [x] I've updated the test suite for new or updated code as appropriate
- [x] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [x] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/processes/updating-changelogs.md)
- [x] I've introduced [breaking
changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md)
in this PR and have prepared draft pull requests for clients and
consumer packages to resolve them

**BREAKING:** `RAMPS_CONTROLLER_REQUIRED_SERVICE_ACTIONS` now includes
`NeoBankService:listAutorampTransactions`. Hosts that spread that list
pick it up on the package bump. Hosts that copy the action list by hand
must delegate it.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Introduces a breaking messenger delegation requirement and new
persisted VBA transaction state with analytics callbacks; behavior is
guarded but hosts must wire the NeoBank action and handle migration of
persisted state.
> 
> **Overview**
> Adds **persisted autoramp transaction status tracking** so hosts can
learn when a VBA deposit transaction is new or its MoonPay status string
changed, without storing amounts or firing duplicate analytics.
> 
> `RampsController` gains persisted `autorampTransactionRecords` (per
autoramp: `syncedAt` plus last-seen status per transaction id), the pure
helper `diffAutorampTransactions`, and
**`refreshAutorampTransactions`**, which loads the newest transaction
page (`page_size` 50), updates the record, then invokes optional
constructor callback **`trackAutorampTransactionStatusChanged`** once
per new id or status change (`previousStatus` omitted for new ids). The
first successful fetch only seeds the record; failed fetches leave it
unchanged; concurrent refreshes per autoramp dedupe to one request;
records are cleared when an autoramp is removed, the cursor is replaced,
or a foreign VBA session is discarded, with in-flight fetches not
re-writing removed autoramps.
> 
> **`NeoBankService.listAutorampTransactions`** accepts optional
**`pageSize`** (`page_size` query). **Breaking:**
`RAMPS_CONTROLLER_REQUIRED_SERVICE_ACTIONS` now requires
**`NeoBankService:listAutorampTransactions`** delegation. New messenger
action **`RampsController:refreshAutorampTransactions`** and related
types are exported from the package.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
86c201b. 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>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Money VBA Transaction Updated properties now extend JsonMap so they can be passed to addProperties, and the tests no longer read fields off a nullable result or a KYC field the handler does not use.

Co-authored-by: George Weiler <georgejweiler@gmail.com>
@sonarqubecloud

Copy link
Copy Markdown

@georgeweiler
georgeweiler added this pull request to the merge queue Oct 28, 2026
Merged via the queue into main with commit 768e5b4 Oct 28, 2026
100 checks passed
@georgeweiler
georgeweiler deleted the cursor/vba-transaction-analytics-b4a1 branch October 28, 2026 12:04
@github-actions github-actions Bot locked and limited conversation to collaborators Oct 28, 2026
@metamask-ci metamask-ci Bot added the release-8.19.0 Issue or pull request that will be included in release 8.19.0 label Oct 28, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

INVALID-PR-TEMPLATE PR's body doesn't match template release-8.19.0 Issue or pull request that will be included in release 8.19.0 size-L team-money-movement issues related to Money Movement features

Projects

None yet

Development

Successfully merging this pull request may close these issues.

7 participants