wallet: Document the state-injection contract in README
Maintainers usually reply within 1 day
@grypez is already working on this.
Since May 26, 2026.
Assessment
This issue has not been assessed yet.
Description
Problem
@metamask/wallet has no usage documentation. The persistence contract — how consumers supply initial state and subscribe to controller state changes — is entirely implicit. Callers must read the source to understand how to wire persistence, and there is no canonical reference for the expected data shapes or event subscription pattern.
Proposed direction
Add a Usage section to packages/wallet/README.md covering:
- Hydration: pass an initial
stateobject keyed by controller name to theWalletconstructor. Missing keys fall back to each controller's default state. - Writes: subscribe to
${ControllerName}:stateChangedevents onwallet.messenger; usewallet.controllerMetadatato identify which fields carrypersist: true. - Include short code examples for both.
Acceptance
README.mdhas a Usage section with working code examples for both hydration and the stateChanged subscription pattern.- The role of
wallet.controllerMetadata(identifying persist-flagged fields) is explained. - Changelog entry added.
- Dominant language
- TypeScript
- Stars
- 422
- Forks
- 313
- Avg merge
- 1d 8h
- Merged PRs (30d)
- 414
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- No contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from MetaMask/core
-
Difficulty 2/5 1-3 hours Newbie friendliness 62/100
Maintainers usually reply within 1 day
-
CI: "Validate changelog diffs" job fails on every fork-sourced pull requestPossibly taken @Roxen-AS claimed this 20 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
Maintainers usually reply within 1 day
-
platform-api-docs: `scan` strategy misses ESM-only packages, which ship `.d.ts` rather than `.d.cts`Possibly taken @gaohan1994 claimed this 21 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
Maintainers usually reply within 1 day
-
[utils] Replace the `uuid` dependency with `crypto.randomUUID()`Possibly taken @avantikonde claimed this 34 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
MetaMask/core#10210 · 1 reaction ·
Maintainers usually reply within 1 day
-
[utils] `toWei` accepts fractional wei and returns wrong valuesPossibly taken @Roxen-AS claimed this 20 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
Maintainers usually reply within 1 day
Similar issues
-
enhancement module: library-ui
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
chthollyphile/folia-major#1206 · 1 comment ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
typescript-eslint/typescript-eslint#13189 ·
Maintainers usually reply within 2 days
-
severity:medium triage:confirmed triage:in-progress triage:reproduced
Difficulty 2/5 1-3 hours Newbie friendliness 73/100
Cotal-AI/Cotal#6442 · 2 comments ·
Maintainers usually reply within 1 day
-
wrong type
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
elastic/elasticsearch-specification#6919 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 62/100
Maintainers usually reply within 1 day