@veilo/sdk-core 0.4.0 → 0.6.0

package/dist/cjs/notes/model.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateKeypair = generateKeypair;
+exports.derivePublicKey = derivePublicKey;
+exports.keypairFromPrivateKey = keypairFromPrivateKey;
+exports.commitUTXO = commitUTXO;
+exports.createUTXO = createUTXO;
+exports.createOwnedUTXO = createOwnedUTXO;
+exports.createZeroUTXO = createZeroUTXO;
+exports.createOwnedZeroUTXO = createOwnedZeroUTXO;
+const random_js_1 = require("../random.js");
+const poseidon_js_1 = require("../poseidon.js");
+// -----------------------------------------------------------------------------
+// Keypair Functions
+// -----------------------------------------------------------------------------
+/**
+ * Generate a random keypair.
+ * Private key is a random 32-byte scalar.
+ * Public key is derived via Poseidon: pubkey = Poseidon(privateKey)
+ */
+function generateKeypair() {
+    const privateKeyBytes = new Uint8Array((0, random_js_1.randomBytes)(32));
+    const privateKey = (0, poseidon_js_1.bytesToBigIntBE)(privateKeyBytes) % poseidon_js_1.BN254_FR_MODULUS;
+    const publicKey = derivePublicKey(privateKey);
+    return { privateKey, publicKey };
+}
+/**
+ * Derive public key from private key.
+ * Matches circuit's Keypair template: publicKey = Poseidon(privateKey)
+ */
+function derivePublicKey(privateKey) {
+    return (0, poseidon_js_1.poseidon1)(privateKey);
+}
+/**
+ * Create keypair from a known private key.
+ */
+function keypairFromPrivateKey(privateKey) {
+    return {
+        privateKey: privateKey % poseidon_js_1.BN254_FR_MODULUS,
+        publicKey: derivePublicKey(privateKey % poseidon_js_1.BN254_FR_MODULUS),
+    };
+}
+// -----------------------------------------------------------------------------
+// UTXO Commitment Functions
+// -----------------------------------------------------------------------------
+/**
+ * Compute UTXO commitment.
+ * Matches circuit's UTXOCommitment template:
+ *   commitment = Poseidon(amount, pubkey, blinding, mintAddress)
+ */
+function commitUTXO(utxo) {
+    const commitment = (0, poseidon_js_1.poseidon4)(utxo.amount, utxo.pubkey, utxo.blinding, utxo.mintAddress);
+    return (0, poseidon_js_1.bigIntToBytesBE)(commitment);
+}
+/**
+ * Create a random UTXO with the given parameters.
+ */
+function createUTXO(params) {
+    const blindingBytes = new Uint8Array((0, random_js_1.randomBytes)(32));
+    const blinding = (0, poseidon_js_1.bytesToBigIntBE)(blindingBytes) % poseidon_js_1.BN254_FR_MODULUS;
+    const utxo = {
+        amount: params.amount,
+        pubkey: params.pubkey,
+        blinding,
+        mintAddress: (0, poseidon_js_1.pubkeyToField)(params.mintAddress),
+    };
+    const commitment = commitUTXO(utxo);
+    return {
+        ...utxo,
+        commitment,
+    };
+}
+/**
+ * Create a UTXO with a specified private key (for owned UTXOs).
+ */
+function createOwnedUTXO(params) {
+    const keypair = keypairFromPrivateKey(params.privateKey);
+    const utxo = createUTXO({
+        amount: params.amount,
+        pubkey: keypair.publicKey,
+        mintAddress: params.mintAddress,
+    });
+    return {
+        ...utxo,
+        privateKey: keypair.privateKey,
+    };
+}
+/**
+ * Create a zero UTXO (for deposits where no input exists).
+ * Zero UTXOs have amount=0 and are used as placeholders in 2-in-2-out transactions.
+ */
+function createZeroUTXO(pubkey, mintAddress) {
+    return createUTXO({
+        amount: 0n,
+        pubkey,
+        mintAddress,
+    });
+}
+/**
+ * Create a zero UTXO with private key (for owned zero UTXOs).
+ */
+function createOwnedZeroUTXO(privateKey, mintAddress) {
+    const keypair = keypairFromPrivateKey(privateKey);
+    const utxo = createZeroUTXO(keypair.publicKey, mintAddress);
+    return {
+        ...utxo,
+        privateKey: keypair.privateKey,
+    };
+}

