feat(wallet): Add split persistence backed by better-sqlite3 by rekmarks · Pull Request #8480 · MetaMask/core

rekmarks · 2026-04-16T02:06:13Z

Summary

Add synchronous, per-property SQLite persistence to the wallet package using better-sqlite3
Each controller state property with persist: true metadata gets its own row in a kv table (key format: ControllerName.propertyName)
Writes happen synchronously within the same call stack as controller.update() via stateChanged event subscriptions, eliminating data loss windows
Defaults to :memory: when no database path is provided

Test plan

yarn workspace @metamask/wallet exec jest --no-coverage --watchman=false src/persistence/ — 22 unit tests covering KeyValueStore CRUD, loadState grouping, persist filtering, StateDeriver application, patch-based diffing, unsubscribe, and multi-controller scenarios
yarn workspace @metamask/wallet exec tsc --noEmit — no new type errors
Integration test with file-backed DB: create Wallet with a file path, perform operations, create second Wallet from same path, verify state restoration

🤖 Generated with Claude Code

Note

Medium Risk
Adds a native better-sqlite3 dependency plus new persistence wiring and a new wallet lifecycle event; failures here could impact state durability and build/install behavior across environments.

Overview
Adds a new @metamask/wallet/persistence entrypoint that provides synchronous SQLite-backed persistence via better-sqlite3: a KeyValueStore plus loadState() and subscribeToChanges() to persist per-controller, per-property state (keyed as Controller.property) based on controller persist metadata and Immer patches.

Updates Wallet lifecycle to expose controllerMetadata, make destroy() idempotent, tear down controllers via Promise.allSettled, and publish a new Root:walletDestroyed event (also added to DefaultEvents) to support persistence self-unsubscribe; adjusts wallet construction to accept WalletOptions directly (with optional state).

Build/test plumbing is updated to support the native addon: adds better-sqlite3 (+ typings), enables it in Lavamoat allowScripts, replaces the test prep script with install-binaries.sh (installs anvil and downloads the sqlite prebuild when missing), and documents rebuild steps in the wallet README.

^{Reviewed by Cursor Bugbot for commit 58ab0c5. Bugbot is set up for automated code reviews on this repo. Configure here.}

socket-security · 2026-04-16T02:07:01Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@types/better-sqlite3@7.6.13
	better-sqlite3@12.9.0

View full report

rekmarks · 2026-04-16T02:38:53Z

@SocketSecurity ignore npm/better-sqlite3@11.10.0

Yes, it has native binaries.

rekmarks · 2026-04-16T02:48:10Z

@SocketSecurity ignore-all

All alerts are due to better-sqlite3 or its transitives. It is a reputable package that we use elsewhere.

FrederikBolding · 2026-04-17T12:04:14Z

