@metamask-previews/account-tree-controller 7.6.1-preview-e57e5c3dc → 7.6.1-preview-c449b8da8

package/dist/state/payload.mjs

@@ -0,0 +1,162 @@
+import { KeyringAccountTypeStruct } from "@metamask/keyring-api";
+import { array, assert, boolean, define, enums, integer, literal, object, exactOptional, refine, sensitive, string, StructError, union } from "@metamask/superstruct";
+import { BytesStruct, formatValidationErrorMessages } from "./utils.mjs";
+const PAYLOAD_GROUP_ID_REGEX = /^(?<walletId>wallet:[^/]+)\/(?<subId>.+)$/u;
+/**
+ * Parses a payload group ID into its wallet ID and group sub-ID components.
+ *
+ * @param groupId - The payload group ID to parse.
+ * @returns The parsed wallet ID and group sub-ID.
+ * @throws If the group ID format is invalid.
+ */
+export function parsePayloadGroupId(groupId) {
+    const match = PAYLOAD_GROUP_ID_REGEX.exec(groupId);
+    if (!match?.groups) {
+        throw new Error(`Invalid payload group ID: "${groupId}"`);
+    }
+    return {
+        walletId: match.groups.walletId,
+        subId: match.groups.subId,
+    };
+}
+/**
+ * Wallet type discriminants used in serialized {@link AccountTreePayload} entries.
+ *
+ * Use these constants instead of raw string literals so callers get autocomplete
+ * and a single source of truth for the discriminant values.
+ */
+export const AccountWalletPayloadType = {
+    Mnemonic: 'mnemonic',
+    PrivateKey: 'private-key',
+};
+/**
+ * Encoding formats for exported private key material.
+ */
+export const AccountWalletPrivateKeyEncoding = {
+    Hexadecimal: 'hexadecimal',
+    Base58: 'base58',
+    Base32: 'base32',
+};
+/**
+ * Constructs an {@link AccountWalletPayloadId} from an entropy source ID.
+ *
+ * @param entropySourceId - Stable entropy source ID returned by `HdKeyring.toEntropySourceId()`.
+ * @returns The portable wallet payload ID.
+ */
+export function toWalletPayloadId(entropySourceId) {
+    return `wallet:${entropySourceId}`;
+}
+/**
+ * Constructs an {@link AccountGroupPayloadId} from a wallet payload ID and a sub-ID.
+ *
+ * @param walletId - The wallet payload ID this group belongs to.
+ * @param subId - The group-specific sub-ID (e.g. group index for mnemonic wallets, address for private-key wallets).
+ * @returns The portable group payload ID.
+ */
+export function toGroupPayloadId(walletId, subId) {
+    return `${walletId}/${subId}`;
+}
+const AccountWalletPayloadIdStruct = define('AccountWalletPayloadId', (value) => typeof value === 'string' && value.startsWith('wallet:')
+    ? true
+    : 'Expected a wallet payload ID starting with "wallet:"');
+const AccountGroupPayloadIdStruct = define('AccountGroupPayloadId', (value) => typeof value === 'string' && PAYLOAD_GROUP_ID_REGEX.test(value)
+    ? true
+    : 'Expected a group payload ID in the form "wallet:<id>/<subId>"');
+const AccountWalletPayloadMetadataStruct = object({
+    name: string(),
+});
+const AccountWalletGroupPayloadMetadataStruct = object({
+    name: string(),
+    pinned: boolean(),
+    hidden: boolean(),
+});
+const AccountWalletPrivateKeyValueStruct = object({
+    privateKey: sensitive(BytesStruct),
+    encoding: enums(Object.values(AccountWalletPrivateKeyEncoding)),
+    type: exactOptional(KeyringAccountTypeStruct),
+});
+const AccountWalletMnemonicGroupEntryStruct = object({
+    id: AccountGroupPayloadIdStruct,
+    groupIndex: integer(),
+    metadata: AccountWalletGroupPayloadMetadataStruct,
+});
+const AccountWalletPrivateKeyGroupEntryStruct = object({
+    id: AccountGroupPayloadIdStruct,
+    value: exactOptional(AccountWalletPrivateKeyValueStruct),
+    metadata: AccountWalletGroupPayloadMetadataStruct,
+});
+// The `groups` array in a mnemonic wallet payload must have contiguous group indices starting at 0.
+const AccountWalletMnemonicGroupsStruct = refine(array(AccountWalletMnemonicGroupEntryStruct), 'contiguous-group-indices', (groups) => {
+    let prev;
+    for (const curr of groups) {
+        if (prev === undefined && curr.groupIndex !== 0) {
+            return `group indices must start at 0; got ${curr.groupIndex}`;
+        }
+        if (prev !== undefined && curr.groupIndex !== prev.groupIndex + 1) {
+            return `group indices must be contiguous and sorted; found gap between index ${prev.groupIndex} and ${curr.groupIndex}`;
+        }
+        prev = curr;
+    }
+    return true;
+});
+const AccountWalletMnemonicPayloadStruct = object({
+    id: AccountWalletPayloadIdStruct,
+    type: literal(AccountWalletPayloadType.Mnemonic),
+    value: exactOptional(sensitive(BytesStruct)),
+    metadata: AccountWalletPayloadMetadataStruct,
+    groups: AccountWalletMnemonicGroupsStruct,
+});
+const AccountWalletPrivateKeyPayloadStruct = object({
+    id: AccountWalletPayloadIdStruct,
+    type: literal(AccountWalletPayloadType.PrivateKey),
+    metadata: AccountWalletPayloadMetadataStruct,
+    groups: array(AccountWalletPrivateKeyGroupEntryStruct),
+});
+const AccountTreeWalletEntryStruct = union([
+    AccountWalletMnemonicPayloadStruct,
+    AccountWalletPrivateKeyPayloadStruct,
+]);
+/** Current version of the {@link AccountTreePayload} format. */
+export const ACCOUNT_TREE_PAYLOAD_CURRENT_VERSION = 1;
+/**
+ * Superstruct schema for a fully versioned {@link AccountTreePayload}.
+ *
+ * Pins `version` to exactly {@link ACCOUNT_TREE_PAYLOAD_CURRENT_VERSION} so
+ * payloads from newer clients (v2+) are rejected rather than silently
+ * mis-handled as v1. Once a migration framework is wired up in
+ * {@link AccountTreeSnapshot.deserialize}, older versions will be up-migrated
+ * before this struct is checked, and newer versions will require a new struct.
+ *
+ * Secret fields (`value`, `privateKey`) use the Superstruct `sensitive()`
+ * wrapper so validation failures redact secrets from error output.
+ */
+export const AccountTreePayloadStruct = object({
+    version: literal(ACCOUNT_TREE_PAYLOAD_CURRENT_VERSION),
+    wallets: array(AccountTreeWalletEntryStruct),
+});
+/**
+ * Asserts that `value` conforms to the v1 {@link AccountTreePayload} schema.
+ *
+ * Prefer {@link AccountTreeSnapshot.deserialize} at transport boundaries so
+ * validation stays paired with snapshot construction. Use this helper when you
+ * already hold a parsed object and need to assert its shape before further
+ * processing.
+ *
+ * @param value - Value to validate.
+ * @throws If `value` is not a valid v1 payload, including unsupported wallet types.
+ */
+export function assertAccountTreePayload(value) {
+    try {
+        // AccountTreePayloadStruct pins version to ACCOUNT_TREE_PAYLOAD_CURRENT_VERSION,
+        // so unknown future versions are rejected here rather than silently mis-handled.
+        assert(value, AccountTreePayloadStruct);
+    }
+    catch (error) {
+        if (error instanceof StructError) {
+            throw new Error(`Invalid AccountTreePayload: ${formatValidationErrorMessages(error)}`);
+        }
+        /* istanbul ignore next */
+        throw error;
+    }
+}
+//# sourceMappingURL=payload.mjs.map

