@unlink-xyz/core 0.1.3-canary.fd5dddf → 0.1.4

package/dist/transactions/reconcile.js

@@ -1,85 +0,0 @@
-import { CoreError } from "../errors.js";
-const ACTIVE_STATUSES = ["pending", "submitted", "broadcasting"];
-export function createJobReconciler(deps) {
-    const { stateStore, depositClient, transactService } = deps;
-    async function markChecked(job, err) {
-        const latest = (await stateStore.getJob(job.relayId)) ?? job;
-        const message = err instanceof Error
-            ? err.message
-            : err !== undefined
-                ? String(err)
-                : null;
-        await stateStore.putJob({
-            ...latest,
-            lastCheckedAt: Date.now(),
-            ...(message ? { error: message } : {}),
-        });
-    }
-    async function markDead(job, reason) {
-        const latest = (await stateStore.getJob(job.relayId)) ?? job;
-        if (latest.status === "succeeded")
-            return;
-        await stateStore.putJob({
-            ...latest,
-            status: "dead",
-            lastCheckedAt: Date.now(),
-            error: reason,
-        });
-    }
-    function isTimedOut(job) {
-        return Date.now() - job.createdAt > job.timeoutMs;
-    }
-    async function reconcileJob(job) {
-        const latest = (await stateStore.getJob(job.relayId)) ?? job;
-        if (!ACTIVE_STATUSES.includes(latest.status)) {
-            return null;
-        }
-        if (latest.status !== "succeeded" && isTimedOut(latest)) {
-            await markDead(latest, "job timed out");
-            return new Error("job timed out");
-        }
-        if (latest.kind === "deposit") {
-            return depositClient.syncPendingDeposit(latest.relayId);
-        }
-        return transactService.syncPendingTransact(latest.relayId);
-    }
-    async function reconcileRelay(relayId) {
-        const job = await stateStore.getJob(relayId);
-        if (!job) {
-            throw new CoreError(`unknown relay ${relayId}`);
-        }
-        try {
-            const res = await reconcileJob(job);
-            await markChecked(job);
-            return res;
-        }
-        catch (err) {
-            await markChecked(job, err);
-            throw err;
-        }
-    }
-    async function reconcileAll(filter = {}) {
-        const jobs = await stateStore.listJobs({
-            kind: filter.kind,
-            statuses: filter.statuses ?? ACTIVE_STATUSES,
-        });
-        const results = [];
-        for (const job of jobs) {
-            try {
-                const res = await reconcileJob(job);
-                await markChecked(job);
-                results.push(res);
-            }
-            catch (err) {
-                await markChecked(job, err);
-                // Allow caller to decide how to handle errors; we keep going.
-                results.push(err);
-            }
-        }
-        return results;
-    }
-    return {
-        reconcileRelay,
-        reconcileAll,
-    };
-}

package/dist/transactions/transact.js

