@lfdecentralizedtrust/zeto-contracts 0.2.1 → 0.5.0

package/test/lib/anon_zeto_helpers.ts

@@ -0,0 +1,76 @@
+// Copyright © 2024 Kaleido, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// Shared ZK helpers for the plain `anon` circuit (non-nullifier tokens such as
+// {Zeto_Anon}). Kept separate from `zeto_anon.ts` so escrow and other suites
+// can import these without registering the full Zeto_Anon Hardhat test module.
+
+import { AbiCoder, BigNumberish } from "ethers";
+import { encodeProof } from "zeto-js";
+import { groth16 } from "snarkjs";
+import { formatPrivKeyForBabyJub, stringifyBigInts } from "maci-crypto";
+import { User, UTXO, logger, ZERO_UTXO } from "./utils";
+
+const ZERO_PUBKEY = [0n, 0n];
+
+export async function prepareProof(
+  circuit: any,
+  provingKey: any,
+  signer: User,
+  inputs: UTXO[],
+  outputs: UTXO[],
+  owners: User[],
+) {
+  const inputCommitments: BigNumberish[] = inputs.map(
+    (input) => input.hash,
+  ) as BigNumberish[];
+  const inputValues = inputs.map((input) => BigInt(input.value || 0n));
+  const inputSalts = inputs.map((input) => input.salt || 0n);
+  const outputCommitments: BigNumberish[] = outputs.map(
+    (output) => output.hash,
+  ) as BigNumberish[];
+  const outputValues = outputs.map((output) => BigInt(output.value || 0n));
+  const outputSalts = outputs.map((o) => o.salt || 0n);
+  const outputOwnerPublicKeys: BigNumberish[][] = owners.map(
+    (owner) => owner.babyJubPublicKey || ZERO_PUBKEY,
+  ) as BigNumberish[][];
+  const otherInputs = stringifyBigInts({
+    inputOwnerPrivateKey: formatPrivKeyForBabyJub(signer.babyJubPrivateKey),
+  });
+
+  const startWitnessCalculation = Date.now();
+  const witness = await circuit.calculateWTNSBin(
+    {
+      inputCommitments,
+      inputValues,
+      inputSalts,
+      outputCommitments,
+      outputValues,
+      outputSalts,
+      outputOwnerPublicKeys,
+      ...otherInputs,
+    },
+    true,
+  );
+  const timeWitnessCalculation = Date.now() - startWitnessCalculation;
+
+  const startProofGeneration = Date.now();
+  const { proof, publicSignals } = (await groth16.prove(
+    provingKey,
+    witness,
+  )) as { proof: BigNumberish[]; publicSignals: BigNumberish[] };
+  const timeProofGeneration = Date.now() - startProofGeneration;
+  logger.debug(
+    `Witness calculation time: ${timeWitnessCalculation}ms, Proof generation time: ${timeProofGeneration}ms`,
+  );
+  const encodedProof = encodeProof(proof);
+  return encodedProof;
+}
+
+export function encodeToBytes(proof: any) {
+  return new AbiCoder().encode(
+    ["tuple(uint256[2] pA, uint256[2][2] pB, uint256[2] pC)"],
+    [proof],
+  );
+}

package/test/lib/deploy.ts

@@ -10,6 +10,7 @@ import {
   deployNonFungible as deployNonFungibleCloneable,
 } from "../../scripts/deploy_cloneable";
 import fungibilities from "../../scripts/tokens.json";
