@veilo/sdk-core 0.4.0 → 0.6.0

package/dist/cjs/shield/owner.js

@@ -3,8 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveShieldOwner = resolveShieldOwner;
 exports.unsafeShieldOwner = unsafeShieldOwner;
 const web3_js_1 = require("@solana/web3.js");
-const relayer_js_1 = require("../relayer.js");
-const errors_js_1 = require("./errors.js");
+const client_js_1 = require("../relayer/client.js");
+const errors_js_1 = require("../relayer/errors.js");
+const errors_js_2 = require("./errors.js");
 /**
  * Owner resolution is a Veilo protocol service, not an integrator-selected
  * transport. Keep the production endpoint and public encryption key inside the
@@ -16,10 +17,7 @@ const errors_js_1 = require("./errors.js");
  * inspectable. The two owner endpoints used below are intentionally public and
  * return public key material only.
  */
-const OWNER_RELAYER = new relayer_js_1.VeiloRelayerClient({
-    apiKey: "",
-    relayerPublicKey: "utVxnA7zax09qJCZ7UJsa8PAOoWLRcCwOkdxg/ZGmD4=",
-});
+const OWNER_RELAYER = new client_js_1.VeiloRelayerClient();
 /**
  * Resolve a shield recipient into the pair of keys that must belong to the same
  * account.
@@ -54,13 +52,13 @@ async function resolveShieldOwner(target) {
         // public and idempotent, and returns only the Poseidon spend key; the
         // address we were given is the matching note-viewing key.
         if ("publicKey" in target &&
-            (e?.status === 404 || (e instanceof relayer_js_1.VeiloApiError && e.status === 404))) {
+            (e?.status === 404 || (e instanceof errors_js_1.VeiloApiError && e.status === 404))) {
             const wallet = typeof target.publicKey === "string"
                 ? new web3_js_1.PublicKey(target.publicKey)
                 : target.publicKey;
             const provisioned = await OWNER_RELAYER.preRegisterKey(wallet.toBase58());
             if (!provisioned?.veiloPublicKey) {
-                throw new errors_js_1.ShieldError("UNKNOWN", "The relayer pre-registered the recipient but returned no Veilo public key.", { context: { publicKey: wallet.toBase58(), response: provisioned }, cause: e });
+                throw new errors_js_2.ShieldError("UNKNOWN", "The relayer pre-registered the recipient but returned no Veilo public key.", { context: { publicKey: wallet.toBase58(), response: provisioned }, cause: e });
             }
             return {
                 veiloPublicKey: BigInt(provisioned.veiloPublicKey),
@@ -75,7 +73,7 @@ async function resolveShieldOwner(target) {
         if (e?.body?.preRegistered ||
             e?.details?.preRegistered ||
             /preregistered/i.test(String(e?.message ?? ""))) {
-            throw new errors_js_1.ShieldError("UNKNOWN", `"${"username" in target ? target.username : "that account"}" is pre-registered ` +
+            throw new errors_js_2.ShieldError("UNKNOWN", `"${"username" in target ? target.username : "that account"}" is pre-registered ` +
                 `and cannot be resolved by username. Resolve it by Solana address instead — ` +
                 `resolveShieldOwner({ publicKey }).`, { context: { preRegistered: true }, cause: e });
         }
@@ -84,7 +82,7 @@ async function resolveShieldOwner(target) {
     const veiloPublicKeyRaw = response?.veiloPublicKey;
     const walletRaw = response?.pubK;
     if (!veiloPublicKeyRaw || !walletRaw) {
-        throw new errors_js_1.ShieldError("UNKNOWN", `The relayer did not return both keys for this recipient ` +
+        throw new errors_js_2.ShieldError("UNKNOWN", `The relayer did not return both keys for this recipient ` +
             `(veiloPublicKey=${!!veiloPublicKeyRaw}, pubK=${!!walletRaw}). ` +
             `Shielding without both would create a note the owner cannot find.`, { context: { response } });
     }
@@ -93,7 +91,7 @@ async function resolveShieldOwner(target) {
         !noteViewingKey.equals(typeof target.publicKey === "string"
             ? new web3_js_1.PublicKey(target.publicKey)
             : target.publicKey)) {
-        throw new errors_js_1.ShieldError("UNKNOWN", "The Veilo owner service returned a different wallet than the one requested. " +
+        throw new errors_js_2.ShieldError("UNKNOWN", "The Veilo owner service returned a different wallet than the one requested. " +
             "Shielding was stopped to prevent creating a note for the wrong recipient.", {
             context: {
                 requested: typeof target.publicKey === "string"

package/dist/cjs/shield/ports.js

@@ -5,7 +5,7 @@ exports.staticTreeSource = staticTreeSource;
 exports.memoryCache = memoryCache;
 exports.noCache = noCache;
 const program_js_1 = require("../program.js");
-const client_js_1 = require("../client.js");
+const pdas_js_1 = require("../accounts/pdas.js");
 const config_js_1 = require("../config.js");
 const errors_js_1 = require("./errors.js");
 /**
@@ -36,7 +36,7 @@ function onChainTreeSource(connection, programId = program_js_1.PRIVACY_POOL_PRO
     return {
         async getDepositTarget(mint) {
             const program = (0, program_js_1.createReadonlyVeiloProgram)(connection);
-            const { config } = (0, client_js_1.getPoolPdas)(programId, mint);
+            const { config } = (0, pdas_js_1.getPoolPdas)(programId, mint);
             const cfg = await program.account.privacyConfig.fetch(config);
             const numTrees = Number(cfg.numTrees);
             if (!Number.isInteger(numTrees) || numTrees <= 0) {
@@ -44,7 +44,7 @@ function onChainTreeSource(connection, programId = program_js_1.PRIVACY_POOL_PRO
             }
             // Fetch every tree in one RPC call. The older getBestTreeForDeposit path
             // fetched them serially, then fetched the chosen trees a second time.
-            const treePdas = Array.from({ length: numTrees }, (_, treeId) => (0, client_js_1.getNoteTreePda)(programId, mint, treeId));
+            const treePdas = Array.from({ length: numTrees }, (_, treeId) => (0, pdas_js_1.getNoteTreePda)(programId, mint, treeId));
             const infos = await connection.getMultipleAccountsInfo(treePdas, {
                 commitment: "confirmed",
             });

package/dist/cjs/shield/preflight.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.preflightShield = preflightShield;
 const spl_token_1 = require("@solana/spl-token");
-const client_js_1 = require("../client.js");
+const pdas_js_1 = require("../accounts/pdas.js");
 const program_js_1 = require("../program.js");
 const config_js_1 = require("../config.js");
 const errors_js_1 = require("./errors.js");
@@ -27,7 +27,7 @@ async function preflightShield(params) {
     // --- Pool state ------------------------------------------------------------
     if (!options.skipPoolState) {
         const program = (0, program_js_1.createReadonlyVeiloProgram)(connection);
-        const { config } = (0, client_js_1.getPoolPdas)(programId, mint);
+        const { config } = (0, pdas_js_1.getPoolPdas)(programId, mint);
         let cfg;
         try {
             cfg = await program.account.privacyConfig.fetch(config);
@@ -103,7 +103,7 @@ async function preflightShield(params) {
         }
         // The vault's ATA must already exist — the program requires the canonical
         // one and will not create it.
-        const { vault } = (0, client_js_1.getPoolPdas)(programId, mint);
+        const { vault } = (0, pdas_js_1.getPoolPdas)(programId, mint);
         const vaultAta = await (0, spl_token_1.getAssociatedTokenAddress)(mint, vault, true);
         const vaultInfo = await connection.getAccountInfo(vaultAta);
         if (!vaultInfo) {

package/dist/cjs/shield/shield.js

@@ -8,14 +8,15 @@ exports.deserializeProofCache = deserializeProofCache;
 const web3_js_1 = require("@solana/web3.js");
 const spl_token_1 = require("@solana/spl-token");
 const program_js_1 = require("../program.js");
-const client_js_1 = require("../client.js");
+const pdas_js_1 = require("../accounts/pdas.js");
 const config_js_1 = require("../config.js");
 const poseidon_js_1 = require("../poseidon.js");
 Object.defineProperty(exports, "bytesToBigIntBE", { enumerable: true, get: function () { return poseidon_js_1.bytesToBigIntBE; } });
 Object.defineProperty(exports, "BN254_FR_MODULUS", { enumerable: true, get: function () { return poseidon_js_1.BN254_FR_MODULUS; } });
 const merkle_js_1 = require("../merkle.js");
-const utxo_js_1 = require("../utxo.js");
-const proof_js_1 = require("../proof.js");
+const model_js_1 = require("../notes/model.js");
+const transaction_js_1 = require("../proofs/transaction.js");
+const encoding_js_1 = require("../proofs/encoding.js");
 const compactNote_js_1 = require("../compactNote.js");
 const ix_js_1 = require("./ix.js");
 const alt_js_1 = require("./alt.js");
@@ -114,14 +115,14 @@ async function shield(params) {
     // --- 3. Outputs ------------------------------------------------------------
     // Output 0 carries the value and is owned by the recipient. Output 1 is a
     // zero-value dummy the 2-in-2-out circuit requires.
-    const outputNote = (0, utxo_js_1.createUTXO)({
+    const outputNote = (0, model_js_1.createUTXO)({
         amount,
         pubkey: owner.veiloPublicKey,
         mintAddress: mint,
     });
-    const dummyOutput = (0, utxo_js_1.createUTXO)({
+    const dummyOutput = (0, model_js_1.createUTXO)({
         amount: 0n,
-        pubkey: (0, utxo_js_1.generateKeypair)().publicKey,
+        pubkey: (0, model_js_1.generateKeypair)().publicKey,
         mintAddress: mint,
     });
     // --- 4. Dummy inputs -------------------------------------------------------
@@ -130,8 +131,8 @@ async function shield(params) {
     // blinding randomness; two keys make it structural.
     const zeroChain = (0, merkle_js_1.poseidonZeroChain)(22).slice(0, 22);
     const dummyInputs = [
-        toDummyInput((0, utxo_js_1.createOwnedZeroUTXO)((0, utxo_js_1.generateKeypair)().privateKey, mint), zeroChain),
-        toDummyInput((0, utxo_js_1.createOwnedZeroUTXO)((0, utxo_js_1.generateKeypair)().privateKey, mint), zeroChain),
+        toDummyInput((0, model_js_1.createOwnedZeroUTXO)((0, model_js_1.generateKeypair)().privateKey, mint), zeroChain),
+        toDummyInput((0, model_js_1.createOwnedZeroUTXO)((0, model_js_1.generateKeypair)().privateKey, mint), zeroChain),
     ];
     // --- 5. ExtData ------------------------------------------------------------
     // For a deposit these slots carry no payment semantics — no fee is taken and
@@ -144,9 +145,9 @@ async function shield(params) {
         refund: 0n,
         claimant: web3_js_1.SystemProgram.programId,
     };
-    const extDataHash = (0, proof_js_1.computeExtDataHash)(extData);
+    const extDataHash = (0, transaction_js_1.computeExtDataHash)(extData);
     // --- 6. Prove --------------------------------------------------------------
-    const circuitInputs = (0, proof_js_1.prepareTransactionInputs)({
+    const circuitInputs = (0, transaction_js_1.prepareTransactionInputs)({
         inputUTXOs: dummyInputs,
         outputUTXOs: [outputNote, dummyOutput],
         root: target.inputRoot,
@@ -156,7 +157,7 @@ async function shield(params) {
     });
     let proof;
     try {
-        proof = (0, proof_js_1.encodeSnarkjsProofToTransactionProof)(await prover(circuitInputs));
+        proof = (0, encoding_js_1.encodeSnarkjsProofToTransactionProof)(await prover(circuitInputs));
     }
     catch (e) {
         throw (0, errors_js_1.mapShieldError)(e);
@@ -176,8 +177,8 @@ async function shield(params) {
         outputTreeId: target.outputTreeId,
         inputNullifiers: circuitInputs.inputNullifiers,
         vaultTokenAccount: isToken
-            ? await (0, spl_token_1.getAssociatedTokenAddress)(mint, (0, client_js_1.getPoolPdas)(programId, mint).vault, true)
-            : (0, client_js_1.getPoolPdas)(programId, mint).vault,
+            ? await (0, spl_token_1.getAssociatedTokenAddress)(mint, (0, pdas_js_1.getPoolPdas)(programId, mint).vault, true)
+            : (0, pdas_js_1.getPoolPdas)(programId, mint).vault,
         isToken,
     });
     // --- 9. Cache everything needed to rebuild ---------------------------------
@@ -452,16 +453,16 @@ function toDummyInput(utxo, zeroChain) {
 }
 function resolveTransactAccounts(params) {
     const { programId, mint, signer } = params;
-    const { config, vault, nullifiers } = (0, client_js_1.getPoolPdas)(programId, mint);
+    const { config, vault, nullifiers } = (0, pdas_js_1.getPoolPdas)(programId, mint);
     return {
         config,
-        global_config: (0, client_js_1.getGlobalConfigPda)(programId),
+        global_config: (0, pdas_js_1.getGlobalConfigPda)(programId),
         vault,
-        input_tree: (0, client_js_1.getNoteTreePda)(programId, mint, params.inputTreeId),
-        output_tree: (0, client_js_1.getNoteTreePda)(programId, mint, params.outputTreeId),
+        input_tree: (0, pdas_js_1.getNoteTreePda)(programId, mint, params.inputTreeId),
+        output_tree: (0, pdas_js_1.getNoteTreePda)(programId, mint, params.outputTreeId),
         nullifiers,
-        nullifier_marker_0: (0, client_js_1.getNullifierMarkerPda)(programId, mint, params.inputNullifiers[0]),
-        nullifier_marker_1: (0, client_js_1.getNullifierMarkerPda)(programId, mint, params.inputNullifiers[1]),
+        nullifier_marker_0: (0, pdas_js_1.getNullifierMarkerPda)(programId, mint, params.inputNullifiers[0]),
+        nullifier_marker_1: (0, pdas_js_1.getNullifierMarkerPda)(programId, mint, params.inputNullifiers[1]),
         relayer: signer,
         // For a deposit nothing is withdrawn, so `recipient` is just the signer.
         // Pointing the unused token slots at accounts already in the transaction

package/dist/cjs/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/cjs/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/cjs/transactions/deposit.js

@@ -0,0 +1,234 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deposit = deposit;
+const anchor = __importStar(require("@coral-xyz/anchor"));
+const web3_js_1 = require("@solana/web3.js");
+const spl_token_1 = require("@solana/spl-token");
+const transaction_js_1 = require("../proofs/transaction.js");
+const encoding_js_1 = require("../proofs/encoding.js");
+const model_js_1 = require("../notes/model.js");
+const config_js_1 = require("../config.js");
+const poseidon_js_1 = require("../poseidon.js");
+const compactNote_js_1 = require("../compactNote.js");
+const pdas_js_1 = require("../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)
+ */
+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 = (0, model_js_1.generateKeypair)();
+    const zeroKeypair1 = (0, model_js_1.generateKeypair)();
+    const zeroInput0 = (0, model_js_1.createOwnedZeroUTXO)(zeroKeypair0.privateKey, mintAddress);
+    const zeroInput1 = (0, model_js_1.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 = (0, model_js_1.createUTXO)({
+        amount: amount,
+        pubkey: recipientPubkey,
+        mintAddress,
+    });
+    const outputUTXO1 = (0, model_js_1.createUTXO)({
+        amount: 0n,
+        pubkey: (0, model_js_1.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 ?? web3_js_1.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 = (0, transaction_js_1.prepareTransactionInputs)({
+        inputUTXOs,
+        outputUTXOs,
+        root: currentRoot,
+        publicAmount: amount, // Positive for deposits
+        extData,
+        mintAddress,
+    });
+    const rawProof = await proofBuilder(circuitInputs);
+    const proof = (0, encoding_js_1.encodeSnarkjsProofToTransactionProof)(rawProof);
+    const depositNoteCiphers = noteCiphers !== undefined
+        ? noteCiphers
+        : noteRecipientWallet
+            ? (0, compactNote_js_1.createNoteCiphers)({
+                recipientWalletPubkey: noteRecipientWallet instanceof web3_js_1.PublicKey
+                    ? noteRecipientWallet.toBytes()
+                    : noteRecipientWallet,
+                blinding: (0, poseidon_js_1.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 } = (0, pdas_js_1.getPoolPdas)(program.programId, mintAddress);
+    const globalConfig = (0, pdas_js_1.getGlobalConfigPda)(program.programId);
+    const inputTree = (0, pdas_js_1.getNoteTreePda)(program.programId, mintAddress, treeId);
+    const outputTree = (0, pdas_js_1.getNoteTreePda)(program.programId, mintAddress, treeId);
+    const nullifierMarker0 = (0, pdas_js_1.getNullifierMarkerPda)(program.programId, mintAddress, circuitInputs.inputNullifiers[0]);
+    const nullifierMarker1 = (0, pdas_js_1.getNullifierMarkerPda)(program.programId, mintAddress, circuitInputs.inputNullifiers[1]);
+    const extDataHash = (0, transaction_js_1.computeExtDataHash)(extData);
+    const isNativeSol = mintAddress.equals(config_js_1.NATIVE_SOL_MINT);
+    let vaultTA;
+    let userTA;
+    let recipientTA;
+    let relayerTA;
+    if (!isNativeSol) {
+        vaultTA = await (0, spl_token_1.getAssociatedTokenAddress)(mintAddress, vault, true);
+        userTA = await (0, spl_token_1.getAssociatedTokenAddress)(mintAddress, depositorPubkey);
+        recipientTA = await (0, spl_token_1.getAssociatedTokenAddress)(mintAddress, extData.recipient);
+        relayerTA = await (0, spl_token_1.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 ? web3_js_1.SystemProgram.programId : spl_token_1.TOKEN_PROGRAM_ID,
+        systemProgram: web3_js_1.SystemProgram.programId,
+    })
+        .transaction();
+    // Add compute budget instruction for higher CU limit
+    const computeBudgetIx = web3_js_1.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/cjs/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/cjs/transactions/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRANSACT_ACCOUNT_NAMES = exports.buildRawTransactInstruction = void 0;
+__exportStar(require("./transact.js"), exports);
+__exportStar(require("./deposit.js"), exports);
+__exportStar(require("./withdraw.js"), exports);
+__exportStar(require("./transfer.js"), exports);
+__exportStar(require("./swap.js"), exports);
+// Raw IDL-correct builder for custom v0/ALT transaction composition.
+var ix_js_1 = require("../shield/ix.js");
+Object.defineProperty(exports, "buildRawTransactInstruction", { enumerable: true, get: function () { return ix_js_1.buildTransactInstruction; } });
+Object.defineProperty(exports, "TRANSACT_ACCOUNT_NAMES", { enumerable: true, get: function () { return ix_js_1.TRANSACT_ACCOUNT_NAMES; } });