feat: expose more info about chomp upgrade step failures (MetaMask#9204)

## Explanation
When the upgrade process throws an error, include the step where the
error occurred in what is thrown. This will allow client applications to
report errors more effectively.
<!--
Thanks for your contribution! Take a moment to answer these questions so
that reviewers have the information they need to properly understand
your changes:

* What is the current state of things and why does it need to change?
* What is the solution your changes offer and how does it work?
* Are there any changes whose purpose might not obvious to those
unfamiliar with the domain?
* If your primary goal was to update one package but you found you had
to update another one along the way, why did you do so?
* If you had to upgrade a dependency, why did you do so?
-->

## References

<!--
Are there any issues that this pull request is tied to?
Are there other links that reviewers should consult to understand these
changes better?
Are there client or consumer pull requests to adopt any breaking
changes?

For example:

* Fixes #12345
* Related to #67890
-->

## 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)
- [ ] 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

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Only changes error propagation on the failure path; upgrade sequencing
and success behavior are unchanged.
> 
> **Overview**
> **`upgradeAccount`** now catches failures from any upgrade step and
re-throws them as **`MoneyAccountUpgradeStepError`**, with **`step`**
set to that step’s `name` and the original value kept on **`cause`**.
The public message still includes the underlying text (from
`Error.message` or `String(cause)`).
> 
> The package adds **`MoneyAccountUpgradeStepError`**,
**`isMoneyAccountUpgradeStepError`** (structural guard for bundled
apps), unit/integration tests, changelog notes, and updated JSDoc for
the messenger action type.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
d66b594. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: Jwhiles

packages/money-account-upgrade-controller/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `MoneyAccountUpgradeStepError` (and the `isMoneyAccountUpgradeStepError` type guard). `upgradeAccount` now wraps any error thrown by a step in this error, exposing the failing step's `name` as `step` and preserving the original error as `cause`, so consumers can attribute failures to a specific step when reporting to Sentry). ([#9204](https://github.com/MetaMask/core/pull/9204))
+
 ### Changed
 
 - Bump `@metamask/keyring-controller` from `^27.0.0` to `^27.1.0` ([#9129](https://github.com/MetaMask/core/pull/9129))

packages/money-account-upgrade-controller/src/MoneyAccountUpgradeController-method-action-types.ts

@@ -9,7 +9,9 @@ import type { MoneyAccountUpgradeController } from './MoneyAccountUpgradeControl
  * Runs each step in the upgrade sequence in order. A step that reports
  * `'already-done'` is skipped without performing any action; a step that
  * reports `'completed'` has performed its action. An error thrown by any
- * step propagates and halts the sequence.
+ * step halts the sequence and is re-thrown wrapped in a
+ * {@link MoneyAccountUpgradeStepError} that records which step failed (the
+ * original error is preserved as `cause`).
  *
  * @param address - The Money Account address to upgrade.
  */

packages/money-account-upgrade-controller/src/MoneyAccountUpgradeController.test.ts

@@ -8,8 +8,14 @@ import type {
 import { hexToNumber } from '@metamask/utils';
 import type { Hex } from '@metamask/utils';
 
-import type { MoneyAccountUpgradeControllerMessenger } from '.';
-import { MoneyAccountUpgradeController } from '.';
+import type {
+  MoneyAccountUpgradeControllerMessenger,
+  MoneyAccountUpgradeStepError,
+} from '.';
+import {
+  MoneyAccountUpgradeController,
+  isMoneyAccountUpgradeStepError,
+} from '.';
 
 const MOCK_CHAIN_ID = '0x1' as Hex; // mainnet, supported in delegation-deployments@1.3.0
 const UNSUPPORTED_CHAIN_ID = '0x539' as Hex; // 1337 — local dev, not in registry
@@ -438,5 +444,70 @@ describe('MoneyAccountUpgradeController', () => {
         controller.upgradeAccount(MOCK_ACCOUNT_ADDRESS),
       ).rejects.toThrow('signing failed');
     });
+
+    it('wraps a step failure in a MoneyAccountUpgradeStepError that records the step and cause', async () => {
+      const { controller, mocks } = setup();
+      await controller.init({
+        chainId: MOCK_CHAIN_ID,
+        boringVaultAddress: MOCK_BORING_VAULT_ADDRESS,
+      });
+      const cause = new Error('signing failed');
+      // The associate-address step (first in the sequence) signs a personal
+      // message before calling CHOMP, so failing this surfaces that step.
+      mocks.signPersonalMessage.mockRejectedValue(cause);
+
+      const error = await controller
+        .upgradeAccount(MOCK_ACCOUNT_ADDRESS)
+        .catch((thrown: unknown) => thrown);
+
+      expect(isMoneyAccountUpgradeStepError(error)).toBe(true);
+      expect(error).toMatchObject({
+        step: 'associate-address',
+        cause,
+      });
+      expect((error as MoneyAccountUpgradeStepError).message).toBe(
+        'Money Account upgrade failed at step "associate-address": signing failed',
+      );
+    });
+
+    it('records the name of the specific step that failed', async () => {
+      const { controller, mocks } = setup();
+      await controller.init({
+        chainId: MOCK_CHAIN_ID,
+        boringVaultAddress: MOCK_BORING_VAULT_ADDRESS,
+      });
+      // The first step (associate-address) passes; fail at the second step
+      // (eip-7702-authorization), which signs the authorization.
+      mocks.signEip7702Authorization.mockRejectedValue(
+        new Error('authorization rejected'),
+      );
+
+      const error = await controller
+        .upgradeAccount(MOCK_ACCOUNT_ADDRESS)
+        .catch((thrown: unknown) => thrown);
+
+      expect(error).toMatchObject({ step: 'eip-7702-authorization' });
+    });
+
+    it('wraps a non-Error thrown by a step, stringifying it as the cause message', async () => {
+      const { controller, mocks } = setup();
+      await controller.init({
+        chainId: MOCK_CHAIN_ID,
+        boringVaultAddress: MOCK_BORING_VAULT_ADDRESS,
+      });
+      mocks.signPersonalMessage.mockRejectedValue('plain string failure');
+
+      const error = await controller
+        .upgradeAccount(MOCK_ACCOUNT_ADDRESS)
+        .catch((thrown: unknown) => thrown);
+
+      expect(error).toMatchObject({
+        step: 'associate-address',
+        cause: 'plain string failure',
+      });
+      expect((error as MoneyAccountUpgradeStepError).message).toBe(
+        'Money Account upgrade failed at step "associate-address": plain string failure',
+      );
+    });
   });
 });