package/dist/cjs/notes/nullifier.d.ts

@@ -0,0 +1,27 @@
+import type { InputUTXO, SerializedUTXO } from "./model.js";
+/**
+ * Compute signature for nullifier derivation.
+ * Matches circuit's Signature template:
+ *   signature = Poseidon(privateKey, commitment, pathIndex)
+ */
+export declare function computeSignature(privateKey: bigint, commitment: bigint, pathIndex: bigint): bigint;
+/**
+ * Derive nullifier for a UTXO.
+ * Matches circuit's UTXONullifier template:
+ *   signature = Poseidon(privateKey, commitment, pathIndex)
+ *   nullifier = Poseidon(commitment, pathIndex, signature)
+ *
+ * The signature-based nullifier ensures only the private key holder can spend.
+ */
+export declare function deriveNullifier(utxo: SerializedUTXO, pathIndex: number, privateKey: bigint): Uint8Array;
+/**
+ * Convert InputUTXO to the format expected by the circuit.
+ */
+export declare function inputUTXOToCircuitFormat(input: InputUTXO): {
+    amount: bigint;
+    pubkey: bigint;
+    blinding: bigint;
+    pathElements: bigint[];
+    pathIndex: number;
+    privateKey: bigint;
+};

package/dist/cjs/notes/nullifier.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeSignature = computeSignature;
+exports.deriveNullifier = deriveNullifier;
+exports.inputUTXOToCircuitFormat = inputUTXOToCircuitFormat;
+const poseidon_js_1 = require("../poseidon.js");
+// -----------------------------------------------------------------------------
+// Nullifier Functions
+// -----------------------------------------------------------------------------
+/**
+ * Compute signature for nullifier derivation.
+ * Matches circuit's Signature template:
+ *   signature = Poseidon(privateKey, commitment, pathIndex)
+ */
+function computeSignature(privateKey, commitment, pathIndex) {
+    return (0, poseidon_js_1.poseidon3)(privateKey, commitment, pathIndex);
+}
+/**
+ * Derive nullifier for a UTXO.
+ * Matches circuit's UTXONullifier template:
+ *   signature = Poseidon(privateKey, commitment, pathIndex)
+ *   nullifier = Poseidon(commitment, pathIndex, signature)
+ *
+ * The signature-based nullifier ensures only the private key holder can spend.
+ */
+function deriveNullifier(utxo, pathIndex, privateKey) {
+    const commitment = (0, poseidon_js_1.bytesToBigIntBE)(utxo.commitment) % poseidon_js_1.BN254_FR_MODULUS;
+    const pathIndexField = BigInt(pathIndex) % poseidon_js_1.BN254_FR_MODULUS;
+    const signature = computeSignature(privateKey, commitment, pathIndexField);
+    const nullifier = (0, poseidon_js_1.poseidon3)(commitment, pathIndexField, signature);
+    return (0, poseidon_js_1.bigIntToBytesBE)(nullifier);
+}
+/**
+ * Convert InputUTXO to the format expected by the circuit.
+ */
+function inputUTXOToCircuitFormat(input) {
+    return {
+        amount: input.amount,
+        pubkey: input.pubkey,
+        blinding: input.blinding,
+        pathElements: input.pathElements.map((e) => (0, poseidon_js_1.bytesToBigIntBE)(e) % poseidon_js_1.BN254_FR_MODULUS),
+        pathIndex: input.pathIndex,
+        privateKey: input.privateKey,
+    };
+}

package/dist/cjs/notes/recovery.d.ts

