@veilo/sdk-core 0.5.0 → 0.7.0

package/dist/cjs/events/types.d.ts

@@ -0,0 +1,39 @@
+import type { PublicKey } from "@solana/web3.js";
+import type { PrivacyPoolIdlVersion } from "../idl/index.js";
+export type CommitmentEventSource = "emitted" | "computed" | "protected";
+/**
+ * A commitment appended to a Veilo Merkle tree.
+ *
+ * Compact recovery fields are optional because they were added across two
+ * program upgrades. Historical events remain valid without them.
+ */
+export type CommitmentEvent = {
+    commitment: Uint8Array;
+    leafIndex: number;
+    newRoot: Uint8Array;
+    timestamp: number;
+    mintAddress: PublicKey;
+    treeId: number;
+    txSignature: string;
+    slot: number;
+    ephemeralPublicKey?: Uint8Array;
+    encryptedBlob?: Uint8Array;
+    viewTag?: number;
+    source?: CommitmentEventSource;
+    idlVersion?: PrivacyPoolIdlVersion;
+};
+/** On-chain event emitted when a private note is consumed. */
+export type NullifierSpentEvent = {
+    nullifier: Uint8Array;
+    timestamp: number;
+    mintAddress: PublicKey;
+    treeId: number;
+    txSignature: string;
+    slot: number;
+    idlVersion?: PrivacyPoolIdlVersion;
+};
+export type ParsedVeiloEvent = {
+    name: string;
+    data: unknown;
+    idlVersion: PrivacyPoolIdlVersion;
+};

package/dist/cjs/events/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/events.d.ts

@@ -1,77 +1 @@
-import { PublicKey } from "@solana/web3.js";
-import { Program, Idl } from "@coral-xyz/anchor";
-import { MerkleTree } from "./merkle.js";
-/**
- * On-chain CommitmentEvent emitted by `transact` and `transact_swap`.
- * Mirrors the IDL CommitmentEvent struct.
- */
-export type CommitmentEvent = {
-    commitment: Uint8Array;
-    leafIndex: number;
-    newRoot: Uint8Array;
-    timestamp: number;
-    mintAddress: PublicKey;
-    treeId: number;
-    txSignature: string;
-    slot: number;
-};
-/**
- * On-chain NullifierSpent event emitted when a UTXO is consumed.
- * Mirrors the IDL NullifierSpent struct.
- */
-export type NullifierSpentEvent = {
-    nullifier: Uint8Array;
-    timestamp: number;
-    mintAddress: PublicKey;
-    treeId: number;
-    txSignature: string;
-    slot: number;
-};
-/**
- * Fetch and parse CommitmentEvents for a program, optionally filtered by mint.
- *
- * @param program     - Anchor program instance
- * @param mintAddress - Filter to a specific pool; omit to get all pools
- * @param before      - Start paging before this signature (exclusive)
- * @param until       - Stop paging at this signature (exclusive)
- * @param limit       - Max signatures to fetch per page (default 1000)
- */
-export declare function scanCommitmentEvents<T extends Idl>(params: {
-    program: Program<T>;
-    mintAddress?: PublicKey;
-    before?: string;
-    until?: string;
-    limit?: number;
-}): Promise<CommitmentEvent[]>;
-/**
- * Fetch and parse NullifierSpent events for a program, optionally filtered by mint.
- */
-export declare function scanNullifierEvents<T extends Idl>(params: {
-    program: Program<T>;
-    mintAddress?: PublicKey;
-    before?: string;
-    until?: string;
-    limit?: number;
-}): Promise<NullifierSpentEvent[]>;
-/**
- * Rebuild a local MerkleTree from on-chain CommitmentEvents.
- * Use this to get a valid inclusion proof for spending any UTXO.
- *
- * CommitmentEvents are sorted by (treeId, leafIndex) so the local tree
- * matches the on-chain state exactly.
- *
- * @param program     - Anchor program instance
- * @param mintAddress - Pool to reconstruct
- * @param treeId      - Which tree to reconstruct (default 0)
- * @param depth       - Merkle tree depth (default 22, must match on-chain)
- */
-export declare function buildTreeFromEvents<T extends Idl>(params: {
-    program: Program<T>;
-    mintAddress: PublicKey;
-    treeId?: number;
-    depth?: number;
-}): Promise<{
-    tree: MerkleTree;
-    events: CommitmentEvent[];
-    latestSignature?: string;
-}>;
+export * from "./events/index.js";

