@zill-protocol/client 4.1.2

package/dist/src/utils/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./constants"), exports);
+__exportStar(require("./misc"), exports);
+//# sourceMappingURL=index.js.map

package/dist/src/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8CAA4B;AAC5B,yCAAuB"}

package/dist/src/utils/misc.d.ts

@@ -0,0 +1,13 @@
+import { SignedOperation, PreSignOperation, Note, IncludedNote, Asset, MapWithObjectKeys, OperationStatus } from "@zill-protocol/core";
+import { JoinSplitRequest } from "../operationRequest";
+export declare function sortNotesByValue<T extends Note>(notes: T[]): T[];
+export declare function getJoinSplitRequestTotalValue(joinSplitRequest: JoinSplitRequest): bigint;
+export interface NullifierWithMerkleIndex {
+    nullifier: bigint;
+    merkleIndex: bigint;
+}
+export declare function getIncludedNotesFromOp(op: PreSignOperation): MapWithObjectKeys<Asset, IncludedNote[]>;
+export declare function getMerkleIndicesAndNfsFromOp(op: PreSignOperation | SignedOperation): NullifierWithMerkleIndex[];
+export declare function isFailedOpStatus(status: OperationStatus): boolean;
+export declare function isTerminalOpStatus(status: OperationStatus): boolean;
+//# sourceMappingURL=misc.d.ts.map

package/dist/src/utils/misc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"misc.d.ts","sourceRoot":"","sources":["../../../src/utils/misc.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,gBAAgB,EAGhB,IAAI,EACJ,YAAY,EACZ,KAAK,EACL,iBAAiB,EAEjB,eAAe,EAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEvD,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAIhE;AAED,wBAAgB,6BAA6B,CAC3C,gBAAgB,EAAE,gBAAgB,GACjC,MAAM,CAMR;AAED,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,GACnB,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC,CAmB1C;AAGD,wBAAgB,4BAA4B,CAC1C,EAAE,EAAE,gBAAgB,GAAG,eAAe,GACrC,wBAAwB,EAAE,CA+B5B;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAMjE;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAInE"}

package/dist/src/utils/misc.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sortNotesByValue = sortNotesByValue;
+exports.getJoinSplitRequestTotalValue = getJoinSplitRequestTotalValue;
+exports.getIncludedNotesFromOp = getIncludedNotesFromOp;
+exports.getMerkleIndicesAndNfsFromOp = getMerkleIndicesAndNfsFromOp;
+exports.isFailedOpStatus = isFailedOpStatus;
+exports.isTerminalOpStatus = isTerminalOpStatus;
+const core_1 = require("@zill-protocol/core");
+function sortNotesByValue(notes) {
+    return notes.sort((a, b) => {
+        return Number(a.value - b.value);
+    });
+}
+function getJoinSplitRequestTotalValue(joinSplitRequest) {
+    let totalVal = joinSplitRequest.unwrapValue;
+    if (joinSplitRequest.payment !== undefined) {
+        totalVal += joinSplitRequest.payment.value;
+    }
+    return totalVal;
+}
+function getIncludedNotesFromOp(op) {
+    const notesMap = new core_1.MapWithObjectKeys();
+    op.joinSplits.forEach((joinSplit) => {
+        const { oldNoteA, oldNoteB } = joinSplit;
+        const notes = [oldNoteA, oldNoteB];
+        notes.forEach((note) => {
+            if (!notesMap.has(note.asset)) {
+                notesMap.set(note.asset, []);
+            }
+            const existingNotes = notesMap.get(note.asset);
+            notesMap.set(note.asset, [...existingNotes, note]);
+        });
+    });
+    return notesMap;
+}
+// returns the merkle indices of the notes spent in an op
+function getMerkleIndicesAndNfsFromOp(op) {
+    return op.joinSplits.flatMap((joinSplit) => {
+        // get merkle index out of the path in the merkle proof
+        // how we do this depends on which kind of joinSplit it is (which depends on the op)
+        let merklePathA;
+        let merklePathB;
+        if (Object.hasOwn(joinSplit, "proofInputs")) {
+            // if it has "proofInputs", it's a `PreProofJoinSplit`
+            // in this case, we get the merkle path out of the proofInputs
+            merklePathA = joinSplit.proofInputs.merkleProofA
+                .path;
+            merklePathB = joinSplit.proofInputs.merkleProofB
+                .path;
+        }
+        else {
+            // otherwise, it's a `PreSignJoinSplit`, in which case we get it out of the joinsplit itself
+            merklePathA = joinSplit.merkleProofA.path;
+            merklePathB = joinSplit.merkleProofB.path;
+        }
+        return [
+            {
+                merkleIndex: (0, core_1.merklePathToIndex)(merklePathA, "LEAF_TO_ROOT"),
+                nullifier: joinSplit.nullifierA,
+            },
+            {
+                merkleIndex: (0, core_1.merklePathToIndex)(merklePathB, "LEAF_TO_ROOT"),
+                nullifier: joinSplit.nullifierB,
+            },
+        ];
+    });
+}
+function isFailedOpStatus(status) {
+    return (status === core_1.OperationStatus.BUNDLE_REVERTED ||
+        status === core_1.OperationStatus.OPERATION_EXECUTION_FAILED ||
+        status === core_1.OperationStatus.OPERATION_PROCESSING_FAILED);
+}
+function isTerminalOpStatus(status) {
+    return (status === core_1.OperationStatus.EXECUTED_SUCCESS || isFailedOpStatus(status));
+}
+//# sourceMappingURL=misc.js.map