+
+  readonly #unsubscribePersistence: () => void;
+
+  constructor({ options, databasePath = ':memory:' }: WalletConstructorArgs) {


If Wallet is to be used in all clients it should be agnostic to persistence. I think these changes should target the CLI branch and be part of the CLI class.

Alternatively we can come up with an interface where each client can pass in their own persistence, but it may be simpler to not deal with it at all in Wallet.

Made some benign modifications to the Wallet interface and made it agnostic of persistence. I kept the persistence files in the wallet package for now to avoid creating a complicated PR stack (or bloating the CLI PR). We can move the persistence stuff out of the wallet package once this is merged.

FrederikBolding · 2026-04-17T12:05:30Z

+        const key = `${controllerName}.${prop}`;
+        const persistFlag = metadata[prop]?.persist;


We should use deriveStateFromMetadata

They're similar but I don't think it's a good fit. deriveStateFromMetadata iterates over every top-level state property and errors on missing properties. The subscribeToChanges handlers iterate over changed properties and deletes missing properties from persistence, which shouldn't happen in practice but that is not for the persistence layer to know. Then there's also the complex error handling logic in deriveStateFromMetadata which doesn't buy us anything here.

Persist controller state to SQLite using a per-property key-value scheme (one row per ControllerName.propertyName). Writes are synchronous within the same call stack as controller state updates, using stateChanged events and Immer patches to write only changed, persist-flagged properties. Defaults to ':memory:' when no database path is provided. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

The build tsconfig is stricter than the dev tsconfig — the union type of controller instances does not expose the protected `destroy` method. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Address review findings: add constructor cleanup on failure, make destroy() idempotent with Promise.allSettled and finally, handle remove patches via store.delete(), catch and log handler write failures, validate degenerate store keys, handle root state replacement patches, add contextful JSON.parse errors, tighten loadState return type, extract PersistableController type and storeKey utility, remove premature KeyValueStore public export, and add tests for new behaviors. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Make `@metamask/wallet` platform-agnostic by removing the SQLite-backed `KeyValueStore` from the `Wallet` constructor. `Wallet` now accepts a flat `WalletOptions` (including an optional `state` payload) and owns no persistence state. Consumers arrange persistence themselves. - `Wallet` exposes a `controllerMetadata` getter so persistence can operate on metadata alone, without reaching into controller instances. - A new `Root:walletDestroyed` event is published after controllers tear down during `destroy()`. `subscribeToChanges` listens for it and self-unsubscribes, eliminating the need for callers to hold an unsubscribe handle. - `subscribeToChanges` now takes a `Record<string, StateMetadataConstraint>` instead of the controller-instance map, and specializes its messenger type to `RootMessenger<DefaultActions, DefaultEvents>` so subscribing to `Root:walletDestroyed` type-checks without suppression. - `KeyValueStore`, `loadState`, and `subscribeToChanges` are exposed via a new `@metamask/wallet/persistence` subpath export; they'll move to their own package later.

So that @metamask/wallet/persistence can be moved to its own package without needing to deep-import from the wallet package.

Renames install-anvil.sh to install-binaries.sh and adds a better-sqlite3 native addon rebuild step for CI environments where the prebuilt binding is absent or incompatible with the Node version. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Check for the compiled addon at `node_modules/better-sqlite3/build/Release/better_sqlite3.node` and skip `prebuild-install` when it's already present. Avoids unnecessary network calls on every `test:prepare` run. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 4c16ea9. Configure here.}

This comment was marked as resolved.

Sign in to view

rekmarks added the no-changelog label Apr 16, 2026

rekmarks force-pushed the rekm/wallet-sqlite branch 6 times, most recently from 8f58b8c to f66328d Compare April 16, 2026 20:30

rekmarks force-pushed the feat/wallet-library branch 2 times, most recently from 623f9af to 3fb60ee Compare April 16, 2026 21:13

rekmarks force-pushed the rekm/wallet-sqlite branch 4 times, most recently from 1d6d1fc to 937ba80 Compare April 16, 2026 21:52

rekmarks marked this pull request as ready for review April 16, 2026 21:59

rekmarks requested a review from a team as a code owner April 16, 2026 21:59

rekmarks force-pushed the rekm/wallet-sqlite branch from 937ba80 to 29c6ac6 Compare April 16, 2026 21:59

cursor bot reviewed Apr 16, 2026

View reviewed changes

Comment thread packages/wallet/src/persistence/persistence.ts

cursor bot reviewed Apr 16, 2026

View reviewed changes

Comment thread packages/wallet/src/Wallet.ts Outdated

rekmarks force-pushed the rekm/wallet-sqlite branch from 0cf2d0d to 520a971 Compare April 17, 2026 03:28

FrederikBolding force-pushed the feat/wallet-library branch from 45d013e to 6ec54b9 Compare April 17, 2026 09:30

FrederikBolding reviewed Apr 17, 2026

View reviewed changes

rekmarks and others added 4 commits April 17, 2026 11:50

fix(wallet): Restore @ts-expect-error for protected destroy access

0b122f7

The build tsconfig is stricter than the dev tsconfig — the union type of controller instances does not expose the protected `destroy` method. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

chore: Bump better-sqlite3

331ef42

chore: lint

283acca

rekmarks and others added 8 commits April 17, 2026 11:50

docs: Fix better-sqlite3 rebuild instructions

18b57d1

refactor: Tweak sqlite imports

b6b0596

refactor: Tweak types, simplify tests

428d427

tests: Cover persistence error paths and lifecycle edge cases

c6a88f5

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

chore: oxfmt & eslint

62ff2e3

refactor: Make change and persist sets readonly

6df4a99

refactor: Unsubscribe in try block

cfad387

rekmarks force-pushed the rekm/wallet-sqlite branch from 520a971 to cfad387 Compare April 17, 2026 18:50

cursor bot reviewed Apr 17, 2026

View reviewed changes

Comment thread packages/wallet/src/Wallet.ts Outdated

rekmarks added 3 commits April 17, 2026 14:49

chore: Re-export persistence-facing types from wallet entry

366b265

So that @metamask/wallet/persistence can be moved to its own package without needing to deep-import from the wallet package.

fix: Prevent synchronous errors from interrupting destroy procedure

f4e8dfa

rekmarks force-pushed the rekm/wallet-sqlite branch from 06b91f1 to f4e8dfa Compare April 17, 2026 22:00

rekmarks and others added 3 commits April 17, 2026 15:07

test: Add tests for destruction robustuness

86a69b0

rekmarks requested a review from FrederikBolding April 17, 2026 22:49

refactor: Exclude instances without metadata from metadata getter

4c16ea9

cursor bot reviewed Apr 20, 2026

View reviewed changes

Comment thread packages/wallet/src/Wallet.ts Outdated

refactor: Remove extraneous registerInitialEventPayload

58ab0c5

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

feat(wallet): Add split persistence backed by better-sqlite3#8480
rekmarks wants to merge 20 commits intofeat/wallet-libraryfrom
rekm/wallet-sqlite

rekmarks commented Apr 16, 2026 •

edited by cursor bot

Loading

Uh oh!

socket-security bot commented Apr 16, 2026 •

edited

Loading

Uh oh!

This comment was marked as resolved.

rekmarks commented Apr 16, 2026

Uh oh!

rekmarks commented Apr 16, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

FrederikBolding Apr 17, 2026

Uh oh!

FrederikBolding Apr 17, 2026

Uh oh!

rekmarks Apr 17, 2026

Uh oh!

FrederikBolding Apr 17, 2026

Uh oh!

rekmarks Apr 17, 2026

Uh oh!

Uh oh!

cursor bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		readonly #unsubscribePersistence: () => void;

		constructor({ options, databasePath = ':memory:' }: WalletConstructorArgs) {

		const key = `${controllerName}.${prop}`;
		const persistFlag = metadata[prop]?.persist;

Uh oh!

Conversation

rekmarks commented Apr 16, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

socket-security bot commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as resolved.

rekmarks commented Apr 16, 2026

Uh oh!

rekmarks commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

FrederikBolding Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

FrederikBolding Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

rekmarks Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

FrederikBolding Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

rekmarks Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rekmarks commented Apr 16, 2026 •

edited by cursor bot

Loading

socket-security bot commented Apr 16, 2026 •

edited

Loading

rekmarks commented Apr 16, 2026 •

edited

Loading