@arcanetech/privacy-sdk-stellar 0.5.4 → 0.6.2

package/dist/index.js

@@ -452,6 +452,261 @@ function buildPrivateRecordFromDeposit(input) {
   };
 }
 
+// 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 importHandle2(sdk, state) {
+  try {
+    return sdk.importLeanImtFromState(state);
+  } catch {
+    return void 0;
+  }
+}
+function merkleTreeHandleForState(state) {
+  return handlesByKey.get(merkleSessionKey(state));
+}
+function bindImportedMerkleTree(input) {
+  rememberHandle(input.poolContract, merkleSessionKey(input.state), input.handle);
+}
+async function bindPoolMerkleTree(state) {
+  const sdk = await loadSessionSdk();
+  if (!sdk) {
+    return void 0;
+  }
+  const snapshot = merkleSnapshotToStateFile(state);
+  const key = merkleSessionKey(snapshot);
+  const existing = sessionsByPool.get(state.poolContract);
+  if (existing?.key === key) {
+    return existing.handle;
+  }
+  const handle = importHandle2(sdk, snapshot);
+  if (handle === void 0) {
+    return void 0;
+  }
+  if (existing) {
+    sdk.dropLeanImt(existing.handle);
+  }
+  rememberHandle(state.poolContract, key, handle);
+  return 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/pool/service.ts
 import {
   decodeDecodedEphemeralKey
@@ -512,18 +767,18 @@ function privateAddressSdk(sdk) {
 import { withdrawObjectFromMerkleWitness as withdrawObjectFromMerkleWitness2 } from "@arcanetech/stellar-privacy-pool-zk-sdk";
 
 // src/transact/proofs/transaction-input.ts
-import { Buffer as Buffer5 } from "buffer";
+import { Buffer as Buffer6 } from "buffer";
 import { StrKey as StrKey2 } from "@stellar/stellar-sdk";
 
 // src/transact/stellar/token-contract.ts
-import { Buffer as Buffer4 } from "buffer";
+import { Buffer as Buffer5 } from "buffer";
 import { StrKey } from "@stellar/stellar-sdk";
 var CONTRACT_ID_BYTE_LENGTH = 32;
 var HEX_CHARS_PER_BYTE = 2;
 var CONTRACT_ID_HEX_CHAR_LENGTH = CONTRACT_ID_BYTE_LENGTH * HEX_CHARS_PER_BYTE;
 var CONTRACT_ID_HEX = /^(?:0x)?([0-9a-f]{64})$/i;
 function encodeContractFromHex(hexPayload) {
-  return StrKey.encodeContract(Buffer4.from(hexPayload, "hex"));
+  return StrKey.encodeContract(Buffer5.from(hexPayload, "hex"));
 }
 function normalizeSorobanContractId(raw) {
   const trimmed = raw.trim();
@@ -556,14 +811,14 @@ var ZERO_PUBLIC_WITHDRAW_ADDRESS = {
 var CONTRACT_ADDRESS_HALF_BYTES = 16;
 var CONTRACT_ADDRESS_BYTES = 32;
 function bytes16ToDecimal(bytes) {
-  return BigInt(`0x${Buffer5.from(bytes).toString("hex")}`).toString();
+  return BigInt(`0x${Buffer6.from(bytes).toString("hex")}`).toString();
 }
 function decimalToBytes16(value) {
   const hex = BigInt(value).toString(16).padStart(CONTRACT_ADDRESS_HALF_BYTES * 2, "0");
   if (hex.length > CONTRACT_ADDRESS_HALF_BYTES * 2) {
     throw new Error("Asset leg does not fit into 16 bytes.");
   }
-  return Buffer5.from(hex, "hex");
+  return Buffer6.from(hex, "hex");
 }
 function tokenAddressFrParts(tokenAddress) {
   const normalized = resolveTokenContractId(tokenAddress);
@@ -605,7 +860,7 @@ function tokenAddressToAssetLeg(tokenAddress) {
   return [hi, lo];
 }
 function assetLegToTokenAddress(assetHi, assetLo) {
-  const payload = Buffer5.concat([decimalToBytes16(assetHi), decimalToBytes16(assetLo)]);
+  const payload = Buffer6.concat([decimalToBytes16(assetHi), decimalToBytes16(assetLo)]);
   return StrKey2.encodeContract(payload);
 }
 function buildZeroPublicLegs(publicNInputs = 1, publicNOutputs = 1) {
@@ -686,7 +941,7 @@ 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,
@@ -873,7 +1128,7 @@ import {
   DEMO_AUDIT_PUBLIC_KEY,
   resolveTransactionAuditParams
 } from "@arcanetech/stellar-privacy-pool-zk-sdk";
-import { Buffer as Buffer6 } from "buffer";
+import { Buffer as Buffer7 } from "buffer";
 var UNCOMPRESSED_PREFIX = "04";
 var UNCOMPRESSED_HEX_LENGTH = 130;
 var XY_HEX_LENGTH = 128;
@@ -900,7 +1155,7 @@ function parseAuditPublicKeyFromEnvHex(raw) {
       "Audit public key must be uncompressed 65-byte hex (04 + X + Y) or 64-byte X+Y hex"
     );
   }
-  const bytes = Buffer6.from(payload, "hex");
+  const bytes = Buffer7.from(payload, "hex");
   const auditPublicKeyXDecimal = BigInt(
     `0x${bytes.subarray(0, X_OFFSET_END).toString("hex")}`
   ).toString(DECIMAL_RADIX);
@@ -943,13 +1198,13 @@ import { ed25519PubkeyPayloadHexToWithdrawFrDecimals } from "@arcanetech/stellar
 
 // src/transact/stellar/account.ts
 import { StrKey as StrKey3 } from "@stellar/stellar-sdk";
-import { Buffer as Buffer7 } from "buffer";
+import { Buffer as Buffer8 } 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 Buffer7.from(raw).toString("hex");
+    return Buffer8.from(raw).toString("hex");
   } catch {
     return void 0;
   }
@@ -1236,10 +1491,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
   );
@@ -1661,23 +1917,6 @@ import {
   randomFrDecimal253,
   scalarHexToFrDecimal as scalarHexToFrDecimal2
 } from "@arcanetech/stellar-privacy-pool-zk-sdk";
-
-// src/transact/merkle/field-decimal.ts
-import { Buffer as Buffer8 } 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 = Buffer8.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,
@@ -1909,6 +2148,7 @@ function createPrivacyPoolService(input) {
 var configuredPrivacyPoolService;
 function configurePrivacyPoolService(service) {
   configuredPrivacyPoolService = service;
+  registerMerkleSessionSdkHost(service);
 }
 function getPrivacyPoolService() {
   if (!configuredPrivacyPoolService) {
@@ -1927,7 +2167,8 @@ function poolMerkleStateToCachedView(state) {
   return {
     commitments: state.commitments,
     updatedAt: state.updatedAt,
-    merkleRootHex: state.merkleRootHex
+    merkleRootHex: state.merkleRootHex,
+    ...state.nodes ? { nodes: state.nodes } : {}
   };
 }
 
@@ -2060,6 +2301,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);
@@ -2152,43 +2452,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/engine/prepare/shared.ts
 async function resolveTokenContractId2(environment, assetId) {
@@ -2263,7 +2526,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 } : {}
+  });
 }
 function enrichPreparedOperation(prepared, outputRecords, artifacts) {
   return {
@@ -2772,13 +3039,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),
@@ -4337,6 +4610,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,
@@ -4344,7 +4618,8 @@ function createPoolMerkleService(context) {
           commitmentCount: mergedCommitments.length,
           merkleRootHex: input.merkleRootHex,
           updatedAt: Date.now(),
-          syncedLedger: input.syncedLedger ?? current?.syncedLedger
+          syncedLedger: input.syncedLedger ?? current?.syncedLedger,
+          nodes
         })
       );
     }
@@ -5614,12 +5889,46 @@ function createDeliveriesStateDelegates(state) {
   };
 }
 
