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

package/dist/transactions/transaction-planner.d.ts

@@ -0,0 +1,34 @@
+import type { Recipient, SelectableNote, TransactionPlan } from "./types/index.js";
+/**
+ * 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 declare function planTransaction<T extends {
+    index: number;
+    value: bigint | string;
+}>(notes: SelectableNote<T>[], recipients: Recipient[], senderMpk: bigint, token: string): TransactionPlan<T>;
+//# sourceMappingURL=transaction-planner.d.ts.map

package/dist/transactions/transaction-planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-planner.d.ts","sourceRoot":"","sources":["../../transactions/transaction-planner.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAGV,SAAS,EACT,cAAc,EACd,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAqD1B;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,eAAe,CAC7B,CAAC,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,EAEnD,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,EAC1B,UAAU,EAAE,SAAS,EAAE,EACvB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,eAAe,CAAC,CAAC,CAAC,CAkEpB"}

package/dist/transactions/transaction-planner.js

@@ -0,0 +1,116 @@
+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,
+    };
+}

package/dist/transactions/transfer-planner.d.ts

@@ -0,0 +1,36 @@
+import type { SelectableNote, TransactionPlan } from "./types/index.js";
+/**
+ * Input for a single transfer in a batch.
+ */
+export type TransferInput = {
+    token: string;
+    amount: bigint;
+    recipientMpk: bigint;
+};
+/**
+ * Plan transfer transaction(s).
+ * Accepts 1 or more transfers. When multiple transfers use the same token,
+ * notes are tracked across transfers to avoid double-spending.
+ *
+ * @param notes - Available unspent notes (all tokens)
+ * @param transfers - Transfers to plan (each with token, amount, recipientMpk)
+ * @param senderMpk - Sender's master public key (for change outputs)
+ * @returns Array of transaction plans, one per transfer input
+ *
+ * @example
+ * ```typescript
+ * // Single transfer
+ * const [plan] = planTransfers(notes, [{ token, amount: 100n, recipientMpk }], senderMpk);
+ *
+ * // Multiple transfers (possibly same token)
+ * const plans = planTransfers(notes, [
+ *   { token: ETH, amount: 100n, recipientMpk: recipient1Mpk },
+ *   { token: USDC, amount: 50n, recipientMpk: recipient2Mpk },
+ * ], senderMpk);
+ * ```
+ */
+export declare function planTransfers<T extends {
+    index: number;
+    value: bigint | string;
+}>(notes: SelectableNote<T>[], transfers: TransferInput[], senderMpk: bigint): TransactionPlan<T>[];
+//# sourceMappingURL=transfer-planner.d.ts.map

package/dist/transactions/transfer-planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer-planner.d.ts","sourceRoot":"","sources":["../../transactions/transfer-planner.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExE;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAC3B,CAAC,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,EAEnD,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,EAC1B,SAAS,EAAE,aAAa,EAAE,EAC1B,SAAS,EAAE,MAAM,GAChB,eAAe,CAAC,CAAC,CAAC,EAAE,CAqFtB"}

package/dist/transactions/transfer-planner.js