@@ -0,0 +1,20 @@
+import type { DecryptedNote } from "./mailbox.js";
+/**
+ * Fetch this account's encrypted notes from the relayer and decrypt them.
+ *
+ * Goes through the managed relayer helper, so the network coordinates stay
+ * internal — there is no URL to pass. Notes that fail to decrypt are skipped:
+ * a query can return rows addressed to other keys, and one bad row must not
+ * lose the rest.
+ *
+ * @param authToken       token from `register()` / `restore()`
+ * @param walletSecretKey full 64-byte keypair.secretKey, used for decryption
+ * @param walletPublicKey optional base58 filter, narrowing the query server-side
+ */
+export declare function fetchAndDecryptNotes(params: {
+    authToken: string;
+    walletSecretKey: Uint8Array;
+    walletPublicKey?: string;
+    limit?: number;
+    offset?: number;
+}): Promise<DecryptedNote[]>;

package/dist/cjs/notes/recovery.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchAndDecryptNotes = fetchAndDecryptNotes;
+const api_js_1 = require("../relayer/api.js");
+const mailbox_js_1 = require("./mailbox.js");
+/**
+ * Fetch this account's encrypted notes from the relayer and decrypt them.
+ *
+ * Goes through the managed relayer helper, so the network coordinates stay
+ * internal — there is no URL to pass. Notes that fail to decrypt are skipped:
+ * a query can return rows addressed to other keys, and one bad row must not
+ * lose the rest.
+ *
+ * @param authToken       token from `register()` / `restore()`
+ * @param walletSecretKey full 64-byte keypair.secretKey, used for decryption
+ * @param walletPublicKey optional base58 filter, narrowing the query server-side
+ */
+async function fetchAndDecryptNotes(params) {
+    const { authToken, walletSecretKey, walletPublicKey, limit, offset } = params;
+    const { notes } = await (0, api_js_1.queryEncryptedNotes)(authToken, {
+        ...(walletPublicKey ? { walletPublicKey } : {}),
+        ...(limit === undefined ? {} : { limit }),
+        ...(offset === undefined ? {} : { offset }),
+    });
+    const results = [];
+    for (const note of notes ?? []) {
+        if (!note.ephemeralPublicKey || !note.encryptedBlob)
+            continue;
+        try {
+            results.push((0, mailbox_js_1.decryptBlindMailboxNote)(walletSecretKey, base64ToBytes(note.ephemeralPublicKey), note.encryptedBlob));
+        }
+        catch {
+            // Not addressed to this key, or corrupted — skip it.
+        }
+    }
+    return results;
+}
+/** Base64 → bytes without assuming a Node Buffer global. */
+function base64ToBytes(value) {
+    if (typeof atob === "function") {
+        const binary = atob(value);
+        const out = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++)
+            out[i] = binary.charCodeAt(i);
+        return out;
+    }
+    return new Uint8Array(Buffer.from(value, "base64"));
+}

