@unlink-xyz/core 0.1.0 → 0.1.3-canary.01ac52d

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 (unlink1...) 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/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/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/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"}