@unlink-xyz/core 0.1.3 → 0.1.4

package/dist/transactions/reconcile.d.ts

@@ -1,20 +1,18 @@
-import type { JobStatus, PendingJobKind } from "../state/index.js";
-import type { BaseStateStore, DepositSyncResult, TransactSyncResult } from "./types.js";
-type DepositClient = {
-    syncPendingDeposit(relayId: string): Promise<DepositSyncResult>;
-};
-type TransactService = {
-    syncPendingTransact(relayId: string): Promise<TransactSyncResult>;
-};
+import type { JobKind, JobStatus } from "../state/index.js";
+import type { BaseStateStore, DepositSyncResult, TransactSyncResult } from "./types/index.js";
 type ReconcilerDeps = {
     stateStore: BaseStateStore;
-    depositClient: DepositClient;
-    transactService: TransactService;
+    depositClient: {
+        syncPendingDeposit: (relayId: string) => Promise<DepositSyncResult>;
+    };
+    transactService: {
+        syncPendingTransact: (relayId: string) => Promise<TransactSyncResult>;
+    };
 };
 export declare function createJobReconciler(deps: ReconcilerDeps): {
     reconcileRelay: (relayId: string) => Promise<DepositSyncResult | TransactSyncResult>;
     reconcileAll: (filter?: {
-        kind?: PendingJobKind;
+        kind?: JobKind;
         statuses?: JobStatus[];
     }) => Promise<unknown[]>;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../transactions/reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,cAAc,EAEf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB,KAAK,aAAa,GAAG;IACnB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACjE,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACnE,CAAC;AAEF,KAAK,cAAc,GAAG;IACpB,UAAU,EAAE,cAAc,CAAC;IAC3B,aAAa,EAAE,aAAa,CAAC;IAC7B,eAAe,EAAE,eAAe,CAAC;CAClC,CAAC;AAIF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,cAAc;8BAUf,MAAM;4BASnC;QACN,IAAI,CAAC,EAAE,cAAc,CAAC;QACtB,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC;KACxB;EAuBJ"}
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../transactions/reconcile.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAa,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,kBAAkB,CAAC;AAE1B,KAAK,cAAc,GAAG;IACpB,UAAU,EAAE,cAAc,CAAC;IAC3B,aAAa,EAAE;QACb,kBAAkB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;KACrE,CAAC;IACF,eAAe,EAAE;QACf,mBAAmB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;KACvE,CAAC;CACH,CAAC;AAIF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,cAAc;8BAmEf,MAAM;4BAgBnC;QACN,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC;KACxB;EAyBJ"}

package/dist/transactions/transact.d.ts

@@ -1,29 +1,37 @@
 import { IMTMerkleProof } from "@zk-kit/imt";
-import { FetchLike } from "../clients/http.js";
-import { LocalMerkleTrees } from "../state/index.js";
-import { TransactRelayResult, TransactRequest, TransactStateStore, TransactSyncResult } from "./types.js";
-export declare 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)";
-type TransactServiceOptions = {
-    merkleTrees?: LocalMerkleTrees;
-    fetch?: FetchLike;
-    pollIntervalMs?: number;
-    pollTimeoutMs?: number;
+import { SerializedWitness, ServiceOptions, TransactParams, TransactRelayResult, TransactStateStore, TransactSyncResult } from "./types/index.js";
+export declare 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, uint256 adapterDataHash) context, (uint256 npk, uint256 amount, address token) withdrawal, (uint256 ephemeralKey, uint256[3] data)[] ciphertexts)[] _transactions)";
+/** Default timeout for proof generation in milliseconds (60 seconds) */
+export declare const DEFAULT_PROOF_TIMEOUT_MS = 60000;
+export declare function computeBoundParamsHash(chainId: number, poolAddress: string, adapterDataHash?: bigint): bigint;
+export type AdapterExecutionCall = {
+    to: string;
+    data: string;
+    value: bigint;
 };
