@arcanetech/privacy-sdk-stellar 0.5.0 → 0.5.2

package/dist/transact/index.d.ts

@@ -155,19 +155,20 @@ interface StellarTransactEnvironment {
     network: StellarNetworkConfig;
     /**
      * Nonce (persistent storage key) of the pool's `ZkConfig` entry this
-     * environment's proofs/circuit shape target. Defaults to `2n` (Commitment
-     * V2, 95 public signals) when omitted. Nonce `0` is the retired 93-signal
-     * layout and must be passed explicitly.
+     * environment's proofs/circuit shape target. Defaults to `3n` (bundled 2×2
+     * binding layout) when omitted. Also bundled: `7n` (6×6). The value must
+     * match the on-chain pool config or bootstrap/execute fails with
+     * `no zk circuit configured for nonce …`.
      */
     zkConfigNonce?: bigint;
     /**
-     * Optional nonce-keyed circuit map. Defaults to the SDK bundled 2×2 (nonce 2)
-     * and 6×6 (nonce 6) schemes. URL fields are only for a custom/dev circuit.
+     * Optional nonce-keyed circuit map. Defaults to the SDK bundled 2×2 (nonce 3)
+     * and 6×6 (nonce 7) schemes. URL fields are only for a custom/dev circuit.
      */
     zkCircuits?: Record<string, StellarZkCircuitDefinition>;
     /**
      * Directory or HTTP prefix for graph / r1cs / proving-key files.
-     * Defaults to the GitHub release for `@arcanetech/stellar-privacy-pool-zk-sdk`.
+     * Defaults to the CDN prefix baked into `@arcanetech/stellar-privacy-pool-zk-sdk`.
      * Staging and local stands override this to serve files from disk.
      */
     zkArtifactBaseUrl?: string;
@@ -552,6 +553,12 @@ interface FetchContractMerkleResult {
     merkleRootHex: string;
     updatedAt: number;
 }
+/**
+ * Loads pool Merkle leaves without `get_commitments()`. That helper walks the
+ * whole tree in one simulate and exceeds the Soroban host budget on a live
+ * stand. Completes the cached prefix from persistent `TreeDataKey::Leaf`
+ * ledger entries instead.
+ */
 declare function fetchAndMergeMerkleState(parameters: {
     poolContractId: string;
     walletPublicKey: string;

package/dist/transact/index.js

@@ -356,6 +356,7 @@ function buildPoolTransactionAuditParameters(input) {
     input.nAuditSlots
   );
 }
+var DECIMAL_APPLICATION_ID = /^\d+$/u;
 function resolvePoolApplicationId(applicationId) {
   const trimmed = applicationId?.trim();
   if (!trimmed) {
@@ -363,6 +364,11 @@ function resolvePoolApplicationId(applicationId) {
       "Privacy pool applicationId is required. Pass it in client factory config."
     );
   }
+  if (!DECIMAL_APPLICATION_ID.test(trimmed)) {
+    throw new Error(
+      "Privacy pool applicationId must be association.audit_id (decimal Fr), not a UUID or foreignId."
+    );
+  }
   return trimmed;
 }
 
@@ -702,8 +708,8 @@ function resolveZkConfigNonce(transactEnvironment) {
 }
 
 // src/transact/zk/browser-artifact-cache.ts
-import { ZK_SDK_PACKAGE_VERSION } from "@arcanetech/stellar-privacy-pool-zk-sdk";
-var ZK_ARTIFACT_CACHE_NAME = `privacy-sdk-stellar-zk-artifacts:${ZK_SDK_PACKAGE_VERSION}`;
+import { ZK_ARTIFACT_VERSION } from "@arcanetech/stellar-privacy-pool-zk-sdk";
+var ZK_ARTIFACT_CACHE_NAME = `privacy-sdk-stellar-zk-artifacts:${ZK_ARTIFACT_VERSION}`;
 function isBrowserCacheApiAvailable() {
   return browserCacheStorage() !== void 0;
 }
@@ -2700,92 +2706,167 @@ async function prepareConfidentialTransferProof(parameters) {
 }
 
 // src/transact/merkle/fetch-contract.ts
+import { Buffer as Buffer14 } from "buffer";
+
+// src/transact/merkle/state-port.ts
+function poolMerkleStateToCachedView(state) {
+  return {
+    commitments: state.commitments,
+    updatedAt: state.updatedAt,
+    merkleRootHex: state.merkleRootHex
+  };
+}
+
+// src/transact/merkle/read-tree-leaves.ts
+import { Address as Address5, xdr as xdr6 } from "@stellar/stellar-sdk";
 import { Buffer as Buffer13 } from "buffer";
 
 // src/transact/merkle/encoding.ts
 import "buffer";
 var FR_ORDER = 0x73eda753299d7d483339d80809a1d80553bda402fffe5bfeffffffff00000001n;
-function bufferToDecimal(buf) {
+function commitmentBufferToDecimal(buf) {
   const hex = buf.toString("hex");
   const bigintFromHex = BigInt(`0x${hex}`);
   const reduced = bigintFromHex % FR_ORDER;
   return reduced.toString();
 }
-function commitmentsBuffersToDecimal(buffers) {
-  return buffers.map((bufferRow) => bufferToDecimal(bufferRow));
-}
 
-// src/transact/merkle/state-port.ts
-function poolMerkleStateToCachedView(state) {
-  return {
-    commitments: state.commitments,
-    updatedAt: state.updatedAt,
-    merkleRootHex: state.merkleRootHex
-  };
-}
-
-// src/transact/merkle/fetch-contract.ts
-function normalizeCommitmentBuffers(rawBuffers) {
-  return rawBuffers.map(
-    (bufferRow) => Buffer13.isBuffer(bufferRow) ? bufferRow : Buffer13.from(bufferRow)
+// src/transact/merkle/read-tree-leaves.ts
+var TREE_LEAF_LEDGER_BATCH_SIZE = 100;
+function treeLeafLedgerKey(contractId, leafIndex) {
+  return xdr6.LedgerKey.contractData(
+    new xdr6.LedgerKeyContractData({
+      contract: new Address5(contractId).toScAddress(),
+      key: treeLeafKeyScValue(leafIndex),
+      durability: xdr6.ContractDataDurability.persistent()
+    })
   );
 }
-function mergeContractMerkleWithCache(parameters) {
-  const cachedCount = parameters.cachedState?.commitments.length ?? 0;
-  const shouldPreferContract = parameters.contractCount > cachedCount || !parameters.cachedState || cachedCount === 0;
-  if (shouldPreferContract) {
-    const updatedAt = Date.now();
-    void parameters.poolMerkleState?.set({
-      poolContract: parameters.poolContractId,
-      commitments: parameters.contractCommitments,
-      commitmentCount: parameters.contractCount,
-      merkleRootHex: parameters.merkleRootHex,
-      updatedAt
-    });
-    return {
-      commitments: parameters.contractCommitments,
-      updatedAt,
-      merkleRootHex: parameters.merkleRootHex,
-      commitmentCount: parameters.contractCount
-    };
+function treeLeafKeyScValue(leafIndex) {
+  return xdr6.ScVal.scvVec([xdr6.ScVal.scvSymbol("Leaf"), xdr6.ScVal.scvU32(leafIndex)]);
+}
+function leafIndexFromContractDataKey(key) {
+  if (key.switch() !== xdr6.ScValType.scvVec()) {
+    return void 0;
   }
-  return {
-    commitments: parameters.cachedState.commitments,
-    updatedAt: parameters.cachedState.updatedAt,
-    merkleRootHex: parameters.cachedState.merkleRootHex ?? parameters.merkleRootHex,
-    commitmentCount: parameters.cachedState.commitments.length
-  };
+  const fields = key.vec();
+  if (!fields || fields.length !== 2) {
+    return void 0;
+  }
+  const [tag, indexValue] = fields;
+  if (!tag || tag.switch() !== xdr6.ScValType.scvSymbol()) {
+    return void 0;
+  }
+  if (tag.sym().toString() !== "Leaf") {
+    return void 0;
+  }
+  if (!indexValue || indexValue.switch() !== xdr6.ScValType.scvU32()) {
+    return void 0;
+  }
+  return indexValue.u32();
 }
-async function readCachedPoolMerkleView(poolMerkleState, poolContractId) {
-  if (!poolMerkleState) {
+function commitmentBytesFromContractDataValue(value) {
+  if (value.switch() !== xdr6.ScValType.scvBytes()) {
     return void 0;
   }
-  const cached = await poolMerkleState.get(poolContractId);
-  return cached ? poolMerkleStateToCachedView(cached) : void 0;
+  return Buffer13.from(value.bytes());
+}
+async function readTreeLeafCommitments(input) {
+  if (input.startIndex >= input.endIndex) {
+    return [];
+  }
+  const byIndex = await readLeafBuffersByIndex(input);
+  return decimalCommitmentsInRange(byIndex, input.startIndex, input.endIndex);
+}
+async function readLeafBuffersByIndex(input) {
+  const keys = ledgerKeysForRange(input.contractId, input.startIndex, input.endIndex);
+  const byIndex = /* @__PURE__ */ new Map();
+  for (const batch of chunkLedgerKeys(keys, TREE_LEAF_LEDGER_BATCH_SIZE)) {
+    const response = await input.reader.getLedgerEntries(...batch);
+    collectLeafBuffers(response.entries, byIndex);
+  }
+  return byIndex;
+}
+function ledgerKeysForRange(contractId, startIndex, endIndex) {
+  const keys = [];
+  for (let leafIndex = startIndex; leafIndex < endIndex; leafIndex += 1) {
+    keys.push(treeLeafLedgerKey(contractId, leafIndex));
+  }
+  return keys;
+}
+function chunkLedgerKeys(keys, batchSize) {
+  const batches = [];
+  for (let offset = 0; offset < keys.length; offset += batchSize) {
+    batches.push(keys.slice(offset, offset + batchSize));
+  }
+  return batches;
+}
+function collectLeafBuffers(entries, byIndex) {
+  for (const entry of entries) {
+    const contractData = entry.val.contractData();
+    const leafIndex = leafIndexFromContractDataKey(contractData.key());
+    const bytes = commitmentBytesFromContractDataValue(contractData.val());
+    if (leafIndex === void 0 || !bytes) {
+      continue;
+    }
+    byIndex.set(leafIndex, bytes);
+  }
+}
+function decimalCommitmentsInRange(byIndex, startIndex, endIndex) {
+  const commitments = [];
+  for (let leafIndex = startIndex; leafIndex < endIndex; leafIndex += 1) {
+    const bytes = byIndex.get(leafIndex);
+    if (!bytes) {
+      throw new Error(`Missing Merkle leaf ${String(leafIndex)} in pool storage.`);
+    }
+    commitments.push(commitmentBufferToDecimal(bytes));
+  }
+  return commitments;
 }
+
+// src/transact/merkle/reuse-cached-commitments.ts
+function completeCacheRootMatches(cachedState, merkleRootHex) {
+  const cachedRoot = cachedState?.merkleRootHex;
+  if (cachedRoot === void 0 || cachedRoot === "") {
+    return true;
+  }
+  return cachedRoot === merkleRootHex;
+}
+function reuseCachedCommitments(input) {
+  const cachedCommitments = input.cachedState?.commitments ?? [];
+  if (cachedCommitments.length === 0) {
+    return [];
+  }
+  if (cachedCommitments.length > input.onChainCount) {
+    return [];
+  }
+  if (cachedCommitments.length === input.onChainCount) {
+    return completeCacheRootMatches(input.cachedState, input.merkleRootHex) ? cachedCommitments : [];
+  }
+  return cachedCommitments;
+}
+
+// src/transact/merkle/fetch-contract.ts
 async function fetchAndMergeMerkleState(parameters) {
-  const client = readPoolClientFactory(parameters.transactEnvironment)({
-    contractId: parameters.poolContractId,
-    walletPublicKey: parameters.walletPublicKey,
-    networkPassphrase: parameters.transactEnvironment.network.networkPassphrase,
-    sorobanRpcUrl: parameters.transactEnvironment.network.rpcUrl
-  });
-  const commitmentsRead = await client.get_commitments();
-  const rawBuffers = commitmentsRead.result;
-  const buffers = normalizeCommitmentBuffers(rawBuffers);
-  const contractCommitments = commitmentsBuffersToDecimal(buffers);
-  const contractCount = contractCommitments.length;
+  const client = createPoolClient(parameters);
+  const countRead = await client.get_commitment_count();
+  const onChainCount = requireCommitmentCount(countRead.result);
   const rootRead = await client.get_merkle_root();
-  const merkleRootBuffer = rootRead.result;
-  const merkleRootHex = Buffer13.from(merkleRootBuffer).toString("hex");
+  const merkleRootHex = merkleRootToHex(rootRead.result);
   const cachedState = await readCachedPoolMerkleView(
     parameters.poolMerkleState,
     parameters.poolContractId
   );
-  return mergeContractMerkleWithCache({
+  const commitments = await loadCommitments({
+    cachedState,
+    onChainCount,
+    merkleRootHex,
+    rpcUrl: parameters.transactEnvironment.network.rpcUrl,
+    contractId: parameters.poolContractId
+  });
+  return persistFetchedMerkleState({
     poolContractId: parameters.poolContractId,
-    contractCommitments,
-    contractCount,
+    commitments,
     merkleRootHex,
     cachedState,
     ...parameters.poolMerkleState ? { poolMerkleState: parameters.poolMerkleState } : {}
@@ -2799,19 +2880,14 @@ async function readLeafEphemeralHex(parameters) {
   if (cached?.xHex && cached.yHex) {
     return { xHex: cached.xHex, yHex: cached.yHex };
   }
-  const client = readPoolClientFactory(parameters.transactEnvironment)({
-    contractId: parameters.poolContractId,
-    walletPublicKey: parameters.walletPublicKey,
-    networkPassphrase: parameters.transactEnvironment.network.networkPassphrase,
-    sorobanRpcUrl: parameters.transactEnvironment.network.rpcUrl
-  });
+  const client = createPoolClient(parameters);
   const read = await client.get_leaf_ephemeral({ leaf_index: parameters.leafIndex });
   const coords = read.result;
   if (!coords?.x || !coords?.y) {
     throw new Error("Missing leaf ephemeral key on contract");
   }
-  const xHex = Buffer13.from(coords.x).toString("hex");
-  const yHex = Buffer13.from(coords.y).toString("hex");
+  const xHex = Buffer14.from(coords.x).toString("hex");
+  const yHex = Buffer14.from(coords.y).toString("hex");
   await parameters.leafEphemeral?.set({
     poolContract: parameters.poolContractId,
     leafIndex: parameters.leafIndex,
@@ -2821,6 +2897,84 @@ async function readLeafEphemeralHex(parameters) {
   });
   return { xHex, yHex };
 }
+function createPoolClient(parameters) {
+  return readPoolClientFactory(parameters.transactEnvironment)({
+    contractId: parameters.poolContractId,
+    walletPublicKey: parameters.walletPublicKey,
+    networkPassphrase: parameters.transactEnvironment.network.networkPassphrase,
+    sorobanRpcUrl: parameters.transactEnvironment.network.rpcUrl
+  });
+}
+function requireCommitmentCount(result) {
+  if (typeof result === "number" && Number.isInteger(result) && result >= 0) {
+    return result;
+  }
+  throw new Error("Pool commitment count is not a non-negative integer.");
+}
+function merkleRootToHex(root) {
+  return Buffer14.from(root).toString("hex");
+}
+async function readCachedPoolMerkleView(poolMerkleState, poolContractId) {
+  if (!poolMerkleState) {
+    return void 0;
+  }
+  const cached = await poolMerkleState.get(poolContractId);
+  return cached ? poolMerkleStateToCachedView(cached) : void 0;
+}
+async function loadCommitments(input) {
+  const reused = reuseCachedCommitments({
+    cachedState: input.cachedState,
+    onChainCount: input.onChainCount,
+    merkleRootHex: input.merkleRootHex
+  });
+  if (reused.length === input.onChainCount) {
+    return reused;
+  }
+  const fetched = await readTreeLeafCommitments({
+    reader: createStellarRpcServer(input.rpcUrl),
+    contractId: input.contractId,
+    startIndex: reused.length,
+    endIndex: input.onChainCount
+  });
+  return [...reused, ...fetched];
+}
+async function persistFetchedMerkleState(input) {
+  const cachedState = input.cachedState;
+  if (cachedState && cachedMerkleUnchanged(cachedState, input.commitments, input.merkleRootHex)) {
+    return viewFromCachedMerkle(cachedState, input.merkleRootHex);
+  }
+  const updatedAt = Date.now();
+  await input.poolMerkleState?.set({
+    poolContract: input.poolContractId,
+    commitments: input.commitments,
+    commitmentCount: input.commitments.length,
+    merkleRootHex: input.merkleRootHex,
+    updatedAt
+  });
+  return {
+    commitments: input.commitments,
+    updatedAt,
+    merkleRootHex: input.merkleRootHex,
+    commitmentCount: input.commitments.length
+  };
+}
+function viewFromCachedMerkle(cachedState, merkleRootHex) {
+  return {
+    commitments: cachedState.commitments,
+    updatedAt: cachedState.updatedAt,
+    merkleRootHex: cachedState.merkleRootHex ?? merkleRootHex,
+    commitmentCount: cachedState.commitments.length
+  };
+}
+function cachedMerkleUnchanged(cachedState, commitments, merkleRootHex) {
+  if (!cachedState) {
+    return false;
+  }
+  if ((cachedState.merkleRootHex ?? merkleRootHex) !== merkleRootHex) {
+    return false;
+  }
+  return cachedState.commitments.join(",") === commitments.join(",");
+}
 
 // src/transact/encoding/fr-decimal-to-bytes.ts
 var BN254_SCALAR_MOD = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
@@ -4921,10 +5075,10 @@ function readTransferFromPrivateAddress(from) {
 import { executionError, insufficientStateError as insufficientStateError2 } from "@arcanetech/privacy-sdk-core";
 
 // src/contracts/pool/pool-domain-service.ts
-import { Buffer as Buffer14 } from "buffer";
+import { Buffer as Buffer15 } from "buffer";
 function hexToBuffer(hex) {
   const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
-  return Buffer14.from(clean, "hex");
+  return Buffer15.from(clean, "hex");
 }
 async function readNullifierConsumedOnChain(input) {
   const client = input.contractContext.createPoolClient({
@@ -5471,7 +5625,7 @@ var RELAY_SIGNAL_INDEX_PUBLIC_DEPOSIT = 91;
 var RELAY_SIGNAL_INDEX_PUBLIC_WITHDRAWAL = 92;
 
 // src/transact/relay/signals.ts
-import { Buffer as Buffer15 } from "buffer";
+import { Buffer as Buffer16 } from "buffer";
 
 // src/transact/relay/layout-profile.ts
 var FIELD_BYTES = 32;
@@ -5551,7 +5705,7 @@ function relayLayoutProfileForNonce(nonce) {
 
 // src/transact/relay/signals.ts
 function decodePublicSignalBytes(publicSignals) {
-  return Buffer15.from(publicSignals.replace(/^0x/iu, ""), "hex");
+  return Buffer16.from(publicSignals.replace(/^0x/iu, ""), "hex");
 }
 function hasSupportedLengthPrefix(bytes, signalCount) {
   const expected = RELAY_TRANSACT_SIGNAL_PREFIX_BYTES + signalCount * RELAY_TRANSACT_FIELD_BYTES;
@@ -5578,7 +5732,7 @@ function sliceSupportedPublicSignalFields(publicSignals, zkConfigNonce = DEFAULT
   const body = hasSupportedLengthPrefix(bytes, profile.signalCount) ? bytes.subarray(RELAY_TRANSACT_SIGNAL_PREFIX_BYTES) : bytes;
   return Array.from(
     { length: profile.signalCount },
-    (_unused, index) => Buffer15.from(
+    (_unused, index) => Buffer16.from(
       body.subarray(
         index * RELAY_TRANSACT_FIELD_BYTES,
         (index + 1) * RELAY_TRANSACT_FIELD_BYTES