@veilo/sdk-core 0.4.0 → 0.6.0

package/dist/esm/relayer.js

@@ -1,249 +1,2 @@
-import nacl from "tweetnacl";
-const DEFAULT_RELAYER_URL = "https://relayer-server.onrender.com";
-// =============================================================================
-// Structured Error
-// =============================================================================
-/** Structured error thrown by VeiloRelayerClient on API failures. */
-export class VeiloApiError extends Error {
-    constructor(code, message, status, details) {
-        super(message);
-        this.name = "VeiloApiError";
-        this.code = code;
-        this.status = status;
-        this.details = details;
-    }
-}
-const DEFAULT_RETRY = {
-    maxRetries: 3,
-    baseDelayMs: 1000,
-    retryableStatuses: [429, 502, 503, 504],
-};
-// =============================================================================
-// Base64 helpers (no dependency on tweetnacl-util)
-// =============================================================================
-function toBase64(bytes) {
-    if (typeof Buffer !== "undefined") {
-        return Buffer.from(bytes).toString("base64");
-    }
-    return btoa(String.fromCharCode(...bytes));
-}
-function fromBase64(str) {
-    if (typeof Buffer !== "undefined") {
-        return new Uint8Array(Buffer.from(str, "base64"));
-    }
-    const binary = atob(str);
-    const bytes = new Uint8Array(binary.length);
-    for (let i = 0; i < binary.length; i++)
-        bytes[i] = binary.charCodeAt(i);
-    return bytes;
-}
-// =============================================================================
-// Encryption
-// =============================================================================
-/**
- * Encrypt a JSON-serializable payload for the relayer using NaCl box.
- * Layout: [ephemeralPubKey (32)] [nonce (24)] [ciphertext (...)]
- */
-function encryptForRelayer(data, relayerPublicKey) {
-    const ephemeral = nacl.box.keyPair();
-    const message = new TextEncoder().encode(JSON.stringify(data));
-    const nonce = nacl.randomBytes(nacl.box.nonceLength);
-    const ciphertext = nacl.box(message, nonce, relayerPublicKey, ephemeral.secretKey);
-    const payload = new Uint8Array(ephemeral.publicKey.length + nonce.length + ciphertext.length);
-    payload.set(ephemeral.publicKey, 0);
-    payload.set(nonce, ephemeral.publicKey.length);
-    payload.set(ciphertext, ephemeral.publicKey.length + nonce.length);
-    return toBase64(payload);
-}
-// =============================================================================
-// Relayer Client
-// =============================================================================
-/**
- * HTTP client for the Veilo relayer API.
- *
- * Handles auth, notes, merkle, and encrypted transact endpoints with
- * automatic retry on transient failures and NaCl box payload encryption.
- *
- * @example
- * ```ts
- * const client = new VeiloRelayerClient({
- *   apiKey: "your-api-key",
- *   relayerPublicKey: "<base64 NaCl public key>",
- * });
- * const root = await client.getMerkleRoot("So111...");
- * ```
- */
-export class VeiloRelayerClient {
-    constructor(config, retry) {
-        this.baseUrl = (config.relayerUrl?.trim() || DEFAULT_RELAYER_URL).replace(/\/+$/, "");
-        this.apiKey = config.apiKey;
-        this.relayerPubKey = fromBase64(config.relayerPublicKey);
-        this.authToken = config.authToken;
-        this.retry = { ...DEFAULT_RETRY, ...retry };
-    }
-    /** Update the auth token (e.g. after register/restore). */
-    setAuthToken(token) {
-        this.authToken = token;
-    }
-    // ---------------------------------------------------------------------------
-    // Internal helpers
-    // ---------------------------------------------------------------------------
-    headers(authenticated) {
-        const h = {
-            "Content-Type": "application/json",
-        };
-        if (this.apiKey)
-            h["x-api-key"] = this.apiKey;
-        if (authenticated && this.authToken) {
-            h["Authorization"] = `Bearer ${this.authToken}`;
-        }
-        return h;
-    }
-    async request(method, path, opts = {}) {
-        const url = `${this.baseUrl}/api${path}`;
-        const { body, authenticated = false, retryable = true } = opts;
-        const maxAttempts = retryable ? this.retry.maxRetries + 1 : 1;
-        let lastError;
-        for (let attempt = 0; attempt < maxAttempts; attempt++) {
-            if (attempt > 0) {
-                const delay = this.retry.baseDelayMs * Math.pow(2, attempt - 1) +
-                    Math.random() * 200;
-                await new Promise((r) => setTimeout(r, delay));
-            }
-            let res;
-            try {
-                res = await fetch(url, {
-                    method,
-                    headers: this.headers(authenticated),
-                    body: body != null ? JSON.stringify(body) : undefined,
-                });
-            }
-            catch (err) {
-                lastError = new VeiloApiError("NETWORK_ERROR", err.message || "Network request failed", 0);
-                continue;
-            }
-            const data = await res.json().catch(() => ({}));
-            if (res.ok && data.success !== false) {
-                return data;
-            }
-            lastError = new VeiloApiError(data.error || "UNKNOWN", data.message || data.error || `Request failed: ${res.status}`, res.status, data);
-            // Only retry on transient statuses
-            if (!this.retry.retryableStatuses.includes(res.status)) {
-                throw lastError;
-            }
-        }
-        throw lastError;
-    }
-    encrypt(data) {
-        return encryptForRelayer({
-            ...data,
-            timestamp: Date.now(),
-            nonce: toBase64(nacl.randomBytes(32)),
-        }, this.relayerPubKey);
-    }
-    // ---------------------------------------------------------------------------
-    // Auth
-    // ---------------------------------------------------------------------------
-    /** Request a signature challenge for wallet authentication. */
-    async getChallenge(walletPublicKey) {
-        return this.request("POST", "/auth/challenge", {
-            body: { walletPublicKey },
-        });
-    }
-    /** Register a new account with a signed challenge. Returns a JWT auth token. */
-    async register(data) {
-        return this.request("POST", "/auth/register", { body: data });
-    }
-    /** Restore an existing account using a signed challenge. Returns a JWT auth token. */
-    async restore(data) {
-        return this.request("POST", "/auth/restore", { body: data });
-    }
-    /** Check whether a username is available for registration. */
-    async checkUsername(username) {
-        return this.request("GET", `/auth/checkUsername?username=${encodeURIComponent(username)}`);
-    }
-    /** Look up a user's Veilo public key by username or wallet public key. */
-    async getVeiloPublicKey(params) {
-        const query = "username" in params && params.username
-            ? `username=${encodeURIComponent(params.username)}`
-            : `publicKey=${encodeURIComponent(params.publicKey)}`;
-        return this.request("GET", `/auth/veiloPublicKey?${query}`);
-    }
-    /**
-     * Provision (or retrieve) the Veilo spend key paired with a Solana address.
-     * Public and idempotent; the response contains public key material only.
-     */
-    async preRegisterKey(solanaAddress) {
-        return this.request("POST", "/auth/pre-register-key", {
-            body: { solanaAddress },
-        });
-    }
-    // ---------------------------------------------------------------------------
-    // Notes
-    // ---------------------------------------------------------------------------
-    /** Save an encrypted note to the relayer's database. */
-    async saveEncryptedNote(data) {
-        return this.request("POST", "/notes/save", { body: data });
-    }
-    /** Query encrypted notes for the authenticated user. Requires auth token. */
-    async queryEncryptedNotes(params = {}) {
-        return this.request("POST", "/notes/query", {
-            body: params,
-            authenticated: true,
-        });
-    }
-    /** Delete all stored data for the authenticated user. Requires auth token. */
-    async deleteUserData() {
-        return this.request("POST", "/notes/delete", { authenticated: true });
-    }
-    // ---------------------------------------------------------------------------
-    // Merkle
-    // ---------------------------------------------------------------------------
-    /** Fetch the current Merkle root for a pool, optionally filtered by mint and tree ID. */
-    async getMerkleRoot(mintAddress, treeId) {
-        const params = new URLSearchParams();
-        if (mintAddress)
-            params.append("mintAddress", mintAddress);
-        if (treeId !== undefined)
-            params.append("treeId", treeId.toString());
-        const qs = params.toString();
-        return this.request("GET", `/merkle/root${qs ? `?${qs}` : ""}`);
-    }
-    /** Fetch the full Merkle tree (all leaves) for a pool. */
-    async getMerkleTree(mintAddress, treeId) {
-        const params = new URLSearchParams();
-        if (mintAddress)
-            params.append("mintAddress", mintAddress);
-        if (treeId !== undefined)
-            params.append("treeId", treeId.toString());
-        const qs = params.toString();
-        return this.request("GET", `/merkle/tree${qs ? `?${qs}` : ""}`);
-    }
-    // ---------------------------------------------------------------------------
-    // Transact (encrypted payloads)
-    // ---------------------------------------------------------------------------
-    /** Submit an encrypted withdrawal request to the relayer. Not retried on failure. */
-    async submitWithdraw(data) {
-        const encryptedPayload = this.encrypt(data);
-        return this.request("POST", "/transact/withdra", {
-            body: { encryptedPayload },
-            retryable: false,
-        });
-    }
-    /** Submit an encrypted private transfer request. Not retried on failure. */
-    async submitPrivateTransfer(data) {
-        const encryptedPayload = this.encrypt(data);
-        return this.request("POST", "/transact/private-transfer", {
-            body: { encryptedPayload },
-            retryable: false,
-        });
-    }
-    /** Submit an encrypted private swap request. Not retried on failure. */
-    async submitPrivateSwap(data) {
-        const encryptedPayload = this.encrypt(data);
-        return this.request("POST", "/transact/private-swap", {
-            body: { encryptedPayload },
-            retryable: false,
-        });
-    }
-}
+// Backward-compatible entry point. Relayer responsibilities live in src/relayer.
+export * from "./relayer/index.js";

