feat: add keyring state migration framework by danroc · Pull Request #505 · MetaMask/accounts

danroc · 2026-04-08T16:08:22Z

Summary

Adds a versioned migration framework to @metamask/keyring-sdk for evolving keyring serialized state
Migrations run during deserialize() and wrap state in a { version, data } envelope
defineMigration() helper provides compile-time type binding between migrate and superstruct schema
Includes developer documentation with integration examples
Adds jest types to tsconfig.packages.json for IDE support

Test plan

yarn workspace @metamask/keyring-sdk test passes (85 tests, 100% coverage)
yarn workspace @metamask/keyring-sdk build succeeds
No lint errors

Add a versioned migration framework that allows keyrings to evolve their serialized state format over time. Migrations run during deserialize() and wrap state in a { version, data } envelope. - KeyringMigration type with generic Output extends Json - defineMigration() helper for compile-time type binding between migrate and superstruct schema - applyMigrations() runner with sequential version validation - isVersionedState() type guard and getLatestVersion() helper - Developer documentation with integration examples - Add jest types to tsconfig.packages.json for IDE support

Replace manual type checks in isVersionedState with a VersionedStateStruct schema using superstruct. Derive VersionedState type from the struct. Use JsonStruct from @metamask/utils for the data field.

…lper

…raint - applyMigrations now returns MigrationResult with a migrated boolean so callers can detect when migrations ran and schedule a persist - defineMigration gains an optional inputSchema (Struct<Input>) that validates state before migrate is called; the Input type parameter removes the need for manual casts inside migrate - migrations.md updated: inputSchema example, migrated usage in deserialize, output-as-input validation chain note, and a new Idempotent migrations constraint

defineMigrations uses rest parameters to infer a tuple type, which lets applyMigrations resolve data as the last migration's output without any cast or as const: const migrations = defineMigrations( defineMigration<V1, V0>({ version: 1, ... }), defineMigration<V2, V1>({ version: 2, ... }), ); const { data } = await applyMigrations(state, migrations); // data: V2 Falls back to Json when the array is typed as KeyringMigration[].

…fineMigration

ccharly · 2026-04-10T12:25:46Z

packages/keyring-sdk/docs/migrations.md

+
+- **`schema`**: Validates the **output** of a migration at runtime.
+- **`inputSchema`**: (Optional) Validates the **input** before the `migrate` function is called.
+- **`defineMigration<Output, Input>`**: Ensures the `migrate` function's return type matches the `schema` type at compile time.


I would have expected to have input first, then output? But I guess it's because we want to have the type for the right version "first"?

Like:

const migrations = defineMigrations( // version 1 -> HdStateV1 defineMigration<HdStateV1, HdStateV0>({ version: 1, inputSchema: HdStateV0Schema, schema: HdStateV1Schema, migrate: (state) => ({ accountCount: state.numberOfAccounts, mnemonic: state.mnemonic, hdPath: state.hdPath, }), }), ...

It's intentional since Output is the primary type. Input can be omitted and it will default to Json.

ccharly · 2026-04-10T12:27:53Z

packages/keyring-sdk/docs/migrations.md

+
+class MyKeyring {
+  async deserialize(state: Json): Promise<void> {
+    const { data } = await applyMigrations(state, migrations);


WDYT about renaming this just migrate?

migrate is already a field of KeyringMigration, I didn't re-use it because I thought it could be confusing.

ccharly · 2026-04-10T12:28:31Z

packages/keyring-sdk/docs/migrations.md

+  defineMigration<HdStateV1, HdStateV0>({
+    version: 1,
+    inputSchema: HdStateV0Schema,
+    schema: HdStateV1Schema,
+    migrate: (state) => ({
+      accountCount: state.numberOfAccounts,
+      mnemonic: state.mnemonic,
+      hdPath: state.hdPath,
+    }),


Maybe we could auto-Infer input and output based on inputSchema and schema? 🤔

It's already the case, they aren't necessary in this case, I can remove the types from the example.

ccharly · 2026-04-10T12:30:54Z

packages/keyring-sdk/docs/migrations.md

+const HdStateV0Schema = object({
+  numberOfAccounts: number(), // legacy field name
+  mnemonic: array(number()),
+  hdPath: string(),
+});
+type HdStateV0 = Infer<typeof HdStateV0Schema>;
+
+const HdStateV1Schema = object({
+  accountCount: number(), // renamed from numberOfAccounts
+  mnemonic: array(number()),
+  hdPath: string(),
+});
+type HdStateV1 = Infer<typeof HdStateV1Schema>;
+
+const HdStateV2Schema = object({
+  accountCount: number(),
+  mnemonic: array(number()),
+  hdPath: string(),
+  createdAt: number(), // new field
+});
+type HdStateV2 = Infer<typeof HdStateV2Schema>;


Nit: But would be nice to enforce that all schemas are JSON-compatible too (not sure we have something ready for this).

Maybe we don't need to enforce this in the superstruct itself, but in the defineMigration* we could make sure T extends Json? Just to avoid allowing state that could not be serialized to JSON?

It's already the case (at least in compile-time), Input and Output must extend Json.

…emas When both `schema` and `inputSchema` are provided to `defineMigration`, TypeScript infers `Output` and `Input` automatically. Remove the explicit generic arguments and redundant `migrate` return type annotations in those cases across docs, tests, and JSDoc examples. The `@ts-expect-error` test for intentionally invalid output retains its explicit `<OutputState>` type param since the compile-time check only fires when TypeScript knows the expected output type.

…rn for migrations

…defined

Replace optional validate with an always-present method that is a no-op when no schema is provided, and update tests to assert behavior rather than presence.

…nction

danroc added 7 commits April 8, 2026 18:07

docs: update keyring-sdk changelog for migration framework

1a4698e

refactor: use superstruct for VersionedState validation

57ff16b

Replace manual type checks in isVersionedState with a VersionedStateStruct schema using superstruct. Derive VersionedState type from the struct. Use JsonStruct from @metamask/utils for the data field.

refactor: simplify migrations with entries() and getVersionAndData he…

a52adf8

…lper

docs: simplify migration documentation

ec6f6f5

danroc force-pushed the dr/kering-migrations branch from 1b3ffa5 to c7354f2 Compare April 8, 2026 21:39

docs: remove redundant API reference from migrations doc

f087b71

danroc force-pushed the dr/kering-migrations branch from 186e5ef to f087b71 Compare April 8, 2026 22:43

danroc added 6 commits April 9, 2026 00:44

docs: remove duplicate defineMigration JSDoc

c0ece22

fix: use integer() for versioned state, remove unnecessary cast in de…

d0e050e

…fineMigration

docs: simplify JSDoc for defineMigration parameters

7c6b530

chore: make migrations a const to allow type inference

1e645f8

chore: rename some tests

543742d

refactor: allow validate to be undefined

94a9efc

danroc force-pushed the dr/kering-migrations branch from 4444802 to 94a9efc Compare April 9, 2026 06:52

docs: simplify documentation

0679d1f

danroc force-pushed the dr/kering-migrations branch from ad96b17 to 0679d1f Compare April 9, 2026 07:29

danroc added 9 commits April 10, 2026 11:56

docs: improve keyring state migrations documentation

4c37748

docs: clarify state persistence responsibility in migrations

c3bfec8

docs: clean up unused code in migrations example

8f55f2d

chore: remove prettier config change

fdc5993

docs: remove redundant migrated flag from migrations example

fafab10

docs: remove redundant migrated flag reference from best practices

e9f2d9b

chore: remove changes to tsconfig

e16d6ca

chore: rename migrations.ts to migration.ts (migration engine)

f6e0e94

chore: unwrap lines

914708d

ccharly reviewed Apr 10, 2026

View reviewed changes

danroc added 10 commits April 10, 2026 16:05

refactor(keyring-sdk): remove defineMigrations and use as const patte…

656545b

…rn for migrations

feat: use JsonStruct to validate inner state when inputSchema is not …

6a27f59

…defined

chore: simplify comment

c7b59a6

chore: refine types of isVersionedState and getVersionAndData

18d4ade

refactor(keyring-sdk): make validate always defined with no-op fallback

e976d4c

Replace optional validate with an always-present method that is a no-op when no schema is provided, and update tests to assert behavior rather than presence.

refactor(keyring-sdk): simplify state assertion in defineMigration fu…

4316c68

…nction

refactor(keyring-sdk): streamline migration validation call

d4bea01

chore: remove redundant comment

9488700

chore: clarify data vs state

dfdbde0

chore: simplify comment

9390053

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add keyring state migration framework#505

feat: add keyring state migration framework#505
danroc wants to merge 35 commits intomainfrom
dr/kering-migrations

danroc commented Apr 8, 2026

Uh oh!

ccharly Apr 10, 2026

Uh oh!

danroc Apr 10, 2026

Uh oh!

ccharly Apr 10, 2026

Uh oh!

danroc Apr 10, 2026

Uh oh!

ccharly Apr 10, 2026

Uh oh!

danroc Apr 10, 2026

Uh oh!

ccharly Apr 10, 2026

Uh oh!

danroc Apr 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

danroc commented Apr 8, 2026

Summary

Test plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants