@veilo/sdk-core 0.5.0 → 0.6.0

package/dist/cjs/index.d.ts

@@ -4,10 +4,15 @@ export * from "./config.js";
 export * from "./merkle.js";
 export * from "./proof.js";
 export * from "./events.js";
-export { createVeiloProgram, createReadonlyVeiloProgram, PRIVACY_POOL_IDL, PRIVACY_POOL_PROGRAM_ID, } from "./program.js";
+export * from "./identity/index.js";
+export * from "./positions/index.js";
+export * from "./perps/index.js";
+export * from "./predictions/index.js";
+export { createVeiloProgram, createReadonlyVeiloProgram, PRIVACY_POOL_CURRENT_IDL, PRIVACY_POOL_IDL, PRIVACY_POOL_IDLS, PRIVACY_POOL_LEGACY_IDL, PRIVACY_POOL_LEGACY2_IDL, PRIVACY_POOL_PROGRAM_ID, } from "./program.js";
+export type { PrivacyPoolIdlVersion } from "./idl/index.js";
 export * from "./shield/index.js";
-export { createTransactionProver, createSwapProver, verifyProof, } from "./prover.js";
-export type { CircuitArtifacts } from "./prover.js";
+export { createTransactionProver, createSwapProver, resolveCircuitArtifacts, verifyProof, } from "./prover.js";
+export type { CircuitArtifacts, CircuitName } from "./prover.js";
 export * from "./compactNote.js";
 export { randomBytes, randomBytes32 } from "./random.js";
 export * from "./relayer.js";

package/dist/cjs/index.js

@@ -14,7 +14,7 @@ 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.pubkeyToField = exports.poseidon4 = exports.poseidon3 = exports.poseidon2 = exports.poseidon1 = exports.frToBigInt = exports.bigIntToBytesBE = exports.bytesToBigIntBE = exports.BN254_FR_MODULUS = exports.getPoseidon = exports.initPoseidon = exports.DEFAULT_RPC_RETRY = exports.withRpcRetry = exports.randomBytes32 = exports.randomBytes = exports.verifyProof = exports.createSwapProver = exports.createTransactionProver = exports.PRIVACY_POOL_PROGRAM_ID = exports.PRIVACY_POOL_IDL = exports.createReadonlyVeiloProgram = exports.createVeiloProgram = void 0;
+exports.pubkeyToField = exports.poseidon4 = exports.poseidon3 = exports.poseidon2 = exports.poseidon1 = exports.frToBigInt = exports.bigIntToBytesBE = exports.bytesToBigIntBE = exports.BN254_FR_MODULUS = exports.getPoseidon = exports.initPoseidon = exports.DEFAULT_RPC_RETRY = exports.withRpcRetry = exports.randomBytes32 = exports.randomBytes = exports.verifyProof = exports.resolveCircuitArtifacts = exports.createSwapProver = exports.createTransactionProver = exports.PRIVACY_POOL_PROGRAM_ID = exports.PRIVACY_POOL_LEGACY2_IDL = exports.PRIVACY_POOL_LEGACY_IDL = exports.PRIVACY_POOL_IDLS = exports.PRIVACY_POOL_IDL = exports.PRIVACY_POOL_CURRENT_IDL = exports.createReadonlyVeiloProgram = exports.createVeiloProgram = void 0;
 // Core client functions
 __exportStar(require("./client.js"), exports);
 // UTXO types and functions (replaces note.ts)
@@ -27,11 +27,20 @@ __exportStar(require("./merkle.js"), exports);
 __exportStar(require("./proof.js"), exports);
 // On-chain event scanning and tree reconstruction
 __exportStar(require("./events.js"), exports);
+// Private product helpers: keys, PDAs, request types, and unsigned API clients.
+__exportStar(require("./identity/index.js"), exports);
+__exportStar(require("./positions/index.js"), exports);
+__exportStar(require("./perps/index.js"), exports);
+__exportStar(require("./predictions/index.js"), exports);
 // Program factory and IDL
 var program_js_1 = require("./program.js");
 Object.defineProperty(exports, "createVeiloProgram", { enumerable: true, get: function () { return program_js_1.createVeiloProgram; } });
 Object.defineProperty(exports, "createReadonlyVeiloProgram", { enumerable: true, get: function () { return program_js_1.createReadonlyVeiloProgram; } });