@@ -1,450 +0,0 @@
-import { AbiCoder, Interface, keccak256 } from "ethers";
-import { createBroadcasterClient } from "../clients/broadcaster.js";
-import { resolveFetch } from "../clients/http.js";
-import { createIndexerClient } from "../clients/indexer.js";
-import { createServiceConfig } from "../config.js";
-import { poseidon } from "../crypto-adapters/index.js";
-import { CoreError, ProofError, ValidationError } from "../errors.js";
-import { proveTransaction } from "../prover/index.js";
-import { DEFAULT_JOB_TIMEOUT_MS, rebuildTreeFromStore, resolveMerkleTrees, } from "../state/index.js";
-import { isNotFoundError, sleep, withTimeout } from "../utils/async.js";
-import { formatUint256, parseHexToBigInt } from "../utils/bigint.js";
-import { deriveCommitment, encryptNote } from "../utils/crypto.js";
-import { DEFAULT_POLL_INTERVAL_MS, DEFAULT_POLL_TIMEOUT_MS, MAX_POLL_INTERVAL_MS, } from "../utils/polling.js";
-import { signTransactMessage } from "../utils/signature.js";
-import { SNARK_SCALAR_FIELD } from "../utils/validators.js";
-export const TRANSACT_ABI = "function transact(((uint256[2] pA, uint256[2][2] pB, uint256[2] pC) proof, uint256 merkleRoot, uint256[] nullifierHashes, uint256[] newCommitments, (uint64 chainId, address poolAddress) context, (uint256 npk, uint256 amount, address token) withdrawal, (uint256[3] data)[] ciphertexts)[] _transactions)";
-/** Default timeout for proof generation in milliseconds (60 seconds) */
-export const DEFAULT_PROOF_TIMEOUT_MS = 60_000;
-const transactInterface = new Interface([TRANSACT_ABI]);
-const DEFAULT_WITHDRAWAL = {
-    npk: 0n,
-    amount: 0n,
-    token: "0x0000000000000000000000000000000000000000",
-};
-export function computeBoundParamsHash(chainId, poolAddress) {
-    const coder = AbiCoder.defaultAbiCoder();
-    const encoded = coder.encode(["uint64", "uint160"], [BigInt(chainId), BigInt(poolAddress)]);
-    return parseHexToBigInt(keccak256(encoded)) % SNARK_SCALAR_FIELD;
-}
-export function serializeWitness(proof, index) {
-    return {
-        root: formatUint256(BigInt(proof.root)),
-        leaf: formatUint256(BigInt(proof.leaf)),
-        pathElements: proof.siblings.map((level) => level.map((node) => formatUint256(BigInt(node)))),
-        pathIndices: proof.pathIndices ?? [],
-        leafIndex: index,
-    };
-}
-export function deserializeWitness(s) {
-    return {
-        root: parseHexToBigInt(s.root),
-        leaf: parseHexToBigInt(s.leaf),
-        siblings: s.pathElements.map((level) => level.map(parseHexToBigInt)),
-        pathIndices: s.pathIndices,
-        leafIndex: s.leafIndex,
-    };
-}
-/**
- * Build proof for a single transaction item.
- * This is the core proof generation logic extracted for parallelization.
- */
-async function buildSingleTransactionProof(store, account, chainId, poolAddress, tx, trees, baseIndex, opts) {
-    if (!tx.inputs?.length)
-        throw new ValidationError("at least one input note is required");
-    // Build input contexts (witnesses + nullifiers)
-    const contexts = [];
-    let merkleRoot;
-    for (const input of tx.inputs) {
-        const note = await store.getNote(chainId, input.index);
-        if (!note)
-            throw new ValidationError(`note ${input.index} not found`);
-        if (note.spentAt !== undefined)
-            throw new ValidationError(`note ${input.index} already spent`);
-        const tree = trees.getOrCreate(chainId);
-        if (input.index >= tree.getLeafCount())
-            throw new ValidationError(`note ${input.index} out of range`);
-        const witness = tree.createMerkleProof(input.index);
-        const root = formatUint256(BigInt(witness.root));
-        if (merkleRoot && merkleRoot !== root)
-            throw new ValidationError("inputs must share same merkle root");
-        merkleRoot = root;
-        const nullifier = poseidon([account.nullifyingKey, BigInt(input.index)]);
-        contexts.push({
-            index: input.index,
-            nullifier,
-            nullifierHex: formatUint256(nullifier),
-            witness,
-        });
-    }
-    // Compute output commitments for regular notes
-    const outputs = tx.outputs.map((o, i) => {
-        const commitment = deriveCommitment({
-            npk: poseidon([o.mpk, o.random]),
-            amount: o.amount,
-            token: o.token,
-        });
-        return {
-            value: commitment,
-            hex: formatUint256(commitment),
-            index: baseIndex + i,
-        };
-    });
-    // Handle withdrawal
-    const withdrawal = tx.withdrawal ?? DEFAULT_WITHDRAWAL;
-    const hasWithdrawal = withdrawal.amount > 0n;
-    if (hasWithdrawal && withdrawal.token !== tx.token) {
-        throw new ValidationError("Withdrawal token must match transaction token");
-    }
-    const withdrawalCommitment = hasWithdrawal
-        ? deriveCommitment({
-            npk: withdrawal.npk,
-            amount: withdrawal.amount,
-            token: withdrawal.token,
-        })
-        : null;
-    // Build arrays for circuit
-    const allCommitmentsOut = hasWithdrawal
-        ? [...outputs.map((o) => o.value), withdrawalCommitment]
-        : outputs.map((o) => o.value);
-    const allNpkOut = hasWithdrawal
-        ? [...tx.outputs.map((o) => poseidon([o.mpk, o.random])), withdrawal.npk]
-        : tx.outputs.map((o) => poseidon([o.mpk, o.random]));
-    const allValueOut = hasWithdrawal
-        ? [...tx.outputs.map((o) => o.amount), withdrawal.amount]
-        : tx.outputs.map((o) => o.amount);
-    // Build prover input
-    const boundParams = computeBoundParamsHash(chainId, poolAddress);
-    const pubSignals = [
-        parseHexToBigInt(merkleRoot),
-        boundParams,
-        ...contexts.map((c) => c.nullifier),
-        ...allCommitmentsOut,
-    ];
-    const inputNotes = await Promise.all(tx.inputs.map((i) => store.getNote(chainId, i.index).then((n) => n)));
-    const sig = signTransactMessage(account.spendingKeyPair.privateKey, poseidon(pubSignals));
-    const proofInput = {
-        merkleRoot: parseHexToBigInt(merkleRoot),
-        boundParamsHash: boundParams,
-        nullifiers: contexts.map((c) => c.nullifier),
-        commitmentsOut: allCommitmentsOut,
-        token: BigInt(tx.token),
-        publicKey: account.spendingKeyPair.pubkey,
-        signature: [sig.R8[0], sig.R8[1], sig.S],
-        randomIn: inputNotes.map((n) => BigInt(n.random)),
-        valueIn: inputNotes.map((n) => BigInt(n.value)),
-        pathElements: contexts.map((c) => c.witness.siblings.map((level) => level.map((s) => s))),
-        leavesIndices: contexts.map((c) => BigInt(c.index)),
-        nullifyingKey: account.nullifyingKey,
-        npkOut: allNpkOut,
-        valueOut: allValueOut,
-    };
-    const proofTimeoutMs = opts.proofTimeoutMs ?? DEFAULT_PROOF_TIMEOUT_MS;
-    const txProof = await withTimeout(proveTransaction(proofInput, { rpcUrl: opts.rpcUrl }), proofTimeoutMs, new ProofError(`Proof generation timed out after ${proofTimeoutMs}ms`)).catch((e) => {
-        if (e instanceof ProofError)
-            throw e;
-        throw new ProofError(`Proof generation failed: ${e.message}`);
-    });
-    const proof = {
-        pA: [BigInt(txProof.proof.pi_a[0]), BigInt(txProof.proof.pi_a[1])],
-        pB: [
-            [BigInt(txProof.proof.pi_b[0][1]), BigInt(txProof.proof.pi_b[0][0])],
-            [BigInt(txProof.proof.pi_b[1][1]), BigInt(txProof.proof.pi_b[1][0])],
-        ],
-        pC: [BigInt(txProof.proof.pi_c[0]), BigInt(txProof.proof.pi_c[1])],
-        pubSignals,
-    };
-    return {
-        proof,
-        witnesses: contexts.map((c) => c.witness),
-        nullifiers: contexts.map((c) => c.nullifierHex),
-        predictedCommitments: outputs.map((o) => o.hex),
-        merkleRoot: merkleRoot,
-        token: tx.token,
-        withdrawal,
-        ciphertexts: tx.outputs.map((note) => ({
-            data: encryptNote(note).data,
-        })),
-        contexts,
-        outputs,
-        inputNotes,
-    };
-}
-// ============================================================================
-// Public API
-// ============================================================================
-/**
- * Execute private transaction(s): build ZK proofs (in parallel), encrypt outputs, and broadcast.
- * Accepts 1 or more transactions - single tx just passes [{...}].
- */
-export async function transact(store, req, opts) {
-    if (!req.transactions?.length)
-        throw new ValidationError("at least one transaction is required");
-    const serviceConfig = createServiceConfig(opts.rpcUrl);
-    const trees = resolveMerkleTrees(opts);
-    const fetchFn = resolveFetch(opts.fetch);
-    const broadcaster = fetchFn
-        ? createBroadcasterClient(serviceConfig.broadcasterBaseUrl, {
-            fetch: fetchFn,
-        })
-        : null;
-    const pollInterval = Math.min(opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS, MAX_POLL_INTERVAL_MS);
-    const pollTimeout = opts.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
-    await rebuildTreeFromStore({
-        chainId: req.chainId,
-        trees,
-        loadLeaf: store.getLeaf.bind(store),
-    });
-    // Calculate base indices for each transaction's outputs
-    let baseIndex = trees.getLeafCount(req.chainId);
-    const baseIndices = [];
-    for (const tx of req.transactions) {
-        baseIndices.push(baseIndex);
-        baseIndex += tx.outputs.length;
-    }
-    // Generate proofs in PARALLEL for all transactions
-    const proofPromises = req.transactions.map((tx, i) => buildSingleTransactionProof(store, req.account, req.chainId, req.poolAddress, tx, trees, baseIndices[i], opts));
-    const results = await Promise.all(proofPromises);
-    // Build combined calldata
-    const calldata = transactInterface.encodeFunctionData("transact", [
-        results.map((r) => ({
-            proof: { pA: r.proof.pA, pB: r.proof.pB, pC: r.proof.pC },
-            merkleRoot: parseHexToBigInt(r.merkleRoot),
-            nullifierHashes: r.contexts.map((c) => c.nullifier),
-            newCommitments: r.proof.pubSignals.slice(2 + r.contexts.length, // Skip root + boundParams + nullifiers
-            r.withdrawal.amount > 0n
-                ? r.proof.pubSignals.length - 1 // Exclude withdrawal commitment (not inserted into tree)
-                : undefined),
-            context: { chainId: BigInt(req.chainId), poolAddress: req.poolAddress },
-            withdrawal: r.withdrawal,
-            ciphertexts: r.ciphertexts,
-        })),
-    ]);
-    const relayId = globalThis.crypto?.randomUUID?.() ?? `tx-${Date.now().toString(16)}`;
-    // Determine if this is a withdrawal (any transaction has withdrawal)
-    const hasAnyWithdrawal = results.some((r) => r.withdrawal.amount > 0n);
-    const historyKind = hasAnyWithdrawal ? "Withdraw" : "Send";
-    // Compute net deltas per token for history preview
-    const deltasByToken = new Map();
-    for (let i = 0; i < req.transactions.length; i++) {
-        const tx = req.transactions[i];
-        const r = results[i];
-        const totalOutputsToRecipients = tx.outputs
-            .filter((o) => o.owner === "recipient")
-            .reduce((sum, o) => sum + o.amount, 0n);
-        // For withdrawals: user loses the withdrawal amount
-        // For sends: user loses what they send to recipients (change returns to them)
-        const netDelta = r.withdrawal.amount > 0n
-            ? -r.withdrawal.amount
-            : -totalOutputsToRecipients;
-        const existing = deltasByToken.get(tx.token) ?? 0n;
-        deltasByToken.set(tx.token, existing + netDelta);
-    }
-    const jobBase = {
-        relayId,
-        chainId: req.chainId,
-        status: "pending",
-        txHash: null,
-        createdAt: Date.now(),
-        timeoutMs: DEFAULT_JOB_TIMEOUT_MS,
-        poolAddress: req.poolAddress,
-        calldata,
-        transactions: results.map((r, i) => {
-            const tx = req.transactions[i];
-            return {
-                token: tx.token,
-                nullifiers: r.nullifiers,
-                predictedCommitments: r.outputs.map((o) => ({ hex: o.hex })),
-                withdrawal: r.withdrawal.amount > 0n
-                    ? {
-                        amount: r.withdrawal.amount.toString(),
-                        recipient: r.withdrawal.npk.toString(),
-                    }
-                    : undefined,
-            };
-        }),
-        historyPreview: {
-            kind: historyKind,
-            amounts: [...deltasByToken.entries()].map(([token, delta]) => ({
-                token,
-                delta: delta.toString(),
-            })),
-        },
-    };
-    const job = hasAnyWithdrawal
-        ? { ...jobBase, kind: "withdraw" }
-        : { ...jobBase, kind: "transfer" };
-    // Submit to broadcaster
-    let txHash = null;
-    if (broadcaster) {
-        const submission = await broadcaster.submitRelay({
-            clientTxId: relayId,
-            chainId: req.chainId,
-            payload: { kind: "call_data", to: req.poolAddress, data: calldata },
-        });
-        if (!submission.accepted) {
-            await store.putJob({
-                ...job,
-                status: "failed",
-                lastCheckedAt: Date.now(),
-                error: submission.message ?? "broadcaster rejected",
-            });
-            throw new CoreError(submission.message ?? "broadcaster rejected");
-        }
-        const deadline = Date.now() + pollTimeout;
-        while (Date.now() <= deadline) {
-            const status = await broadcaster.getRelayStatus(relayId);
-            if (status.state === "succeeded") {
-                txHash = status.txHash ?? null;
-                break;
-            }
-            if (status.state === "failed" || status.state === "dead") {
-                await store.putJob({
-                    ...job,
-                    status: "failed",
-                    lastCheckedAt: Date.now(),
-                    error: status.error ?? "broadcaster relay failed",
-                });
-                throw new CoreError(status.error ?? "broadcaster relay failed");
-            }
-            await sleep(pollInterval);
-        }
-        if (!txHash && Date.now() > deadline) {
-            await store.putJob({
-                ...job,
-                status: "failed",
-                lastCheckedAt: Date.now(),
-                error: "broadcaster relay timed out",
-            });
-            throw new CoreError("broadcaster relay timed out");
-        }
-    }
-    await store.putJob({
-        ...job,
-        status: "broadcasting",
-        txHash,
-    });
-    // Build result with individual transaction results
-    const transactionResults = results.map((r) => ({
-        proof: r.proof,
-        witnesses: r.witnesses,
-        nullifiers: r.nullifiers,
-        predictedCommitments: r.predictedCommitments,
-    }));
-    return {
-        relayId,
-        calldata,
-        transactions: transactionResults,
-    };
-}
-/**
- * Wait for a pending transaction to be indexed and update local state.
- */
-export async function syncTransact(store, relayId, opts) {
-    const record = await store.getJob(relayId);
-    if (!record || (record.kind !== "transfer" && record.kind !== "withdraw"))
-        throw new CoreError(`unknown pool transaction relay ${relayId}`);
-    const job = record;
-    const serviceConfig = createServiceConfig(opts.rpcUrl);
-    const trees = resolveMerkleTrees(opts);
-    const fetchFn = resolveFetch(opts.fetch);
-    const indexer = fetchFn
-        ? createIndexerClient(serviceConfig.indexerBaseUrl, { fetch: fetchFn })
-        : null;
-    const pollInterval = Math.min(opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS, MAX_POLL_INTERVAL_MS);
-    const pollTimeout = opts.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
-    await rebuildTreeFromStore({
-        chainId: job.chainId,
-        trees,
-        loadLeaf: store.getLeaf.bind(store),
-    });
-    // Collect all predicted commitments from all transactions
-    const allPredictedOutputs = job.transactions.flatMap((tx) => tx.predictedCommitments.map((c) => c.hex));
-    // Wait for indexed commitments
-    const indexed = [];
-    if (indexer && allPredictedOutputs.length > 0) {
-        const pending = new Set(allPredictedOutputs.map((h) => h.toLowerCase()));
-        const deadline = Date.now() + pollTimeout;
-        let delay = pollInterval;
-        while (pending.size > 0 && Date.now() <= deadline) {
-            for (const hex of [...pending]) {
-                const rec = await indexer
-                    .getCommitment({ chainId: job.chainId, commitment: hex })
-                    .catch((e) => {
-                    if (!isNotFoundError(e))
-                        throw e;
-                    return null;
-                });
-                if (rec) {
-                    indexed.push(rec);
-                    pending.delete(hex);
-                }
-            }
-            if (pending.size > 0) {
-                await sleep(delay);
-                delay = Math.min(delay * 2, MAX_POLL_INTERVAL_MS);
-            }
-        }
-        if (pending.size > 0) {
-            await store.putJob({
-                ...job,
-                status: "failed",
-                lastCheckedAt: Date.now(),
-                error: "commitments not indexed before timeout",
-            });
-            throw new CoreError("commitments not indexed before timeout");
-        }
-    }
-    // Get latest root from indexed records (syncChain handles actual storage)
-    const sortedIndexed = indexed.sort((a, b) => a.index - b.index);
-    const latestRoot = sortedIndexed.at(-1)?.root ?? trees.getRoot(job.chainId);
-    // Collect all nullifiers from all transactions and mark notes as spent
-    const allNullifiers = job.transactions.flatMap((tx) => tx.nullifiers);
-    const timestamp = Date.now();
-    // Look up note indices by matching nullifiers to notes in the store
-    const allNotes = await store.listNotes({
-        chainId: job.chainId,
-        includeSpent: true,
-    });
-    const nullifierToNoteIndex = new Map();
-    for (const note of allNotes) {
-        if (note.nullifier) {
-            nullifierToNoteIndex.set(note.nullifier, note.index);
-        }
-    }
-    // Resolve every nullifier to its note index, fail fast if any is unknown
-    const resolved = [];
-    for (const nullifier of allNullifiers) {
-        const noteIndex = nullifierToNoteIndex.get(nullifier);
-        if (noteIndex === undefined) {
-            const short = nullifier.slice(0, 10) + "…";
-            const error = `Unknown nullifier ${short} - note not found in local state. This may indicate a sync issue.`;
-            await store.putJob({
-                ...job,
-                status: "failed",
-                lastCheckedAt: Date.now(),
-                error,
-            });
-            throw new CoreError(error);
-        }
-        resolved.push({ nullifier, noteIndex });
-    }
-    const txHash = job.txHash ?? undefined;
-    await Promise.all(resolved.flatMap(({ nullifier, noteIndex }) => [
-        store.putNullifier({ chainId: job.chainId, nullifier, noteIndex }),
-        store.markNoteSpent(job.chainId, noteIndex, timestamp, txHash),
-    ]));
-    await store.putJob({
-        ...job,
-        status: "succeeded",
-        lastCheckedAt: timestamp,
-    });
-    return {
-        chainId: job.chainId,
-        root: latestRoot,
-        nullifiers: allNullifiers,
-        newCommitments: indexed.map((r) => r.commitment),
-        txHash: job.txHash ?? undefined,
-        indexedCommitments: indexed,
-    };
-}

