feat: MUSD-248 create money-account-balance-service

.github/CODEOWNERS

@@ -39,6 +39,7 @@
 
 ## Earn Team
 /packages/earn-controller                   @MetaMask/earn
+/packages/money-account-balance-service     @MetaMask/earn
 
 ## Social AI Team
 /packages/ai-controllers                    @MetaMask/social-ai
@@ -146,6 +147,8 @@
 /packages/delegation-controller/CHANGELOG.md      @MetaMask/delegation @MetaMask/core-platform
 /packages/earn-controller/package.json            @MetaMask/earn @MetaMask/core-platform
 /packages/earn-controller/CHANGELOG.md            @MetaMask/earn @MetaMask/core-platform
+/packages/money-account-balance-service/package.json @MetaMask/earn @MetaMask/core-platform
+/packages/money-account-balance-service/CHANGELOG.md @MetaMask/earn @MetaMask/core-platform
 /packages/eip-5792-middleware/package.json        @MetaMask/wallet-integrations @MetaMask/core-platform
 /packages/eip-5792-middleware/CHANGELOG.md        @MetaMask/wallet-integrations @MetaMask/core-platform
 /packages/eip1193-permission-middleware/package.json @MetaMask/wallet-integrations @MetaMask/core-platform

README.md

@@ -65,6 +65,7 @@ Each package in this repository has its own README where you can find installati
 - [`@metamask/message-manager`](packages/message-manager)
 - [`@metamask/messenger`](packages/messenger)
 - [`@metamask/messenger-cli`](packages/messenger-cli)
+- [`@metamask/money-account-balance-service`](packages/money-account-balance-service)
 - [`@metamask/money-account-controller`](packages/money-account-controller)
 - [`@metamask/multichain-account-service`](packages/multichain-account-service)
 - [`@metamask/multichain-api-middleware`](packages/multichain-api-middleware)
@@ -151,6 +152,7 @@ linkStyle default opacity:0.5
   message_manager(["@metamask/message-manager"]);
   messenger(["@metamask/messenger"]);
   messenger_cli(["@metamask/messenger-cli"]);
+  money_account_balance_service(["@metamask/money-account-balance-service"]);
   money_account_controller(["@metamask/money-account-controller"]);
   multichain_account_service(["@metamask/multichain-account-service"]);
   multichain_api_middleware(["@metamask/multichain-api-middleware"]);
@@ -350,6 +352,10 @@ linkStyle default opacity:0.5
   message_manager --> base_controller;
   message_manager --> controller_utils;
   message_manager --> messenger;
