@unlink-xyz/core 0.1.2 → 0.1.3-canary.0877bfe

package/dist/transactions/deposit.js

@@ -1,169 +1,220 @@
 import { Interface } from "ethers";
-import { v4 as uuidv4 } from "uuid";
+import { resolveFetch } from "../clients/http.js";
 import { createIndexerClient } from "../clients/indexer.js";
-import { serviceConfig } from "../config.js";
-import { ByteLength, ByteUtils } from "../key-derivation/bytes.js";
-import { createMerkleTrees, DEFAULT_JOB_TIMEOUT_MS, rebuildTreeFromStore, } from "../state/index.js";
-import { isNotFoundError, sleep } from "../utils/async.js";
-import { parseHexToBigInt } from "../utils/bigint.js";
+import { createServiceConfig } from "../config.js";
+import { ETH_TOKEN } from "../constants.js";
+import { CoreError, InitializationError, ValidationError } from "../errors.js";
+import { FieldSize, Hex } from "../keys/hex.js";
+import { DEFAULT_JOB_TIMEOUT_MS, rebuildTreeFromStore, resolveMerkleTrees, } from "../state/index.js";
+import { sleep } from "../utils/async.js";
 import { computeCommitment, deriveNpk, encryptNote } from "../utils/crypto.js";
-import { DEFAULT_POLL_INTERVAL_MS, DEFAULT_POLL_TIMEOUT_MS, MAX_POLL_INTERVAL_MS, } from "../utils/polling.js";
-import { ensureAddress, ensureChainId } from "../utils/validators.js";
+import { DEFAULT_INITIAL_POLL_DELAY_MS, DEFAULT_POLL_INTERVAL_MS, DEFAULT_POLL_TIMEOUT_MS, MAX_POLL_INTERVAL_MS, } from "../utils/polling.js";
 export const DEPOSIT_ABI = [
-    "function deposit(address _depositor, (uint256 npk, uint256 amount, address token)[] notes, (uint256[3] data)[] ciphertexts)",
+    "function deposit(address _depositor, (uint256 npk, uint256 amount, address token)[] notes, (uint256[3] data)[] ciphertexts) payable",
 ];
 const depositInterface = new Interface(DEPOSIT_ABI);