package/dist/state/payload.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.mjs","sourceRoot":"","sources":["../../src/state/payload.ts"],"names":[],"mappings":"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","sourcesContent":["import { KeyringAccountTypeStruct } from '@metamask/keyring-api';\nimport type { KeyringAccount } from '@metamask/keyring-api';\nimport {\n  array,\n  assert,\n  boolean,\n  define,\n  enums,\n  integer,\n  literal,\n  object,\n  exactOptional,\n  refine,\n  sensitive,\n  string,\n  StructError,\n  union,\n} from '@metamask/superstruct';\nimport type { Infer } from '@metamask/superstruct';\n\nimport type { DeepReadonly, EncodedBytes } from './utils.js';\nimport { BytesStruct, formatValidationErrorMessages } from './utils.js';\n\n/** Stable cross-device wallet identifier. Format: `wallet:<entropySourceId>`. */\nexport type AccountWalletPayloadId = `wallet:${string}`;\n\n/** Stable cross-device group identifier. Format: `wallet:<entropySourceId>/<groupSubId>`. */\nexport type AccountGroupPayloadId = `${AccountWalletPayloadId}/${string}`;\n\n/**\n * Parsed representation of an {@link AccountGroupPayloadId}.\n */\nexport type ParsedPayloadGroupId = {\n  /** The wallet portion of the group ID. */\n  walletId: AccountWalletPayloadId;\n  /** The group-specific sub-ID (e.g. group index for mnemonic wallets, address for private-key wallets). */\n  subId: string;\n};\n\nconst PAYLOAD_GROUP_ID_REGEX = /^(?<walletId>wallet:[^/]+)\\/(?<subId>.+)$/u;\n\n/**\n * Parses a payload group ID into its wallet ID and group sub-ID components.\n *\n * @param groupId - The payload group ID to parse.\n * @returns The parsed wallet ID and group sub-ID.\n * @throws If the group ID format is invalid.\n */\nexport function parsePayloadGroupId(\n  groupId: AccountGroupPayloadId,\n): ParsedPayloadGroupId {\n  const match = PAYLOAD_GROUP_ID_REGEX.exec(groupId);\n  if (!match?.groups) {\n    throw new Error(`Invalid payload group ID: \"${groupId}\"`);\n  }\n  return {\n    walletId: match.groups.walletId as AccountWalletPayloadId,\n    subId: match.groups.subId,\n  };\n}\n\n/**\n * Wallet type discriminants used in serialized {@link AccountTreePayload} entries.\n *\n * Use these constants instead of raw string literals so callers get autocomplete\n * and a single source of truth for the discriminant values.\n */\nexport const AccountWalletPayloadType = {\n  Mnemonic: 'mnemonic',\n  PrivateKey: 'private-key',\n} as const;\n\nexport type AccountWalletPayloadType =\n  (typeof AccountWalletPayloadType)[keyof typeof AccountWalletPayloadType];\n\n/** Wallet-level metadata carried in every payload wallet entry. */\nexport type AccountWalletPayloadMetadata = { name: string };\n\n/** Group-level metadata carried in every payload group entry. */\nexport type AccountWalletGroupPayloadMetadata = {\n  name: string;\n  pinned: boolean;\n  hidden: boolean;\n};\n\n/** A single group entry inside an {@link AccountWalletMnemonicPayload}. */\nexport type AccountWalletMnemonicGroupEntry = {\n  /** Stable group payload ID. Format: `<walletPayloadId>/<groupIndex>`. */\n  id: AccountGroupPayloadId;\n  /** BIP-44 account index this group was derived at. */\n  groupIndex: number;\n  metadata: AccountWalletGroupPayloadMetadata;\n};\n\n/**\n * Encoding formats for exported private key material.\n */\nexport const AccountWalletPrivateKeyEncoding = {\n  Hexadecimal: 'hexadecimal',\n  Base58: 'base58',\n  Base32: 'base32',\n} as const;\n\nexport type AccountWalletPrivateKeyEncoding =\n  (typeof AccountWalletPrivateKeyEncoding)[keyof typeof AccountWalletPrivateKeyEncoding];\n\n/** A single group entry inside an {@link AccountWalletPrivateKeyPayload}. */\nexport type AccountWalletPrivateKeyGroupEntry = {\n  /** Stable group payload ID. Format: `wallet:private-key/<address>`. */\n  id: AccountGroupPayloadId;\n  /**\n   * Private key material. Shape matches `ExportedAccount` from `@metamask/keyring-api/v2`\n   * so the importer knows how to decode the key without additional out-of-band information.\n   * Absent in metadata-only exports.\n   */\n  value?: {\n    privateKey: EncodedBytes;\n    encoding: AccountWalletPrivateKeyEncoding;\n    /**\n     * Account type from `KeyringAccountType` (e.g. `'eip155:eoa'`, `'bip122:p2wpkh'`).\n     * Absent for EVM accounts -- import via `SimpleKeyring`.\n     * Present for non-EVM accounts -- routing to the BIP-44 Snap handling this type is not yet implemented.\n     */\n    type?: KeyringAccount['type'];\n  };\n  metadata: AccountWalletGroupPayloadMetadata;\n};\n\n/** Payload entry for an HD (entropy) wallet and its derived account groups. */\nexport type AccountWalletMnemonicPayload = {\n  id: AccountWalletPayloadId;\n  type: typeof AccountWalletPayloadType.Mnemonic;\n  /** BIP-39 mnemonic phrase encoded as bytes. Absent in metadata-only exports. */\n  value?: EncodedBytes;\n  metadata: AccountWalletPayloadMetadata;\n  groups: AccountWalletMnemonicGroupEntry[];\n};\n\n/**\n * Payload entry for all imported private-key accounts.\n *\n * All local simple-keyring wallets are merged into this single entry;\n * each account is represented as a separate group entry keyed by address.\n */\nexport type AccountWalletPrivateKeyPayload = {\n  id: AccountWalletPayloadId;\n  type: typeof AccountWalletPayloadType.PrivateKey;\n  metadata: AccountWalletPayloadMetadata;\n  groups: AccountWalletPrivateKeyGroupEntry[];\n};\n\n/** Union of all wallet entry types that can appear in an {@link AccountTreePayload}. */\nexport type AccountTreeWalletEntry =\n  | AccountWalletMnemonicPayload\n  | AccountWalletPrivateKeyPayload;\n\n/** Portable snapshot of the full account tree state (flat versioned format). */\nexport type AccountTreePayload = {\n  version: number;\n  wallets: AccountTreeWalletEntry[];\n};\n\n/**\n * Deeply read-only wallet view passed to {@link AccountTreeSnapshot.filterWallets}\n * and {@link AccountTreeSnapshot.filterAllGroups} predicates.\n *\n * Entries are deep-cloned and deep-frozen when a snapshot is constructed, so\n * callers cannot mutate wallet IDs, types, secrets, metadata, or groups.\n */\nexport type AccountTreeSnapshotWallet = DeepReadonly<\n  AccountWalletMnemonicPayload | AccountWalletPrivateKeyPayload\n>;\n\n/**\n * Deeply read-only group view passed to {@link AccountTreeSnapshot.filterGroups}\n * and {@link AccountTreeSnapshot.filterAllGroups} predicates.\n *\n * Entries are deep-cloned and deep-frozen when a snapshot is constructed, so\n * callers cannot mutate group IDs, secrets, metadata, or parent wallet references.\n */\nexport type AccountTreeSnapshotGroup = DeepReadonly<\n  AccountWalletMnemonicGroupEntry | AccountWalletPrivateKeyGroupEntry\n>;\n\n/**\n * Constructs an {@link AccountWalletPayloadId} from an entropy source ID.\n *\n * @param entropySourceId - Stable entropy source ID returned by `HdKeyring.toEntropySourceId()`.\n * @returns The portable wallet payload ID.\n */\nexport function toWalletPayloadId(\n  entropySourceId: string,\n): AccountWalletPayloadId {\n  return `wallet:${entropySourceId}`;\n}\n\n/**\n * Constructs an {@link AccountGroupPayloadId} from a wallet payload ID and a sub-ID.\n *\n * @param walletId - The wallet payload ID this group belongs to.\n * @param subId - The group-specific sub-ID (e.g. group index for mnemonic wallets, address for private-key wallets).\n * @returns The portable group payload ID.\n */\nexport function toGroupPayloadId(\n  walletId: AccountWalletPayloadId,\n  subId: string | number,\n): AccountGroupPayloadId {\n  return `${walletId}/${subId}`;\n}\n\n/** Options accepted by {@link AccountTreeController.exportState}. */\nexport type ExportStateOptions = {\n  /** When `true`, secrets (mnemonic / private keys) are included. Requires the vault to be unlocked. */\n  includeSecrets?: boolean;\n};\n\nconst AccountWalletPayloadIdStruct = define<AccountWalletPayloadId>(\n  'AccountWalletPayloadId',\n  (value) =>\n    typeof value === 'string' && value.startsWith('wallet:')\n      ? true\n      : 'Expected a wallet payload ID starting with \"wallet:\"',\n);\n\nconst AccountGroupPayloadIdStruct = define<AccountGroupPayloadId>(\n  'AccountGroupPayloadId',\n  (value) =>\n    typeof value === 'string' && PAYLOAD_GROUP_ID_REGEX.test(value)\n      ? true\n      : 'Expected a group payload ID in the form \"wallet:<id>/<subId>\"',\n);\n\nconst AccountWalletPayloadMetadataStruct = object({\n  name: string(),\n});\n\nconst AccountWalletGroupPayloadMetadataStruct = object({\n  name: string(),\n  pinned: boolean(),\n  hidden: boolean(),\n});\n\nconst AccountWalletPrivateKeyValueStruct = object({\n  privateKey: sensitive(BytesStruct),\n  encoding: enums(Object.values(AccountWalletPrivateKeyEncoding)),\n  type: exactOptional(KeyringAccountTypeStruct),\n});\n\nconst AccountWalletMnemonicGroupEntryStruct = object({\n  id: AccountGroupPayloadIdStruct,\n  groupIndex: integer(),\n  metadata: AccountWalletGroupPayloadMetadataStruct,\n});\n\nconst AccountWalletPrivateKeyGroupEntryStruct = object({\n  id: AccountGroupPayloadIdStruct,\n  value: exactOptional(AccountWalletPrivateKeyValueStruct),\n  metadata: AccountWalletGroupPayloadMetadataStruct,\n});\n\n// The `groups` array in a mnemonic wallet payload must have contiguous group indices starting at 0.\nconst AccountWalletMnemonicGroupsStruct = refine(\n  array(AccountWalletMnemonicGroupEntryStruct),\n  'contiguous-group-indices',\n  (groups) => {\n    let prev: AccountWalletMnemonicGroupEntry | undefined;\n    for (const curr of groups) {\n      if (prev === undefined && curr.groupIndex !== 0) {\n        return `group indices must start at 0; got ${curr.groupIndex}`;\n      }\n      if (prev !== undefined && curr.groupIndex !== prev.groupIndex + 1) {\n        return `group indices must be contiguous and sorted; found gap between index ${prev.groupIndex} and ${curr.groupIndex}`;\n      }\n      prev = curr;\n    }\n    return true;\n  },\n);\n\nconst AccountWalletMnemonicPayloadStruct = object({\n  id: AccountWalletPayloadIdStruct,\n  type: literal(AccountWalletPayloadType.Mnemonic),\n  value: exactOptional(sensitive(BytesStruct)),\n  metadata: AccountWalletPayloadMetadataStruct,\n  groups: AccountWalletMnemonicGroupsStruct,\n});\n\nconst AccountWalletPrivateKeyPayloadStruct = object({\n  id: AccountWalletPayloadIdStruct,\n  type: literal(AccountWalletPayloadType.PrivateKey),\n  metadata: AccountWalletPayloadMetadataStruct,\n  groups: array(AccountWalletPrivateKeyGroupEntryStruct),\n});\n\nconst AccountTreeWalletEntryStruct = union([\n  AccountWalletMnemonicPayloadStruct,\n  AccountWalletPrivateKeyPayloadStruct,\n]);\n\n/** Current version of the {@link AccountTreePayload} format. */\nexport const ACCOUNT_TREE_PAYLOAD_CURRENT_VERSION = 1;\n\n/**\n * Superstruct schema for a fully versioned {@link AccountTreePayload}.\n *\n * Pins `version` to exactly {@link ACCOUNT_TREE_PAYLOAD_CURRENT_VERSION} so\n * payloads from newer clients (v2+) are rejected rather than silently\n * mis-handled as v1. Once a migration framework is wired up in\n * {@link AccountTreeSnapshot.deserialize}, older versions will be up-migrated\n * before this struct is checked, and newer versions will require a new struct.\n *\n * Secret fields (`value`, `privateKey`) use the Superstruct `sensitive()`\n * wrapper so validation failures redact secrets from error output.\n */\nexport const AccountTreePayloadStruct = object({\n  version: literal(ACCOUNT_TREE_PAYLOAD_CURRENT_VERSION),\n  wallets: array(AccountTreeWalletEntryStruct),\n});\n\n/** Inferred TypeScript type for a value matching {@link AccountTreePayloadStruct}. */\nexport type AccountTreePayloadStructType = Infer<\n  typeof AccountTreePayloadStruct\n>;\n\n/**\n * Asserts that `value` conforms to the v1 {@link AccountTreePayload} schema.\n *\n * Prefer {@link AccountTreeSnapshot.deserialize} at transport boundaries so\n * validation stays paired with snapshot construction. Use this helper when you\n * already hold a parsed object and need to assert its shape before further\n * processing.\n *\n * @param value - Value to validate.\n * @throws If `value` is not a valid v1 payload, including unsupported wallet types.\n */\nexport function assertAccountTreePayload(\n  value: unknown,\n): asserts value is AccountTreePayload {\n  try {\n    // AccountTreePayloadStruct pins version to ACCOUNT_TREE_PAYLOAD_CURRENT_VERSION,\n    // so unknown future versions are rejected here rather than silently mis-handled.\n    assert(value, AccountTreePayloadStruct);\n  } catch (error) {\n    if (error instanceof StructError) {\n      throw new Error(\n        `Invalid AccountTreePayload: ${formatValidationErrorMessages(error)}`,\n      );\n    }\n    /* istanbul ignore next */\n    throw error;\n  }\n}\n"]}

