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

package/dist/state/payload.d.cts

@@ -0,0 +1,288 @@
+import type { KeyringAccount } from "@metamask/keyring-api";
+import type { Infer } from "@metamask/superstruct";
+import type { DeepReadonly, EncodedBytes } from "./utils.cjs";
+/** Stable cross-device wallet identifier. Format: `wallet:<entropySourceId>`. */
+export type AccountWalletPayloadId = `wallet:${string}`;
+/** Stable cross-device group identifier. Format: `wallet:<entropySourceId>/<groupSubId>`. */
+export type AccountGroupPayloadId = `${AccountWalletPayloadId}/${string}`;
+/**
+ * Parsed representation of an {@link AccountGroupPayloadId}.
+ */
+export type ParsedPayloadGroupId = {
+    /** The wallet portion of the group ID. */
+    walletId: AccountWalletPayloadId;
+    /** The group-specific sub-ID (e.g. group index for mnemonic wallets, address for private-key wallets). */
+    subId: string;
+};
+/**
+ * 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 declare function parsePayloadGroupId(groupId: AccountGroupPayloadId): ParsedPayloadGroupId;
+/**
+ * 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 declare const AccountWalletPayloadType: {
+    readonly Mnemonic: "mnemonic";
+    readonly PrivateKey: "private-key";
+};
+export type AccountWalletPayloadType = (typeof AccountWalletPayloadType)[keyof typeof AccountWalletPayloadType];
+/** Wallet-level metadata carried in every payload wallet entry. */
+export type AccountWalletPayloadMetadata = {
+    name: string;
+};
+/** Group-level metadata carried in every payload group entry. */
+export type AccountWalletGroupPayloadMetadata = {
+    name: string;
+    pinned: boolean;
+    hidden: boolean;
+};
+/** A single group entry inside an {@link AccountWalletMnemonicPayload}. */
+export type AccountWalletMnemonicGroupEntry = {
+    /** Stable group payload ID. Format: `<walletPayloadId>/<groupIndex>`. */
+    id: AccountGroupPayloadId;
+    /** BIP-44 account index this group was derived at. */
+    groupIndex: number;
+    metadata: AccountWalletGroupPayloadMetadata;
+};
+/**
+ * Encoding formats for exported private key material.
+ */
+export declare const AccountWalletPrivateKeyEncoding: {
+    readonly Hexadecimal: "hexadecimal";
+    readonly Base58: "base58";
+    readonly Base32: "base32";
+};
+export type AccountWalletPrivateKeyEncoding = (typeof AccountWalletPrivateKeyEncoding)[keyof typeof AccountWalletPrivateKeyEncoding];
+/** A single group entry inside an {@link AccountWalletPrivateKeyPayload}. */
+export type AccountWalletPrivateKeyGroupEntry = {
+    /** Stable group payload ID. Format: `wallet:private-key/<address>`. */
+    id: AccountGroupPayloadId;
+    /**
+     * Private key material. Shape matches `ExportedAccount` from `@metamask/keyring-api/v2`
+     * so the importer knows how to decode the key without additional out-of-band information.
+     * Absent in metadata-only exports.
+     */
+    value?: {
+        privateKey: EncodedBytes;
+        encoding: AccountWalletPrivateKeyEncoding;
+        /**
+         * Account type from `KeyringAccountType` (e.g. `'eip155:eoa'`, `'bip122:p2wpkh'`).
+         * Absent for EVM accounts -- import via `SimpleKeyring`.
+         * Present for non-EVM accounts -- routing to the BIP-44 Snap handling this type is not yet implemented.
+         */
+        type?: KeyringAccount['type'];
+    };
+    metadata: AccountWalletGroupPayloadMetadata;
+};
+/** Payload entry for an HD (entropy) wallet and its derived account groups. */
+export type AccountWalletMnemonicPayload = {
+    id: AccountWalletPayloadId;
+    type: typeof AccountWalletPayloadType.Mnemonic;
+    /** BIP-39 mnemonic phrase encoded as bytes. Absent in metadata-only exports. */
+    value?: EncodedBytes;
+    metadata: AccountWalletPayloadMetadata;
+    groups: AccountWalletMnemonicGroupEntry[];
+};
+/**
+ * Payload entry for all imported private-key accounts.
+ *
+ * All local simple-keyring wallets are merged into this single entry;
+ * each account is represented as a separate group entry keyed by address.
+ */
+export type AccountWalletPrivateKeyPayload = {
+    id: AccountWalletPayloadId;
+    type: typeof AccountWalletPayloadType.PrivateKey;
+    metadata: AccountWalletPayloadMetadata;
+    groups: AccountWalletPrivateKeyGroupEntry[];
+};
+/** Union of all wallet entry types that can appear in an {@link AccountTreePayload}. */
+export type AccountTreeWalletEntry = AccountWalletMnemonicPayload | AccountWalletPrivateKeyPayload;
+/** Portable snapshot of the full account tree state (flat versioned format). */
+export type AccountTreePayload = {
+    version: number;
+    wallets: AccountTreeWalletEntry[];
+};
+/**
+ * Deeply read-only wallet view passed to {@link AccountTreeSnapshot.filterWallets}
+ * and {@link AccountTreeSnapshot.filterAllGroups} predicates.
+ *
+ * Entries are deep-cloned and deep-frozen when a snapshot is constructed, so
+ * callers cannot mutate wallet IDs, types, secrets, metadata, or groups.
+ */
+export type AccountTreeSnapshotWallet = DeepReadonly<AccountWalletMnemonicPayload | AccountWalletPrivateKeyPayload>;
+/**
+ * Deeply read-only group view passed to {@link AccountTreeSnapshot.filterGroups}
+ * and {@link AccountTreeSnapshot.filterAllGroups} predicates.
+ *
+ * Entries are deep-cloned and deep-frozen when a snapshot is constructed, so
+ * callers cannot mutate group IDs, secrets, metadata, or parent wallet references.
+ */
+export type AccountTreeSnapshotGroup = DeepReadonly<AccountWalletMnemonicGroupEntry | AccountWalletPrivateKeyGroupEntry>;
+/**
+ * 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 declare function toWalletPayloadId(entropySourceId: string): AccountWalletPayloadId;
+/**
+ * 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 declare function toGroupPayloadId(walletId: AccountWalletPayloadId, subId: string | number): AccountGroupPayloadId;
+/** Options accepted by {@link AccountTreeController.exportState}. */
+export type ExportStateOptions = {
+    /** When `true`, secrets (mnemonic / private keys) are included. Requires the vault to be unlocked. */
+    includeSecrets?: boolean;
+};
+/** Current version of the {@link AccountTreePayload} format. */
+export declare 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 declare const AccountTreePayloadStruct: import("@metamask/superstruct").Struct<{
+    wallets: ({
+        id: `wallet:${string}`;
+        type: "mnemonic";
+        metadata: {
+            name: string;
+        };
+        groups: {
+            id: `wallet:${string}/${string}`;
+            metadata: {
+                name: string;
+                pinned: boolean;
+                hidden: boolean;
+            };
+            groupIndex: number;
+        }[];
+        value?: EncodedBytes | undefined;
+    } | {
+        id: `wallet:${string}`;
+        type: "private-key";
+        metadata: {
+            name: string;
+        };
+        groups: {
+            id: `wallet:${string}/${string}`;
+            metadata: {
+                name: string;
+                pinned: boolean;
+                hidden: boolean;
+            };
+            value?: {
+                privateKey: EncodedBytes;
+                encoding: "hexadecimal" | "base58" | "base32";
+                type?: "eip155:eoa" | "eip155:erc4337" | "bip122:p2pkh" | "bip122:p2sh" | "bip122:p2wpkh" | "bip122:p2tr" | "solana:data-account" | "tron:eoa" | "stellar:account" | "any:account" | undefined;
+            } | undefined;
+        }[];
+    })[];
+    version: 1;
+}, {
+    version: import("@metamask/superstruct").Struct<1, 1>;
+    wallets: import("@metamask/superstruct").Struct<({
+        id: `wallet:${string}`;
+        type: "mnemonic";
+        metadata: {
+            name: string;
+        };
+        groups: {
+            id: `wallet:${string}/${string}`;
+            metadata: {
+                name: string;
+                pinned: boolean;
+                hidden: boolean;
+            };
+            groupIndex: number;
+        }[];
+        value?: EncodedBytes | undefined;
+    } | {
+        id: `wallet:${string}`;
+        type: "private-key";
+        metadata: {
+            name: string;
+        };
+        groups: {
+            id: `wallet:${string}/${string}`;
+            metadata: {
+                name: string;
+                pinned: boolean;
+                hidden: boolean;
+            };
+            value?: {
+                privateKey: EncodedBytes;
+                encoding: "hexadecimal" | "base58" | "base32";
+                type?: "eip155:eoa" | "eip155:erc4337" | "bip122:p2pkh" | "bip122:p2sh" | "bip122:p2wpkh" | "bip122:p2tr" | "solana:data-account" | "tron:eoa" | "stellar:account" | "any:account" | undefined;
+            } | undefined;
+        }[];
+    })[], import("@metamask/superstruct").Struct<{
+        id: `wallet:${string}`;
+        type: "mnemonic";
+        metadata: {
+            name: string;
+        };
+        groups: {
+            id: `wallet:${string}/${string}`;
+            metadata: {
+                name: string;
+                pinned: boolean;
+                hidden: boolean;
+            };
+            groupIndex: number;
+        }[];
+        value?: EncodedBytes | undefined;
+    } | {
+        id: `wallet:${string}`;
+        type: "private-key";
+        metadata: {
+            name: string;
+        };
+        groups: {
+            id: `wallet:${string}/${string}`;
+            metadata: {
+                name: string;
+                pinned: boolean;
+                hidden: boolean;
+            };
+            value?: {
+                privateKey: EncodedBytes;
+                encoding: "hexadecimal" | "base58" | "base32";
+                type?: "eip155:eoa" | "eip155:erc4337" | "bip122:p2pkh" | "bip122:p2sh" | "bip122:p2wpkh" | "bip122:p2tr" | "solana:data-account" | "tron:eoa" | "stellar:account" | "any:account" | undefined;
+            } | undefined;
+        }[];
+    }, null>>;
+}>;
+/** Inferred TypeScript type for a value matching {@link AccountTreePayloadStruct}. */
+export type AccountTreePayloadStructType = Infer<typeof AccountTreePayloadStruct>;
+/**
+ * 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 declare function assertAccountTreePayload(value: unknown): asserts value is AccountTreePayload;
+//# sourceMappingURL=payload.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"payload.d.cts","sourceRoot":"","sources":["../../src/state/payload.ts"],"names":[],"mappings":"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"}

package/dist/state/payload.d.mts

@@ -0,0 +1,288 @@
+import type { KeyringAccount } from "@metamask/keyring-api";
+import type { Infer } from "@metamask/superstruct";
+import type { DeepReadonly, EncodedBytes } from "./utils.mjs";
+/** Stable cross-device wallet identifier. Format: `wallet:<entropySourceId>`. */
+export type AccountWalletPayloadId = `wallet:${string}`;
+/** Stable cross-device group identifier. Format: `wallet:<entropySourceId>/<groupSubId>`. */
+export type AccountGroupPayloadId = `${AccountWalletPayloadId}/${string}`;
+/**
+ * Parsed representation of an {@link AccountGroupPayloadId}.
+ */
+export type ParsedPayloadGroupId = {
+    /** The wallet portion of the group ID. */
+    walletId: AccountWalletPayloadId;
+    /** The group-specific sub-ID (e.g. group index for mnemonic wallets, address for private-key wallets). */
+    subId: string;
+};
+/**
+ * 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 declare function parsePayloadGroupId(groupId: AccountGroupPayloadId): ParsedPayloadGroupId;
+/**
+ * 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 declare const AccountWalletPayloadType: {
+    readonly Mnemonic: "mnemonic";
+    readonly PrivateKey: "private-key";
+};
+export type AccountWalletPayloadType = (typeof AccountWalletPayloadType)[keyof typeof AccountWalletPayloadType];
+/** Wallet-level metadata carried in every payload wallet entry. */
+export type AccountWalletPayloadMetadata = {
+    name: string;
+};
+/** Group-level metadata carried in every payload group entry. */
+export type AccountWalletGroupPayloadMetadata = {
+    name: string;
+    pinned: boolean;
+    hidden: boolean;
+};
+/** A single group entry inside an {@link AccountWalletMnemonicPayload}. */
+export type AccountWalletMnemonicGroupEntry = {
+    /** Stable group payload ID. Format: `<walletPayloadId>/<groupIndex>`. */
+    id: AccountGroupPayloadId;
+    /** BIP-44 account index this group was derived at. */
+    groupIndex: number;
+    metadata: AccountWalletGroupPayloadMetadata;
+};
+/**
+ * Encoding formats for exported private key material.
+ */
+export declare const AccountWalletPrivateKeyEncoding: {
+    readonly Hexadecimal: "hexadecimal";
+    readonly Base58: "base58";
+    readonly Base32: "base32";
+};
+export type AccountWalletPrivateKeyEncoding = (typeof AccountWalletPrivateKeyEncoding)[keyof typeof AccountWalletPrivateKeyEncoding];
+/** A single group entry inside an {@link AccountWalletPrivateKeyPayload}. */
+export type AccountWalletPrivateKeyGroupEntry = {
+    /** Stable group payload ID. Format: `wallet:private-key/<address>`. */
+    id: AccountGroupPayloadId;
+    /**
+     * Private key material. Shape matches `ExportedAccount` from `@metamask/keyring-api/v2`
+     * so the importer knows how to decode the key without additional out-of-band information.
+     * Absent in metadata-only exports.
+     */
+    value?: {
+        privateKey: EncodedBytes;
+        encoding: AccountWalletPrivateKeyEncoding;
+        /**
+         * Account type from `KeyringAccountType` (e.g. `'eip155:eoa'`, `'bip122:p2wpkh'`).
+         * Absent for EVM accounts -- import via `SimpleKeyring`.
+         * Present for non-EVM accounts -- routing to the BIP-44 Snap handling this type is not yet implemented.
+         */
+        type?: KeyringAccount['type'];
+    };
+    metadata: AccountWalletGroupPayloadMetadata;
+};
+/** Payload entry for an HD (entropy) wallet and its derived account groups. */
+export type AccountWalletMnemonicPayload = {
+    id: AccountWalletPayloadId;
+    type: typeof AccountWalletPayloadType.Mnemonic;
+    /** BIP-39 mnemonic phrase encoded as bytes. Absent in metadata-only exports. */
+    value?: EncodedBytes;
+    metadata: AccountWalletPayloadMetadata;
+    groups: AccountWalletMnemonicGroupEntry[];
+};
+/**
+ * Payload entry for all imported private-key accounts.
+ *
+ * All local simple-keyring wallets are merged into this single entry;
+ * each account is represented as a separate group entry keyed by address.
+ */
+export type AccountWalletPrivateKeyPayload = {
+    id: AccountWalletPayloadId;
+    type: typeof AccountWalletPayloadType.PrivateKey;
+    metadata: AccountWalletPayloadMetadata;
+    groups: AccountWalletPrivateKeyGroupEntry[];
+};
+/** Union of all wallet entry types that can appear in an {@link AccountTreePayload}. */
+export type AccountTreeWalletEntry = AccountWalletMnemonicPayload | AccountWalletPrivateKeyPayload;
+/** Portable snapshot of the full account tree state (flat versioned format). */
+export type AccountTreePayload = {
+    version: number;
+    wallets: AccountTreeWalletEntry[];
+};
+/**
+ * Deeply read-only wallet view passed to {@link AccountTreeSnapshot.filterWallets}
+ * and {@link AccountTreeSnapshot.filterAllGroups} predicates.
+ *
+ * Entries are deep-cloned and deep-frozen when a snapshot is constructed, so
+ * callers cannot mutate wallet IDs, types, secrets, metadata, or groups.
+ */
+export type AccountTreeSnapshotWallet = DeepReadonly<AccountWalletMnemonicPayload | AccountWalletPrivateKeyPayload>;
+/**
+ * Deeply read-only group view passed to {@link AccountTreeSnapshot.filterGroups}
+ * and {@link AccountTreeSnapshot.filterAllGroups} predicates.
+ *
+ * Entries are deep-cloned and deep-frozen when a snapshot is constructed, so
+ * callers cannot mutate group IDs, secrets, metadata, or parent wallet references.
+ */
+export type AccountTreeSnapshotGroup = DeepReadonly<AccountWalletMnemonicGroupEntry | AccountWalletPrivateKeyGroupEntry>;
+/**
+ * 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 declare function toWalletPayloadId(entropySourceId: string): AccountWalletPayloadId;
+/**
+ * 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 declare function toGroupPayloadId(walletId: AccountWalletPayloadId, subId: string | number): AccountGroupPayloadId;
+/** Options accepted by {@link AccountTreeController.exportState}. */
+export type ExportStateOptions = {
+    /** When `true`, secrets (mnemonic / private keys) are included. Requires the vault to be unlocked. */
+    includeSecrets?: boolean;
+};
+/** Current version of the {@link AccountTreePayload} format. */
+export declare 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 declare const AccountTreePayloadStruct: import("@metamask/superstruct").Struct<{
+    wallets: ({
+        id: `wallet:${string}`;
+        type: "mnemonic";
+        metadata: {
+            name: string;
+        };
+        groups: {
+            id: `wallet:${string}/${string}`;
+            metadata: {
+                name: string;
+                pinned: boolean;
+                hidden: boolean;
+            };
+            groupIndex: number;
+        }[];
+        value?: EncodedBytes | undefined;
+    } | {
+        id: `wallet:${string}`;
+        type: "private-key";
+        metadata: {
+            name: string;
+        };
+        groups: {
+            id: `wallet:${string}/${string}`;
+            metadata: {
+                name: string;
+                pinned: boolean;
+                hidden: boolean;
+            };
+            value?: {
+                privateKey: EncodedBytes;
+                encoding: "hexadecimal" | "base58" | "base32";
+                type?: "eip155:eoa" | "eip155:erc4337" | "bip122:p2pkh" | "bip122:p2sh" | "bip122:p2wpkh" | "bip122:p2tr" | "solana:data-account" | "tron:eoa" | "stellar:account" | "any:account" | undefined;
+            } | undefined;
+        }[];
+    })[];
+    version: 1;
+}, {
+    version: import("@metamask/superstruct").Struct<1, 1>;
+    wallets: import("@metamask/superstruct").Struct<({
+        id: `wallet:${string}`;
+        type: "mnemonic";
+        metadata: {
+            name: string;
+        };
+        groups: {
+            id: `wallet:${string}/${string}`;
+            metadata: {
+                name: string;
+                pinned: boolean;
+                hidden: boolean;
+            };
+            groupIndex: number;
+        }[];
+        value?: EncodedBytes | undefined;
+    } | {
+        id: `wallet:${string}`;
+        type: "private-key";
+        metadata: {
+            name: string;
+        };
+        groups: {
+            id: `wallet:${string}/${string}`;
+            metadata: {
+                name: string;
+                pinned: boolean;
+                hidden: boolean;
+            };
+            value?: {
+                privateKey: EncodedBytes;
+                encoding: "hexadecimal" | "base58" | "base32";
+                type?: "eip155:eoa" | "eip155:erc4337" | "bip122:p2pkh" | "bip122:p2sh" | "bip122:p2wpkh" | "bip122:p2tr" | "solana:data-account" | "tron:eoa" | "stellar:account" | "any:account" | undefined;
+            } | undefined;
+        }[];
+    })[], import("@metamask/superstruct").Struct<{
+        id: `wallet:${string}`;
+        type: "mnemonic";
+        metadata: {
+            name: string;
+        };
+        groups: {
+            id: `wallet:${string}/${string}`;
+            metadata: {
+                name: string;
+                pinned: boolean;
+                hidden: boolean;
+            };
+            groupIndex: number;
+        }[];
+        value?: EncodedBytes | undefined;
+    } | {
+        id: `wallet:${string}`;
+        type: "private-key";
+        metadata: {
+            name: string;
+        };
+        groups: {
+            id: `wallet:${string}/${string}`;
+            metadata: {
+                name: string;
+                pinned: boolean;
+                hidden: boolean;
+            };
+            value?: {
+                privateKey: EncodedBytes;
+                encoding: "hexadecimal" | "base58" | "base32";
+                type?: "eip155:eoa" | "eip155:erc4337" | "bip122:p2pkh" | "bip122:p2sh" | "bip122:p2wpkh" | "bip122:p2tr" | "solana:data-account" | "tron:eoa" | "stellar:account" | "any:account" | undefined;
+            } | undefined;
+        }[];
+    }, null>>;
+}>;
+/** Inferred TypeScript type for a value matching {@link AccountTreePayloadStruct}. */
+export type AccountTreePayloadStructType = Infer<typeof AccountTreePayloadStruct>;
+/**
+ * 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 declare function assertAccountTreePayload(value: unknown): asserts value is AccountTreePayload;
+//# sourceMappingURL=payload.d.mts.map

package/dist/state/payload.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.d.mts","sourceRoot":"","sources":["../../src/state/payload.ts"],"names":[],"mappings":"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"}