feat: Implement wallet initialization library#8838
Open
FrederikBolding wants to merge 26 commits into
Open
Conversation
Member
Author
|
@metamaskbot publish-previews |
Contributor
|
Preview builds have been published. Learn how to use preview builds in other projects. Expand for full list of packages and versions. |
Member
Author
|
@metamaskbot publish-previews |
Contributor
|
Preview builds have been published. Learn how to use preview builds in other projects. Expand for full list of packages and versions. |
Contributor
Hmm. I wonder if "instances" sounds a bit too vague. It's true they are instances of classes, but then so are lots of other things. For context, we discussed a unified term for controllers and services in this PR: https://github.com/MetaMask/decisions/pull/41#discussion_r1809429486. I had some ideas such as "messaging actor" (or just "actor"), but I think "messenger client" was the least worst option (and the one that Mark also agreed upon). "Messageable" was also a contender. Any of these options appeal to you? |
mcmire
reviewed
May 18, 2026
Contributor
mcmire
left a comment
mcmire
left a comment
There was a problem hiding this comment.
Going in a good direction. Here are some thoughts and comments.
Member
Author
|
@metamaskbot publish-previews |
Member
Author
@mcmire I haven't spent much time thinking about this, when the prototyping started I don't believe we had adopted "messenger client" on the MetaMask clients yet. If that already is our decided preferred naming, I can make changes, but "messenger client" seems similarly vague and maybe even an overloaded term considering API clients, the MetaMask clients themselves (extension/mobile) etc. |
Contributor
|
Preview builds have been published. Learn how to use preview builds in other projects. Expand for full list of packages and versions. |
Member
Author
|
@metamaskbot publish-previews |
Contributor
|
Preview builds have been published. Learn how to use preview builds in other projects. Expand for full list of packages and versions. |
Contributor
Yeah, it's not not a perfect name for sure. I purposefully avoided using the term "messenger client" in my presentation for similar reasons. I don't think we have adopted the term widely, so we could come up with a different one and no one would bat an eye. I guess we could go with "instance" for now and maybe something else will pop out later. |
Contributor
|
@FrederikBolding This looks pretty good to me so far. Let me know when this is out of draft. |
Member
Author
|
@metamaskbot publish-previews |
Contributor
|
Preview builds have been published. Learn how to use preview builds in other projects. Expand for full list of packages and versions. |
Member
Author
|
@metamaskbot publish-previews |
Contributor
|
Preview builds have been published. Learn how to use preview builds in other projects. Expand for full list of packages and versions. |
FrederikBolding
force-pushed
the
fb/wallet-lib-v1
branch
from
d28b57d to
49b8e9e
Compare
FrederikBolding
temporarily deployed
to
default-branch
GitHub Actions
Inactive
Mrtenz
reviewed
May 21, 2026
|
|
||
| export { defaultConfigurations }; | ||
|
|
||
| type ExtractInstance<Config> = |
Member
There was a problem hiding this comment.
Would be helpful to have some docs for these types, since it may not be immediately obvious what some of these do.
Mrtenz
reviewed
May 21, 2026
| import type { InstanceSpecificOptions } from '../types'; | ||
| import type { DefaultActions, DefaultEvents, RootMessenger } from './defaults'; | ||
|
|
||
| export type InstanceState<Instance> = Instance extends { state: unknown } |
Member
Author
There was a problem hiding this comment.
I added documentation for some of them, any specific ones you think are still confusing? a2c4a8c
Mrtenz
reviewed
May 21, 2026
Comment on lines
+17
to
+18
| const indices = phrase.split(' ').map((word) => wordlist.indexOf(word)); | ||
| const mnemonic = new Uint8Array(new Uint16Array(indices).buffer); |
Member
There was a problem hiding this comment.
IIRC key-tree has a util function for this.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Mrtenz
reviewed
May 21, 2026
Mrtenz
reviewed
May 21, 2026
Mrtenz
reviewed
May 21, 2026
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
There are 2 total unresolved issues (including 1 from previous review).
❌ 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 681bd35. Configure here.
mcmire
reviewed
May 21, 2026
Contributor
mcmire
left a comment
mcmire
left a comment
There was a problem hiding this comment.
Looks basically good, I just had one question about test coverage.
| import { initialize } from './initialization/initialization'; | ||
| import { WalletOptions } from './types'; | ||
|
|
||
| export class Wallet { |
Contributor
There was a problem hiding this comment.
Nit: Would be good to add JSDoc that briefly describes the purpose of this class and provides an example. Same for the README. This can be done in a future PR, however.
| functions: 100, | ||
| lines: 100, | ||
| statements: 100, | ||
| functions: 89.65, |
Contributor
There was a problem hiding this comment.
Is it possible to reach 100%?
| state, | ||
| messenger, | ||
| keyringBuilders: options.keyringBuilders, | ||
| encryptor: (options.encryptor ?? encryptorFactory(600_000)) as Encryptor< |
Contributor
There was a problem hiding this comment.
Nit: Why the typecast here?
| * Utility type for narrowing the InstanceSpecificOptions to just the options required for the instance. | ||
| */ | ||
| type InstanceOptions<Instance> = | ||
| CamelCaseInstanceName<Instance> extends keyof InstanceSpecificOptions |
Contributor
There was a problem hiding this comment.
I see that instanceOptions now takes properties which are camel-cased versions of instance names. I thought it made more sense for it to use the names directly (i.e. allow them to be PascalCased?) because I feel like this is what people will want to do naturally. However, did you change this because you didn't want them to constantly run up against our ESLint rule for property names?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Explanation
This PR implements a narrowly-scoped (as compared to the original feature branch) version of the wallet initialization library that only includes initializing the
KeyringController. This can eventually be used to demonstrate the integration of the library into the clients and serves as the base for future work.Overall it works in a similarly to the initialization pattern used in extension and mobile today, with some differences:
InitializationConfiguration. This object contains both a function to setup the messenger and the instance.InitializationConfiguration.messengeris expected to have access to actions/events necessary to initialize and operate the instance.There is no way to access the instances directly.The
Walletinstance provides access to the instances within using themessengerwhile also exposing a limited set of useful properties likestateandcontrollerMetadata.References
https://consensyssoftware.atlassian.net/browse/WPC-999
Checklist
Note
Medium Risk
Introduces a new
@metamask/walletinitialization layer that wires upKeyringControllerwith encryption configuration; errors here could affect vault creation/unlock behavior. Risk is moderated since this is largely additive and scoped to a new package.Overview
Adds the initial
@metamask/walletlibrary, replacing the placeholder export with a newWalletclass that bootstraps controller/service instances via a shared initialization registry and exposes read-onlymessenger, combinedstate, and per-controllercontrollerMetadata, plus adestroy()lifecycle.Implements the first default instance (
KeyringController), including abrowser-passworder-backed encryptor configured for PBKDF2 iterations (overrideable viainstanceOptions), and adds a helperimportSecretRecoveryPhrasethat restores a vault through messenger calls.Updates package wiring (new runtime deps, TS project references), adds a comprehensive test suite for initialization/immutability/lifecycle, relaxes Jest coverage thresholds for the new code, and records the package’s initial release in the changelog (plus README dependency graph update).
Reviewed by Cursor Bugbot for commit 5a37811. Bugbot is set up for automated code reviews on this repo. Configure here.