feat(wallet-cli): add SQLite-backed controller-state persistence

[sirtimid]

Explanation

@metamask/wallet-cli runs a background daemon that hosts a @metamask/wallet instance. For controller state to survive daemon restarts, it needs durable local storage. This PR adds that persistence layer. It is purely additive and not yet wired into a daemon process — the daemon entry point that consumes it lands in a follow-up.

• KeyValueStore — a synchronous better-sqlite3-backed key-value store (a single kv table with a TEXT key and a JSON-serialized TEXT value). Corrupt rows fail loud (a descriptive, key-scoped error) rather than returning garbage.
• loadState(store) — rehydrates persisted state into the { [controllerName]: { [property]: value } } shape accepted by the Wallet constructor's state option.
• subscribeToChanges(messenger, controllerMetadata, store, log?) — subscribes to every <Controller>:stateChanged event and writes persist-flagged top-level properties through to the store (applying StateDeriver persist functions, and deleting a key when its property is removed from state). It returns an unsubscribe handle; teardown is owned by the caller (a dispose() handle in a later PR), so there is no package-level teardown event.

better-sqlite3 native addon

better-sqlite3 ships a native C addon. The monorepo runs Yarn with enableScripts: false, so the addon is not built during yarn install. To handle this:

• a test:prepare step (scripts/install-binaries.sh) fetches a matching prebuild via prebuild-install before tests run;
• engines.node is set to >=20 (better-sqlite3 v12 only ships prebuilt binaries for Node 20+);
• @metamask/wallet-cli is excluded from the Node 18.x CI test matrix;
• yarn.config.cjs exempts the package from the standard test-script and engines.node constraints accordingly.

References

• Closes wallet-cli: Move sqlite persistence from wallet to wallet-cli #8682
• Builds on feat: add @metamask/wallet-cli package scaffold #9065 (the @metamask/wallet-cli package scaffold). This PR targets that branch and should merge after it.

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
• I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

🤖 Generated with Claude Code

---

Note

Medium Risk
New durable state path can diverge from in-memory state on disk write failures (logged only today); native addon and Node 20+ requirement affect install and CI.

Overview
Adds SQLite-backed persistence in @metamask/wallet-cli so wallet controller state can survive restarts (not yet wired into the daemon).

A synchronous KeyValueStore (better-sqlite3, JSON values in a kv table) is the storage backend. loadState rebuilds { controllerName: { property: value } } for Wallet construction, honoring only properties still marked persist in controller metadata so stale rows are not resurrected. subscribeToChanges listens on <Controller>:stateChanged, writes persist-flagged top-level fields from Immer patches (including StateDeriver transforms and deletes when properties are removed), logs write failures without stopping the process, and returns an unsubscribe handle.

better-sqlite3 is added with engines.node >=20, a test:prepare / install-binaries.sh prebuild step (monorepo enableScripts: false), CI matrix exclusion for Node 18 on this package, and yarn.config.cjs exceptions for the custom test script and engines field. Dependencies on @metamask/wallet, @metamask/base-controller, and immer are added with matching tsconfig project references.

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

[socket-security]

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.10.0

View full report

[socket-security]

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

Ignoring alerts on:

• better-sqlite3@12.10.0
• prebuild-install@7.1.3
• detect-libc@2.1.2
• simple-get@4.0.1
• tunnel-agent@0.6.0
• chownr@1.1.4

View full report

[sirtimid]

@SocketSecurity ignore npm/better-sqlite3@12.10.0

[sirtimid]

@SocketSecurity ignore npm/detect-libc@2.1.2
Shell access = spawning getconf/ldd to detect glibc vs musl for prebuild selection. Expected & necessary.

@SocketSecurity ignore npm/simple-get@4.0.1
Network access = the HTTP(S) client prebuild-install uses to fetch the binary from GitHub releases.

@SocketSecurity ignore npm/tunnel-agent@0.6.0
Network access = HTTPS-over-proxy tunneling for the prebuild download; "code anomaly" is a false positive.

@SocketSecurity ignore npm/chownr@1.1.4
"Code anomaly" false positive on isaacs' recursive-chown util, used via tar-fs to unpack the prebuild tarball.

@SocketSecurity ignore npm/prebuild-install@7.1.3
Socket flags as deprecated; it's better-sqlite3 v12's bundled prebuild fetcher, runs only at test-prep, not shipped.

All alerts are transitive deps of better-sqlite3's prebuild-install toolchain (better-sqlite3 → prebuild-install → {detect-libc, simple-get, tunnel-agent, tar-fs → chownr}), which downloads/unpacks the prebuilt native SQLite addon. None are in @metamask/wallet-cli's own code or runtime path. The monorepo sets enableScripts: false, so none run on yarn install; prebuild-install runs only via the package's explicit test:prepare script and in CI.

[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 fb00cf0. Configure here.}

[grypez]

Familiar! Approved

[Mrtenz]

Instead of this we can just install better-sqlite3 into the root package and enable it to run the postinstall script there.

A better alternative would be to find a package that doesn't need postinstall scripts, though.

[sirtimid]

Thanks! Two parts to this:

On switching to a package without postinstall scripts: we're staying on better-sqlite3 on purpose. The ocap-kernel, that wallet-cli will host, already uses it, so picking a different engine here would mean two SQLite implementations in one process.

On installing it at the root + allow-scripts: fair point, that's the idiomatic mechanism (secp256k1 already goes through it). The reason I kept it as a scoped test:prepare step is to avoid running better-sqlite3 native build on every monorepo yarn install. Also v12 only ships prebuilds for Node 22+, so contributors on Node 18 (still supported repo-wide) would fall back to a source compile, and an allow-scripts failure exits the whole install, for packages that have nothing to do with wallet-cli.

[sirtimid]

Once we can raise the nodejs floor to >= 22.5 and once it's not anymore experimental we can switch to node:sqlite but we researched all the alternatives at the ocap-kernel team and concluded that better-sqlite3 is better, for now.