package/dist/cjs/events.js

@@ -10,158 +10,10 @@ var __createBinding = (this && this.__createBinding) || (Object.create ? (functi
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];
 }));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.scanCommitmentEvents = scanCommitmentEvents;
-exports.scanNullifierEvents = scanNullifierEvents;
-exports.buildTreeFromEvents = buildTreeFromEvents;
-const anchor = __importStar(require("@coral-xyz/anchor"));
-const merkle_js_1 = require("./merkle.js");
-// -----------------------------------------------------------------------------
-// Event Scanning
-// -----------------------------------------------------------------------------
-/**
- * Fetch and parse CommitmentEvents for a program, optionally filtered by mint.
- *
- * @param program     - Anchor program instance
- * @param mintAddress - Filter to a specific pool; omit to get all pools
- * @param before      - Start paging before this signature (exclusive)
- * @param until       - Stop paging at this signature (exclusive)
- * @param limit       - Max signatures to fetch per page (default 1000)
- */
-async function scanCommitmentEvents(params) {
-    const { program, mintAddress, before, until, limit = 1000 } = params;
-    const out = [];
-    const eventParser = new anchor.EventParser(program.programId, new anchor.BorshCoder(program.idl));
-    const sigs = await program.provider.connection.getSignaturesForAddress(program.programId, { before, until, limit });
-    for (const sigInfo of sigs) {
-        if (sigInfo.err)
-            continue;
-        const tx = await program.provider.connection.getTransaction(sigInfo.signature, { commitment: "confirmed", maxSupportedTransactionVersion: 0 });
-        if (!tx)
-            continue;
-        const events = Array.from(eventParser.parseLogs(tx.meta?.logMessages ?? []));
-        for (const ev of events) {
-            if (ev.name !== "commitmentEvent")
-                continue;
-            const d = ev.data;
-            const evMint = d.mintAddress;
-            if (mintAddress && !evMint.equals(mintAddress))
-                continue;
-            out.push({
-                commitment: new Uint8Array(d.commitment),
-                leafIndex: Number(d.leafIndex),
-                newRoot: new Uint8Array(d.newRoot),
-                timestamp: Number(d.timestamp),
-                mintAddress: evMint,
-                treeId: Number(d.treeId),
-                txSignature: sigInfo.signature,
-                slot: sigInfo.slot,
-            });
-        }
-    }
-    return out;
-}
-/**
- * Fetch and parse NullifierSpent events for a program, optionally filtered by mint.
- */
-async function scanNullifierEvents(params) {
-    const { program, mintAddress, before, until, limit = 1000 } = params;
-    const out = [];
-    const eventParser = new anchor.EventParser(program.programId, new anchor.BorshCoder(program.idl));
-    const sigs = await program.provider.connection.getSignaturesForAddress(program.programId, { before, until, limit });
-    for (const sigInfo of sigs) {
-        if (sigInfo.err)
-            continue;
-        const tx = await program.provider.connection.getTransaction(sigInfo.signature, { commitment: "confirmed", maxSupportedTransactionVersion: 0 });
-        if (!tx)
-            continue;
-        const events = Array.from(eventParser.parseLogs(tx.meta?.logMessages ?? []));
-        for (const ev of events) {
-            if (ev.name !== "nullifierSpent")
-                continue;
-            const d = ev.data;
-            const evMint = d.mintAddress;
-            if (mintAddress && !evMint.equals(mintAddress))
-                continue;
-            out.push({
-                nullifier: new Uint8Array(d.nullifier),
-                timestamp: Number(d.timestamp),
-                mintAddress: evMint,
-                treeId: Number(d.treeId),
-                txSignature: sigInfo.signature,
-                slot: sigInfo.slot,
-            });
-        }
-    }
-    return out;
-}
-// -----------------------------------------------------------------------------
-// Tree Reconstruction
-// -----------------------------------------------------------------------------
-/**
- * Rebuild a local MerkleTree from on-chain CommitmentEvents.
- * Use this to get a valid inclusion proof for spending any UTXO.
- *
- * CommitmentEvents are sorted by (treeId, leafIndex) so the local tree
- * matches the on-chain state exactly.
- *
- * @param program     - Anchor program instance
- * @param mintAddress - Pool to reconstruct
- * @param treeId      - Which tree to reconstruct (default 0)
- * @param depth       - Merkle tree depth (default 22, must match on-chain)
- */
-async function buildTreeFromEvents(params) {
-    const { program, mintAddress, treeId = 0, depth = 22 } = params;
-    // Fetch all commitment events for this pool (page until no more results).
-    // Oldest-first so we insert leaves in the correct order.
-    const allEvents = [];
-    let before;
-    while (true) {
-        const page = await scanCommitmentEvents({
-            program,
-            mintAddress,
-            before,
-            limit: 1000,
-        });
-        if (page.length === 0)
-            break;
-        allEvents.push(...page);
-        before = page[page.length - 1].txSignature;
-        if (page.length < 1000)
-            break;
-    }
-    // Keep only events for this treeId, sort by leafIndex ascending
-    const treeEvents = allEvents
-        .filter((e) => e.treeId === treeId)
-        .sort((a, b) => a.leafIndex - b.leafIndex);
-    const tree = new merkle_js_1.MerkleTree(depth);
-    for (const ev of treeEvents) {
-        tree.insert(ev.commitment);
-    }
-    const latestSignature = treeEvents.length > 0
-        ? treeEvents[treeEvents.length - 1].txSignature
-        : undefined;
-    return { tree, events: treeEvents, latestSignature };
-}
+// Backward-compatible entry point. Event parsing, scanning, and recovery live
+// in focused modules under src/events.
+__exportStar(require("./events/index.js"), exports);