+// src/transact/merkle/write-snapshot.ts
+async function writePoolMerkleState(input) {
+  await input.setPoolMerkleState(input.state);
+  await bindPoolMerkleTree(input.state);
+}
+async function appendPoolMerkleCommitments(input) {
+  const current = await input.getPoolMerkleState(input.payload.poolContract);
+  const merged = [...current?.commitments ?? [], ...input.payload.commitments];
+  const nodes = input.payload.nodes ?? await resolveExtendedMerkleNodes({
+    poolContract: input.payload.poolContract,
+    commitments: merged,
+    merkleRootHex: input.payload.merkleRootHex,
+    ...current ? { cachedState: poolMerkleStateToCachedView(current) } : {}
+  });
+  await input.appendPoolCommitments({
+    poolContract: input.payload.poolContract,
+    commitments: input.payload.commitments,
+    merkleRootHex: input.payload.merkleRootHex,
+    ...input.payload.syncedLedger === void 0 ? {} : { syncedLedger: input.payload.syncedLedger },
+    ...nodes ? { nodes } : {}
+  });
+  const written = await input.getPoolMerkleState(input.payload.poolContract);
+  if (written) {
+    await bindPoolMerkleTree(written);
+  }
+}
+
 // src/client/state-delegates/pool.ts
 function createPoolStateDelegates(state) {
   return {
     getPoolMerkleState: (poolContract) => state.getPoolMerkleState(poolContract),
-    setPoolMerkleState: (poolState) => state.setPoolMerkleState(poolState),
-    appendPoolCommitments: (input) => state.appendPoolCommitments(input),
+    setPoolMerkleState: (poolState) => writePoolMerkleState({
+      setPoolMerkleState: (next) => state.setPoolMerkleState(next),
+      state: poolState
+    }),
+    appendPoolCommitments: (input) => appendPoolMerkleCommitments({
+      getPoolMerkleState: (poolContract) => state.getPoolMerkleState(poolContract),
+      appendPoolCommitments: (payload) => state.appendPoolCommitments(payload),
+      payload: input
+    }),
     getLeafEphemeral: (input) => state.getLeafEphemeral(input),
     setLeafEphemeral: (ephemeral) => state.setLeafEphemeral(ephemeral)
   };
@@ -5672,12 +5981,42 @@ function createStateDelegates(state) {
   };
 }
 
