@arcanetech/privacy-sdk-stellar 0.5.4 → 0.6.2

package/dist/transact/index.d.ts

@@ -29,6 +29,11 @@ interface StellarPrivateCoinNote {
     asset_lo: string;
     application_id?: string;
 }
+interface StellarLeanImtNode {
+    level: number;
+    index: number;
+    value: string;
+}
 interface StellarPoolMerkleState {
     poolContract: string;
     commitments: string[];
@@ -36,6 +41,7 @@ interface StellarPoolMerkleState {
     merkleRootHex: string;
     updatedAt: number;
     syncedLedger?: number;
+    nodes?: StellarLeanImtNode[];
 }
 interface StellarLeafEphemeral {
     poolContract: string;
@@ -100,6 +106,12 @@ interface LeafEphemeralStatePort {
     }): Promise<StellarLeafEphemeral | undefined>;
     set(ephemeral: StellarLeafEphemeral): Promise<void>;
 }
+interface CachedPoolMerkleView {
+    commitments: string[];
+    updatedAt: number;
+    merkleRootHex?: string;
+    nodes?: StellarLeanImtNode[];
+}
 
 type StellarSignTransaction = (input: {
     xdr: string;
@@ -574,7 +586,16 @@ interface FetchContractMerkleResult {
     commitments: string[];
     merkleRootHex: string;
     updatedAt: number;
+    nodes?: StellarLeanImtNode[];
 }
+declare function persistFetchedMerkleState(input: {
+    poolContractId: string;
+    commitments: string[];
+    merkleRootHex: string;
+    cachedState: CachedPoolMerkleView | undefined;
+    poolMerkleState?: PoolMerkleStatePort;
+}): Promise<FetchContractMerkleResult>;
+
 /**
  * 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
@@ -586,7 +607,7 @@ declare function fetchAndMergeMerkleState(parameters: {
     walletPublicKey: string;
     transactEnvironment: StellarTransactEnvironment;
     poolMerkleState?: PoolMerkleStatePort;
-}): Promise<FetchContractMerkleResult>;
+}): Promise<Awaited<ReturnType<typeof persistFetchedMerkleState>>>;
 declare function readLeafEphemeralHex(parameters: {
     poolContractId: string;
     walletPublicKey: string;

package/dist/transact/index.js

@@ -228,11 +228,240 @@ function uniformApplicationIdHints(applicationId, nAuditSlots) {
 
 // src/transact/proofs/confidential/helpers.ts
 import { withdrawObjectFromMerkleWitness } from "@arcanetech/stellar-privacy-pool-zk-sdk";
+
+// src/transact/merkle/lean-imt-api.ts
+function asLeanImtSessionApi(sdk) {
+  const candidate = sdk;
+  if (typeof candidate.importLeanImtFromState !== "function") {
+    return void 0;
+  }
+  if (typeof candidate.insertTwoLeanImt !== "function") {
+    return void 0;
+  }
+  if (typeof candidate.exportLeanImt !== "function") {
+    return void 0;
+  }
+  if (typeof candidate.dropLeanImt !== "function") {
+    return void 0;
+  }
+  if (typeof candidate.buildWithdrawMerkleWitnessFromHandle !== "function") {
+    return void 0;
+  }
+  return candidate;
+}
+
+// src/transact/merkle/field-decimal.ts
+import { Buffer as Buffer4 } from "buffer";
+var BN254 = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+var MERKLE_ROOT_BYTE_LENGTH = 32;
+var DECIMAL_STRING_RADIX = 10;
+function merkleRootBufferToFrDecimal(root) {
+  if (root.length !== MERKLE_ROOT_BYTE_LENGTH) {
+    throw new Error(
+      `expected ${MERKLE_ROOT_BYTE_LENGTH}-byte merkle root, got ${root.length}`
+    );
+  }
+  const hex = Buffer4.from(root).toString("hex");
+  return (BigInt(`0x${hex}`) % BN254).toString(DECIMAL_STRING_RADIX);
+}
+var MERKLE_ROOT_HEX_PATTERN = /^[0-9a-fA-F]{64}$/;
+function merkleRootHexToFrDecimal(merkleRootHex) {
+  const trimmed = merkleRootHex.trim();
+  if (!MERKLE_ROOT_HEX_PATTERN.test(trimmed)) {
+    return void 0;
+  }
+  return merkleRootBufferToFrDecimal(Buffer4.from(trimmed, "hex"));
+}
+
+// src/transact/merkle/state-file.ts
+function merkleSnapshotToStateFile(input) {
+  const root = merkleRootHexToFrDecimal(input.merkleRootHex);
+  const nodes = input.nodes;
+  if (!nodes || nodes.length === 0 || root === void 0) {
+    return { commitments: input.commitments };
+  }
+  return {
+    commitments: input.commitments,
+    nodes,
+    root
+  };
+}
+
+// src/transact/merkle/extend-snapshot.ts
+function isEvenLeafCount(count) {
+  return count % 2 === 0;
+}
+function importHandle(sdk, state) {
+  try {
+    return sdk.importLeanImtFromState(state);
+  } catch {
+    return void 0;
+  }
+}
+function insertNewPairs(input) {
+  for (let index = input.prefixLength; index < input.commitments.length; index += 2) {
+    const leafA = input.commitments.at(index);
+    const leafB = input.commitments.at(index + 1);
+    if (leafA === void 0 || leafB === void 0) {
+      return false;
+    }
+    try {
+      input.sdk.insertTwoLeanImt(input.handle, leafA, leafB);
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+function snapshotNodes(sdk, handle) {
+  try {
+    return sdk.exportLeanImt(handle).nodes;
+  } catch {
+    return void 0;
+  }
+}
+function prefixSnapshotState(input) {
+  const prefixLength = input.cachedState?.nodes ? input.cachedState.commitments.length : 0;
+  return merkleSnapshotToStateFile({
+    commitments: input.commitments.slice(0, prefixLength),
+    merkleRootHex: input.cachedState?.merkleRootHex ?? input.merkleRootHex,
+    ...input.cachedState?.nodes ? { nodes: input.cachedState.nodes } : {}
+  });
+}
+function importSnapshotState(input) {
+  if (input.prefixState.nodes && input.prefixState.commitments.length > 0) {
+    return input.prefixState;
+  }
+  return merkleSnapshotToStateFile({
+    commitments: input.commitments,
+    merkleRootHex: input.merkleRootHex
+  });
+}
+function exportExtendedNodes(input) {
+  const inserted = input.prefixState.nodes ? insertNewPairs({
+    sdk: input.sdk,
+    handle: input.handle,
+    prefixLength: input.prefixState.commitments.length,
+    commitments: input.commitments
+  }) : true;
+  if (!inserted) {
+    input.sdk.dropLeanImt(input.handle);
+    return void 0;
+  }
+  const nodes = snapshotNodes(input.sdk, input.handle);
+  if (!nodes) {
+    input.sdk.dropLeanImt(input.handle);
+  }
+  return nodes;
+}
+function extendMerkleSnapshotNodes(input) {
+  if (!isEvenLeafCount(input.commitments.length)) {
+    return {};
+  }
+  const prefixState = prefixSnapshotState(input);
+  const handle = importHandle(
+    input.sdk,
+    importSnapshotState({ ...input, prefixState })
+  );
+  if (handle === void 0) {
+    return {};
+  }
+  const nodes = exportExtendedNodes({
+    sdk: input.sdk,
+    handle,
+    prefixState,
+    commitments: input.commitments
+  });
+  if (!nodes) {
+    return {};
+  }
+  return { nodes, handle };
+}
+
+// src/transact/merkle/tree-session.ts
+var merkleSdkHost;
+function registerMerkleSessionSdkHost(host) {
+  merkleSdkHost = host;
+}
+async function loadSessionSdk() {
+  const host = merkleSdkHost;
+  if (typeof host?.getInitializedSdk !== "function") {
+    return void 0;
+  }
+  try {
+    return asLeanImtSessionApi(await host.getInitializedSdk());
+  } catch {
+    return void 0;
+  }
+}
+var sessionsByPool = /* @__PURE__ */ new Map();
+var handlesByKey = /* @__PURE__ */ new Map();
+function merkleSessionKey(state) {
+  const root = state.root?.trim();
+  if (root) {
+    return `${state.commitments.length}:${root}`;
+  }
+  const first = state.commitments[0] ?? "";
+  const last = state.commitments.at(-1) ?? "";
+  return `${state.commitments.length}:${first}:${last}`;
+}
+function rememberHandle(poolContract, key, handle) {
+  const existing = sessionsByPool.get(poolContract);
+  if (existing && existing.handle !== handle) {
+    handlesByKey.delete(existing.key);
+  }
+  sessionsByPool.set(poolContract, { handle, key });
+  handlesByKey.set(key, handle);
+}
+function merkleTreeHandleForState(state) {
+  return handlesByKey.get(merkleSessionKey(state));
+}
+function bindImportedMerkleTree(input) {
+  rememberHandle(input.poolContract, merkleSessionKey(input.state), input.handle);
+}
+async function resolveExtendedMerkleNodes(input) {
+  const cached = input.cachedState;
+  if (cached && cached.commitments.length === input.commitments.length && cached.merkleRootHex === input.merkleRootHex) {
+    return cached.nodes;
+  }
+  const sdk = await loadSessionSdk();
+  if (!sdk) {
+    return void 0;
+  }
+  const extended = extendMerkleSnapshotNodes({
+    sdk,
+    commitments: input.commitments,
+    merkleRootHex: input.merkleRootHex,
+    ...cached ? { cachedState: cached } : {}
+  });
+  if (extended.handle !== void 0) {
+    bindImportedMerkleTree({
+      poolContract: input.poolContract,
+      handle: extended.handle,
+      state: merkleSnapshotToStateFile({
+        commitments: input.commitments,
+        merkleRootHex: input.merkleRootHex,
+        ...extended.nodes ? { nodes: extended.nodes } : {}
+      })
+    });
+  }
+  return extended.nodes;
+}
+function withdrawMerkleWitnessFromTree(input) {
+  const session = asLeanImtSessionApi(input.sdk);
+  const handle = merkleTreeHandleForState(input.state);
+  if (session && handle !== void 0) {
+    return session.buildWithdrawMerkleWitnessFromHandle(input.coin, handle);
+  }
+  return input.sdk.buildWithdrawMerkleWitness(input.coin, input.state);
+}
+
+// src/transact/proofs/confidential/helpers.ts
 var MIN_CONFIDENTIAL_TRANSFER_STROOPS = 1n;
 var ZERO_STROOPS = 0n;
 function withdrawWitnessForCoin(parameters) {
   const { sdk, coin, state } = parameters;
-  const witness = sdk.buildWithdrawMerkleWitness(coin, state);
+  const witness = withdrawMerkleWitnessFromTree({ sdk, coin, state });
   const withdrawApplicationId = coin.application_id ?? parameters.applicationId;
   const withdrawObject = withdrawObjectFromMerkleWitness(
     witness,
@@ -419,7 +648,7 @@ import {
   DEMO_AUDIT_PUBLIC_KEY,
   resolveTransactionAuditParams
 } from "@arcanetech/stellar-privacy-pool-zk-sdk";
-import { Buffer as Buffer4 } from "buffer";
+import { Buffer as Buffer5 } from "buffer";
 var UNCOMPRESSED_PREFIX = "04";
 var UNCOMPRESSED_HEX_LENGTH = 130;
 var XY_HEX_LENGTH = 128;
@@ -446,7 +675,7 @@ function parseAuditPublicKeyFromEnvHex(raw) {
       "Audit public key must be uncompressed 65-byte hex (04 + X + Y) or 64-byte X+Y hex"
     );
   }
-  const bytes = Buffer4.from(payload, "hex");
+  const bytes = Buffer5.from(payload, "hex");
   const auditPublicKeyXDecimal = BigInt(
     `0x${bytes.subarray(0, X_OFFSET_END).toString("hex")}`
   ).toString(DECIMAL_RADIX);
@@ -489,13 +718,13 @@ import { ed25519PubkeyPayloadHexToWithdrawFrDecimals } from "@arcanetech/stellar
 
 // src/transact/stellar/account.ts
 import { StrKey as StrKey3 } from "@stellar/stellar-sdk";
-import { Buffer as Buffer5 } from "buffer";
+import { Buffer as Buffer6 } from "buffer";
 var MUXED_ACCOUNT_ID_BYTE_LENGTH = 8;
 var ED25519_PUBLIC_KEY_BYTE_LENGTH = 32;
 function ed25519HexFromGAddress(trimmed) {
   try {
     const raw = StrKey3.decodeEd25519PublicKey(trimmed);
-    return Buffer5.from(raw).toString("hex");
+    return Buffer6.from(raw).toString("hex");
   } catch {
     return void 0;
   }
@@ -782,10 +1011,11 @@ async function proveSingleWithdrawTransaction(parameters) {
   );
 }
 function buildPrimaryWithdrawForCoin(parameters) {
-  const witness = parameters.sdk.buildWithdrawMerkleWitness(
-    parameters.coin,
-    parameters.state
-  );
+  const witness = withdrawMerkleWitnessFromTree({
+    sdk: parameters.sdk,
+    coin: parameters.coin,
+    state: parameters.state
+  });
   const privKeyScalar = privKeyScalarDecimalFromRecipientScalarHex(
     parameters.privKeyScalarHex
   );
@@ -1207,23 +1437,6 @@ import {
   randomFrDecimal253,
   scalarHexToFrDecimal as scalarHexToFrDecimal2
 } from "@arcanetech/stellar-privacy-pool-zk-sdk";
-
-// src/transact/merkle/field-decimal.ts
-import { Buffer as Buffer6 } from "buffer";
-var BN254 = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
-var MERKLE_ROOT_BYTE_LENGTH = 32;
-var DECIMAL_STRING_RADIX = 10;
-function merkleRootBufferToFrDecimal(root) {
-  if (root.length !== MERKLE_ROOT_BYTE_LENGTH) {
-    throw new Error(
-      `expected ${MERKLE_ROOT_BYTE_LENGTH}-byte merkle root, got ${root.length}`
-    );
-  }
-  const hex = Buffer6.from(root).toString("hex");
-  return (BigInt(`0x${hex}`) % BN254).toString(DECIMAL_STRING_RADIX);
-}
-
-// src/transact/pool/prepare-deposit-proof.ts
 function userDepositSlot(input) {
   return {
     value: input.coin.value,
@@ -1455,6 +1668,7 @@ function createPrivacyPoolService(input) {
 var configuredPrivacyPoolService;
 function configurePrivacyPoolService(service) {
   configuredPrivacyPoolService = service;
+  registerMerkleSessionSdkHost(service);
 }
 function getPrivacyPoolService() {
   if (!configuredPrivacyPoolService) {
@@ -3112,7 +3326,8 @@ function poolMerkleStateToCachedView(state) {
   return {
     commitments: state.commitments,
     updatedAt: state.updatedAt,
-    merkleRootHex: state.merkleRootHex
+    merkleRootHex: state.merkleRootHex,
+    ...state.nodes ? { nodes: state.nodes } : {}
   };
 }
 
@@ -3245,6 +3460,65 @@ function reuseCachedCommitments(input) {
   return cachedCommitments;
 }
 
+// src/transact/merkle/persist-fetched.ts
+function cachedMerkleUnchanged(cachedState, commitments, merkleRootHex) {
+  if (!cachedState) {
+    return false;
+  }
+  if (cachedState.commitments.length !== commitments.length) {
+    return false;
+  }
+  return cachedState.merkleRootHex === merkleRootHex;
+}
+function viewFromCachedMerkle(cachedState, merkleRootHex) {
+  return {
+    commitments: cachedState.commitments,
+    updatedAt: cachedState.updatedAt,
+    merkleRootHex: cachedState.merkleRootHex ?? merkleRootHex,
+    commitmentCount: cachedState.commitments.length,
+    ...cachedState.nodes ? { nodes: cachedState.nodes } : {}
+  };
+}
+function merkleStateForPersist(input) {
+  return {
+    poolContract: input.poolContractId,
+    commitments: input.commitments,
+    commitmentCount: input.commitments.length,
+    merkleRootHex: input.merkleRootHex,
+    updatedAt: input.updatedAt,
+    ...input.nodes ? { nodes: input.nodes } : {}
+  };
+}
+async function persistFetchedMerkleState(input) {
+  const cachedState = input.cachedState;
+  if (cachedMerkleUnchanged(cachedState, input.commitments, input.merkleRootHex) && cachedState) {
+    return viewFromCachedMerkle(cachedState, input.merkleRootHex);
+  }
+  const nodes = await resolveExtendedMerkleNodes({
+    poolContract: input.poolContractId,
+    commitments: input.commitments,
+    merkleRootHex: input.merkleRootHex,
+    ...cachedState ? { cachedState } : {}
+  });
+  const updatedAt = Date.now();
+  await input.poolMerkleState?.set(
+    merkleStateForPersist({
+      poolContractId: input.poolContractId,
+      commitments: input.commitments,
+      merkleRootHex: input.merkleRootHex,
+      updatedAt,
+      ...nodes ? { nodes } : {}
+    })
+  );
+  return {
+    commitments: input.commitments,
+    updatedAt,
+    merkleRootHex: input.merkleRootHex,
+    commitmentCount: input.commitments.length,
+    ...nodes ? { nodes } : {}
+  };
+}
+
 // src/transact/merkle/fetch-contract.ts
 async function fetchAndMergeMerkleState(parameters) {
   const client = createPoolClient(parameters);
@@ -3337,43 +3611,6 @@ async function loadCommitments(input) {
   });
   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;
@@ -3486,13 +3723,19 @@ var walletPrivateAddressRecordSchema = z.object({
   privateAddress: z.string().min(1),
   createdAt: z.number()
 });
+var leanImtNodeSchema = z.object({
+  level: z.number().int().nonnegative(),
+  index: z.number().int().nonnegative(),
+  value: z.string().min(1)
+});
 var poolMerkleStateSchema = z.object({
   poolContract: z.string().min(1),
   commitments: z.array(z.string()),
   commitmentCount: z.number().int().nonnegative(),
   merkleRootHex: z.string().min(1),
   updatedAt: z.number(),
-  syncedLedger: z.number().int().optional()
+  syncedLedger: z.number().int().optional(),
+  nodes: z.array(leanImtNodeSchema).optional()
 });
 var leafEphemeralSchema = z.object({
   poolContract: z.string().min(1),
@@ -4905,6 +5148,7 @@ function createPoolMerkleService(context) {
     async appendPoolCommitments(input) {
       const current = await this.getPoolMerkleState(input.poolContract);
       const mergedCommitments = [...current?.commitments ?? [], ...input.commitments];
+      const nodes = input.nodes ?? (input.commitments.length === 0 ? current?.nodes : void 0);
       await this.setPoolMerkleState(
         withoutUndefinedFields({
           poolContract: input.poolContract,
@@ -4912,7 +5156,8 @@ function createPoolMerkleService(context) {
           commitmentCount: mergedCommitments.length,
           merkleRootHex: input.merkleRootHex,
           updatedAt: Date.now(),
-          syncedLedger: input.syncedLedger ?? current?.syncedLedger
+          syncedLedger: input.syncedLedger ?? current?.syncedLedger,
+          nodes
         })
       );
     }
@@ -5441,7 +5686,11 @@ async function loadMerkleState(environment, walletPublicKey) {
     transactEnvironment: environment,
     ...environment.poolMerkleState ? { poolMerkleState: environment.poolMerkleState } : {}
   });
-  return { commitments: merged.commitments };
+  return merkleSnapshotToStateFile({
+    commitments: merged.commitments,
+    merkleRootHex: merged.merkleRootHex,
+    ...merged.nodes ? { nodes: merged.nodes } : {}
+  });
 }
 
 // src/transact/escrow/require-escrow-spend-scalar.ts
@@ -5588,7 +5837,8 @@ async function buildSpendProofContextAtExecute(input) {
     input.prepared.intent.asset
   );
   const coin = requireCoinNoteFromRecord(primaryRecord);
-  const { commitments } = await loadMerkleState(input.environment, walletPublicKey);
+  const merkleState = await loadMerkleState(input.environment, walletPublicKey);
+  const commitments = merkleState.commitments;
   const leafIndex = findCommitmentLeafIndex(commitments, coin.commitment);
   if (leafIndex < 0) {
     throw new Error("Coin commitment not found in on-chain Merkle state.");
@@ -5605,6 +5855,7 @@ async function buildSpendProofContextAtExecute(input) {
     tokenAddress,
     coin,
     commitments,
+    merkleState,
     ephemeral,
     senderPrivKeyScalarHex,
     recipientPrivateAddressStpl1: input.recipientPrivateAddressStpl1
@@ -5670,7 +5921,7 @@ async function buildSingleTransferProofAtExecute(input) {
   const changeStroops = BigInt(context.coin.value) - input.prepared.intent.amount - (feeOutput?.requiredFee ?? 0n);
   const proof = await prepareConfidentialTransferProof({
     coin: context.coin,
-    state: { commitments: context.commitments },
+    state: context.merkleState,
     senderPrivKeyScalarHex: context.senderPrivKeyScalarHex,
     depositorEphemeralKey: serializeEphemeralKeyString({
       xHex: context.ephemeral.xHex,
@@ -5707,7 +5958,7 @@ async function buildDualTransferProofAtExecute(input) {
   const proof = await prepareConfidentialTransferProofDual({
     coinA: context.coin,
     coinB: secondary.coin,
-    state: { commitments: context.commitments },
+    state: context.merkleState,
     senderPrivKeyScalarHex: context.senderPrivKeyScalarHex,
     ephemeralAKey: serializeEphemeralKeyString({
       xHex: context.ephemeral.xHex,
@@ -5955,7 +6206,7 @@ async function finalizeSingleWithdrawAtExecute(prepared, environment, poolServic
   });
   const proof = await poolService.prepareWithdrawTransactProof({
     coin: context.coin,
-    state: { commitments: context.commitments },
+    state: context.merkleState,
     destinationStellarAddress: prepared.intent.to,
     privKeyScalarHex: context.senderPrivKeyScalarHex,
     depositorEphemeralKey: serializeEphemeralKeyString({
@@ -6008,7 +6259,7 @@ async function finalizeDualWithdrawAtExecute(prepared, environment, poolService,
   const proof = await poolService.prepareWithdrawTransactProofDual({
     coinA: context.coin,
     coinB: secondary.coin,
-    state: { commitments: context.commitments },
+    state: context.merkleState,
     destinationStellarAddress: prepared.intent.to,
     privKeyScalarHex: context.senderPrivKeyScalarHex,
     ...dualWithdrawEphemeralKeys({ context, secondary }),