+  money_account_balance_service --> base_data_service;
+  money_account_balance_service --> controller_utils;
+  money_account_balance_service --> messenger;
+  money_account_balance_service --> network_controller;
   money_account_controller --> accounts_controller;
   money_account_controller --> base_controller;
   money_account_controller --> keyring_controller;

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

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Add `MoneyAccountBalanceService` data service ([#8428](https://github.com/MetaMask/core/pull/8428))
+  - Fetch mUSD ERC-20 balance via RPC (`getMusdBalance`)
+  - Fetch musdSHFvd vault share balance via RPC (`getMusdSHFvdBalance`)
+  - Fetch Veda Accountant exchange rate via RPC (`getExchangeRate`)
+  - Compute mUSD-equivalent value of vault share holdings (`getMusdEquivalentValue`)
+  - Fetch vault APY from the Veda performance REST API (`getVaultApy`)
+
+[Unreleased]: https://github.com/MetaMask/core/

packages/money-account-balance-service/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MetaMask
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,15 @@
+# `@metamask/money-account-balance-service`
+
+Data service for fetching Money account balances via on-chain RPC reads, the Veda Accountant exchange rate, and the Veda vault APY from Veda's REST API.
+
+## Installation
+
+`yarn add @metamask/money-account-balance-service`
+
+or
+
+`npm install @metamask/money-account-balance-service`
+
+## Contributing
+
+This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/core/blob/main/README.md).

packages/money-account-balance-service/jest.config.js

@@ -0,0 +1,24 @@
+/*
+ * For a detailed explanation regarding each configuration property and type check, visit:
+ * https://jestjs.io/docs/configuration
+ */
+
+const merge = require('deepmerge');
+const path = require('path');
+
+const baseConfig = require('../../jest.config.packages');
+
+const displayName = path.basename(__dirname);
+
+module.exports = merge(baseConfig, {
+  displayName,
+
+  coverageThreshold: {
+    global: {
+      branches: 100,
+      functions: 100,
+      lines: 100,
+      statements: 100,
+    },
+  },
+});

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

@@ -0,0 +1,82 @@
+{
+  "name": "@metamask/money-account-balance-service",
+  "version": "0.0.0",
+  "description": "Data service for fetching Money account balances, exchange rates, and vault APY",
+  "keywords": [
+    "Ethereum",
+    "MetaMask"
+  ],
+  "homepage": "https://github.com/MetaMask/core/tree/main/packages/money-account-balance-service#readme",
+  "bugs": {
+    "url": "https://github.com/MetaMask/core/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MetaMask/core.git"
+  },
+  "files": [
+    "dist/"
+  ],
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "ts-bridge --project tsconfig.build.json --verbose --clean --no-references",
+    "build:all": "ts-bridge --project tsconfig.build.json --verbose --clean",
+    "build:docs": "typedoc",
+    "changelog:update": "../../scripts/update-changelog.sh @metamask/money-account-balance-service",
+    "changelog:validate": "../../scripts/validate-changelog.sh @metamask/money-account-balance-service",
+    "messenger-action-types:check": "tsx ../../packages/messenger-cli/src/cli.ts --check",
+    "messenger-action-types:generate": "tsx ../../packages/messenger-cli/src/cli.ts --generate",
+    "since-latest-release": "../../scripts/since-latest-release.sh",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
+    "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",
+    "test:verbose": "NODE_OPTIONS=--experimental-vm-modules jest --verbose",
+    "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch"
+  },
+  "dependencies": {
+    "@ethersproject/contracts": "^5.7.0",
+    "@ethersproject/providers": "^5.7.0",
+    "@metamask/base-data-service": "^0.1.1",
+    "@metamask/controller-utils": "^11.20.0",
+    "@metamask/messenger": "^1.1.1",
+    "@metamask/metamask-eth-abis": "^3.1.1",
+    "@metamask/network-controller": "^30.0.1",
+    "@metamask/superstruct": "^3.1.0",
+    "@metamask/utils": "^11.9.0"
+  },
+  "devDependencies": {
+    "@metamask/auto-changelog": "^6.0.0",
+    "@ts-bridge/cli": "^0.6.4",
+    "@types/jest": "^29.5.14",
+    "deepmerge": "^4.2.2",
+    "jest": "^29.7.0",
+    "nock": "^13.3.1",
+    "ts-jest": "^29.2.5",
+    "tsx": "^4.20.5",
+    "typedoc": "^0.25.13",
+    "typedoc-plugin-missing-exports": "^2.0.0",
+    "typescript": "~5.3.3"
+  },
+  "engines": {
+    "node": "^18.18 || >=20"
+  }
+}

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