-export type SerializedWitness = {
-    root: string;
-    leaf: string;
-    pathElements: string[][];
-    pathIndices: number[];
-    leafIndex: number;
+export type AdapterExecutionReshield = {
+    npk: bigint;
+    random: bigint;
+    token: string;
+    minAmount: bigint;
 };
+export declare function computeAdapterDataHash(params: {
+    calls: AdapterExecutionCall[];
+    reshields: AdapterExecutionReshield[];
+    inputTokens: string[];
+    nonce: bigint;
+    deadline: bigint;
+    chainId: number;
+}): bigint;
 export declare function serializeWitness(proof: IMTMerkleProof, index: number): SerializedWitness;
-export declare function deserializeWitness(serialized: SerializedWitness): IMTMerkleProof;
+export declare function deserializeWitness(s: SerializedWitness): IMTMerkleProof;
 /**
- * Simulates the transact pipeline: builds Merkle witnesses, derives nullifiers, and updates local state.
+ * Execute private transaction(s): build ZK proofs (in parallel), encrypt outputs, and broadcast.
+ * Accepts 1 or more transactions - single tx just passes [{...}].
  */
-export declare function createTransactService(stateStore: TransactStateStore, options?: TransactServiceOptions): {
-    transact(request: TransactRequest): Promise<TransactRelayResult>;
-    syncPendingTransact(relayId: string): Promise<TransactSyncResult>;
-};
-export {};
+export declare function transact(store: TransactStateStore, req: TransactParams, opts: ServiceOptions): Promise<TransactRelayResult>;
+/**
+ * Wait for a pending transaction to be indexed and update local state.
+ */
+export declare function syncTransact(store: TransactStateStore, relayId: string, opts: ServiceOptions): Promise<TransactSyncResult>;
 //# sourceMappingURL=transact.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"transact.d.ts","sourceRoot":"","sources":["../../transactions/transact.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAI7C,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAK/C,OAAO,EAGL,gBAAgB,EAGjB,MAAM,mBAAmB,CAAC;AAqB3B,OAAO,EAGL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,YAAY,kTACwR,CAAC;AA8ClT,KAAK,sBAAsB,GAAG;IAC5B,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAmDF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,EAAE,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,MAAM,GACZ,iBAAiB,CAUnB;AAED,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,iBAAiB,GAC5B,cAAc,CAUhB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,kBAAkB,EAC9B,OAAO,GAAE,sBAA2B;sBAwVV,eAAe,GAAG,OAAO,CAAC,mBAAmB,CAAC;iCA+LnC,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;EAoF1E"}
+{"version":3,"file":"transact.d.ts","sourceRoot":"","sources":["../../transactions/transact.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAiC7C,OAAO,EAEL,iBAAiB,EACjB,cAAc,EAGd,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,kBAAkB,CAAC;AAE1B,eAAO,MAAM,YAAY,iWACuU,CAAC;AAEjW,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAS/C,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,eAAe,GAAE,MAAW,GAC3B,MAAM,CAOR;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,SAAS,EAAE,wBAAwB,EAAE,CAAC;IACtC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAqBT;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,MAAM,GACZ,iBAAiB,CAUnB;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,iBAAiB,GAAG,cAAc,CAQvE;AA6MD;;;GAGG;AACH,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,kBAAkB,EACzB,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,mBAAmB,CAAC,CAoN9B;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,kBAAkB,CAAC,CAkI7B"}

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, senderViewingPubKey: Uint8Array): 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;AAuD1B;;;;;;;;;;;;;;;;;;;;;;;;;;;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,EACb,mBAAmB,EAAE,UAAU,GAC9B,eAAe,CAAC,CAAC,CAAC,CA2EpB"}

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

@@ -0,0 +1,37 @@
+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;
+    recipientViewingPubKey: Uint8Array;
+};
+/**
+ * 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, senderViewingPubKey: Uint8Array): 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;IACrB,sBAAsB,EAAE,UAAU,CAAC;CACpC,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,EACjB,mBAAmB,EAAE,UAAU,GAC9B,eAAe,CAAC,CAAC,CAAC,EAAE,CA4FtB"}

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

@@ -0,0 +1,67 @@
+/**
+ * Types for deposit operations.
+ */
+import type { AccountView } 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 identity (viewing key + mpk); spending key not needed for deposit */
+    account: AccountView;
+    /** 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,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,gFAAgF;IAChF,OAAO,EAAE,WAAW,CAAC;IACrB,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,70 @@
+/**
+ * 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 = {
+    ephemeralKey: bigint;
+    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";
+    /** Ed25519 viewing public key of the note owner (for ECDH encryption) */
+    viewingPublicKey: Uint8Array;
+};
+/**
+ * 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,YAAY,EAAE,MAAM,CAAC;IACrB,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;IAC7B,yEAAyE;IACzE,gBAAgB,EAAE,UAAU,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/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/options.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Configuration options for transaction services.
+ */
+import type { FetchLike } from "../../clients/http.js";
+import type { ProverOptions } from "../../prover/prover.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 & {
+    /** Gateway URL for the Unlink backend services */
+    gatewayUrl: string;
+    /** Optional prover/artifact source overrides */
+    prover?: ProverOptions;
+    /** 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;
+    /**
+     * Skip broadcaster submission (for swap adapter wrapping).
+     */
+    skipBroadcast?: boolean;
+    /** Skip local job persistence (adapter manages its own job record). */
+    persistJob?: boolean;
+};
+/**
+ * Options for note synchronization operations.
+ */
+export type NoteSyncOptions = {
+    /** Gateway URL for the Unlink backend services (required if indexerClient not provided) */
+    gatewayUrl?: string;
+    /** Merkle tree instances for local state */
+    merkleTrees?: LocalMerkleTrees;
+    /** Indexer client instance (if provided, gatewayUrl 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,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,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,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,uEAAuE;IACvE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,sEAAsE;IAEtE,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/planning.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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;
+    /** Recipient's Ed25519 viewing public key (for ECDH encryption) */
+    viewingPublicKey: Uint8Array;
+};
+/**
+ * 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;IACf,mEAAmE;IACnE,gBAAgB,EAAE,UAAU,CAAC;CAC9B,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/state-stores.d.ts

@@ -0,0 +1,151 @@
+/**
+ * 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>;
+    listLeaves(chainId: number): Promise<LeafRecord[]>;
+    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>;
+    listCiphertexts(chainId: number): Promise<{
+        index: number;
+        payload: Uint8Array;
+    }[]>;
+    clearCiphertexts(chainId: number): Promise<void>;
+    countNullifiers(chainId: number): Promise<number>;
+    clearNullifiers(chainId: number): Promise<void>;
+    clearNullifiersFromIndex(chainId: number, fromIndex: number): Promise<void>;
+    putNullifier(record: NullifierRecord): 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;
+            adapterNpk?: string;
+            adapterToken?: string;
+            adapterAmount?: string;
+            adapterRandom?: 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>;
+    /** Atomically store multiple commitments in a single batch write. */
+    syncCommitmentBatch(items: Array<{
+        leaf: {
+            chainId: number;
+            index: number;
+            commitment: string;
+            txHash?: string;
+            eventType?: string;
+            adapterNpk?: string;
+            adapterToken?: string;
+            adapterAmount?: string;
+            adapterRandom?: 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>;
+    getRescanCursor(chainId: number, mpk: string): Promise<number | null>;
+    setRescanCursor(chainId: number, mpk: string, value: number): Promise<void>;
+    clearRescanCursors(chainId: number): 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