@veilo/sdk-core 0.5.0 → 0.7.0

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

@@ -10,18 +10,23 @@ export * from "./merkle.js";
 export * from "./proof.js";
 // On-chain event scanning and tree reconstruction
 export * from "./events.js";
+// Private product helpers: keys, PDAs, request types, and unsigned API clients.
+export * from "./identity/index.js";
+export * from "./positions/index.js";
+export * from "./perps/index.js";
+export * from "./predictions/index.js";
 // Program factory and IDL
-export { createVeiloProgram, createReadonlyVeiloProgram, PRIVACY_POOL_IDL, PRIVACY_POOL_PROGRAM_ID, } from "./program.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";
 // Wallet-agnostic shielding — build an unsigned deposit for any external wallet
 export * from "./shield/index.js";
 // Proof generation (requires snarkjs peer dependency)
-export { createTransactionProver, createSwapProver, verifyProof, } from "./prover.js";
+export { createTransactionProver, createSwapProver, resolveCircuitArtifacts, verifyProof, } from "./prover.js";
 // Compact note ciphers — the on-chain payload that makes notes recoverable
 // from chain data alone, without any relayer involvement.
 export * from "./compactNote.js";
 // Cross-platform CSPRNG (no node:crypto import — safe in browser bundles)
 export { randomBytes, randomBytes32 } from "./random.js";
-// Relayer API client
+// Managed relayer API helpers (network configuration remains internal)
 export * from "./relayer.js";
 // Veilo Cloak Partner API client and helpers
 export * from "./cloak.js";

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

@@ -0,0 +1,18 @@
+/** Coerce a note amount to base units without ever going through Number. */
+export 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/esm/notes/index.d.ts

@@ -3,3 +3,7 @@ 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 "./scan.js";
+export * from "./amount.js";

package/dist/esm/notes/index.js

@@ -3,3 +3,7 @@ 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 "./scan.js";
+export * from "./amount.js";

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

@@ -1,28 +1,45 @@
+import { queryEncryptedNotes } from "../relayer/api.js";
 import { decryptBlindMailboxNote } 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 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());
+export async function fetchAndDecryptNotes(params) {
+    const { authToken, walletSecretKey, walletPublicKey, limit, offset } = params;
+    const { notes } = await 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 = decryptBlindMailboxNote(walletSecretKey, new Uint8Array(epk), note.encryptedBlob);
-            results.push(decrypted);
+            results.push(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/esm/notes/scan.d.ts

@@ -0,0 +1,74 @@
+import type { CompactScanNote, RelayerEncryptedNote } from "../relayer/types.js";
+/**
+ * Finding your own notes in the public feed.
+ *
+ * The compact feed is deliberately anonymous: every row is ciphertext plus a
+ * one-byte view tag, and nothing on it says who a note belongs to. You find
+ * yours by trial decryption. The view tag exists to make that cheap — it
+ * rejects ~255/256 of other people's rows with one hash instead of a full
+ * decrypt.
+ */
+/** Server-side page cap (notes.constants COMPACT_SCAN_MAX_LIMIT). */
+export declare const COMPACT_SCAN_MAX_LIMIT = 1000;
+/** Server-side cap per fetch-by-commitment request. */
+export declare const MAX_COMMITMENTS_PER_FETCH = 50;
+/** A feed row that decrypted under your key. */
+export interface ScannedNote {
+    /** Value in base units. */
+    amount: bigint;
+    /** 32-byte blinding factor recovered from the cipher. */
+    blinding: Uint8Array;
+    /** Commitment hex, as stored. */
+    commitment: string;
+    leafIndex?: number | null;
+    treeId?: number | null;
+    mint?: string | null;
+    timestamp?: number;
+    txSignature?: string;
+    /** The raw feed row this came from. */
+    source: CompactScanNote;
+}
+export interface ScanCompactNotesOptions {
+    /** Rows per request. Capped at COMPACT_SCAN_MAX_LIMIT. */
+    pageSize?: number;
+    /** Resume from a previous run's `nextCursor`. */
+    cursor?: string;
+    /** Stop after this many pages. Unlimited by default. */
+    maxPages?: number;
+    /** Called after each page, for progress reporting. Return false to stop. */
+    onPage?: (progress: {
+        scanned: number;
+        matched: number;
+        cursor: string | null;
+    }) => boolean | void;
+}
+export interface ScanCompactNotesResult {
+    /** Rows that decrypted under your key. */
+    notes: ScannedNote[];
+    /** Feed rows examined. */
+    scanned: number;
+    /**
+     * Cursor to resume from. Null means the feed was exhausted; a string means
+     * scanning stopped early (maxPages, or onPage returning false).
+     */
+    nextCursor: string | null;
+}
+/**
+ * Walk the compact feed and return the notes that belong to this key.
+ *
+ * Paginates to exhaustion by default. The X25519 private key is derived once
+ * and reused across every row rather than per row — that derivation dominates
+ * the cost otherwise.
+ *
+ * @param walletSecretKey full 64-byte keypair.secretKey
+ */
+export declare function scanCompactNotes(walletSecretKey: Uint8Array, options?: ScanCompactNotesOptions): Promise<ScanCompactNotesResult>;
+/**
+ * Look up stored notes by commitment, chunked to the server's limit.
+ *
+ * Requests are issued concurrently. Commitments the relayer does not know are
+ * simply absent from the result — the array is not positional.
+ */
+export declare function fetchNotesByCommitment(commitments: string[], options?: {
+    walletPublicKey?: string;
+}): Promise<RelayerEncryptedNote[]>;

package/dist/esm/notes/scan.js

@@ -0,0 +1,105 @@
+import { compactScan, fetchNotesByCommitmentPage, } from "../relayer/api.js";
+import { decryptCompactNoteCipher, matchesViewTag, toX25519Private, } from "../compactNote.js";
+/**
+ * Finding your own notes in the public feed.
+ *
+ * The compact feed is deliberately anonymous: every row is ciphertext plus a
+ * one-byte view tag, and nothing on it says who a note belongs to. You find
+ * yours by trial decryption. The view tag exists to make that cheap — it
+ * rejects ~255/256 of other people's rows with one hash instead of a full
+ * decrypt.
+ */
+/** Server-side page cap (notes.constants COMPACT_SCAN_MAX_LIMIT). */
+export const COMPACT_SCAN_MAX_LIMIT = 1000;
+/** Server-side cap per fetch-by-commitment request. */
+export const MAX_COMMITMENTS_PER_FETCH = 50;
+function decodeBase64(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"));
+}
+/**
+ * Walk the compact feed and return the notes that belong to this key.
+ *
+ * Paginates to exhaustion by default. The X25519 private key is derived once
+ * and reused across every row rather than per row — that derivation dominates
+ * the cost otherwise.
+ *
+ * @param walletSecretKey full 64-byte keypair.secretKey
+ */
+export async function scanCompactNotes(walletSecretKey, options = {}) {
+    const pageSize = Math.min(options.pageSize ?? 500, COMPACT_SCAN_MAX_LIMIT);
+    const x25519Private = toX25519Private(walletSecretKey);
+    const notes = [];
+    let cursor = options.cursor;
+    let scanned = 0;
+    let pages = 0;
+    for (;;) {
+        const page = await compactScan({ limit: pageSize, cursor });
+        pages++;
+        for (const row of page.notes ?? []) {
+            if (!row.compactEphemeralKey || !row.compactBlob)
+                continue;
+            scanned++;
+            const ephemeralPublicKey = decodeBase64(row.compactEphemeralKey);
+            // View tag first: one hash rejects almost every row that is not ours.
+            const { matches, sharedSecret } = matchesViewTag(walletSecretKey, ephemeralPublicKey, row.viewTag ?? -1, { x25519Private });
+            if (!matches)
+                continue;
+            const opened = decryptCompactNoteCipher(walletSecretKey, ephemeralPublicKey, decodeBase64(row.compactBlob), { sharedSecret, x25519Private });
+            if (!opened)
+                continue; // view-tag collision, ~1 in 256
+            notes.push({
+                amount: opened.amount,
+                blinding: opened.blinding,
+                commitment: row.commitment,
+                leafIndex: row.leafIndex,
+                treeId: row.treeId,
+                mint: row.mintAddress,
+                timestamp: row.timestamp,
+                txSignature: row.txSignature,
+                source: row,
+            });
+        }
+        cursor = page.nextCursor ?? undefined;
+        const keepGoing = options.onPage?.({
+            scanned,
+            matched: notes.length,
+            cursor: page.nextCursor,
+        });
+        if (keepGoing === false)
+            break;
+        if (!page.hasMore || !cursor)
+            return { notes, scanned, nextCursor: null };
+        if (options.maxPages && pages >= options.maxPages)
+            break;
+    }
+    return { notes, scanned, nextCursor: cursor ?? null };
+}
+/**
+ * Look up stored notes by commitment, chunked to the server's limit.
+ *
+ * Requests are issued concurrently. Commitments the relayer does not know are
+ * simply absent from the result — the array is not positional.
+ */
+export async function fetchNotesByCommitment(commitments, options = {}) {
+    const unique = [...new Set(commitments.map((c) => c.trim().toLowerCase()))];
+    if (unique.length === 0)
+        return [];
+    const chunks = [];
+    for (let i = 0; i < unique.length; i += MAX_COMMITMENTS_PER_FETCH) {
+        chunks.push(unique.slice(i, i + MAX_COMMITMENTS_PER_FETCH));
+    }
+    const pages = await Promise.all(chunks.map((chunk) => fetchNotesByCommitmentPage({
+        commitments: chunk,
+        ...(options.walletPublicKey
+            ? { walletPublicKey: options.walletPublicKey }
+            : {}),
+    })));
+    return pages.flatMap((page) => page.notes ?? []);
+}

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

@@ -0,0 +1,133 @@
+/**
+ * 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>;
+/**
+ * One input to a merge step: an existing note, or the output of an earlier step.
+ *
+ * Steps chain, so a plan for five notes refers to notes that do not exist yet.
+ * Modelling that explicitly beats returning amounts and leaving the caller to
+ * work out which is which.
+ */
+export type MergeInput<T> = {
+    kind: "note";
+    note: T;
+    amount: bigint;
+} | {
+    kind: "step";
+    step: number;
+    amount: bigint;
+};
+export interface MergeStep<T> {
+    /** 1-based, and the number `{ kind: "step" }` inputs refer to. */
+    step: number;
+    inputs: [MergeInput<T>, MergeInput<T>];
+    /** Value of the single note this step produces. */
+    outputAmount: bigint;
+}
+export interface NoteConsolidationPlan<T> {
+    ok: true;
+    treeId: number;
+    /**
+     * Merges to run in order, each a 2-in-1-out self-transfer. Empty when the
+     * amount is already spendable within MAX_INPUT_NOTES.
+     */
+    steps: MergeStep<T>[];
+    /** Notes the plan consumes, in the order it consumes them. */
+    notes: T[];
+    /** Sum of those notes. */
+    total: bigint;
+    /** total - amount, the change left after the final spend. */
+    change: bigint;
+}
+/**
+ * Plan how to make `amount` spendable when no one or two notes cover it.
+ *
+ * `selectNotesForAmount` reports `requiresMerge` but cannot act on it: the
+ * circuit takes two inputs, so spending five notes means merging them down
+ * first. Each step here is one 2-in-1-out transfer to yourself, and k notes
+ * need k-2 of them before a final two-input spend.
+ *
+ * Merges the two SMALLEST notes each round. That retires dust first and leaves
+ * the large notes untouched, so the plan is short and the final spend has the
+ * least change.
+ *
+ * The plan is pure — it performs nothing. Execute the steps with
+ * `privateTransfer`, feeding each step's output note into the next.
+ */
+export declare function planNoteConsolidation<T extends SelectableNote>(notes: T[], amount: bigint | string | number, options?: {
+    mint?: string | null;
+}): NoteConsolidationPlan<T> | NoteSelectionFailure;