@@ -0,0 +1,85 @@
+import { ValidationError } from "../errors.js";
+import { planTransaction } from "./transaction-planner.js";
+/**
+ * Plan transfer transaction(s).
+ * Accepts 1 or more transfers. When multiple transfers use the same token,
+ * notes are tracked across transfers to avoid double-spending.
+ *
+ * @param notes - Available unspent notes (all tokens)
+ * @param transfers - Transfers to plan (each with token, amount, recipientMpk)
+ * @param senderMpk - Sender's master public key (for change outputs)
+ * @returns Array of transaction plans, one per transfer input
+ *
+ * @example
+ * ```typescript
+ * // Single transfer
+ * const [plan] = planTransfers(notes, [{ token, amount: 100n, recipientMpk }], senderMpk);
+ *
+ * // Multiple transfers (possibly same token)
+ * const plans = planTransfers(notes, [
+ *   { token: ETH, amount: 100n, recipientMpk: recipient1Mpk },
+ *   { token: USDC, amount: 50n, recipientMpk: recipient2Mpk },
+ * ], senderMpk);
+ * ```
+ */
+export function planTransfers(notes, transfers, senderMpk) {
+    if (!transfers.length) {
+        throw new ValidationError("At least one transfer is required");
+    }
+    // Validate all transfers upfront
+    for (const t of transfers) {
+        if (!t.token) {
+            throw new ValidationError(`Missing token address in transfer: ${JSON.stringify(t)}`);
+        }
+        // Convert amount to bigint if needed (handles string amounts from frontend)
+        const amount = typeof t.amount === "bigint" ? t.amount : BigInt(t.amount);
+        if (amount <= 0n) {
+            throw new ValidationError(`Invalid transfer amount for ${t.token}: ${t.amount}`);
+        }
+        // Update amount to bigint for downstream use
+        t.amount = amount;
+    }
+    // Pre-validate total balances per token (use normalized tokens for comparison)
+    const requiredByToken = new Map();
+    for (const t of transfers) {
+        const tokenLower = t.token.toLowerCase();
+        const existing = requiredByToken.get(tokenLower) ?? 0n;
+        requiredByToken.set(tokenLower, existing + t.amount);
+    }
+    for (const [tokenLower, required] of requiredByToken) {
+        const available = notes
+            .filter((n) => {
+            const noteToken = n.token;
+            return noteToken && noteToken.toLowerCase() === tokenLower;
+        })
+            .reduce((sum, n) => sum + BigInt(n.value), 0n);
+        if (available < required) {
+            throw new ValidationError(`Insufficient balance for ${tokenLower}: need ${required}, have ${available}`);
+        }
+    }
+    // Track used note indices per token to avoid double-spending
+    const usedNotesByToken = new Map();
+    const plans = [];
+    for (const t of transfers) {
+        const tokenLower = t.token.toLowerCase();
+        // Get available notes for this token, excluding already-used ones
+        const usedIndices = usedNotesByToken.get(tokenLower) ?? new Set();
+        const availableNotes = notes.filter((n) => {
+            const noteToken = n.token;
+            return (noteToken &&
+                noteToken.toLowerCase() === tokenLower &&
+                !usedIndices.has(n.index));
+        });
+        // Plan this transfer using the existing planTransaction function
+        const plan = planTransaction(availableNotes, [{ mpk: t.recipientMpk, amount: t.amount }], senderMpk, t.token);
+        // Mark selected notes as used
+        if (!usedNotesByToken.has(tokenLower)) {
+            usedNotesByToken.set(tokenLower, new Set());
+        }
+        for (const input of plan.inputs) {
+            usedNotesByToken.get(tokenLower).add(input.index);
+        }
+        plans.push(plan);
+    }
+    return plans;
+}

package/dist/transactions/types/deposit.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Types for deposit operations.
+ */
+import type { Account } from "../../account/account.js";
+import type { NoteInput } from "./domain.js";
+/**
+ * Parameters required to execute a deposit.
+ * Always accepts an array of notes - single deposits just pass [note].
+ */
+export type DepositParams = {
+    /** Account with keys for signing and viewing */
+    account: Account;
+    /** Chain ID for the target blockchain */
+    chainId: number;
+    /** Pool contract address */
+    poolAddress: string;
+    /** Depositor address (on-chain account) */
+    depositor: string;
+    /** Notes to deposit (can be different tokens) */
+    notes: NoteInput[];
+};
+/**
+ * Individual commitment info in a deposit result.
+ */
+export type DepositCommitmentInfo = {
+    /** Commitment hex string */
+    commitment: string;
+    /** Token address */
+    token: string;
+    /** Amount deposited */
+    amount: bigint;
+};
+/**
+ * Result of a deposit request.
+ * The user must submit this transaction on-chain using their EOA.
+ */
+export type DepositRelayResult = {
+    /** Relay ID for tracking */
+    relayId: string;
+    /** Pool contract address to submit transaction to */
+    to: string;
+    /** Calldata to submit on-chain */
+    calldata: string;
+    /** msg.value to attach: sum of ETH note amounts, or 0n for pure ERC20 */
+    value: bigint;
+    /** Individual commitment results */
+    commitments: DepositCommitmentInfo[];
+};
+/**
+ * Result of syncing a pending deposit.
+ */
+export type DepositSyncResult = {
+    /** Chain ID */
+    chainId: number;
+    /** Individual commitment sync results */
+    commitments: Array<{
+        /** Index of the commitment in the tree */
+        index: number;
+        /** Commitment hex string */
+        commitment: string;
+        /** Merkle root after insertion */
+        root: string;
+    }>;
+    /** Final merkle root after all insertions */
+    finalRoot: string;
+};
+//# sourceMappingURL=deposit.d.ts.map

package/dist/transactions/types/deposit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deposit.d.ts","sourceRoot":"","sources":["../../../transactions/types/deposit.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,gDAAgD;IAChD,OAAO,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,WAAW,EAAE,qBAAqB,EAAE,CAAC;CACtC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,eAAe;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,WAAW,EAAE,KAAK,CAAC;QACjB,0CAA0C;QAC1C,KAAK,EAAE,MAAM,CAAC;QACd,4BAA4B;QAC5B,UAAU,EAAE,MAAM,CAAC;QACnB,kCAAkC;QAClC,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IACH,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC"}

