fix(transaction-pay-controller): guard fiat post-ramp second leg against locked keyring and CHOMP races (MetaMask#9267)

## Explanation

Two failure modes for the direct mUSD Money Account vault deposit are
addressed in this PR.

**Locked keyring at submit time**

When a fiat order completes and the post-ramp second leg is triggered
(direct mUSD vault deposit, Relay nested-calldata, or simple relay), the
wallet may be locked — for example if the user backgrounded the app
during Apple Pay checkout and the auto-lock timer fired. In that state
`KeyringController.keyrings` is empty, `doesAccountSupportEIP7702`
returns `false` for the Money Account address, and `addTransactionBatch`
(called with `disableHook` and `disableSequential`) throws `Account does
not support EIP-7702`, failing the deposit.

A `waitForKeyringUnlock` guard is added at the top of
`submitRelayAfterFiatCompletion` in `fiat-submit.ts`. Before any
second-leg logic runs the function checks
`KeyringController:getState().isUnlocked`. If already unlocked it
proceeds immediately; if locked it subscribes to
`KeyringController:unlock` and waits indefinitely, resuming only after
the user authenticates. `KeyringControllerUnlockEvent` is added to
`AllowedEvents` in `types.ts` to allow the subscription.

**CHOMP auto-vault race**

CHOMP is a backend service that may auto-vault mUSD from the Money
Account independently of the extension/mobile submit path. If CHOMP runs
concurrently with the checkout flow the vault deposit that
`addTransactionBatch` tries to submit may conflict with a deposit CHOMP
already completed, causing a double-vault.

A CHOMP idempotency check is added in `submitDirectMusdVaultDeposit`
using a single `eth_getLogs` call that scans for recent mUSD
Transfer-out events from the Money Account. The baseline block is
derived from the ramps settlement tx receipt (already fetched for the
amount) so no additional network request is needed. The check runs
before `addTransactionBatch` (skip the submit entirely) and again in the
catch path (CHOMP may have won the race just before submit). Detection
errors are swallowed so they never break the normal vault path.

## References

## 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
- [ ] I've introduced breaking changes in this PR and have prepared
draft pull requests for clients and consumer packages to resolve them

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes the fiat post-ramp and direct mUSD vault submission path
(signing, batch submit, and on-chain idempotency) and adds a new
messenger event permission for clients; incorrect CHOMP matching could
skip or mis-attribute a vault hash.
> 
> **Overview**
> Fixes two post–fiat-ramp failure modes for the **direct mUSD Money
Account vault** path and other fiat second legs.
> 
> **Locked keyring:** After the on-ramp order completes, the controller
now calls `waitForKeyringUnlock` before `submitRelayAfterFiatCompletion`
(relay, nested calldata, and direct mUSD). If the wallet is locked it
subscribes to `KeyringController:unlock` and resumes only after unlock,
avoiding false EIP-7702 / `addTransactionBatch` failures when the user
was away during checkout. `KeyringControllerUnlockEvent` is added to
`AllowedEvents` so clients must grant that subscription.
> 
> **CHOMP race:** New `findRecentChompVaultDeposit` scans Monad
`eth_getLogs` for mUSD `Transfer` events from the Money Account (newest
first, amount ≥ settled raw). `submitDirectMusdVaultDeposit` runs this
**before** `addTransactionBatch` (skip submit and return the CHOMP tx
hash) and **again on batch failure** (treat CHOMP as success). Scan
errors are swallowed so the normal vault path still runs. The log window
starts at the ramps settlement receipt block: `resolveSourceAmountRaw` /
`getTransferredAmountFromTxHash` now return `{ amountRaw, fromBlock }` /
`{ amountRaw, blockNumber }` instead of a bare string, with no extra RPC
when the receipt was already fetched for ERC-20 amounts.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
f307c21. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: matthewwalsh0

packages/transaction-pay-controller/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add CHOMP idempotency for direct mUSD vault deposits ([#9267](https://github.com/MetaMask/core/pull/9267))
+
+### Fixed
+
+- Wait for keyring unlock before executing fiat post-ramp second leg ([#9267](https://github.com/MetaMask/core/pull/9267))
+
 ## [23.16.1]
 
 ### Changed

packages/transaction-pay-controller/src/strategy/fiat/chomp.test.ts

@@ -0,0 +1,194 @@
+import type { Hex } from '@metamask/utils';
+
+import { CHAIN_ID_MONAD, MUSD_MONAD_ADDRESS } from '../../constants';
+import type { TransactionPayControllerMessenger } from '../../types';
+import { rpcRequest } from '../../utils/provider';
+import { findRecentChompVaultDeposit } from './chomp';
+
+jest.mock('../../utils/provider');
+
+const MONEY_ACCOUNT_ADDRESS =
+  '0x1111111111111111111111111111111111111111' as Hex;
+const CHOMP_TX_HASH =
+  '0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef' as Hex;
+const FROM_BLOCK = '0x100' as Hex;
+const SOURCE_AMOUNT_RAW = '5000000'; // 5 mUSD (6 decimals)
+// uint256 hex for 5000000 (>= source amount)
+const TRANSFER_DATA_SUFFICIENT =
+  '0x00000000000000000000000000000000000000000000000000000000004c4b40';
+// uint256 hex for 4999999 (< source amount)
+const TRANSFER_DATA_INSUFFICIENT =
+  '0x00000000000000000000000000000000000000000000000000000000004c4b3f';
+
+const ERC20_TRANSFER_TOPIC =
+  '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef';
+
+function padAddress(address: string): string {
+  return `0x${address.replace(/^0x/u, '').toLowerCase().padStart(64, '0')}`;
+}
+
+const MONEY_ACCOUNT_PADDED = padAddress(MONEY_ACCOUNT_ADDRESS);
+
+function buildMusdTransferLog(
+  txHash: Hex = CHOMP_TX_HASH,
+  data: string = TRANSFER_DATA_SUFFICIENT,
+): {
+  address: string;
+  topics: string[];
+  data: string;
+  transactionHash: Hex;
+} {
+  return {
+    address: MUSD_MONAD_ADDRESS,
+    data,
+    topics: [
+      ERC20_TRANSFER_TOPIC,
+      MONEY_ACCOUNT_PADDED,
+      padAddress('0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'),
+    ],
+    transactionHash: txHash,
+  };
+}
+
+function buildMessenger(): TransactionPayControllerMessenger {
+  return {} as TransactionPayControllerMessenger;
+}
+
+describe('chomp', () => {
+  const rpcRequestMock = jest.mocked(rpcRequest);
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+  });
+
+  describe('findRecentChompVaultDeposit', () => {
+    it('returns the CHOMP tx hash when a Transfer log with sufficient amount is found', async () => {
+      rpcRequestMock.mockResolvedValueOnce([buildMusdTransferLog()]);
+
+      const result = await findRecentChompVaultDeposit({
+        fromBlock: FROM_BLOCK,
+        messenger: buildMessenger(),
+        moneyAccountAddress: MONEY_ACCOUNT_ADDRESS,
+        sourceAmountRaw: SOURCE_AMOUNT_RAW,
+      });
+
+      expect(result).toBe(CHOMP_TX_HASH);
+      // Only eth_getLogs should have been called.
+      expect(rpcRequestMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('returns undefined when the mUSD transfer amount is below the required amount', async () => {
+      rpcRequestMock.mockResolvedValueOnce([
+        buildMusdTransferLog(CHOMP_TX_HASH, TRANSFER_DATA_INSUFFICIENT),
+      ]);
+
+      const result = await findRecentChompVaultDeposit({
+        fromBlock: FROM_BLOCK,
+        messenger: buildMessenger(),
+        moneyAccountAddress: MONEY_ACCOUNT_ADDRESS,
+        sourceAmountRaw: SOURCE_AMOUNT_RAW,
+      });
+
+      expect(result).toBeUndefined();
+      expect(rpcRequestMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('returns undefined when no mUSD Transfer logs are found', async () => {
+      rpcRequestMock.mockResolvedValueOnce([]);
+
+      const result = await findRecentChompVaultDeposit({
+        fromBlock: FROM_BLOCK,
+        messenger: buildMessenger(),
+        moneyAccountAddress: MONEY_ACCOUNT_ADDRESS,
+        sourceAmountRaw: SOURCE_AMOUNT_RAW,
+      });
+
+      expect(result).toBeUndefined();
+      expect(rpcRequestMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('queries eth_getLogs with the correct filter', async () => {
+      rpcRequestMock.mockResolvedValueOnce([]);
+
+      await findRecentChompVaultDeposit({
+        fromBlock: FROM_BLOCK,
+        messenger: buildMessenger(),
+        moneyAccountAddress: MONEY_ACCOUNT_ADDRESS,
+        sourceAmountRaw: SOURCE_AMOUNT_RAW,
+      });
+
+      expect(rpcRequestMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          chainId: CHAIN_ID_MONAD,
+          method: 'eth_getLogs',
+          params: [
+            expect.objectContaining({
+              address: MUSD_MONAD_ADDRESS,
+              fromBlock: FROM_BLOCK,
+              toBlock: 'latest',
+              topics: [ERC20_TRANSFER_TOPIC, MONEY_ACCOUNT_PADDED, null],
+            }),
+          ],
+        }),
+      );
+    });
+
+    it('processes logs newest-first and returns the most recent match', async () => {
+      const olderHash =
+        '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex;
+      const newerHash =
+        '0x0000000000000000000000000000000000000000000000000000000000000002' as Hex;
+
+      rpcRequestMock.mockResolvedValueOnce([
+        buildMusdTransferLog(olderHash),
+        buildMusdTransferLog(newerHash),
+      ]);
+
+      const result = await findRecentChompVaultDeposit({
+        fromBlock: FROM_BLOCK,
+        messenger: buildMessenger(),
+        moneyAccountAddress: MONEY_ACCOUNT_ADDRESS,
+        sourceAmountRaw: SOURCE_AMOUNT_RAW,
+      });
+
+      expect(result).toBe(newerHash);
+      expect(rpcRequestMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('skips logs with insufficient amount and returns the first sufficient one', async () => {
+      const insufficientHash =
+        '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex;
+
+      rpcRequestMock.mockResolvedValueOnce([
+        buildMusdTransferLog(insufficientHash, TRANSFER_DATA_INSUFFICIENT),
+        buildMusdTransferLog(CHOMP_TX_HASH),
+      ]);
+
+      const result = await findRecentChompVaultDeposit({
+        fromBlock: FROM_BLOCK,
+        messenger: buildMessenger(),
+        moneyAccountAddress: MONEY_ACCOUNT_ADDRESS,
+        sourceAmountRaw: SOURCE_AMOUNT_RAW,
+      });
+
+      // Logs reversed: CHOMP_TX_HASH checked first (newer), passes amount check.
+      expect(result).toBe(CHOMP_TX_HASH);
+      expect(rpcRequestMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('treats a log with data "0x" as zero amount and skips it', async () => {
+      rpcRequestMock.mockResolvedValueOnce([
+        buildMusdTransferLog(CHOMP_TX_HASH, '0x'),
+      ]);
+
+      const result = await findRecentChompVaultDeposit({
+        fromBlock: FROM_BLOCK,
+        messenger: buildMessenger(),
+        moneyAccountAddress: MONEY_ACCOUNT_ADDRESS,
+        sourceAmountRaw: SOURCE_AMOUNT_RAW,
+      });
+
+      expect(result).toBeUndefined();
+    });
+  });
+});

packages/transaction-pay-controller/src/strategy/fiat/chomp.ts

@@ -0,0 +1,86 @@
+import type { Hex } from '@metamask/utils';
+import { createModuleLogger } from '@metamask/utils';
+
+import { CHAIN_ID_MONAD, MUSD_MONAD_ADDRESS } from '../../constants';
+import { projectLogger } from '../../logger';
+import type { TransactionPayControllerMessenger } from '../../types';
+import { rpcRequest } from '../../utils/provider';
+
+const log = createModuleLogger(projectLogger, 'chomp');
+
+/** keccak256('Transfer(address,address,uint256)') */
+const ERC20_TRANSFER_TOPIC =
+  '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef';
+
+type RpcLog = {
+  address: string;
+  topics: string[];
+  data: string;
+  transactionHash: Hex;
+};
+
+export async function findRecentChompVaultDeposit({
+  messenger,
+  moneyAccountAddress,
+  sourceAmountRaw,
+  fromBlock,
+}: {
+  messenger: TransactionPayControllerMessenger;
+  moneyAccountAddress: Hex;
+  sourceAmountRaw: string;
+  fromBlock: Hex;
+}): Promise<Hex | undefined> {
+  const fromPadded = padAddress(moneyAccountAddress);
+
+  const logs = await rpcRequest<RpcLog[]>({
+    messenger,
+    chainId: CHAIN_ID_MONAD,
+    method: 'eth_getLogs',
+    params: [
+      {
+        address: MUSD_MONAD_ADDRESS,
+        fromBlock,
+        toBlock: 'latest',
+        topics: [ERC20_TRANSFER_TOPIC, fromPadded, null],
+      },
+    ],
+  });
+
+  log('CHOMP scan: mUSD Transfer logs found', {
+    count: logs.length,
+    fromBlock,
+    moneyAccountAddress,
+  });
+
+  const requiredAmount = BigInt(sourceAmountRaw);
+
+  // Examine newest logs first so we return the most recent CHOMP match.
+  for (const txLog of [...logs].reverse()) {
+    const transferAmount = BigInt(txLog.data === '0x' ? '0x0' : txLog.data);
+
+    if (transferAmount < requiredAmount) {
+      log('CHOMP scan: skipping log — transfer amount below required', {
+        requiredAmount: requiredAmount.toString(),
+        transferAmount: transferAmount.toString(),
+        txHash: txLog.transactionHash,
+      });
+      continue;
+    }
+
+    log('CHOMP scan: match found', {
+      moneyAccountAddress,
+      sourceAmountRaw,
+      transferAmount: transferAmount.toString(),
+      txHash: txLog.transactionHash,
+    });
+
+    return txLog.transactionHash;
+  }
+
+  log('CHOMP scan: no match found', { fromBlock, moneyAccountAddress });
+  return undefined;
+}
+
+function padAddress(address: Hex): string {
+  return `0x${address.replace(/^0x/u, '').toLowerCase().padStart(64, '0')}`;
+}