feat(money): add mobile wrappers for Money Account vault deposit and withdraw

[saustrie-consensys]

Description

Money Account only earns yield and funds Card spend through vault shares (vmUSD), so mUSD that arrives from an external payout has to be vaulted, and paying out to a partner (Iron, for the Pix flow) requires redeeming vmUSD back to mUSD and transferring it. Core now exposes both directions as TransactionPayController messenger actions (MetaMask/core#9849). This PR is the mobile-side plumbing for them.

It adds two thin wrappers in app/core/Engine/controllers/transaction-pay-controller/money-account-vault-actions.ts:

• submitMoneyAccountVaultDeposit({ moneyAccountAddress, transactionHash }) vaults a completed mUSD payout. It is headless (no confirmation UI). Successful vaults are deduped in-memory for the Core controller lifetime, so retries in the same session return the prior hash; an app restart can try again. Disabled vaulting returns { skipped: true } and does not permanently block a later retry after the feature flag is enabled. The upcoming MoonPay/Iron websocket listener can call it directly, as can any Money Account screen.
• submitMoneyAccountVaultWithdraw({ amountInRaw, moneyAccountAddress, recipient, requestId }) redeems vmUSD and transfers the resulting mUSD to an Iron deposit address in one atomic batch, going through the normal transaction confirmation. Quote / Pix identifiers stay out of this wrapper; they belong in RampsController / NeoBankService.

It also delegates the two actions the controller now needs, MoneyAccountBalanceService:getMoneyAccountBalance and TransactionController:addTransactionBatch, in the transaction-pay-controller messenger.

No UI is wired up here, and no behavior changes for users yet. The websocket listener and the Pix send screen are separate tickets; this PR only gives them a stable entrypoint to call. The wrappers compile against the local controller interface, but they need the Core release containing MetaMask/core#9849 to actually work at runtime.

Changelog

CHANGELOG entry: null

Related issues

Refs: MetaMask/core#9849

Manual testing steps

N/A. There is no user-reachable surface in this PR: it adds wrapper functions and messenger delegations that nothing calls yet, and the underlying Core actions are not in a released version of @metamask/transaction-pay-controller yet. Behavior is covered by unit tests in money-account-vault-actions.test.ts and transaction-pay-controller-messenger.test.ts. Manual Gherkin steps will accompany the PRs that add the Iron websocket listener and the Pix send button.

Screenshots/Recordings

N/A. No UI changes.

Before

N/A

After

N/A

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Performance checks (if applicable)

• I've tested on Android
  • Ideally on a mid-range device; emulator is acceptable
• I've tested with a power user scenario
  • Use these power-user SRPs to import wallets with many accounts and tokens
• I've instrumented key operations with Sentry traces for production performance metrics
  • See trace() for usage and addToken for an example

Performance boxes are left unchecked deliberately: this PR adds no UI and no runtime work on any user path, so there is nothing to measure on device yet. Tracing will be added with the screens that call these actions.

For performance guidelines and tooling, see the Performance Guide.

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.

[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.

[metamask-ci]

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

Warnings — informational, address before merging:

• Pre-merge author checklist has unchecked items (e.g. "I've tested on Android"). Every box must be consciously checked — see docs/readme/ready-for-review.md.

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

[metamask-ci]

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

Warnings — informational, address before merging:

• Pre-merge author checklist has unchecked items (e.g. "I've tested on Android"). Every box must be consciously checked — see docs/readme/ready-for-review.md.

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

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: SmokeMoney, SmokeConfirmations
• Selected Performance tags: None (no tests recommended)
• Risk Level: medium
• AI Confidence: 72%

click to see 🤖 AI reasoning details

E2E Test Selection:
The PR introduces two sets of changes:

1. New money-account-vault-actions.ts (entirely new file): Adds submitMoneyAccountVaultDeposit and submitMoneyAccountVaultWithdraw action wrappers that delegate to TransactionPayController. These are Money Account vault operations (deposit mUSD from Iron payouts, withdraw vmUSD to Iron addresses). The file is not yet imported by any UI component — only its own unit test imports it — so direct E2E impact is minimal. However, it establishes infrastructure for Money Account vault flows.

2. transaction-pay-controller-messenger.ts changes (additive): Adds two new action delegations to the TransactionPayController messenger:

   • MoneyAccountBalanceService:getMoneyAccountBalance (with a cast, noting it's from a future release)
   • TransactionController:addTransactionBatch

   These are additive changes — no existing delegations are removed or modified. The addTransactionBatch action is used for atomic batch transactions, which is relevant to the Money Account withdrawal flow (the code comments mention "atomic withdraw/transfer batch").

Tag selection rationale:

• SmokeMoney: The changes are directly related to Money Account vault deposit/withdraw flows, which are part of the MetaMask Card/fiat infrastructure. The messenger changes expand TransactionPayController's capabilities for Money flows.
• SmokeConfirmations: The vault withdrawal creates "an approval request" requiring user confirmation before broadcasting the atomic batch. The TransactionController:addTransactionBatch delegation is used for batch transaction confirmations. Per tag description, SmokeMoney flows that execute on-chain transactions should also select SmokeConfirmations.

Risk assessment: Medium — changes are additive (new file + new messenger delegations), no existing functionality is modified. The messenger changes are low-risk additions. The new vault actions are not yet wired to UI, limiting E2E exposure. However, the TransactionPayController messenger is a core infrastructure component for Money flows, warranting validation.

Performance Test Selection:
The changes are additive infrastructure additions (new vault action wrappers and messenger delegations) that don't affect any performance-sensitive flows like app launch, login, onboarding, asset loading, or swap execution. The new money-account-vault-actions.ts file is not yet wired to any UI, and the messenger changes are additive delegations that don't alter existing performance characteristics. No performance test tags are warranted.

View GitHub Actions results

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud