@veilo/sdk-core 0.4.0 → 0.6.0

package/dist/esm/events/tree.d.ts

@@ -0,0 +1,27 @@
+import type { Idl, Program } from "@coral-xyz/anchor";
+import type { PublicKey } from "@solana/web3.js";
+import { MerkleTree } from "../merkle.js";
+import type { CommitmentEvent } from "./types.js";
+/** Rebuild a local Veilo tree from emitted, computed, and protected history. */
+export declare function buildTreeFromEvents<T extends Idl>(params: {
+    program: Program<T>;
+    mintAddress: PublicKey;
+    treeId?: number;
+    depth?: number;
+    /** Eventless commitments recovered with the helpers in `events/recovery`. */
+    additionalEvents?: readonly CommitmentEvent[];
+    /** Includes the relayer's two protected historical repairs. Defaults to true. */
+    includeProtectedEvents?: boolean;
+    /** Reject missing or duplicate leaf indices instead of building a wrong root. */
+    strictLeafIndices?: boolean;
+}): Promise<{
+    tree: MerkleTree;
+    events: CommitmentEvent[];
+    latestSignature?: string;
+}>;
+export declare function dedupeCommitmentEvents(events: readonly CommitmentEvent[]): CommitmentEvent[];
+/** Build a Merkle tree from already-collected events in authoritative order. */
+export declare function reconstructTreeFromCommitmentEvents(events: readonly CommitmentEvent[], options?: {
+    depth?: number;
+    strictLeafIndices?: boolean;
+}): MerkleTree;

package/dist/esm/events/tree.js

@@ -0,0 +1,58 @@
+import { MerkleTree } from "../merkle.js";
+import { mergeProtectedCommitmentEvents } from "./recovery.js";
+import { scanAllCommitmentEvents } from "./scanning.js";
+/** Rebuild a local Veilo tree from emitted, computed, and protected history. */
+export async function buildTreeFromEvents(params) {
+    const { program, mintAddress, treeId = 0, depth = 22, additionalEvents = [], includeProtectedEvents = true, strictLeafIndices = true, } = params;
+    const emitted = await scanAllCommitmentEvents({ program, mintAddress });
+    let treeEvents = dedupeCommitmentEvents([...emitted, ...additionalEvents])
+        .filter((event) => event.treeId === treeId && event.mintAddress.equals(mintAddress))
+        .sort((a, b) => a.leafIndex - b.leafIndex);
+    if (includeProtectedEvents) {
+        treeEvents = mergeProtectedCommitmentEvents(treeEvents, {
+            mintAddress,
+            treeId,
+        });
+    }
+    const tree = reconstructTreeFromCommitmentEvents(treeEvents, {
+        depth,
+        strictLeafIndices,
+    });
+    return {
+        tree,
+        events: treeEvents,
+        latestSignature: treeEvents[treeEvents.length - 1]?.txSignature,
+    };
+}
+export function dedupeCommitmentEvents(events) {
+    const byCommitment = new Map();
+    for (const event of events) {
+        const key = Array.from(event.commitment, (value) => value.toString(16).padStart(2, "0")).join("");
+        const existing = byCommitment.get(key);
+        if (!existing || eventPriority(event) > eventPriority(existing)) {
+            byCommitment.set(key, event);
+        }
+    }
+    return [...byCommitment.values()];
+}
+function eventPriority(event) {
+    // Events created before `source` was added came from on-chain log scans and
+    // are therefore treated as authoritative emitted records.
+    if (event.source === "protected")
+        return 1;
+    if (event.source === "computed")
+        return 2;
+    return 3;
+}
+/** Build a Merkle tree from already-collected events in authoritative order. */
+export function reconstructTreeFromCommitmentEvents(events, options = {}) {
+    const tree = new MerkleTree(options.depth ?? 22);
+    for (const event of [...events].sort((a, b) => a.leafIndex - b.leafIndex)) {
+        if ((options.strictLeafIndices ?? true) &&
+            event.leafIndex !== tree.nextIndex) {
+            throw new Error(`Commitment history gap: expected leaf ${tree.nextIndex}, got ${event.leafIndex}`);
+        }
+        tree.insert(event.commitment);
+    }
+    return tree;
+}

package/dist/esm/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/esm/events/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/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/esm/events.js

