@veilo/sdk-core 0.3.3 → 0.4.0

package/README.md

@@ -410,13 +410,49 @@ const signature: string = await transact({
   publicAmount: 0n,
   inputNullifiers: [nullifier1, nullifier2],
   outputCommitments: [output1.commitment, output2.commitment],
-  extData: { recipient, relayer: relayerPubkey, fee: 0n, refund: 0n },
+  extData: { recipient, relayer: relayerPubkey, fee: 0n, refund: 0n, claimant },
   proof,
 });
 ```
 
 ---
 
+#### Wallet-agnostic shielding
+
+`shield()` builds an unsigned v0 deposit transaction for any Solana wallet to
+sign. The signer funds the deposit, while the resulting private note can belong
+to a different Veilo user. The SDK never receives a wallet secret key and never
+broadcasts on the caller's behalf.
+
+```ts
+import {
+  createTransactionProver,
+  resolveShieldOwner,
+  shield,
+} from "@veilo/sdk-core";
+
+const owner = await resolveShieldOwner({ username: "alice" });
+const result = await shield({
+  connection,
+  amount: 5_000_000n,
+  mint: USDC_MINT,
+  owner,
+  signer: { publicKey: wallet.publicKey },
+  prover: createTransactionProver({ wasmPath, zkeyPath }),
+});
+
+const signed = await wallet.signTransaction(result.transaction);
+const signature = await connection.sendRawTransaction(signed.serialize());
+```
+
+Use `rebuild()` if the blockhash or deadline expires, and call
+`finalizeShield()` after confirmation to obtain the authoritative Merkle leaf
+index. See [SHIELD_INTEGRATION.md](./SHIELD_INTEGRATION.md) for the complete
+build → sign → submit → finalize flow, retry rules, owner-key invariant, and
+fee/rent requirements.
+
+---
+
 ### 4.8 Private Swaps
 
 Cross-pool private swaps via Jupiter/Raydium. For native SOL source pools the SDK automatically composes the required `fund_native_source` + `transact_swap` instructions into a single atomic transaction.
@@ -452,7 +488,7 @@ const signature: string = await transactSwap({
   },
   swapAmount: 1_000_000_000n,
   swapData: jupiterInstructionBytes, // Buffer
-  extData: { recipient, relayer: relayerPubkey, fee, refund: 0n },
+  extData: { recipient, relayer: relayerPubkey, fee, refund: 0n, claimant },
   sourceVaultTokenAccount,
   sourceMintAccount,
   destVaultTokenAccount,
@@ -542,7 +578,7 @@ import {
 const circuitInputs: TransactionCircuitInputs = prepareTransactionInputs({
   root: tree.root(),
   publicAmount: 1_000_000_000n,
-  extData: { recipient, relayer: relayerPubkey, fee: 0n, refund: 0n },
+  extData: { recipient, relayer: relayerPubkey, fee: 0n, refund: 0n, claimant },
   mintAddress: NATIVE_SOL_MINT,
   inputs: [input1, input2],
   outputs: [output1, output2],
@@ -563,6 +599,7 @@ const extDataHash = computeExtDataHash({
   relayer,
   fee: 0n,
   refund: 0n,
+  claimant,
 });
 
 // Compute swap param/data hashes (for swap circuit inputs)
@@ -1182,6 +1219,7 @@ await transact({
     relayer: relayerPubkey,
     fee: 0n,
     refund: 0n,
+    claimant: claimantPubkey,
   },
   proof,
 });
@@ -1213,6 +1251,7 @@ const circuitInputs: TransactionCircuitInputs = prepareTransactionInputs({
     relayer: relayerPubkey,
     fee: 0n,
     refund: 0n,
+    claimant: claimantPubkey,
   },
   mintAddress: NATIVE_SOL_MINT,
   inputs: [input1, input2],

package/SHIELD_INTEGRATION.md

@@ -0,0 +1,143 @@
+# Wallet-agnostic shielding
+
+`shield()` builds an unsigned Solana v0 transaction that moves funds from any
+signing wallet into Veilo's privacy pool. The wallet that pays and the Veilo
+account that owns the resulting private note are independent.
+
+This is a build API, like Jupiter's transaction APIs. The SDK proves, encrypts,
+and assembles. Your application asks its wallet to sign, submits the signed
+bytes, confirms them, and handles retry.
+
+## Security model
+
+- `signer.publicKey` is the transaction fee payer and public funding source.
+- `owner.veiloPublicKey` controls spending the private note.
+- `owner.noteViewingKey` controls detecting and decrypting the note during a
+  chain scan.
+- The SDK never receives a signer secret key.
+- The compact note cipher is embedded in the on-chain instruction, so note
+  recovery does not depend on a webhook or a later relayer callback.
+
+The two owner keys must belong to the same Veilo account. If they do not, the
+note is spendable but invisible to its owner. Always use `resolveShieldOwner()`;
+construct an owner manually only when you can prove the pairing yourself.
+
+## Complete flow
+
+```ts
+import { Connection, PublicKey } from "@solana/web3.js";
+import {
+  createTransactionProver,
+  finalizeShield,
+  mapShieldError,
+  rebuild,
+  resolveShieldOwner,
+  shield,
+} from "@veilo/sdk-core";
+
+const connection = new Connection(RPC_URL, "confirmed");
+const owner = await resolveShieldOwner({ username: "alice" });
+const prover = createTransactionProver({
+  wasmPath: TRANSACTION_WASM_URL,
+  zkeyPath: TRANSACTION_ZKEY_URL,
+});
+
+let result = await shield({
+  connection,
+  amount: 5_000_000n, // base units
+  mint: new PublicKey(USDC_MINT),
+  owner,
+  signer: { publicKey: wallet.publicKey },
+  prover,
+});
+
+async function signAndSubmit() {
+  const signed = await wallet.signTransaction(result.transaction);
+  const signature = await connection.sendRawTransaction(signed.serialize(), {
+    maxRetries: 0,
+  });
+
+  const confirmation = await connection.confirmTransaction(
+    {
+      signature,
+      blockhash: result.blockhash,
+      lastValidBlockHeight: result.lastValidBlockHeight,
+    },
+    "confirmed",
+  );
+  if (confirmation.value.err) throw confirmation.value.err;
+  return signature;
+}
+
+let signature: string;
+try {
+  signature = await signAndSubmit();
+} catch (cause) {
+  const error = mapShieldError(cause);
+  if (error.retryable !== "rebuild") throw error;
+
+  // Reuses the proof and note; only the blockhash and deadline are refreshed.
+  result = await rebuild(result, { connection });
+  signature = await signAndSubmit(); // the rebuilt transaction needs a new signature
+}
+
+const finalized = await finalizeShield({
+  connection,
+  signature,
+  note: result.note,
+  owner,
+  commitment: "finalized",
+});
+
+console.log(finalized.leafIndex, finalized.treeId);
+```
+
+`predictedLeafIndex` is informational only. Concurrent deposits can move the
+actual index before your transaction lands. Persist `finalized.leafIndex`, which
+comes from this transaction's `CommitmentEvent`.
+
+## Preflight and wallet UX
+
+Preflight runs before the 10–30 second proof and checks pool limits, token
+ownership and balance, ATA state, and the SOL needed by the transaction. If an
+SPL token account has any delegate—even with a delegated amount of zero—the
+program rejects it. `TOKEN_ACCOUNT_DELEGATED` includes a `remedy` with the
+`Revoke` instruction the wallet can sign before retrying.
+
+The wallet may describe the Veilo instruction as an unknown program. Show the
+amount and destination in your own review screen before opening the wallet so
+the signer can verify what it is authorizing.
+
+## SOL requirements
+
+The signer pays:
+
+- the amount itself for native SOL shields;
+- the normal transaction and priority fees; and
+- rent for two nullifier-marker accounts (about 0.00192 SOL at current rent).
+
+The program fixes the marker payer to the signer. A zero-SOL wallet therefore
+cannot use this path, even for an SPL token shield and even if another service
+would sponsor the transaction fee. This API does not provide a gasless mode.
+
+## Retry decisions
+
+Use `mapShieldError()` and branch on `retryable`:
+
+| Error | Retry class | Action |
+|---|---|---|
+| `BLOCKHASH_EXPIRED`, `DEADLINE_EXPIRED` | `rebuild` | Call `rebuild()`, sign again, submit again. |
+| `ROOT_STALE` | `reshield` | Call `shield()` again; a fresh proof is required. |
+| `NULLIFIER_COLLISION` | `none` | Treat as already submitted and check the original signature. |
+| Preflight and configuration errors | `none` | Correct the stated condition before retrying. |
+
+`ShieldProofCache` is public and JSON-serializable. `ShieldNote` is secret. Do
+not store or transmit the note in the clear, and do not bundle it with the proof
+cache merely because the cache is safe to move between processes.
+
+## Optional mailbox delivery
+
+`finalizeShield()` returns an encrypted `blob` suitable for `/notes/save`.
+Supplying `recipientWalletPublicKey` gives faster mailbox delivery and push
+notifications, but records a sender-to-recipient association at the relayer.
+Omitting it keeps discovery chain-only and preserves that privacy boundary.

package/config.d.ts

@@ -0,0 +1,2 @@
+// Stub for legacy resolvers — see config.js
+export * from "./dist/cjs/config.js";

package/config.js

@@ -0,0 +1,4 @@
+// Stub for legacy resolvers (TypeScript moduleResolution: "node", older bundlers)
+// that ignore the "exports" map. Modern resolvers use "./config" from package.json
+// exports and never reach this file.
+module.exports = require("./dist/cjs/config.js");

package/dist/cjs/client.d.ts

@@ -1,10 +1,10 @@
 import * as anchor from "@coral-xyz/anchor";
-import { Program, Idl } from "@coral-xyz/anchor";
+import type { Program, Idl } from "@coral-xyz/anchor";
 import { PublicKey, Transaction, Keypair } from "@solana/web3.js";
-import { TransactionProofStruct, TransactionProofBuilder, ExtData } from "./proof";
-import { SerializedUTXO, InputUTXO } from "./utxo";
-import { MerkleTree } from "./merkle";
-import { PrivacyConfigAccount } from "./config";
+import { TransactionProofStruct, TransactionProofBuilder, ExtData } from "./proof.js";
+import { SerializedUTXO, InputUTXO } from "./utxo.js";
+import { MerkleTree } from "./merkle.js";
+import { PrivacyConfigAccount } from "./config.js";
 /**
  * Get pool PDAs for a given mint address.
  * Note: All seeds use "v3" suffix.

package/dist/cjs/client.js

@@ -1,4 +1,37 @@
 "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.getPoolPdas = getPoolPdas;
 exports.getNoteTreePda = getNoteTreePda;
@@ -25,13 +58,17 @@ exports.updateGlobalConfig = updateGlobalConfig;
 exports.getSwapExecutorPda = getSwapExecutorPda;
 exports.fundNativeSource = fundNativeSource;
 exports.transactSwap = transactSwap;
-const anchor_1 = require("@coral-xyz/anchor");
+const anchor = __importStar(require("@coral-xyz/anchor"));
+// Pulled off the namespace rather than named-imported. @coral-xyz/anchor is CJS
+// with no `exports` map, and Node ESM's named-export detection cannot see `BN`
+// (it is re-exported from bn.js), so `import { BN }` throws at runtime under ESM.
+const { BN } = anchor;
 const web3_js_1 = require("@solana/web3.js");
 const spl_token_1 = require("@solana/spl-token");
-const proof_1 = require("./proof");
-const utxo_1 = require("./utxo");
-const config_1 = require("./config");
-const retry_1 = require("./retry");
+const proof_js_1 = require("./proof.js");
+const utxo_js_1 = require("./utxo.js");
+const config_js_1 = require("./config.js");
+const retry_js_1 = require("./retry.js");
 // -----------------------------------------------------------------------------
 // PDA Helpers
 // -----------------------------------------------------------------------------
@@ -282,7 +319,7 @@ async function initializePool(params) {
     const { config, vault, nullifiers } = getPoolPdas(program.programId, mintAddress);
     const noteTree = getNoteTreePda(program.programId, mintAddress, 0);
     await program.methods
-        .initialize(feeBps, mintAddress, minDepositAmount ? new anchor_1.BN(minDepositAmount.toString()) : null, maxDepositAmount ? new anchor_1.BN(maxDepositAmount.toString()) : null, minWithdrawAmount ? new anchor_1.BN(minWithdrawAmount.toString()) : null, maxWithdrawAmount ? new anchor_1.BN(maxWithdrawAmount.toString()) : null)
+        .initialize(feeBps, mintAddress, minDepositAmount ? new BN(minDepositAmount.toString()) : null, maxDepositAmount ? new BN(maxDepositAmount.toString()) : null, minWithdrawAmount ? new BN(minWithdrawAmount.toString()) : null, maxWithdrawAmount ? new BN(maxWithdrawAmount.toString()) : null)
         .accounts({
         config,
         vault,
@@ -305,7 +342,7 @@ async function updatePoolConfig(params) {
     const { program, admin, mintAddress, minDepositAmount, maxDepositAmount, minWithdrawAmount, maxWithdrawAmount, feeBps, feeErrorMarginBps, minWithdrawalFee, minSwapFee, swapFeeBps, } = params;
     const { config } = getPoolPdas(program.programId, mintAddress);
     await program.methods
-        .updatePoolConfig(mintAddress, minDepositAmount ? new anchor_1.BN(minDepositAmount.toString()) : null, maxDepositAmount ? new anchor_1.BN(maxDepositAmount.toString()) : null, minWithdrawAmount ? new anchor_1.BN(minWithdrawAmount.toString()) : null, maxWithdrawAmount ? new anchor_1.BN(maxWithdrawAmount.toString()) : null, feeBps != null ? new anchor_1.BN(feeBps) : null, minWithdrawalFee ? new anchor_1.BN(minWithdrawalFee.toString()) : null, feeErrorMarginBps != null ? new anchor_1.BN(feeErrorMarginBps) : null, minSwapFee ? new anchor_1.BN(minSwapFee.toString()) : null, swapFeeBps != null ? new anchor_1.BN(swapFeeBps) : null)
+        .updatePoolConfig(mintAddress, minDepositAmount ? new BN(minDepositAmount.toString()) : null, maxDepositAmount ? new BN(maxDepositAmount.toString()) : null, minWithdrawAmount ? new BN(minWithdrawAmount.toString()) : null, maxWithdrawAmount ? new BN(maxWithdrawAmount.toString()) : null, feeBps != null ? new BN(feeBps) : null, minWithdrawalFee ? new BN(minWithdrawalFee.toString()) : null, feeErrorMarginBps != null ? new BN(feeErrorMarginBps) : null, minSwapFee ? new BN(minSwapFee.toString()) : null, swapFeeBps != null ? new BN(swapFeeBps) : null)
         .accounts({
         config,
         admin: admin.publicKey,
@@ -412,8 +449,8 @@ async function transact(params) {
     // Nullifier markers are global (no tree_id) to prevent cross-tree double-spend
     const nullifierMarker0 = getNullifierMarkerPda(program.programId, mintAddress, inputNullifiers[0]);
     const nullifierMarker1 = getNullifierMarkerPda(program.programId, mintAddress, inputNullifiers[1]);
-    const extDataHash = (0, proof_1.computeExtDataHash)(extData);
-    const isNativeSol = mintAddress.equals(config_1.NATIVE_SOL_MINT);
+    const extDataHash = (0, proof_js_1.computeExtDataHash)(extData);
+    const isNativeSol = mintAddress.equals(config_js_1.NATIVE_SOL_MINT);
     // For SPL tokens, resolve token accounts
     let vaultTA = vaultTokenAccount;
     let userTA = userTokenAccount;
@@ -434,11 +471,11 @@ async function transact(params) {
         }
     }
     const tx = program.methods
-        .transact(Array.from(root), inputTreeId, outputTreeId, new anchor_1.BN(publicAmount.toString()), Array.from(extDataHash), mintAddress, Array.from(inputNullifiers[0]), Array.from(inputNullifiers[1]), Array.from(outputCommitments[0]), Array.from(outputCommitments[1]), new anchor_1.BN(deadline.toString()), {
+        .transact(Array.from(root), inputTreeId, outputTreeId, new BN(publicAmount.toString()), Array.from(extDataHash), mintAddress, Array.from(inputNullifiers[0]), Array.from(inputNullifiers[1]), Array.from(outputCommitments[0]), Array.from(outputCommitments[1]), new BN(deadline.toString()), {
         recipient: extData.recipient,
         relayer: extData.relayer,
-        fee: new anchor_1.BN(extData.fee.toString()),
-        refund: new anchor_1.BN(extData.refund.toString()),
+        fee: new BN(extData.fee.toString()),
+        refund: new BN(extData.refund.toString()),
     }, {
         proofA: proof.proofA,
         proofB: proof.proofB,
@@ -463,7 +500,7 @@ async function transact(params) {
         systemProgram: web3_js_1.SystemProgram.programId,
     })
         .signers([relayer]);
-    return (0, retry_1.withRpcRetry)(() => tx.rpc());
+    return (0, retry_js_1.withRpcRetry)(() => tx.rpc());
 }
 /**
  * Build an unsigned deposit {@link Transaction} for the privacy pool.
@@ -480,10 +517,10 @@ async function transact(params) {
 async function deposit(params) {
     const { program, depositor, amount, mintAddress, recipientPubkey, tree, proofBuilder, treeId = 0, extData: partialExtData, } = params;
     // Create a random keypair for the zero inputs (they don't matter since amount is 0)
-    const zeroKeypair = (0, utxo_1.generateKeypair)();
+    const zeroKeypair = (0, utxo_js_1.generateKeypair)();
     // Create zero input UTXOs (for deposits, we don't spend any existing UTXOs)
-    const zeroInput0 = (0, utxo_1.createOwnedZeroUTXO)(zeroKeypair.privateKey, mintAddress);
-    const zeroInput1 = (0, utxo_1.createOwnedZeroUTXO)(zeroKeypair.privateKey, mintAddress);
+    const zeroInput0 = (0, utxo_js_1.createOwnedZeroUTXO)(zeroKeypair.privateKey, mintAddress);
+    const zeroInput1 = (0, utxo_js_1.createOwnedZeroUTXO)(zeroKeypair.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.
@@ -503,12 +540,12 @@ async function deposit(params) {
             privateKey: zeroKeypair.privateKey,
         },
     ];
-    const outputUTXO0 = (0, utxo_1.createUTXO)({
+    const outputUTXO0 = (0, utxo_js_1.createUTXO)({
         amount: amount,
         pubkey: recipientPubkey,
         mintAddress,
     });
-    const outputUTXO1 = (0, utxo_1.createUTXO)({
+    const outputUTXO1 = (0, utxo_js_1.createUTXO)({
         amount: 0n,
         pubkey: recipientPubkey,
         mintAddress,
@@ -525,7 +562,7 @@ async function deposit(params) {
         refund: partialExtData?.refund ?? 0n,
         claimant: partialExtData?.claimant ?? web3_js_1.SystemProgram.programId,
     };
-    const circuitInputs = (0, proof_1.prepareTransactionInputs)({
+    const circuitInputs = (0, proof_js_1.prepareTransactionInputs)({
         inputUTXOs,
         outputUTXOs,
         root: currentRoot,
@@ -534,7 +571,7 @@ async function deposit(params) {
         mintAddress,
     });
     const rawProof = await proofBuilder(circuitInputs);
-    const proof = (0, proof_1.encodeSnarkjsProofToTransactionProof)(rawProof);
+    const proof = (0, proof_js_1.encodeSnarkjsProofToTransactionProof)(rawProof);
     // -----------------------------------------------------------------------
     // Build the transact instruction inline (duplicated from `transact()`).
     //
@@ -552,8 +589,8 @@ async function deposit(params) {
     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 = (0, proof_1.computeExtDataHash)(extData);
-    const isNativeSol = mintAddress.equals(config_1.NATIVE_SOL_MINT);
+    const extDataHash = (0, proof_js_1.computeExtDataHash)(extData);
+    const isNativeSol = mintAddress.equals(config_js_1.NATIVE_SOL_MINT);
     let vaultTA;
     let userTA;
     let recipientTA;
@@ -565,12 +602,12 @@ async function deposit(params) {
         relayerTA = await (0, spl_token_1.getAssociatedTokenAddress)(mintAddress, depositorPubkey);
     }
     const builtTx = await program.methods
-        .transact(Array.from(currentRoot), treeId, treeId, new anchor_1.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 anchor_1.BN(Math.floor(Date.now() / 1000) + 3600), // 1-hour window from build time
+        .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 anchor_1.BN(extData.fee.toString()),
-        refund: new anchor_1.BN(extData.refund.toString()),
+        fee: new BN(extData.fee.toString()),
+        refund: new BN(extData.refund.toString()),
     }, {
         proofA: proof.proofA,
         proofB: proof.proofB,
@@ -639,12 +676,12 @@ async function withdraw(params) {
     if (changeAmount < 0n) {
         throw new Error("Insufficient input balance for withdrawal");
     }
-    const changeUTXO = (0, utxo_1.createUTXO)({
+    const changeUTXO = (0, utxo_js_1.createUTXO)({
         amount: changeAmount,
         pubkey: changePubkey,
         mintAddress,
     });
-    const zeroUTXO = (0, utxo_1.createUTXO)({
+    const zeroUTXO = (0, utxo_js_1.createUTXO)({
         amount: 0n,
         pubkey: changePubkey,
         mintAddress,
@@ -659,7 +696,7 @@ async function withdraw(params) {
     };
     // publicAmount is negative for withdrawals
     const publicAmount = -withdrawAmount;
-    const circuitInputs = (0, proof_1.prepareTransactionInputs)({
+    const circuitInputs = (0, proof_js_1.prepareTransactionInputs)({
         inputUTXOs,
         outputUTXOs,
         root,
@@ -668,7 +705,7 @@ async function withdraw(params) {
         mintAddress,
     });
     const rawProof = await proofBuilder(circuitInputs);
-    const proof = (0, proof_1.encodeSnarkjsProofToTransactionProof)(rawProof);
+    const proof = (0, proof_js_1.encodeSnarkjsProofToTransactionProof)(rawProof);
     await transact({
         program,
         relayer,
@@ -710,12 +747,12 @@ async function privateTransfer(params) {
     if (totalInput !== totalOutput) {
         throw new Error(`Balance mismatch: inputs=${totalInput}, outputs=${totalOutput}`);
     }
-    const outputUTXO0 = (0, utxo_1.createUTXO)({
+    const outputUTXO0 = (0, utxo_js_1.createUTXO)({
         amount: outputAmounts[0],
         pubkey: outputPubkeys[0],
         mintAddress,
     });
-    const outputUTXO1 = (0, utxo_1.createUTXO)({
+    const outputUTXO1 = (0, utxo_js_1.createUTXO)({
         amount: outputAmounts[1],
         pubkey: outputPubkeys[1],
         mintAddress,
@@ -734,7 +771,7 @@ async function privateTransfer(params) {
     };
     // publicAmount is 0 for transfers
     const publicAmount = 0n;
-    const circuitInputs = (0, proof_1.prepareTransactionInputs)({
+    const circuitInputs = (0, proof_js_1.prepareTransactionInputs)({
         inputUTXOs,
         outputUTXOs,
         root,
@@ -743,7 +780,7 @@ async function privateTransfer(params) {
         mintAddress,
     });
     const rawProof = await proofBuilder(circuitInputs);
-    const proof = (0, proof_1.encodeSnarkjsProofToTransactionProof)(rawProof);
+    const proof = (0, proof_js_1.encodeSnarkjsProofToTransactionProof)(rawProof);
     await transact({
         program,
         relayer,
@@ -814,7 +851,7 @@ async function fundNativeSource(params) {
     const executor = getSwapExecutorPda(program.programId, sourceMint, destMint, inputNullifier0, relayer.publicKey);
     const executorSourceToken = await (0, spl_token_1.getAssociatedTokenAddress)(spl_token_1.NATIVE_MINT, executor, true);
     return program.methods
-        .fundNativeSource(sourceMint, destMint, Array.from(inputNullifier0), new anchor_1.BN(swapAmount.toString()))
+        .fundNativeSource(sourceMint, destMint, Array.from(inputNullifier0), new BN(swapAmount.toString()))
         .accounts({
         executor,
         executorSourceToken,
@@ -857,17 +894,17 @@ async function transactSwap(params) {
         proofB: proof.proofB,
         proofC: proof.proofC,
     }, Array.from(sourceRoot), sourceTreeId, sourceMint, Array.from(inputNullifiers[0]), Array.from(inputNullifiers[1]), destTreeId, destMint, Array.from(outputCommitments[0]), Array.from(outputCommitments[1]), {
-        minAmountOut: new anchor_1.BN(swapParams.minAmountOut.toString()),
-        deadline: new anchor_1.BN(swapParams.deadline.toString()),
+        minAmountOut: new BN(swapParams.minAmountOut.toString()),
+        deadline: new BN(swapParams.deadline.toString()),
         sourceMint: swapParams.sourceMint,
         destMint: swapParams.destMint,
-        destAmount: new anchor_1.BN(swapParams.destAmount.toString()),
+        destAmount: new BN(swapParams.destAmount.toString()),
         swapDataHash: Array.from(swapParams.swapDataHash),
-    }, new anchor_1.BN(swapAmount.toString()), swapData, {
+    }, new BN(swapAmount.toString()), swapData, {
         recipient: extData.recipient,
         relayer: extData.relayer,
-        fee: new anchor_1.BN(extData.fee.toString()),
-        refund: new anchor_1.BN(extData.refund.toString()),
+        fee: new BN(extData.fee.toString()),
+        refund: new BN(extData.refund.toString()),
     })
         .accounts({
         sourceConfig,
@@ -898,7 +935,7 @@ async function transactSwap(params) {
         .instruction();
     const provider = program.provider;
     const tx = new web3_js_1.Transaction();
-    if (sourceMint.equals(config_1.NATIVE_SOL_MINT)) {
+    if (sourceMint.equals(config_js_1.NATIVE_SOL_MINT)) {
         const fundIx = await fundNativeSource({
             program,
             relayer,
@@ -910,5 +947,5 @@ async function transactSwap(params) {
         tx.add(fundIx);
     }
     tx.add(swapIx);
-    return (0, retry_1.withRpcRetry)(() => provider.sendAndConfirm(tx, [relayer]));
+    return (0, retry_js_1.withRpcRetry)(() => provider.sendAndConfirm(tx, [relayer]));
 }

package/dist/cjs/compactNote.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Compact note ciphers — the 80-byte payload carried inside the on-chain
+ * `transact` instruction (`note_ciphers: Option<NoteCiphers>`) and re-emitted in
+ * `CommitmentEvent`.
+ *
+ * This is what makes a note recoverable from chain data alone: a recipient who
+ * was never told about a deposit can still find it by scanning `view_tag` and
+ * decrypting the blob. Without it, note delivery depends on someone calling the
+ * relayer, which a third-party integrator cannot be trusted to do.
+ *
+ * ## Byte-compatibility is load-bearing
+ *
+ * Four sibling implementations already exist (relayer-server, extension ×2,
+ * wallet-app). This is the canonical one, and it MUST agree with them byte for
+ * byte in both directions:
+ *
+ *   - disagree on encrypt → new notes are invisible to every existing client
+ *   - disagree on decrypt → the entire historical note corpus becomes unreadable
+ *
+ * Three details are easy to get wrong and are individually fatal:
+ *
+ *  1. The KDF is `nacl.hash(x).slice(0, 32)` — **truncated SHA-512**, despite the
+ *     sibling helper being named `sha256ForNotes`. See `kdfSHA512_256` in utxo.ts.
+ *  2. The ephemeral key published on-chain is **Ed25519**; it is converted to
+ *     X25519 only for the Diffie-Hellman. Scanners convert it back.
+ *  3. `viewTag` is the first byte of the hash of the **raw shared secret**, not of
+ *     the derived key. A wrong view tag makes every note invisible to the scan
+ *     loop, which rejects ~255/256 candidates on this byte alone.
+ *
+ * The ECDH primitives are imported from `utxo.ts` rather than reimplemented — a
+ * fifth independent Edwards→Montgomery implementation is exactly how the current
+ * drift risk between the four siblings arose.
+ *
+ * Verified against the siblings by `tests/compact-note.test.ts` (golden vectors)
+ * and `scripts/verify-compact-cipher-parity.mjs` (differential).
+ */
+/** Size of the on-chain compact blob: nonce[24] || secretbox(40-byte plaintext)[56]. */
+export declare const COMPACT_BLOB_LENGTH = 80;
+export type CompactNoteCipher = {
+    /** Ed25519 ephemeral public key, published on-chain. */
+    ephemeralPublicKey: Uint8Array;
+    /** 80 bytes: nonce[24] || ciphertext[56]. */
+    compactBlob: Uint8Array;
+    /** 1-byte scan filter. */
+    viewTag: number;
+};
+/**
+ * Test-only determinism hook. NOT part of the public contract — it exists so
+ * golden vectors can pin exact bytes against the sibling implementations, which
+ * is the only way to prove byte-compatibility rather than assume it.
+ *
+ * @internal
+ */
+export type CompactNoteDeterminism = {
+    ephemeralSeed: Uint8Array;
+    nonce: Uint8Array;
+};
+/**
+ * Encrypt a note's secret material to a recipient's Solana wallet key.
+ *
+ * The recipient does not need to be the signer of the transaction, or to have
+ * any prior relationship with the sender — this is what makes shielding to an
+ * arbitrary owner possible.
+ *
+ * @param recipientWalletPubkey 32-byte Ed25519 Solana wallet public key
+ * @param blinding              32-byte big-endian blinding factor
+ * @param amount                note amount in base units
+ */
+export declare function createCompactNoteCipher(recipientWalletPubkey: Uint8Array, blinding: Uint8Array, amount: bigint, 
+/** @internal */ __det?: CompactNoteDeterminism): CompactNoteCipher;
+/**
+ * Recover a note's blinding and amount from an on-chain compact cipher.
+ *
+ * Returns `null` when the blob was not encrypted to this key — the expected
+ * outcome for the overwhelming majority of candidates during a scan, so callers
+ * should filter on `viewTag` first (see {@link matchesViewTag}) and only attempt
+ * decryption on the ~1/256 that survive.
+ *
+ * @param walletSecretKey 32-byte Ed25519 seed or 64-byte secret key
+ */
+export declare function decryptCompactNoteCipher(walletSecretKey: Uint8Array, ephemeralPublicKey: Uint8Array, compactBlob: Uint8Array, precomputed?: {
+    sharedSecret?: Uint8Array;
+    x25519Private?: Uint8Array;
+}): {
+    blinding: Uint8Array;
+    amount: bigint;
+} | null;
+/**
+ * Cheap scan filter: does this on-chain cipher plausibly belong to us?
+ *
+ * Rejects ~255/256 candidates for the cost of one scalar multiplication and one
+ * hash, versus a full secretbox open. Hoist `x25519Private` across a scan loop
+ * with {@link toX25519Private}.
+ */
+export declare function matchesViewTag(walletSecretKey: Uint8Array, ephemeralPublicKey: Uint8Array, viewTag: number, precomputed?: {
+    x25519Private?: Uint8Array;
+}): {
+    matches: boolean;
+    sharedSecret: Uint8Array;
+};
+/**
+ * Convert an Ed25519 wallet secret key to its X25519 scalar once, for reuse
+ * across a scan loop.
+ */
+export declare function toX25519Private(walletSecretKey: Uint8Array): Uint8Array;
+/** The all-zero cipher the program treats as "no note here". */
+export declare function emptyNoteCipher(): CompactNoteCipher;