@veilo/sdk-core 0.6.0 → 0.7.0

package/README.md

@@ -283,6 +283,52 @@ configuration flag — see [Support](#support). Reaching past the package's
 `exports` map to import internal modules is unsupported and not covered by
 semver.
 
+### Finding your notes on the public feed
+
+Every row in the compact feed is ciphertext plus a one-byte view tag; nothing on
+it says who a note belongs to. You find yours by trial decryption, and the view
+tag makes that cheap — it rejects roughly 255 of every 256 foreign rows with a
+single hash instead of a full decrypt.
+
+```ts
+import { scanCompactNotes, fetchNotesByCommitment } from "@veilo/sdk-core";
+
+const { notes, scanned, nextCursor } = await scanCompactNotes(walletSecretKey, {
+  onPage: ({ matched }) => console.log(`${matched} found so far`),
+});
+```
+
+It paginates to exhaustion by default and derives the X25519 key once for the
+whole scan. Stop early with `maxPages` or by returning `false` from `onPage`;
+`nextCursor` is then non-null and can be passed back later to resume. The feed
+carries only unspent, unclaimed notes, and it needs no auth token — scanning
+reveals nothing without your key.
+
+`fetchNotesByCommitment(commitments)` looks up known commitments instead,
+chunked at the server's 50-per-request cap and issued concurrently. Commitments
+the relayer does not know are simply absent from the result.
+
+### Consolidating notes before a large spend
+
+When no one or two notes cover an amount, `selectNotesForAmount` reports
+`requiresMerge`. `planNoteConsolidation` says what to do about it:
+
+```ts
+const plan = planNoteConsolidation(unspentNotes, amountRaw, { mint });
+if (plan.ok) {
+  for (const { inputs, outputAmount } of plan.steps) {
+    // one 2-in-1-out privateTransfer to yourself per step
+  }
+}
+```
+
+Each step is a self-transfer combining two inputs into one, so k notes need k-2
+steps before a final two-input spend. Steps chain — a later step can consume an
+earlier step's output, and inputs are tagged `{ kind: "note" }` or
+`{ kind: "step", step }` so you always know which. The two smallest are merged
+each round, which retires dust first and leaves large notes intact. The plan is
+pure: it computes, it does not execute.
+
 ### Spend status and private balance
 
 Nothing in a note says whether it has been spent — a note is yours until its

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

@@ -5,4 +5,5 @@ 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/cjs/notes/index.js

@@ -21,4 +21,5 @@ __exportStar(require("./mailbox.js"), exports);
 __exportStar(require("./recovery.js"), exports);
 __exportStar(require("./spent.js"), exports);
 __exportStar(require("./selection.js"), exports);
+__exportStar(require("./scan.js"), exports);
 __exportStar(require("./amount.js"), exports);

package/dist/cjs/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/cjs/notes/scan.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_COMMITMENTS_PER_FETCH = exports.COMPACT_SCAN_MAX_LIMIT = void 0;
+exports.scanCompactNotes = scanCompactNotes;
+exports.fetchNotesByCommitment = fetchNotesByCommitment;
+const api_js_1 = require("../relayer/api.js");
+const compactNote_js_1 = require("../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). */
+exports.COMPACT_SCAN_MAX_LIMIT = 1000;
+/** Server-side cap per fetch-by-commitment request. */
+exports.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
+ */
+async function scanCompactNotes(walletSecretKey, options = {}) {
+    const pageSize = Math.min(options.pageSize ?? 500, exports.COMPACT_SCAN_MAX_LIMIT);
+    const x25519Private = (0, compactNote_js_1.toX25519Private)(walletSecretKey);
+    const notes = [];
+    let cursor = options.cursor;
+    let scanned = 0;
+    let pages = 0;
+    for (;;) {
+        const page = await (0, api_js_1.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 } = (0, compactNote_js_1.matchesViewTag)(walletSecretKey, ephemeralPublicKey, row.viewTag ?? -1, { x25519Private });
+            if (!matches)
+                continue;
+            const opened = (0, compactNote_js_1.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.
+ */
+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 += exports.MAX_COMMITMENTS_PER_FETCH) {
+        chunks.push(unique.slice(i, i + exports.MAX_COMMITMENTS_PER_FETCH));
+    }
+    const pages = await Promise.all(chunks.map((chunk) => (0, api_js_1.fetchNotesByCommitmentPage)({
+        commitments: chunk,
+        ...(options.walletPublicKey
+            ? { walletPublicKey: options.walletPublicKey }
+            : {}),
+    })));
+    return pages.flatMap((page) => page.notes ?? []);
+}

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

@@ -75,3 +75,59 @@ export type NoteSelectionResult<T> = NoteSelection<T> | NoteSelectionFailure;
 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;

package/dist/cjs/notes/selection.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_INPUT_NOTES = void 0;
 exports.canonicalTreeId = canonicalTreeId;
 exports.selectNotesForAmount = selectNotesForAmount;
+exports.planNoteConsolidation = planNoteConsolidation;
 const web3_js_1 = require("@solana/web3.js");
 const amount_js_1 = require("./amount.js");
 /**
@@ -191,3 +192,69 @@ function selectWithinTree(bucket, target, treeId) {
         requiresMerge: chosen.length > exports.MAX_INPUT_NOTES,
     };
 }
+/**
+ * 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.
+ */
+function planNoteConsolidation(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 selection = selectNotesForAmount(notes, target, options);
+    if (!selection.ok)
+        return selection;
+    // Already spendable in one transaction.
+    if (!selection.requiresMerge) {
+        return {
+            ok: true,
+            treeId: selection.treeId,
+            steps: [],
+            notes: selection.notes,
+            total: selection.total,
+            change: selection.change,
+        };
+    }
+    // Ascending, so the two cheapest merge first.
+    const pool = selection.notes
+        .map((note, index) => ({
+        kind: "note",
+        note,
+        amount: (0, amount_js_1.toBaseUnits)(note.amount, `notes[${index}].amount`),
+    }))
+        .sort((a, b) => (a.amount > b.amount ? 1 : a.amount < b.amount ? -1 : 0));
+    const steps = [];
+    while (pool.length > exports.MAX_INPUT_NOTES) {
+        const first = pool.shift();
+        const second = pool.shift();
+        const outputAmount = first.amount + second.amount;
+        const step = steps.length + 1;
+        steps.push({ step, inputs: [first, second], outputAmount });
+        const produced = { kind: "step", step, amount: outputAmount };
+        // Keep the pool ordered so the next round still merges the two smallest.
+        const at = pool.findIndex((entry) => entry.amount > outputAmount);
+        if (at === -1)
+            pool.push(produced);
+        else
+            pool.splice(at, 0, produced);
+    }
+    return {
+        ok: true,
+        treeId: selection.treeId,
+        steps,
+        notes: selection.notes,
+        total: selection.total,
+        change: selection.change,
+    };
+}

package/dist/cjs/relayer/api.d.ts

@@ -1,4 +1,4 @@
-import type { CheckNullifiersResponse, ChallengeResponse, CheckUsernameResponse, DeleteUserDataResponse, MerkleRootResponse, MerkleTreeResponse, PreRegisterKeyResponse, PrivateSwapRequest, PrivateSwapResponse, PrivateTransferRequest, PrivateTransferResponse, QueryNotesRequest, QueryNotesResponse, RegisterRequest, RegisterResponse, RestoreRequest, RestoreResponse, SaveEncryptedNoteRequest, SaveEncryptedNoteResponse, VeiloPublicKeyResponse, WithdrawRequest, WithdrawResponse } from "./types.js";
+import type { CheckNullifiersResponse, CompactScanResponse, FetchByCommitmentRequest, FetchByCommitmentResponse, ChallengeResponse, CheckUsernameResponse, DeleteUserDataResponse, MerkleRootResponse, MerkleTreeResponse, PreRegisterKeyResponse, PrivateSwapRequest, PrivateSwapResponse, PrivateTransferRequest, PrivateTransferResponse, QueryNotesRequest, QueryNotesResponse, RegisterRequest, RegisterResponse, RestoreRequest, RestoreResponse, SaveEncryptedNoteRequest, SaveEncryptedNoteResponse, VeiloPublicKeyResponse, WithdrawRequest, WithdrawResponse } from "./types.js";
 /** Request a wallet-authentication challenge from Veilo. */
 export declare function getChallenge(walletPublicKey: string): Promise<ChallengeResponse>;
 /** Register a Veilo account and receive its auth token. */
@@ -19,6 +19,16 @@ export declare function saveEncryptedNote(data: SaveEncryptedNoteRequest): Promi
 export declare function queryEncryptedNotes(authToken: string, params?: QueryNotesRequest): Promise<QueryNotesResponse>;
 /** Delete the authenticated user's stored data without retaining their token. */
 export declare function deleteUserData(authToken: string): Promise<DeleteUserDataResponse>;
+/** One page of the public compact-note feed. Prefer `scanCompactNotes`. */
+export declare function compactScan(params?: {
+    limit?: number;
+    cursor?: string;
+}): Promise<CompactScanResponse>;
+/**
+ * One fetch-by-commitment request, capped at 50 commitments by the server.
+ * Prefer `fetchNotesByCommitment` from the notes module, which chunks for you.
+ */
+export declare function fetchNotesByCommitmentPage(data: FetchByCommitmentRequest): Promise<FetchByCommitmentResponse>;
 /** Raw check-batch call. Prefer `checkNullifiersSpent`, which chunks for you. */
 export declare function checkNullifiers(nullifiers: string[]): Promise<CheckNullifiersResponse>;
 export declare function getMerkleRoot(mintAddress?: string, treeId?: number): Promise<MerkleRootResponse>;

package/dist/cjs/relayer/api.js

@@ -10,6 +10,8 @@ exports.preRegisterKey = preRegisterKey;
 exports.saveEncryptedNote = saveEncryptedNote;
 exports.queryEncryptedNotes = queryEncryptedNotes;
 exports.deleteUserData = deleteUserData;
+exports.compactScan = compactScan;
+exports.fetchNotesByCommitmentPage = fetchNotesByCommitmentPage;
 exports.checkNullifiers = checkNullifiers;
 exports.getMerkleRoot = getMerkleRoot;
 exports.getMerkleTree = getMerkleTree;
@@ -49,6 +51,17 @@ function queryEncryptedNotes(authToken, params = {}) {
 function deleteUserData(authToken) {
     return (0, internal_js_1.createInternalRelayerClient)({ authToken }).deleteUserData();
 }
+/** One page of the public compact-note feed. Prefer `scanCompactNotes`. */
+function compactScan(params = {}) {
+    return (0, internal_js_1.getInternalRelayerClient)().compactScan(params);
+}
+/**
+ * One fetch-by-commitment request, capped at 50 commitments by the server.
+ * Prefer `fetchNotesByCommitment` from the notes module, which chunks for you.
+ */
+function fetchNotesByCommitmentPage(data) {
+    return (0, internal_js_1.getInternalRelayerClient)().fetchNotesByCommitment(data);
+}
 /** Raw check-batch call. Prefer `checkNullifiersSpent`, which chunks for you. */
 function checkNullifiers(nullifiers) {
     return (0, internal_js_1.getInternalRelayerClient)().checkNullifiers(nullifiers);

package/dist/cjs/relayer/client.d.ts

@@ -1,4 +1,4 @@
-import type { CheckNullifiersResponse, ChallengeResponse, CheckUsernameResponse, DeleteUserDataResponse, MerkleRootResponse, MerkleTreeResponse, PreRegisterKeyResponse, PrivateSwapRequest, PrivateSwapResponse, PrivateTransferRequest, PrivateTransferResponse, QueryNotesRequest, QueryNotesResponse, RegisterRequest, RegisterResponse, RestoreRequest, RestoreResponse, RetryPolicy, SaveEncryptedNoteRequest, SaveEncryptedNoteResponse, VeiloPublicKeyResponse, WithdrawRequest, WithdrawResponse } from "./types.js";
+import type { CheckNullifiersResponse, CompactScanResponse, FetchByCommitmentRequest, FetchByCommitmentResponse, ChallengeResponse, CheckUsernameResponse, DeleteUserDataResponse, MerkleRootResponse, MerkleTreeResponse, PreRegisterKeyResponse, PrivateSwapRequest, PrivateSwapResponse, PrivateTransferRequest, PrivateTransferResponse, QueryNotesRequest, QueryNotesResponse, RegisterRequest, RegisterResponse, RestoreRequest, RestoreResponse, RetryPolicy, SaveEncryptedNoteRequest, SaveEncryptedNoteResponse, VeiloPublicKeyResponse, WithdrawRequest, WithdrawResponse } from "./types.js";
 import { type InternalRelayerClientOptions } from "./internal-config.js";
 import type { ClosePositionRequest, ClosePositionResponse, MergePositionsRequest, MergePositionsResponse, OpenPositionRequest, OpenPositionResponse } from "../positions/types.js";
 import type { JperpCancelTriggerRequest, JperpCancelTriggerResponse, JperpCloseRequest, JperpDecreaseResponse, JperpOpenRequest, JperpOpenResponse, JperpRecoverNativeRequest, JperpRecoverNativeResponse, JperpRecoverSeedRequest, JperpRecoverSeedResponse, JperpReissueRequest, JperpReissueResponse, JperpSetTpslRequest, JperpUpdateTpslRequest } from "../perps/types.js";
@@ -37,6 +37,19 @@ export declare class VeiloRelayerClient {
     /** Query encrypted notes for the authenticated user. Requires auth token. */
     queryEncryptedNotes(params?: QueryNotesRequest): Promise<QueryNotesResponse>;
     /** Delete all stored data for the authenticated user. Requires auth token. */
+    /**
+     * One page of the public compact-note feed.
+     *
+     * Unauthenticated by design: rows carry only ciphertext and a one-byte view
+     * tag, so scanning reveals nothing without the recipient's key. The feed
+     * excludes spent notes and any note already claimed by a wallet.
+     */
+    compactScan(params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<CompactScanResponse>;
+    /** Look up stored notes by commitment. Max 50 per request. */
+    fetchNotesByCommitment(data: FetchByCommitmentRequest): Promise<FetchByCommitmentResponse>;
     /**
      * Ask which of these nullifiers the relayer has seen spent.
      *

package/dist/cjs/relayer/client.js

@@ -81,6 +81,28 @@ class VeiloRelayerClient {
         });
     }
     /** Delete all stored data for the authenticated user. Requires auth token. */
+    /**
+     * One page of the public compact-note feed.
+     *
+     * Unauthenticated by design: rows carry only ciphertext and a one-byte view
+     * tag, so scanning reveals nothing without the recipient's key. The feed
+     * excludes spent notes and any note already claimed by a wallet.
+     */
+    async compactScan(params = {}) {
+        const query = new URLSearchParams();
+        if (params.limit !== undefined)
+            query.set("limit", String(params.limit));
+        if (params.cursor)
+            query.set("cursor", params.cursor);
+        const qs = query.toString();
+        return this.transport.request("GET", `/notes/compact-scan${qs ? `?${qs}` : ""}`);
+    }
+    /** Look up stored notes by commitment. Max 50 per request. */
+    async fetchNotesByCommitment(data) {
+        return this.transport.request("POST", "/notes/fetch-by-commitment", {
+            body: data,
+        });
+    }
     /**
      * Ask which of these nullifiers the relayer has seen spent.
      *

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

@@ -39,6 +39,37 @@ export interface QueryNotesResponse {
     limit: number;
     offset: number;
 }
+/** One row from the public compact-note scan feed. */
+export interface CompactScanNote {
+    _id: string;
+    commitment: string;
+    compactEphemeralKey: string | null;
+    compactBlob: string | null;
+    viewTag: number | null;
+    leafIndex?: number | null;
+    treeId?: number | null;
+    mintAddress?: string | null;
+    timestamp?: number;
+    txSignature?: string;
+    spent?: boolean;
+    spentTx?: string;
+}
+export interface CompactScanResponse {
+    success: boolean;
+    notes: CompactScanNote[];
+    /** Opaque cursor for the next page; null when the feed is exhausted. */
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+/** Commitments to look up. Max 50 per request, 64-char hex. */
+export interface FetchByCommitmentRequest {
+    commitments: string[];
+    walletPublicKey?: string;
+}
+export interface FetchByCommitmentResponse {
+    success: boolean;
+    notes: RelayerEncryptedNote[];
+}
 /** Nullifiers to test for spend status. Max 200 per request, 64-char hex. */
 export interface CheckNullifiersRequest {
     nullifiers: string[];

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

@@ -5,4 +5,5 @@ 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

@@ -5,4 +5,5 @@ 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/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

@@ -75,3 +75,59 @@ export type NoteSelectionResult<T> = NoteSelection<T> | NoteSelectionFailure;
 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;

package/dist/esm/notes/selection.js

@@ -186,3 +186,69 @@ function selectWithinTree(bucket, target, treeId) {
         requiresMerge: chosen.length > MAX_INPUT_NOTES,
     };
 }
+/**
+ * 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 function planNoteConsolidation(notes, amount, options = {}) {
+    const target = toBaseUnits(amount, "amount");
+    if (target <= 0n) {
+        throw new Error(`amount must be positive, got ${target}`);
+    }
+    const selection = selectNotesForAmount(notes, target, options);
+    if (!selection.ok)
+        return selection;
+    // Already spendable in one transaction.
+    if (!selection.requiresMerge) {
+        return {
+            ok: true,
+            treeId: selection.treeId,
+            steps: [],
+            notes: selection.notes,
+            total: selection.total,
+            change: selection.change,
+        };
+    }
+    // Ascending, so the two cheapest merge first.
+    const pool = selection.notes
+        .map((note, index) => ({
+        kind: "note",
+        note,
+        amount: toBaseUnits(note.amount, `notes[${index}].amount`),
+    }))
+        .sort((a, b) => (a.amount > b.amount ? 1 : a.amount < b.amount ? -1 : 0));
+    const steps = [];
+    while (pool.length > MAX_INPUT_NOTES) {
+        const first = pool.shift();
+        const second = pool.shift();
+        const outputAmount = first.amount + second.amount;
+        const step = steps.length + 1;
+        steps.push({ step, inputs: [first, second], outputAmount });
+        const produced = { kind: "step", step, amount: outputAmount };
+        // Keep the pool ordered so the next round still merges the two smallest.
+        const at = pool.findIndex((entry) => entry.amount > outputAmount);
+        if (at === -1)
+            pool.push(produced);
+        else
+            pool.splice(at, 0, produced);
+    }
+    return {
+        ok: true,
+        treeId: selection.treeId,
+        steps,
+        notes: selection.notes,
+        total: selection.total,
+        change: selection.change,
+    };
+}

package/dist/esm/relayer/api.d.ts

@@ -1,4 +1,4 @@
-import type { CheckNullifiersResponse, ChallengeResponse, CheckUsernameResponse, DeleteUserDataResponse, MerkleRootResponse, MerkleTreeResponse, PreRegisterKeyResponse, PrivateSwapRequest, PrivateSwapResponse, PrivateTransferRequest, PrivateTransferResponse, QueryNotesRequest, QueryNotesResponse, RegisterRequest, RegisterResponse, RestoreRequest, RestoreResponse, SaveEncryptedNoteRequest, SaveEncryptedNoteResponse, VeiloPublicKeyResponse, WithdrawRequest, WithdrawResponse } from "./types.js";
+import type { CheckNullifiersResponse, CompactScanResponse, FetchByCommitmentRequest, FetchByCommitmentResponse, ChallengeResponse, CheckUsernameResponse, DeleteUserDataResponse, MerkleRootResponse, MerkleTreeResponse, PreRegisterKeyResponse, PrivateSwapRequest, PrivateSwapResponse, PrivateTransferRequest, PrivateTransferResponse, QueryNotesRequest, QueryNotesResponse, RegisterRequest, RegisterResponse, RestoreRequest, RestoreResponse, SaveEncryptedNoteRequest, SaveEncryptedNoteResponse, VeiloPublicKeyResponse, WithdrawRequest, WithdrawResponse } from "./types.js";
 /** Request a wallet-authentication challenge from Veilo. */
 export declare function getChallenge(walletPublicKey: string): Promise<ChallengeResponse>;
 /** Register a Veilo account and receive its auth token. */
@@ -19,6 +19,16 @@ export declare function saveEncryptedNote(data: SaveEncryptedNoteRequest): Promi
 export declare function queryEncryptedNotes(authToken: string, params?: QueryNotesRequest): Promise<QueryNotesResponse>;
 /** Delete the authenticated user's stored data without retaining their token. */
 export declare function deleteUserData(authToken: string): Promise<DeleteUserDataResponse>;
+/** One page of the public compact-note feed. Prefer `scanCompactNotes`. */
+export declare function compactScan(params?: {
+    limit?: number;
+    cursor?: string;
+}): Promise<CompactScanResponse>;
+/**
+ * One fetch-by-commitment request, capped at 50 commitments by the server.
+ * Prefer `fetchNotesByCommitment` from the notes module, which chunks for you.
+ */
+export declare function fetchNotesByCommitmentPage(data: FetchByCommitmentRequest): Promise<FetchByCommitmentResponse>;
 /** Raw check-batch call. Prefer `checkNullifiersSpent`, which chunks for you. */
 export declare function checkNullifiers(nullifiers: string[]): Promise<CheckNullifiersResponse>;
 export declare function getMerkleRoot(mintAddress?: string, treeId?: number): Promise<MerkleRootResponse>;

package/dist/esm/relayer/api.js

@@ -31,6 +31,17 @@ export function queryEncryptedNotes(authToken, params = {}) {
 export function deleteUserData(authToken) {
     return createInternalRelayerClient({ authToken }).deleteUserData();
 }
+/** One page of the public compact-note feed. Prefer `scanCompactNotes`. */
+export function compactScan(params = {}) {
+    return getInternalRelayerClient().compactScan(params);
+}
+/**
+ * One fetch-by-commitment request, capped at 50 commitments by the server.
+ * Prefer `fetchNotesByCommitment` from the notes module, which chunks for you.
+ */
+export function fetchNotesByCommitmentPage(data) {
+    return getInternalRelayerClient().fetchNotesByCommitment(data);
+}
 /** Raw check-batch call. Prefer `checkNullifiersSpent`, which chunks for you. */
 export function checkNullifiers(nullifiers) {
     return getInternalRelayerClient().checkNullifiers(nullifiers);

package/dist/esm/relayer/client.d.ts

@@ -1,4 +1,4 @@
-import type { CheckNullifiersResponse, ChallengeResponse, CheckUsernameResponse, DeleteUserDataResponse, MerkleRootResponse, MerkleTreeResponse, PreRegisterKeyResponse, PrivateSwapRequest, PrivateSwapResponse, PrivateTransferRequest, PrivateTransferResponse, QueryNotesRequest, QueryNotesResponse, RegisterRequest, RegisterResponse, RestoreRequest, RestoreResponse, RetryPolicy, SaveEncryptedNoteRequest, SaveEncryptedNoteResponse, VeiloPublicKeyResponse, WithdrawRequest, WithdrawResponse } from "./types.js";
+import type { CheckNullifiersResponse, CompactScanResponse, FetchByCommitmentRequest, FetchByCommitmentResponse, ChallengeResponse, CheckUsernameResponse, DeleteUserDataResponse, MerkleRootResponse, MerkleTreeResponse, PreRegisterKeyResponse, PrivateSwapRequest, PrivateSwapResponse, PrivateTransferRequest, PrivateTransferResponse, QueryNotesRequest, QueryNotesResponse, RegisterRequest, RegisterResponse, RestoreRequest, RestoreResponse, RetryPolicy, SaveEncryptedNoteRequest, SaveEncryptedNoteResponse, VeiloPublicKeyResponse, WithdrawRequest, WithdrawResponse } from "./types.js";
 import { type InternalRelayerClientOptions } from "./internal-config.js";
 import type { ClosePositionRequest, ClosePositionResponse, MergePositionsRequest, MergePositionsResponse, OpenPositionRequest, OpenPositionResponse } from "../positions/types.js";
 import type { JperpCancelTriggerRequest, JperpCancelTriggerResponse, JperpCloseRequest, JperpDecreaseResponse, JperpOpenRequest, JperpOpenResponse, JperpRecoverNativeRequest, JperpRecoverNativeResponse, JperpRecoverSeedRequest, JperpRecoverSeedResponse, JperpReissueRequest, JperpReissueResponse, JperpSetTpslRequest, JperpUpdateTpslRequest } from "../perps/types.js";
@@ -37,6 +37,19 @@ export declare class VeiloRelayerClient {
     /** Query encrypted notes for the authenticated user. Requires auth token. */
     queryEncryptedNotes(params?: QueryNotesRequest): Promise<QueryNotesResponse>;
     /** Delete all stored data for the authenticated user. Requires auth token. */
+    /**
+     * One page of the public compact-note feed.
+     *
+     * Unauthenticated by design: rows carry only ciphertext and a one-byte view
+     * tag, so scanning reveals nothing without the recipient's key. The feed
+     * excludes spent notes and any note already claimed by a wallet.
+     */
+    compactScan(params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<CompactScanResponse>;
+    /** Look up stored notes by commitment. Max 50 per request. */
+    fetchNotesByCommitment(data: FetchByCommitmentRequest): Promise<FetchByCommitmentResponse>;
     /**
      * Ask which of these nullifiers the relayer has seen spent.
      *

package/dist/esm/relayer/client.js

@@ -75,6 +75,28 @@ export class VeiloRelayerClient {
         });
     }
     /** Delete all stored data for the authenticated user. Requires auth token. */
+    /**
+     * One page of the public compact-note feed.
+     *
+     * Unauthenticated by design: rows carry only ciphertext and a one-byte view
+     * tag, so scanning reveals nothing without the recipient's key. The feed
+     * excludes spent notes and any note already claimed by a wallet.
+     */
+    async compactScan(params = {}) {
+        const query = new URLSearchParams();
+        if (params.limit !== undefined)
+            query.set("limit", String(params.limit));
+        if (params.cursor)
+            query.set("cursor", params.cursor);
+        const qs = query.toString();
+        return this.transport.request("GET", `/notes/compact-scan${qs ? `?${qs}` : ""}`);
+    }
+    /** Look up stored notes by commitment. Max 50 per request. */
+    async fetchNotesByCommitment(data) {
+        return this.transport.request("POST", "/notes/fetch-by-commitment", {
+            body: data,
+        });
+    }
     /**
      * Ask which of these nullifiers the relayer has seen spent.
      *

package/dist/esm/relayer/types.d.ts

@@ -39,6 +39,37 @@ export interface QueryNotesResponse {
     limit: number;
     offset: number;
 }
+/** One row from the public compact-note scan feed. */
+export interface CompactScanNote {
+    _id: string;
+    commitment: string;
+    compactEphemeralKey: string | null;
+    compactBlob: string | null;
+    viewTag: number | null;
+    leafIndex?: number | null;
+    treeId?: number | null;
+    mintAddress?: string | null;
+    timestamp?: number;
+    txSignature?: string;
+    spent?: boolean;
+    spentTx?: string;
+}
+export interface CompactScanResponse {
+    success: boolean;
+    notes: CompactScanNote[];
+    /** Opaque cursor for the next page; null when the feed is exhausted. */
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+/** Commitments to look up. Max 50 per request, 64-char hex. */
+export interface FetchByCommitmentRequest {
+    commitments: string[];
+    walletPublicKey?: string;
+}
+export interface FetchByCommitmentResponse {
+    success: boolean;
+    notes: RelayerEncryptedNote[];
+}
 /** Nullifiers to test for spend status. Max 200 per request, 64-char hex. */
 export interface CheckNullifiersRequest {
     nullifiers: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veilo/sdk-core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "TypeScript SDK for the Veilo Privacy Pool - UTXO-based privacy protocol on Solana with ZK-SNARKs",
   "homepage": "https://github.com/VeiloSolana/veilo-sdk#readme",
   "bugs": {