package/dist/state/snapshot.cjs

@@ -0,0 +1,202 @@
+"use strict";
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _AccountTreeSnapshot_entries, _AccountTreeSnapshot_idMap;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccountTreeSnapshot = void 0;
+const payload_js_1 = require("./payload.cjs");
+const utils_js_1 = require("./utils.cjs");
+/**
+ * Immutable value object returned by {@link AccountTreeController.exportState}.
+ *
+ * Construct with {@link AccountTreeController.exportState},
+ * {@link AccountTreeSnapshot.deserialize}, or `new AccountTreeSnapshot(...)`
+ * for tests and advanced use.
+ *
+ * Wallet and group entries are deep-cloned and deep-frozen once in the
+ * constructor. Filtering predicates receive those read-only views directly;
+ * each filter method returns a new snapshot that repeats the process for its
+ * result.
+ *
+ * An optional ID map (local ↔ payload) may be supplied when bridging between
+ * internal controller IDs and the stable cross-device IDs in the serialized
+ * payload. The map covers the original export and is preserved unchanged
+ * through filtering until {@link serialize}. Omit it when deterministic IDs
+ * make {@link toLocalId} / {@link toPayloadId} unnecessary.
+ */
+class AccountTreeSnapshot {
+    /**
+     * @param entries - Wallet entries in the snapshot.
+     * @param idMap - Optional local ↔ payload ID map from export.
+     */
+    constructor(entries, idMap) {
+        _AccountTreeSnapshot_entries.set(this, void 0);
+        _AccountTreeSnapshot_idMap.set(this, void 0);
+        __classPrivateFieldSet(this, _AccountTreeSnapshot_entries, (0, utils_js_1.deepFreeze)(structuredClone(entries)), "f");
+        __classPrivateFieldSet(this, _AccountTreeSnapshot_idMap, idMap, "f");
+    }
+    /**
+     * Returns a new snapshot containing only the wallets for which
+     * `predicate` returns `true`.
+     *
+     * When filtering by wallet ID, compare against stable payload IDs from
+     * {@link serialize} or convert local IDs with {@link toPayloadId} first.
+     *
+     * @param predicate - Function called with each deeply read-only wallet entry.
+     * @returns A filtered snapshot.
+     */
+    filterWallets(predicate) {
+        const filteredEntries = __classPrivateFieldGet(this, _AccountTreeSnapshot_entries, "f").filter((entry) => predicate(entry));
+        return new AccountTreeSnapshot(filteredEntries, __classPrivateFieldGet(this, _AccountTreeSnapshot_idMap, "f"));
+    }
+    /**
+     * Filters groups within one wallet. Other wallets are left unchanged.
+     *
+     * Throws if `walletId` does not identify a wallet in the snapshot.
+     * Removes the wallet if no groups remain after filtering — this prevents a
+     * mnemonic wallet with zero selected groups from still transferring its secret.
+     *
+     * **Mnemonic wallets:** group indices must remain contiguous starting at 0
+     * after filtering, because the payload schema enforces this invariant.
+     * Predicates that produce gaps (e.g. keeping only index 1, or 0 and 2) will
+     * cause {@link AccountTreeSnapshot.deserialize} to reject the payload on the
+     * receiving end.
+     *
+     * @param walletId - Stable payload wallet ID to filter groups within.
+     * @param predicate - Function called with each deeply read-only group entry.
+     * @returns A filtered snapshot.
+     * @throws If `walletId` is not present in the snapshot.
+     */
+    filterGroups(walletId, predicate) {
+        const walletIndex = __classPrivateFieldGet(this, _AccountTreeSnapshot_entries, "f").findIndex((entry) => entry.id === walletId);
+        if (walletIndex === -1) {
+            throw new Error(`Cannot filter groups: wallet "${walletId}" not found in snapshot`);
+        }
+        const wallet = __classPrivateFieldGet(this, _AccountTreeSnapshot_entries, "f")[walletIndex];
+        const filteredGroups = wallet.groups.filter((group) => predicate(group));
+        const filteredEntries = [...__classPrivateFieldGet(this, _AccountTreeSnapshot_entries, "f")];
+        if (filteredGroups.length === 0) {
+            filteredEntries.splice(walletIndex, 1);
+        }
+        else if (wallet.type === payload_js_1.AccountWalletPayloadType.Mnemonic) {
+            filteredEntries[walletIndex] = {
+                ...wallet,
+                groups: filteredGroups,
+            };
+        }
+        else {
+            filteredEntries[walletIndex] = {
+                ...wallet,
+                groups: filteredGroups,
+            };
+        }
+        return new AccountTreeSnapshot(filteredEntries, __classPrivateFieldGet(this, _AccountTreeSnapshot_idMap, "f"));
+    }
+    /**
+     * Filters groups across every wallet.
+     *
+     * The parent wallet is provided as context to the predicate. Removes any
+     * wallet with no remaining groups after filtering.
+     *
+     * **Mnemonic wallets:** see {@link filterGroups} for the contiguous-index
+     * constraint that applies here as well.
+     *
+     * @param predicate - Function called with each group and its parent wallet.
+     * @returns A filtered snapshot.
+     */
+    filterAllGroups(predicate) {
+        const filteredEntries = [];
+        for (const wallet of __classPrivateFieldGet(this, _AccountTreeSnapshot_entries, "f")) {
+            const filteredGroups = wallet.groups.filter((group) => predicate(group, wallet));
+            if (filteredGroups.length === 0) {
+                continue;
+            }
+            if (wallet.type === payload_js_1.AccountWalletPayloadType.Mnemonic) {
+                filteredEntries.push({
+                    ...wallet,
+                    groups: filteredGroups,
+                });
+            }
+            else {
+                filteredEntries.push({
+                    ...wallet,
+                    groups: filteredGroups,
+                });
+            }
+        }
+        return new AccountTreeSnapshot(filteredEntries, __classPrivateFieldGet(this, _AccountTreeSnapshot_idMap, "f"));
+    }
+    /**
+     * Converts a payload ID (wallet or group) to the corresponding local
+     * `AccountTreeController` ID.
+     *
+     * The map reflects the original export, not the wallets/groups currently
+     * retained in this snapshot after filtering.
+     *
+     * @param payloadId - Stable cross-device wallet or group payload ID.
+     * @returns The local controller ID, or `undefined` if not found or no ID map is present.
+     */
+    toLocalId(payloadId) {
+        return __classPrivateFieldGet(this, _AccountTreeSnapshot_idMap, "f")?.getLocalId(payloadId);
+    }
+    /**
+     * Converts a local `AccountTreeController` ID (wallet or group) to its
+     * stable cross-device payload ID.
+     *
+     * The map reflects the original export, not the wallets/groups currently
+     * retained in this snapshot after filtering.
+     *
+     * @param localId - Local controller wallet or group ID.
+     * @returns The payload ID, or `undefined` if not found or no ID map is present.
+     */
+    toPayloadId(localId) {
+        return __classPrivateFieldGet(this, _AccountTreeSnapshot_idMap, "f")?.getPayloadId(localId);
+    }
+    /**
+     * Serializes the snapshot to a flat {@link AccountTreePayload} with `version` inlined
+     * alongside the wallet entries.
+     *
+     * Returns the constructor-frozen wallet tree without copying it again.
+     *
+     * @returns The versioned flat payload.
+     */
+    serialize() {
+        return {
+            version: payload_js_1.ACCOUNT_TREE_PAYLOAD_CURRENT_VERSION,
+            wallets: __classPrivateFieldGet(this, _AccountTreeSnapshot_entries, "f"),
+        };
+    }
+    /**
+     * Validates a raw value as an {@link AccountTreePayload}, running any
+     * necessary version migrations, and returns an immutable snapshot.
+     *
+     * This is the entry point for untrusted serialized data. Unsupported schema
+     * versions and wallet types fail closed with an error instead of returning a
+     * partial snapshot.
+     *
+     * The returned snapshot has no ID map — {@link toLocalId} / {@link toPayloadId}
+     * return `undefined`. Pass an {@link IdMap} to the constructor when you need
+     * the map.
+     *
+     * @param raw - Unknown value to parse.
+     * @returns A validated snapshot.
+     * @throws If `raw` is not a valid payload or its version is unsupported.
+     */
+    static async deserialize(raw) {
+        // TODO: Use migration framework here.
+        (0, payload_js_1.assertAccountTreePayload)(raw);
+        return new AccountTreeSnapshot(raw.wallets);
+    }
+}
+exports.AccountTreeSnapshot = AccountTreeSnapshot;
+_AccountTreeSnapshot_entries = new WeakMap(), _AccountTreeSnapshot_idMap = new WeakMap();
+//# sourceMappingURL=snapshot.cjs.map

