@arcanetech/privacy-sdk-stellar 0.6.2 → 1.0.0-rc.0

package/dist/node.d.ts

@@ -340,13 +340,28 @@ interface FetchContractMerkleResult {
     nodes?: StellarLeanImtNode[];
 }
 
-type StellarTransactionDetails = {
-    txHash: string;
-    status: StellarTransactionConfirmationStatus;
-    ledger?: number;
-    createdAt?: string;
-    invokedPoolContractId?: string;
-    transferAmountRaw?: string;
+type IncomingNoteDeadReason = 'commitment_mismatch' | 'nullifier_consumed';
+type IncomingNoteAssessment = {
+    kind: 'dead';
+    reason: IncomingNoteDeadReason;
+} | {
+    kind: 'pending';
+} | {
+    kind: 'spendable';
+};
+type IncomingNoteFields = {
+    value: string;
+    nullifier: string;
+    secret: string;
+    commitment: string;
+    asset_hi: string;
+    asset_lo: string;
+    application_id?: string;
+};
+type AssessIncomingNoteInput = {
+    note: IncomingNoteFields;
+    commitmentHex: string;
+    privKeyScalarHex: string;
 };
 
 interface StellarPublicBalanceInput {
@@ -452,6 +467,20 @@ type ComposedStellarStateService = ReturnType<typeof composeStellarStateService>
 
 type StellarStateService = ComposedStellarStateService;
 
+type AssessIncomingNoteClientInput = AssessIncomingNoteInput & {
+    walletPublicKey: string;
+    poolContractId?: string;
+};
+
+type StellarTransactionDetails = {
+    txHash: string;
+    status: StellarTransactionConfirmationStatus;
+    ledger?: number;
+    createdAt?: string;
+    invokedPoolContractId?: string;
+    transferAmountRaw?: string;
+};
+
 declare function composeStellarPrivacyClient(config: ResolvedStellarPrivacyClientConfig): {
     state: {
         getTransactionStatus(txHash: string): Promise<StellarTransactionStatus | undefined>;
@@ -567,6 +596,7 @@ declare function composeStellarPrivacyClient(config: ResolvedStellarPrivacyClien
         }) => Promise<StellarTransactionStatus>;
         fetchTransactionConfirmationStatus: (txHash: string) => Promise<StellarTransactionStatus>;
         getTransactionDetails: (txHash: string) => Promise<StellarTransactionDetails>;
+        assessIncomingNote: (assessmentInput: AssessIncomingNoteClientInput) => Promise<IncomingNoteAssessment>;
         checkRegistrationStatus: (registrationInput: {
             address: StellarAddress;
             walletPublicKey: string;
@@ -675,6 +705,7 @@ type StellarPrivacyClient = {
     registerPrivateAddress: StellarPrivacyClientNetwork['registerPrivateAddress'];
     resolveTransferRecipient: StellarPrivacyClientNetwork['resolveTransferRecipient'];
     checkPrivateRecordSpendStatus: StellarPrivacyClientNetwork['checkPrivateRecordSpendStatus'];
+    assessIncomingNote: StellarPrivacyClientNetwork['assessIncomingNote'];
     waitForTransactionConfirmation: StellarPrivacyClientNetwork['waitForTransactionConfirmation'];
     fetchTransactionConfirmationStatus: StellarPrivacyClientNetwork['fetchTransactionConfirmationStatus'];
     getTransactionDetails: StellarPrivacyClientNetwork['getTransactionDetails'];

package/dist/node.js

@@ -932,14 +932,39 @@ function uniformApplicationIdHints(applicationId, nAuditSlots) {
 }
 
 // src/transact/proofs/confidential/helpers.ts
-import { withdrawObjectFromMerkleWitness } from "@arcanetech/stellar-privacy-pool-zk-sdk";
+import {
+  withdrawObjectFromEscrowMerkleWitness,
+  withdrawObjectFromMerkleWitness
+} from "@arcanetech/stellar-privacy-pool-zk-sdk";
 var MIN_CONFIDENTIAL_TRANSFER_STROOPS = 1n;
 var ZERO_STROOPS = 0n;
+function escrowSpendWitnessFromLimbs(limbs, derivedScalarHex) {
+  const nonce = limbs.nonceDecimal?.trim() ?? "";
+  if (!nonce) {
+    throw new Error("Escrow claimant limbs require nonceDecimal");
+  }
+  return {
+    nonce,
+    recipientHi: limbs.recipientHi,
+    recipientLo: limbs.recipientLo,
+    derivedScalarHex
+  };
+}
 function withdrawWitnessForCoin(parameters) {
   const { sdk, coin, state } = parameters;
   const witness = withdrawMerkleWitnessFromTree({ sdk, coin, state });
   const withdrawApplicationId = coin.application_id ?? parameters.applicationId;
-  const withdrawObject = withdrawObjectFromMerkleWitness(
+  const withdrawObject = parameters.escrow ? withdrawObjectFromEscrowMerkleWitness(
+    witness,
+    parameters.ownerPubHex,
+    withdrawApplicationId,
+    parameters.escrow.derivedScalarHex,
+    {
+      nonce: parameters.escrow.nonce,
+      recipientHi: parameters.escrow.recipientHi,
+      recipientLo: parameters.escrow.recipientLo
+    }
+  ) : withdrawObjectFromMerkleWitness(
     witness,
     parameters.ownerPubHex,
     withdrawApplicationId,
@@ -948,21 +973,21 @@ function withdrawWitnessForCoin(parameters) {
   return { witness, withdrawObject };
 }
 function dualWithdrawLegsWithSharedRoot(parameters) {
-  const legA = withdrawWitnessForCoin({
+  const shared = {
     sdk: parameters.sdk,
-    coin: parameters.coinA,
     state: parameters.state,
     ownerPubHex: parameters.ownerPubHex,
     privKeyScalar: parameters.privKeyScalar,
-    applicationId: parameters.applicationId
+    applicationId: parameters.applicationId,
+    ...parameters.escrow ? { escrow: parameters.escrow } : {}
+  };
+  const legA = withdrawWitnessForCoin({
+    ...shared,
+    coin: parameters.coinA
   });
   const legB = withdrawWitnessForCoin({
-    sdk: parameters.sdk,
-    coin: parameters.coinB,
-    state: parameters.state,
-    ownerPubHex: parameters.ownerPubHex,
-    privKeyScalar: parameters.privKeyScalar,
-    applicationId: parameters.applicationId
+    ...shared,
+    coin: parameters.coinB
   });
   if (legA.witness.stateRoot !== legB.witness.stateRoot) {
     throw new Error("Merkle state root mismatch between input coins");
@@ -1233,7 +1258,10 @@ function ed25519PublicKeyHexFromStellarAccount(address) {
 }
 
 // src/transact/encoding/priv-key-scalar-from-recipient-hex.ts
-import { canonicalBabyJubScalarFromInteger } from "@arcanetech/stellar-privacy-pool-zk-sdk";
+import {
+  canonicalBabyJubScalarFromInteger,
+  reduceDerivedEscrowSpendScalar
+} from "@arcanetech/stellar-privacy-pool-zk-sdk";
 var SCALAR_HEX_CHAR_LENGTH = 64;
 var DECIMAL_RADIX2 = 10;
 function normalizeRecipientScalarHex(hexInput) {
@@ -1256,6 +1284,25 @@ function privKeyScalarDecimalFromRecipientScalarHex(hexInput) {
   const value = BigInt(`0x${hex}`);
   return canonicalBabyJubScalarFromInteger(value).toString(DECIMAL_RADIX2);
 }
+function privKeyScalarDecimalFromDerivedEscrowHex(hexInput) {
+  const hex = normalizeRecipientScalarHex(hexInput);
+  const value = BigInt(`0x${hex}`);
+  return reduceDerivedEscrowSpendScalar(value).toString(DECIMAL_RADIX2);
+}
+function resolveTransferSpendScalars(input) {
+  const senderHex = input.senderPrivKeyScalarHex;
+  if (!input.escrowSweep) {
+    return {
+      privKeyScalar: privKeyScalarDecimalFromRecipientScalarHex(senderHex),
+      ownerScalarHex: senderHex
+    };
+  }
+  const privKeyScalar = privKeyScalarDecimalFromDerivedEscrowHex(senderHex);
+  return {
+    privKeyScalar,
+    ownerScalarHex: BigInt(privKeyScalar).toString(16).padStart(SCALAR_HEX_CHAR_LENGTH, "0")
+  };
+}
 
 // src/transact/fees/append-fee-output.ts
 function feeCoinFromSlot(slot) {
@@ -5560,6 +5607,9 @@ function createNullifierSpentChecker(transactEnvironment) {
   };
 }
 
+// src/client/assess-incoming-note-network.ts
+import { commitmentHexFromNoteOpening } from "@arcanetech/stellar-privacy-pool-zk-sdk";
+
 // src/client/pool-sync.ts
 function requireTransactEnvironment(transactEnvironment) {
   if (!transactEnvironment) {
@@ -5598,6 +5648,129 @@ async function readPoolLeafEphemeralHexWithEnvironment(transactEnvironment, inpu
   });
 }
 
+// src/client/assess-incoming-note.ts
+var COMMITMENT_HEX_LENGTH = 64;
+function normalizeCommitmentHex(value) {
+  return value.trim().replace(/^0x/iu, "").toLowerCase().padStart(COMMITMENT_HEX_LENGTH, "0");
+}
+function commitmentDecimalFromHex(hex) {
+  return BigInt(`0x${normalizeCommitmentHex(hex)}`).toString();
+}
+function commitmentFieldsAgree(input) {
+  const recomputedHex = normalizeCommitmentHex(input.recomputedCommitmentHex);
+  if (recomputedHex !== normalizeCommitmentHex(input.deliveredCommitmentHex)) {
+    return false;
+  }
+  try {
+    return BigInt(input.noteCommitmentDecimal.trim()) === BigInt(`0x${recomputedHex}`);
+  } catch {
+    return false;
+  }
+}
+async function assessIncomingNote(input) {
+  const assessmentInput = {
+    note: input.note,
+    commitmentHex: input.commitmentHex,
+    privKeyScalarHex: input.privKeyScalarHex
+  };
+  const recomputedHex = await input.ports.recomputeCommitmentHex(assessmentInput);
+  if (!commitmentFieldsAgree({
+    noteCommitmentDecimal: input.note.commitment,
+    deliveredCommitmentHex: input.commitmentHex,
+    recomputedCommitmentHex: recomputedHex
+  })) {
+    return { kind: "dead", reason: "commitment_mismatch" };
+  }
+  const commitmentDecimal = commitmentDecimalFromHex(recomputedHex);
+  const leafPresent = await input.ports.hasCommitmentLeaf(commitmentDecimal);
+  if (!leafPresent) {
+    return { kind: "pending" };
+  }
+  const nullifierHashHex = await input.ports.calculateNullifierHash(
+    input.note.nullifier,
+    privKeyScalarDecimalFromRecipientScalarHex(input.privKeyScalarHex)
+  );
+  const consumed = await input.ports.isNullifierConsumed(nullifierHashHex);
+  if (consumed) {
+    return { kind: "dead", reason: "nullifier_consumed" };
+  }
+  return { kind: "spendable" };
+}
+
+// src/client/assess-incoming-note-network.ts
+function noteApplicationId(note, environment) {
+  const fromNote = note.application_id?.trim();
+  if (fromNote) {
+    return fromNote;
+  }
+  return environment.network.applicationId;
+}
+async function recomputeCommitmentHexFromNote(input) {
+  return commitmentHexFromNoteOpening({
+    value: input.note.value,
+    secret: input.note.secret,
+    nullifier: input.note.nullifier,
+    assetHi: input.note.asset_hi,
+    assetLo: input.note.asset_lo,
+    applicationId: input.applicationId,
+    recipientScalarHex: input.privKeyScalarHex
+  });
+}
+async function hasCommitmentLeafInPoolState(input) {
+  const cached = await input.state.getPoolMerkleState(input.poolContractId);
+  if ((cached?.commitments ?? []).includes(input.commitmentDecimal)) {
+    return true;
+  }
+  await syncPoolMerkleStateWithEnvironment(input.environment, {
+    poolContractId: input.poolContractId,
+    walletPublicKey: input.walletPublicKey
+  });
+  const synced = await input.state.getPoolMerkleState(input.poolContractId);
+  return (synced?.commitments ?? []).includes(input.commitmentDecimal);
+}
+function createAssessIncomingNotePorts(input) {
+  const { environment, state, poolContractId, walletPublicKey } = input;
+  return {
+    recomputeCommitmentHex: ({ note, privKeyScalarHex }) => recomputeCommitmentHexFromNote({
+      note,
+      privKeyScalarHex,
+      applicationId: noteApplicationId(note, environment)
+    }),
+    hasCommitmentLeaf: (commitmentDecimal) => hasCommitmentLeafInPoolState({
+      environment,
+      state,
+      poolContractId,
+      walletPublicKey,
+      commitmentDecimal
+    }),
+    calculateNullifierHash: (nullifier, privKeyScalarDecimal) => getPrivacyPoolService().calculateNullifierHash(nullifier, privKeyScalarDecimal),
+    isNullifierConsumed: async (nullifierHashHex) => {
+      const contractContext = requireContractContext(environment);
+      return readNullifierConsumedOnChain({
+        contractContext,
+        poolContractId,
+        walletPublicKey,
+        nullifierHashHex
+      });
+    }
+  };
+}
+async function assessIncomingNoteWithEnvironment(input) {
+  const environment = requireNetworkEnvironment(input.transactEnvironment);
+  const poolContractId = input.poolContractId?.trim() || environment.network.poolContract;
+  return assessIncomingNote({
+    note: input.note,
+    commitmentHex: input.commitmentHex,
+    privKeyScalarHex: input.privKeyScalarHex,
+    ports: createAssessIncomingNotePorts({
+      environment,
+      state: input.state,
+      poolContractId,
+      walletPublicKey: input.walletPublicKey
+    })
+  });
+}
+
 // src/client/network-facet.ts
 function createPoolNetworkFacet(input) {
   const { transactEnvironment } = input;
@@ -5631,6 +5804,16 @@ function createRegistryNetworkFacet(input) {
     })
   };
 }
+function createAssessmentNetworkFacet(input) {
+  const { transactEnvironment, state } = input;
+  return {
+    assessIncomingNote: (assessmentInput) => assessIncomingNoteWithEnvironment({
+      transactEnvironment,
+      state,
+      ...assessmentInput
+    })
+  };
+}
 function createRpcNetworkFacet(input) {
   const { transactEnvironment } = input;
   return {
@@ -5662,6 +5845,7 @@ function createNetworkFacet(input) {
   return {
     ...createPoolNetworkFacet(input),
     ...createRegistryNetworkFacet(input),
+    ...createAssessmentNetworkFacet(input),
     ...createRpcNetworkFacet(input)
   };
 }
@@ -5874,6 +6058,7 @@ function createStellarPrivacyClientInstance(config) {
     registerPrivateAddress: (input) => composed.network.registerPrivateAddress(input),
     resolveTransferRecipient: (input) => composed.network.resolveTransferRecipient(input),
     checkPrivateRecordSpendStatus: (input) => composed.network.checkPrivateRecordSpendStatus(input),
+    assessIncomingNote: (input) => composed.network.assessIncomingNote(input),
     waitForTransactionConfirmation: (input) => composed.network.waitForTransactionConfirmation(input),
     fetchTransactionConfirmationStatus: (txHash) => composed.network.fetchTransactionConfirmationStatus(txHash),
     getTransactionDetails: (txHash) => composed.network.getTransactionDetails(txHash)
@@ -6395,14 +6580,63 @@ async function buildSenderTransferDepositsAndPublicInput(parameters) {
   });
 }
 
-// src/transact/proofs/confidential/dual.ts
-function confidentialEscrowFields(parameters) {
+// src/transact/proofs/confidential/transfer-spend.ts
+function confidentialEscrowFields(input) {
   return {
-    ...parameters.escrowSend ? { escrowSend: parameters.escrowSend } : {},
-    ...parameters.escrowClaimantLimbs ? { escrowClaimantLimbs: parameters.escrowClaimantLimbs } : {}
+    ...input.escrowSend ? { escrowSend: input.escrowSend } : {},
+    ...input.escrowClaimantLimbs ? { escrowClaimantLimbs: input.escrowClaimantLimbs } : {}
   };
 }
+function transferDepositInputFromProof(input, changeStroops, stateRoot) {
+  return {
+    senderPrivKeyScalarHex: input.senderPrivKeyScalarHex,
+    recipientPrivateAddressStpl1: input.recipientPrivateAddressStpl1,
+    transferStroops: input.transferStroops,
+    changeStroops,
+    selfPrivateAddressStpl1ForChange: input.selfPrivateAddressStpl1ForChange,
+    tokenAddress: input.tokenAddress,
+    stateRoot,
+    ...confidentialEscrowFields(input),
+    ...input.feeOutput ? { feeOutput: input.feeOutput } : {}
+  };
+}
+function spendWithdrawForTransfer(parameters) {
+  const limbs = parameters.input.escrowClaimantLimbs;
+  const { privKeyScalar, ownerScalarHex } = resolveTransferSpendScalars({
+    senderPrivKeyScalarHex: parameters.input.senderPrivKeyScalarHex,
+    escrowSweep: Boolean(limbs)
+  });
+  const spent = withdrawWitnessForCoin({
+    sdk: parameters.sdk,
+    coin: parameters.input.coin,
+    state: parameters.input.state,
+    ownerPubHex: parameters.sdk.ecdhEphemeralPublicKeyFromScalarHex(ownerScalarHex),
+    privKeyScalar,
+    applicationId: parameters.applicationId,
+    ...limbs ? {
+      escrow: escrowSpendWitnessFromLimbs(
+        limbs,
+        parameters.input.senderPrivKeyScalarHex
+      )
+    } : {}
+  });
+  if (limbs) {
+    return spent;
+  }
+  return {
+    witness: spent.witness,
+    withdrawObject: stampWithdrawEscrowLimbs(
+      spent.withdrawObject,
+      sweepWithdrawStamp(confidentialEscrowFields(parameters.input))
+    )
+  };
+}
+
+// src/transact/proofs/confidential/dual.ts
 function stampDualWithdrawLegs(legs, parameters) {
+  if (parameters.escrowClaimantLimbs) {
+    return legs;
+  }
   const escrowLimbs = sweepWithdrawStamp(confidentialEscrowFields(parameters));
   return {
     legA: {
@@ -6466,12 +6700,12 @@ function dualTransferChangeStroops(parameters) {
 }
 async function buildDualTransferProofContext(parameters, applicationId, sdk) {
   const changeStroops = dualTransferChangeStroops(parameters);
-  const privKeyScalar = privKeyScalarDecimalFromRecipientScalarHex(
-    parameters.senderPrivKeyScalarHex
-  );
-  const ownerPubHex = sdk.ecdhEphemeralPublicKeyFromScalarHex(
-    parameters.senderPrivKeyScalarHex
-  );
+  const limbs = parameters.escrowClaimantLimbs;
+  const { privKeyScalar, ownerScalarHex } = resolveTransferSpendScalars({
+    senderPrivKeyScalarHex: parameters.senderPrivKeyScalarHex,
+    escrowSweep: Boolean(limbs)
+  });
+  const ownerPubHex = sdk.ecdhEphemeralPublicKeyFromScalarHex(ownerScalarHex);
   const { legA, legB } = stampDualWithdrawLegs(
     dualWithdrawLegsWithSharedRoot({
       sdk,
@@ -6480,7 +6714,13 @@ async function buildDualTransferProofContext(parameters, applicationId, sdk) {
       state: parameters.state,
       ownerPubHex,
       privKeyScalar,
-      applicationId
+      applicationId,
+      ...limbs ? {
+        escrow: escrowSpendWitnessFromLimbs(
+          limbs,
+          parameters.senderPrivKeyScalarHex
+        )
+      } : {}
     }),
     parameters
   );
@@ -6583,25 +6823,6 @@ async function proveTransaction(parameters) {
     parameters.audit
   );
 }
-function confidentialEscrowFields2(input) {
-  return {
-    ...input.escrowSend ? { escrowSend: input.escrowSend } : {},
-    ...input.escrowClaimantLimbs ? { escrowClaimantLimbs: input.escrowClaimantLimbs } : {}
-  };
-}
-function transferDepositInputFromProof(input, changeStroops, stateRoot) {
-  return {
-    senderPrivKeyScalarHex: input.senderPrivKeyScalarHex,
-    recipientPrivateAddressStpl1: input.recipientPrivateAddressStpl1,
-    transferStroops: input.transferStroops,
-    changeStroops,
-    selfPrivateAddressStpl1ForChange: input.selfPrivateAddressStpl1ForChange,
-    tokenAddress: input.tokenAddress,
-    stateRoot,
-    ...confidentialEscrowFields2(input),
-    ...input.feeOutput ? { feeOutput: input.feeOutput } : {}
-  };
-}
 async function buildTransferProofInputs(parameters) {
   const changeStroops = validateSingleCoinTransferAmounts(
     parameters.input.transferStroops,
@@ -6609,35 +6830,11 @@ async function buildTransferProofInputs(parameters) {
     parameters.input.selfPrivateAddressStpl1ForChange,
     parameters.input.feeOutput?.requiredFee ?? 0n
   );
-  const privKeyScalar = privKeyScalarDecimalFromRecipientScalarHex(
-    parameters.input.senderPrivKeyScalarHex
-  );
-  const { witness, withdrawObject } = withdrawWitnessForCoin({
-    sdk: parameters.sdk,
-    coin: parameters.input.coin,
-    state: parameters.input.state,
-    ownerPubHex: parameters.sdk.ecdhEphemeralPublicKeyFromScalarHex(
-      parameters.input.senderPrivKeyScalarHex
-    ),
-    privKeyScalar,
-    applicationId: parameters.applicationId
-  });
-  const stampedWithdraw = stampWithdrawEscrowLimbs(
-    withdrawObject,
-    sweepWithdrawStamp(confidentialEscrowFields2(parameters.input))
-  );
-  const { recipientSlot, deposits, changeCoin, feeCoin, publicInput } = await buildSenderTransferDepositsAndPublicInput(
+  const { witness, withdrawObject } = spendWithdrawForTransfer(parameters);
+  const depositsBuild = await buildSenderTransferDepositsAndPublicInput(
     transferDepositInputFromProof(parameters.input, changeStroops, witness.stateRoot)
   );
-  return {
-    witness,
-    withdrawObject: stampedWithdraw,
-    recipientSlot,
-    deposits,
-    changeCoin,
-    feeCoin,
-    publicInput
-  };
+  return { witness, withdrawObject, ...depositsBuild };
 }
 async function prepareConfidentialTransferProof(parameters) {
   const poolService = getPrivacyPoolService();