@@ -1,129 +1,3 @@
-import * as anchor from "@coral-xyz/anchor";
-import { MerkleTree } from "./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)
- */
-export 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.
- */
-export 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)
- */
-export 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 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.
+export * from "./events/index.js";

package/dist/esm/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/esm/identity/encoding.js

@@ -0,0 +1,75 @@
+const BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+export 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;
+}
+export function utf8(value) {
+    return new TextEncoder().encode(value);
+}
+export 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;
+}
+export 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;
+}
+export function assertBytes(value, length, label) {
+    if (value.length !== length) {
+        throw new RangeError(`${label} must be ${length} bytes, got ${value.length}`);
+    }
+}
+export function bytesToHex(bytes) {
+    return Array.from(bytes, (value) => value.toString(16).padStart(2, "0")).join("");
+}
+export 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. */
+export 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/esm/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/esm/identity/index.js

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

package/dist/esm/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/esm/identity/noteKey.js

@@ -0,0 +1,91 @@
+/**
+ * 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.
+ */
+import { hmac } from "@noble/hashes/hmac";
+import { sha256 } from "@noble/hashes/sha256";
+import { BN254_FR_MODULUS, bytesToBigIntBE, poseidon1 } from "../poseidon.js";
+import { assertBytes, bytesToHex, utf8 } from "./encoding.js";
+import { deriveSpendingKeyWithSigner } from "./spending.js";
+/** Domain-separation label. Permanent — see the header. */
+export const 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
+ */
+export function deriveNoteKeyFromSpendingKey(spendingKey) {
+    assertBytes(spendingKey, 32, "spending key");
+    for (let counter = 0; counter < MAX_REJECTION_ROUNDS; counter++) {
+        const candidate = hmac(sha256, spendingKey, utf8(`${VEILO_NOTE_KEY_LABEL}|${counter}`));
+        if (bytesToBigIntBE(candidate) < 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 "${VEILO_NOTE_KEY_LABEL}"`);
+}
+/**
+ * Derive the note spending key and its Poseidon public key.
+ *
+ * Call `initPoseidon()` once before this, as with `derivePositionKeys`.
+ */
+export function deriveNoteKeypairFromSpendingKey(spendingKey) {
+    const noteSecretKey = deriveNoteKeyFromSpendingKey(spendingKey);
+    const notePublicKey = poseidon1(bytesToBigIntBE(noteSecretKey));
+    return {
+        noteSecretKey,
+        noteSecretKeyHex: 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.
+ */
+export async function deriveNoteKeypairWithSigner(signMessage, index = 0) {
+    return deriveNoteKeypairFromSpendingKey(await deriveSpendingKeyWithSigner(signMessage, index));
+}

package/dist/esm/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/esm/identity/spending.js

@@ -0,0 +1,35 @@
+import { sha256 } from "@noble/hashes/sha256";
+import nacl from "tweetnacl";
+import { assertBytes, concatBytes, encodeBase58, uint32Le, utf8, } from "./encoding.js";
+export const VEILO_SPENDING_KEY_DOMAIN = "veilo_spending_key_v1";
+/** Exact message signed by Veilo clients to derive a spending-key root. */
+export function getSpendingKeyMessage(index = 0) {
+    return concatBytes(utf8(VEILO_SPENDING_KEY_DOMAIN), uint32Le(index, "spending-key index"));
+}
+/** Convert the deterministic 64-byte wallet signature into a spending key. */
+export function deriveSpendingKeyFromSignature(signature) {
+    assertBytes(signature, 64, "spending-key signature");
+    return sha256(signature);
+}
+/**
+ * Wallet-standard-friendly spending-key derivation.
+ * The callback owns signing; the SDK never receives the wallet secret key.
+ */
+export 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.
+ */
+export function deriveSpendingKeyFromKeypair(keypair, index = 0) {
+    return deriveSpendingKeyFromSignature(nacl.sign.detached(getSpendingKeyMessage(index), keypair.secretKey));
+}
+/** Serialize an ephemeral claimant secret for an encrypted relayer request. */
+export function encodeClaimantSecretKey(keypairOrSecret) {
+    const secret = keypairOrSecret instanceof Uint8Array
+        ? keypairOrSecret
+        : keypairOrSecret.secretKey;
+    assertBytes(secret, 64, "claimant secret key");
+    return encodeBase58(secret);
+}

package/dist/esm/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;