package/dist/esm/shield/alt.js

@@ -1,6 +1,6 @@
 import { ComputeBudgetProgram, PublicKey, SystemProgram, } from "@solana/web3.js";
 import { TOKEN_PROGRAM_ID, getAssociatedTokenAddress, getAssociatedTokenAddressSync, } from "@solana/spl-token";
-import { getGlobalConfigPda, getNoteTreePda, getPoolPdas, } from "../client.js";
+import { getGlobalConfigPda, getNoteTreePda, getPoolPdas, } from "../accounts/pdas.js";
 import { PRIVACY_POOL_PROGRAM_ID } from "../program.js";
 import { NATIVE_SOL_MINT } from "../config.js";
 import { ShieldError } from "./errors.js";

package/dist/esm/shield/errors.js

@@ -1,4 +1,4 @@
-import { parseOnChainError } from "../client.js";
+import { parseOnChainError } from "../accounts/errors.js";
 export class ShieldError extends Error {
     constructor(code, message, opts = {}) {
         super(message);

package/dist/esm/shield/finalize.js

@@ -1,6 +1,6 @@
 import * as anchor from "@coral-xyz/anchor";
 import { PRIVACY_POOL_IDL, PRIVACY_POOL_PROGRAM_ID } from "../program.js";
-import { encryptBlindMailboxNote } from "../utxo.js";
+import { encryptBlindMailboxNote } from "../notes/mailbox.js";
 import { bigIntToBytesBE } from "../poseidon.js";
 import { ShieldError } from "./errors.js";
 /**

package/dist/esm/shield/ix.d.ts

@@ -1,5 +1,5 @@
 import { PublicKey, TransactionInstruction } from "@solana/web3.js";
-import type { TransactionProofStruct } from "../proof.js";
+import type { TransactionProofStruct } from "../proofs/types.js";
 /**
  * `transact` instruction assembly, driven by the IDL rather than by a
  * hand-written account list.

package/dist/esm/shield/owner.js

@@ -1,5 +1,6 @@
 import { PublicKey } from "@solana/web3.js";
-import { VeiloApiError, VeiloRelayerClient } from "../relayer.js";
+import { VeiloRelayerClient } from "../relayer/client.js";
+import { VeiloApiError } from "../relayer/errors.js";
 import { ShieldError } from "./errors.js";
 /**
  * Owner resolution is a Veilo protocol service, not an integrator-selected
@@ -12,10 +13,7 @@ import { ShieldError } from "./errors.js";
  * inspectable. The two owner endpoints used below are intentionally public and
  * return public key material only.
  */
-const OWNER_RELAYER = new VeiloRelayerClient({
-    apiKey: "",
-    relayerPublicKey: "utVxnA7zax09qJCZ7UJsa8PAOoWLRcCwOkdxg/ZGmD4=",
-});
+const OWNER_RELAYER = new VeiloRelayerClient();
 /**
  * Resolve a shield recipient into the pair of keys that must belong to the same
  * account.

package/dist/esm/shield/ports.js

@@ -1,5 +1,5 @@
 import { createReadonlyVeiloProgram, PRIVACY_POOL_PROGRAM_ID } from "../program.js";
-import { getNoteTreePda, getPoolPdas } from "../client.js";
+import { getNoteTreePda, getPoolPdas } from "../accounts/pdas.js";
 import { MERKLE_TREE_DEPTH } from "../config.js";
 import { ShieldError } from "./errors.js";
 /**

package/dist/esm/shield/preflight.js

@@ -1,5 +1,5 @@
 import { createRevokeInstruction, getAccount, getAssociatedTokenAddress, TokenAccountNotFoundError, } from "@solana/spl-token";
-import { getPoolPdas } from "../client.js";
+import { getPoolPdas } from "../accounts/pdas.js";
 import { createReadonlyVeiloProgram, PRIVACY_POOL_PROGRAM_ID } from "../program.js";
 import { NATIVE_SOL_MINT } from "../config.js";
 import { ShieldError } from "./errors.js";

package/dist/esm/shield/shield.js

@@ -1,12 +1,13 @@
 import { ComputeBudgetProgram, PublicKey, SystemProgram, TransactionMessage, VersionedTransaction, } from "@solana/web3.js";
 import { TOKEN_PROGRAM_ID, getAssociatedTokenAddress } from "@solana/spl-token";
 import { PRIVACY_POOL_PROGRAM_ID } from "../program.js";
-import { getGlobalConfigPda, getNoteTreePda, getNullifierMarkerPda, getPoolPdas, } from "../client.js";
+import { getGlobalConfigPda, getNoteTreePda, getNullifierMarkerPda, getPoolPdas, } from "../accounts/pdas.js";
 import { MERKLE_TREE_DEPTH, NATIVE_SOL_MINT } from "../config.js";
 import { bigIntToBytesBE, bytesToBigIntBE, BN254_FR_MODULUS, } from "../poseidon.js";
 import { poseidonZeroChain } from "../merkle.js";
-import { createUTXO, createOwnedZeroUTXO, generateKeypair, } from "../utxo.js";
-import { computeExtDataHash, encodeSnarkjsProofToTransactionProof, prepareTransactionInputs, } from "../proof.js";
+import { createUTXO, createOwnedZeroUTXO, generateKeypair, } from "../notes/model.js";
+import { computeExtDataHash, prepareTransactionInputs, } from "../proofs/transaction.js";
+import { encodeSnarkjsProofToTransactionProof } from "../proofs/encoding.js";
 import { createCompactNoteCipher, emptyNoteCipher } from "../compactNote.js";
 import { buildTransactInstruction } from "./ix.js";
 import { sharedDepositAlt } from "./alt.js";

package/dist/esm/shield/types.d.ts

@@ -1,5 +1,5 @@
 import { AddressLookupTableAccount, Connection, PublicKey, VersionedTransaction } from "@solana/web3.js";
-import type { TransactionProofBuilder, TransactionProofStruct } from "../proof.js";
+import type { TransactionProofBuilder, TransactionProofStruct } from "../proofs/types.js";
 import type { CompactNoteCipher } from "../compactNote.js";
 /**
  * Who owns the resulting note. Both halves are required and neither is derived

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

@@ -0,0 +1,94 @@
+import type { Program, Idl } from "@coral-xyz/anchor";
+import { PublicKey, Transaction } from "@solana/web3.js";
+import type { ExtData, TransactionProofBuilder } from "../proofs/types.js";
+import type { SerializedUTXO } from "../notes/model.js";
+import { MerkleTree } from "../merkle.js";
+import { type NoteCiphers } from "../compactNote.js";
+/**
+ * Result of a deposit operation, produced by `DepositBuild.commit()` after the
+ * caller has successfully submitted the deposit transaction on-chain.
+ */
+export type DepositResult = {
+    /** The output UTXOs created by the deposit */
+    outputUTXOs: [SerializedUTXO, SerializedUTXO];
+    /** The leaf indices where the UTXOs were inserted */
+    leafIndices: [number, number];
+    /** The new Merkle root after insertion */
+    root: Uint8Array;
+};
+/**
+ * The return of `deposit()`. Instead of submitting the transaction itself,
+ * `deposit()` hands back an unsigned {@link Transaction} so the caller can
+ * sign it with whatever wallet they control (Solana wallet-adapter, Ledger,
+ * anchor NodeWallet, etc.) and submit it on their own terms.
+ *
+ * Usage pattern (browser / wallet-adapter):
+ *
+ *     const { transaction, commit } = await deposit({ ... });
+ *     const signed = await wallet.signTransaction(transaction);
+ *     const sig = await connection.sendRawTransaction(signed.serialize());
+ *     await connection.confirmTransaction(sig, "confirmed");
+ *     const result = commit();   // updates the local tree, returns DepositResult
+ */
+export type DepositBuild = {
+    /**
+     * Unsigned {@link Transaction} for the deposit. `feePayer` and
+     * `recentBlockhash` are already populated, so the caller only needs to sign
+     * and send.
+     */
+    transaction: Transaction;
+    /**
+     * Output UTXOs created by this deposit. Safe to read before submission —
+     * the commitment values are deterministic from the circuit inputs and do
+     * not depend on the on-chain result.
+     */
+    outputUTXOs: [SerializedUTXO, SerializedUTXO];
+    /**
+     * Inserts the two output commitments into the local {@link MerkleTree} and
+     * returns the receipt. Call this **only after** the on-chain transaction
+     * has been confirmed — deferring the insert keeps the local tree
+     * consistent with chain state if the submission fails.
+     *
+     * Calling `commit()` more than once is unsupported and will corrupt the
+     * local tree.
+     */
+    commit: () => DepositResult;
+};
+/**
+ * Build an unsigned deposit {@link Transaction} for the privacy pool.
+ *
+ * For deposits, we use zero input UTXOs (amount=0) and create output UTXOs
+ * with the deposit amount. `publicAmount` is positive. The caller is
+ * responsible for signing and submitting the returned transaction, and then
+ * calling `commit()` once it confirms.
+ *
+ * @param amount - Amount to deposit in lamports/token units
+ * @param recipientPubkey - UTXO public key that will own the deposited funds
+ * @param treeId - The tree ID to deposit into (defaults to 0)
+ */
+export declare function deposit<T extends Idl>(params: {
+    program: Program<T>;
+    /**
+     * Account that will pay for and sign the deposit transaction. Only
+     * `publicKey` is read — `deposit()` never touches a secret key. A browser
+     * wallet-adapter wallet, a Node `anchor.Wallet`, or a raw `Keypair` are all
+     * structurally acceptable.
+     */
+    depositor: {
+        publicKey: PublicKey;
+    };
+    amount: bigint;
+    mintAddress: PublicKey;
+    recipientPubkey: bigint;
+    tree: MerkleTree;
+    proofBuilder: TransactionProofBuilder;
+    treeId?: number;
+    extData?: Partial<ExtData>;
+    /** Solana wallet key used to make output note 0 recoverable from chain events. */
+    noteRecipientWallet?: PublicKey | Uint8Array;
+    /** Prebuilt recovery payload. Takes precedence over noteRecipientWallet. */
+    noteCiphers?: NoteCiphers | null;
+}): Promise<DepositBuild>;
+/**
+ * Result of a withdrawal operation.
+ */

package/dist/esm/transactions/deposit.js

@@ -0,0 +1,198 @@
+import * as anchor from "@coral-xyz/anchor";
+import { ComputeBudgetProgram, PublicKey, SystemProgram, } from "@solana/web3.js";
+import { TOKEN_PROGRAM_ID, getAssociatedTokenAddress } from "@solana/spl-token";
+import { computeExtDataHash, prepareTransactionInputs, } from "../proofs/transaction.js";
+import { encodeSnarkjsProofToTransactionProof } from "../proofs/encoding.js";
+import { createOwnedZeroUTXO, createUTXO, generateKeypair, } from "../notes/model.js";
+import { NATIVE_SOL_MINT } from "../config.js";
+import { bigIntToBytesBE } from "../poseidon.js";
+import { createNoteCiphers, } from "../compactNote.js";
+import { getGlobalConfigPda, getNoteTreePda, getNullifierMarkerPda, getPoolPdas, } from "../accounts/pdas.js";
+// Anchor is CJS and does not expose BN as a detectable Node ESM named export.
+const { BN } = anchor;
+/**
+ * Build an unsigned deposit {@link Transaction} for the privacy pool.
+ *
+ * For deposits, we use zero input UTXOs (amount=0) and create output UTXOs
+ * with the deposit amount. `publicAmount` is positive. The caller is
+ * responsible for signing and submitting the returned transaction, and then
+ * calling `commit()` once it confirms.
+ *
+ * @param amount - Amount to deposit in lamports/token units
+ * @param recipientPubkey - UTXO public key that will own the deposited funds
+ * @param treeId - The tree ID to deposit into (defaults to 0)
+ */
+export async function deposit(params) {
+    const { program, depositor, amount, mintAddress, recipientPubkey, tree, proofBuilder, treeId = 0, extData: partialExtData, noteRecipientWallet, noteCiphers, } = params;
+    if (amount <= 0n) {
+        throw new Error("Deposit amount must be positive");
+    }
+    // Create zero input UTXOs (for deposits, we don't spend any existing UTXOs)
+    const zeroKeypair0 = generateKeypair();
+    const zeroKeypair1 = generateKeypair();
+    const zeroInput0 = createOwnedZeroUTXO(zeroKeypair0.privateKey, mintAddress);
+    const zeroInput1 = createOwnedZeroUTXO(zeroKeypair1.privateKey, mintAddress);
+    // The circuit skips the Merkle proof check for zero-amount inputs (amount == 0
+    // causes `enabled = 0` in MerkleProofIfEnabled). So we provide a dummy path using
+    // the tree's pre-computed zero chain without inserting anything into the tree.
+    const dummyPath = tree.zeroes.slice(0, tree.depth);
+    const currentRoot = tree.root;
+    const inputUTXOs = [
+        {
+            ...zeroInput0,
+            pathIndex: 0,
+            pathElements: dummyPath,
+            privateKey: zeroKeypair0.privateKey,
+        },
+        {
+            ...zeroInput1,
+            pathIndex: 0,
+            pathElements: dummyPath,
+            privateKey: zeroKeypair1.privateKey,
+        },
+    ];
+    const outputUTXO0 = createUTXO({
+        amount: amount,
+        pubkey: recipientPubkey,
+        mintAddress,
+    });
+    const outputUTXO1 = createUTXO({
+        amount: 0n,
+        pubkey: generateKeypair().publicKey,
+        mintAddress,
+    });
+    const outputUTXOs = [
+        outputUTXO0,
+        outputUTXO1,
+    ];
+    const depositorPubkey = depositor.publicKey;
+    const extData = {
+        recipient: partialExtData?.recipient ?? depositorPubkey,
+        relayer: partialExtData?.relayer ?? depositorPubkey,
+        fee: partialExtData?.fee ?? 0n,
+        refund: partialExtData?.refund ?? 0n,
+        claimant: partialExtData?.claimant ?? SystemProgram.programId,
+    };
+    if (!extData.relayer.equals(depositorPubkey)) {
+        throw new Error("Deposit extData.relayer must be the signing depositor");
+    }
+    if (extData.fee !== 0n || extData.refund !== 0n) {
+        throw new Error("Deposits require extData fee and refund to be zero");
+    }
+    const circuitInputs = prepareTransactionInputs({
+        inputUTXOs,
+        outputUTXOs,
+        root: currentRoot,
+        publicAmount: amount, // Positive for deposits
+        extData,
+        mintAddress,
+    });
+    const rawProof = await proofBuilder(circuitInputs);
+    const proof = encodeSnarkjsProofToTransactionProof(rawProof);
+    const depositNoteCiphers = noteCiphers !== undefined
+        ? noteCiphers
+        : noteRecipientWallet
+            ? createNoteCiphers({
+                recipientWalletPubkey: noteRecipientWallet instanceof PublicKey
+                    ? noteRecipientWallet.toBytes()
+                    : noteRecipientWallet,
+                blinding: bigIntToBytesBE(outputUTXO0.blinding),
+                amount: outputUTXO0.amount,
+            }, null)
+            : null;
+    // -----------------------------------------------------------------------
+    // Build the transact instruction inline because deposits return an unsigned
+    // wallet-signable transaction while `transact()` submits with a Keypair.
+    //
+    // We intentionally don't reuse the `transact()` helper: it submits via
+    // anchor's `.rpc()` with `.signers([relayer])`, which assumes the caller
+    // holds a real Keypair. For deposit, we want to return an unsigned
+    // Transaction so the caller (typically a browser wallet) can sign it.
+    // -----------------------------------------------------------------------
+    const { config, vault, nullifiers } = getPoolPdas(program.programId, mintAddress);
+    const globalConfig = getGlobalConfigPda(program.programId);
+    const inputTree = getNoteTreePda(program.programId, mintAddress, treeId);
+    const outputTree = getNoteTreePda(program.programId, mintAddress, treeId);
+    const nullifierMarker0 = getNullifierMarkerPda(program.programId, mintAddress, circuitInputs.inputNullifiers[0]);
+    const nullifierMarker1 = getNullifierMarkerPda(program.programId, mintAddress, circuitInputs.inputNullifiers[1]);
+    const extDataHash = computeExtDataHash(extData);
+    const isNativeSol = mintAddress.equals(NATIVE_SOL_MINT);
+    let vaultTA;
+    let userTA;
+    let recipientTA;
+    let relayerTA;
+    if (!isNativeSol) {
+        vaultTA = await getAssociatedTokenAddress(mintAddress, vault, true);
+        userTA = await getAssociatedTokenAddress(mintAddress, depositorPubkey);
+        recipientTA = await getAssociatedTokenAddress(mintAddress, extData.recipient);
+        relayerTA = await getAssociatedTokenAddress(mintAddress, depositorPubkey);
+    }
+    const builtTx = await program.methods
+        .transact(Array.from(currentRoot), treeId, treeId, new BN(amount.toString()), Array.from(extDataHash), mintAddress, Array.from(circuitInputs.inputNullifiers[0]), Array.from(circuitInputs.inputNullifiers[1]), Array.from(circuitInputs.outputCommitments[0]), Array.from(circuitInputs.outputCommitments[1]), new BN(Math.floor(Date.now() / 1000) + 3600), // 1-hour window from build time
+    {
+        recipient: extData.recipient,
+        relayer: extData.relayer,
+        fee: new BN(extData.fee.toString()),
+        refund: new BN(extData.refund.toString()),
+        claimant: extData.claimant,
+    }, {
+        proofA: proof.proofA,
+        proofB: proof.proofB,
+        proofC: proof.proofC,
+    }, depositNoteCiphers
+        ? {
+            note0EphemeralKey: Array.from(depositNoteCiphers.note0EphemeralKey),
+            note0Encrypted: Array.from(depositNoteCiphers.note0Encrypted),
+            note0ViewTag: depositNoteCiphers.note0ViewTag,
+            note1EphemeralKey: Array.from(depositNoteCiphers.note1EphemeralKey),
+            note1Encrypted: Array.from(depositNoteCiphers.note1Encrypted),
+            note1ViewTag: depositNoteCiphers.note1ViewTag,
+        }
+        : null)
+        .accountsStrict({
+        config,
+        globalConfig,
+        vault,
+        inputTree,
+        outputTree,
+        nullifiers,
+        nullifierMarker0,
+        nullifierMarker1,
+        relayer: depositorPubkey,
+        recipient: extData.recipient,
+        vaultTokenAccount: vaultTA ?? depositorPubkey,
+        userTokenAccount: userTA ?? depositorPubkey,
+        recipientTokenAccount: recipientTA ?? extData.recipient,
+        relayerTokenAccount: relayerTA ?? depositorPubkey,
+        tokenProgram: isNativeSol ? SystemProgram.programId : TOKEN_PROGRAM_ID,
+        systemProgram: SystemProgram.programId,
+    })
+        .transaction();
+    // Add compute budget instruction for higher CU limit
+    const computeBudgetIx = ComputeBudgetProgram.setComputeUnitLimit({
+        units: 1000000,
+    });
+    builtTx.instructions.unshift(computeBudgetIx);
+    // Populate feePayer + recentBlockhash so the wallet only has to sign.
+    const provider = program.provider;
+    builtTx.feePayer = depositorPubkey;
+    const { blockhash } = await provider.connection.getLatestBlockhash();
+    builtTx.recentBlockhash = blockhash;
+    const commit = () => {
+        const { index: outIdx0 } = tree.insert(outputUTXOs[0].commitment);
+        const { index: outIdx1, root: newRoot } = tree.insert(outputUTXOs[1].commitment);
+        return {
+            outputUTXOs,
+            leafIndices: [outIdx0, outIdx1],
+            root: newRoot,
+        };
+    };
+    return {
+        transaction: builtTx,
+        outputUTXOs,
+        commit,
+    };
+}
+/**
+ * Result of a withdrawal operation.
+ */

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

@@ -0,0 +1,7 @@
+export * from "./transact.js";
+export * from "./deposit.js";
+export * from "./withdraw.js";
+export * from "./transfer.js";
+export * from "./swap.js";
+export { buildTransactInstruction as buildRawTransactInstruction, TRANSACT_ACCOUNT_NAMES, } from "../shield/ix.js";
+export type { TransactAccounts as RawTransactAccounts, TransactArgs as RawTransactArgs, } from "../shield/ix.js";

package/dist/esm/transactions/index.js

@@ -0,0 +1,7 @@
+export * from "./transact.js";
+export * from "./deposit.js";
+export * from "./withdraw.js";
+export * from "./transfer.js";
+export * from "./swap.js";
+// Raw IDL-correct builder for custom v0/ALT transaction composition.
+export { buildTransactInstruction as buildRawTransactInstruction, TRANSACT_ACCOUNT_NAMES, } from "../shield/ix.js";