feat(wallet): Add split persistence backed by better-sqlite3

package.json

@@ -113,7 +113,8 @@
       "babel-runtime>core-js": false,
       "simple-git-hooks": false,
       "tsx>esbuild": false,
-      "eslint-plugin-import-x>unrs-resolver": false
+      "eslint-plugin-import-x>unrs-resolver": false,
+      "better-sqlite3": true
     }
   }
 }

packages/wallet/README.md

@@ -10,6 +10,16 @@ or
 
 `npm install @metamask/wallet`
 
+## Troubleshooting
+
+### Rebuilding `better-sqlite3`
+
+This package depends on `better-sqlite3`, which includes a native C addon. The prebuilt binary is downloaded automatically during `yarn install`. If you switch Node versions or branches and the binding is missing, rebuild it with:
+
+```sh
+cd node_modules/better-sqlite3 && npx prebuild-install
+```
+
 ## Contributing
 
 This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/core#readme).

packages/wallet/package.json

@@ -32,6 +32,16 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./persistence": {
+      "import": {
+        "types": "./dist/persistence/index.d.mts",
+        "default": "./dist/persistence/index.mjs"
+      },
+      "require": {
+        "types": "./dist/persistence/index.d.cts",
+        "default": "./dist/persistence/index.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -47,7 +57,7 @@
     "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:prepare": "./scripts/install-anvil.sh",
+    "test:prepare": "./scripts/install-binaries.sh",
     "test": "yarn test:prepare && 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",
@@ -65,12 +75,14 @@
     "@metamask/remote-feature-flag-controller": "^4.2.0",
     "@metamask/scure-bip39": "^2.1.1",
     "@metamask/transaction-controller": "^64.3.0",
-    "@metamask/utils": "^11.9.0"
+    "@metamask/utils": "^11.9.0",
+    "better-sqlite3": "^12.9.0"
   },
   "devDependencies": {
     "@metamask/auto-changelog": "^6.1.0",
     "@metamask/foundryup": "^1.0.1",
     "@ts-bridge/cli": "^0.6.4",
+    "@types/better-sqlite3": "^7.6.13",
     "@types/jest": "^29.5.14",
     "deepmerge": "^4.2.2",
     "jest": "^29.7.0",

packages/wallet/scripts/install-binaries.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+
+set -e
+set -o pipefail
+
+# Pin cwd to the package root so all paths are predictable regardless of how
+# this script is invoked. Also derive the monorepo root (two levels up).
+PACKAGE_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+MONOREPO_ROOT="$(cd "${PACKAGE_ROOT}/../.." && pwd)"
+cd "${PACKAGE_ROOT}"
+
+# Run foundryup's TypeScript entry point directly via tsx. This avoids having
+# to build @metamask/foundryup first, which matters in CI where workspace deps
+# aren't built before tests run.
+if ! output=$(yarn tsx ../foundryup/src/cli.ts --binaries anvil 2>&1); then
+  echo "$output" >&2
+  exit 1
+fi
+
+# Install the better-sqlite3 native addon if missing. Yarn has
+# `enableScripts: false` globally, so install scripts never run during
+# `yarn install` and the addon may be absent from the filesystem. Invoke the
+# prebuild-install binary directly to fetch a matching prebuild for the active
+# Node version and platform.
+BETTER_SQLITE3_DIR="${MONOREPO_ROOT}/node_modules/better-sqlite3"
+if [ ! -f "${BETTER_SQLITE3_DIR}/build/Release/better_sqlite3.node" ]; then
+  (
+    cd "${BETTER_SQLITE3_DIR}"
+    "${MONOREPO_ROOT}/node_modules/.bin/prebuild-install"
+  )
+fi

packages/wallet/src/Wallet.test.ts

@@ -5,10 +5,12 @@ import {
   DistributionType,
   EnvironmentType,
 } from '@metamask/remote-feature-flag-controller';
+import { TransactionController } from '@metamask/transaction-controller';
 import { enableNetConnect } from 'nock';
 
 import { startAnvil } from '../test/anvil';
 import type { AnvilInstance } from '../test/anvil';
+import * as initializationModule from './initialization';
 import {
   createSecretRecoveryPhrase,
   importSecretRecoveryPhrase,
@@ -22,20 +24,18 @@ const TEST_PASSWORD = 'testpass';
 
 async function setupWallet(): Promise<Wallet> {
   const wallet = new Wallet({
-    options: {
-      infuraProjectId: 'fake-infura-project-id',
-      clientVersion: '1.0.0',
-      showApprovalRequest: (): undefined => undefined,
-      clientConfigApiService: new ClientConfigApiService({
-        fetch: globalThis.fetch,
-        config: {
-          client: ClientType.Extension,
-          distribution: DistributionType.Main,
-          environment: EnvironmentType.Production,
-        },
-      }),
-      getMetaMetricsId: (): string => 'fake-metrics-id',
-    },
+    infuraProjectId: 'fake-infura-project-id',
+    clientVersion: '1.0.0',
+    showApprovalRequest: (): undefined => undefined,
+    clientConfigApiService: new ClientConfigApiService({
+      fetch: globalThis.fetch,
+      config: {
+        client: ClientType.Extension,
+        distribution: DistributionType.Main,
+        environment: EnvironmentType.Production,
+      },
+    }),
+    getMetaMetricsId: (): string => 'fake-metrics-id',
   });
 
   await importSecretRecoveryPhrase(wallet, TEST_PASSWORD, TEST_PHRASE);
@@ -134,20 +134,18 @@ describe('Wallet', () => {
 
   it('can create secret recovery phrase', async () => {
     wallet = new Wallet({
-      options: {
-        infuraProjectId: 'fake-infura-project-id',
-        clientVersion: '1.0.0',
-        showApprovalRequest: (): undefined => undefined,
-        clientConfigApiService: new ClientConfigApiService({
-          fetch: globalThis.fetch,
-          config: {
-            client: ClientType.Extension,
-            distribution: DistributionType.Main,
-            environment: EnvironmentType.Production,
-          },
-        }),
-        getMetaMetricsId: (): string => 'fake-metrics-id',
-      },
+      infuraProjectId: 'fake-infura-project-id',
+      clientVersion: '1.0.0',
+      showApprovalRequest: (): undefined => undefined,
+      clientConfigApiService: new ClientConfigApiService({
+        fetch: globalThis.fetch,
+        config: {
+          client: ClientType.Extension,
+          distribution: DistributionType.Main,
+          environment: EnvironmentType.Production,
+        },
+      }),
+      getMetaMetricsId: (): string => 'fake-metrics-id',
     });
 
     await createSecretRecoveryPhrase(wallet, TEST_PASSWORD);
@@ -169,4 +167,90 @@ describe('Wallet', () => {
       vault: expect.any(String),
     });
   });
+
+  describe('lifecycle', () => {
+    const options = {
+      infuraProjectId: 'fake-infura-project-id',
+      clientVersion: '1.0.0',
+      showApprovalRequest: (): undefined => undefined,
+      clientConfigApiService: new ClientConfigApiService({
+        fetch: globalThis.fetch,
+        config: {
+          client: ClientType.Extension,
+          distribution: DistributionType.Main,
+          environment: EnvironmentType.Production,
+        },
+      }),
+      getMetaMetricsId: (): string => 'fake-metrics-id',
+    };
+
+    it('exposes controllerMetadata for each initialized controller', () => {
+      wallet = new Wallet(options);
+
+      const names = Object.keys(wallet.controllerMetadata);
+      expect(names).toStrictEqual(Object.keys(wallet.state));
+      for (const name of names) {
+        expect(wallet.controllerMetadata[name]).toBeDefined();
+      }
+    });
+
+    it('omits instances without a metadata property from controllerMetadata', () => {
+      const fakeMetadata = { foo: { persist: true, anonymous: false } };
+      jest.spyOn(initializationModule, 'initialize').mockReturnValueOnce({
+        WithMeta: { state: {}, metadata: fakeMetadata },
+        NoMeta: { state: {} },
+      } as never);
+
+      wallet = new Wallet(options);
+
+      expect(wallet.controllerMetadata).toStrictEqual({
+        WithMeta: fakeMetadata,
+      });
+      expect(Object.keys(wallet.state)).toStrictEqual(['WithMeta', 'NoMeta']);
+    });
+
+    it('publishes Root:walletDestroyed exactly once on destroy', async () => {
+      wallet = new Wallet(options);
+
+      const listener = jest.fn();
+      wallet.messenger.subscribe('Root:walletDestroyed', listener);
+
+      await wallet.destroy();
+      await wallet.destroy();
+
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('publishes Root:walletDestroyed even if a controller destroy throws synchronously', async () => {
+      wallet = new Wallet(options);
+
+      jest
+        .spyOn(TransactionController.prototype, 'destroy')
+        .mockImplementation(() => {
+          throw new Error('sync destroy error');
+        });
+
+      const listener = jest.fn();
+      wallet.messenger.subscribe('Root:walletDestroyed', listener);
+
+      await wallet.destroy();
+
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('publishes Root:walletDestroyed even if a controller destroy rejects', async () => {
+      wallet = new Wallet(options);
+
+      jest
+        .spyOn(TransactionController.prototype, 'destroy')
+        .mockRejectedValue(new Error('async destroy error') as never);
+
+      const listener = jest.fn();
+      wallet.messenger.subscribe('Root:walletDestroyed', listener);
+
+      await wallet.destroy();
+
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+  });
 });

packages/wallet/src/Wallet.ts

@@ -1,5 +1,6 @@
+import type { StateMetadataConstraint } from '@metamask/base-controller';
 import { Messenger } from '@metamask/messenger';
-import type { Json } from '@metamask/utils';
+import { hasProperty } from '@metamask/utils';
 
 import type {
   DefaultActions,
@@ -11,23 +12,34 @@ import type {
 import { initialize } from './initialization';
 import type { WalletOptions } from './types';
 
-export type WalletConstructorArgs = {
-  state?: Record<string, Json>;
-  options: WalletOptions;
-};
-
 export class Wallet {
   // TODO: Expand types when passing additionalConfigurations.
   public readonly messenger: RootMessenger<DefaultActions, DefaultEvents>;
 
   readonly #instances: DefaultInstances;
 
-  constructor({ state = {}, options }: WalletConstructorArgs) {
+  readonly #controllerMetadata: Readonly<
+    Record<string, Readonly<StateMetadataConstraint>>
+  >;
+
+  #destroyed = false;
+
+  constructor({ state, ...options }: WalletOptions) {
     this.messenger = new Messenger({
       namespace: 'Root',
     });
 
-    this.#instances = initialize({ state, messenger: this.messenger, options });
+    this.#instances = initialize({
+      state: state ?? {},
+      messenger: this.messenger,
+      options,
+    });
+
+    this.#controllerMetadata = Object.fromEntries(
+      Object.entries(this.#instances)
+        .filter(([_, instance]) => hasProperty(instance, 'metadata'))
+        .map(([name, instance]) => [name, instance.metadata]),
+    );
   }
 
   get state(): DefaultState {
@@ -40,17 +52,30 @@ export class Wallet {
     ) as DefaultState;
   }
 
+  get controllerMetadata(): Readonly<
+    Record<string, Readonly<StateMetadataConstraint>>
+  > {
+    return this.#controllerMetadata;
+  }
+
   async destroy(): Promise<void> {
-    await Promise.all(
+    if (this.#destroyed) {
+      return;
+    }
+    this.#destroyed = true;
+
+    await Promise.allSettled(
       Object.values(this.#instances).map((instance) => {
         // @ts-expect-error Accessing protected property.
         if (typeof instance.destroy === 'function') {
           // @ts-expect-error Accessing protected property.
-          return instance.destroy();
+          return (async (): Promise<void> => await instance.destroy())();
         }
         /* istanbul ignore next */
-        return undefined;
+        return Promise.resolve();
       }),
     );
+
+    this.messenger.publish('Root:walletDestroyed');
   }
 }

packages/wallet/src/index.ts

@@ -1 +1,8 @@
 export { Wallet } from './Wallet';
+export type { WalletOptions } from './types';
+export type {
+  DefaultActions,
+  DefaultEvents,
+  RootMessenger,
+  WalletDestroyedEvent,
+} from './initialization';

packages/wallet/src/initialization/defaults.ts

@@ -38,7 +38,14 @@ export type DefaultInstances = {
 
 export type DefaultActions = MessengerActions<AllMessengers>;
 
-export type DefaultEvents = MessengerEvents<AllMessengers>;
+export type WalletDestroyedEvent = {
+  type: 'Root:walletDestroyed';
+  payload: [];
+};
+
+export type DefaultEvents =
+  | MessengerEvents<AllMessengers>
+  | WalletDestroyedEvent;
 
 export type RootMessenger<
   AllowedActions extends ActionConstraint = ActionConstraint,