@zill-protocol/client 4.1.2

package/src/snapJsonRpc.ts

@@ -0,0 +1,109 @@
+import {
+  Address,
+  CanonAddrRegistryEntry,
+  PreSignOperation,
+  SignedOperation,
+} from "@zill-protocol/core";
+import {
+  CanonAddress,
+  NocturneSignature,
+  SpendPk,
+  ViewingKey,
+} from "@zill-protocol/crypto";
+import * as JSON from "bigint-json-serialization";
+import { OperationWithMetadata } from "./types";
+
+export interface SetSpendKeyMethod {
+  method: "nocturne_setSpendKey";
+  params: {
+    spendKey: string;
+    eoaAddress: Address;
+  };
+  return: string | null; // error string or null
+}
+
+export interface SignCanonAddrRegistryEntryMethod {
+  method: "nocturne_signCanonAddrRegistryEntry";
+  params: {
+    entry: CanonAddrRegistryEntry;
+    chainId: bigint;
+    registryAddress: string;
+  };
+  return: {
+    canonAddr: CanonAddress;
+    digest: bigint;
+    sig: NocturneSignature;
+    spendPubkey: SpendPk;
+    vkNonce: bigint;
+  };
+}
+
+export interface SignOperationMethod {
+  method: "nocturne_signOperation";
+  params: OperationWithMetadata<PreSignOperation>;
+  return: SignedOperation;
+}
+
+export interface RequestSpendKeyEoaMethod {
+  method: "nocturne_requestSpendKeyEoa";
+  params: null;
+  return: Address | null;
+}
+
+export interface RequestViewingKeyMethodResponse {
+  vk: ViewingKey;
+  vkNonce: bigint;
+}
+
+export interface RequestViewingKeyMethod {
+  method: "nocturne_requestViewingKey";
+  params: null;
+  return: RequestViewingKeyMethodResponse;
+}
+
+export type RpcRequestMethod =
+  | SetSpendKeyMethod
+  | SignCanonAddrRegistryEntryMethod
+  | SignOperationMethod
+  | RequestViewingKeyMethod
+  | RequestSpendKeyEoaMethod;
+
+export type SnapRpcRequestHandlerArgs = {
+  origin: string;
+  request: RpcRequestMethod;
+};
+
+export type SnapRpcRequestHandler = (
+  args: SnapRpcRequestHandlerArgs
+) => Promise<RpcRequestMethod["return"]>;
+
+export function assertAllRpcMethodsHandled(request: never): never {
+  // @ts-expect-error on request.method—if this fires at runtime, we want to see the method name
+  throw new Error("Snap JSON RPC method not handled: " + request.method);
+}
+
+export function parseObjectValues(params: object): object {
+  return Object.fromEntries(
+    Object.entries(params).map(([key, value]) => {
+      const parsedValue = JSON.parse(value);
+      if (parsedValue && parsedValue.__primitive) {
+        return [key, parsedValue.value ?? undefined];
+      } else {
+        return [key, parsedValue];
+      }
+    })
+  );
+}
+
+export function stringifyObjectValues(params: object): object {
+  return Object.fromEntries(
+    Object.entries(params).map(([key, value]) => [
+      key,
+      JSON.stringify(
+        typeof value === "object"
+          ? value
+          : { __primitive: true, value: value ?? null }
+      ),
+    ])
+  );
+}

package/src/syncSDK.ts

