@cloak.dev/sdk 0.2.1 → 0.2.2-staging.33f11a2

package/dist/index.js

@@ -621,7 +621,7 @@ function parseStrictViewingKeyChallenge(response, userPubkey, viewingKeyHex) {
 
 // src/config/relay.ts
 var CLOAK_PRODUCTION_RELAY_URL = "https://api.cloak.ag";
-var RELAY_ORIGIN_ALLOWLIST = [CLOAK_PRODUCTION_RELAY_URL];
+var RELAY_ORIGIN_ALLOWLIST = ["https://staging-api.cloak.ag"];
 var ABSOLUTE_URL = /^[a-z][a-z0-9+.-]*:\/\//i;
 var LOOPBACK_IPV4 = /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
 var THIS_NETWORK_IPV4 = /^0\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
@@ -4533,6 +4533,91 @@ async function matchDepositNote(params) {
   return { ...secrets, amount, mintAddress, commitment: candidate, noteSalt };
 }
 
+// src/notes/change-note.ts
+import { blake3 as blake35 } from "@noble/hashes/blake3";
+var CHANGE_NOTE_DOMAIN = new TextEncoder().encode("cloak_change_note_v1");
+var CHANGE_BLINDING_INFO = new TextEncoder().encode("blinding");
+var MAX_OUTPUT_INDEX = 1;
+var MAX_CHAIN_NOTE_SALT2 = (1n << BigInt(CHAIN_NOTE_SALT_BITS)) - 1n;
+function saltToBytes2(noteSalt) {
+  if (typeof noteSalt !== "bigint" || noteSalt <= 0n || noteSalt > MAX_CHAIN_NOTE_SALT2) {
+    throw new Error(`noteSalt must be a positive ${CHAIN_NOTE_SALT_BITS}-bit value`);
+  }
+  const out = new Uint8Array(32);
+  let v = noteSalt;
+  for (let i = 31; i >= 0; i--) {
+    out[i] = Number(v & 0xffn);
+    v >>= 8n;
+  }
+  return out;
+}
+function toFieldSecret3(bytes) {
+  let value = 0n;
+  for (let i = 0; i < 32; i++) value = value << 8n | BigInt(bytes[i]);
+  const reduced = value % (BN254_MODULUS >> 4n);
+  return reduced === 0n ? 1n : reduced;
+}
+function randomChangeNoteSalt() {
+  const bytes = randomBytes(12);
+  let v = 0n;
+  for (const b of bytes) v = v << 8n | BigInt(b);
+  return v === 0n ? 1n : v;
+}
+function deriveChangeNoteBlinding(viewingKeyNk, noteSalt, outputIndex) {
+  if (!viewingKeyNk || !(viewingKeyNk instanceof Uint8Array) || viewingKeyNk.length !== 32) {
+    throw new Error("viewingKeyNk must be 32 bytes");
+  }
+  if (!Number.isInteger(outputIndex) || outputIndex < 0 || outputIndex > MAX_OUTPUT_INDEX) {
+    throw new Error(`outputIndex must be 0..${MAX_OUTPUT_INDEX}`);
+  }
+  const salt = saltToBytes2(noteSalt);
+  const preimage = new Uint8Array(
+    CHANGE_NOTE_DOMAIN.length + viewingKeyNk.length + salt.length + 1 + CHANGE_BLINDING_INFO.length
+  );
+  let off = 0;
+  preimage.set(CHANGE_NOTE_DOMAIN, off);
+  off += CHANGE_NOTE_DOMAIN.length;
+  preimage.set(viewingKeyNk, off);
+  off += viewingKeyNk.length;
+  preimage.set(salt, off);
+  off += salt.length;
+  preimage[off] = outputIndex;
+  off += 1;
+  preimage.set(CHANGE_BLINDING_INFO, off);
+  return toFieldSecret3(blake35(preimage));
+}
+async function createRecoverableChangeUtxo(amount, keypair, viewingKeyNk, mintAddress = NATIVE_SOL_MINT, noteSalt = randomChangeNoteSalt(), outputIndex = 0) {
+  if (typeof amount !== "bigint" || amount <= 0n) {
+    throw new Error("amount must be a positive bigint");
+  }
+  const blinding = deriveChangeNoteBlinding(viewingKeyNk, noteSalt, outputIndex);
+  const utxo = { amount, keypair, blinding, mintAddress };
+  utxo.commitment = await computeCommitment(utxo);
+  return { utxo, noteSalt };
+}
+function normalizeCommitment2(value) {
+  if (typeof value === "bigint") return value;
+  if (typeof value !== "string") return null;
+  const clean = value.startsWith("0x") ? value.slice(2) : value;
+  if (!/^[0-9a-fA-F]{1,64}$/.test(clean)) return null;
+  return BigInt("0x" + clean);
+}
+async function matchChangeNote(params) {
+  const { viewingKeyNk, noteSalt, amount, keypair, mintAddress, outputIndex, outputCommitments } = params;
+  if (typeof amount !== "bigint" || amount <= 0n) return null;
+  if (!keypair || typeof keypair.publicKey !== "bigint" || keypair.publicKey === 0n) return null;
+  let blinding;
+  try {
+    blinding = deriveChangeNoteBlinding(viewingKeyNk, noteSalt, outputIndex);
+  } catch {
+    return null;
+  }
+  const candidate = await computeCommitment({ amount, keypair, blinding, mintAddress });
+  const published = (outputCommitments ?? []).map(normalizeCommitment2).filter((value) => value !== null);
+  if (!published.some((value) => value === candidate)) return null;
+  return { keypair, blinding, amount, mintAddress, commitment: candidate, noteSalt };
+}
+
 // src/flows/transact.ts
 import { buildPoseidon as buildPoseidon2 } from "circomlibjs";
 import nacl6 from "tweetnacl";
@@ -5114,6 +5199,84 @@ async function fetchAltAddressesFromRelayHealth(relayUrl) {
     return [];
   }
 }
+async function fetchSupplementalAltFromRelay(relayUrl, params) {
+  const body = JSON.stringify({
+    mint: params.mint.toBase58(),
+    nullifiers: [
+      Buffer.from(params.nullifiers[0]).toString("hex"),
+      Buffer.from(params.nullifiers[1]).toString("hex")
+    ],
+    bind0: Buffer.from(params.bind0).toString("hex"),
+    depositor: params.depositor.toBase58()
+  });
+  let response;
+  try {
+    response = await relayFetch(`${relayUrl.replace(/\/$/, "")}/supplemental-alt`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`Supplemental ALT request to the relay failed: ${msg}`);
+  }
+  if (!response.ok) {
+    let text = "";
+    try {
+      text = await response.text();
+    } catch {
+    }
+    throw new Error(
+      `Supplemental ALT request failed (${response.status})${text ? `: ${text}` : ""}`
+    );
+  }
+  let json;
+  try {
+    json = await response.json();
+  } catch {
+    throw new Error("Supplemental ALT response was not valid JSON");
+  }
+  const table = json?.table;
+  if (typeof table !== "string" || table.length === 0) {
+    throw new Error("Supplemental ALT response is missing a 'table' address");
+  }
+  try {
+    return new PublicKey8(table);
+  } catch {
+    throw new Error(`Supplemental ALT response 'table' is not a valid public key: ${table}`);
+  }
+}
+async function resolveRelaySupplementalAlt(connection, table, expected, pollOpts) {
+  const pollIntervalMs = pollOpts?.pollIntervalMs ?? 150;
+  const timeoutMs = pollOpts?.timeoutMs ?? 5e3;
+  const expectedB58 = expected.map((pk) => pk.toBase58());
+  const deadline = Date.now() + timeoutMs;
+  for (; ; ) {
+    const result = await connection.getAddressLookupTable(table, { commitment: "confirmed" });
+    if (!result.value) {
+      throw new Error(`Supplemental ALT ${table.toBase58()} could not be fetched from the RPC.`);
+    }
+    const account = result.value;
+    const present = new Set(account.state.addresses.map((a) => a.toBase58()));
+    const missing = expectedB58.filter((addr) => !present.has(addr));
+    if (missing.length === 0) {
+      const currentSlot = await connection.getSlot("confirmed");
+      if (account.state.lastExtendedSlot < currentSlot) {
+        return account;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `Supplemental ALT ${table.toBase58()} did not become resolvable within ${timeoutMs}ms (lastExtendedSlot=${account.state.lastExtendedSlot} never fell behind current slot=${currentSlot}).`
+        );
+      }
+    } else if (Date.now() >= deadline) {
+      throw new Error(
+        `Supplemental ALT ${table.toBase58()} is still missing expected address(es) after ${timeoutMs}ms: ` + missing.join(", ")
+      );
+    }
+    await sleep2(pollIntervalMs);
+  }
+}
 function deriveRelayUrlFromRiskQuoteUrl(riskQuoteUrl) {
   if (!riskQuoteUrl) return void 0;
   const trimmed = riskQuoteUrl.replace(/\/$/, "");
@@ -5784,7 +5947,7 @@ async function planDirectV0Submission(args) {
   );
   return { tier: "minimal", instructions: minimal, supplementalAltRequested, fullSize, minimalSize };
 }
-async function submitViaExternalFeePayer(connection, depositor, externalFeePayer, externalFeePayerPubkey, instructions, addressLookupTableAccounts, onProgress, allowSupplementalAlt = true) {
+async function submitViaExternalFeePayer(connection, depositor, externalFeePayer, externalFeePayerPubkey, instructions, addressLookupTableAccounts, onProgress, allowSupplementalAlt = true, relayAltAttempt) {
   if (!depositor.signTransaction) {
     throw new Error(
       "externalFeePayer requires wallet-style signTransaction \u2014 keypair-only depositors aren't supported for external fee payment."
@@ -5813,6 +5976,18 @@ async function submitViaExternalFeePayer(connection, depositor, externalFeePayer
   };
   const compressWithSupplementalAlt = async (instrs, extraAddresses = []) => {
     onProgress?.("Transaction exceeds packet limit; creating supplemental ALT...");
+    if (relayAltAttempt) {
+      try {
+        onProgress?.("Requesting supplemental lookup table from relay...");
+        addressLookupTableAccounts = [await relayAltAttempt()];
+        return;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        onProgress?.(
+          `Relay supplemental ALT failed (${msg}); falling back to a depositor-signed table.`
+        );
+      }
+    }
     try {
       const supplementalAddresses = dedupePubkeys([
         ...collectLookupCandidatesFromInstructions(instrs, externalFeePayerPubkey, void 0),
@@ -5880,7 +6055,7 @@ async function submitViaExternalFeePayer(connection, depositor, externalFeePayer
   }
   return signature;
 }
-async function submitTransactionDirect(connection, programId, depositor, proofBytes, publicInputsBytes, nullifiers, mint, recipient, riskOracleQueue, riskQuoteUrl, getRiskQuoteInstruction, onProgress, addressLookupTableAccounts, rangeApiKey, encryptedNoteBytes, relayUrl, altAddresses, relayer, relayerFee, onTransactProofBuilt, externalFeePayer) {
+async function submitTransactionDirect(connection, programId, depositor, proofBytes, publicInputsBytes, nullifiers, mint, recipient, riskOracleQueue, riskQuoteUrl, getRiskQuoteInstruction, onProgress, addressLookupTableAccounts, rangeApiKey, encryptedNoteBytes, relayUrl, altAddresses, relayer, relayerFee, onTransactProofBuilt, externalFeePayer, relaySupplementalAlt) {
   onProgress?.("Building transaction...");
   addressLookupTableAccounts = await resolveAddressLookupTableAccounts(
     connection,
@@ -5901,14 +6076,8 @@ async function submitTransactionDirect(connection, programId, depositor, proofBy
       "rangeApiKey direct risk quotes do not support H-01 deposit nonce binding. Use relayUrl/riskQuoteUrl or getRiskQuoteInstruction."
     );
   }
-  if (isDeposit && (!addressLookupTableAccounts || addressLookupTableAccounts.length === 0) && encryptedNoteBytes && encryptedNoteBytes.length > 0) {
-    onProgress?.("Creating address lookup table (chain notes require v0 tx to fit)...");
-    addressLookupTableAccounts = await createEphemeralALT(connection, depositor, onProgress, [], externalFeePayer);
-  }
-  if (isDeposit && isSplPool && (!addressLookupTableAccounts || addressLookupTableAccounts.length === 0)) {
-    onProgress?.("Creating address lookup table (SPL deposit requires v0 tx)...");
-    addressLookupTableAccounts = await createEphemeralALT(connection, depositor, onProgress, [], externalFeePayer);
-  }
+  const needsAltForChainNotes = isDeposit && Boolean(encryptedNoteBytes && encryptedNoteBytes.length > 0);
+  const needsAltForSplDeposit = isDeposit && isSplPool;
   const publicAmountBytes = publicInputsBytes.slice(32, 40);
   const publicAmountBuffer = Buffer.from(publicAmountBytes);
   const publicAmount = readBigInt64LE(publicAmountBuffer, 0);
@@ -5960,6 +6129,49 @@ async function submitTransactionDirect(connection, programId, depositor, proofBy
   const nullifier1Hex = Buffer.from(nullifiers[1]).toString("hex");
   let riskNoncePda;
   let depositNonce = null;
+  let relaySupplementalAltPromise;
+  const requestRelaySupplementalAlt = () => {
+    const [nullifierPda0] = deriveNullifierPDA(programId, pdas.pool, nullifiers[0]);
+    const [nullifierPda1] = deriveNullifierPDA(programId, pdas.pool, nullifiers[1]);
+    const [riskNoncePdaForAlt] = deriveRiskNoncePDA(programId, depositNonce);
+    const depositorAta = getAssociatedTokenAddressSync(mint, depositor.publicKey, false, TOKEN_PROGRAM_ID);
+    return fetchSupplementalAltFromRelay(relayUrl, {
+      mint,
+      nullifiers,
+      bind0: depositNonce,
+      depositor: depositor.publicKey
+    }).then(
+      (table) => resolveRelaySupplementalAlt(connection, table, [
+        nullifierPda0,
+        nullifierPda1,
+        riskNoncePdaForAlt,
+        depositorAta
+      ])
+    );
+  };
+  const relayAltEligible = () => Boolean(relaySupplementalAlt && relayUrl && isDeposit && isSplPool && depositNonce && nullifiers);
+  const getRelaySupplementalAlt = () => {
+    if (!relaySupplementalAltPromise) {
+      relaySupplementalAltPromise = requestRelaySupplementalAlt();
+    }
+    return relaySupplementalAltPromise;
+  };
+  const acquireDepositAlt = async () => {
+    if (relayAltEligible()) {
+      try {
+        onProgress?.("Requesting lookup table from relay...");
+        const relayAlt = await getRelaySupplementalAlt();
+        return [relayAlt];
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        onProgress?.(
+          `Relay lookup table failed (${msg}); falling back to a depositor-signed table.`
+        );
+      }
+    }
+    onProgress?.("Creating address lookup table for V0 transaction...");
+    return createEphemeralALT(connection, depositor, onProgress, [], externalFeePayer);
+  };
   if ((isDeposit || isSend) && riskCheckEnabled && !riskQuoteIx) {
     if (getRiskQuoteInstruction) {
       onProgress?.("Fetching risk quote (custom)...");
@@ -5990,10 +6202,13 @@ async function submitTransactionDirect(connection, programId, depositor, proofBy
     }
     if (depositNonce) {
       [riskNoncePda] = deriveRiskNoncePDA(programId, depositNonce);
+      if (relaySupplementalAlt && relayUrl && isSplPool) {
+        getRelaySupplementalAlt().catch(() => {
+        });
+      }
     }
-    if (riskQuoteIx && (!addressLookupTableAccounts || addressLookupTableAccounts.length === 0)) {
-      onProgress?.("Creating address lookup table for V0 transaction (risk quote)...");
-      addressLookupTableAccounts = await createEphemeralALT(connection, depositor, onProgress, [], externalFeePayer);
+    if ((!addressLookupTableAccounts || addressLookupTableAccounts.length === 0) && (riskQuoteIx || needsAltForChainNotes || needsAltForSplDeposit)) {
+      addressLookupTableAccounts = await acquireDepositAlt();
     }
   }
   if (!isDeposit && riskCheckEnabled && recipient && riskQuoteUrl && !riskQuoteIx) {
@@ -6059,7 +6274,14 @@ async function submitTransactionDirect(connection, programId, depositor, proofBy
       externalFeePayerPubkey,
       fullInstructions,
       addressLookupTableAccounts,
-      onProgress
+      onProgress,
+      void 0,
+      // `addressLookupTableAccounts` above already carries the relay-owned table when eligible
+      // (acquireDepositAlt ran before this branch, same as the non-externalFeePayer path). This is
+      // only for submitViaExternalFeePayer's OWN, separate supplemental round — triggered by the
+      // external payer's extra signature and payment-instruction accounts pushing an already-ALT'd
+      // tx back over the limit — so that round also tries the relay before an ephemeral fallback.
+      relayAltEligible() ? getRelaySupplementalAlt : void 0
     );
   } else if (useV0) {
     const plan = await planDirectV0Submission({
@@ -6068,6 +6290,23 @@ async function submitTransactionDirect(connection, programId, depositor, proofBy
       compact: compactInstructions,
       minimal: minimalInstructions,
       createSupplementalAlt: async () => {
+        if (relayAltEligible()) {
+          try {
+            onProgress?.("Requesting supplemental lookup table from relay...");
+            const relayAlt = await getRelaySupplementalAlt();
+            addressLookupTableAccounts = [
+              ...(addressLookupTableAccounts ?? []).filter((t) => !t.key.equals(relayAlt.key)),
+              relayAlt
+            ];
+            ({ blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash());
+            return;
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            onProgress?.(
+              `Relay supplemental ALT failed (${msg}); falling back to a depositor-signed table.`
+            );
+          }
+        }
         const supplementalAddresses = collectLookupCandidatesFromInstructions(
           minimalInstructions,
           depositor.publicKey,
@@ -6860,6 +7099,21 @@ async function transact(params, options) {
       "options.chainNoteSalt requires an explicit chainNoteViewingKeyNk (or getChainNoteViewingKeyNk). The salt anchors a deposit note derived from that nk; inferring nk from the output note's own key would encrypt the chain note under a different key than the note was derived from, and the deposit would be undiscoverable."
     );
   }
+  const chainNoteSalt = options.chainNoteSalt !== void 0 ? assertChainNoteSalt(options.chainNoteSalt) : randomChainNoteSalt();
+  const chainNoteWillCarrySalt = !options.disableChainNotes && !(options.encryptedNotes && options.encryptedNotes.length > 0);
+  if (explicitChainNoteNk && chainNoteWillCarrySalt) {
+    const inputOwners = new Set(inputUtxos.map((u) => u.keypair.publicKey));
+    for (let i = 0; i < outputUtxos.length; i++) {
+      const out = outputUtxos[i];
+      if (!out || out.amount <= BigInt(0)) continue;
+      if (!inputOwners.has(out.keypair.publicKey)) continue;
+      if (out.blinding !== deriveChangeNoteBlinding(explicitChainNoteNk, chainNoteSalt, i)) {
+        throw new Error(
+          `Output ${i} is change (amount ${out.amount}, owned by an input's keypair) but its blinding is not the one derivable from this wallet's viewing key. It was almost certainly built with \`createUtxo\`, whose blinding is random and is written nowhere on chain \u2014 if the caller ever drops the returned note, the funds are unspendable forever. Build change with \`createRecoverableChangeUtxo(amount, keypair, nk, mint, salt, outputIndex)\` and pass the same salt as \`options.chainNoteSalt\`, or use \`partialWithdraw\` / \`transfer\` / \`swapWithChange\`, which do it for you.`
+        );
+      }
+    }
+  }
   assertAllowedRpcConnection(connection);
   await ensureViewingKeyRegistered(options, onProgress, fallbackNk);
   const resolvedChainNoteNk = explicitChainNoteNk ?? fallbackNk ?? null;
@@ -7214,7 +7468,6 @@ async function transact(params, options) {
   const maxFee = isWithdrawal ? protocolFeeSnapshot : BigInt(0);
   const extDataHash = await computeExtDataHash(recipient ?? null, relayerFee, relayer ?? null, maxFee);
   const chainNoteTimestamp = BigInt(Date.now());
-  const chainNoteSalt = options.chainNoteSalt !== void 0 ? assertChainNoteSalt(options.chainNoteSalt) : randomChainNoteSalt();
   const mintField = pubkeyToFieldElement(mint);
   let signature = "pending-" + Date.now().toString();
   let commitmentIndices = [-1, -1];
@@ -7489,7 +7742,8 @@ async function transact(params, options) {
           relayer ?? null,
           relayerFee,
           options.onTransactProofBuilt,
-          externalFeePayer
+          externalFeePayer,
+          options.relaySupplementalAlt
         );
         signature = directResult.signature;
         commitmentIndices = directResult.commitmentIndices;
@@ -7881,16 +8135,30 @@ async function transfer(inputUtxos, recipientPubkey, amount, options) {
   const change = inputSum - amount;
   const myKeypair = inputUtxos[0].keypair;
   const mint = inputUtxos[0].mintAddress;
+  const transferNk = await resolveChainNoteNk(options);
+  const changeNoteSalt = transferNk ? randomChangeNoteSalt() : void 0;
+  const isSendToSelf = inputUtxos.some((u) => u.keypair.publicKey === recipientPubkey);
   const recipientKeypair = {
     privateKey: BigInt(0),
     // Recipient's private key unknown
     publicKey: recipientPubkey
   };
-  const recipientUtxo = await createUtxo(amount, recipientKeypair, mint);
+  const recipientUtxo = transferNk && isSendToSelf ? (await createRecoverableChangeUtxo(amount, myKeypair, transferNk, mint, changeNoteSalt, 0)).utxo : await createUtxo(amount, recipientKeypair, mint);
   const outputUtxos = [recipientUtxo];
   if (change > BigInt(0)) {
-    const changeUtxo = await createUtxo(change, myKeypair, mint);
-    outputUtxos.push(changeUtxo);
+    if (transferNk) {
+      const { utxo } = await createRecoverableChangeUtxo(
+        change,
+        myKeypair,
+        transferNk,
+        mint,
+        changeNoteSalt,
+        1
+      );
+      outputUtxos.push(utxo);
+    } else {
+      outputUtxos.push(await createUtxo(change, myKeypair, mint));
+    }
   }
   return transact(
     {
@@ -7899,7 +8167,7 @@ async function transfer(inputUtxos, recipientPubkey, amount, options) {
       externalAmount: BigInt(0)
       // Pure shield-to-shield
     },
-    options
+    changeNoteSalt !== void 0 ? { ...options, chainNoteSalt: changeNoteSalt } : options
   );
 }
 async function partialWithdraw(inputUtxos, recipient, withdrawAmount, options) {
@@ -7916,7 +8184,9 @@ async function partialWithdraw(inputUtxos, recipient, withdrawAmount, options) {
     utxos.sort((a, b) => a.amount > b.amount ? 1 : a.amount < b.amount ? -1 : 0);
     const [small1, small2, ...rest] = utxos;
     const mergedAmount = small1.amount + small2.amount;
-    const mergedOutput = await createUtxo(mergedAmount, myKeypair, mint);
+    const mergeNk = await resolveChainNoteNk(options);
+    const mergeSalt = mergeNk ? randomChangeNoteSalt() : void 0;
+    const mergedOutput = mergeNk ? (await createRecoverableChangeUtxo(mergedAmount, myKeypair, mergeNk, mint, mergeSalt, 0)).utxo : await createUtxo(mergedAmount, myKeypair, mint);
     const mergeResult = await transact(
       {
         inputUtxos: [small1, small2],
@@ -7926,7 +8196,8 @@ async function partialWithdraw(inputUtxos, recipient, withdrawAmount, options) {
       },
       {
         ...options,
-        cachedMerkleTree: cachedTree
+        cachedMerkleTree: cachedTree,
+        ...mergeSalt !== void 0 && { chainNoteSalt: mergeSalt }
       }
     );
     cachedTree = mergeResult.merkleTree;
@@ -7939,9 +8210,25 @@ async function partialWithdraw(inputUtxos, recipient, withdrawAmount, options) {
   const finalInputSum = sumUtxoAmounts(utxos);
   const change = finalInputSum - withdrawAmount;
   const outputUtxos = [];
+  let changeNoteSalt;
   if (change > BigInt(0)) {
-    const changeUtxo = await createUtxo(change, myKeypair, mint);
-    outputUtxos.push(changeUtxo);
+    const changeNk = await resolveChainNoteNk(options);
+    if (changeNk) {
+      const salt = randomChangeNoteSalt();
+      const { utxo } = await createRecoverableChangeUtxo(
+        change,
+        myKeypair,
+        changeNk,
+        mint,
+        salt,
+        0
+        // partialWithdraw puts change at output 0
+      );
+      outputUtxos.push(utxo);
+      changeNoteSalt = salt;
+    } else {
+      outputUtxos.push(await createUtxo(change, myKeypair, mint));
+    }
   }
   return transact(
     {
@@ -7952,7 +8239,8 @@ async function partialWithdraw(inputUtxos, recipient, withdrawAmount, options) {
     },
     {
       ...options,
-      cachedMerkleTree: cachedTree
+      cachedMerkleTree: cachedTree,
+      ...changeNoteSalt !== void 0 && { chainNoteSalt: changeNoteSalt }
     }
   );
 }
@@ -8086,7 +8374,16 @@ async function swapUtxo(params, options) {
   onProgress?.("Validating transaction parameters...");
   const swapFallbackNk = getNkFromUtxoPrivateKey(inputUtxos[0].keypair.privateKey);
   await ensureViewingKeyRegistered(options, onProgress, swapFallbackNk);
-  const resolvedSwapChainNoteNk = await resolveChainNoteNk(options) ?? swapFallbackNk;
+  const explicitSwapChainNoteNk = await resolveChainNoteNk(options);
+  const resolvedSwapChainNoteNk = explicitSwapChainNoteNk ?? swapFallbackNk;
+  const chainNoteSalt = options.chainNoteSalt !== void 0 ? assertChainNoteSalt(options.chainNoteSalt) : randomChainNoteSalt();
+  if (explicitSwapChainNoteNk && changeUtxo && changeUtxo.amount > BigInt(0) && inputUtxos.some((u) => u.keypair.publicKey === changeUtxo.keypair.publicKey)) {
+    if (changeUtxo.blinding !== deriveChangeNoteBlinding(explicitSwapChainNoteNk, chainNoteSalt, 0)) {
+      throw new Error(
+        `Swap change (amount ${changeUtxo.amount}, owned by an input's keypair) has a blinding that is not derivable from this wallet's viewing key. It was almost certainly built with \`createUtxo\`, whose blinding is random and is written nowhere on chain \u2014 if the caller ever drops the returned note, the funds are unspendable forever. Build it with \`createRecoverableChangeUtxo(amount, keypair, nk, mint, salt, 0)\` and pass the same salt as \`options.chainNoteSalt\`, or use \`swapWithChange\`, which does it for you.`
+      );
+    }
+  }
   const swapPoolMint = NATIVE_SOL_MINT;
   const pdas = getShieldPoolPDAs(programId, swapPoolMint);
   let merkleState = null;
@@ -8428,7 +8725,6 @@ async function swapUtxo(params, options) {
     outputCommitments.push(await computeCommitment(utxo));
   }
   const chainNoteTimestamp = BigInt(Date.now());
-  const chainNoteSalt = randomChainNoteSalt();
   onProgress?.("Computing external data hash...");
   const mint = swapPoolMint;
   const mintField = pubkeyToFieldElement(mint);
@@ -8646,6 +8942,9 @@ async function swapUtxo(params, options) {
       url.searchParams.set("wallet", poolPda.toBase58());
       url.searchParams.set("recipient", recipientWallet.toBase58());
       url.searchParams.set("sender", recipientWallet.toBase58());
+      url.searchParams.set("pool_mint", mint.toBase58());
+      url.searchParams.set("nullifier0", toHex(bigintToBytes322(inputNullifiers[0])));
+      url.searchParams.set("nullifier1", toHex(bigintToBytes322(inputNullifiers[1])));
       const quoteRes = await relayFetch(url.toString());
       if (!quoteRes.ok) {
         const text = await quoteRes.text();
@@ -8890,10 +9189,18 @@ async function swapWithChange(inputUtxos, swapAmount, outputMint, recipientAta,
     throw new Error(`Insufficient balance: input(${totalInput}) < swap(${swapAmount})`);
   }
   let changeUtxo;
+  let changeNoteSalt;
   if (change > BigInt(0)) {
     const myKeypair = inputUtxos[0].keypair;
     const mint = inputUtxos[0].mintAddress;
-    changeUtxo = await createUtxo(change, myKeypair, mint);
+    const changeNk = await resolveChainNoteNk(options);
+    if (changeNk) {
+      const salt = randomChangeNoteSalt();
+      changeUtxo = (await createRecoverableChangeUtxo(change, myKeypair, changeNk, mint, salt, 0)).utxo;
+      changeNoteSalt = salt;
+    } else {
+      changeUtxo = await createUtxo(change, myKeypair, mint);
+    }
   }
   return swapUtxo(
     {
@@ -8905,7 +9212,7 @@ async function swapWithChange(inputUtxos, swapAmount, outputMint, recipientAta,
       recipientWallet,
       minOutputAmount
     },
-    options
+    changeNoteSalt !== void 0 ? { ...options, chainNoteSalt: changeNoteSalt } : options
   );
 }
 
@@ -9708,6 +10015,7 @@ async function scanTransactions(opts) {
   const txs = [];
   const swapCtxByCommitment = /* @__PURE__ */ new Map();
   const recoveredDepositNotes = [];
+  const recoveredChangeNotes = [];
   let processed = 0;
   let rpcCallsMade = 0;
   onStatus?.(`Scanning ${sigInfos.length} transactions...`);
@@ -10055,6 +10363,34 @@ async function scanTransactions(opts) {
                 if (debug) console.log(`[DEBUG] ${sigInfo.signature}: deposit recovery failed (${e?.message || e})`);
               }
             }
+            if (isWithdrawal && compactNote.noteSalt !== void 0 && compactNote.outAmount0 !== void 0 && compactNote.outAmount0 > 0n && compactNote.outPubkey0 !== void 0 && compactNote.outPubkey0 !== 0n) {
+              try {
+                const recoveredChange = await matchChangeNote({
+                  viewingKeyNk,
+                  noteSalt: compactNote.noteSalt,
+                  amount: compactNote.outAmount0,
+                  keypair: { privateKey: 0n, publicKey: compactNote.outPubkey0 },
+                  mintAddress: new PublicKey9(asset.mint),
+                  outputIndex: 0,
+                  // v4 describes output 0, which is where change lands
+                  outputCommitments: ixCtx.outputCommitments ?? []
+                });
+                if (recoveredChange) {
+                  recoveredChangeNotes.push({
+                    ...recoveredChange,
+                    signature: sigInfo.signature,
+                    timestamp: decoded.timestamp
+                  });
+                  if (debug) {
+                    console.log(
+                      `[DEBUG] ${sigInfo.signature}: recovered change note (amount=${recoveredChange.amount})`
+                    );
+                  }
+                }
+              } catch (e) {
+                if (debug) console.log(`[DEBUG] ${sigInfo.signature}: change recovery failed (${e?.message || e})`);
+              }
+            }
             txs.push({
               txType: decoded.txType,
               amount: grossAmount,
@@ -10160,7 +10496,8 @@ async function scanTransactions(opts) {
     lastSignature: newestSignature,
     rpcCallsMade,
     deliveredNotes,
-    recoveredDepositNotes
+    recoveredDepositNotes,
+    recoveredChangeNotes
   };
 }
 function toComplianceReport(result) {
@@ -10606,12 +10943,14 @@ export {
   createCloakError,
   createDepositInstruction,
   createLogger,
+  createRecoverableChangeUtxo,
   createRecoverableDepositUtxo,
   createUtxo,
   createZeroUtxo,
   decryptCompactChainNote,
   decryptComplianceMetadataWithMasterKey,
   decryptTransactionMetadata,
+  deriveChangeNoteBlinding,
   deriveDepositNoteSecrets,
   deriveDiversifiedViewingKey,
   deriveDiversifier,
@@ -10697,6 +11036,7 @@ export {
   loadPendingDeposits,
   loadPendingWithdrawals,
   loadVerifiedCircuitArtifacts,
+  matchChangeNote,
   matchDepositNote,
   matchSwapRefundLeaf,
   openRecipientDeliveryNote,
@@ -10717,6 +11057,7 @@ export {
   pubkeyToFieldElement,
   pubkeyToLimbs,
   randomBytes,
+  randomChangeNoteSalt,
   randomDepositNoteSalt,
   randomFieldElement,
   readMerkleTreeState,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cloak.dev/sdk",
   "description": "Shield, send, and swap on Solana privately — TypeScript SDK with UTXO-based zero-knowledge transactions",
-  "version": "0.2.1",
+  "version": "0.2.2-staging.33f11a2",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",