packages/money-account-upgrade-controller/src/MoneyAccountUpgradeController.ts

@@ -30,6 +30,7 @@ import type {
 import { hexToNumber } from '@metamask/utils';
 import type { Hex } from '@metamask/utils';
 
+import { MoneyAccountUpgradeStepError } from './errors';
 import type { MoneyAccountUpgradeControllerMethodActions } from './MoneyAccountUpgradeController-method-action-types';
 import { associateAddressStep } from './steps/associate-address';
 import { buildDelegationStep } from './steps/build-delegations';
@@ -203,7 +204,9 @@ export class MoneyAccountUpgradeController extends BaseController<
    * Runs each step in the upgrade sequence in order. A step that reports
    * `'already-done'` is skipped without performing any action; a step that
    * reports `'completed'` has performed its action. An error thrown by any
-   * step propagates and halts the sequence.
+   * step halts the sequence and is re-thrown wrapped in a
+   * {@link MoneyAccountUpgradeStepError} that records which step failed (the
+   * original error is preserved as `cause`).
    *
    * @param address - The Money Account address to upgrade.
    */
@@ -215,11 +218,15 @@ export class MoneyAccountUpgradeController extends BaseController<
     }
 
     for (const step of this.#steps) {
-      await step.run({
-        messenger: this.messenger,
-        address,
-        ...this.#config,
-      });
+      try {
+        await step.run({
+          messenger: this.messenger,
+          address,
+          ...this.#config,
+        });
+      } catch (error) {
+        throw new MoneyAccountUpgradeStepError(step.name, error);
+      }
     }
   }
 }

packages/money-account-upgrade-controller/src/errors.test.ts