@@ -0,0 +1,24 @@
+import { Hex } from '@metamask/utils';
+
+export const VEDA_PERFORMANCE_API_BASE_URL = 'https://api.sevenseas.capital';
+
+export const VEDA_API_NETWORK_NAMES: Record<Hex, string> = {
+  '0xa4b1': 'arbitrum',
+};
+
+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.
+ */
+export const ACCOUNTANT_ABI = [
+  {
+    inputs: [],
+    name: 'getRate',
+    outputs: [{ internalType: 'uint256', name: 'rate', type: 'uint256' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+] as const;

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

@@ -0,0 +1,6 @@
+export class VedaResponseValidationError extends Error {
+  constructor(message?: string) {
+    super(message ?? 'Malformed response received from Veda API');
+    this.name = 'VedaResponseValidationError';
+  }
+}

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

@@ -0,0 +1,18 @@
+export { MoneyAccountBalanceService } from './money-account-balance-service';
+export type {
+  MoneyAccountBalanceServiceActions,
+  MoneyAccountBalanceServiceEvents,
+  MoneyAccountBalanceServiceMessenger,
+} from './money-account-balance-service';
+export type {
+  MoneyAccountBalanceServiceGetMusdBalanceAction,
+  MoneyAccountBalanceServiceGetMusdSHFvdBalanceAction,
+  MoneyAccountBalanceServiceGetExchangeRateAction,
+  MoneyAccountBalanceServiceGetMusdEquivalentValueAction,
+  MoneyAccountBalanceServiceGetVaultApyAction,
+} from './money-account-balance-service-method-action-types';
+export type {
+  ExchangeRateResponse,
+  MusdEquivalentValueResponse,
+  NormalizedVaultApyResponse,
+} from './response.types';

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

@@ -0,0 +1,78 @@
+/**
+ * This file is auto generated.
+ * Do not edit manually.
+ */
+
+import type { MoneyAccountBalanceService } from './money-account-balance-service';
+
+/**
+ * Fetches the mUSD ERC-20 balance for the given account address via RPC.
+ *
+ * @param accountAddress - The Money account's Ethereum address.
+ * @returns The mUSD balance as a raw uint256 string.
+ */
+export type MoneyAccountBalanceServiceGetMusdBalanceAction = {
+  type: `MoneyAccountBalanceService:getMusdBalance`;
+  handler: MoneyAccountBalanceService['getMusdBalance'];
+};
+
+/**
+ * Fetches the musdSHFvd (Veda vault share) ERC-20 balance for the given
+ * account address via RPC.
+ *
+ * @param accountAddress - The Money account's Ethereum address.
+ * @returns The musdSHFvd balance as a raw uint256 string.
+ */
+export type MoneyAccountBalanceServiceGetMusdSHFvdBalanceAction = {
+  type: `MoneyAccountBalanceService:getMusdSHFvdBalance`;
+  handler: MoneyAccountBalanceService['getMusdSHFvdBalance'];
+};
+
+/**
+ * Fetches the current exchange rate from the Veda Accountant contract via
+ * RPC. The rate represents the conversion factor from musdSHFvd shares to
+ * the underlying mUSD asset.
+ *
+ * @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.
+ */
+export type MoneyAccountBalanceServiceGetExchangeRateAction = {
+  type: `MoneyAccountBalanceService:getExchangeRate`;
+  handler: MoneyAccountBalanceService['getExchangeRate'];
+};
+
+/**
+ * Computes the mUSD-equivalent value of the account's musdSHFvd holdings.
+ * Internally fetches the musdSHFvd balance and exchange rate (using cached
+ * values when available within their staleTime windows), then multiplies
+ * them.
+ *
+ * @param accountAddress - The Money account's Ethereum address.
+ * @returns The musdSHFvd balance, exchange rate, and computed
+ * mUSD-equivalent value as raw uint256 strings.
+ */
+export type MoneyAccountBalanceServiceGetMusdEquivalentValueAction = {
+  type: `MoneyAccountBalanceService:getMusdEquivalentValue`;
+  handler: MoneyAccountBalanceService['getMusdEquivalentValue'];
+};
+
+/**
+ * Fetches the vault's APY and fee breakdown from the Veda performance REST API.
+ *
+ * @returns The normalized vault APY response.
+ */
+export type MoneyAccountBalanceServiceGetVaultApyAction = {
+  type: `MoneyAccountBalanceService:getVaultApy`;
+  handler: MoneyAccountBalanceService['getVaultApy'];
+};
+
+/**
+ * Union of all MoneyAccountBalanceService action types.
+ */
+export type MoneyAccountBalanceServiceMethodActions =
+  | MoneyAccountBalanceServiceGetMusdBalanceAction
+  | MoneyAccountBalanceServiceGetMusdSHFvdBalanceAction
+  | MoneyAccountBalanceServiceGetExchangeRateAction
+  | MoneyAccountBalanceServiceGetMusdEquivalentValueAction
+  | MoneyAccountBalanceServiceGetVaultApyAction;