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))
+  - It can be used 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,120 @@
+# 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:
+
+```json
+{
+  "version": 2,
+  "data": { "accountCount": 3, "mnemonic": [...], "hdPath": "m/44'/60'/0'/0" }
+}
+```
+
+Unversioned state (vaults created before migration support was added) has no envelope. The framework treats it as version 0 and applies all migrations.
+
+## Key Concepts
+
+- **`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.
+- **`as const` arrays**: Use an array with `as const` to allow TypeScript to infer the final state type via `applyMigrations`.
+
+## 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(),
+});
+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>;
+```
+
+### 2. Define the Migration Chain
+
+```typescript
+import { defineMigration } from '@metamask/keyring-sdk';
+
+const migrations = [
+  defineMigration({
+    version: 1,
+    inputSchema: HdStateV0Schema,
+    schema: HdStateV1Schema,
+    migrate: (data) => ({
+      accountCount: data.numberOfAccounts,
+      mnemonic: data.mnemonic,
+      hdPath: data.hdPath,
+    }),
+  }),
+  defineMigration<HdStateV2, HdStateV1>({
+    version: 2,
+    schema: HdStateV2Schema,
+    migrate: (data) => ({ ...data, createdAt: Date.now() }),
+  }),
+] as const;
+```
+
+### 3. Implement in your Keyring
+
+```typescript
+import { applyMigrations, getLatestVersion } from '@metamask/keyring-sdk';
+import type { VersionedState } from '@metamask/keyring-sdk';
+import type { Json } from '@metamask/utils';
+
+class MyKeyring {
+  async deserialize(state: Json): Promise<void> {
+    const { data } = await applyMigrations(state, migrations);
+
+    // data is typed as HdStateV2
+    this.#mnemonic = data.mnemonic;
+    this.#accountCount = data.accountCount;
+    this.#hdPath = data.hdPath;
+  }
+
+  async serialize(): Promise<VersionedState<HdStateV2>> {
+    return {
+      version: getLatestVersion(migrations),
+      data: {
+        mnemonic: this.#mnemonic,
+        accountCount: this.#accountCount,
+        hdPath: this.#hdPath,
+      },
+    };
+  }
+}
+```
+
+## Best Practices
+
+- **`as const` arrays**: Declare the migrations array with `as const` so TypeScript infers the final state type from `applyMigrations`. Without it, `data` falls back to `Json`.
+- **Idempotent migrations**: Design migrations so re-running them on already-migrated data is harmless.
+- **Immutability**: Treat the input `data` as immutable within the `migrate` function.
+- **Schema coverage**: Ensure `schema` covers all fields expected in the new version to prevent runtime errors.
+
+## Constraints
+
+- **Sequential versions**: migrations must be numbered 1, 2, 3, ... with no gaps.
+- **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';