package/dist/cjs/notes/selection.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Choosing which notes to spend.
+ *
+ * Two constraints drive everything here:
+ *
+ *  1. The transaction circuit is 2-in-2-out, so a single transaction can spend
+ *     at most TWO notes.
+ *  2. Notes can only be co-spent if they live in the SAME Merkle tree, and the
+ *     tree is derived from the MINT — see `canonicalTreeId`.
+ */
+/** Inputs the transaction circuit accepts in one proof. */
+export declare const MAX_INPUT_NOTES = 2;
+/**
+ * The tree a note belongs to, derived from its mint.
+ *
+ * Mirrors the relayer's `mintAddressToTreeId` byte for byte: the all-zero
+ * native-SOL mint maps to 0, anything else to its first four mint bytes as a
+ * big-endian uint32.
+ *
+ * DERIVE THIS, NEVER TRUST A STORED `treeId`. Change notes are written with the
+ * on-chain shard index (a small 0/1/2…) while deposits and synced notes carry
+ * the mint-derived id. For native SOL both are 0 so the difference hides; for
+ * SPL tokens the two land in different buckets, and co-spending across them
+ * fails at proof time as a commitment mismatch.
+ *
+ * An undecodable mint falls back to the SOL bucket rather than inventing a
+ * phantom tree, matching the server.
+ */
+export declare function canonicalTreeId(mintAddress?: string | null): number;
+/** The minimum a note must carry to be selectable. */
+export interface SelectableNote {
+    /** Base units. bigint preferred; strings and safe integers accepted. */
+    amount: bigint | string | number;
+    /** Mint address; determines the tree. Absent means native SOL. */
+    mint?: string | null;
+}
+export interface NoteSelection<T> {
+    ok: true;
+    /** The chosen notes, your own objects. */
+    notes: T[];
+    /** Tree every chosen note belongs to. */
+    treeId: number;
+    /** Sum of the chosen notes. */
+    total: bigint;
+    /** total - amount. Becomes the change note. */
+    change: bigint;
+    /**
+     * True when more than MAX_INPUT_NOTES were needed, so this cannot be proved
+     * as one transaction — the notes must be combined first.
+     */
+    requiresMerge: boolean;
+}
+export interface NoteSelectionFailure {
+    ok: false;
+    reason: "NO_NOTES" | "INSUFFICIENT_FUNDS";
+    /** Largest total reachable within a single tree. */
+    available: bigint;
+    message: string;
+}
+export type NoteSelectionResult<T> = NoteSelection<T> | NoteSelectionFailure;
+/**
+ * Pick notes to cover `amount`, preferring the fewest notes and least change.
+ *
+ * Considers each tree separately, since notes cannot be co-spent across trees,
+ * and returns the best single-tree selection:
+ *
+ *   1. one note that covers the amount (smallest such note, least change);
+ *   2. otherwise the best PAIR, found by a two-pointer scan over the
+ *      amount-sorted notes — O(n) rather than an O(n²) all-pairs search;
+ *   3. otherwise the largest notes greedily, flagged `requiresMerge` because
+ *      more than two inputs cannot go into one proof.
+ *
+ * @param amount base units to cover
+ */
+export declare function selectNotesForAmount<T extends SelectableNote>(notes: T[], amount: bigint | string | number, options?: {
+    mint?: string | null;
+}): NoteSelectionResult<T>;