package/dist/transactions/transaction-planner.js

@@ -1,116 +0,0 @@
-import { poseidon } from "../crypto-adapters/index.js";
-import { ProofError, ValidationError } from "../errors.js";
-import { CIRCUIT_REGISTRY } from "../prover/registry.js";
-import { randomBigint } from "../utils/random.js";
-import { selectNotesForAmount } from "./note-selection.js";
-/**
- * Select the smallest circuit that fits the given input/output counts.
- */
-function selectCircuitForTransaction(inputCount, outputCount) {
-    // Sort circuits by total size (inputs + outputs) ascending
-    const circuits = Object.values(CIRCUIT_REGISTRY).sort((a, b) => a.inputs + a.outputs - (b.inputs + b.outputs));
-    const circuit = circuits.find((c) => c.inputs >= inputCount && c.outputs >= outputCount);
-    if (!circuit) {
-        throw new ProofError(`No circuit supports ${inputCount} inputs and ${outputCount} outputs. ` +
-            `Available: ${circuits.map((c) => `${c.inputs}x${c.outputs}`).join(", ")}`);
-    }
-    return circuit;
-}
-/**
- * Generate a planned output note with derived npk and commitment.
- */
-function generateOutput(mpk, amount, token, owner) {
-    const random = randomBigint();
-    const npk = poseidon([mpk, random]);
-    const tokenScalar = BigInt(token);
-    const commitment = poseidon([npk, tokenScalar, amount]);
-    return {
-        mpk,
-        random,
-        token,
-        amount,
-        owner,
-        npk,
-        commitment,
-    };
-}
-/**
- * Plan a transaction: select notes, choose circuit, generate outputs.
- *
- * This function handles:
- * 1. Note selection using consolidation-first algorithm
- * 2. Circuit selection (smallest that fits)
- * 3. Output generation with cryptographic derivations
- *
- * @param notes - Available unspent notes (pre-filtered by token/chain by caller)
- * @param recipients - List of recipients with their amounts
- * @param senderMpk - Sender's master public key (for change output)
- * @param token - Token address being transferred
- * @returns Complete transaction plan ready for building TransactRequest
- * @throws ValidationError if insufficient balance, no valid circuit, or other constraints fail
- *
- * @example
- * ```typescript
- * const plan = planTransaction(
- *   spendableNotes,
- *   [{ mpk: recipientMpk, amount: 100n }],
- *   senderMpk,
- *   "0x...",
- * );
- * // plan.inputs - selected notes to spend
- * // plan.outputs - generated outputs (recipient + change)
- * // plan.circuit - circuit to use for proof
- * ```
- */
-export function planTransaction(notes, recipients, senderMpk, token) {
-    // Validate inputs
-    if (!recipients.length) {
-        throw new ValidationError("At least one recipient is required");
-    }
-    // Validate each recipient has a positive amount
-    for (let i = 0; i < recipients.length; i++) {
-        const recipient = recipients[i];
-        if (recipient && recipient.amount <= 0n) {
-            throw new ValidationError(`Recipient at index ${i} has invalid amount: ${recipient.amount}. All recipients must have amount > 0`);
-        }
-    }
-    const totalSent = recipients.reduce((sum, r) => sum + r.amount, 0n);
-    // Select notes using consolidation-first algorithm
-    // Note: maxInputs/maxOutputs defaults are derived from CIRCUIT_REGISTRY in selectNotesForAmount
-    const selection = selectNotesForAmount(notes, totalSent, {
-        recipientCount: recipients.length,
-    });
-    const { selected: inputs, totalInput, change } = selection;
-    // Determine output count: 1 per recipient + 1 for change (if any)
-    const outputCount = recipients.length + (change > 0n ? 1 : 0);
-    // Select smallest fitting circuit
-    const circuit = selectCircuitForTransaction(inputs.length, outputCount);
-    // Generate outputs
-    const outputs = [];
-    // Recipient outputs
-    for (const recipient of recipients) {
-        outputs.push(generateOutput(recipient.mpk, recipient.amount, token, "recipient"));
-    }
-    // Change output (if any)
-    if (change > 0n) {
-        outputs.push(generateOutput(senderMpk, change, token, "self"));
-    }
-    // Create outputNotes for TransactParams (without derived fields, but with owner metadata)
-    const outputNotes = outputs.map((o) => ({
-        mpk: o.mpk,
-        random: o.random,
-        token: o.token,
-        amount: o.amount,
-        owner: o.owner,
-    }));
-    return {
-        inputs,
-        outputs,
-        outputNotes,
-        circuit,
-        totalInput,
-        totalSent,
-        change,
-        token,
-    };
-}