+Object.defineProperty(exports, "PRIVACY_POOL_CURRENT_IDL", { enumerable: true, get: function () { return program_js_1.PRIVACY_POOL_CURRENT_IDL; } });
 Object.defineProperty(exports, "PRIVACY_POOL_IDL", { enumerable: true, get: function () { return program_js_1.PRIVACY_POOL_IDL; } });
+Object.defineProperty(exports, "PRIVACY_POOL_IDLS", { enumerable: true, get: function () { return program_js_1.PRIVACY_POOL_IDLS; } });
+Object.defineProperty(exports, "PRIVACY_POOL_LEGACY_IDL", { enumerable: true, get: function () { return program_js_1.PRIVACY_POOL_LEGACY_IDL; } });
+Object.defineProperty(exports, "PRIVACY_POOL_LEGACY2_IDL", { enumerable: true, get: function () { return program_js_1.PRIVACY_POOL_LEGACY2_IDL; } });
 Object.defineProperty(exports, "PRIVACY_POOL_PROGRAM_ID", { enumerable: true, get: function () { return program_js_1.PRIVACY_POOL_PROGRAM_ID; } });
 // Wallet-agnostic shielding — build an unsigned deposit for any external wallet
 __exportStar(require("./shield/index.js"), exports);
@@ -39,6 +48,7 @@ __exportStar(require("./shield/index.js"), exports);
 var prover_js_1 = require("./prover.js");
 Object.defineProperty(exports, "createTransactionProver", { enumerable: true, get: function () { return prover_js_1.createTransactionProver; } });
 Object.defineProperty(exports, "createSwapProver", { enumerable: true, get: function () { return prover_js_1.createSwapProver; } });
+Object.defineProperty(exports, "resolveCircuitArtifacts", { enumerable: true, get: function () { return prover_js_1.resolveCircuitArtifacts; } });
 Object.defineProperty(exports, "verifyProof", { enumerable: true, get: function () { return prover_js_1.verifyProof; } });
 // Compact note ciphers — the on-chain payload that makes notes recoverable
 // from chain data alone, without any relayer involvement.
@@ -47,7 +57,7 @@ __exportStar(require("./compactNote.js"), exports);
 var random_js_1 = require("./random.js");
 Object.defineProperty(exports, "randomBytes", { enumerable: true, get: function () { return random_js_1.randomBytes; } });
 Object.defineProperty(exports, "randomBytes32", { enumerable: true, get: function () { return random_js_1.randomBytes32; } });
-// Relayer API client
+// Managed relayer API helpers (network configuration remains internal)
 __exportStar(require("./relayer.js"), exports);
 // Veilo Cloak Partner API client and helpers
 __exportStar(require("./cloak.js"), exports);

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

@@ -0,0 +1,2 @@
+/** Coerce a note amount to base units without ever going through Number. */
+export declare function toBaseUnits(amount: bigint | string | number, label: string): bigint;

package/dist/cjs/notes/amount.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toBaseUnits = toBaseUnits;
+/** Coerce a note amount to base units without ever going through Number. */
+function toBaseUnits(amount, label) {
+    if (typeof amount === "bigint")
+        return amount;
+    if (typeof amount === "number") {
+        if (!Number.isSafeInteger(amount)) {
+            throw new Error(`${label} ${amount} is not a safe integer; pass a bigint or a decimal ` +
+                "string for token amounts.");
+        }
+        return BigInt(amount);
+    }
+    try {
+        return BigInt(amount);
+    }
+    catch {
+        throw new Error(`${label} ${JSON.stringify(amount)} is not a valid amount.`);
+    }
+}

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

@@ -3,3 +3,6 @@ export * from "./nullifier.js";
 export * from "./encryption.js";
 export * from "./mailbox.js";
 export * from "./recovery.js";
+export * from "./spent.js";
+export * from "./selection.js";
+export * from "./amount.js";

package/dist/cjs/notes/index.js

@@ -19,3 +19,6 @@ __exportStar(require("./nullifier.js"), exports);
 __exportStar(require("./encryption.js"), exports);
 __exportStar(require("./mailbox.js"), exports);
 __exportStar(require("./recovery.js"), exports);
+__exportStar(require("./spent.js"), exports);
+__exportStar(require("./selection.js"), exports);
+__exportStar(require("./amount.js"), exports);

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