package/dist/cjs/identity/encoding.d.ts

@@ -0,0 +1,9 @@
+export declare function concatBytes(...parts: readonly Uint8Array[]): Uint8Array;
+export declare function utf8(value: string): Uint8Array;
+export declare function uint32Le(value: number, label?: string): Uint8Array;
+export declare function uint64Le(value: bigint, label?: string): Uint8Array;
+export declare function assertBytes(value: Uint8Array, length: number, label: string): void;
+export declare function bytesToHex(bytes: Uint8Array): string;
+export declare function hexToBytes(value: string, length?: number, label?: string): Uint8Array;
+/** Encode bytes using the Bitcoin/Solana base58 alphabet. */
+export declare function encodeBase58(bytes: Uint8Array): string;

package/dist/cjs/identity/encoding.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.concatBytes = concatBytes;
+exports.utf8 = utf8;
+exports.uint32Le = uint32Le;
+exports.uint64Le = uint64Le;
+exports.assertBytes = assertBytes;
+exports.bytesToHex = bytesToHex;
+exports.hexToBytes = hexToBytes;
+exports.encodeBase58 = encodeBase58;
+const BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+function concatBytes(...parts) {
+    const output = new Uint8Array(parts.reduce((length, part) => length + part.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        output.set(part, offset);
+        offset += part.length;
+    }
+    return output;
+}
+function utf8(value) {
+    return new TextEncoder().encode(value);
+}
+function uint32Le(value, label = "value") {
+    if (!Number.isSafeInteger(value) || value < 0 || value > 4294967295) {
+        throw new RangeError(`${label} must be an unsigned 32-bit integer`);
+    }
+    const bytes = new Uint8Array(4);
+    new DataView(bytes.buffer).setUint32(0, value, true);
+    return bytes;
+}
+function uint64Le(value, label = "value") {
+    if (value < 0n || value > 0xffffffffffffffffn) {
+        throw new RangeError(`${label} must be an unsigned 64-bit integer`);
+    }
+    const bytes = new Uint8Array(8);
+    new DataView(bytes.buffer).setBigUint64(0, value, true);
+    return bytes;
+}
+function assertBytes(value, length, label) {
+    if (value.length !== length) {
+        throw new RangeError(`${label} must be ${length} bytes, got ${value.length}`);
+    }
+}
+function bytesToHex(bytes) {
+    return Array.from(bytes, (value) => value.toString(16).padStart(2, "0")).join("");
+}
+function hexToBytes(value, length, label = "hex value") {
+    const clean = value.startsWith("0x") ? value.slice(2) : value;
+    if (!/^[0-9a-f]*$/i.test(clean) || clean.length % 2 !== 0) {
+        throw new TypeError(`${label} must be an even-length hexadecimal string`);
+    }
+    const bytes = Uint8Array.from({ length: clean.length / 2 }, (_, index) => Number.parseInt(clean.slice(index * 2, index * 2 + 2), 16));
+    if (length !== undefined)
+        assertBytes(bytes, length, label);
+    return bytes;
+}
+/** Encode bytes using the Bitcoin/Solana base58 alphabet. */
+function encodeBase58(bytes) {
+    if (bytes.length === 0)
+        return "";
+    let zeroes = 0;
+    while (zeroes < bytes.length && bytes[zeroes] === 0)
+        zeroes++;
+    if (zeroes === bytes.length)
+        return "1".repeat(zeroes);
+    const digits = [0];
+    for (let index = zeroes; index < bytes.length; index++) {
+        let carry = bytes[index];
+        for (let digit = 0; digit < digits.length; digit++) {
+            const value = digits[digit] * 256 + carry;
+            digits[digit] = value % 58;
+            carry = Math.floor(value / 58);
+        }
+        while (carry > 0) {
+            digits.push(carry % 58);
+            carry = Math.floor(carry / 58);
+        }
+    }
+    let encoded = "1".repeat(zeroes);
+    for (let index = digits.length - 1; index >= 0; index--) {
+        encoded += BASE58_ALPHABET[digits[index]];
+    }
+    return encoded;
+}

package/dist/cjs/identity/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./encoding.js";
+export * from "./spending.js";
+export * from "./noteKey.js";
+export * from "./viewKey.js";

package/dist/cjs/identity/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./encoding.js"), exports);
+__exportStar(require("./spending.js"), exports);
+__exportStar(require("./noteKey.js"), exports);
+__exportStar(require("./viewKey.js"), exports);

package/dist/cjs/identity/noteKey.d.ts

@@ -0,0 +1,33 @@
+/** Domain-separation label. Permanent — see the header. */
+export declare const VEILO_NOTE_KEY_LABEL = "veilo_note_key_v1";
+/** The note spending key plus the Poseidon public key derived from it. */
+export interface NoteKeypair {
+    /** Raw 32-byte scalar, strictly below the BN254 Fr modulus. */
+    noteSecretKey: Uint8Array;
+    /** Hex form, matching how the relayer has always returned this key. */
+    noteSecretKeyHex: string;
+    /** Poseidon(noteSecretKey) — the note's committed owner. */
+    notePublicKey: bigint;
+    /** Decimal string form, as the relayer and note scanner expect it. */
+    notePublicKeyString: string;
+}
+/**
+ * Derive the note spending key from a spending-key root.
+ *
+ * @param spendingKey 32 bytes from `deriveSpendingKeyFromSignature` or a sibling
+ */
+export declare function deriveNoteKeyFromSpendingKey(spendingKey: Uint8Array): Uint8Array;
+/**
+ * Derive the note spending key and its Poseidon public key.
+ *
+ * Call `initPoseidon()` once before this, as with `derivePositionKeys`.
+ */
+export declare function deriveNoteKeypairFromSpendingKey(spendingKey: Uint8Array): NoteKeypair;
+/**
+ * One-shot derivation for a dapp holding only a wallet-standard `signMessage`.
+ *
+ * Prompts a single signature, then returns spend authority for the account.
+ * The signature is secret material: keep it in memory, never persist it, and
+ * never expose the result on a global.
+ */
+export declare function deriveNoteKeypairWithSigner(signMessage: (message: Uint8Array) => Promise<Uint8Array>, index?: number): Promise<NoteKeypair>;

package/dist/cjs/identity/noteKey.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VEILO_NOTE_KEY_LABEL = void 0;
+exports.deriveNoteKeyFromSpendingKey = deriveNoteKeyFromSpendingKey;
+exports.deriveNoteKeypairFromSpendingKey = deriveNoteKeypairFromSpendingKey;
+exports.deriveNoteKeypairWithSigner = deriveNoteKeypairWithSigner;
+/**
+ * Derivation of the Veilo NOTE SPENDING KEY from a spending-key root.
+ *
+ * ⚠ BYTE-FOR-BYTE PORT — must agree with
+ *   veilo-browser-extension/extension-ui/src/lib/veiloNoteKey.ts
+ *   wallet-app/src/lib/veiloNoteKey.ts
+ * An account created in one client must be spendable from the others, so the
+ * label, the HMAC construction and the rejection rule are all load-bearing.
+ * `tests/identity-keys.test.ts` re-implements the client algorithm
+ * independently and asserts equality, plus pins a known-answer vector.
+ *
+ * WHAT THIS KEY IS
+ * ----------------
+ * `zk-circuits/keypair.circom` defines publicKey = Poseidon(privateKey), and
+ * `transaction.circom` constrains Poseidon(privateKey) === the note's committed
+ * owner before it will emit a proof, then derives the nullifier from the same
+ * key. This one scalar is both proof of ownership and spend authority; there is
+ * no second factor anywhere in the circuit. Treat it exactly as you would a
+ * wallet secret key.
+ *
+ * Derivation:
+ *   spendingKey     = deriveSpendingKeyFromSignature(sig)          // ./spending.js
+ *   veiloPrivateKey = rejectionSample(hmac_sha256(spendingKey, "veilo_note_key_v1|N"))
+ *   veiloPublicKey  = Poseidon(veiloPrivateKey)
+ *
+ * WHY REJECTION SAMPLING AND NOT `mod Fr`
+ * ---------------------------------------
+ * Reducing a 256-bit hash modulo Fr biases the low end of the range. Note that
+ * `derivePositionKeys` uses modular reduction; this key follows the stricter
+ * convention because it is a SPENDING key, matching how real note secrets are
+ * generated. About 0.3% of draws are retried.
+ *
+ * ⚠ THE LABEL IS PERMANENT. Once one note exists under "veilo_note_key_v1",
+ * changing the label or the sampling method makes that note unspendable
+ * forever. Version it, never edit it.
+ *
+ * ⚠ APPLIES TO `derived-v3` ACCOUNTS ONLY. Accounts whose relayer record has
+ * `veiloKeySource` absent or "legacy" have a SERVER-GENERATED note key that no
+ * derivation can reproduce — those clients must decrypt the key the relayer
+ * serves them. Check the account's key source before assuming this function
+ * yields a usable key.
+ */
+const hmac_1 = require("@noble/hashes/hmac");
+const sha256_1 = require("@noble/hashes/sha256");
+const poseidon_js_1 = require("../poseidon.js");
+const encoding_js_1 = require("./encoding.js");
+const spending_js_1 = require("./spending.js");
+/** Domain-separation label. Permanent — see the header. */
+exports.VEILO_NOTE_KEY_LABEL = "veilo_note_key_v1";
+/** Practically unreachable: 256 consecutive rejections is ~1e-640. */
+const MAX_REJECTION_ROUNDS = 256;
+/**
+ * Derive the note spending key from a spending-key root.
+ *
+ * @param spendingKey 32 bytes from `deriveSpendingKeyFromSignature` or a sibling
+ */
+function deriveNoteKeyFromSpendingKey(spendingKey) {
+    (0, encoding_js_1.assertBytes)(spendingKey, 32, "spending key");
+    for (let counter = 0; counter < MAX_REJECTION_ROUNDS; counter++) {
+        const candidate = (0, hmac_1.hmac)(sha256_1.sha256, spendingKey, (0, encoding_js_1.utf8)(`${exports.VEILO_NOTE_KEY_LABEL}|${counter}`));
+        if ((0, poseidon_js_1.bytesToBigIntBE)(candidate) < poseidon_js_1.BN254_FR_MODULUS)
+            return candidate;
+    }
+    // Reaching here means HMAC-SHA256 is broken, not that we were unlucky.
+    throw new Error(`Failed to derive a field element for "${exports.VEILO_NOTE_KEY_LABEL}"`);
+}
+/**
+ * Derive the note spending key and its Poseidon public key.
+ *
+ * Call `initPoseidon()` once before this, as with `derivePositionKeys`.
+ */
+function deriveNoteKeypairFromSpendingKey(spendingKey) {
+    const noteSecretKey = deriveNoteKeyFromSpendingKey(spendingKey);
+    const notePublicKey = (0, poseidon_js_1.poseidon1)((0, poseidon_js_1.bytesToBigIntBE)(noteSecretKey));
+    return {
+        noteSecretKey,
+        noteSecretKeyHex: (0, encoding_js_1.bytesToHex)(noteSecretKey),
+        notePublicKey,
+        notePublicKeyString: notePublicKey.toString(),
+    };
+}
+/**
+ * One-shot derivation for a dapp holding only a wallet-standard `signMessage`.
+ *
+ * Prompts a single signature, then returns spend authority for the account.
+ * The signature is secret material: keep it in memory, never persist it, and
+ * never expose the result on a global.
+ */
+async function deriveNoteKeypairWithSigner(signMessage, index = 0) {
+    return deriveNoteKeypairFromSpendingKey(await (0, spending_js_1.deriveSpendingKeyWithSigner)(signMessage, index));
+}

package/dist/cjs/identity/spending.d.ts

@@ -0,0 +1,18 @@
+import { Keypair } from "@solana/web3.js";
+export declare const VEILO_SPENDING_KEY_DOMAIN = "veilo_spending_key_v1";
+/** Exact message signed by Veilo clients to derive a spending-key root. */
+export declare function getSpendingKeyMessage(index?: number): Uint8Array;
+/** Convert the deterministic 64-byte wallet signature into a spending key. */
+export declare function deriveSpendingKeyFromSignature(signature: Uint8Array): Uint8Array;
+/**
+ * Wallet-standard-friendly spending-key derivation.
+ * The callback owns signing; the SDK never receives the wallet secret key.
+ */
+export declare function deriveSpendingKeyWithSigner(signMessage: (message: Uint8Array) => Promise<Uint8Array>, index?: number): Promise<Uint8Array>;
+/**
+ * Keypair convenience matching the wallet-app and extension implementation.
+ * Keep the keypair on the user's device and never send it to a service.
+ */
+export declare function deriveSpendingKeyFromKeypair(keypair: Keypair, index?: number): Uint8Array;
+/** Serialize an ephemeral claimant secret for an encrypted relayer request. */
+export declare function encodeClaimantSecretKey(keypairOrSecret: Keypair | Uint8Array): string;

package/dist/cjs/identity/spending.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VEILO_SPENDING_KEY_DOMAIN = void 0;
+exports.getSpendingKeyMessage = getSpendingKeyMessage;
+exports.deriveSpendingKeyFromSignature = deriveSpendingKeyFromSignature;
+exports.deriveSpendingKeyWithSigner = deriveSpendingKeyWithSigner;
+exports.deriveSpendingKeyFromKeypair = deriveSpendingKeyFromKeypair;
+exports.encodeClaimantSecretKey = encodeClaimantSecretKey;
+const sha256_1 = require("@noble/hashes/sha256");
+const tweetnacl_1 = __importDefault(require("tweetnacl"));
+const encoding_js_1 = require("./encoding.js");
+exports.VEILO_SPENDING_KEY_DOMAIN = "veilo_spending_key_v1";
+/** Exact message signed by Veilo clients to derive a spending-key root. */
+function getSpendingKeyMessage(index = 0) {
+    return (0, encoding_js_1.concatBytes)((0, encoding_js_1.utf8)(exports.VEILO_SPENDING_KEY_DOMAIN), (0, encoding_js_1.uint32Le)(index, "spending-key index"));
+}
+/** Convert the deterministic 64-byte wallet signature into a spending key. */
+function deriveSpendingKeyFromSignature(signature) {
+    (0, encoding_js_1.assertBytes)(signature, 64, "spending-key signature");
+    return (0, sha256_1.sha256)(signature);
+}
+/**
+ * Wallet-standard-friendly spending-key derivation.
+ * The callback owns signing; the SDK never receives the wallet secret key.
+ */
+async function deriveSpendingKeyWithSigner(signMessage, index = 0) {
+    return deriveSpendingKeyFromSignature(await signMessage(getSpendingKeyMessage(index)));
+}
+/**
+ * Keypair convenience matching the wallet-app and extension implementation.
+ * Keep the keypair on the user's device and never send it to a service.
+ */
+function deriveSpendingKeyFromKeypair(keypair, index = 0) {
+    return deriveSpendingKeyFromSignature(tweetnacl_1.default.sign.detached(getSpendingKeyMessage(index), keypair.secretKey));
+}
+/** Serialize an ephemeral claimant secret for an encrypted relayer request. */
+function encodeClaimantSecretKey(keypairOrSecret) {
+    const secret = keypairOrSecret instanceof Uint8Array
+        ? keypairOrSecret
+        : keypairOrSecret.secretKey;
+    (0, encoding_js_1.assertBytes)(secret, 64, "claimant secret key");
+    return (0, encoding_js_1.encodeBase58)(secret);
+}

package/dist/cjs/identity/viewKey.d.ts

@@ -0,0 +1,38 @@
+import type { CompactNoteCipher } from "../compactNote.js";
+/** HKDF salt. Provisional — see the header. */
+export declare const VEILO_VIEW_KEY_SALT = "veilo_view_v1";
+/** HKDF info. Provisional — see the header. */
+export declare const VEILO_VIEW_KEY_INFO = "x25519";
+/** An X25519 keypair used only to decrypt notes. */
+export interface ViewKeypair {
+    /** 32-byte clamped X25519 scalar. Secret: decrypts every note sent to it. */
+    viewSecretKey: Uint8Array;
+    /** 32-byte X25519 public key — the value senders encrypt to. */
+    viewPublicKey: Uint8Array;
+}
+/** Derive the view keypair from a spending-key root. */
+export declare function deriveViewKeypairFromSpendingKey(spendingKey: Uint8Array): ViewKeypair;
+/**
+ * One-shot derivation for a dapp holding only a wallet-standard `signMessage`.
+ *
+ * Uses the same signature as `deriveNoteKeypairWithSigner`, so a client that
+ * wants both prompts once and derives the spending key itself rather than
+ * calling both helpers.
+ */
+export declare function deriveViewKeypairWithSigner(signMessage: (message: Uint8Array) => Promise<Uint8Array>, index?: number): Promise<ViewKeypair>;
+/**
+ * Scan one candidate cipher with a view key.
+ *
+ * Returns `null` both for a view-tag miss and for a blob that was not encrypted
+ * to this key — the expected outcome for nearly every candidate. The shared
+ * secret is computed once and reused for the tag check and the open, which is
+ * the cheapest correct order for a scan loop: the tag rejects ~255/256
+ * candidates for one scalar multiplication and one hash.
+ *
+ * ⚠ Only decrypts notes encrypted TO `viewPublicKey`. Notes sealed to a wallet
+ * Ed25519 key — every note written before the v2 format — will not open here.
+ */
+export declare function openCompactNoteWithViewKey(viewSecretKey: Uint8Array, cipher: CompactNoteCipher): {
+    blinding: Uint8Array;
+    amount: bigint;
+} | null;