@arcanetech/privacy-sdk-stellar 0.2.3 → 0.3.0

package/dist/index.d.ts

@@ -252,6 +252,12 @@ interface StellarKytEnvironment {
 }
 interface StellarTransactEnvironment {
     network: StellarNetworkConfig;
+    /**
+     * Nonce (persistent storage key) of the pool's `ZkConfig` entry this
+     * environment's proofs/circuit shape target. Defaults to `0n` (the
+     * standard circuit) when omitted.
+     */
+    zkConfigNonce?: bigint;
     auditPublicKey?: AuditPublicKey;
     kyt: StellarKytEnvironment;
     signTransaction?: StellarSignTransaction;

package/dist/index.js

@@ -486,7 +486,7 @@ function createInternalPoolContractClient(input) {
     networkPassphrase: input.networkPassphrase,
     walletPublicKey: input.walletPublicKey
   });
-  return new PrivacyPoolContractClient({
+  const client = new PrivacyPoolContractClient({
     contractId: input.contractId,
     networkPassphrase: input.networkPassphrase,
     rpcUrl: input.sorobanRpcUrl,
@@ -494,6 +494,7 @@ function createInternalPoolContractClient(input) {
     publicKey: input.walletPublicKey,
     signTransaction: signBinding
   });
+  return client;
 }
 
 // src/contracts/registry/create-registry-client.ts
@@ -1693,7 +1694,7 @@ function pickRecordsForSpendAmount(input) {
     if (selectedTotal >= input.amount) {
       return selected;
     }
-    if (input.kind === "transfer" && selected.length >= 2) {
+    if ((input.kind === "transfer" || input.kind === "withdraw") && selected.length >= 2) {
       throw insufficientStateError3(
         "missing_private_records",
         "Storage does not contain enough private records for this operation.",
@@ -6415,12 +6416,17 @@ function enrichWithdrawOutputRecords(prepared, proof) {
     precommitementHex: changeCoin.precommitementHex
   }));
 }
-async function finalizeWithdrawAtExecute(prepared, environment, poolService) {
-  if (prepared.kind !== "withdraw") {
-    throw new Error("Withdraw finalize requires a withdraw operation.");
-  }
-  const withdrawIntent = prepared.intent;
-  const withdrawFrom = withdrawIntent.from;
+function buildWithdrawFinalizeArtifacts(proof, context) {
+  return {
+    proofHex: proof.proof_hex,
+    publicHex: proof.public_hex,
+    applicationIdsPlaintext: proof.applicationIdsPlaintext,
+    tokenAddress: context.tokenAddress,
+    walletPublicKey: context.walletPublicKey,
+    executeFinalizeRequired: false
+  };
+}
+async function finalizeSingleWithdrawAtExecute(prepared, environment, poolService, withdrawFrom) {
   const context = await buildSpendProofContextAtExecute({
     prepared,
     environment,
@@ -6441,14 +6447,71 @@ async function finalizeWithdrawAtExecute(prepared, environment, poolService) {
     tokenAddress: context.tokenAddress
   });
   enrichWithdrawOutputRecords(prepared, proof);
-  return {
-    proofHex: proof.proof_hex,
-    publicHex: proof.public_hex,
-    applicationIdsPlaintext: proof.applicationIdsPlaintext,
-    tokenAddress: context.tokenAddress,
+  return buildWithdrawFinalizeArtifacts(proof, context);
+}
+async function finalizeDualWithdrawAtExecute(prepared, environment, poolService, withdrawFrom) {
+  const [, secondaryRecord] = prepared.consumedRecords;
+  if (!secondaryRecord) {
+    throw new Error("Dual withdraw execution requires two private input records.");
+  }
+  const context = await buildSpendProofContextAtExecute({
+    prepared,
+    environment,
+    recipientPrivateAddressStpl1: withdrawFrom
+  });
+  const secondary = await readCoinEphemeralForRecord({
+    record: secondaryRecord,
+    environment,
     walletPublicKey: context.walletPublicKey,
-    executeFinalizeRequired: false
-  };
+    commitments: context.commitments
+  });
+  const totalNotes = BigInt(context.coin.value) + BigInt(secondary.coin.value);
+  const changeStroops = totalNotes - prepared.intent.amount;
+  const proof = await poolService.prepareWithdrawTransactProofDual({
+    coinA: context.coin,
+    coinB: secondary.coin,
+    state: { commitments: context.commitments },
+    destinationStellarAddress: prepared.intent.to,
+    privKeyScalarHex: context.senderPrivKeyScalarHex,
+    depositorEphemeralAKey: serializeEphemeralKeyString({
+      xHex: context.ephemeral.xHex,
+      yHex: context.ephemeral.yHex
+    }),
+    depositorEphemeralBKey: serializeEphemeralKeyString({
+      xHex: secondary.ephemeral.xHex,
+      yHex: secondary.ephemeral.yHex
+    }),
+    withdrawAmountStroops: prepared.intent.amount,
+    changePrivateAddressStpl1: changeStroops > 0n ? withdrawFrom : void 0,
+    tokenAddress: context.tokenAddress
+  });
+  enrichWithdrawOutputRecords(prepared, proof);
+  return buildWithdrawFinalizeArtifacts(proof, context);
+}
+async function finalizeWithdrawAtExecute(prepared, environment, poolService) {
+  if (prepared.kind !== "withdraw") {
+    throw new Error("Withdraw finalize requires a withdraw operation.");
+  }
+  const withdrawIntent = prepared.intent;
+  const withdrawFrom = withdrawIntent.from;
+  const recordCount = prepared.consumedRecords.length;
+  if (recordCount === 1) {
+    return finalizeSingleWithdrawAtExecute(
+      prepared,
+      environment,
+      poolService,
+      withdrawFrom
+    );
+  }
+  if (recordCount === 2) {
+    return finalizeDualWithdrawAtExecute(
+      prepared,
+      environment,
+      poolService,
+      withdrawFrom
+    );
+  }
+  throw new Error("Confidential withdraw execution supports at most two input notes.");
 }
 async function finalizeSpendOperationAtExecute(prepared, environment, poolService) {
   if (prepared.kind !== "transfer" && prepared.kind !== "withdraw") {
@@ -6606,6 +6669,12 @@ async function registerKytPassage(parameters) {
   await waitForKytRegistration({ server, hash: result.hash });
 }
 
+// src/transact/environment/zk-config-nonce.ts
+var DEFAULT_ZK_CONFIG_NONCE = 0n;
+function resolveZkConfigNonce(transactEnvironment) {
+  return transactEnvironment.zkConfigNonce ?? DEFAULT_ZK_CONFIG_NONCE;
+}
+
 // src/transact/kyt/passage/inspect.ts
 function buildApplicationIdHints(applicationId) {
   return [applicationId, applicationId, applicationId, applicationId];
@@ -6659,6 +6728,7 @@ async function requestKytPassageForPoolInteraction(input) {
           decryptedAuditSlots: input.decryptedAuditSlots,
           onboarding: input.onboarding,
           nonce: buildNonce(),
+          zkConfigNonce: resolveZkConfigNonce(input.transactEnvironment),
           currentLedger
         },
         kytJsonReplacer
@@ -6681,11 +6751,123 @@ async function requestKytPassageForPoolInteraction(input) {
   return body;
 }
 
+// src/transact/submit/zk-config-ttl.ts
+import {
+  Address as Address2,
+  Operation as Operation2,
+  SorobanDataBuilder,
+  TransactionBuilder as TransactionBuilder2,
+  rpc as rpc4,
+  xdr as xdr3
+} from "@stellar/stellar-sdk";
+var ZK_CONFIG_TTL_THRESHOLD_LEDGERS = 1e5;
+var ZK_CONFIG_TTL_EXTEND_TO_LEDGERS = 5e5;
+var EXTEND_TTL_FEE_STROOPS = "1000000";
+var EXTEND_TTL_TIMEOUT_SECONDS = 300;
+var EXTEND_TTL_MAX_POLLS = 60;
+var EXTEND_TTL_POLL_INTERVAL_MS = 1e3;
+async function waitForExtendFootprintTtlConfirmation(parameters) {
+  for (let attempt = 0; attempt < EXTEND_TTL_MAX_POLLS; attempt += 1) {
+    const response = await parameters.server.getTransaction(parameters.hash);
+    if (response.status === "SUCCESS") {
+      return;
+    }
+    if (response.status === "FAILED") {
+      throw new Error("ZK config TTL extension failed on-chain");
+    }
+    await new Promise((resolve) => {
+      setTimeout(resolve, EXTEND_TTL_POLL_INTERVAL_MS);
+    });
+  }
+  throw new Error("ZK config TTL extension was not confirmed in time");
+}
+function zkConfigLedgerKey(contractId, nonce) {
+  const configKeyScValue = xdr3.ScVal.scvVec([
+    xdr3.ScVal.scvSymbol("Config"),
+    xdr3.ScVal.scvU64(xdr3.Uint64.fromString(nonce.toString()))
+  ]);
+  return xdr3.LedgerKey.contractData(
+    new xdr3.LedgerKeyContractData({
+      contract: new Address2(contractId).toScAddress(),
+      key: configKeyScValue,
+      durability: xdr3.ContractDataDurability.persistent()
+    })
+  );
+}
+async function needsTtlExtension(parameters) {
+  const [entriesResponse, latestLedger] = await Promise.all([
+    parameters.server.getLedgerEntries(parameters.ledgerKey),
+    parameters.server.getLatestLedger()
+  ]);
+  const entry = entriesResponse.entries.at(0);
+  if (!entry || entry.liveUntilLedgerSeq === void 0) {
+    return false;
+  }
+  const remainingLedgers = entry.liveUntilLedgerSeq - latestLedger.sequence;
+  return remainingLedgers < ZK_CONFIG_TTL_THRESHOLD_LEDGERS;
+}
+async function submitExtendFootprintTtlTransaction(parameters) {
+  const sourceAccount = await parameters.server.getAccount(parameters.sourcePublicKey);
+  const transaction = new TransactionBuilder2(sourceAccount, {
+    fee: EXTEND_TTL_FEE_STROOPS,
+    networkPassphrase: parameters.networkPassphrase
+  }).addOperation(
+    Operation2.extendFootprintTtl({ extendTo: ZK_CONFIG_TTL_EXTEND_TO_LEDGERS })
+  ).setSorobanData(
+    new SorobanDataBuilder().setReadOnly([parameters.ledgerKey]).build()
+  ).setTimeout(EXTEND_TTL_TIMEOUT_SECONDS).build();
+  const preparedTransaction = await parameters.server.prepareTransaction(transaction);
+  const { signedTxXdr } = await parameters.signTransaction({
+    xdr: preparedTransaction.toXDR(),
+    networkPassphrase: parameters.networkPassphrase,
+    address: parameters.sourcePublicKey
+  });
+  const signedTransaction = TransactionBuilder2.fromXDR(
+    signedTxXdr,
+    parameters.networkPassphrase
+  );
+  const result = await parameters.server.sendTransaction(signedTransaction);
+  const status = String(result.status);
+  if (status !== "PENDING" && status !== "SUCCESS") {
+    throw new Error(`ZK config TTL extension submit failed: ${status}`);
+  }
+  await waitForExtendFootprintTtlConfirmation({
+    server: parameters.server,
+    hash: result.hash
+  });
+}
+async function extendZkConfigTtlIfNeeded(parameters) {
+  if (!parameters.signTransaction) {
+    return;
+  }
+  const server = new rpc4.Server(parameters.sorobanRpcUrl, { allowHttp: true });
+  const ledgerKey = zkConfigLedgerKey(parameters.contractId, parameters.nonce);
+  if (!await needsTtlExtension({ server, ledgerKey })) {
+    return;
+  }
+  await submitExtendFootprintTtlTransaction({
+    server,
+    ledgerKey,
+    networkPassphrase: parameters.networkPassphrase,
+    sourcePublicKey: parameters.sourcePublicKey,
+    signTransaction: parameters.signTransaction
+  });
+}
+
 // src/transact/submit/pool-transact.ts
 import { Buffer as Buffer17 } from "buffer";
 async function submitPoolTransact(parameters) {
+  await extendZkConfigTtlIfNeeded({
+    sorobanRpcUrl: parameters.sorobanRpcUrl,
+    networkPassphrase: parameters.networkPassphrase,
+    contractId: parameters.contractId,
+    nonce: parameters.nonce,
+    sourcePublicKey: parameters.from,
+    signTransaction: parameters.transactEnvironment.signTransaction
+  });
   const assembledTransaction = await parameters.contractClient.transact({
     from: parameters.from,
+    nonce: parameters.nonce,
     proof_bytes: Buffer17.from(parameters.proofHex.replace(/^0x/iu, ""), "hex"),
     pub_signals_bytes: Buffer17.from(parameters.publicHex.replace(/^0x/iu, ""), "hex"),
     onboarding: parameters.onboarding,
@@ -6724,11 +6906,16 @@ async function submitSorobanConfidentialTransfer(input) {
   });
   return submitPoolTransact({
     contractClient: poolClient,
+    contractId: input.contractId,
     from: input.walletPublicKey,
+    nonce: resolveZkConfigNonce(input.transactEnvironment),
     proofHex: input.proofHex,
     publicHex: input.publicHex,
     ...input.onboarding ? { onboarding: input.onboarding } : {},
-    approval
+    approval,
+    networkPassphrase: input.networkPassphrase,
+    sorobanRpcUrl: input.sorobanRpcUrl,
+    transactEnvironment: input.transactEnvironment
   });
 }
 
@@ -6757,10 +6944,15 @@ async function submitPreparedDeposit(prepared, environment) {
   });
   return submitPoolTransact({
     contractClient: poolClient,
+    contractId: environment.network.poolContract,
     from: artifacts.walletPublicKey,
+    nonce: resolveZkConfigNonce(environment),
     proofHex: artifacts.proofHex,
     publicHex: artifacts.publicHex,
-    approval
+    approval,
+    networkPassphrase: environment.network.networkPassphrase,
+    sorobanRpcUrl: environment.network.rpcUrl,
+    transactEnvironment: environment
   });
 }
 async function submitPreparedPoolTransact(prepared, environment) {
@@ -7009,10 +7201,15 @@ async function submitSorobanDeposit(input) {
   });
   return submitPoolTransact({
     contractClient: poolClient,
+    contractId: input.contractId,
     from: input.walletPublicKey,
+    nonce: resolveZkConfigNonce(input.transactEnvironment),
     proofHex: proof_hex,
     publicHex: public_hex,
-    approval
+    approval,
+    networkPassphrase: input.networkPassphrase,
+    sorobanRpcUrl: input.sorobanRpcUrl,
+    transactEnvironment: input.transactEnvironment
   });
 }
 export {