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

package/dist/transactions/types/state-stores.d.ts

@@ -0,0 +1,103 @@
+/**
+ * State store interfaces for transaction operations.
+ */
+import type { JobKind, JobRecord, JobStatus, LeafRecord, NoteRecord, NullifierRecord, RootRecord } from "../../state/index.js";
+/**
+ * Base state store interface with common methods shared across services.
+ */
+export type BaseStateStore = {
+    putLeaf(record: LeafRecord): Promise<void>;
+    getLeaf(chainId: number, index: number): Promise<LeafRecord | null>;
+    clearLeaves(chainId: number): Promise<void>;
+    putRoot(record: RootRecord): Promise<void>;
+    putJob(job: JobRecord): Promise<void>;
+    getJob(relayId: string): Promise<JobRecord | null>;
+    listJobs(filter?: {
+        kind?: JobKind;
+        statuses?: JobStatus[];
+    }): Promise<JobRecord[]>;
+    deleteJob(relayId: string): Promise<void>;
+};
+/**
+ * State store interface for transaction operations.
+ */
+export type TransactStateStore = BaseStateStore & {
+    getNote(chainId: number, index: number): Promise<NoteRecord | null>;
+    markNoteSpent(chainId: number, index: number, spentAt?: number, spentTxHash?: string): Promise<NoteRecord>;
+    putNullifier(record: NullifierRecord): Promise<void>;
+    listNotes(options?: {
+        chainId?: number;
+        mpk?: string;
+        token?: string;
+        includeSpent?: boolean;
+    }): Promise<NoteRecord[]>;
+};
+/**
+ * State store interface for note synchronization operations.
+ * Extends BaseStateStore with note-specific methods.
+ */
+export type NoteSyncStateStore = BaseStateStore & {
+    putNote(record: NoteRecord): Promise<void>;
+    getNote(chainId: number, index: number): Promise<NoteRecord | null>;
+    clearNotes(chainId: number): Promise<void>;
+    listNotes(options?: {
+        chainId?: number;
+        mpk?: string;
+        token?: string;
+        includeSpent?: boolean;
+    }): Promise<NoteRecord[]>;
+    markNoteSpent(chainId: number, index: number, spentAt?: number, spentTxHash?: string): Promise<NoteRecord>;
+    putCiphertext(chainId: number, index: number, payload: Uint8Array): Promise<void>;
+    getCiphertext(chainId: number, index: number): Promise<Uint8Array | null>;
+    clearCiphertexts(chainId: number): Promise<void>;
+    countNullifiers(chainId: number): Promise<number>;
+    clearNullifiers(chainId: number): Promise<void>;
+    clearNullifiersFromIndex(chainId: number, fromIndex: number): Promise<void>;
+    putNullifier(record: {
+        chainId: number;
+        nullifier: string;
+        noteIndex?: number;
+    }): Promise<void>;
+    /**
+     * Atomically store a commitment's leaf, ciphertext, root, and optionally note.
+     * Uses storage.batch() for all-or-nothing semantics.
+     */
+    syncCommitment(params: {
+        leaf: {
+            chainId: number;
+            index: number;
+            commitment: string;
+            txHash?: string;
+            eventType?: string;
+            insertedAt?: number;
+        };
+        ciphertext: {
+            chainId: number;
+            index: number;
+            payload: Uint8Array;
+        };
+        root: {
+            chainId: number;
+            root: string;
+        };
+        note?: {
+            chainId: number;
+            index: number;
+            token: string;
+            value: string;
+            commitment: string;
+            npk: string;
+            mpk: string;
+            random: string;
+            nullifier: string;
+            createdTxHash?: string;
+            createdEventType?: string;
+            createdAt?: number;
+            spentAt?: number;
+            spentTxHash?: string;
+        };
+    }): Promise<void>;
+    /** Clear notes, leaves, ciphertexts, and unspent indices for indices >= fromIndex. */
+    clearChainDataFromIndex(chainId: number, fromIndex: number): Promise<void>;
+};
+//# sourceMappingURL=state-stores.d.ts.map

package/dist/transactions/types/state-stores.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-stores.d.ts","sourceRoot":"","sources":["../../../transactions/types/state-stores.ts"],"names":[],"mappings":"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"}

package/dist/transactions/types/state-stores.js

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

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