package/dist/cjs/notes/selection.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_INPUT_NOTES = void 0;
+exports.canonicalTreeId = canonicalTreeId;
+exports.selectNotesForAmount = selectNotesForAmount;
+const web3_js_1 = require("@solana/web3.js");
+const amount_js_1 = require("./amount.js");
+/**
+ * Choosing which notes to spend.
+ *
+ * Two constraints drive everything here:
+ *
+ *  1. The transaction circuit is 2-in-2-out, so a single transaction can spend
+ *     at most TWO notes.
+ *  2. Notes can only be co-spent if they live in the SAME Merkle tree, and the
+ *     tree is derived from the MINT — see `canonicalTreeId`.
+ */
+/** Inputs the transaction circuit accepts in one proof. */
+exports.MAX_INPUT_NOTES = 2;
+/**
+ * The tree a note belongs to, derived from its mint.
+ *
+ * Mirrors the relayer's `mintAddressToTreeId` byte for byte: the all-zero
+ * native-SOL mint maps to 0, anything else to its first four mint bytes as a
+ * big-endian uint32.
+ *
+ * DERIVE THIS, NEVER TRUST A STORED `treeId`. Change notes are written with the
+ * on-chain shard index (a small 0/1/2…) while deposits and synced notes carry
+ * the mint-derived id. For native SOL both are 0 so the difference hides; for
+ * SPL tokens the two land in different buckets, and co-spending across them
+ * fails at proof time as a commitment mismatch.
+ *
+ * An undecodable mint falls back to the SOL bucket rather than inventing a
+ * phantom tree, matching the server.
+ */
+function canonicalTreeId(mintAddress) {
+    if (!mintAddress || mintAddress.trim() === "")
+        return 0;
+    try {
+        const bytes = new web3_js_1.PublicKey(mintAddress).toBytes();
+        if (bytes.every((byte) => byte === 0))
+            return 0;
+        return (((bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3]) >>> 0);
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Pick notes to cover `amount`, preferring the fewest notes and least change.
+ *
+ * Considers each tree separately, since notes cannot be co-spent across trees,
+ * and returns the best single-tree selection:
+ *
+ *   1. one note that covers the amount (smallest such note, least change);
+ *   2. otherwise the best PAIR, found by a two-pointer scan over the
+ *      amount-sorted notes — O(n) rather than an O(n²) all-pairs search;
+ *   3. otherwise the largest notes greedily, flagged `requiresMerge` because
+ *      more than two inputs cannot go into one proof.
+ *
+ * @param amount base units to cover
+ */
+function selectNotesForAmount(notes, amount, options = {}) {
+    const target = (0, amount_js_1.toBaseUnits)(amount, "amount");
+    if (target <= 0n) {
+        throw new Error(`amount must be positive, got ${target}`);
+    }
+    const wanted = options.mint === undefined ? undefined : canonicalTreeId(options.mint);
+    const byTree = new Map();
+    notes.forEach((note, index) => {
+        const treeId = canonicalTreeId(note.mint);
+        if (wanted !== undefined && treeId !== wanted)
+            return;
+        const entry = {
+            note,
+            amount: (0, amount_js_1.toBaseUnits)(note.amount, `notes[${index}].amount`),
+        };
+        if (entry.amount <= 0n)
+            return;
+        const bucket = byTree.get(treeId);
+        if (bucket)
+            bucket.push(entry);
+        else
+            byTree.set(treeId, [entry]);
+    });
+    if (byTree.size === 0) {
+        return {
+            ok: false,
+            reason: "NO_NOTES",
+            available: 0n,
+            message: "No spendable notes for the requested mint.",
+        };
+    }
+    let best;
+    let available = 0n;
+    for (const [treeId, bucket] of byTree) {
+        const treeTotal = bucket.reduce((sum, entry) => sum + entry.amount, 0n);
+        if (treeTotal > available)
+            available = treeTotal;
+        const selection = selectWithinTree(bucket, target, treeId);
+        if (!selection)
+            continue;
+        if (!best || isBetter(selection, best))
+            best = selection;
+    }
+    if (!best) {
+        return {
+            ok: false,
+            reason: "INSUFFICIENT_FUNDS",
+            available,
+            message: `No single tree holds ${target} base units. Largest tree total is ` +
+                `${available}. Notes in different trees cannot be co-spent.`,
+        };
+    }
+    return best;
+}
+/** Fewer inputs first, then least change. */
+function isBetter(a, b) {
+    if (a.notes.length !== b.notes.length)
+        return a.notes.length < b.notes.length;
+    return a.change < b.change;
+}
+function selectWithinTree(bucket, target, treeId) {
+    // Descending by amount, compared as bigint: Number() would lose precision
+    // above 2^53 base units.
+    const sorted = [...bucket].sort((a, b) => b.amount > a.amount ? 1 : b.amount < a.amount ? -1 : 0);
+    // 1. Smallest single note that covers the target — walk up from the end.
+    let single;
+    for (let i = sorted.length - 1; i >= 0; i--) {
+        if (sorted[i].amount >= target) {
+            single = sorted[i];
+            break;
+        }
+    }
+    if (single) {
+        return {
+            ok: true,
+            notes: [single.note],
+            treeId,
+            total: single.amount,
+            change: single.amount - target,
+            requiresMerge: false,
+        };
+    }
+    // 2. Best pair by two-pointer scan over the descending list.
+    let bestPair;
+    let bestChange = 0n;
+    let lo = 0;
+    let hi = sorted.length - 1;
+    while (lo < hi) {
+        const combined = sorted[lo].amount + sorted[hi].amount;
+        if (combined >= target) {
+            const change = combined - target;
+            if (!bestPair || change < bestChange) {
+                bestChange = change;
+                bestPair = [sorted[lo], sorted[hi]];
+            }
+            lo++;
+        }
+        else {
+            hi--;
+        }
+    }
+    if (bestPair) {
+        return {
+            ok: true,
+            notes: [bestPair[0].note, bestPair[1].note],
+            treeId,
+            total: bestPair[0].amount + bestPair[1].amount,
+            change: bestChange,
+            requiresMerge: false,
+        };
+    }
+    // 3. Greedy over the largest notes. More than two inputs, so it needs a merge.
+    const chosen = [];
+    let total = 0n;
+    for (const entry of sorted) {
+        chosen.push(entry);
+        total += entry.amount;
+        if (total >= target)
+            break;
+    }
+    if (total < target)
+        return undefined;
+    return {
+        ok: true,
+        notes: chosen.map((entry) => entry.note),
+        treeId,
+        total,
+        change: total - target,
+        requiresMerge: chosen.length > exports.MAX_INPUT_NOTES,
+    };
+}

package/dist/cjs/notes/spent.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Spend status and private balance.
+ *
+ * A note is yours until its nullifier is published; nothing in the note itself
+ * says whether it has been spent. So a balance is always two steps: ask which
+ * nullifiers are spent, then sum what is left. This module is that pair.
+ */
+/** Server-side cap per check-batch request (notes.constants MAX_NULLIFIERS_PER_CHECK). */
+export declare const MAX_NULLIFIERS_PER_CHECK = 200;
+/** Grouping key used for notes that carry no mint. */
+export declare const UNKNOWN_MINT = "unknown";
+/**
+ * Ask the relayer which of these nullifiers are spent.
+ *
+ * Deduplicates, lower-cases, and splits into MAX_NULLIFIERS_PER_CHECK batches
+ * that are issued concurrently. Returns a Set for membership testing; a
+ * nullifier absent from it is unspent as far as the relayer knows.
+ *
+ * @throws if any entry is not 64-char hex — a malformed nullifier that silently
+ *         read as "unspent" would overstate a balance.
+ */
+export declare function checkNullifiersSpent(nullifiers: string[]): Promise<Set<string>>;
+/** The minimum a note must carry to be counted. */
+export interface SpendableNote {
+    /** Base units. bigint preferred; strings and safe integers are accepted. */
+    amount: bigint | string | number;
+    /** 64-character hex nullifier for this note. */
+    nullifier: string;
+    /** Mint this note is denominated in. Groups the result; optional. */
+    mint?: string;
+}
+export interface PrivateBalance<T extends SpendableNote = SpendableNote> {
+    /** Sum of every unspent note, across all mints. */
+    total: bigint;
+    /** Unspent totals keyed by mint (UNKNOWN_MINT when a note carries none). */
+    byMint: Record<string, bigint>;
+    /** The caller's own note objects, partitioned. */
+    unspent: T[];
+    spent: T[];
+}
+export interface PrivateBalanceOptions {
+    /**
+     * Supply spend status yourself instead of asking the relayer — e.g. from a
+     * chain scan of nullifier events, or a local cache. Receives normalized
+     * lower-case hex.
+     */
+    resolveSpent?: (nullifiers: string[]) => Promise<Set<string>> | Set<string>;
+}
+/**
+ * Sum unspent notes, per mint and in total.
+ *
+ * ```ts
+ * const { total, byMint, unspent } = await getPrivateBalance(myNotes);
+ * ```
+ *
+ * Amounts are base units and stay bigint throughout — never sum note amounts as
+ * numbers. Notes are matched to spend status by nullifier, so every note needs
+ * one; the partitioned arrays hand back your own objects, not copies.
+ */
+export declare function getPrivateBalance<T extends SpendableNote>(notes: T[], options?: PrivateBalanceOptions): Promise<PrivateBalance<T>>;

package/dist/cjs/notes/spent.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNKNOWN_MINT = exports.MAX_NULLIFIERS_PER_CHECK = void 0;
+exports.checkNullifiersSpent = checkNullifiersSpent;
+exports.getPrivateBalance = getPrivateBalance;
+const api_js_1 = require("../relayer/api.js");
+const amount_js_1 = require("./amount.js");
+/**
+ * Spend status and private balance.
+ *
+ * A note is yours until its nullifier is published; nothing in the note itself
+ * says whether it has been spent. So a balance is always two steps: ask which
+ * nullifiers are spent, then sum what is left. This module is that pair.
+ */
+/** Server-side cap per check-batch request (notes.constants MAX_NULLIFIERS_PER_CHECK). */
+exports.MAX_NULLIFIERS_PER_CHECK = 200;
+/** Grouping key used for notes that carry no mint. */
+exports.UNKNOWN_MINT = "unknown";
+const HEX64 = /^[0-9a-f]{64}$/;
+/**
+ * Normalize a nullifier to the form the relayer answers in.
+ *
+ * The endpoint's validator is case-INSENSITIVE, but it answers with
+ * `Buffer.toString("hex")` — always lowercase. Sending upper-case hex therefore
+ * returns a `spent` list that never matches what you sent, and every note reads
+ * as unspent. Normalizing here is what makes membership testing sound.
+ */
+function normalizeNullifier(nullifier, index) {
+    const normalized = nullifier.trim().toLowerCase();
+    if (!HEX64.test(normalized)) {
+        throw new Error(`nullifiers[${index}] must be a 64-character hex string, got ` +
+            `${JSON.stringify(nullifier)}`);
+    }
+    return normalized;
+}
+function chunk(items, size) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}
+/**
+ * Ask the relayer which of these nullifiers are spent.
+ *
+ * Deduplicates, lower-cases, and splits into MAX_NULLIFIERS_PER_CHECK batches
+ * that are issued concurrently. Returns a Set for membership testing; a
+ * nullifier absent from it is unspent as far as the relayer knows.
+ *
+ * @throws if any entry is not 64-char hex — a malformed nullifier that silently
+ *         read as "unspent" would overstate a balance.
+ */
+async function checkNullifiersSpent(nullifiers) {
+    const unique = [...new Set(nullifiers.map(normalizeNullifier))];
+    if (unique.length === 0)
+        return new Set();
+    const batches = await Promise.all(chunk(unique, exports.MAX_NULLIFIERS_PER_CHECK).map((batch) => (0, api_js_1.checkNullifiers)(batch)));
+    const spent = new Set();
+    for (const response of batches) {
+        for (const nullifier of response.spent ?? []) {
+            spent.add(nullifier.toLowerCase());
+        }
+    }
+    return spent;
+}
+/**
+ * Sum unspent notes, per mint and in total.
+ *
+ * ```ts
+ * const { total, byMint, unspent } = await getPrivateBalance(myNotes);
+ * ```
+ *
+ * Amounts are base units and stay bigint throughout — never sum note amounts as
+ * numbers. Notes are matched to spend status by nullifier, so every note needs
+ * one; the partitioned arrays hand back your own objects, not copies.
+ */
+async function getPrivateBalance(notes, options = {}) {
+    const normalized = notes.map((note, index) => ({
+        note,
+        amount: (0, amount_js_1.toBaseUnits)(note.amount, `notes[${index}].amount`),
+        nullifier: normalizeNullifier(note.nullifier, index),
+    }));
+    const resolve = options.resolveSpent ?? checkNullifiersSpent;
+    const spentSet = await resolve(normalized.map((entry) => entry.nullifier));
+    const balance = {
+        total: 0n,
+        byMint: {},
+        unspent: [],
+        spent: [],
+    };
+    for (const entry of normalized) {
+        if (spentSet.has(entry.nullifier)) {
+            balance.spent.push(entry.note);
+            continue;
+        }
+        const mint = entry.note.mint ?? exports.UNKNOWN_MINT;
+        balance.unspent.push(entry.note);
+        balance.total += entry.amount;
+        balance.byMint[mint] = (balance.byMint[mint] ?? 0n) + entry.amount;
+    }
+    return balance;
+}