feat: add keyring state migration framework

packages/keyring-sdk/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add keyring state migration framework ([#505](https://github.com/MetaMask/accounts/pull/505))
+  - Use `createMigrations().add(...)` to build a chain of versioned migration steps, and `.apply(state)` to migrate the internal state of keyrings
+
 ### Changed
 
 - Bump `@metamask/keyring-api` from `^23.2.0` to `^23.5.0` ([#569](https://github.com/MetaMask/accounts/pull/569), [#583](https://github.com/MetaMask/accounts/pull/583), [#587](https://github.com/MetaMask/accounts/pull/587))

packages/keyring-sdk/docs/migrations.md

@@ -0,0 +1,117 @@
+# Keyring State Migrations
+
+A framework for evolving keyring serialized state across versions. Migrations run during `deserialize()` and transform old state into the current format.
+
+Versioned state is stored as an envelope:
+
+```json5
+{
+  "version": 1,
+  "data": { /* Keyring state */ }
+}
+```
+
+Unversioned state (vaults created before migration support was added) has no envelope. The framework treats it as version 0 and applies all steps.
+
+## Key Concepts
+
+- **`createMigrations()`**: Starts an empty migration chain.
+- **`.add(step)`**: Appends a step to the chain and returns a new chain typed to that step's output.
+- **`outputSchema`**: (Optional) Validates the **output** of a step at runtime.
+- **`inputSchema`**: (Optional) Validates the **input** before the `migrate` function is called.
+- **Positional versions**: The first `.add()` call produces version 1, the second version 2, and so on.
+
+## Example
+
+### 1. Define State Schemas
+
+Define a schema for each version of your state.
+
+```typescript
+import { object, array, number, string } from '@metamask/superstruct';
+import type { Infer } from '@metamask/superstruct';
+
+const HdStateV0Schema = object({
+  numberOfAccounts: number(), // legacy field name
+  mnemonic: array(number()),
+  hdPath: string(),
+});
+
+const HdStateV1Schema = object({
+  accountCount: number(), // renamed from numberOfAccounts
+  mnemonic: array(number()),
+  hdPath: string(),
+});
+
+const HdStateV2Schema = object({
+  accountCount: number(),
+  mnemonic: array(number()),
+  hdPath: string(),
+  createdAt: number(), // new field
+});
+
+type HdStateV0 = Infer<typeof HdStateV0Schema>;
+type HdStateV1 = Infer<typeof HdStateV1Schema>;
+type HdStateV2 = Infer<typeof HdStateV2Schema>;
+```
+
+### 2. Define the Migration Chain
+
+```typescript
+import { createMigrations } from '@metamask/keyring-sdk';
+
+const migrations = createMigrations()
+  .add({
+    inputSchema: HdStateV0Schema,
+    outputSchema: HdStateV1Schema,
+    migrate: (data) => ({
+      accountCount: data.numberOfAccounts,
+      mnemonic: data.mnemonic,
+      hdPath: data.hdPath,
+    }),
+  })
+  .add({
+    outputSchema: HdStateV2Schema,
+    migrate: (data) => ({ ...data, createdAt: Date.now() }), // data is typed as HdStateV1, no cast needed
+  });
+```
+
+### 3. Implement in your Keyring
+
+```typescript
+import type { VersionedState } from '@metamask/keyring-sdk';
+import type { Json } from '@metamask/utils';
+
+class MyKeyring {
+  async deserialize(state: Json): Promise<void> {
+    const { data } = await migrations.apply(state);
+
+    // data is typed as HdStateV2
+    this.#mnemonic = data.mnemonic;
+    this.#accountCount = data.accountCount;
+    this.#hdPath = data.hdPath;
+  }
+
+  async serialize(): Promise<VersionedState<HdStateV2>> {
+    return {
+      version: migrations.version,
+      data: {
+        mnemonic: this.#mnemonic,
+        accountCount: this.#accountCount,
+        hdPath: this.#hdPath,
+      },
+    };
+  }
+}
+```
+
+## Best Practices
+
+- **Idempotent migrations**: Design steps so re-running them on already-migrated data is harmless.
+- **Immutability**: Treat the input `data` as immutable within the `migrate` function.
+- **Schema coverage**: Ensure `outputSchema` covers all fields expected in the new version to prevent runtime errors.
+- **Non-mutating chains**: `.add()` returns a new chain rather than mutating the one it's called on, so it's safe to branch multiple chains off a shared base.
+
+## Constraints
+
+- **Forward-only**: there is no downgrade path. Code that does not understand the versioned envelope will fail on migrated state.

packages/keyring-sdk/src/index.ts

@@ -1,3 +1,4 @@
 export * from './keyring-account-registry';
+export * from './migration';
 export * from './mnemonic';
 export * from './eth';

packages/keyring-sdk/src/migration.test-d.ts

@@ -0,0 +1,53 @@
+import { object, number, string } from '@metamask/superstruct';
+import type { Json } from '@metamask/utils';
+import { expectType } from 'tsd';
+
+import { createMigrations } from './migration';
+import type { MigrationChain, MigrationResult } from './migration';
+
+// `createMigrations()` starts an empty chain typed to accept `Json`.
+expectType<MigrationChain<Json>>(createMigrations());
+
+// A step's `migrate` receives the previous step's output shape, with no cast needed.
+createMigrations()
+  .add({ migrate: (): { count: number } => ({ count: 1 }) })
+  .add({
+    migrate: (data) => {
+      expectType<number>(data.count);
+      return data;
+    },
+  });
+
+// A step's `migrate` must accept the previous step's output shape.
+createMigrations()
+  .add({ migrate: (): { count: number } => ({ count: 1 }) })
+  // @ts-expect-error [test] `data` is `{ count: number }`, not `{ label: string }`.
+  .add({ migrate: (data: { label: string }) => data.label });
+
+// `inputSchema` narrows `migrate`'s input to the schema's inferred type, with no cast
+// needed.
+createMigrations().add({
+  inputSchema: object({ oldCount: number() }),
+  migrate: (data) => {
+    expectType<number>(data.oldCount);
+    return { count: data.oldCount };
+  },
+});
+
+// `inputSchema` must be compatible with the chain's current data type, just like
+// `migrate`.
+createMigrations()
+  .add({ migrate: (): { count: number } => ({ count: 1 }) })
+  .add({
+    // @ts-expect-error [test] `inputSchema`'s inferred type doesn't extend `{ count: number }`.
+    inputSchema: object({ label: string() }),
+    migrate: () => 'x',
+  });
+
+// `apply()` resolves to the final step's output type.
+const migrationsForApply = createMigrations().add({
+  migrate: (): { count: number } => ({ count: 1 }),
+});
+expectType<Promise<MigrationResult<{ count: number }>>>(
+  migrationsForApply.apply({}),
+);