@@ -0,0 +1,76 @@
+/**
+ * Types for transaction operations.
+ */
+import type { IMTMerkleProof } from "@zk-kit/imt";
+import type { Account } from "../../account/account.js";
+import type { CommitmentRecord } from "../../clients/indexer.js";
+import type { NoteInput, Proof, SpendNoteReference, WithdrawalNoteInput } from "./domain.js";
+/**
+ * A single transaction item (used in the transactions array).
+ */
+export type TransactItem = {
+    /** Token address */
+    token: string;
+    /** Input notes to spend */
+    inputs: SpendNoteReference[];
+    /** Output notes to create */
+    outputs: NoteInput[];
+    /** Optional withdrawal output */
+    withdrawal?: WithdrawalNoteInput;
+};
+/**
+ * Parameters required to execute private transaction(s).
+ * Always accepts an array of transactions - single tx just passes [item].
+ */
+export type TransactParams = {
+    /** Account with keys for signing and viewing */
+    account: Account;
+    /** Chain ID for the target blockchain */
+    chainId: number;
+    /** Pool contract address */
+    poolAddress: string;
+    /** Transactions to execute (proofs generated in parallel, bundled into one call) */
+    transactions: TransactItem[];
+};
+/**
+ * Result of a single transaction within the batch.
+ */
+export type TransactItemResult = {
+    /** Generated proof */
+    proof: Proof;
+    /** Merkle witnesses for inputs */
+    witnesses: IMTMerkleProof[];
+    /** Nullifiers of spent notes */
+    nullifiers: string[];
+    /** Predicted commitment hex strings */
+    predictedCommitments: string[];
+};
+/**
+ * Result of the transact flow, including calldata and state deltas.
+ */
+export type TransactRelayResult = {
+    /** Relay ID for tracking */
+    relayId: string;
+    /** Calldata to submit on-chain */
+    calldata: string;
+    /** Individual transaction results */
+    transactions: TransactItemResult[];
+};
+/**
+ * Result of syncing a pending transaction.
+ */
+export type TransactSyncResult = {
+    /** Chain ID */
+    chainId: number;
+    /** Merkle root after transaction */
+    root: string;
+    /** Nullifiers of spent notes (all transactions combined) */
+    nullifiers: string[];
+    /** New commitment hex strings (all transactions combined) */
+    newCommitments: string[];
+    /** Transaction hash (if available) */
+    txHash?: string;
+    /** Indexed commitments */
+    indexedCommitments?: CommitmentRecord[];
+};
+//# sourceMappingURL=transact.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transact.d.ts","sourceRoot":"","sources":["../../../transactions/types/transact.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EACV,SAAS,EACT,KAAK,EACL,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAErB;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,6BAA6B;IAC7B,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,iCAAiC;IACjC,UAAU,CAAC,EAAE,mBAAmB,CAAC;CAClC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,gDAAgD;IAChD,OAAO,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,YAAY,EAAE,YAAY,EAAE,CAAC;CAC9B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,sBAAsB;IACtB,KAAK,EAAE,KAAK,CAAC;IACb,kCAAkC;IAClC,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,gCAAgC;IAChC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,uCAAuC;IACvC,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,YAAY,EAAE,kBAAkB,EAAE,CAAC;CACpC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,eAAe;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,6DAA6D;IAC7D,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,kBAAkB,CAAC,EAAE,gBAAgB,EAAE,CAAC;CACzC,CAAC"}

package/dist/transactions/types/transact.js

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

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

@@ -0,0 +1,58 @@
+import { type CircuitConfig } from "../prover/registry.js";
+import type { NoteInput, SelectableNote, WithdrawalNoteInput } from "./types/index.js";
+/**
+ * Result of planning a withdrawal transaction.
+ */
+export type WithdrawalPlan<T> = {
+    /** Selected input notes to spend */
+    inputs: SelectableNote<T>[];
+    /** Output notes (change only, if any) */
+    outputNotes: NoteInput[];
+    /** Withdrawal specification */
+    withdrawal: WithdrawalNoteInput;
+    /** Selected circuit configuration */
+    circuit: CircuitConfig;
+    /** Total input amount from selected notes */
+    totalInput: bigint;
+    /** Amount being withdrawn */
+    withdrawAmount: bigint;
+    /** Change amount returned to sender */
+    change: bigint;
+    /** Token address */
+    token: string;
+};
+/**
+ * Input for a single withdrawal in a batch.
+ */
+export type WithdrawalInput = {
+    token: string;
+    amount: bigint;
+    recipient: string;
+};
+/**
+ * Plan withdrawal transaction(s).
+ * Accepts 1 or more withdrawals. When multiple withdrawals use the same token,
+ * notes are tracked across withdrawals to avoid double-spending.
+ *
+ * @param notes - Available unspent notes (all tokens)
+ * @param withdrawals - Withdrawals to plan (each with token, amount, recipient)
+ * @param senderMpk - Sender's master public key (for change outputs)
+ * @returns Array of withdrawal plans, one per withdrawal input
+ *
+ * @example
+ * ```typescript
+ * // Single withdrawal
+ * const [plan] = planWithdrawals(notes, [{ token, amount: 100n, recipient: "0x..." }], mpk);
+ *
+ * // Multiple withdrawals (possibly same token)
+ * const plans = planWithdrawals(notes, [
+ *   { token: ETH, amount: 100n, recipient: "0x..." },
+ *   { token: USDC, amount: 50n, recipient: "0x..." },
+ * ], mpk);
+ * ```
+ */
+export declare function planWithdrawals<T extends {
+    index: number;
+    value: bigint | string;
+}>(notes: SelectableNote<T>[], withdrawals: WithdrawalInput[], senderMpk: bigint): WithdrawalPlan<T>[];
+//# sourceMappingURL=withdrawal-planner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"withdrawal-planner.d.ts","sourceRoot":"","sources":["../../transactions/withdrawal-planner.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG7E,OAAO,KAAK,EACV,SAAS,EACT,cAAc,EACd,mBAAmB,EACpB,MAAM,kBAAkB,CAAC;AAE1B;;GAEG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI;IAC9B,oCAAoC;IACpC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5B,yCAAyC;IACzC,WAAW,EAAE,SAAS,EAAE,CAAC;IACzB,+BAA+B;IAC/B,UAAU,EAAE,mBAAmB,CAAC;IAChC,qCAAqC;IACrC,OAAO,EAAE,aAAa,CAAC;IACvB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAmFF;;;;;;;;;;;;;;;;;;;;;GAqBG;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,WAAW,EAAE,eAAe,EAAE,EAC9B,SAAS,EAAE,MAAM,GAChB,cAAc,CAAC,CAAC,CAAC,EAAE,CA0ErB"}