@@ -0,0 +1,285 @@
+import { NocturneViewer } from "@zill-protocol/crypto";
+import { NocturneDB } from "./NocturneDB";
+import { PendingOutputRecord } from "./types";
+import {
+  IncludedEncryptedNote,
+  IncludedNote,
+  IncludedNoteCommitment,
+  NoteTrait,
+  EncryptedStateDiff,
+  StateDiff,
+  SDKSyncAdapter,
+  TotalEntityIndexTrait,
+  decryptNote,
+  SparseMerkleProver,
+  consecutiveChunks,
+  timed,
+  timedAsync,
+  Histogram,
+} from "@zill-protocol/core";
+
+export interface SyncOpts {
+  endBlock?: number;
+  timeoutSeconds?: number;
+  timing?: boolean;
+  finalityBlocks?: number;
+  debug?: boolean;
+  onPendingOutputsConfirmed?: (outputs: PendingOutputRecord[]) => void;
+}
+
+export interface SyncDeps {
+  viewer: NocturneViewer;
+}
+
+// Sync SDK, returning last synced merkle index of last state diff
+export async function syncSDK(
+  { viewer }: SyncDeps,
+  adapter: SDKSyncAdapter,
+  db: NocturneDB,
+  merkle: SparseMerkleProver,
+  opts?: SyncOpts
+): Promise<number | undefined> {
+  const currTotalEntityIndex = await db.currentTotalEntityIndex();
+  const startTotalEntityIndex = currTotalEntityIndex
+    ? currTotalEntityIndex + 1n
+    : 0n;
+
+  const currentBlock = await adapter.getLatestIndexedBlock();
+  const endTotalEntityIndex = TotalEntityIndexTrait.fromBlockNumber(
+    opts?.endBlock ?? currentBlock
+  );
+  const range = {
+    startTotalEntityIndex,
+    endTotalEntityIndex,
+    startBlock: TotalEntityIndexTrait.toComponents(startTotalEntityIndex)
+      .blockNumber,
+    endBlock: currentBlock,
+  };
+  if (opts?.debug) {
+    console.log(
+      `[syncSDK] syncing SDK from totalEntityIndex ${startTotalEntityIndex} (block ${range.startBlock}) to ${endTotalEntityIndex} (block ${currentBlock})...`,
+      { range }
+    );
+  }
+
+  const newDiffs = adapter.iterStateDiffs(startTotalEntityIndex, {
+    endTotalEntityIndex,
+    timing: opts?.timing,
+    finalityBlocks: opts?.finalityBlocks,
+  });
+
+  // decrypt notes and compute nullifiers
+  const diffHistogram = opts?.timing
+    ? new Histogram("decryptStateDiff time (ms) per note")
+    : undefined;
+  const diffs = newDiffs.map((diff) => {
+    const [decrypted, time] = timed(() => decryptStateDiff(viewer, diff));
+    diffHistogram?.sample(time / diff.notes.length);
+    return decrypted;
+  });
+
+  let latestSyncedMerkleIndex: number | undefined =
+    await db.latestSyncedMerkleIndex();
+
+  if (opts?.timeoutSeconds) {
+    setTimeout(() => diffs.close(), opts.timeoutSeconds * 1000);
+  }
+
+  // apply diffs
+  const applyStateDiffHistogram = opts?.timing
+    ? new Histogram("applyStateDiff time (ms) per note or commitment")
+    : undefined;
+  const updateMerkleHistogram = opts?.timing
+    ? new Histogram("updateMerkle time (ms) per note or commitment")
+    : undefined;
+  for await (const diff of diffs.iter) {
+    if (opts?.debug) {
+      console.log(
+        "[syncSDK] diff latestNewlySyncedMerkleIndex",
+        diff.latestNewlySyncedMerkleIndex
+      );
+    }
+    // update notes in DB
+    const [nfIndices, nfTime] = await timedAsync(() =>
+      db.applyStateDiff(
+        diff,
+        opts?.onPendingOutputsConfirmed
+          ? { onPendingOutputsConfirmed: opts.onPendingOutputsConfirmed }
+          : undefined
+      )
+    );
+    applyStateDiffHistogram?.sample(nfTime / diff.notesAndCommitments.length);
+    latestSyncedMerkleIndex = await db.latestSyncedMerkleIndex();
+
+    // TODO: deal with case where we have failure between applying state diff to DB and merkle being persisted
+
+    if (diff.latestCommittedMerkleIndex) {
+      const [_, time] = await timedAsync(() =>
+        updateMerkle(
+          merkle,
+          diff.latestCommittedMerkleIndex!,
+          diff.notesAndCommitments.map((n) => n.inner),
+          nfIndices,
+          opts?.debug ?? false
+        )
+      );
+      updateMerkleHistogram?.sample(time / diff.notesAndCommitments.length);
+    }
+  }
+
+  diffHistogram?.print();
+  applyStateDiffHistogram?.print();
+  updateMerkleHistogram?.print();
+
+  return latestSyncedMerkleIndex;
+}
+
+async function updateMerkle(
+  merkle: SparseMerkleProver,
+  latestCommittedMerkleIndex: number,
+  notesAndCommitments: (IncludedNote | IncludedNoteCommitment)[],
+  nfIndices: number[],
+  logWarnings: boolean
+): Promise<void> {
+  const ordered = [...notesAndCommitments].sort(
+    (a, b) => a.merkleIndex - b.merkleIndex
+  );
+  const currentCount = merkle.count();
+  const filtered = ordered.filter(
+    (noteOrCommitment) => noteOrCommitment.merkleIndex >= currentCount
+  );
+  if (logWarnings && filtered.length !== ordered.length) {
+    console.warn("[syncSDK] skipping stale leaves", {
+      currentCount,
+      skipped: ordered.length - filtered.length,
+      first: ordered[0]?.merkleIndex,
+      last: ordered[ordered.length - 1]?.merkleIndex,
+    });
+  }
+
+  // add all new leaves as uncommitted leaves
+  const batches = consecutiveChunks(
+    filtered,
+    (noteOrCommitment) => noteOrCommitment.merkleIndex
+  );
+  for (const batch of batches) {
+    const startIndex = batch[0].merkleIndex;
+    const leaves = [];
+    const includes = [];
+    for (const noteOrCommitment of batch) {
+      if (NoteTrait.isCommitment(noteOrCommitment)) {
+        leaves.push(
+          (noteOrCommitment as IncludedNoteCommitment).noteCommitment
+        );
+        includes.push(false);
+      } else {
+        leaves.push(NoteTrait.toCommitment(noteOrCommitment as IncludedNote));
+        includes.push(true);
+      }
+    }
+    merkle.insertBatchUncommitted(startIndex, leaves, includes);
+  }
+
+  // commit up to latest subtree commit
+  merkle.commitUpToIndex(latestCommittedMerkleIndex);
+
+  // mark nullified ones for pruning
+  for (const index of nfIndices) {
+    try {
+      merkle.markForPruning(index);
+    } catch (err) {
+      if (logWarnings) {
+        console.warn("[syncSDK] skip pruning missing leaf", {
+          index,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  }
+
+  // persist merkle to underlying KV store
+  await merkle.persist();
+}
+
+function decryptStateDiff(
+  viewer: NocturneViewer,
+  {
+    notes,
+    nullifiers,
+    latestCommittedMerkleIndex,
+    latestCommitTei,
+    latestNewlySyncedMerkleIndex,
+    totalEntityIndex,
+  }: EncryptedStateDiff
+): StateDiff {
+  const notesAndCommitments = notes.map(({ inner, totalEntityIndex }) => {
+    const note = inner;
+    const isEncrypted = NoteTrait.isEncryptedNote(note);
+    if (isEncrypted) {
+      // if it's encrypted, attempt to decrypt.
+      // if it succeeds, then return the decrypted note
+      // if it fails, assume it's not ours and just the commitment and merkle index
+      try {
+        const { merkleIndex, commitment, ...encryptedNote } =
+          note as IncludedEncryptedNote;
+
+        // TODO: come up with a way to handle sender mismatches when we implement history proofs
+        const includedNote: IncludedNote = {
+          ...decryptNote(viewer, encryptedNote),
+          merkleIndex,
+        };
+        const nullifier = NoteTrait.createNullifier(viewer, includedNote);
+        const res = { ...includedNote, nullifier };
+        return {
+          inner: res,
+          totalEntityIndex,
+        };
+      } catch (err) {
+        const encryptedNote = note as IncludedEncryptedNote;
+        const { commitment, merkleIndex } = encryptedNote;
+        const nc = {
+          noteCommitment: commitment,
+          merkleIndex,
+        };
+
+        return {
+          inner: nc,
+          totalEntityIndex,
+        };
+      }
+    } else {
+      // if it's not encrypted, check if it's ours.
+      // if it is, then return it
+      // if it's not, return only the commitment
+      const includedNote = note as IncludedNote;
+      const isOwn = viewer.isOwnAddress(includedNote.owner);
+
+      if (isOwn) {
+        const nullifier = NoteTrait.createNullifier(viewer, includedNote);
+        const res = { ...includedNote, nullifier };
+        return {
+          inner: res,
+          totalEntityIndex,
+        };
+      } else {
+        const nc = {
+          noteCommitment: NoteTrait.toCommitment(includedNote),
+          merkleIndex: includedNote.merkleIndex,
+        };
+        return {
+          inner: nc,
+          totalEntityIndex,
+        };
+      }
+    }
+  });
+
+  return {
+    notesAndCommitments,
+    nullifiers,
+    latestCommittedMerkleIndex,
+    latestCommitTei,
+    latestNewlySyncedMerkleIndex,
+    totalEntityIndex,
+  };
+}

package/src/types.ts

@@ -0,0 +1,83 @@
+import {
+  Address,
+  Asset,
+  CanonAddress,
+  Operation,
+  OperationStatus,
+} from "@zill-protocol/core";
+
+export type OpWithMetadata<O> = {
+  op: O;
+  metadata: OperationMetadata;
+};
+
+export interface OptimisticNFRecord {
+  nullifier: bigint;
+  expirationDate: number;
+}
+
+export type OpHistoryRecord = {
+  digest: bigint;
+  metadata: OperationMetadata;
+
+  spentNoteMerkleIndices: number[];
+
+  status?: OperationStatus;
+
+  createdAt: number;
+  lastModified: number;
+};
+
+export interface OperationMetadata {
+  items: OperationMetadataItem[];
+}
+
+export type PendingOutputRecord = {
+  commitment: bigint;
+  asset: Asset;
+  value: bigint;
+  createdAt: number;
+  opDigest?: bigint;
+  expectedInsertionIndex?: number;
+};
+
+export type OperationMetadataItem =
+  | ConfidentialPaymentMetadata
+  | ActionMetadata;
+
+export type ActionMetadata =
+  | {
+      type: "Action";
+      actionType: "Transfer";
+      recipientAddress: Address;
+      erc20Address: Address;
+      amount: bigint;
+    }
+  | {
+      type: "Action";
+      actionType: "Weth To Wsteth";
+      amount: bigint;
+    }
+  | {
+      type: "Action";
+      actionType: "Transfer ETH";
+      recipientAddress: Address;
+      amount: bigint;
+    };
+
+export interface ConfidentialPaymentMetadata {
+  type: "ConfidentialPayment";
+  recipient: CanonAddress;
+  asset: Asset;
+  amount: bigint;
+}
+
+export interface OpDigestWithMetadata {
+  opDigest: bigint;
+  metadata?: OperationMetadata;
+}
+
+export interface OperationWithMetadata<T extends Operation> {
+  op: T;
+  metadata?: OperationMetadata;
+}

package/src/utils/constants.ts

@@ -0,0 +1,16 @@
+export function chainIdToNetworkName(chainId: bigint): string {
+  switch (chainId) {
+    case 1n:
+      return "mainnet";
+    case 5n:
+      return "goerli";
+    case 11155111n:
+      return "sepolia";
+    case 31337n:
+      return "localhost";
+    default:
+      throw new Error(`unsupported chainId: ${chainId}`);
+  }
+}
+
+export const OPTIMISTIC_RECORD_TTL: number = 30 * 60 * 1000; // 30 minutes

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from "./constants";
+export * from "./misc";

package/src/utils/misc.ts

@@ -0,0 +1,107 @@
+import {
+  SignedOperation,
+  PreSignOperation,
+  PreProofJoinSplit,
+  PreSignJoinSplit,
+  Note,
+  IncludedNote,
+  Asset,
+  MapWithObjectKeys,
+  merklePathToIndex,
+  OperationStatus,
+} from "@zill-protocol/core";
+import { JoinSplitRequest } from "../operationRequest";
+
+export function sortNotesByValue<T extends Note>(notes: T[]): T[] {
+  return notes.sort((a, b) => {
+    return Number(a.value - b.value);
+  });
+}
+
+export function getJoinSplitRequestTotalValue(
+  joinSplitRequest: JoinSplitRequest
+): bigint {
+  let totalVal = joinSplitRequest.unwrapValue;
+  if (joinSplitRequest.payment !== undefined) {
+    totalVal += joinSplitRequest.payment.value;
+  }
+  return totalVal;
+}
+
+export interface NullifierWithMerkleIndex {
+  nullifier: bigint;
+  merkleIndex: bigint;
+}
+
+export function getIncludedNotesFromOp(
+  op: PreSignOperation
+): MapWithObjectKeys<Asset, IncludedNote[]> {
+  const notesMap: MapWithObjectKeys<Asset, IncludedNote[]> =
+    new 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
+export function getMerkleIndicesAndNfsFromOp(
+  op: PreSignOperation | SignedOperation
+): NullifierWithMerkleIndex[] {
+  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: bigint[];
+    let merklePathB: bigint[];
+
+    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 as PreProofJoinSplit).proofInputs.merkleProofA
+        .path;
+      merklePathB = (joinSplit as PreProofJoinSplit).proofInputs.merkleProofB
+        .path;
+    } else {
+      // otherwise, it's a `PreSignJoinSplit`, in which case we get it out of the joinsplit itself
+      merklePathA = (joinSplit as PreSignJoinSplit).merkleProofA.path;
+      merklePathB = (joinSplit as PreSignJoinSplit).merkleProofB.path;
+    }
+
+    return [
+      {
+        merkleIndex: merklePathToIndex(merklePathA, "LEAF_TO_ROOT"),
+        nullifier: joinSplit.nullifierA,
+      },
+      {
+        merkleIndex: merklePathToIndex(merklePathB, "LEAF_TO_ROOT"),
+        nullifier: joinSplit.nullifierB,
+      },
+    ];
+  });
+}
+
+export function isFailedOpStatus(status: OperationStatus): boolean {
+  return (
+    status === OperationStatus.BUNDLE_REVERTED ||
+    status === OperationStatus.OPERATION_EXECUTION_FAILED ||
+    status === OperationStatus.OPERATION_PROCESSING_FAILED
+  );
+}
+
+export function isTerminalOpStatus(status: OperationStatus): boolean {
+  return (
+    status === OperationStatus.EXECUTED_SUCCESS || isFailedOpStatus(status)
+  );
+}