package/dist/transactions/types/domain.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Core domain types for cryptographic operations.
+ */
+/**
+ * Placeholder proof structure matching the pool interface.
+ */
+export type Proof = {
+    pA: [bigint, bigint];
+    pB: [[bigint, bigint], [bigint, bigint]];
+    pC: [bigint, bigint];
+    pubSignals: bigint[];
+};
+/**
+ * Encrypted note ciphertext.
+ */
+export type Ciphertext = {
+    data: [bigint, bigint, bigint];
+};
+/**
+ * Generic note input for deposits and transaction outputs.
+ */
+export type NoteInput = {
+    /** Master public key */
+    mpk: bigint;
+    /** Random nonce */
+    random: bigint;
+    /** Token address */
+    token: string;
+    /** Amount */
+    amount: bigint;
+    /** Whether this output goes to a recipient or back to sender as change */
+    owner?: "recipient" | "self";
+};
+/**
+ * Withdrawal note input for extracting funds from the pool.
+ */
+export type WithdrawalNoteInput = {
+    /** Note public key (derived) */
+    npk: bigint;
+    /** Amount to withdraw */
+    amount: bigint;
+    /** Token address */
+    token: string;
+};
+/**
+ * Minimal reference to an input note.
+ */
+export type SpendNoteReference = {
+    /** Index of the note in the commitment tree */
+    index: number;
+};
+/**
+ * Serialized witness for merkle proof.
+ */
+export type SerializedWitness = {
+    /** Merkle root as hex string */
+    root: string;
+    /** Leaf value as hex string */
+    leaf: string;
+    /** Path elements (siblings) as hex strings */
+    pathElements: string[][];
+    /** Path indices for merkle proof */
+    pathIndices: number[];
+    /** Leaf index in the tree */
+    leafIndex: number;
+};
+//# sourceMappingURL=domain.d.ts.map

package/dist/transactions/types/domain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain.d.ts","sourceRoot":"","sources":["../../../transactions/types/domain.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG;IAClB,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrB,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACzC,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa;IACb,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,KAAK,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;CAC9B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,YAAY,EAAE,MAAM,EAAE,EAAE,CAAC;IACzB,oCAAoC;IACpC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC"}

package/dist/transactions/types/domain.js

@@ -0,0 +1,4 @@
+/**
+ * Core domain types for cryptographic operations.
+ */
+export {};

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

@@ -0,0 +1,18 @@
+/**
+ * Transaction type definitions.
+ *
+ * Organized by concern:
+ * - state-stores: Database/storage interfaces
+ * - options: Configuration for services
+ * - domain: Core cryptographic types
+ * - deposit: Deposit-specific types
+ * - transact: Transaction-specific types
+ * - planning: Transaction planning types
+ */
+export * from "./state-stores.js";
+export * from "./options.js";
+export * from "./domain.js";
+export * from "./deposit.js";
+export * from "./transact.js";
+export * from "./planning.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../transactions/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC"}

package/dist/transactions/types/index.js

@@ -0,0 +1,17 @@
+/**
+ * Transaction type definitions.
+ *
+ * Organized by concern:
+ * - state-stores: Database/storage interfaces
+ * - options: Configuration for services
+ * - domain: Core cryptographic types
+ * - deposit: Deposit-specific types
+ * - transact: Transaction-specific types
+ * - planning: Transaction planning types
+ */
+export * from "./state-stores.js";
+export * from "./options.js";
+export * from "./domain.js";
+export * from "./deposit.js";
+export * from "./transact.js";
+export * from "./planning.js";

package/dist/transactions/types/options.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Configuration options for transaction services.
+ */
+import type { FetchLike } from "../../clients/http.js";
+import type { LocalMerkleTrees } from "../../state/index.js";
+/**
+ * Polling configuration for async operations.
+ */
+export type PollingOptions = {
+    /** Polling interval in milliseconds */
+    pollIntervalMs?: number;
+    /** Polling timeout in milliseconds */
+    pollTimeoutMs?: number;
+    /** Initial delay before first poll (reduces 404s for fresh operations). Set to 0 in tests. */
+    initialPollDelayMs?: number;
+};
+/**
+ * Common options for transaction services (deposit, transact).
+ */
+export type ServiceOptions = PollingOptions & {
+    /** RPC URL for the Unlink backend services */
+    rpcUrl: string;
+    /** Fetch implementation for HTTP requests */
+    fetch?: FetchLike;
+    /** Merkle tree instances for local state */
+    merkleTrees?: LocalMerkleTrees;
+    /** Timeout for proof generation in milliseconds (default: 60000) */
+    proofTimeoutMs?: number;
+};
+/**
+ * Options for note synchronization operations.
+ */
+export type NoteSyncOptions = {
+    /** RPC URL for the Unlink backend services (required if indexerClient not provided) */
+    rpcUrl?: string;
+    /** Merkle tree instances for local state */
+    merkleTrees?: LocalMerkleTrees;
+    /** Indexer client instance (if provided, rpcUrl is not needed) */
+    indexerClient?: ReturnType<any>;
+    /** Fetch implementation for HTTP requests */
+    fetch?: FetchLike;
+    /** Batch size for fetching commitments */
+    limit?: number;
+};
+//# sourceMappingURL=options.d.ts.map