@@ -1,10 +1,20 @@
 import type { DecryptedNote } from "./mailbox.js";
 /**
- * Fetch all encrypted notes for a wallet from the relayer's Blind Mailbox endpoint
- * and decrypt them using the wallet's secret key.
+ * Fetch this account's encrypted notes from the relayer and decrypt them.
  *
- * @param walletPublicKey  Base58 wallet address used to query the relayer
- * @param walletSecretKey  Full 64-byte keypair.secretKey for decryption
- * @param relayerUrl       Relayer base URL (e.g. "https://relay.veilo.app")
+ * 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(walletPublicKey: string, walletSecretKey: Uint8Array, relayerUrl: string): Promise<DecryptedNote[]>;
+export declare function fetchAndDecryptNotes(params: {
+    authToken: string;
+    walletSecretKey: Uint8Array;
+    walletPublicKey?: string;
+    limit?: number;
+    offset?: number;
+}): Promise<DecryptedNote[]>;

package/dist/cjs/notes/recovery.js

@@ -1,31 +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 all encrypted notes for a wallet from the relayer's Blind Mailbox endpoint
- * and decrypt them using the wallet's secret key.
+ * Fetch this account's encrypted notes from the relayer and decrypt them.
  *
- * @param walletPublicKey  Base58 wallet address used to query the relayer
- * @param walletSecretKey  Full 64-byte keypair.secretKey for decryption
- * @param relayerUrl       Relayer base URL (e.g. "https://relay.veilo.app")
+ * 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(walletPublicKey, walletSecretKey, relayerUrl) {
-    const resp = await fetch(`${relayerUrl}/api/notes?recipientPublicKey=${walletPublicKey}`);
-    if (!resp.ok) {
-        throw new Error(`fetchAndDecryptNotes: ${resp.status} ${resp.statusText}`);
-    }
-    const { notes } = (await resp.json());
+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) {
+    for (const note of notes ?? []) {
+        if (!note.ephemeralPublicKey || !note.encryptedBlob)
+            continue;
         try {
-            const epk = Buffer.from(note.ephemeralPublicKey, "base64");
-            const decrypted = (0, mailbox_js_1.decryptBlindMailboxNote)(walletSecretKey, new Uint8Array(epk), note.encryptedBlob);
-            results.push(decrypted);
+            results.push((0, mailbox_js_1.decryptBlindMailboxNote)(walletSecretKey, base64ToBytes(note.ephemeralPublicKey), note.encryptedBlob));
         }
         catch {
-            // Note not for this key or corrupted — skip silently
+            // 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;
+}

package/dist/cjs/perps/constants.d.ts

@@ -0,0 +1,16 @@
+import type { JperpMarket, JperpMarketPayload, JperpSide } from "./types.js";
+export declare const JUPITER_PERPS_PROGRAM_ID = "PERPHjGBqRHArX4DySjwM6UJHiR3sWAatqfdBS2qQJu";
+export declare const JUPITER_PERPS_EVENT_AUTHORITY = "37hJBDnntwqhGbK7L6M1bLyvccj4u55CCUiLPdYkiqBN";
+export declare const JUPITER_PERPS_POOL = "5BUwFW4nRbftYTDMbgxykoFWqWHPzahFSNAaaaJtVKsq";
+export declare const JUPITER_JLP_MINT = "27G8MtK7VtTcCHkpASjSDdkWWYfoqT6ggEuKidVJidD4";
+export declare const JPERP_USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+export declare const JPERP_NATIVE_SOL_MINT = "11111111111111111111111111111111";
+export declare const JPERP_WRAPPED_SOL_MINT = "So11111111111111111111111111111111111111112";
+export declare const JUPITER_PERPS_CUSTODIES: Record<JperpMarket | "USDC" | "USDT", string>;
+export declare const JUPITER_PERPS_DOVES_ORACLES: Record<JperpMarket, string>;
+export declare const JPERP_LONG_POOL_MINTS: Record<JperpMarket, string>;
+export declare const JPERP_LONG_JUPITER_MINTS: Record<JperpMarket, string>;
+export declare const JPERP_LONG_DECIMALS: Record<JperpMarket, number>;
+export declare const JPERP_USD_DECIMALS = 6;
+/** Resolve the exact market payload duplicated by the wallet-app reference. */
+export declare function getJperpMarketPayload(market: JperpMarket, side: JperpSide): JperpMarketPayload;