+import { logger } from "./utils";
 import { ethers } from "hardhat";
 
 export async function deployZeto(tokenName: string) {
@@ -34,7 +35,7 @@ export async function deployZeto(tokenName: string) {
   }
 
   if (process.env.USE_FACTORY !== "true") {
-    console.log("Deploying as upgradeable contracts");
+    logger.debug("Deploying as upgradeable contracts");
     // setup via the deployment scripts
     const deployFunc = isFungible
       ? deployFungibleUpgradeable
@@ -42,7 +43,7 @@ export async function deployZeto(tokenName: string) {
     const result = await deployFunc(tokenName);
     ({ deployer, zeto, erc20 } = result as any);
   } else {
-    console.log('Deploying as cloneable contracts using "ZetoTokenFactory"');
+    logger.debug('Deploying as cloneable contracts using "ZetoTokenFactory"');
     let args, zetoImpl;
     const deployFunc = isFungible
       ? deployFungibleCloneable

package/test/lib/utils.ts

@@ -18,13 +18,15 @@ import {
   ContractTransactionReceipt,
   Signer,
   BigNumberish,
-  AddressLike,
 } from "ethers";
 import {
   genKeypair,
   formatPrivKeyForBabyJub,
-  genEcdhSharedKey,
 } from "maci-crypto";
+import { Logger, ILogObj } from "tslog";
+const logLevel = process.env.LOG_LEVEL || "3";
+export const logger: Logger<ILogObj> = new Logger({ name: "e2e", minLevel: parseInt(logLevel) });
+
 import { Poseidon, newSalt, tokenUriHash } from "zeto-js";
 
 const poseidonHash3 = Poseidon.poseidon3;
@@ -35,18 +37,18 @@ export interface UTXO {
   value?: number;
   tokenId?: number;
   uri?: string;
-  hash: BigInt;
-  salt?: BigInt;
+  hash: bigint;
+  salt?: bigint;
 }
 
-export const ZERO_UTXO: UTXO = { hash: BigInt(0) };
+export const ZERO_UTXO: UTXO = { hash: 0n };
 
 export interface User {
   signer: Signer;
   ethAddress: string;
-  babyJubPrivateKey: BigInt;
-  babyJubPublicKey: BigInt[];
-  formattedPrivateKey: BigInt;
+  babyJubPrivateKey: bigint;
+  babyJubPublicKey: bigint[];
+  formattedPrivateKey: bigint;
 }
 
 export async function newUser(signer: Signer) {
@@ -62,7 +64,7 @@ export async function newUser(signer: Signer) {
   };
 }
 
-export function newUTXO(value: number, owner: User, salt?: BigInt): UTXO {
+export function newUTXO(value: number, owner: User, salt?: bigint): UTXO {
   if (!salt) salt = newSalt();
   const hash = poseidonHash4([
     BigInt(value),
@@ -77,7 +79,7 @@ export function newAssetUTXO(
   tokenId: number,
   uri: string,
   owner: User,
-  salt?: BigInt,
+  salt?: bigint,
 ): UTXO {
   if (!salt) salt = newSalt();
   const hash = poseidonHash5([
@@ -122,10 +124,13 @@ export async function doMint(
     .connect(minter)
     .mint(outputCommitments, "0x");
   const result = await tx.wait();
-  console.log(`Method mint() complete. Gas used: ${result?.gasUsed}`);
+  logger.debug(`Method mint() complete. Gas used: ${result?.gasUsed}`);
   if (result?.gasUsed && Array.isArray(gasHistories)) {
     gasHistories.push(result?.gasUsed);
   }
+  if (!result) {
+    throw new Error("doMint: transaction receipt is null");
+  }
   return result;
 }
 
@@ -141,10 +146,13 @@ export async function doDeposit(
     .connect(depositUser)
     .deposit(amount, commitment, proof, "0x");
   const result = await tx.wait();
-  console.log(`Method deposit() complete. Gas used: ${result?.gasUsed}`);
+  logger.debug(`Method deposit() complete. Gas used: ${result?.gasUsed}`);
   if (result?.gasUsed && Array.isArray(gasHistories)) {
     gasHistories.push(result?.gasUsed);
   }
+  if (!result) {
+    throw new Error("doDeposit: transaction receipt is null");
+  }
   return result;
 }
 
@@ -162,17 +170,23 @@ export async function doWithdraw(
     .connect(withdrawUser)
     .withdraw(amount, nullifiers, commitment, root, proof);
   const result = await tx.wait();
-  console.log(`Method withdraw() complete. Gas used: ${result?.gasUsed}`);
+  logger.debug(`Method withdraw() complete. Gas used: ${result?.gasUsed}`);
   if (result?.gasUsed && Array.isArray(gasHistories)) {
     gasHistories.push(result?.gasUsed);
   }
+  if (!result) {
+    throw new Error("doWithdraw: transaction receipt is null");
+  }
   return result;
 }
 
 export function parseUTXOEvents(
   zetoTokenContract: any,
-  result: ContractTransactionReceipt,
+  result: ContractTransactionReceipt | null,
 ) {
+  if (!result) {
+    throw new Error("parseUTXOEvents: transaction receipt is null");
+  }
   let returnValues: any[] = [];
   for (const log of result.logs || []) {
     const event = zetoTokenContract.interface.parseLog(log as any);
@@ -183,6 +197,13 @@ export function parseUTXOEvents(
         outputs: event?.args.outputs,
         submitter: event?.args.submitter,
       };
+    } else if (event?.name === "UTXOTransferLocked") {
+      e = {
+        lockedInputs: event?.args.lockedInputs,
+        lockedOutputs: event?.args.lockedOutputs,
+        outputs: event?.args.outputs,
+        submitter: event?.args.submitter,
+      };
     } else if (event?.name === "UTXOTransferWithEncryptedValues") {
       e = {
         inputs: event?.args.inputs,
@@ -192,6 +213,15 @@ export function parseUTXOEvents(
         submitter: event?.args.submitter,
         ecdhPublicKey: event?.args.ecdhPublicKey,
       };
+    } else if (event?.name === "UTXOTransferWithMlkemEncryptedValues") {
+      e = {
+        inputs: event?.args.inputs,
+        outputs: event?.args.outputs,
+        encryptedValues: event?.args.encryptedValues,
+        encryptionNonce: event?.args.encryptionNonce,
+        submitter: event?.args.submitter,
+        encapsulatedSharedSecret: event?.args.encapsulatedSharedSecret,
+      };
     } else if (event?.name === "UTXOTransferNonRepudiation") {
       e = {
         inputs: event?.args.inputs,
@@ -208,36 +238,45 @@ export function parseUTXOEvents(
         receivers: event?.args.receivers,
         submitter: event?.args.submitter,
       };
-    } else if (event?.name === "TradeCompleted") {
+    } else if (event?.name === "UTXOWithdraw") {
       e = {
-        tradeId: event?.args.tradeId,
-        trade: event?.args.trade,
+        amount: event?.args.amount,
+        inputs: event?.args.inputs,
+        output: event?.args.output,
       };
-    } else if (event?.name === "UTXOsLocked") {
+    } else if (event?.name === "LockCreate") {
       e = {
-        outputs: event?.args.outputs,
-        lockedOutputs: event?.args.lockedOutputs,
-        delegate: event?.args.delegate,
+        lockId: event?.args.lockId,
+        lockData: event?.args.lockData,
       };
-    } else if (event?.name === "LockDelegateChanged") {
+    } else if (event?.name === "UnlockPrepare") {
       e = {
-        lockedOutputs: event?.args.lockedOutputs,
-        oldDelegate: event?.args.oldDelegate,
-        newDelegate: event?.args.newDelegate,
+        lockId: event?.args.lockId,
+        operator: event?.args.operator,
+        settle: event?.args.settle,
       };
-    } else if (event?.name === "PaymentInitiated") {
+    } else if (event?.name === "Unlock") {
       e = {
-        paymentId: event?.args.paymentId,
-        lockedInputs: event?.args.lockedInputs,
-        nullifiers: event?.args.nullifiers,
-        outputs: event?.args.outputs,
+        lockId: event?.args.lockId,
+        operator: event?.args.operator,
+        inputs: event?.args.inputs,
+        delegate: event?.args.delegate,
+        settle: event?.args.settle,
       };
-    } else if (
-      event?.name === "PaymentApproved" ||
-      event?.name === "PaymentCompleted"
-    ) {
+    } else if (event?.name === "LockRollback") {
       e = {
-        paymentId: event?.args.paymentId,
+        lockId: event?.args.lockId,
+        operator: event?.args.operator,
+        inputs: event?.args.inputs,
+        delegate: event?.args.delegate,
+        rollback: event?.args.rollback,
+      };
+    } else if (event?.name === "LockDelegate") {
+      e = {
+        lockId: event?.args.lockId,
+        operator: event?.args.operator,
+        oldDelegate: event?.args.oldDelegate,
+        newDelegate: event?.args.newDelegate,
       };
     }
     returnValues.push(e);

package/test/test/escrow1.ts

@@ -15,11 +15,16 @@
 // limitations under the License.
 
 import { ethers, ignition, network } from "hardhat";
-import { Signer, encodeBytes32String, ZeroHash, lock } from "ethers";
+import {
+  Signer,
+  AbiCoder,
+  BigNumberish,
+  ContractTransactionReceipt,
+} from "ethers";
 import { expect } from "chai";
-import { loadCircuit, getProofHash } from "zeto-js";
+import { loadCircuit } from "zeto-js";
 import zkEscrowModule from "../../ignition/modules/test/escrow1";
-import zetoAnonTests from "../zeto_anon";
+import { prepareProof } from "../lib/anon_zeto_helpers";
 import {
   UTXO,
   User,
@@ -27,11 +32,36 @@ import {
   newUTXO,
   doMint,
   ZERO_UTXO,
-  parseUTXOEvents,
+  logger,
 } from "../lib/utils";
 import { loadProvingKeys } from "../utils";
 import { deployZeto } from "../lib/deploy";
 
+// ABI fragments for the ZetoLockableCapability *Args payloads.
+// These mirror the canonical encodings used by every Zeto token that
+// implements ILockableCapability.
+const CREATE_ARGS_ABI =
+  "tuple(bytes32 txId, uint256[] inputs, uint256[] outputs, uint256[] lockedOutputs, bytes proof)";
+const DELEGATE_ARGS_ABI = "tuple(bytes32 txId)";
+
+function encodeCreateArgs(args: {
+  txId: string;
+  inputs: BigNumberish[];
+  outputs: BigNumberish[];
+  lockedOutputs: BigNumberish[];
+  proof: string;
+}) {
+  return new AbiCoder().encode([CREATE_ARGS_ABI], [args]);
+}
+
+function encodeDelegateArgs(txId: string) {
+  return new AbiCoder().encode([DELEGATE_ARGS_ABI], [{ txId }]);
+}
+
+function randomBytes32(): string {
+  return ethers.hexlify(ethers.randomBytes(32));
+}
+
 describe("Escrow flow for payment with Zeto_Anon", function () {
   let Alice: User;
   let Bob: User;
@@ -48,6 +78,7 @@ describe("Escrow flow for payment with Zeto_Anon", function () {
   // UTXOs involved in the escrow flow
   let lockedPayment1: UTXO;
   let paymentToBob: UTXO;
+  let lockId: string;
 
   // other variables
   let deployer: Signer;
@@ -66,11 +97,15 @@ describe("Escrow flow for payment with Zeto_Anon", function () {
     Bob = await newUser(b);
     Charlie = await newUser(c);
 
+    // The Zeto_Anon token uses the same `anon` circuit for both regular
+    // transfers and the locked-input branch (the lockVerifier is wired
+    // to Groth16Verifier_Anon in the ignition module). One circuit/key
+    // pair therefore covers both the createLock and spendLock proofs.
     circuit = await loadCircuit("anon");
     ({ provingKeyFile: provingKey } = loadProvingKeys("anon"));
 
     ({ deployer, zeto: zkPayment } = await deployZeto("Zeto_Anon"));
-    console.log(`ZK Payment contract deployed at ${zkPayment.target}`);
+    logger.debug(`ZK Payment contract deployed at ${zkPayment.target}`);
     ({ zkEscrow } = await ignition.deploy(zkEscrowModule, {
       parameters: {
         zkEscrow1: {
@@ -85,62 +120,101 @@ describe("Escrow flow for payment with Zeto_Anon", function () {
     payment2 = newUTXO(20, Alice);
     const result = await doMint(zkPayment, deployer, [payment1, payment2]);
 
-    // simulate Alice and Bob listening to minting events and updating his local merkle tree
+    // simulate Alice and Bob listening to minting events and updating
+    // their local merkle trees
     for (const log of result.logs) {
       const event = zkPayment.interface.parseLog(log as any);
       expect(event.args.outputs.length).to.equal(2);
     }
   });
 
-  it("Alice locks some payment tokens and designates the escrow as the delegate", async function () {
+  it("Alice locks payment1 by calling createLock on the Zeto token", async function () {
+    // The locked output preserves the value but is a fresh commitment
+    // (new salt). The createLock proof attests to the standard transfer
+    // payment1 -> lockedPayment1.
     lockedPayment1 = newUTXO(payment1.value!, Alice);
-    const { inputCommitments, outputCommitments, encodedProof } =
-      await zetoAnonTests.prepareProof(
-        circuit,
-        provingKey,
-        Alice,
-        [payment1, ZERO_UTXO],
-        [lockedPayment1, ZERO_UTXO],
-        [Alice, {}],
-      );
+    const encodedZkProof = await prepareProof(
+      circuit,
+      provingKey,
+      Alice,
+      [payment1, ZERO_UTXO],
+      [lockedPayment1, ZERO_UTXO],
+      [Alice, {}],
+    );
+
+    const createArgs = encodeCreateArgs({
+      txId: randomBytes32(),
+      inputs: [payment1.hash],
+      // For the fungible Zeto_Anon createLock, lockedOutputs holds the
+      // freshly-locked UTXO and outputs is empty (no change is being
+      // returned to Alice, since payment1's full value is moved into
+      // the lock).
+      outputs: [],
+      lockedOutputs: [lockedPayment1.hash],
+      proof: encodeProofOnly(encodedZkProof),
+    });
+
+    // Pre-compute the lockId off-chain to assert the contract derives
+    // the same value (deterministic from caller + txId).
+    lockId = await zkPayment.connect(Alice.signer).computeLockId(createArgs);
+
+    const tx = await zkPayment
+      .connect(Alice.signer)
+      .createLock(createArgs, ethers.ZeroHash, ethers.ZeroHash, "0x");
+    const result: ContractTransactionReceipt | null = await tx.wait();
+    logger.debug(`createLock() complete. Gas used: ${result?.gasUsed}`);
+
+    // Sanity-check the lock state after creation.
+    const info = await zkPayment.getLock(lockId);
+    expect(info.owner).to.equal(Alice.ethAddress);
+    expect(info.spender).to.equal(Alice.ethAddress);
+    expect(await zkPayment.locked(lockedPayment1.hash)).to.deep.equal([
+      true,
+      Alice.ethAddress,
+    ]);
+  });
+
+  it("Alice delegates the lock to the escrow contract", async function () {
     const tx = await zkPayment
       .connect(Alice.signer)
-      .lock(
-        inputCommitments,
-        [],
-        outputCommitments,
-        encodedProof,
+      .delegateLock(
+        lockId,
+        encodeDelegateArgs(randomBytes32()),
         zkEscrow.target,
         "0x",
       );
-    const result = await tx.wait();
-    const events = parseUTXOEvents(zkPayment, result);
-
-    // simulate Alice's tradinig partner listening to the locking events and verifying the committed (locked) value
-    const lockedUTXO = events[0].lockedOutputs[0];
-    const lockDelegate = events[0].delegate;
-    // Alice's trading partner is sent the secrets for the locked UTXO (which is still owned by Alice)
-    // in an off-chain message. so they can be used to verify the locked UTXO, and the lock delegate
-    expect(lockedUTXO).to.equal(lockedPayment1.hash);
-    expect(lockDelegate).to.equal(zkEscrow.target);
+    await tx.wait();
+
+    // After delegation the escrow is the sole spender; Alice can no
+    // longer spend the lock directly.
+    const info = await zkPayment.getLock(lockId);
+    expect(info.spender).to.equal(zkEscrow.target);
+    expect(await zkPayment.locked(lockedPayment1.hash)).to.deep.equal([
+      true,
+      zkEscrow.target,
+    ]);
   });
 
   it("Alice initiates a payment transaction to Bob through the escrow", async function () {
-    paymentToBob = newUTXO(lockedPayment1.value!, Bob, lockedPayment1.salt);
+    paymentToBob = newUTXO(lockedPayment1.value!, Bob);
     const tx = await zkEscrow
       .connect(Alice.signer)
-      .initiatePayment([lockedPayment1.hash], [paymentToBob.hash], "0x");
+      .initiatePayment(lockId, [paymentToBob.hash], "0x");
     const result = await tx.wait();
-    const events = parseUTXOEvents(zkEscrow, result);
-    // simulate Bob listening to the payment events and verifying the proposed payment
-    const proposedPayment = events[0].outputs[0];
-    const check = newUTXO(lockedPayment1.value!, Bob, lockedPayment1.salt);
-    expect(proposedPayment).to.equal(check.hash);
-    paymentId = events[0].paymentId;
+    const initiated = parseEscrowEvent(zkEscrow, result, "PaymentInitiated");
+    expect(initiated, "PaymentInitiated event not emitted").to.not.be.undefined;
+
+    // Bob listens to the payment events and verifies the proposed
+    // payment matches what Alice promised off-chain.
+    expect(initiated!.outputs[0]).to.equal(paymentToBob.hash);
+    expect(initiated!.lockId).to.equal(lockId);
+    paymentId = initiated!.paymentId;
   });
 
-  it("Alice approves the payment by submitting a valid proof that can successfully verify the proposed payment", async function () {
-    const { encodedProof } = await zetoAnonTests.prepareProof(
+  it("Alice approves the payment by submitting a valid locked-input proof", async function () {
+    // The spend proof transfers lockedPayment1 -> paymentToBob (now
+    // owned by Bob). Same `anon` circuit as the createLock step.
+    const encodedZkProof = await prepareProof(
       circuit,
       provingKey,
       Alice,
@@ -150,29 +224,82 @@ describe("Escrow flow for payment with Zeto_Anon", function () {
     );
     const tx = await zkEscrow
       .connect(Alice.signer)
-      .approvePayment(paymentId, encodedProof, "0x");
+      .approvePayment(paymentId, encodeProofOnly(encodedZkProof), "0x");
     const result = await tx.wait();
-    // simulate Bob listening to the escrow events and verifying the payment has been approved.
-    // the escrow contract guaratees that the proof is valid
-    const events = parseUTXOEvents(zkEscrow, result);
-    const approvedPayment = events[0].paymentId;
-    expect(approvedPayment).to.equal(paymentId);
+
+    // Bob listens to the escrow's PaymentApproved event; the escrow
+    // having stored the proof guarantees completePayment cannot fail
+    // on proof grounds later.
+    const approved = parseEscrowEvent(zkEscrow, result, "PaymentApproved");
+    expect(approved, "PaymentApproved event not emitted").to.not.be.undefined;
+    expect(approved!.paymentId).to.equal(paymentId);
   });
 
-  it("Bob, or anyone, can call the escrow to finalize the payment and receive the locked UTXO", async function () {
+  it("Bob, or anyone, can call the escrow to finalize the payment and receive the unlocked UTXO", async function () {
     const tx = await zkEscrow
       .connect(Bob.signer)
       .completePayment(paymentId, "0x");
     const result = await tx.wait();
-    // simulate Bob listening to the payment events and verifying
-    // the expected UTXO has been transferred to him
-    let events = parseUTXOEvents(zkPayment, result);
-    const transferredPayment = events[0].outputs[0];
-    const check = newUTXO(paymentToBob.value!, Bob, paymentToBob.salt);
-    expect(transferredPayment).to.equal(check.hash);
-    // simulate Bob listening to the escrow events and verifying the payment has been completed
-    events = parseUTXOEvents(zkEscrow, result);
-    const completedPayment = events[1].paymentId;
-    expect(completedPayment).to.equal(paymentId);
+
+    // The Zeto token emits ZetoLockSpent containing the new unlocked
+    // outputs.
+    const lockSpent = result!.logs
+      .map((l) => {
+        try {
+          return zkPayment.interface.parseLog(l as any);
+        } catch (_e) {
+          return null;
+        }
+      })
+      .find((p: any) => p && p.name === "ZetoLockSpent");
+    expect(lockSpent, "ZetoLockSpent event not emitted").to.not.be.undefined;
+    expect(lockSpent!.args.outputs[0]).to.equal(paymentToBob.hash);
+
+    // Lock is consumed; the locked-UTXO ledger no longer carries
+    // lockedPayment1.
+    expect(await zkPayment.isLockActive(lockId)).to.equal(false);
+    expect((await zkPayment.locked(lockedPayment1.hash))[0]).to.be.false;
+
+    // Escrow's PaymentCompleted event fires for the same paymentId.
+    const completed = parseEscrowEvent(zkEscrow, result, "PaymentCompleted");
+    expect(completed, "PaymentCompleted event not emitted").to.not.be.undefined;
+    expect(completed!.paymentId).to.equal(paymentId);
   });
 });
+
+// parseEscrowEvent extracts the first event of a given name from a
+// transaction receipt by parsing logs through the escrow contract's
+// own ABI. Unlike `parseUTXOEvents`, which only knows about the Zeto
+// token's UTXO event family, this helper handles the escrow's
+// custom Payment* events.
+function parseEscrowEvent(
+  escrowContract: any,
+  receipt: ContractTransactionReceipt | null,
+  name: string,
+): any | undefined {
+  if (!receipt) return undefined;
+  for (const log of receipt.logs || []) {
+    let parsed;
+    try {
+      parsed = escrowContract.interface.parseLog(log as any);
+    } catch (_e) {
+      continue;
+    }
+    if (parsed && parsed.name === name) {
+      // Return the args Result directly; ethers exposes named fields
+      // (e.g. result.paymentId) alongside positional ones.
+      return parsed.args;
+    }
+  }
+  return undefined;
+}
+
+// encodeProofOnly mirrors the wire format that
+// {Zeto_Anon.constructPublicInputs} expects: a bare `Commonlib.Proof`
+// tuple (no merkle root prefix, since Zeto_Anon is non-nullifier).
+function encodeProofOnly(proof: any) {
+  return new AbiCoder().encode(
+    ["tuple(uint256[2] pA, uint256[2][2] pB, uint256[2] pC)"],
+    [proof],
+  );
+}