package/dist/transactions/types/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../../transactions/types/options.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,uCAAuC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sCAAsC;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8FAA8F;IAC9F,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG;IAC5C,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,uFAAuF;IACvF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,kEAAkE;IAElE,aAAa,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;IAChC,6CAA6C;IAC7C,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC"}

package/dist/transactions/types/options.js

@@ -0,0 +1 @@
+export {};

package/dist/transactions/types/planning.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Types for transaction planning and note selection.
+ */
+import type { NoteInput } from "./domain.js";
+/**
+ * A recipient of funds in a transaction.
+ */
+export type Recipient = {
+    /** Recipient's master public key */
+    mpk: bigint;
+    /** Amount to send */
+    amount: bigint;
+};
+/**
+ * A planned output note with derived cryptographic values.
+ */
+export type PlannedOutput = NoteInput & {
+    /** Whether this output goes to a recipient or back to sender as change */
+    owner: "recipient" | "self";
+    /** Derived note public key: poseidon([mpk, random]) */
+    npk: bigint;
+    /** Derived commitment: poseidon([npk, tokenScalar, amount]) */
+    commitment: bigint;
+};
+/**
+ * Complete transaction plan with selected inputs, planned outputs, and circuit.
+ */
+export type TransactionPlan<T> = {
+    /** Selected input notes */
+    inputs: SelectableNote<T>[];
+    /** Planned output notes (recipients + change) */
+    outputs: PlannedOutput[];
+    /** Output notes formatted for TransactParams (without derived fields) */
+    outputNotes: NoteInput[];
+    /** Selected circuit configuration */
+    circuit: any;
+    /** Total input amount from selected notes */
+    totalInput: bigint;
+    /** Total amount sent to recipients */
+    totalSent: bigint;
+    /** Change amount returned to sender */
+    change: bigint;
+    /** Token address */
+    token: string;
+};
+/**
+ * Minimal note representation for selection algorithm.
+ * Generic over T to allow passing through additional note fields.
+ */
+export type SelectableNote<T = unknown> = T & {
+    /** Note index in the commitment tree */
+    index: number;
+    /** Note value */
+    value: bigint | string;
+};
+/**
+ * Options for note selection algorithm.
+ */
+export type SelectionOptions = {
+    /** Maximum input notes to select (circuit constraint). Default: 8 */
+    maxInputs?: number;
+    /** Maximum output notes (circuit constraint). Default: 4 */
+    maxOutputs?: number;
+    /** Number of recipients (outputs excluding change). Default: 1 */
+    recipientCount?: number;
+};
+/**
+ * Result of note selection algorithm.
+ */
+export type SelectionResult<T> = {
+    /** Selected notes, sorted by value ascending */
+    selected: SelectableNote<T>[];
+    /** Sum of selected note values */
+    totalInput: bigint;
+    /** Amount needed for transaction */
+    totalNeeded: bigint;
+    /** Change amount (totalInput - totalNeeded) */
+    change: bigint;
+};
+//# sourceMappingURL=planning.d.ts.map

package/dist/transactions/types/planning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planning.d.ts","sourceRoot":"","sources":["../../../transactions/types/planning.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG;IACtC,0EAA0E;IAC1E,KAAK,EAAE,WAAW,GAAG,MAAM,CAAC;IAC5B,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI;IAC/B,2BAA2B;IAC3B,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5B,iDAAiD;IACjD,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,yEAAyE;IACzE,WAAW,EAAE,SAAS,EAAE,CAAC;IACzB,qCAAqC;IAErC,OAAO,EAAE,GAAG,CAAC;IACb,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,GAAG;IAC5C,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB;IACjB,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI;IAC/B,gDAAgD;IAChD,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9B,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC"}

package/dist/transactions/types/planning.js

@@ -0,0 +1 @@
+export {};