package/dist/src/utils/misc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"misc.js","sourceRoot":"","sources":["../../../src/utils/misc.ts"],"names":[],"mappings":"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"}

package/dist/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../index.ts","../src/nocturneclient.ts","../src/nocturnedb.ts","../src/optracker.ts","../src/index.ts","../src/oprequestgas.ts","../src/prepareoperation.ts","../src/proveoperation.ts","../src/signoperation.ts","../src/snapjsonrpc.ts","../src/syncsdk.ts","../src/types.ts","../src/conversion/converter.ts","../src/conversion/index.ts","../src/conversion/mock.ts","../src/operationrequest/builder.ts","../src/operationrequest/index.ts","../src/operationrequest/operationrequest.ts","../src/utils/constants.ts","../src/utils/index.ts","../src/utils/misc.ts","../package.json"],"version":"5.9.3"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@zill-protocol/client",
+  "version": "4.1.2",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*",
+    "src/**/*"
+  ],
+  "scripts": {
+    "build": "yarn clean; tsc --build",
+    "check": "tsc --noEmit",
+    "clean": "rm -rf .turbo dist",
+    "gen-test-cases:operationhash": "npx ts-node ./scripts/genOperationHashTestCase.ts",
+    "gen-test-cases:registryentry": "npx ts-node ./scripts/genCanonAddrRegistryEntryHashTestCase.ts",
+    "gen-test-cases:poseidonext": "npx ts-node ./scripts/genPoseidonExtTestCase.ts",
+    "lint": "eslint --fix src --ext .ts",
+    "prettier:check": "prettier --check ./src ./test",
+    "prettier:write": "prettier --write ./src ./test",
+    "publish": "yarn build; yarn npm publish --access public",
+    "test:unit": "mocha --require ts-node/register test/** --timeout 45000 --exit"
+  },
+  "dependencies": {
+    "@zill-protocol/config": "^1.7.4",
+    "@zill-protocol/contracts": "^3.0.0",
+    "@zill-protocol/core": "^3.3.1",
+    "@zill-protocol/crypto": "^0.4.3",
+    "async-mutex": "^0.4.0",
+    "big-integer": "^1.6.42",
+    "bigint-json-serialization": "^1.0.1",
+    "ethers": "^5.7.2",
+    "js-sha256": "^0.9.0"
+  },
+  "devDependencies": {
+    "@types/chai": "^4.3.3",
+    "@types/chai-as-promised": "^7.1.5",
+    "@types/mocha": "^10.0.0",
+    "@types/node": "^25.0.1",
+    "@types/sinon": "^10.0.13",
+    "@types/sinon-chai": "^3.2.9",
+    "@typescript-eslint/eslint-plugin": "^8.49.0",
+    "@typescript-eslint/parser": "^8.49.0",
+    "chai": "^4.3.6",
+    "chai-as-promised": "^7.1.1",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "mocha": "^10.1.0",
+    "prettier": "^3.7.4",
+    "sinon": "^15.0.1",
+    "sinon-chai": "^3.7.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/NocturneClient.ts

@@ -0,0 +1,415 @@
+import { NocturneConfig, loadNocturneConfig } from "@zill-protocol/config";
+import { Handler, Handler__factory } from "@zill-protocol/contracts";
+import { NocturneViewer, StealthAddressTrait } from "@zill-protocol/crypto";
+import ethers from "ethers";
+import { GetNotesOpts, NocturneDB } from "./NocturneDB";
+import { OpTracker } from "./OpTracker";
+import { EthToTokenConverter } from "./conversion";
+import { handleGasForOperationRequest } from "./opRequestGas";
+import {
+  OperationRequest,
+  ensureOpRequestChainInfo,
+} from "./operationRequest/operationRequest";
+import { prepareOperation } from "./prepareOperation";
+import { SyncOpts, syncSDK } from "./syncSDK";
+import { OpHistoryRecord, OperationMetadata, PendingOutputRecord } from "./types";
+import {
+  getJoinSplitRequestTotalValue,
+  getMerkleIndicesAndNfsFromOp,
+} from "./utils";
+
+import {
+  Asset,
+  AssetTrait,
+  AssetWithBalance,
+  IncludedNote,
+  MapWithObjectKeys,
+  Note,
+  NoteTrait,
+  OperationStatus,
+  OperationTrait,
+  PreSignOperation,
+  SDKSyncAdapter,
+  SignedOperation,
+  SparseMerkleProver,
+  TotalEntityIndex,
+  TotalEntityIndexTrait,
+  decryptNote,
+  maxArray,
+} from "@zill-protocol/core";
+
+const PRUNE_OPTIMISTIC_NFS_TIMER = 60 * 1000; // 1 minute
+
+export class NocturneClient {
+  protected provider: ethers.providers.Provider;
+  protected config: NocturneConfig;
+  protected handlerContract: Handler;
+  protected merkleProver: SparseMerkleProver;
+  protected db: NocturneDB;
+  protected syncAdapter: SDKSyncAdapter;
+  protected tokenConverter: EthToTokenConverter;
+  protected opTracker: OpTracker;
+  protected pendingOutputsListeners: Set<
+    (outputs: PendingOutputRecord[]) => void
+  > = new Set();
+
+  readonly viewer: NocturneViewer;
+  readonly gasAssets: Map<string, Asset>;
+
+  constructor(
+    viewer: NocturneViewer,
+    provider: ethers.providers.Provider,
+    configOrNetworkName: NocturneConfig | string,
+    merkleProver: SparseMerkleProver,
+    db: NocturneDB,
+    syncAdapter: SDKSyncAdapter,
+    tokenConverter: EthToTokenConverter,
+    nulliferChecker: OpTracker
+  ) {
+    if (typeof configOrNetworkName == "string") {
+      this.config = loadNocturneConfig(configOrNetworkName);
+    } else {
+      this.config = configOrNetworkName;
+    }
+
+    this.provider = provider;
+
+    this.gasAssets = new Map(
+      Array.from(this.config.erc20s.entries())
+        .filter(([_, config]) => config.isGasAsset)
+        .map(([ticker, config]) => {
+          return [ticker, AssetTrait.erc20AddressToAsset(config.address)];
+        })
+    );
+
+    this.viewer = viewer;
+    console.log(`Canonical address: `, this.viewer.canonicalAddress());
+    this.handlerContract = Handler__factory.connect(
+      this.config.handlerAddress,
+      provider
+    );
+    this.merkleProver = merkleProver;
+    this.db = db;
+    this.syncAdapter = syncAdapter;
+    this.tokenConverter = tokenConverter;
+    this.opTracker = nulliferChecker;
+
+    // set an interval to prune optimistic nfs to ensure they don't get stuck
+    const prune = async () => {
+      await this.pruneOptimisticNullifiers();
+      setTimeout(prune, PRUNE_OPTIMISTIC_NFS_TIMER);
+    };
+    void prune();
+  }
+
+  async clearDb(): Promise<void> {
+    await this.db.kv.clear();
+  }
+
+  // Sync SDK, returning last synced merkle index of last state diff
+  async sync(opts?: SyncOpts): Promise<number | undefined> {
+    const hasListeners = this.pendingOutputsListeners.size > 0;
+    const shouldNotify = hasListeners || opts?.onPendingOutputsConfirmed;
+    const onPendingOutputsConfirmed = shouldNotify
+      ? (outputs: PendingOutputRecord[]) => {
+          if (!outputs.length) {
+            return;
+          }
+          if (hasListeners) {
+            for (const listener of this.pendingOutputsListeners) {
+              try {
+                listener(outputs);
+              } catch (err) {
+                console.warn("[sync] pending output listener failed", err);
+              }
+            }
+          }
+          opts?.onPendingOutputsConfirmed?.(outputs);
+        }
+      : undefined;
+
+    const baseOpts = opts
+      ? {
+          ...opts,
+          finalityBlocks: opts.finalityBlocks ?? this.config.finalityBlocks,
+        }
+      : undefined;
+    const mergedOpts = onPendingOutputsConfirmed
+      ? { ...(baseOpts ?? {}), onPendingOutputsConfirmed }
+      : baseOpts;
+
+    const latestSyncedMerkleIndex = await syncSDK(
+      { viewer: this.viewer },
+      this.syncAdapter,
+      this.db,
+      this.merkleProver,
+      mergedOpts
+    );
+
+    return latestSyncedMerkleIndex;
+  }
+
+  async prepareOperation(
+    opRequest: OperationRequest,
+    gasMultiplier: number
+  ): Promise<PreSignOperation> {
+    opRequest = await ensureOpRequestChainInfo(opRequest, this.provider);
+
+    const deps = {
+      db: this.db,
+      gasAssets: this.gasAssets,
+      tokenConverter: this.tokenConverter,
+      handlerContract: this.handlerContract,
+      merkle: this.merkleProver,
+      viewer: this.viewer,
+    };
+    const gasAccountedOpRequest = await handleGasForOperationRequest(
+      deps,
+      opRequest,
+      gasMultiplier
+    );
+
+    return await prepareOperation(deps, gasAccountedOpRequest);
+  }
+
+  async getAllAssetBalances(opts?: GetNotesOpts): Promise<AssetWithBalance[]> {
+    const notes = await this.db.getAllNotes(opts);
+    return Array.from(notes.entries()).map(([assetString, notes]) => {
+      const asset = NocturneDB.parseAssetKey(assetString);
+      const balance = notes.reduce((a, b) => a + b.value, 0n);
+      return {
+        asset,
+        balance,
+        numNotes: notes.length,
+      };
+    });
+  }
+
+  async getBalanceForAsset(asset: Asset, opts?: GetNotesOpts): Promise<bigint> {
+    return await this.db.getBalanceForAsset(asset, opts);
+  }
+
+  async getNotesForAsset(
+    asset: Asset,
+    opts?: GetNotesOpts
+  ): Promise<IncludedNote[]> {
+    return await this.db.getNotesForAsset(asset, opts);
+  }
+
+  async getPrivateBalanceBreakdown(asset: Asset): Promise<{
+    confirmed: bigint;
+    pendingUncommitted: bigint;
+    pendingLocal: bigint;
+    pending: bigint;
+    total: bigint;
+  }> {
+    const [confirmed, totalUncommitted, pendingLocal] = await Promise.all([
+      this.db.getBalanceForAsset(asset),
+      this.db.getBalanceForAsset(asset, { includeUncommitted: true }),
+      this.db.getPendingBalanceForAsset(asset),
+    ]);
+    const pendingUncommitted =
+      totalUncommitted > confirmed ? totalUncommitted - confirmed : 0n;
+    const pending = pendingUncommitted + pendingLocal;
+    return {
+      confirmed,
+      pendingUncommitted,
+      pendingLocal,
+      pending,
+      total: confirmed + pending,
+    };
+  }
+
+  async getPendingBalanceForAsset(asset: Asset): Promise<bigint> {
+    return await this.db.getPendingBalanceForAsset(asset);
+  }
+
+  async getPendingOutputs(
+    opts?: { asset?: Asset }
+  ): Promise<PendingOutputRecord[]> {
+    return await this.db.getPendingOutputs(opts);
+  }
+
+  async listPendingNotes(
+    opts?: { asset?: Asset }
+  ): Promise<PendingOutputRecord[]> {
+    return await this.db.getPendingOutputs(opts);
+  }
+
+  async addPendingOutputs(outputs: PendingOutputRecord[]): Promise<void> {
+    await this.db.addPendingOutputs(outputs);
+  }
+
+  async addPendingOutputsFromOperation(
+    op: PreSignOperation | SignedOperation
+  ): Promise<void> {
+    const senderOwner = StealthAddressTrait.fromCanonAddress(
+      this.viewer.canonicalAddress()
+    );
+    const senderKey = StealthAddressTrait.toString(senderOwner);
+    const digest = OperationTrait.computeDigest(op);
+    const outputs: PendingOutputRecord[] = [];
+
+    for (const joinSplit of op.joinSplits) {
+      let notes: Note[] = [];
+      if ("newNoteA" in joinSplit) {
+        notes = [joinSplit.newNoteA, joinSplit.newNoteB];
+      } else {
+        const decryptedNotes = [
+          joinSplit.newNoteAEncrypted,
+          joinSplit.newNoteBEncrypted,
+        ]
+          .map((encryptedNote): Note | null => {
+            try {
+              const { sender, ...note } = decryptNote(this.viewer, encryptedNote);
+              return note;
+            } catch (err) {
+              return null;
+            }
+          })
+          .filter((note): note is Note => note !== null);
+        notes = decryptedNotes;
+      }
+      for (const note of notes) {
+        if (note.value <= 0n) {
+          continue;
+        }
+        const ownerKey = StealthAddressTrait.toString(note.owner);
+        if (ownerKey !== senderKey) {
+          continue;
+        }
+        outputs.push({
+          commitment: NoteTrait.toCommitment(note),
+          asset: note.asset,
+          value: note.value,
+          createdAt: Date.now(),
+          opDigest: digest,
+        });
+      }
+    }
+
+    await this.db.addPendingOutputs(outputs);
+  }
+
+  async removePendingOutputsByOpDigest(opDigest: bigint): Promise<void> {
+    await this.db.removePendingOutputsByOpDigest(opDigest);
+  }
+
+  onPendingNoteConfirmed(
+    listener: (outputs: PendingOutputRecord[]) => void
+  ): () => void {
+    this.pendingOutputsListeners.add(listener);
+    return () => {
+      this.pendingOutputsListeners.delete(listener);
+    };
+  }
+
+  async getLatestSyncedMerkleIndex(): Promise<number | undefined> {
+    return await this.db.latestSyncedMerkleIndex();
+  }
+
+  async getLatestCommittedMerkleIndex(): Promise<number | undefined> {
+    return await this.db.latestCommittedMerkleIndex();
+  }
+
+  /**
+   * Force-nullify notes locally by nullifier. This is useful as a mitigation
+   * when the sync source cannot supply nullifiers (e.g. Mirror down) but the
+   * bundler reports the nullifier already exists on-chain.
+   */
+  async forceNullifyNotes(nullifiers: bigint[]): Promise<number[]> {
+    return await this.db.nullifyNotes(nullifiers);
+  }
+
+  getCurrentTreeRoot(): bigint {
+    return this.merkleProver.getRoot();
+  }
+
+  async hasEnoughBalanceForOperationRequest(
+    opRequest: OperationRequest
+  ): Promise<boolean> {
+    const assetRequestedAmounts = new MapWithObjectKeys<Asset, bigint>();
+    for (const joinSplitRequest of opRequest.joinSplitRequests) {
+      const asset = joinSplitRequest.asset;
+      let currentAmount = assetRequestedAmounts.get(asset) || 0n;
+      currentAmount += getJoinSplitRequestTotalValue(joinSplitRequest);
+      assetRequestedAmounts.set(asset, currentAmount);
+    }
+
+    for (const [asset, requestedAmount] of assetRequestedAmounts.entries()) {
+      const balance = await this.db.getBalanceForAsset(asset);
+      if (balance < requestedAmount) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  async getCreationBlockOfNewestNoteInOp(
+    op: PreSignOperation | SignedOperation
+  ): Promise<number> {
+    const totalEntityIndex = await getTotalEntityIndexOfNewestNoteInOp(
+      this.db,
+      op
+    );
+    return Number(
+      TotalEntityIndexTrait.toComponents(totalEntityIndex).blockNumber
+    );
+  }
+
+  async addOpToHistory(
+    op: PreSignOperation | SignedOperation,
+    metadata: OperationMetadata
+  ): Promise<void> {
+    await this.db.addOpToHistory(op, metadata);
+  }
+
+  async removeOpFromHistory(digest: bigint): Promise<void> {
+    await this.db.removeOpFromHistory(digest);
+  }
+
+  async getOpHistory(includePending?: boolean): Promise<OpHistoryRecord[]> {
+    return await this.db.getHistory(includePending);
+  }
+
+  async getOpHistoryRecord(
+    digest: bigint
+  ): Promise<OpHistoryRecord | undefined> {
+    return await this.db.getHistoryRecord(digest);
+  }
+
+  async setOpStatusInHistory(
+    digest: bigint,
+    status: OperationStatus
+  ): Promise<void> {
+    await this.db.setStatusForOp(digest, status);
+  }
+
+  async pruneOptimisticNullifiers(): Promise<void> {
+    await this.db.pruneOptimisticNFs();
+  }
+}
+
+export async function getTotalEntityIndexOfNewestNoteInOp(
+  db: NocturneDB,
+  op: PreSignOperation | SignedOperation
+): Promise<TotalEntityIndex> {
+  // get the max merkle index of any note in any joinsplit in the op
+  const maxMerkleIndex = maxArray(
+    getMerkleIndicesAndNfsFromOp(op).map(({ merkleIndex }) => merkleIndex)
+  );
+
+  // get the corresponding TotalEntityIndex
+  const totalEntityIndex = await db.getTotalEntityIndexForMerkleIndex(
+    Number(maxMerkleIndex)
+  );
+
+  if (totalEntityIndex === undefined) {
+    throw new Error(
+      `totalEntityIndex not found for newest note with merkle index ${maxMerkleIndex}`
+    );
+  }
+
+  return totalEntityIndex;
+}