@@ -0,0 +1,65 @@
+import {
+  MoneyAccountUpgradeStepError,
+  isMoneyAccountUpgradeStepError,
+} from './errors';
+
+describe('MoneyAccountUpgradeStepError', () => {
+  it('records the step name and preserves an Error cause', () => {
+    const cause = new Error('boom');
+
+    const error = new MoneyAccountUpgradeStepError('build-delegation', cause);
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error.name).toBe('MoneyAccountUpgradeStepError');
+    expect(error.step).toBe('build-delegation');
+    expect(error.cause).toBe(cause);
+    expect(error.message).toBe(
+      'Money Account upgrade failed at step "build-delegation": boom',
+    );
+  });
+
+  it('stringifies a non-Error cause in the message', () => {
+    const error = new MoneyAccountUpgradeStepError('register-intents', 42);
+
+    expect(error.cause).toBe(42);
+    expect(error.message).toBe(
+      'Money Account upgrade failed at step "register-intents": 42',
+    );
+  });
+});
+
+describe('isMoneyAccountUpgradeStepError', () => {
+  it('returns true for a MoneyAccountUpgradeStepError', () => {
+    expect(
+      isMoneyAccountUpgradeStepError(
+        new MoneyAccountUpgradeStepError('associate-address', new Error('x')),
+      ),
+    ).toBe(true);
+  });
+
+  it('returns true for a structurally-equivalent error from another realm', () => {
+    const lookalike = new Error('whatever');
+    lookalike.name = 'MoneyAccountUpgradeStepError';
+    (lookalike as unknown as { step: string }).step = 'associate-address';
+
+    expect(isMoneyAccountUpgradeStepError(lookalike)).toBe(true);
+  });
+
+  it('returns false for a plain Error', () => {
+    expect(isMoneyAccountUpgradeStepError(new Error('nope'))).toBe(false);
+  });
+
+  it('returns false for an error with the right name but no step', () => {
+    const error = new Error('nope');
+    error.name = 'MoneyAccountUpgradeStepError';
+
+    expect(isMoneyAccountUpgradeStepError(error)).toBe(false);
+  });
+
+  it('returns false for non-error values', () => {
+    expect(isMoneyAccountUpgradeStepError(undefined)).toBe(false);
+    expect(isMoneyAccountUpgradeStepError(null)).toBe(false);
+    expect(isMoneyAccountUpgradeStepError('error')).toBe(false);
+    expect(isMoneyAccountUpgradeStepError({ step: 'x' })).toBe(false);
+  });
+});

packages/money-account-upgrade-controller/src/errors.ts

@@ -0,0 +1,45 @@
+/**
+ * Error thrown by `MoneyAccountUpgradeController.upgradeAccount` when one of
+ * the upgrade steps fails.
+ *
+ * Wraps the underlying error (preserved as `cause`) and records the name of
+ * the step that was running, so consumers can attribute the failure to a
+ * specific step — e.g. when tagging an error report — without parsing the
+ * message.
+ */
+export class MoneyAccountUpgradeStepError extends Error {
+  /** The name of the step that threw. */
+  readonly step: string;
+
+  /** The underlying error thrown by the step. */
+  readonly cause: unknown;
+
+  constructor(step: string, cause: unknown) {
+    const causeMessage = cause instanceof Error ? cause.message : String(cause);
+    super(`Money Account upgrade failed at step "${step}": ${causeMessage}`);
+
+    this.name = 'MoneyAccountUpgradeStepError';
+    this.step = step;
+    this.cause = cause;
+  }
+}
+
+/**
+ * Type guard for {@link MoneyAccountUpgradeStepError}.
+ *
+ * Uses a structural check rather than `instanceof` so it holds across module
+ * realm boundaries — e.g. when the controller is consumed from a bundled host
+ * app where a duplicate copy of this class may exist.
+ *
+ * @param error - The value to test.
+ * @returns Whether `error` is a `MoneyAccountUpgradeStepError`.
+ */
+export function isMoneyAccountUpgradeStepError(
+  error: unknown,
+): error is MoneyAccountUpgradeStepError {
+  return (
+    error instanceof Error &&
+    error.name === 'MoneyAccountUpgradeStepError' &&
+    typeof (error as { step?: unknown }).step === 'string'
+  );
+}

packages/money-account-upgrade-controller/src/index.ts

@@ -1,4 +1,8 @@
 export type { UpgradeConfig } from './types';
+export {
+  MoneyAccountUpgradeStepError,
+  isMoneyAccountUpgradeStepError,
+} from './errors';
 export { MoneyAccountUpgradeController } from './MoneyAccountUpgradeController';
 export type {
   MoneyAccountUpgradeControllerState,