@unlink-xyz/core 0.1.3-canary.79048c8 → 0.1.3-canary.7a2ea6a

package/README.md

@@ -0,0 +1,9 @@
+# @unlink-xyz/core
+
+Low-level TypeScript SDK for the Unlink privacy protocol.
+
+## Overview
+
+Core library providing key derivation, proof generation, transaction construction, state management, and high-level wallet API for UTXO-based private transactions on EVM blockchains. Used as a foundation by `@unlink-xyz/react` and consumed directly for server-side applications.
+
+> **Documentation:** [SDK overview](../../docs/sdk/index.mdx) | [Architecture](../../docs/concepts/4-architecture/sdk.mdx)

package/dist/account/{zkAccount.d.ts → account.d.ts}

@@ -1,4 +1,4 @@
-import { type SpendingKeyPair, type ViewingKeyPair } from "../key-derivation/wallet-node.js";
+import { type SpendingKeyPair, type ViewingKeyPair } from "../keys/derive.js";
 import type { Storage } from "../types.js";
 export type MasterSeedCrypto = {
     encrypt(seed: Uint8Array): Promise<Uint8Array> | Uint8Array;
@@ -14,14 +14,45 @@ export type GenerateMasterSeedOptions = {
 export declare const MASTER_SEED_LENGTH = 64;
 export declare const MASTER_SEED_KEY = "cfg:wallet:master_seed/v1";
 export declare const MASTER_MNEMONIC_KEY = "cfg:wallet:master_mnemonic/v1";
-export type ZkAccount = {
+export type Account = {
     spendingKeyPair: SpendingKeyPair;
     viewingKeyPair: ViewingKeyPair;
     nullifyingKey: bigint;
     masterPublicKey: bigint;
+    /** Bech32m address (0zk1...) for this account */
+    address: string;
 };
-export declare function deriveZkAccount(masterSeed: Uint8Array, accountIndex?: number): Promise<ZkAccount>;
-export declare function deriveZkAccountFromMnemonic(mnemonic: string, accountIndex?: number, password?: string): Promise<ZkAccount>;
+/**
+ * Read-only account identity — the fields needed by the transaction layer
+ * without any signing capability. Both Account and MultisigAccount satisfy this.
+ */
+export type AccountView = {
+    nullifyingKey: bigint;
+    masterPublicKey: bigint;
+    viewingKeyPair: ViewingKeyPair;
+    address: string;
+};
+/**
+ * Signing capability decoupled from account identity.
+ * Async to support multi-round protocols (FROST), hardware wallets, etc.
+ */
+export type Signer = {
+    publicKey: [bigint, bigint];
+    sign(message: bigint): Promise<{
+        R8: [bigint, bigint];
+        S: bigint;
+    }>;
+};
+/**
+ * Extract an AccountView from a full Account.
+ */
+export declare function toAccountView(account: Account): AccountView;
+/**
+ * Create a Signer from a single spending key pair.
+ */
+export declare function createSingleKeySigner(privateKey: Uint8Array, pubkey: [bigint, bigint]): Signer;
+export declare function deriveAccount(masterSeed: Uint8Array, accountIndex?: number): Account;
+export declare function deriveAccountFromMnemonic(mnemonic: string, accountIndex?: number, password?: string): Account;
 export declare function generateMasterSeed({ storage, rng, crypto, overwrite, mnemonicPassphrase, }: GenerateMasterSeedOptions): Promise<Uint8Array>;
 export declare function loadMasterSeed(storage: Storage, crypto?: MasterSeedCrypto): Promise<Uint8Array | null>;
 export declare function storeMasterSeed(storage: Storage, seed: Uint8Array, crypto?: MasterSeedCrypto): Promise<void>;
@@ -35,4 +66,4 @@ export type ImportMasterMnemonicOptions = {
 };
 export declare function importMasterMnemonic({ storage, mnemonic, crypto, overwrite, password, }: ImportMasterMnemonicOptions): Promise<Uint8Array>;
 export declare function storeMasterMnemonic(storage: Storage, mnemonic: string, crypto?: MasterSeedCrypto): Promise<void>;
-//# sourceMappingURL=zkAccount.d.ts.map
+//# sourceMappingURL=account.d.ts.map

package/dist/account/account.d.ts.map

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

package/dist/account/{zkAccount.js → account.js}

@@ -1,47 +1,68 @@
-import { Mnemonic } from "../key-derivation/bip39.js";
-import { ByteUtils } from "../key-derivation/bytes.js";
-import { deriveNodesFromSeed, WalletNode, } from "../key-derivation/wallet-node.js";
-import { zeroize } from "../utils/secure-memory.js";
+import { zeroize } from "../crypto/secure-memory.js";
+import { ValidationError } from "../errors.js";
+import { encodeAddress } from "../keys/address.js";
+import { deriveAccountKeys, } from "../keys/derive.js";
+import { Hex } from "../keys/hex.js";
+import { Mnemonic } from "../keys/mnemonic.js";
+import { signTransactMessage } from "../utils/signature.js";
 export const MASTER_SEED_LENGTH = 64;
 export const MASTER_SEED_KEY = "cfg:wallet:master_seed/v1";
 export const MASTER_MNEMONIC_KEY = "cfg:wallet:master_mnemonic/v1";
 const MNEMONIC_ENTROPY_BYTES = 32;
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
-export async function deriveZkAccount(masterSeed, accountIndex = 0) {
+/**
+ * Extract an AccountView from a full Account.
+ */
+export function toAccountView(account) {
+    return {
+        nullifyingKey: account.nullifyingKey,
+        masterPublicKey: account.masterPublicKey,
+        viewingKeyPair: account.viewingKeyPair,
+        address: account.address,
+    };
+}
+/**
+ * Create a Signer from a single spending key pair.
+ */
+export function createSingleKeySigner(privateKey, pubkey) {
+    return {
+        publicKey: pubkey,
+        sign: async (message) => signTransactMessage(privateKey, message),
+    };
+}
+export function deriveAccount(masterSeed, accountIndex = 0) {
     const seed = normalizeMasterSeed(masterSeed);
     if (!Number.isInteger(accountIndex) || accountIndex < 0) {
-        throw new Error("accountIndex must be a non-negative integer");
+        throw new ValidationError("accountIndex must be a non-negative integer");
     }
-    const { spending, viewing } = deriveNodesFromSeed(seed, accountIndex);
-    const spendingKeyPair = spending.getSpendingKeyPair();
-    const viewingKeyPair = await viewing.getViewingKeyPair();
-    const nullifyingKey = WalletNode.getNullifyingKey(viewingKeyPair.privateKey);
-    const masterPublicKey = WalletNode.getMasterPublicKey(spendingKeyPair.pubkey, nullifyingKey);
+    const keys = deriveAccountKeys(seed, accountIndex);
+    const address = encodeAddress({
+        masterPublicKey: keys.masterPublicKey,
+        viewingPublicKey: keys.viewing.pubkey,
+    });
     return {
-        spendingKeyPair,
-        viewingKeyPair,
-        nullifyingKey,
-        masterPublicKey,
+        spendingKeyPair: keys.spending,
+        viewingKeyPair: keys.viewing,
+        nullifyingKey: keys.nullifyingKey,
+        masterPublicKey: keys.masterPublicKey,
+        address,
     };
 }
-export async function deriveZkAccountFromMnemonic(mnemonic, accountIndex = 0, password = "") {
+export function deriveAccountFromMnemonic(mnemonic, accountIndex = 0, password = "") {
     const normalized = normalizeMnemonic(mnemonic);
     const seed = mnemonicToSeed(normalized, password);
     try {
-        return await deriveZkAccount(seed, accountIndex);
+        return deriveAccount(seed, accountIndex);
     }
     finally {
         zeroize(seed);
     }
 }
+/** Passthrough crypto, storage handles buffer isolation */
 const identityMasterSeedCrypto = {
-    encrypt(seed) {
-        return clone(seed);
-    },
-    decrypt(payload) {
-        return clone(payload);
-    },
+    encrypt: (seed) => seed,
+    decrypt: (payload) => payload,
 };
 export async function generateMasterSeed({ storage, rng, crypto = identityMasterSeedCrypto, overwrite = false, mnemonicPassphrase, }) {
     if (!overwrite) {
@@ -57,10 +78,10 @@ export async function generateMasterSeed({ storage, rng, crypto = identityMaster
     }
     const entropy = rng(MNEMONIC_ENTROPY_BYTES);
     if (entropy.length !== MNEMONIC_ENTROPY_BYTES) {
-        throw new Error(`mnemonic entropy must be ${MNEMONIC_ENTROPY_BYTES} bytes`);
+        throw new ValidationError(`mnemonic entropy must be ${MNEMONIC_ENTROPY_BYTES} bytes`);
     }
     try {
-        const mnemonic = Mnemonic.fromEntropy(ByteUtils.bytesToHex(entropy));
+        const mnemonic = Mnemonic.fromEntropy(Hex.fromBytes(entropy));
         await storeMasterMnemonic(storage, mnemonic, crypto);
         const seed = mnemonicToSeed(mnemonic, mnemonicPassphrase);
         await storeMasterSeed(storage, seed, crypto);
@@ -81,9 +102,9 @@ export async function storeMasterSeed(storage, seed, crypto = identityMasterSeed
     const normalized = normalizeMasterSeed(seed);
     const encrypted = await crypto.encrypt(normalized);
     if (!(encrypted instanceof Uint8Array)) {
-        throw new Error("master seed encryptor must return Uint8Array");
+        throw new ValidationError("master seed encryptor must return Uint8Array");
     }
-    await storage.put(MASTER_SEED_KEY, clone(encrypted));
+    await storage.put(MASTER_SEED_KEY, encrypted);
 }
 export async function loadMasterMnemonic(storage, crypto = identityMasterSeedCrypto) {
     const stored = await storage.get(MASTER_MNEMONIC_KEY);
@@ -102,7 +123,7 @@ export async function importMasterMnemonic({ storage, mnemonic, crypto = identit
     if (!overwrite) {
         const existing = await loadMasterMnemonic(storage, crypto);
         if (existing) {
-            throw new Error("master mnemonic already exists; set overwrite to true to replace it");
+            throw new ValidationError("master mnemonic already exists; set overwrite to true to replace it");
         }
     }
     const normalized = normalizeMnemonic(mnemonic);
@@ -115,30 +136,28 @@ export async function storeMasterMnemonic(storage, mnemonic, crypto = identityMa
     const normalized = normalizeMnemonic(mnemonic);
     const encrypted = await crypto.encrypt(textEncoder.encode(normalized));
     if (!(encrypted instanceof Uint8Array)) {
-        throw new Error("master mnemonic encryptor must return Uint8Array");
+        throw new ValidationError("master mnemonic encryptor must return Uint8Array");
     }
-    await storage.put(MASTER_MNEMONIC_KEY, clone(encrypted));
-}
-function clone(bytes) {
-    return new Uint8Array(bytes);
+    await storage.put(MASTER_MNEMONIC_KEY, encrypted);
 }
+/** Validates seed format. Storage handles buffer isolation on put/get. */
 function normalizeMasterSeed(seed) {
     if (!(seed instanceof Uint8Array)) {
-        throw new Error("master seed must be a Uint8Array");
+        throw new ValidationError("master seed must be a Uint8Array");
     }
     if (seed.length !== MASTER_SEED_LENGTH) {
-        throw new Error(`master seed must be ${MASTER_SEED_LENGTH} bytes`);
+        throw new ValidationError(`master seed must be ${MASTER_SEED_LENGTH} bytes`);
     }
-    return clone(seed);
+    return seed;
 }
 function normalizeMnemonic(mnemonic) {
     const formatted = mnemonic.trim().replace(/\s+/g, " ");
     if (!Mnemonic.validate(formatted)) {
-        throw new Error("invalid BIP-39 mnemonic phrase");
+        throw new ValidationError("invalid BIP-39 mnemonic phrase");
     }
     return formatted;
 }
 function mnemonicToSeed(mnemonic, password = "") {
     const seedHex = Mnemonic.toSeed(mnemonic, password);
-    return ByteUtils.hexStringToBytes(seedHex);
+    return Hex.toBytes(seedHex);
 }

package/dist/account/accounts.d.ts

@@ -0,0 +1,42 @@
+import type { Storage } from "../types.js";
+import type { AccountInfo } from "../wallet/types.js";
+import { deriveAccount as deriveAccountFn, type Account } from "./account.js";
+export declare const DERIVED_ACCOUNTS_KEY = "cfg:wallet:derived_accounts";
+export declare const ACTIVE_ACCOUNT_INDEX_KEY = "cfg:wallet:active_account_index";
+export declare const ACCOUNT_KEY_PREFIX = "cfg:wallet:account:";
+export type AccountsServiceDeps = {
+    storage: Storage;
+    deriveAccount: typeof deriveAccountFn;
+    getMasterSeed: () => Promise<Uint8Array>;
+};
+export type AccountsService = {
+    /**
+     * List all derived accounts (index + mpk only, safe to display).
+     */
+    list(): Promise<AccountInfo[]>;
+    /**
+     * Get full Account by index (null if not derived yet).
+     */
+    get(index: number): Promise<Account | null>;
+    /**
+     * Derive and persist a new account at the specified index.
+     * If index is not specified, uses the next available index.
+     * @throws If the index is already used
+     */
+    create(index?: number): Promise<Account>;
+    /**
+     * Get the currently active account (null if none).
+     */
+    getActive(): Promise<Account | null>;
+    /**
+     * Get the currently active account index (null if none).
+     */
+    getActiveIndex(): Promise<number | null>;
+    /**
+     * Switch to a different account by index.
+     * @throws If the account at the given index doesn't exist
+     */
+    setActive(index: number): Promise<void>;
+};
+export declare function createAccountsService(deps: AccountsServiceDeps): AccountsService;
+//# sourceMappingURL=accounts.d.ts.map

package/dist/account/accounts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accounts.d.ts","sourceRoot":"","sources":["../../account/accounts.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,aAAa,IAAI,eAAe,EAAE,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAM9E,eAAO,MAAM,oBAAoB,gCAAgC,CAAC;AAClE,eAAO,MAAM,wBAAwB,oCAAoC,CAAC;AAC1E,eAAO,MAAM,kBAAkB,wBAAwB,CAAC;AAExD,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,OAAO,eAAe,CAAC;IACtC,aAAa,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC;CAC1C,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B;;OAEG;IACH,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAE/B;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAE5C;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzC;;OAEG;IACH,SAAS,IAAI,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAErC;;OAEG;IACH,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEzC;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC,CAAC;AAyBF,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,mBAAmB,GACxB,eAAe,CAkHjB"}

package/dist/account/accounts.js

@@ -0,0 +1,119 @@
+import { ValidationError } from "../errors.js";
+import { deserializeAccountRecord, serializeAccountRecord, } from "./serialization.js";
+export const DERIVED_ACCOUNTS_KEY = "cfg:wallet:derived_accounts";
+export const ACTIVE_ACCOUNT_INDEX_KEY = "cfg:wallet:active_account_index";
+export const ACCOUNT_KEY_PREFIX = "cfg:wallet:account:";
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function accountKey(index) {
+    return `${ACCOUNT_KEY_PREFIX}${index}`;
+}
+function encodeIndices(indices) {
+    return encoder.encode(JSON.stringify(indices));
+}
+function decodeIndices(data) {
+    return JSON.parse(decoder.decode(data));
+}
+function encodeIndex(index) {
+    return encoder.encode(JSON.stringify(index));
+}
+function decodeIndex(data) {
+    return JSON.parse(decoder.decode(data));
+}
+export function createAccountsService(deps) {
+    const { storage, deriveAccount, getMasterSeed } = deps;
+    async function getDerivedIndices() {
+        const stored = await storage.get(DERIVED_ACCOUNTS_KEY);
+        if (!stored)
+            return [];
+        return decodeIndices(stored);
+    }
+    async function setDerivedIndices(indices) {
+        await storage.put(DERIVED_ACCOUNTS_KEY, encodeIndices(indices));
+    }
+    async function loadAccount(index) {
+        const stored = await storage.get(accountKey(index));
+        if (!stored)
+            return null;
+        return deserializeAccountRecord(stored);
+    }
+    async function persistAccount(index, account) {
+        await storage.put(accountKey(index), serializeAccountRecord(account));
+    }
+    async function list() {
+        const indices = await getDerivedIndices();
+        const accounts = [];
+        for (const index of indices) {
+            const account = await loadAccount(index);
+            if (account) {
+                accounts.push({
+                    index,
+                    masterPublicKey: account.masterPublicKey,
+                    address: account.address,
+                });
+            }
+        }
+        return accounts;
+    }
+    async function get(index) {
+        const indices = await getDerivedIndices();
+        if (!indices.includes(index))
+            return null;
+        return loadAccount(index);
+    }
+    async function create(index) {
+        const indices = await getDerivedIndices();
+        // Determine the index to use
+        let targetIndex;
+        if (index !== undefined) {
+            if (indices.includes(index)) {
+                throw new ValidationError(`Account at index ${index} already exists`);
+            }
+            targetIndex = index;
+        }
+        else {
+            // Use next available index
+            targetIndex = indices.length > 0 ? Math.max(...indices) + 1 : 0;
+        }
+        // Derive the account
+        const masterSeed = await getMasterSeed();
+        const account = deriveAccount(masterSeed, targetIndex);
+        // Persist the account (storage handles buffer isolation)
+        await persistAccount(targetIndex, account);
+        // Update the indices list
+        const newIndices = [...indices, targetIndex].sort((a, b) => a - b);
+        await setDerivedIndices(newIndices);
+        // If this is the first account, set it as active
+        if (indices.length === 0) {
+            await setActive(targetIndex);
+        }
+        return account;
+    }
+    async function getActiveIndex() {
+        const stored = await storage.get(ACTIVE_ACCOUNT_INDEX_KEY);
+        if (!stored)
+            return null;
+        return decodeIndex(stored);
+    }
+    async function getActive() {
+        const activeIndex = await getActiveIndex();
+        if (activeIndex === null)
+            return null;
+        return loadAccount(activeIndex);
+    }
+    async function setActive(index) {
+        const indices = await getDerivedIndices();
+        if (!indices.includes(index)) {
+            throw new ValidationError(`Cannot set active: account at index ${index} does not exist`);
+        }
+        await storage.put(ACTIVE_ACCOUNT_INDEX_KEY, encodeIndex(index));
+    }
+    return {
+        list,
+        get,
+        create,
+        getActive,
+        getActiveIndex,
+        setActive,
+    };
+}

package/dist/account/seed.d.ts

@@ -0,0 +1,45 @@
+import type { Storage } from "../types.js";
+import { type MasterSeedCrypto } from "./account.js";
+export type SeedServiceDeps = {
+    storage: Storage;
+    rng: (n: number) => Uint8Array;
+    crypto?: MasterSeedCrypto;
+};
+export type SeedService = {
+    /**
+     * Check if a wallet exists (has mnemonic stored).
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Create a new wallet. Generates a BIP-39 mnemonic and derives the master seed.
+     * Returns the mnemonic so the user can back it up.
+     * @throws If a wallet already exists (use import with overwrite instead)
+     */
+    create(): Promise<{
+        mnemonic: string;
+    }>;
+    /**
+     * Import an existing BIP-39 mnemonic.
+     * @throws If the mnemonic is invalid
+     * @throws If a wallet already exists and overwrite is false
+     */
+    importMnemonic(mnemonic: string, opts?: {
+        overwrite?: boolean;
+    }): Promise<void>;
+    /**
+     * Export the stored mnemonic for backup.
+     * @throws If no wallet exists
+     */
+    exportMnemonic(): Promise<string>;
+    /**
+     * Get the master seed (for account derivation).
+     * @throws If no wallet exists
+     */
+    getMasterSeed(): Promise<Uint8Array>;
+    /**
+     * Delete all wallet data. This is destructive and cannot be undone.
+     */
+    delete(): Promise<void>;
+};
+export declare function createSeedService(deps: SeedServiceDeps): SeedService;
+//# sourceMappingURL=seed.d.ts.map

package/dist/account/seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../../account/seed.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAOL,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AAOtB,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,UAAU,CAAC;IAC/B,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAE3B;;;;OAIG;IACH,MAAM,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAExC;;;;OAIG;IACH,cAAc,CACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAC7B,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;OAGG;IACH,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAElC;;;OAGG;IACH,aAAa,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAErC;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW,CAgHpE"}

package/dist/account/seed.js

@@ -0,0 +1,91 @@
+import { ValidationError } from "../errors.js";
+import { generateMasterSeed, importMasterMnemonic, loadMasterMnemonic, loadMasterSeed, MASTER_MNEMONIC_KEY, MASTER_SEED_KEY, } from "./account.js";
+import { ACCOUNT_KEY_PREFIX, ACTIVE_ACCOUNT_INDEX_KEY, DERIVED_ACCOUNTS_KEY, } from "./accounts.js";
+export function createSeedService(deps) {
+    const { storage, rng, crypto } = deps;
+    async function exists() {
+        const mnemonic = await loadMasterMnemonic(storage, crypto);
+        return mnemonic !== null;
+    }
+    async function create() {
+        // Check if wallet already exists
+        const walletExists = await exists();
+        if (walletExists) {
+            throw new ValidationError("Wallet already exists. Use import with overwrite option to replace it.");
+        }
+        // Generate new mnemonic and seed
+        await generateMasterSeed({
+            storage,
+            rng,
+            crypto,
+            mnemonicPassphrase: "",
+            overwrite: false,
+        });
+        // Load and return the mnemonic so user can back it up
+        const mnemonic = await loadMasterMnemonic(storage, crypto);
+        if (!mnemonic) {
+            throw new ValidationError("Failed to create wallet: mnemonic not stored");
+        }
+        return { mnemonic };
+    }
+    async function importMnemonic(mnemonic, opts) {
+        const overwrite = opts?.overwrite ?? false;
+        // Check if wallet already exists
+        if (!overwrite) {
+            const walletExists = await exists();
+            if (walletExists) {
+                throw new ValidationError("Wallet already exists. Use overwrite option to replace it.");
+            }
+        }
+        // Import the mnemonic first
+        await importMasterMnemonic({
+            storage,
+            mnemonic,
+            crypto,
+            overwrite,
+            password: "",
+        });
+        // Clear account data after successful import to avoid data loss on failure
+        if (overwrite) {
+            await clearAccountData();
+        }
+    }
+    async function exportMnemonic() {
+        const mnemonic = await loadMasterMnemonic(storage, crypto);
+        if (!mnemonic) {
+            throw new ValidationError("No wallet exists. Create or import a wallet first.");
+        }
+        return mnemonic;
+    }
+    async function getMasterSeed() {
+        const seed = await loadMasterSeed(storage, crypto);
+        if (!seed) {
+            throw new ValidationError("No wallet exists. Create or import a wallet first.");
+        }
+        return seed;
+    }
+    async function clearAccountData() {
+        // Delete all account records by prefix
+        const accountRecords = await storage.iter({ prefix: ACCOUNT_KEY_PREFIX });
+        for (const { key } of accountRecords) {
+            await storage.delete(key);
+        }
+        // Clear metadata keys
+        await storage.delete(DERIVED_ACCOUNTS_KEY);
+        await storage.delete(ACTIVE_ACCOUNT_INDEX_KEY);
+    }
+    async function deleteWallet() {
+        // Clear all wallet data
+        await storage.delete(MASTER_MNEMONIC_KEY);
+        await storage.delete(MASTER_SEED_KEY);
+        await clearAccountData();
+    }
+    return {
+        exists,
+        create,
+        importMnemonic,
+        exportMnemonic,
+        getMasterSeed,
+        delete: deleteWallet,
+    };
+}

package/dist/account/serialization.d.ts

@@ -0,0 +1,6 @@
+import { formatUint256 } from "../utils/bigint.js";
+import type { Account } from "./account.js";
+export { formatUint256 };
+export declare function serializeAccountRecord(account: Account): Uint8Array;
+export declare function deserializeAccountRecord(payload: Uint8Array): Account;
+//# sourceMappingURL=serialization.d.ts.map

package/dist/account/serialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../../account/serialization.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAMnD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAE,aAAa,EAAE,CAAC;AAQzB,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,CAmBnE;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CA6BrE"}

package/dist/account/serialization.js

@@ -0,0 +1,53 @@
+import { formatUint256 } from "../utils/bigint.js";
+import { ACCOUNT_RECORD_VERSION, BIGINT_RADIX, } from "../wallet/types.js";
+export { formatUint256 };
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const encodeBigInt = (value) => value.toString(BIGINT_RADIX);
+const decodeBigInt = (value) => BigInt(`0x${value}`);
+export function serializeAccountRecord(account) {
+    const record = {
+        version: ACCOUNT_RECORD_VERSION,
+        spendingKeyPair: {
+            privateKey: Array.from(account.spendingKeyPair.privateKey),
+            pubkey: [
+                encodeBigInt(account.spendingKeyPair.pubkey[0]),
+                encodeBigInt(account.spendingKeyPair.pubkey[1]),
+            ],
+        },
+        viewingKeyPair: {
+            privateKey: Array.from(account.viewingKeyPair.privateKey),
+            pubkey: Array.from(account.viewingKeyPair.pubkey),
+        },
+        nullifyingKey: encodeBigInt(account.nullifyingKey),
+        masterPublicKey: encodeBigInt(account.masterPublicKey),
+        address: account.address,
+    };
+    return encoder.encode(JSON.stringify(record));
+}
+export function deserializeAccountRecord(payload) {
+    const parsed = JSON.parse(decoder.decode(payload));
+    if (parsed.version !== ACCOUNT_RECORD_VERSION) {
+        throw new Error(`unsupported wallet account version ${parsed.version}`);
+    }
+    const spendingPubkey = [
+        decodeBigInt(parsed.spendingKeyPair.pubkey[0]),
+        decodeBigInt(parsed.spendingKeyPair.pubkey[1]),
+    ];
+    const viewingPubkey = Uint8Array.from(parsed.viewingKeyPair.pubkey);
+    const masterPublicKey = decodeBigInt(parsed.masterPublicKey);
+    const address = parsed.address;
+    return {
+        spendingKeyPair: {
+            privateKey: Uint8Array.from(parsed.spendingKeyPair.privateKey),
+            pubkey: spendingPubkey,
+        },
+        viewingKeyPair: {
+            privateKey: Uint8Array.from(parsed.viewingKeyPair.privateKey),
+            pubkey: viewingPubkey,
+        },
+        nullifyingKey: decodeBigInt(parsed.nullifyingKey),
+        masterPublicKey,
+        address,
+    };
+}