package/dist/transactions/withdrawal-planner.js

@@ -0,0 +1,128 @@
+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.
+ * For withdrawals, outputs = change only (0 or 1).
+ */
+function selectCircuitForWithdrawal(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;
+}
+/**
+ * Plan a single withdrawal transaction. Used internally by `planWithdrawals`.
+ */
+function planSingleWithdrawal(notes, withdrawAmount, recipientAddress, senderMpk, token) {
+    if (withdrawAmount <= 0n) {
+        throw new ValidationError("Withdrawal amount must be positive");
+    }
+    const selection = selectNotesForAmount(notes, withdrawAmount, {
+        recipientCount: 0,
+    });
+    const { selected: inputs, totalInput, change } = selection;
+    const changeOutputCount = change > 0n ? 1 : 0;
+    const outputCount = changeOutputCount + 1;
+    const circuit = selectCircuitForWithdrawal(inputs.length, outputCount);
+    const outputNotes = [];
+    if (change > 0n) {
+        const random = randomBigint();
+        outputNotes.push({
+            mpk: senderMpk,
+            random,
+            token,
+            amount: change,
+        });
+    }
+    const withdrawal = {
+        npk: BigInt(recipientAddress),
+        amount: withdrawAmount,
+        token,
+    };
+    return {
+        inputs,
+        outputNotes,
+        withdrawal,
+        circuit,
+        totalInput,
+        withdrawAmount,
+        change,
+        token,
+    };
+}
+/**
+ * Plan withdrawal transaction(s).
+ * Accepts 1 or more withdrawals. When multiple withdrawals use the same token,
+ * notes are tracked across withdrawals to avoid double-spending.
+ *
+ * @param notes - Available unspent notes (all tokens)
+ * @param withdrawals - Withdrawals to plan (each with token, amount, recipient)
+ * @param senderMpk - Sender's master public key (for change outputs)
+ * @returns Array of withdrawal plans, one per withdrawal input
+ *
+ * @example
+ * ```typescript
+ * // Single withdrawal
+ * const [plan] = planWithdrawals(notes, [{ token, amount: 100n, recipient: "0x..." }], mpk);
+ *
+ * // Multiple withdrawals (possibly same token)
+ * const plans = planWithdrawals(notes, [
+ *   { token: ETH, amount: 100n, recipient: "0x..." },
+ *   { token: USDC, amount: 50n, recipient: "0x..." },
+ * ], mpk);
+ * ```
+ */
+export function planWithdrawals(notes, withdrawals, senderMpk) {
+    if (!withdrawals.length) {
+        throw new ValidationError("At least one withdrawal is required");
+    }
+    // Validate all withdrawals upfront
+    for (const w of withdrawals) {
+        if (w.amount <= 0n) {
+            throw new ValidationError(`Invalid withdrawal amount for ${w.token}: ${w.amount}`);
+        }
+    }
+    // Pre-validate total balances per token (use normalized tokens for comparison)
+    const requiredByToken = new Map();
+    for (const w of withdrawals) {
+        const tokenLower = w.token.toLowerCase();
+        const existing = requiredByToken.get(tokenLower) ?? 0n;
+        requiredByToken.set(tokenLower, existing + w.amount);
+    }
+    for (const [tokenLower, required] of requiredByToken) {
+        const available = notes
+            .filter((n) => n.token.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 w of withdrawals) {
+        const tokenLower = w.token.toLowerCase();
+        // Get available notes for this token, excluding already-used ones
+        const usedIndices = usedNotesByToken.get(tokenLower) ?? new Set();
+        const availableNotes = notes.filter((n) => n.token.toLowerCase() ===
+            tokenLower && !usedIndices.has(n.index));
+        // Plan this withdrawal (pass original token for output)
+        const plan = planSingleWithdrawal(availableNotes, w.amount, w.recipient, senderMpk, w.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;
+}