@unlink-xyz/core 0.1.0

package/dist/transactions/transact.js

@@ -0,0 +1,561 @@
+import { poseidon } from "@railgun-community/circomlibjs";
+import { AbiCoder, Interface, keccak256 } from "ethers";
+import { createBroadcasterClient } from "../clients/broadcaster.js";
+import { createIndexerClient } from "../clients/indexer.js";
+import { serviceConfig } from "../config.js";
+import { CoreError } from "../errors.js";
+import { proveTransaction } from "../prover/index.js";
+import { createMerkleTrees, DEFAULT_JOB_TIMEOUT_MS, rebuildTreeFromStore, } from "../state/index.js";
+import { isNotFoundError, sleep } from "../utils/async.js";
+import { ensureBigint, 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 { ensureAddress, ensureChainId, ensureNoteCommitmentInput, ensureWithdrawalInput, 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)";
+const transactInterface = new Interface([TRANSACT_ABI]);
+function validateTransactRequest(request) {
+    ensureChainId(request.chainId);
+    ensureAddress("pool address", request.poolAddress);
+    ensureAddress("token", request.token);
+    ensureBigint("nullifyingKey", request.zkAccount.nullifyingKey);
+    if (!Array.isArray(request.inputs) || request.inputs.length === 0) {
+        throw new CoreError("at least one input note is required");
+    }
+    request.inputs.forEach((input, idx) => {
+        if (!Number.isInteger(input.index) || input.index < 0) {
+            throw new CoreError(`inputs[${idx}].index must be a non-negative integer`);
+        }
+    });
+    ensureWithdrawalInput("request.withdrawal", request.withdrawal);
+    request.outputs.forEach((output, idx) => {
+        if (output.mpk < 0n) {
+            throw new CoreError(`outputs[${idx}].mpk must be non-negative`);
+        }
+        if (output.random < 0n) {
+            throw new CoreError(`outputs[${idx}].random must be non-negative`);
+        }
+        ensureNoteCommitmentInput(`outputs[${idx}]`, {
+            npk: poseidon([output.mpk, output.random]),
+            amount: output.amount,
+            token: output.token,
+        });
+    });
+}
+/**
+ * Computes the bound parameters hash from chain ID, pool address, and withdrawal parameters.
+ * This hash binds the transaction to specific chain and withdrawal context.
+ */
+export function computeBoundParamsHash(chainId, poolAddress) {
+    const chainIdBigInt = BigInt(chainId);
+    const poolAddressBigInt = BigInt(poolAddress);
+    const hashInput = [chainIdBigInt, poolAddressBigInt];
+    const coder = AbiCoder.defaultAbiCoder();
+    const input = coder.encode(["uint64", "uint160"], hashInput);
+    const result = keccak256(input);
+    return parseHexToBigInt(result) % 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(serialized) {
+    return {
+        root: parseHexToBigInt(serialized.root),
+        leaf: parseHexToBigInt(serialized.leaf),
+        siblings: serialized.pathElements.map((level) => level.map((node) => parseHexToBigInt(node))),
+        pathIndices: serialized.pathIndices,
+        leafIndex: serialized.leafIndex,
+    };
+}
+/**
+ * Simulates the transact pipeline: builds Merkle witnesses, derives nullifiers, and updates local state.
+ */
+export function createTransactService(stateStore, options = {}) {
+    if (!stateStore) {
+        throw new Error("stateStore dependency is required");
+    }
+    const trees = options.merkleTrees ?? createMerkleTrees();
+    const fetchImpl = options.fetch ?? (typeof fetch === "function" ? fetch : undefined);
+    const broadcasterClient = fetchImpl
+        ? createBroadcasterClient(serviceConfig.broadcasterBaseUrl, {
+            fetch: fetchImpl,
+        })
+        : null;
+    const indexerClient = fetchImpl
+        ? createIndexerClient(serviceConfig.indexerBaseUrl, { fetch: fetchImpl })
+        : null;
+    const pollIntervalMs = Math.min(options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS, MAX_POLL_INTERVAL_MS);
+    const pollTimeoutMs = options.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
+    // Gather witnesses and nullifiers for each input note; also guards against stale or inconsistent state.
+    async function buildInputContexts(request) {
+        const contexts = [];
+        let sharedRoot;
+        for (const [idx, input] of request.inputs.entries()) {
+            if (!Number.isInteger(input.index) || input.index < 0) {
+                throw new CoreError(`inputs[${idx}].index must be a non-negative integer`);
+            }
+            const note = await stateStore.getNote(request.chainId, input.index);
+            if (!note) {
+                throw new CoreError(`note ${input.index} not found for chain ${request.chainId}`);
+            }
+            if (note.spentAt !== undefined) {
+                throw new CoreError(`note ${input.index} is already spent`);
+            }
+            const tree = trees.getOrCreate(request.chainId);
+            if (input.index >= tree.getLeafCount()) {
+                throw new CoreError(`note ${input.index} out of range for tree`);
+            }
+            const proof = tree.createMerkleProof(input.index);
+            const proofRoot = formatUint256(BigInt(proof.root));
+            if (!sharedRoot) {
+                sharedRoot = proofRoot;
+            }
+            else if (sharedRoot !== proofRoot) {
+                throw new CoreError("input notes must share the same Merkle root");
+            }
+            const mpk = parseHexToBigInt(note.mpk);
+            const random = parseHexToBigInt(note.random);
+            const derivedNpk = poseidon([mpk, random]);
+            const storedNpk = parseHexToBigInt(note.npk);
+            if (storedNpk !== derivedNpk) {
+                throw new CoreError(`note ${input.index} npk mismatch`);
+            }
+            const amount = BigInt(note.value);
+            if (amount < 0n) {
+                throw new CoreError(`note ${input.index} amount must be non-negative`);
+            }
+            ensureAddress("note token", note.token);
+            const tokenScalar = BigInt(note.token);
+            const commitment = poseidon([derivedNpk, tokenScalar, amount]);
+            const storedCommitment = parseHexToBigInt(note.commitment);
+            if (storedCommitment !== commitment) {
+                throw new CoreError(`note ${input.index} commitment mismatch`);
+            }
+            const proofLeaf = BigInt(proof.leaf);
+            if (proofLeaf !== storedCommitment) {
+                throw new CoreError(`note ${input.index} proof leaf mismatch`);
+            }
+            const nullifierValue = poseidon([
+                request.zkAccount.nullifyingKey,
+                BigInt(input.index),
+            ]);
+            const context = {
+                index: input.index,
+                nullifier: {
+                    value: nullifierValue,
+                    hex: formatUint256(nullifierValue),
+                },
+                witness: proof,
+            };
+            contexts.push(context);
+        }
+        if (!sharedRoot) {
+            throw new CoreError("at least one input note is required");
+        }
+        return { root: sharedRoot, contexts };
+    }
+    // Record the nullifiers and mark each consumed note as spent at the same timestamp.
+    async function persistNullifiersAndSpend(chainId, contexts, timestamp) {
+        await Promise.all(contexts.map((context) => Promise.all([
+            stateStore.putNullifier({
+                chainId,
+                nullifier: context.nullifier.hex,
+                noteIndex: context.index,
+            }),
+            stateStore.markNoteSpent(chainId, context.index, timestamp),
+        ])));
+    }
+    /**
+     * Derive commitments and assign provisional indexes without mutating local state.
+     * The local tree length stands in for the on-chain leaf count when predicting indices.
+     */
+    function computeAssignedCommitments(chainId, outputs = []) {
+        const baseIndex = trees.getLeafCount(chainId);
+        return outputs.map((output, idx) => {
+            const commitment = deriveCommitment({
+                npk: poseidon([output.mpk, output.random]),
+                amount: output.amount,
+                token: output.token,
+            });
+            return {
+                value: commitment,
+                hex: formatUint256(commitment),
+                index: baseIndex + idx,
+            };
+        });
+    }
+    async function waitForIndexedCommitments(chainId, outputs) {
+        if (!indexerClient) {
+            return [];
+        }
+        const pending = new Set(outputs.map((output) => output.hex.toLowerCase()));
+        const records = new Map();
+        let delay = pollIntervalMs;
+        const deadline = Date.now() + pollTimeoutMs;
+        while (pending.size > 0 && Date.now() <= deadline) {
+            for (const commitment of [...pending]) {
+                const record = await indexerClient
+                    .getCommitment({ chainId, commitment })
+                    .catch((err) => {
+                    if (!isNotFoundError(err)) {
+                        throw err;
+                    }
+                    return null;
+                });
+                if (record) {
+                    const key = record.commitment.toLowerCase();
+                    records.set(key, record);
+                    pending.delete(commitment);
+                }
+            }
+            if (pending.size === 0) {
+                break;
+            }
+            await sleep(delay);
+            delay = Math.min(delay * 2, MAX_POLL_INTERVAL_MS);
+        }
+        if (pending.size > 0) {
+            throw new CoreError("commitments not found in indexer before timeout");
+        }
+        return outputs.map((output) => {
+            const key = output.hex.toLowerCase();
+            const record = records.get(key);
+            if (!record) {
+                throw new CoreError(`missing indexed commitment ${output.hex} after fetch`);
+            }
+            return record;
+        });
+    }
+    async function submitAndAwaitBroadcasterRelay(relayId, pending) {
+        if (!broadcasterClient) {
+            return;
+        }
+        if (!pending.broadcasterRelayId) {
+            const submission = await broadcasterClient.submitRelay({
+                clientTxId: relayId,
+                chainId: pending.chainId,
+                payload: {
+                    kind: "call_data",
+                    to: pending.poolAddress,
+                    data: pending.calldata,
+                },
+            });
+            if (!submission.accepted) {
+                throw new CoreError(submission.message ??
+                    "broadcaster rejected transaction relay submission");
+            }
+            pending.broadcasterRelayId = submission.id;
+        }
+        const deadline = Date.now() + pollTimeoutMs;
+        while (Date.now() <= deadline) {
+            const status = await broadcasterClient.getRelayStatus(pending.broadcasterRelayId);
+            if (status.state === "succeeded") {
+                pending.txHash = status.txHash ?? pending.txHash ?? null;
+                return;
+            }
+            if (status.state === "failed" || status.state === "dead") {
+                throw new CoreError(status.error ?? "broadcaster relay failed");
+            }
+            await sleep(pollIntervalMs);
+        }
+        throw new CoreError("broadcaster relay timed out");
+    }
+    async function applyIndexerUpdates(chainId, records) {
+        const applied = [];
+        const sorted = [...records].sort((a, b) => a.index - b.index);
+        for (const entry of sorted) {
+            const value = parseHexToBigInt(entry.commitment);
+            const currentCount = trees.getLeafCount(chainId);
+            if (entry.index < currentCount) {
+                const proof = trees.createMerkleProof(chainId, entry.index);
+                if (BigInt(proof.leaf) !== value) {
+                    throw new CoreError(`existing leaf mismatch at index ${entry.index}, stored ${proof.leaf.toString(16)}, indexed ${entry.commitment}`);
+                }
+                applied.push({
+                    value,
+                    hex: entry.commitment,
+                    index: entry.index,
+                    root: entry.root,
+                });
+                continue;
+            }
+            if (entry.index > currentCount) {
+                throw new CoreError(`local merkle tree gap, expected next index ${currentCount}, got indexed ${entry.index}`);
+            }
+            // Replay the commitment into the local Merkle tree and ensure the assigned index matches reality.
+            const { index, root } = trees.addLeaf(chainId, value);
+            if (index !== entry.index) {
+                throw new CoreError(`local merkle tree desynchronized, indexed ${entry.index}, local ${index}`);
+            }
+            applied.push({
+                value,
+                hex: entry.commitment,
+                index,
+                root,
+            });
+            await Promise.all([
+                stateStore.putLeaf({
+                    chainId,
+                    index,
+                    commitment: entry.commitment,
+                }),
+                stateStore.putRoot({
+                    chainId,
+                    root,
+                }),
+            ]);
+        }
+        return applied;
+    }
+    async function persistTransactSuccess(job, pending, persisted) {
+        await stateStore.putRoot({
+            chainId: pending.chainId,
+            root: persisted.latestRoot,
+        });
+        await stateStore.putPendingJob({
+            ...job,
+            status: "succeeded",
+            broadcasterRelayId: pending.broadcasterRelayId ?? job.broadcasterRelayId,
+            txHash: pending.txHash ?? job.txHash ?? null,
+            lastCheckedAt: Date.now(),
+            predictedOutputs: job.predictedOutputs.map((output) => {
+                const matched = persisted.rootedCommitments.find((rc) => rc.hex.toLowerCase() === output.hex.toLowerCase());
+                return {
+                    ...output,
+                    index: matched?.index ?? output.index,
+                    root: matched?.root ?? output.root,
+                };
+            }),
+            expectedRoot: persisted.latestRoot,
+        });
+    }
+    const allocateRelayId = () => {
+        if (typeof globalThis.crypto?.randomUUID === "function") {
+            return globalThis.crypto.randomUUID();
+        }
+        return `transact-${Date.now().toString(16)}-${Math.floor(Math.random() * 1e6)}`;
+    };
+    return {
+        async transact(request) {
+            validateTransactRequest(request);
+            await rebuildTreeFromStore({
+                chainId: request.chainId,
+                trees,
+                loadLeaf: stateStore.getLeaf.bind(stateStore),
+            });
+            const { root, contexts } = await buildInputContexts(request);
+            const assignedOutputs = computeAssignedCommitments(request.chainId, request.outputs);
+            // Compute bound parameters hash
+            const boundParamsHash = computeBoundParamsHash(request.chainId, request.poolAddress);
+            // Public signals must match the circuit's public input order:
+            // [merkleRoot, boundParamsHash, ...nullifiers, ...commitmentsOut]
+            const pubSignals = [
+                parseHexToBigInt(root),
+                boundParamsHash,
+                ...contexts.map((context) => context.nullifier.value),
+                ...assignedOutputs.map((output) => output.value),
+            ];
+            // Retrieve input notes to access random and value fields
+            const inputNotes = await Promise.all(request.inputs.map(async (input) => {
+                const note = await stateStore.getNote(request.chainId, input.index);
+                if (!note) {
+                    throw new CoreError(`note ${input.index} not found for chain`);
+                }
+                return note;
+            }));
+            // Generate signature over the message (hash of public signals)
+            const message = poseidon(pubSignals);
+            const signature = signTransactMessage(request.zkAccount.spendingKeyPair.privateKey, message);
+            // Construct the complete raw input for the prover
+            const rawInput = {
+                merkleRoot: root,
+                boundParamsHash: boundParamsHash.toString(),
+                nullifiers: contexts.map((c) => c.nullifier.hex),
+                commitmentsOut: assignedOutputs.map((o) => o.hex),
+                token: request.token,
+                publicKey: request.zkAccount.spendingKeyPair.pubkey.map((pk) => pk.toString()),
+                signature: [
+                    signature.R8[0].toString(),
+                    signature.R8[1].toString(),
+                    signature.S.toString(),
+                ],
+                randomIn: inputNotes.map((note) => note.random),
+                valueIn: inputNotes.map((note) => note.value),
+                pathElements: contexts.map((c) => c.witness.siblings.map((s) => s.toString())),
+                leavesIndices: contexts.map((c) => c.index),
+                nullifyingKey: formatUint256(request.zkAccount.nullifyingKey),
+                npkOut: request.outputs.map((o) => formatUint256(poseidon([o.mpk, o.random]))),
+                valueOut: request.outputs.map((o) => o.amount.toString()),
+            };
+            const proofInput = {
+                merkleRoot: BigInt(rawInput.merkleRoot),
+                boundParamsHash: BigInt(rawInput.boundParamsHash),
+                nullifiers: rawInput.nullifiers.map((n) => BigInt(n)),
+                commitmentsOut: rawInput.commitmentsOut.map((c) => BigInt(c)),
+                token: BigInt(rawInput.token),
+                publicKey: rawInput.publicKey.map((pk) => BigInt(pk)),
+                signature: rawInput.signature.map((s) => BigInt(s)),
+                randomIn: rawInput.randomIn.map((r) => BigInt(r)),
+                valueIn: rawInput.valueIn.map((v) => BigInt(v)),
+                pathElements: rawInput.pathElements.map((pe) => pe.map((e) => BigInt(e))),
+                leavesIndices: rawInput.leavesIndices.map((i) => BigInt(i)),
+                nullifyingKey: BigInt(rawInput.nullifyingKey),
+                npkOut: rawInput.npkOut.map((npk) => BigInt(npk)),
+                valueOut: rawInput.valueOut.map((v) => BigInt(v)),
+            };
+            const txProof = await proveTransaction(proofInput).catch((e) => {
+                throw new CoreError(`Proof generation failed: ${e.message}`);
+            });
+            ensureWithdrawalInput("request.withdrawal", request.withdrawal);
+            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,
+            };
+            const calldata = transactInterface.encodeFunctionData("transact", [
+                [
+                    {
+                        proof: { ...proof, pubSignals: undefined },
+                        merkleRoot: parseHexToBigInt(root),
+                        nullifierHashes: contexts.map((context) => context.nullifier.value),
+                        newCommitments: assignedOutputs.map((output) => output.value),
+                        context: {
+                            chainID: BigInt(request.chainId),
+                            poolAddress: request.poolAddress,
+                        },
+                        withdrawal: request.withdrawal,
+                        ciphertexts: request.outputs.map((note) => ({
+                            data: encryptNote(note).data,
+                        })),
+                    },
+                ],
+            ]);
+            const relayId = allocateRelayId();
+            const job = {
+                relayId,
+                kind: "transact",
+                chainId: request.chainId,
+                status: "pending",
+                broadcasterRelayId: null,
+                txHash: null,
+                createdAt: Date.now(),
+                timeoutMs: DEFAULT_JOB_TIMEOUT_MS,
+                poolAddress: request.poolAddress,
+                calldata,
+                contexts: contexts.map((context) => ({
+                    index: context.index,
+                    nullifier: context.nullifier.hex,
+                    witness: serializeWitness(context.witness, context.index),
+                    root,
+                })),
+                predictedOutputs: assignedOutputs.map((output) => ({
+                    hex: output.hex,
+                    index: output.index,
+                })),
+                expectedRoot: root,
+            };
+            // Submit to broadcaster immediately so reconciliation never has to send the relay.
+            const pendingForBroadcast = {
+                chainId: job.chainId,
+                root,
+                contexts,
+                assignedOutputs,
+                poolAddress: job.poolAddress,
+                calldata: job.calldata,
+                broadcasterRelayId: job.broadcasterRelayId,
+                txHash: job.txHash,
+            };
+            await submitAndAwaitBroadcasterRelay(relayId, pendingForBroadcast);
+            await stateStore.putPendingJob({
+                ...job,
+                status: "broadcasting",
+                broadcasterRelayId: pendingForBroadcast.broadcasterRelayId,
+                txHash: pendingForBroadcast.txHash,
+            });
+            return {
+                relayId,
+                calldata,
+                proof,
+                witnesses: contexts.map((context) => context.witness),
+                nullifiers: contexts.map((context) => context.nullifier.hex),
+                predictedCommitments: assignedOutputs.map((output) => output.hex),
+            };
+        },
+        async syncPendingTransact(relayId) {
+            const job = await stateStore.getPendingJob(relayId);
+            if (!job || job.kind !== "transact") {
+                throw new Error(`unknown transact relay ${relayId}`);
+            }
+            const contexts = job.contexts.map((context) => ({
+                index: context.index,
+                nullifier: {
+                    value: parseHexToBigInt(context.nullifier),
+                    hex: context.nullifier,
+                },
+                witness: deserializeWitness(context.witness),
+            }));
+            const assignedOutputs = job.predictedOutputs.map((output) => ({
+                hex: output.hex,
+                value: parseHexToBigInt(output.hex),
+                index: output.index,
+            }));
+            const pending = {
+                chainId: job.chainId,
+                root: job.expectedRoot ??
+                    job.contexts[0]?.root ??
+                    trees.getRoot(job.chainId),
+                contexts,
+                assignedOutputs,
+                poolAddress: job.poolAddress,
+                calldata: job.calldata,
+                broadcasterRelayId: job.broadcasterRelayId ?? null,
+                txHash: job.txHash ?? null,
+            };
+            await rebuildTreeFromStore({
+                chainId: job.chainId,
+                trees,
+                loadLeaf: stateStore.getLeaf.bind(stateStore),
+            });
+            await stateStore.putRoot({
+                chainId: pending.chainId,
+                root: pending.root,
+            });
+            const indexedRecords = await waitForIndexedCommitments(pending.chainId, pending.assignedOutputs);
+            const rootedCommitments = await applyIndexerUpdates(pending.chainId, indexedRecords);
+            const timestamp = Date.now();
+            await persistNullifiersAndSpend(pending.chainId, pending.contexts, timestamp);
+            const lastCommitment = rootedCommitments[rootedCommitments.length - 1] ?? null;
+            const latestRoot = lastCommitment
+                ? lastCommitment.root
+                : trees.getRoot(pending.chainId);
+            await persistTransactSuccess(job, pending, {
+                rootedCommitments,
+                latestRoot,
+            });
+            return {
+                chainId: pending.chainId,
+                root: latestRoot,
+                nullifiers: pending.contexts.map((context) => context.nullifier.hex),
+                newCommitments: rootedCommitments.map((output) => output.hex),
+                txHash: pending.txHash ?? undefined,
+                indexedCommitments: indexedRecords,
+            };
+        },
+    };
+}

package/dist/transactions/types.d.ts

@@ -0,0 +1,114 @@
+import { IMTMerkleProof } from "@zk-kit/imt";
+import type { ZkAccount } from "../account/zkAccount.js";
+import type { CommitmentRecord } from "../clients/indexer.js";
+import type { JobStatus, LeafRecord, NoteRecord, NullifierRecord, PendingJobKind, PendingJobRecord, 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>;
+    putPendingJob(job: PendingJobRecord): Promise<void>;
+    getPendingJob(relayId: string): Promise<PendingJobRecord | null>;
+    listPendingJobs(filter?: {
+        kind?: PendingJobKind;
+        statuses?: JobStatus[];
+    }): Promise<PendingJobRecord[]>;
+    deletePendingJob(relayId: string): Promise<void>;
+};
+export type DepositStateStore = BaseStateStore;
+export type TransactStateStore = BaseStateStore & {
+    getNote(chainId: number, index: number): Promise<NoteRecord | null>;
+    markNoteSpent(chainId: number, index: number, spentAt?: number): Promise<NoteRecord>;
+    putNullifier(record: NullifierRecord): Promise<void>;
+};
+export type DepositNoteInput = {
+    mpk: bigint;
+    random: bigint;
+    token: string;
+    amount: bigint;
+};
+export type DepositRequest = {
+    zkAccount: ZkAccount;
+    chainId: number;
+    poolAddress: string;
+    depositor: string;
+    note: DepositNoteInput;
+};
+export type DepositRelayResult = {
+    relayId: string;
+    calldata: string;
+    commitment: string;
+};
+export type DepositSyncResult = {
+    chainId: number;
+    index: number;
+    commitment: string;
+    root: string;
+};
+/**
+ * Minimal reference to an input note; index resolves the canonical note state.
+ */
+export type SpendNoteReference = {
+    index: number;
+};
+export type WithdrawalNoteInput = {
+    npk: bigint;
+    amount: bigint;
+    token: string;
+};
+/**
+ * Private output note to append back into the pool after spending.
+ */
+export type OutputNoteInput = {
+    mpk: bigint;
+    random: bigint;
+    token: string;
+    amount: bigint;
+};
+/**
+ * Placeholder proof structure matching the pool interface; pubSignals remain meaningful.
+ */
+export type Proof = {
+    pA: [bigint, bigint];
+    pB: [[bigint, bigint], [bigint, bigint]];
+    pC: [bigint, bigint];
+    pubSignals: bigint[];
+};
+/**
+ * Parameters required to a mock transact call against the local state.
+ */
+export type TransactRequest = {
+    zkAccount: ZkAccount;
+    chainId: number;
+    poolAddress: string;
+    token: string;
+    inputs: SpendNoteReference[];
+    withdrawal: WithdrawalNoteInput;
+    outputs: OutputNoteInput[];
+};
+/**
+ * Result of the mock transact flow, including calldata and state deltas.
+ */
+export type TransactRelayResult = {
+    relayId: string;
+    calldata: string;
+    proof: Proof;
+    witnesses: IMTMerkleProof[];
+    nullifiers: string[];
+    predictedCommitments: string[];
+};
+export type TransactSyncResult = {
+    chainId: number;
+    root: string;
+    nullifiers: string[];
+    newCommitments: string[];
+    txHash?: string;
+    indexedCommitments?: CommitmentRecord[];
+};
+export type Ciphertext = {
+    data: [bigint, bigint, bigint];
+};
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/transactions/types.js

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