-function validateDepositRequest(request) {
-    ensureChainId(request.chainId);
-    ensureAddress("pool address", request.poolAddress);
-    ensureAddress("depositor", request.depositor);
-    ensureAddress("token", request.note.token);
-    if (request.note.mpk < 0n) {
-        throw new Error("mpk must be non-negative");
-    }
-    if (request.note.random < 0n) {
-        throw new Error("random must be non-negative");
+/**
+ * Process notes: derive npk, compute commitment, and encrypt.
+ */
+function processNotes(_account, _chainId, _poolAddress, _depositor, notes) {
+    return notes.map((note) => {
+        const npk = deriveNpk(note);
+        const commitment = computeCommitment(note, npk);
+        const commitmentHex = Hex.fromBigInt(commitment, FieldSize.SCALAR, true);
+        const encrypted = encryptNote(note);
+        return {
+            npk,
+            commitmentHex,
+            token: note.token,
+            amount: note.amount,
+            encrypted,
+        };
+    });
+}
+/**
+ * Build deposit calldata from processed notes.
+ */
+function buildDepositCalldata(depositor, processedNotes) {
+    return depositInterface.encodeFunctionData("deposit", [
+        depositor,
+        processedNotes.map((d) => ({
+            npk: d.npk,
+            amount: d.amount,
+            token: d.token,
+        })),
+        processedNotes.map((d) => ({ data: d.encrypted.data })),
+    ]);
+}
+/**
+ * Generate a relay ID for tracking.
+ */
+function generateRelayId(prefix) {
+    return (globalThis.crypto?.randomUUID?.() ?? `${prefix}-${Date.now().toString(16)}`);
+}
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Prepare a deposit: compute commitments, build calldata, and persist pending job.
+ * Accepts 1 or more notes in a single transaction.
+ */
+export async function deposit(store, req) {
+    if (!req.notes?.length) {
+        throw new ValidationError("At least one note is required for deposit");
     }
-    if (request.note.amount < 0n) {
-        throw new Error("amount must be non-negative");
+    const processedNotes = processNotes(req.account, req.chainId, req.poolAddress, req.depositor, req.notes);
+    const calldata = buildDepositCalldata(req.depositor, processedNotes);
+    const relayId = generateRelayId("dep");
+    const value = processedNotes
+        .filter((n) => n.token.toLowerCase() === ETH_TOKEN.toLowerCase())
+        .reduce((sum, n) => sum + n.amount, 0n);
+    const job = {
+        relayId,
+        kind: "deposit",
+        chainId: req.chainId,
+        status: "pending",
+        txHash: null,
+        createdAt: Date.now(),
+        timeoutMs: DEFAULT_JOB_TIMEOUT_MS,
+        predictedCommitments: processedNotes.map((d) => ({
+            hex: d.commitmentHex,
+            token: d.token,
+            amount: d.amount.toString(),
+        })),
+    };
+    await store.putJob(job);
+    return {
+        relayId,
+        to: req.poolAddress,
+        calldata,
+        value,
+        commitments: processedNotes.map((d) => ({
+            commitment: d.commitmentHex,
+            token: d.token,
+            amount: d.amount,
+        })),
+    };
+}
+/**
+ * Poll for a single commitment and verify/persist it.
+ */
+async function pollAndVerifyCommitment(ctx, commitmentHex) {
+    let delay = ctx.pollInterval;
+    let record = null;
+    while (Date.now() <= ctx.deadline) {
+        record = await ctx.indexer.tryGetCommitment({
+            chainId: ctx.chainId,
+            commitment: commitmentHex,
+        });
+        if (record)
+            break;
+        await sleep(delay);
+        delay = Math.min(delay * 2, MAX_POLL_INTERVAL_MS);
     }
-    const tokenScalar = BigInt(request.note.token);
-    if (tokenScalar < 0n) {
-        throw new Error("token must map to non-negative scalar");
+    if (!record) {
+        throw new CoreError(`commitment ${commitmentHex} not found before timeout`);
     }
+    // Note: We intentionally do NOT verify or store the leaf here. The syncChain
+    // flow handles leaf storage, merkle verification, and note decryption together.
+    // If we verified the tree here, we'd need to keep it in sync across multiple
+    // reconcile calls, and if we stored the leaf, syncChain would skip this index
+    // and notes wouldn't be decrypted.
+    //
+    // The indexer's commitment record already contains the verified index and root,
+    // which we return to the caller. The subsequent sync will verify consistency
+    // when it processes this commitment.
+    return {
+        index: record.index,
+        commitment: record.commitment,
+        root: record.root,
+        txHash: record.txHash,
+    };
 }
-export function createDepositClient(stateStore, options) {
-    if (!stateStore) {
-        throw new Error("stateStore dependency is required");
-    }
-    const merkleTrees = options.merkleTrees ?? createMerkleTrees();
-    const indexerClient = createIndexerClient(serviceConfig.indexerBaseUrl, {
-        fetch: options.fetch,
+/**
+ * Create sync context with common setup.
+ */
+async function createSyncContext(store, chainId, createdAt, opts) {
+    const fetchFn = resolveFetch(opts.fetch);
+    if (!fetchFn)
+        throw new InitializationError("fetch is required for sync");
+    const serviceConfig = createServiceConfig(opts.rpcUrl);
+    const trees = resolveMerkleTrees(opts);
+    const indexer = createIndexerClient(serviceConfig.indexerBaseUrl, {
+        fetch: fetchFn,
     });
-    function buildCalldata(request, npk) {
-        return depositInterface.encodeFunctionData("deposit", [
-            request.depositor,
-            [
-                // TODO(julienbrs) handle multiple notes
-                {
-                    npk: npk,
-                    amount: request.note.amount,
-                    token: request.note.token,
-                },
-            ],
-            [
-                {
-                    data: encryptNote(request.note).data,
-                },
-            ],
-        ]);
-    }
-    async function persistDepositSuccess(job, record, indexedRoot) {
-        await Promise.all([
-            stateStore.putLeaf({
-                chainId: job.chainId,
-                index: record.index,
-                commitment: record.commitment,
-            }),
-            stateStore.putRoot({
-                chainId: job.chainId,
-                root: indexedRoot,
-            }),
-            stateStore.putPendingJob({
-                ...job,
-                status: "succeeded",
-                lastCheckedAt: Date.now(),
-                txHash: record.txHash ?? job.txHash ?? null,
-                predictedCommitment: {
-                    ...job.predictedCommitment,
-                    index: record.index,
-                    root: indexedRoot,
-                },
-            }),
-        ]);
+    const pollInterval = opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const pollTimeout = opts.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
+    await rebuildTreeFromStore({
+        chainId,
+        trees,
+        loadLeaf: store.getLeaf.bind(store),
+    });
+    // Calculate deadline BEFORE initial delay so pollTimeout is the total wait time
+    const deadline = Date.now() + pollTimeout;
+    // Wait initial delay for fresh deposits to reduce wasted 404 polls
+    const initialDelay = opts.initialPollDelayMs ?? DEFAULT_INITIAL_POLL_DELAY_MS;
+    const jobAge = Date.now() - createdAt;
+    if (initialDelay > 0 && jobAge < initialDelay) {
+        await sleep(initialDelay - jobAge);
     }
     return {
-        async request(request) {
-            validateDepositRequest(request);
-            const npk = deriveNpk(request);
-            const calldata = buildCalldata(request, npk);
-            const commitment = computeCommitment(request, npk);
-            const commitmentHex = ByteUtils.nToHex(commitment, ByteLength.UINT_256, true);
-            const relayId = uuidv4();
-            const job = {
-                relayId,
-                kind: "deposit",
-                chainId: request.chainId,
-                status: "pending",
-                broadcasterRelayId: null,
-                txHash: null,
-                createdAt: Date.now(),
-                timeoutMs: DEFAULT_JOB_TIMEOUT_MS,
-                predictedCommitment: {
-                    hex: commitmentHex,
-                },
-            };
-            await stateStore.putPendingJob(job);
-            return { relayId, calldata, commitment: commitmentHex };
-        },
-        async syncPendingDeposit(relayId) {
-            const job = await stateStore.getPendingJob(relayId);
-            if (!job || job.kind !== "deposit") {
-                throw new Error(`unknown deposit relay ${relayId}`);
-            }
-            await rebuildTreeFromStore({
-                chainId: job.chainId,
-                trees: merkleTrees,
-                loadLeaf: stateStore.getLeaf.bind(stateStore),
-            });
-            const commitmentHex = job.predictedCommitment.hex;
-            const record = await waitForCommitment(job.chainId, commitmentHex);
-            const { index, root: indexedRoot } = record;
-            const commitmentValue = parseHexToBigInt(commitmentHex);
-            const { index: localIndex, root: localRoot } = merkleTrees.addLeaf(job.chainId, commitmentValue);
-            // TODO: if local state drift detected, need to re-sync since last correct state
-            if (localIndex !== index) {
-                throw new Error("local merkle tree desynchronized (index mismatch), local index: " +
-                    localIndex +
-                    ", indexed index: " +
-                    index);
-            }
-            if (localRoot.toLowerCase() !== indexedRoot.toLowerCase()) {
-                throw new Error("local merkle tree desynchronized (root mismatch), local root: " +
-                    localRoot +
-                    ", indexed root: " +
-                    indexedRoot);
-            }
-            await persistDepositSuccess(job, record, indexedRoot);
-            return {
-                chainId: job.chainId,
-                index,
-                commitment: record.commitment,
-                root: indexedRoot,
-            };
-        },
+        store,
+        chainId,
+        indexer,
+        trees,
+        pollInterval,
+        deadline,
     };
-    async function waitForCommitment(chainId, commitmentHex) {
-        const timeout = options.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
-        const startedAt = Date.now();
-        let delay = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-        while (Date.now() - startedAt <= timeout) {
-            try {
-                const record = await indexerClient.getCommitment({
-                    chainId,
-                    commitment: commitmentHex,
-                });
-                if (record)
-                    return record;
-            }
-            catch (err) {
-                if (!isNotFoundError(err)) {
-                    throw err;
-                }
-            }
-            await sleep(delay);
-            delay = Math.min(delay * 2, MAX_POLL_INTERVAL_MS);
+}
+// ============================================================================
+// Sync Public API
+// ============================================================================
+/**
+ * Wait for all commitments in a deposit to be indexed and update local state.
+ * Works for both single and multi-note deposits.
+ */
+export async function syncDeposit(store, relayId, opts) {
+    const jobRecord = await store.getJob(relayId);
+    if (!jobRecord || jobRecord.kind !== "deposit")
+        throw new CoreError(`unknown deposit relay ${relayId}`);
+    const job = jobRecord;
+    const ctx = await createSyncContext(store, job.chainId, job.createdAt, opts);
+    try {
+        const syncedCommitments = [];
+        for (const predicted of job.predictedCommitments) {
+            const synced = await pollAndVerifyCommitment(ctx, predicted.hex);
+            syncedCommitments.push(synced);
         }
-        throw new Error("commitment not found in indexer before timeout");
+        const finalRoot = syncedCommitments[syncedCommitments.length - 1].root;
+        // Update job status (syncChain handles root storage)
+        await store.putJob({
+            ...job,
+            status: "succeeded",
+            lastCheckedAt: Date.now(),
+            txHash: syncedCommitments[0]?.txHash ?? job.txHash ?? null,
+            predictedCommitments: job.predictedCommitments.map((p, i) => ({
+                ...p,
+                index: syncedCommitments[i]?.index,
+                root: syncedCommitments[i]?.root,
+            })),
+        });
+        return {
+            chainId: job.chainId,
+            commitments: syncedCommitments.map((s) => ({
+                index: s.index,
+                commitment: s.commitment,
+                root: s.root,
+            })),
+            finalRoot,
+        };
+    }
+    catch (error) {
+        await store.putJob({
+            ...job,
+            status: "failed",
+            lastCheckedAt: Date.now(),
+            error: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
     }
 }

package/dist/transactions/index.d.ts

@@ -1,7 +1,10 @@
-export { createDepositClient } from "./deposit.js";
-export { createTransactService } from "./transact.js";
+export { deposit, syncDeposit } from "./deposit.js";
+export { transact, syncTransact } from "./transact.js";
+export { planTransaction } from "./transaction-planner.js";
+export { planWithdrawals, type WithdrawalPlan, type WithdrawalInput, } from "./withdrawal-planner.js";
+export { planTransfers, type TransferInput } from "./transfer-planner.js";
+export { selectNotesForAmount } from "./note-selection.js";
 export { createJobReconciler } from "./reconcile.js";
 export { createNoteSyncService } from "./note-sync.js";
-export type { NoteSyncStateStore } from "./note-sync.js";
-export type { DepositRelayResult, DepositNoteInput, DepositRequest, DepositSyncResult, DepositStateStore, Proof, OutputNoteInput, SpendNoteReference, TransactRelayResult, TransactRequest, TransactSyncResult, TransactStateStore, WithdrawalNoteInput, } from "./types.js";
+export type { BaseStateStore, TransactStateStore, NoteSyncStateStore, PollingOptions, ServiceOptions, NoteSyncOptions, Proof, Ciphertext, NoteInput, WithdrawalNoteInput, SpendNoteReference, SerializedWitness, DepositParams, DepositRelayResult, DepositSyncResult, DepositCommitmentInfo, TransactParams, TransactItem, TransactRelayResult, TransactItemResult, TransactSyncResult, Recipient, PlannedOutput, TransactionPlan, SelectableNote, SelectionOptions, SelectionResult, } from "./types/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/transactions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../transactions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,EACL,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../transactions/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EACL,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAGvD,YAAY,EAEV,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAGlB,cAAc,EACd,cAAc,EACd,eAAe,EAGf,KAAK,EACL,UAAU,EACV,SAAS,EACT,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EAGjB,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EAGrB,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAGlB,SAAS,EACT,aAAa,EACb,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,eAAe,GAChB,MAAM,kBAAkB,CAAC"}

package/dist/transactions/index.js

@@ -1,4 +1,9 @@
-export { createDepositClient } from "./deposit.js";
-export { createTransactService } from "./transact.js";
+// Primary API
+export { deposit, syncDeposit } from "./deposit.js";
+export { transact, syncTransact } from "./transact.js";
+export { planTransaction } from "./transaction-planner.js";
+export { planWithdrawals, } from "./withdrawal-planner.js";
+export { planTransfers } from "./transfer-planner.js";
+export { selectNotesForAmount } from "./note-selection.js";
 export { createJobReconciler } from "./reconcile.js";
 export { createNoteSyncService } from "./note-sync.js";

package/dist/transactions/note-selection.d.ts

@@ -0,0 +1,17 @@
+import type { SelectableNote, SelectionOptions, SelectionResult } from "./types/index.js";
+/**
+ * Select notes for a transaction with consolidation-first strategy.
+ *
+ * Priorities:
+ * 1. Consolidation - prefer spending more small notes
+ * 2. Minimize change - find combinations with less overshoot
+ * 3. Respect maxInputs constraint
+ *
+ * @param notes - Available unspent notes (caller filters by token)
+ * @param totalNeeded - Total amount needed for all recipients
+ * @param options - Selection options
+ * @returns Selection result with notes and amounts
+ * @throws ValidationError if insufficient balance or constraints can't be met
+ */
+export declare function selectNotesForAmount<T>(notes: SelectableNote<T>[], totalNeeded: bigint, options?: SelectionOptions): SelectionResult<T>;
+//# sourceMappingURL=note-selection.d.ts.map

package/dist/transactions/note-selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"note-selection.d.ts","sourceRoot":"","sources":["../../transactions/note-selection.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAyB1B;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,EAC1B,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,eAAe,CAAC,CAAC,CAAC,CAuEpB"}

package/dist/transactions/note-selection.js

@@ -0,0 +1,201 @@
+import { ValidationError } from "../errors.js";
+import { CIRCUIT_REGISTRY } from "../prover/registry.js";
+/** Maximum inputs supported by available circuits */
+const MAX_CIRCUIT_INPUTS = Math.max(...Object.values(CIRCUIT_REGISTRY).map((c) => c.inputs));
+/** Maximum outputs supported by available circuits */
+const MAX_CIRCUIT_OUTPUTS = Math.max(...Object.values(CIRCUIT_REGISTRY).map((c) => c.outputs));
+/**
+ * Get the value of a note as bigint.
+ * Handles both bigint and string values for NoteRecord compatibility.
+ */
+function getNoteValue(note) {
+    return typeof note.value === "bigint" ? note.value : BigInt(note.value);
+}
+/**
+ * Select notes for a transaction with consolidation-first strategy.
+ *
+ * Priorities:
+ * 1. Consolidation - prefer spending more small notes
+ * 2. Minimize change - find combinations with less overshoot
+ * 3. Respect maxInputs constraint
+ *
+ * @param notes - Available unspent notes (caller filters by token)
+ * @param totalNeeded - Total amount needed for all recipients
+ * @param options - Selection options
+ * @returns Selection result with notes and amounts
+ * @throws ValidationError if insufficient balance or constraints can't be met
+ */
+export function selectNotesForAmount(notes, totalNeeded, options) {
+    const maxInputs = options?.maxInputs ?? MAX_CIRCUIT_INPUTS;
+    const maxOutputs = options?.maxOutputs ?? MAX_CIRCUIT_OUTPUTS;
+    const recipientCount = options?.recipientCount ?? 1;
+    // Validate inputs
+    if (totalNeeded <= 0n) {
+        throw new ValidationError("Amount must be positive");
+    }
+    if (!notes.length) {
+        throw new ValidationError("No notes available");
+    }
+    // Validate output constraints: recipients + potential change <= maxOutputs
+    // Change is needed when selected sum > totalNeeded (almost always)
+    // So we conservatively assume change will be needed
+    if (recipientCount + 1 > maxOutputs) {
+        throw new ValidationError(`Too many recipients: ${recipientCount} recipients + change exceeds maxOutputs (${maxOutputs})`);
+    }
+    // Check total balance
+    const totalAvailable = notes.reduce((sum, n) => sum + getNoteValue(n), 0n);
+    if (totalAvailable < totalNeeded) {
+        throw new ValidationError("Insufficient balance");
+    }
+    // Sort ascending for consolidation preference (smallest first)
+    const sortedAsc = [...notes].sort((a, b) => {
+        const aVal = getNoteValue(a);
+        const bVal = getNoteValue(b);
+        return aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
+    });
+    // Phase 1: Try greedy smallest-first
+    let baseline = greedySelect(sortedAsc, totalNeeded, maxInputs);
+    // Phase 2: If greedy smallest-first didn't work, try largest-first as fallback
+    if (baseline.sum < totalNeeded) {
+        const sortedDesc = [...sortedAsc].reverse();
+        baseline = greedySelect(sortedDesc, totalNeeded, maxInputs);
+    }
+    // Phase 3: If we have a valid baseline, use branch-and-bound to optimize
+    // Only run B&B on a subset of notes to keep it fast
+    let optimized;
+    if (baseline.sum >= totalNeeded) {
+        // Limit B&B to reasonable subset for performance (30 smallest notes)
+        const maxNotesForBnB = Math.min(sortedAsc.length, 30);
+        const notesForBnB = sortedAsc.slice(0, maxNotesForBnB);
+        optimized = findOptimalSelection(notesForBnB, totalNeeded, maxInputs, baseline);
+    }
+    else {
+        optimized = baseline;
+    }
+    // If no valid solution found
+    if (optimized.sum < totalNeeded) {
+        throw new ValidationError("Cannot meet amount within maxInputs constraint");
+    }
+    return {
+        selected: optimized.notes,
+        totalInput: optimized.sum,
+        totalNeeded,
+        change: optimized.sum - totalNeeded,
+    };
+}
+/**
+ * Greedy selection: accumulate notes until threshold met.
+ * Returns a partial solution if it can't meet the target.
+ */
+function greedySelect(sorted, target, maxInputs) {
+    const selected = [];
+    let sum = 0n;
+    for (const note of sorted) {
+        if (sum >= target)
+            break;
+        if (selected.length >= maxInputs)
+            break;
+        selected.push(note);
+        sum += getNoteValue(note);
+    }
+    return { notes: selected, sum };
+}
+/**
+ * Compare two solutions.
+ * Returns true if (candidate) is better than (best).
+ *
+ * Priority 0: Prefer valid solutions (sum >= target)
+ * Priority 1: Prefer more notes (consolidation)
+ * Priority 2: Prefer less change
+ */
+function isBetterSolution(candidate, best, target) {
+    const candidateValid = candidate.sum >= target;
+    const bestValid = best.sum >= target;
+    // Priority 0: Prefer valid solutions
+    if (candidateValid && !bestValid)
+        return true;
+    if (!candidateValid && bestValid)
+        return false;
+    if (!candidateValid && !bestValid) {
+        // Neither valid - prefer higher sum (closer to target)
+        return candidate.sum > best.sum;
+    }
+    // Both valid - apply consolidation + change minimization
+    const candidateChange = candidate.sum - target;
+    const bestChange = best.sum - target;
+    // Priority 1: Prefer more notes (consolidation)
+    if (candidate.notes.length > best.notes.length)
+        return true;
+    if (candidate.notes.length < best.notes.length)
+        return false;
+    // Priority 2: Prefer less change
+    return candidateChange < bestChange;
+}
+/**
+ * Branch-and-bound search for optimal selection.
+ *
+ * Explores the solution space with aggressive pruning:
+ * - Stop when sum >= target (don't over-select beyond what's needed)
+ * - Stop when remaining notes can't reach target
+ * - Stop when maxInputs exceeded
+ * - Early termination when we find a solution with maxInputs notes and exact match
+ */
+function findOptimalSelection(sorted, target, maxInputs, baseline) {
+    let best = baseline;
+    let foundOptimal = false;
+    // Precompute remaining sums for pruning
+    const remainingSums = new Array(sorted.length + 1).fill(0n);
+    for (let i = sorted.length - 1; i >= 0; i--) {
+        const nextSum = remainingSums[i + 1] ?? 0n;
+        const note = sorted[i];
+        const noteValue = note ? getNoteValue(note) : 0n;
+        remainingSums[i] = nextSum + noteValue;
+    }
+    function search(index, selected, sum) {
+        // Early exit if we found optimal solution
+        if (foundOptimal)
+            return;
+        // Pruning: too many notes selected
+        if (selected.length > maxInputs)
+            return;
+        // Found valid solution, now comparing with best
+        if (sum >= target) {
+            const candidate = { notes: selected, sum };
+            if (isBetterSolution(candidate, best, target)) {
+                best = { notes: [...selected], sum };
+                // Check if this is optimal (maxInputs notes with exact match)
+                if (selected.length === maxInputs && sum === target) {
+                    foundOptimal = true;
+                }
+            }
+            // Don't add more notes once target is met
+            return;
+        }
+        // Pruning: can't reach target with remaining notes
+        const remaining = remainingSums[index] ?? 0n;
+        if (sum + remaining < target)
+            return;
+        // Pruning: reached end of notes
+        if (index >= sorted.length)
+            return;
+        // Pruning: can't possibly beat best's note count
+        const remainingSlots = maxInputs - selected.length;
+        const remainingNotes = sorted.length - index;
+        if (selected.length + Math.min(remainingSlots, remainingNotes) <
+            best.notes.length) {
+            // Even selecting all remaining notes won't beat best's count
+            // Only skip if best is already valid
+            if (best.sum >= target)
+                return;
+        }
+        const currentNote = sorted[index];
+        if (!currentNote)
+            return;
+        // Try including current note (explore this branch first for consolidation)
+        search(index + 1, [...selected, currentNote], sum + getNoteValue(currentNote));
+        // Try excluding current note
+        search(index + 1, selected, sum);
+    }
+    search(0, [], 0n);
+    return best;
+}