+// src/client/hydrate-state.ts
+async function hydratePoolMerkleStates(client, states) {
+  for (const poolState of states ?? []) {
+    await client.setPoolMerkleState(poolState);
+  }
+}
+async function hydrateWalletAddresses(client, snapshot) {
+  for (const record of snapshot.walletPrivateAddressRecords ?? []) {
+    await client.saveWalletPrivateAddressRecord(record);
+  }
+  for (const scalar of snapshot.walletPrivateAddressScalars ?? []) {
+    await client.saveWalletPrivateAddressScalar(scalar);
+  }
+  for (const entry of snapshot.walletDefaultPrivateAddressNonces ?? []) {
+    await client.setWalletDefaultPrivateAddressNonce(entry);
+  }
+}
+async function hydrateStellarPrivacyState(client, snapshot) {
+  if (snapshot.assets && snapshot.assets.length > 0) {
+    await client.replaceAssets(snapshot.assets);
+  }
+  await hydratePoolMerkleStates(client, snapshot.poolMerkleStates);
+  if (snapshot.privateRecords && snapshot.privateRecords.length > 0) {
+    await client.upsertPrivateRecords(snapshot.privateRecords);
+  }
+  await hydrateWalletAddresses(client, snapshot);
+}
+
 // src/client/client.ts
 function createStellarPrivacyClientInstance(config) {
   const composed = composeStellarPrivacyClient(config);
+  const stateDelegates = createStateDelegates(composed.state);
   return {
     state: composed.state,
-    ...createStateDelegates(composed.state),
+    ...stateDelegates,
+    hydrateState: (snapshot) => hydrateStellarPrivacyState(stateDelegates, snapshot),
     deposit: (intent) => composed.operations.deposit(intent),
     transfer: (intent) => composed.operations.transfer(intent),
     withdraw: (intent) => composed.operations.withdraw(intent),
@@ -5998,7 +6337,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.");
@@ -6015,6 +6355,7 @@ async function buildSpendProofContextAtExecute(input) {
     tokenAddress,
     coin,
     commitments,
+    merkleState,
     ephemeral,
     senderPrivKeyScalarHex,
     recipientPrivateAddressStpl1: input.recipientPrivateAddressStpl1
@@ -6516,7 +6857,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,
@@ -6553,7 +6894,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,
@@ -6801,7 +7142,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({
@@ -6854,7 +7195,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 }),