feat: MUSD-681: (money-account-balance-service) replace constructor config with remote feature flag subscription (MetaMask#8742)

## Explanation

<!--
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?
-->

This PR updates the `@metamask/money-account-balance-service` to use a
remote vault config instead of constructor args.

## 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
-->

- [MUSD-681: Support remote vault config feature flag in Money Balance
Service](https://consensyssoftware.atlassian.net/browse/MUSD-681)

## Checklist

- [ ] I've updated the test suite for new or updated code as appropriate
- [ ] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [ ] 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]
> **Medium Risk**
> Breaking API changes shift vault configuration from constructor args
to `RemoteFeatureFlagController` state and alter response shapes, which
can break consumers and affect balance/APY lookups until flags are
available. Runtime behavior now depends on async flag delivery and
validation, adding new error paths and cache invalidation logic.
> 
> **Overview**
> Refactors `MoneyAccountBalanceService` to **stop taking vault config
in the constructor** and instead `init()`/subscribe to
`RemoteFeatureFlagController` (`getState` + `stateChange`) for a remote
`moneyAccountVaultConfig`, throwing `VaultConfigNotAvailableError` until
a valid config is present and routing malformed configs via
`VaultConfigValidationError`.
> 
> Updates on-chain/API fetching to use the new config shape
(`boringVault`, `chainId`, `lensAddress`, `tellerAddress`, etc.),
including switching `getMusdEquivalentValue` to call the Lens contract’s
`balanceOfInAssets` and tightening `getVaultApy` to error when the chain
ID lacks a `VEDA_API_NETWORK_NAMES` mapping (adds Monad). Adds
corresponding structs/types, logging, exports, dependency on
`@metamask/remote-feature-flag-controller`, and extensive test coverage
for config lifecycle and cache invalidation.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
5e603a6. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: Matt561

README.md

@@ -375,6 +375,7 @@ linkStyle default opacity:0.5
   money_account_balance_service --> controller_utils;
   money_account_balance_service --> messenger;
   money_account_balance_service --> network_controller;
+  money_account_balance_service --> remote_feature_flag_controller;
   money_account_controller --> accounts_controller;
   money_account_controller --> base_controller;
   money_account_controller --> keyring_controller;

packages/money-account-balance-service/CHANGELOG.md

@@ -7,8 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `VaultConfigNotAvailableError` and `VaultConfigValidationError` error classes for typed consumer error handling ([#8742](https://github.com/MetaMask/core/pull/8742))
+- Add `LENS_ABI` constant for the Arctic Architecture Lens contract ([#8742](https://github.com/MetaMask/core/pull/8742))
+
 ### Changed
 
+- **BREAKING:** `MoneyAccountBalanceService` no longer accepts vault config via constructor. Vault config is now read from `RemoteFeatureFlagController` state. Add `@metamask/remote-feature-flag-controller` as a dependency and permit `RemoteFeatureFlagController:getState`action and `RemoteFeatureFlagController:stateChange` event on the service's messenger. Service methods throw `VaultConfigNotAvailableError` until a valid config is available. ([#8742](https://github.com/MetaMask/core/pull/8742))
+- **BREAKING:** `VaultConfig` fields have changed — `vaultAddress` → `boringVault`, `vaultChainId` → `chainId`; `underlyingTokenAddress` and `underlyingTokenDecimals` removed; `lensAddress` and `tellerAddress` added ([#8742](https://github.com/MetaMask/core/pull/8742))
+- **BREAKING:** `MusdEquivalentValueResponse` shape has changed — `musdSHFvdBalance`, `exchangeRate`, and `musdEquivalentValue` replaced by a single `balanceOfInAssets` field ([#8742](https://github.com/MetaMask/core/pull/8742))
+- Monad (`0x8f`) added to `VEDA_API_NETWORK_NAMES` ([#8742](https://github.com/MetaMask/core/pull/8742))
 - Bump `@metamask/messenger` from `^1.1.1` to `^1.2.0` ([#8632](https://github.com/MetaMask/core/pull/8632))
 - Bump `@metamask/network-controller` from `^30.0.1` to `^30.1.0` ([#8636](https://github.com/MetaMask/core/pull/8636))
 

packages/money-account-balance-service/package.json

@@ -60,6 +60,7 @@
     "@metamask/messenger": "^1.2.0",
     "@metamask/metamask-eth-abis": "^3.1.1",
     "@metamask/network-controller": "^30.1.0",
+    "@metamask/remote-feature-flag-controller": "^4.2.0",
     "@metamask/superstruct": "^3.1.0",
     "@metamask/utils": "^11.9.0"
   },

packages/money-account-balance-service/src/constants.ts

@@ -2,18 +2,31 @@ import { Hex } from '@metamask/utils';
 
 export const VEDA_PERFORMANCE_API_BASE_URL = 'https://api.sevenseas.capital';
 
+/**
+ * The key under which vault config is stored in
+ * `RemoteFeatureFlagController` state's `remoteFeatureFlags` map.
+ */
+export const VAULT_CONFIG_FEATURE_FLAG_KEY = 'moneyAccountVaultConfig';
+
 export const VEDA_API_NETWORK_NAMES: Record<Hex, string> = {
   '0xa4b1': 'arbitrum',
+  '0x8f': 'monad',
 };
 
-export const DEFAULT_VEDA_API_NETWORK_NAME = VEDA_API_NETWORK_NAMES['0xa4b1'];
-
 /**
- * Minimal ABI for the Veda Accountant's `getRate()` function (selector 0x679aefce).
- * Returns the exchange rate between vault shares (musdSHFvd) and the
- * underlying asset (mUSD) as a uint256.
+ * Minimal ABI for the Veda Accountant contract. Covers:
+ *  - base    (0x5001f3b5) — the underlying ERC20 base asset address
+ *  - getRate (0x679aefce) — exchange rate between vault shares and the
+ *                           underlying asset (mUSD) as a uint256
  */
 export const ACCOUNTANT_ABI = [
+  {
+    inputs: [],
+    name: 'base',
+    outputs: [{ internalType: 'contract ERC20', name: '', type: 'address' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
   {
     inputs: [],
     name: 'getRate',
@@ -22,3 +35,33 @@ export const ACCOUNTANT_ABI = [
     type: 'function',
   },
 ] as const;
+
+/**
+ * Minimal ABI for the Arctic Architecture Lens contract.
+ * Covers:
+ *  - balanceOf        (0xf7888aec) — shares held by an account in a BoringVault
+ *  - balanceOfInAssets (0x789fd871) — share balance denominated in underlying assets
+ */
+export const LENS_ABI = [
+  {
+    inputs: [
+      { name: 'account', type: 'address' },
+      { name: 'boringVault', type: 'address' },
+    ],
+    name: 'balanceOf',
+    outputs: [{ name: 'shares', type: 'uint256' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [
+      { name: 'account', type: 'address' },
+      { name: 'boringVault', type: 'address' },
+      { name: 'accountant', type: 'address' },
+    ],
+    name: 'balanceOfInAssets',
+    outputs: [{ name: 'assets', type: 'uint256' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+] as const;

packages/money-account-balance-service/src/errors.ts

@@ -4,3 +4,34 @@ export class VedaResponseValidationError extends Error {
     this.name = 'VedaResponseValidationError';
   }
 }
+
+/**
+ * Thrown when a public method is called but vault config has not yet been
+ * loaded from RemoteFeatureFlagController, or the flag key is absent.
+ * This is a transient condition — the service will recover once flags are
+ * fetched and a valid config arrives.
+ */
+export class VaultConfigNotAvailableError extends Error {
+  constructor() {
+    super(
+      'MoneyAccountBalanceService: vault config is not available. ' +
+        'RemoteFeatureFlagController may not have fetched flags yet.',
+    );
+    this.name = 'VaultConfigNotAvailableError';
+  }
+}
+
+/**
+ * Thrown when the vault config flag value is present but fails superstruct
+ * validation. This surfaces to error monitoring service (e.g. Sentry) via the messenger's captureException
+ * handler.
+ */
+export class VaultConfigValidationError extends Error {
+  constructor(message?: string) {
+    super(
+      message ??
+        'MoneyAccountBalanceService: vault config from remote feature flags is malformed.',
+    );
+    this.name = 'VaultConfigValidationError';
+  }
+}

packages/money-account-balance-service/src/index.ts

@@ -16,3 +16,8 @@ export type {
   MusdEquivalentValueResponse,
   NormalizedVaultApyResponse,
 } from './response.types';
+export {
+  VaultConfigNotAvailableError,
+  VaultConfigValidationError,
+} from './errors';
+export type { VaultConfig } from './types';

packages/money-account-balance-service/src/logger.ts

@@ -0,0 +1,7 @@
+import { createProjectLogger, createModuleLogger } from '@metamask/utils';
+
+export const projectLogger = createProjectLogger(
+  'money-account-balance-service',
+);
+
+export { createModuleLogger };

packages/money-account-balance-service/src/money-account-balance-service-method-action-types.ts

@@ -10,6 +10,7 @@ import type { MoneyAccountBalanceService } from './money-account-balance-service
  *
  * @param accountAddress - The Money account's Ethereum address.
  * @returns The mUSD balance as a raw uint256 string.
+ * @throws {@link VaultConfigNotAvailableError} if vault config has not been loaded.
  */
 export type MoneyAccountBalanceServiceGetMusdBalanceAction = {
   type: `MoneyAccountBalanceService:getMusdBalance`;
@@ -22,6 +23,7 @@ export type MoneyAccountBalanceServiceGetMusdBalanceAction = {
  *
  * @param accountAddress - The Money account's Ethereum address.
  * @returns The musdSHFvd balance as a raw uint256 string.
+ * @throws {@link VaultConfigNotAvailableError} if vault config has not been loaded.
  */
 export type MoneyAccountBalanceServiceGetMusdSHFvdBalanceAction = {
   type: `MoneyAccountBalanceService:getMusdSHFvdBalance`;
@@ -36,6 +38,7 @@ export type MoneyAccountBalanceServiceGetMusdSHFvdBalanceAction = {
  * @param options - The options for the query.
  * @param options.staleTime - The stale time for the query. Defaults to 30 seconds.
  * @returns The exchange rate as a raw uint256 string.
+ * @throws {@link VaultConfigNotAvailableError} if vault config has not been loaded.
  */
 export type MoneyAccountBalanceServiceGetExchangeRateAction = {
   type: `MoneyAccountBalanceService:getExchangeRate`;
@@ -51,6 +54,7 @@ export type MoneyAccountBalanceServiceGetExchangeRateAction = {
  * @param accountAddress - The Money account's Ethereum address.
  * @returns The musdSHFvd balance, exchange rate, and computed
  * mUSD-equivalent value as raw uint256 strings.
+ * @throws {@link VaultConfigNotAvailableError} if vault config has not been loaded.
  */
 export type MoneyAccountBalanceServiceGetMusdEquivalentValueAction = {
   type: `MoneyAccountBalanceService:getMusdEquivalentValue`;
@@ -61,6 +65,7 @@ export type MoneyAccountBalanceServiceGetMusdEquivalentValueAction = {
  * Fetches the vault's APY and fee breakdown from the Veda performance REST API.
  *
  * @returns The normalized vault APY response.
+ * @throws {@link VaultConfigNotAvailableError} if vault config has not been loaded.
  */
 export type MoneyAccountBalanceServiceGetVaultApyAction = {
   type: `MoneyAccountBalanceService:getVaultApy`;