package/dist/state/snapshot.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.cjs","sourceRoot":"","sources":["../../src/state/snapshot.ts"],"names":[],"mappings":"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","sourcesContent":["import type { IdMap } from './id-map.js';\nimport type {\n  AccountGroupPayloadId,\n  AccountTreePayload,\n  AccountTreeSnapshotGroup,\n  AccountTreeSnapshotWallet,\n  AccountTreeWalletEntry,\n  AccountWalletMnemonicGroupEntry,\n  AccountWalletPayloadId,\n  AccountWalletPrivateKeyGroupEntry,\n} from './payload.js';\nimport {\n  AccountWalletPayloadType,\n  assertAccountTreePayload,\n  ACCOUNT_TREE_PAYLOAD_CURRENT_VERSION,\n} from './payload.js';\nimport { deepFreeze } from './utils.js';\n\n/**\n * Immutable value object returned by {@link AccountTreeController.exportState}.\n *\n * Construct with {@link AccountTreeController.exportState},\n * {@link AccountTreeSnapshot.deserialize}, or `new AccountTreeSnapshot(...)`\n * for tests and advanced use.\n *\n * Wallet and group entries are deep-cloned and deep-frozen once in the\n * constructor. Filtering predicates receive those read-only views directly;\n * each filter method returns a new snapshot that repeats the process for its\n * result.\n *\n * An optional ID map (local ↔ payload) may be supplied when bridging between\n * internal controller IDs and the stable cross-device IDs in the serialized\n * payload. The map covers the original export and is preserved unchanged\n * through filtering until {@link serialize}. Omit it when deterministic IDs\n * make {@link toLocalId} / {@link toPayloadId} unnecessary.\n */\nexport class AccountTreeSnapshot {\n  readonly #entries: AccountTreeWalletEntry[];\n\n  readonly #idMap: IdMap | undefined;\n\n  /**\n   * @param entries - Wallet entries in the snapshot.\n   * @param idMap - Optional local ↔ payload ID map from export.\n   */\n  constructor(entries: AccountTreeWalletEntry[], idMap?: IdMap) {\n    this.#entries = deepFreeze(structuredClone(entries));\n    this.#idMap = idMap;\n  }\n\n  /**\n   * Returns a new snapshot containing only the wallets for which\n   * `predicate` returns `true`.\n   *\n   * When filtering by wallet ID, compare against stable payload IDs from\n   * {@link serialize} or convert local IDs with {@link toPayloadId} first.\n   *\n   * @param predicate - Function called with each deeply read-only wallet entry.\n   * @returns A filtered snapshot.\n   */\n  filterWallets(\n    predicate: (wallet: AccountTreeSnapshotWallet) => boolean,\n  ): AccountTreeSnapshot {\n    const filteredEntries = this.#entries.filter((entry) =>\n      predicate(entry as AccountTreeSnapshotWallet),\n    );\n\n    return new AccountTreeSnapshot(filteredEntries, this.#idMap);\n  }\n\n  /**\n   * Filters groups within one wallet. Other wallets are left unchanged.\n   *\n   * Throws if `walletId` does not identify a wallet in the snapshot.\n   * Removes the wallet if no groups remain after filtering — this prevents a\n   * mnemonic wallet with zero selected groups from still transferring its secret.\n   *\n   * **Mnemonic wallets:** group indices must remain contiguous starting at 0\n   * after filtering, because the payload schema enforces this invariant.\n   * Predicates that produce gaps (e.g. keeping only index 1, or 0 and 2) will\n   * cause {@link AccountTreeSnapshot.deserialize} to reject the payload on the\n   * receiving end.\n   *\n   * @param walletId - Stable payload wallet ID to filter groups within.\n   * @param predicate - Function called with each deeply read-only group entry.\n   * @returns A filtered snapshot.\n   * @throws If `walletId` is not present in the snapshot.\n   */\n  filterGroups(\n    walletId: AccountWalletPayloadId,\n    predicate: (group: AccountTreeSnapshotGroup) => boolean,\n  ): AccountTreeSnapshot {\n    const walletIndex = this.#entries.findIndex(\n      (entry) => entry.id === walletId,\n    );\n    if (walletIndex === -1) {\n      throw new Error(\n        `Cannot filter groups: wallet \"${walletId}\" not found in snapshot`,\n      );\n    }\n\n    const wallet = this.#entries[walletIndex];\n\n    const filteredGroups = wallet.groups.filter((group) =>\n      predicate(group as AccountTreeSnapshotGroup),\n    );\n\n    const filteredEntries = [...this.#entries];\n    if (filteredGroups.length === 0) {\n      filteredEntries.splice(walletIndex, 1);\n    } else if (wallet.type === AccountWalletPayloadType.Mnemonic) {\n      filteredEntries[walletIndex] = {\n        ...wallet,\n        groups: filteredGroups as AccountWalletMnemonicGroupEntry[],\n      };\n    } else {\n      filteredEntries[walletIndex] = {\n        ...wallet,\n        groups: filteredGroups as AccountWalletPrivateKeyGroupEntry[],\n      };\n    }\n\n    return new AccountTreeSnapshot(filteredEntries, this.#idMap);\n  }\n\n  /**\n   * Filters groups across every wallet.\n   *\n   * The parent wallet is provided as context to the predicate. Removes any\n   * wallet with no remaining groups after filtering.\n   *\n   * **Mnemonic wallets:** see {@link filterGroups} for the contiguous-index\n   * constraint that applies here as well.\n   *\n   * @param predicate - Function called with each group and its parent wallet.\n   * @returns A filtered snapshot.\n   */\n  filterAllGroups(\n    predicate: (\n      group: AccountTreeSnapshotGroup,\n      wallet: AccountTreeSnapshotWallet,\n    ) => boolean,\n  ): AccountTreeSnapshot {\n    const filteredEntries: AccountTreeWalletEntry[] = [];\n\n    for (const wallet of this.#entries) {\n      const filteredGroups = wallet.groups.filter((group) =>\n        predicate(\n          group as AccountTreeSnapshotGroup,\n          wallet as AccountTreeSnapshotWallet,\n        ),\n      );\n\n      if (filteredGroups.length === 0) {\n        continue;\n      }\n\n      if (wallet.type === AccountWalletPayloadType.Mnemonic) {\n        filteredEntries.push({\n          ...wallet,\n          groups: filteredGroups as AccountWalletMnemonicGroupEntry[],\n        });\n      } else {\n        filteredEntries.push({\n          ...wallet,\n          groups: filteredGroups as AccountWalletPrivateKeyGroupEntry[],\n        });\n      }\n    }\n\n    return new AccountTreeSnapshot(filteredEntries, this.#idMap);\n  }\n\n  /**\n   * Converts a payload ID (wallet or group) to the corresponding local\n   * `AccountTreeController` ID.\n   *\n   * The map reflects the original export, not the wallets/groups currently\n   * retained in this snapshot after filtering.\n   *\n   * @param payloadId - Stable cross-device wallet or group payload ID.\n   * @returns The local controller ID, or `undefined` if not found or no ID map is present.\n   */\n  toLocalId(\n    payloadId: AccountWalletPayloadId | AccountGroupPayloadId,\n  ): ReturnType<IdMap['getLocalId']> {\n    return this.#idMap?.getLocalId(payloadId);\n  }\n\n  /**\n   * Converts a local `AccountTreeController` ID (wallet or group) to its\n   * stable cross-device payload ID.\n   *\n   * The map reflects the original export, not the wallets/groups currently\n   * retained in this snapshot after filtering.\n   *\n   * @param localId - Local controller wallet or group ID.\n   * @returns The payload ID, or `undefined` if not found or no ID map is present.\n   */\n  toPayloadId(\n    localId: Parameters<IdMap['add']>[0],\n  ): ReturnType<IdMap['getPayloadId']> {\n    return this.#idMap?.getPayloadId(localId);\n  }\n\n  /**\n   * Serializes the snapshot to a flat {@link AccountTreePayload} with `version` inlined\n   * alongside the wallet entries.\n   *\n   * Returns the constructor-frozen wallet tree without copying it again.\n   *\n   * @returns The versioned flat payload.\n   */\n  serialize(): AccountTreePayload {\n    return {\n      version: ACCOUNT_TREE_PAYLOAD_CURRENT_VERSION,\n      wallets: this.#entries,\n    };\n  }\n\n  /**\n   * Validates a raw value as an {@link AccountTreePayload}, running any\n   * necessary version migrations, and returns an immutable snapshot.\n   *\n   * This is the entry point for untrusted serialized data. Unsupported schema\n   * versions and wallet types fail closed with an error instead of returning a\n   * partial snapshot.\n   *\n   * The returned snapshot has no ID map — {@link toLocalId} / {@link toPayloadId}\n   * return `undefined`. Pass an {@link IdMap} to the constructor when you need\n   * the map.\n   *\n   * @param raw - Unknown value to parse.\n   * @returns A validated snapshot.\n   * @throws If `raw` is not a valid payload or its version is unsupported.\n   */\n  static async deserialize(raw: unknown): Promise<AccountTreeSnapshot> {\n    // TODO: Use migration framework here.\n    assertAccountTreePayload(raw);\n    return new AccountTreeSnapshot(raw.wallets);\n  }\n}\n"]}

package/dist/state/snapshot.d.cts

@@ -0,0 +1,120 @@
+import type { IdMap } from "./id-map.cjs";
+import type { AccountGroupPayloadId, AccountTreePayload, AccountTreeSnapshotGroup, AccountTreeSnapshotWallet, AccountTreeWalletEntry, AccountWalletPayloadId } from "./payload.cjs";
+/**
+ * Immutable value object returned by {@link AccountTreeController.exportState}.
+ *
+ * Construct with {@link AccountTreeController.exportState},
+ * {@link AccountTreeSnapshot.deserialize}, or `new AccountTreeSnapshot(...)`
+ * for tests and advanced use.
+ *
+ * Wallet and group entries are deep-cloned and deep-frozen once in the
+ * constructor. Filtering predicates receive those read-only views directly;
+ * each filter method returns a new snapshot that repeats the process for its
+ * result.
+ *
+ * An optional ID map (local ↔ payload) may be supplied when bridging between
+ * internal controller IDs and the stable cross-device IDs in the serialized
+ * payload. The map covers the original export and is preserved unchanged
+ * through filtering until {@link serialize}. Omit it when deterministic IDs
+ * make {@link toLocalId} / {@link toPayloadId} unnecessary.
+ */
+export declare class AccountTreeSnapshot {
+    #private;
+    /**
+     * @param entries - Wallet entries in the snapshot.
+     * @param idMap - Optional local ↔ payload ID map from export.
+     */
+    constructor(entries: AccountTreeWalletEntry[], idMap?: IdMap);
+    /**
+     * Returns a new snapshot containing only the wallets for which
+     * `predicate` returns `true`.
+     *
+     * When filtering by wallet ID, compare against stable payload IDs from
+     * {@link serialize} or convert local IDs with {@link toPayloadId} first.
+     *
+     * @param predicate - Function called with each deeply read-only wallet entry.
+     * @returns A filtered snapshot.
+     */
+    filterWallets(predicate: (wallet: AccountTreeSnapshotWallet) => boolean): AccountTreeSnapshot;
+    /**
+     * Filters groups within one wallet. Other wallets are left unchanged.
+     *
+     * Throws if `walletId` does not identify a wallet in the snapshot.
+     * Removes the wallet if no groups remain after filtering — this prevents a
+     * mnemonic wallet with zero selected groups from still transferring its secret.
+     *
+     * **Mnemonic wallets:** group indices must remain contiguous starting at 0
+     * after filtering, because the payload schema enforces this invariant.
+     * Predicates that produce gaps (e.g. keeping only index 1, or 0 and 2) will
+     * cause {@link AccountTreeSnapshot.deserialize} to reject the payload on the
+     * receiving end.
+     *
+     * @param walletId - Stable payload wallet ID to filter groups within.
+     * @param predicate - Function called with each deeply read-only group entry.
+     * @returns A filtered snapshot.
+     * @throws If `walletId` is not present in the snapshot.
+     */
+    filterGroups(walletId: AccountWalletPayloadId, predicate: (group: AccountTreeSnapshotGroup) => boolean): AccountTreeSnapshot;
+    /**
+     * Filters groups across every wallet.
+     *
+     * The parent wallet is provided as context to the predicate. Removes any
+     * wallet with no remaining groups after filtering.
+     *
+     * **Mnemonic wallets:** see {@link filterGroups} for the contiguous-index
+     * constraint that applies here as well.
+     *
+     * @param predicate - Function called with each group and its parent wallet.
+     * @returns A filtered snapshot.
+     */
+    filterAllGroups(predicate: (group: AccountTreeSnapshotGroup, wallet: AccountTreeSnapshotWallet) => boolean): AccountTreeSnapshot;
+    /**
+     * Converts a payload ID (wallet or group) to the corresponding local
+     * `AccountTreeController` ID.
+     *
+     * The map reflects the original export, not the wallets/groups currently
+     * retained in this snapshot after filtering.
+     *
+     * @param payloadId - Stable cross-device wallet or group payload ID.
+     * @returns The local controller ID, or `undefined` if not found or no ID map is present.
+     */
+    toLocalId(payloadId: AccountWalletPayloadId | AccountGroupPayloadId): ReturnType<IdMap['getLocalId']>;
+    /**
+     * Converts a local `AccountTreeController` ID (wallet or group) to its
+     * stable cross-device payload ID.
+     *
+     * The map reflects the original export, not the wallets/groups currently
+     * retained in this snapshot after filtering.
+     *
+     * @param localId - Local controller wallet or group ID.
+     * @returns The payload ID, or `undefined` if not found or no ID map is present.
+     */
+    toPayloadId(localId: Parameters<IdMap['add']>[0]): ReturnType<IdMap['getPayloadId']>;
+    /**
+     * Serializes the snapshot to a flat {@link AccountTreePayload} with `version` inlined
+     * alongside the wallet entries.
+     *
+     * Returns the constructor-frozen wallet tree without copying it again.
+     *
+     * @returns The versioned flat payload.
+     */
+    serialize(): AccountTreePayload;
+    /**
+     * Validates a raw value as an {@link AccountTreePayload}, running any
+     * necessary version migrations, and returns an immutable snapshot.
+     *
+     * This is the entry point for untrusted serialized data. Unsupported schema
+     * versions and wallet types fail closed with an error instead of returning a
+     * partial snapshot.
+     *
+     * The returned snapshot has no ID map — {@link toLocalId} / {@link toPayloadId}
+     * return `undefined`. Pass an {@link IdMap} to the constructor when you need
+     * the map.
+     *
+     * @param raw - Unknown value to parse.
+     * @returns A validated snapshot.
+     * @throws If `raw` is not a valid payload or its version is unsupported.
+     */
+    static deserialize(raw: unknown): Promise<AccountTreeSnapshot>;
+}
+//# sourceMappingURL=snapshot.d.cts.map

package/dist/state/snapshot.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.cts","sourceRoot":"","sources":["../../src/state/snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,qBAAoB;AACzC,OAAO,KAAK,EACV,qBAAqB,EACrB,kBAAkB,EAClB,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,EAEtB,sBAAsB,EAEvB,sBAAqB;AAQtB;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,mBAAmB;;IAK9B;;;OAGG;gBACS,OAAO,EAAE,sBAAsB,EAAE,EAAE,KAAK,CAAC,EAAE,KAAK;IAK5D;;;;;;;;;OASG;IACH,aAAa,CACX,SAAS,EAAE,CAAC,MAAM,EAAE,yBAAyB,KAAK,OAAO,GACxD,mBAAmB;IAQtB;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,CACV,QAAQ,EAAE,sBAAsB,EAChC,SAAS,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,OAAO,GACtD,mBAAmB;IAkCtB;;;;;;;;;;;OAWG;IACH,eAAe,CACb,SAAS,EAAE,CACT,KAAK,EAAE,wBAAwB,EAC/B,MAAM,EAAE,yBAAyB,KAC9B,OAAO,GACX,mBAAmB;IA+BtB;;;;;;;;;OASG;IACH,SAAS,CACP,SAAS,EAAE,sBAAsB,GAAG,qBAAqB,GACxD,UAAU,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAIlC;;;;;;;;;OASG;IACH,WAAW,CACT,OAAO,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GACnC,UAAU,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAIpC;;;;;;;OAOG;IACH,SAAS,IAAI,kBAAkB;IAO/B;;;;;;;;;;;;;;;OAeG;WACU,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAKrE"}