@unlink-xyz/core 0.1.0 → 0.1.2

package/state/merkle/hydrator.ts

@@ -0,0 +1,69 @@
+import { parseHexToBigInt } from "../../utils/bigint.js";
+
+export type LeafLoader = (
+  chainId: number,
+  index: number,
+) => Promise<{ commitment: string } | null>;
+
+export async function rebuildTreeFromStore({
+  chainId,
+  trees,
+  loadLeaf,
+}: {
+  chainId: number;
+  trees: {
+    reset(chainId: number): void;
+    addLeaf(chainId: number, value: bigint): { index: number };
+    getLeafCount?(chainId: number): number;
+  };
+  loadLeaf: LeafLoader;
+}) {
+  trees.reset(chainId);
+  let idx = 0;
+  for (;;) {
+    const leaf = await loadLeaf(chainId, idx);
+    if (!leaf) break;
+    const { index } = trees.addLeaf(chainId, parseHexToBigInt(leaf.commitment));
+    if (index !== idx) {
+      throw new Error(
+        `stored leaves are inconsistent with local tree, expected ${idx}, got ${index}`,
+      );
+    }
+    idx += 1;
+  }
+  return idx;
+}
+
+export type HydrateChainParams = {
+  chainId: number;
+  trees: {
+    reset(chainId: number): void;
+    addLeaf(chainId: number, value: bigint): { index: number };
+  };
+  loadLeaf: LeafLoader;
+  hydrated: Set<number>;
+};
+
+// TODO: Will be used for inmemory merkle tree handling for caching.
+// Atm everytime we need to access the tree we have to rebuild it from the store.
+// This function will help to avoid multiple rebuilds for the same chain
+export async function hydrateChain({
+  chainId,
+  trees,
+  loadLeaf,
+  hydrated,
+}: HydrateChainParams) {
+  if (hydrated.has(chainId)) return;
+  trees.reset(chainId);
+  let idx = 0;
+  for (;;) {
+    const leaf = await loadLeaf(chainId, idx);
+    if (!leaf) break;
+    const { index } = trees.addLeaf(chainId, parseHexToBigInt(leaf.commitment));
+    if (index !== idx) {
+      throw new Error("stored leaves are inconsistent with local tree");
+    }
+    idx += 1;
+  }
+  hydrated.add(chainId);
+}

package/state/merkle/index.ts

@@ -0,0 +1,12 @@
+export {
+  createLocalMerkleTree,
+  createMerkleTrees,
+  type LocalMerkleTree,
+  type LocalMerkleTrees,
+  type MerkleProof,
+} from "./merkle-tree.js";
+export {
+  hydrateChain,
+  rebuildTreeFromStore,
+  type HydrateChainParams,
+} from "./hydrator.js";

package/state/merkle/merkle-tree.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+
+import { createLocalMerkleTree } from "./merkle-tree.js";
+
+describe("local merkle tree", () => {
+  it("returns deterministic roots for identical insert sequences", () => {
+    const inserts = [0x01n, 0x02n, 0x03n];
+
+    const treeA = createLocalMerkleTree();
+    const rootsA = inserts.map((leaf) => treeA.addLeaf(leaf).root);
+
+    const treeB = createLocalMerkleTree();
+    const rootsB = inserts.map((leaf) => treeB.addLeaf(leaf).root);
+
+    expect(rootsA).toEqual(rootsB);
+    expect(treeA.getRoot()).toBe(treeB.getRoot());
+  });
+
+  it("tracks inserted leaf count and updates root", () => {
+    const tree = createLocalMerkleTree();
+    const initialRoot = tree.getRoot();
+
+    const first = tree.addLeaf(1n);
+    expect(tree.getLeafCount()).toBe(1);
+    expect(first.index).toBe(0);
+    expect(first.root).not.toBe(initialRoot);
+
+    const second = tree.addLeaf(0x02n);
+    expect(tree.getLeafCount()).toBe(2);
+    expect(second.index).toBe(1);
+    expect(second.root).not.toBe(first.root);
+  });
+
+  it("exposes zero hashes for valid levels and rejects invalid ones", () => {
+    const tree = createLocalMerkleTree();
+
+    expect(tree.getZero(0)).toMatch(/^0x[0-9a-f]+$/);
+    expect(() => tree.getZero(-1)).toThrow("invalid level");
+    expect(() => tree.getZero(tree.depth + 1)).toThrow("invalid level");
+  });
+
+  it("starts with zero root until the first insert", () => {
+    const tree = createLocalMerkleTree();
+    const emptyRoot = tree.getRoot();
+
+    expect(emptyRoot).toBe(tree.getZero(tree.depth));
+    tree.addLeaf(5n);
+    expect(tree.getRoot()).not.toBe(emptyRoot);
+  });
+});

package/state/merkle/merkle-tree.ts

@@ -0,0 +1,163 @@
+import { poseidon } from "@railgun-community/circomlibjs";
+import {
+  IMT,
+  IMTMerkleProof,
+  type IMTHashFunction,
+  type IMTNode,
+} from "@zk-kit/imt";
+
+import { ByteLength, ByteUtils } from "../../key-derivation/bytes.js";
+import { ensureChainId } from "../../utils/validators.js";
+
+type BigIntTree = IMT & {
+  root: bigint;
+  zeroes: bigint[];
+  leaves: bigint[];
+};
+
+export type AddLeafResult = {
+  index: number;
+  root: string;
+};
+
+export type MerkleProof = {
+  root: string;
+  leaf: string;
+  pathElements: string[][];
+  pathIndices: number[];
+  leafIndex: number;
+};
+
+const DEFAULT_DEPTH = 16;
+const DEFAULT_ARITY = 2;
+const ZERO_BYTE_LENGTH = ByteLength.UINT_256;
+
+// Simple adapter: IMTNode[] -> poseidon(bigint[])
+const hash: IMTHashFunction = (values: IMTNode[]) =>
+  poseidon(values.map((v) => BigInt(v)));
+
+const formatNode = (value: bigint) =>
+  ByteUtils.nToHex(value, ZERO_BYTE_LENGTH, true);
+
+export function createLocalMerkleTree() {
+  const zeroLeaf = 0n;
+  const capacity = 2 ** DEFAULT_DEPTH;
+  const tree = new IMT(
+    hash,
+    DEFAULT_DEPTH,
+    zeroLeaf,
+    DEFAULT_ARITY,
+  ) as BigIntTree;
+
+  function addLeaf(value: bigint): AddLeafResult {
+    if (tree.leaves.length >= capacity) {
+      throw new Error("merkle tree is full");
+    }
+
+    const insertedIndex = tree.leaves.length;
+    tree.insert(value);
+
+    return {
+      index: insertedIndex,
+      root: formatNode(tree.root),
+    };
+  }
+
+  function getRoot() {
+    return formatNode(tree.root);
+  }
+
+  function getLeafCount() {
+    return tree.leaves.length;
+  }
+
+  function getLeaf(index: number) {
+    const leaf = tree.leaves[index];
+    if (leaf === undefined) {
+      throw new Error("leaf does not exist in this tree");
+    }
+    return formatNode(BigInt(leaf));
+  }
+
+  function createMerkleProof(index: number): IMTMerkleProof {
+    return tree.createProof(index);
+  }
+
+  return {
+    addLeaf,
+    getRoot,
+    getLeafCount,
+    getLeaf,
+    createMerkleProof,
+    getZero(level: number) {
+      if (level === tree.depth) {
+        return getRoot();
+      }
+      const zero = tree.zeroes[level];
+      if (zero === undefined) {
+        throw new Error("invalid level");
+      }
+      return formatNode(zero);
+    },
+    get depth() {
+      return tree.depth;
+    },
+    get capacity() {
+      return capacity;
+    },
+  };
+}
+
+export type LocalMerkleTree = ReturnType<typeof createLocalMerkleTree>;
+
+export type LocalMerkleTrees = {
+  get(chainId: number): LocalMerkleTree | undefined;
+  getOrCreate(chainId: number): LocalMerkleTree;
+  addLeaf(chainId: number, value: bigint): AddLeafResult;
+  createMerkleProof(chainId: number, index: number): IMTMerkleProof;
+  getRoot(chainId: number): string;
+  getLeafCount(chainId: number): number;
+  reset(chainId: number): void;
+};
+
+export function createMerkleTrees(): LocalMerkleTrees {
+  const trees = new Map<number, LocalMerkleTree>();
+
+  const resetTree = (chainId: number) => {
+    ensureChainId(chainId);
+    const tree = createLocalMerkleTree();
+    trees.set(chainId, tree);
+    return tree;
+  };
+  const getOrCreate = (chainId: number) => {
+    ensureChainId(chainId);
+    let tree = trees.get(chainId);
+    if (!tree) {
+      tree = resetTree(chainId);
+    }
+    return tree;
+  };
+
+  return {
+    get(chainId) {
+      ensureChainId(chainId);
+      return trees.get(chainId);
+    },
+    getOrCreate,
+    addLeaf(chainId, value) {
+      return getOrCreate(chainId).addLeaf(value);
+    },
+    createMerkleProof(chainId, index) {
+      return getOrCreate(chainId).createMerkleProof(index);
+    },
+    getRoot(chainId) {
+      return getOrCreate(chainId).getRoot();
+    },
+    getLeafCount(chainId) {
+      return getOrCreate(chainId).getLeafCount();
+    },
+    reset(chainId) {
+      resetTree(chainId);
+    },
+  };
+}

package/state/store/ciphertext-store.ts

@@ -0,0 +1,28 @@
+import { keys, validateKey } from "../../keys.js";
+import type { Storage } from "../../types.js";
+import { ensureChainId, ensurePositiveInt } from "../../utils/validators.js";
+
+export function createCiphertextStore(storage: Storage) {
+  return {
+    /**
+     * Store encrypted note payloads alongside their on-chain commitments.
+     */
+    async putCiphertext(chainId: number, index: number, payload: Uint8Array) {
+      ensureChainId(chainId);
+      ensurePositiveInt("ciphertext index", index);
+      const key = keys.ciphertext(chainId, index);
+      validateKey(key);
+      await storage.put(key, new Uint8Array(payload));
+    },
+
+    /**
+     * Retrieve encrypted note payloads; returns null when the ciphertext is missing.
+     */
+    async getCiphertext(chainId: number, index: number) {
+      ensureChainId(chainId);
+      ensurePositiveInt("ciphertext index", index);
+      const data = await storage.get(keys.ciphertext(chainId, index));
+      return data ? new Uint8Array(data) : null;
+    },
+  };
+}

package/state/store/index.ts

@@ -0,0 +1,24 @@
+export { createStateStore } from "./store.js";
+export { createLeafStore } from "./leaf-store.js";
+export { createNoteStore } from "./note-store.js";
+export { createNullifierStore } from "./nullifier-store.js";
+export { createRootStore } from "./root-store.js";
+export { createCiphertextStore } from "./ciphertext-store.js";
+export { createJobStore } from "./job-store.js";
+export {
+  DEFAULT_JOB_TIMEOUT_MS,
+  type JobStatus,
+  type PendingJobKind,
+  type PendingJobRecord,
+  type PendingDepositJob,
+  type PendingTransactJob,
+  type PendingTransactContext,
+  type PendingTransactOutput,
+} from "./jobs.js";
+export type {
+  LeafRecord,
+  NoteInsert,
+  NoteRecord,
+  NullifierRecord,
+  RootRecord,
+} from "./records.js";

package/state/store/job-store.ts

@@ -0,0 +1,162 @@
+import { keys } from "../../keys.js";
+import type { Storage } from "../../types.js";
+import { decodeJson, encodeJson, getJson } from "../../utils/json-codec.js";
+import {
+  ensureAddress,
+  ensureChainId,
+  ensurePositiveInt,
+} from "../../utils/validators.js";
+import type {
+  JobStatus,
+  PendingDepositJob,
+  PendingJobKind,
+  PendingJobRecord,
+  PendingTransactContext,
+  PendingTransactJob,
+} from "../store/jobs.js";
+import { DEFAULT_JOB_TIMEOUT_MS } from "../store/jobs.js";
+
+const VALID_STATUSES: JobStatus[] = [
+  "pending",
+  "submitted",
+  "broadcasting",
+  "succeeded",
+  "failed",
+  "dead",
+] as const;
+
+function assertStatus(status: string): asserts status is JobStatus {
+  if (!VALID_STATUSES.includes(status as JobStatus)) {
+    throw new Error(`invalid job status: ${status}`);
+  }
+}
+
+function assertKind(kind: string): asserts kind is PendingJobKind {
+  if (kind !== "deposit" && kind !== "transact") {
+    throw new Error(`invalid job kind: ${kind}`);
+  }
+}
+
+function normalizeTimestamps<T extends PendingJobRecord>(job: T): T {
+  const createdAt =
+    typeof job.createdAt === "number" && Number.isFinite(job.createdAt)
+      ? job.createdAt
+      : Date.now();
+  const timeoutMs =
+    typeof job.timeoutMs === "number" && job.timeoutMs > 0
+      ? job.timeoutMs
+      : DEFAULT_JOB_TIMEOUT_MS;
+
+  return {
+    ...job,
+    createdAt,
+    timeoutMs,
+  };
+}
+
+function validateTransactContext(context: PendingTransactContext) {
+  ensurePositiveInt("context index", context.index);
+  if (!context.nullifier) {
+    throw new Error("context nullifier is required");
+  }
+  const { witness } = context;
+  if (!witness) {
+    throw new Error("context witness is required");
+  }
+  ensurePositiveInt("witness leafIndex", witness.leafIndex);
+  if (
+    !Array.isArray(witness.pathElements) ||
+    !Array.isArray(witness.pathIndices)
+  ) {
+    throw new Error("witness pathElements and pathIndices are required");
+  }
+}
+
+function validateTransactJob(job: PendingTransactJob) {
+  ensureAddress("pool address", job.poolAddress);
+  if (!job.calldata) {
+    throw new Error("calldata is required for transact job");
+  }
+  job.contexts.forEach(validateTransactContext);
+  job.predictedOutputs.forEach((output) => {
+    if (!output.hex) {
+      throw new Error("predicted output hex is required");
+    }
+    ensurePositiveInt("predicted output index", output.index);
+  });
+}
+
+function validateDepositJob(job: PendingDepositJob) {
+  if (!job.predictedCommitment?.hex) {
+    throw new Error("predicted commitment hex is required");
+  }
+  if (job.predictedCommitment.index !== undefined) {
+    ensurePositiveInt(
+      "predicted commitment index",
+      job.predictedCommitment.index,
+    );
+  }
+}
+
+function validateJob(job: PendingJobRecord) {
+  if (!job.relayId) {
+    throw new Error("relayId is required");
+  }
+  ensureChainId(job.chainId);
+  assertStatus(job.status);
+  assertKind(job.kind);
+  ensurePositiveInt("job createdAt", job.createdAt);
+  ensurePositiveInt("job timeoutMs", job.timeoutMs);
+  if (job.lastCheckedAt !== undefined) {
+    ensurePositiveInt("job lastCheckedAt", job.lastCheckedAt);
+  }
+  if (job.kind === "deposit") {
+    validateDepositJob(job);
+  } else {
+    validateTransactJob(job);
+  }
+}
+
+function buildJobKey(relayId: string) {
+  return keys.job(relayId);
+}
+
+export function createJobStore(storage: Storage) {
+  return {
+    async putPendingJob(job: PendingJobRecord) {
+      const normalized = normalizeTimestamps(job);
+      validateJob(normalized);
+      await storage.put(
+        buildJobKey(normalized.relayId),
+        encodeJson(normalized),
+      );
+    },
+
+    async getPendingJob(relayId: string) {
+      return getJson<PendingJobRecord>(storage, buildJobKey(relayId));
+    },
+
+    async listPendingJobs(
+      filter: {
+        kind?: PendingJobKind;
+        statuses?: JobStatus[];
+      } = {},
+    ) {
+      const entries = await storage.iter({ prefix: "jobs:" });
+      const statuses = filter.statuses ?? VALID_STATUSES;
+      const filtered = entries
+        .map(({ value }) => decodeJson<PendingJobRecord>(value))
+        .filter(
+          (job) =>
+            (filter.kind === undefined || job.kind === filter.kind) &&
+            statuses.includes(job.status),
+        );
+      filtered.sort((a, b) => a.createdAt - b.createdAt);
+      return filtered;
+    },
+
+    async deletePendingJob(relayId: string) {
+      await storage.delete(buildJobKey(relayId));
+    },
+  };
+}

package/state/store/jobs.ts

@@ -0,0 +1,64 @@
+export type JobStatus =
+  | "pending"
+  | "submitted"
+  | "broadcasting"
+  | "succeeded"
+  | "failed"
+  | "dead";
+
+export type PendingJobKind = "deposit" | "transact";
+
+export type PendingJobBase = {
+  relayId: string;
+  kind: PendingJobKind;
+  chainId: number;
+  status: JobStatus;
+  broadcasterRelayId?: string | null;
+  txHash?: string | null;
+  createdAt: number;
+  lastCheckedAt?: number;
+  timeoutMs: number;
+  error?: string | null;
+};
+
+export type PendingDepositJob = PendingJobBase & {
+  kind: "deposit";
+  predictedCommitment: {
+    hex: string;
+    index?: number;
+    root?: string;
+  };
+};
+
+export type PendingTransactContext = {
+  index: number;
+  nullifier: string;
+  // Serialized Merkle proof with hex-encoded nodes to keep it JSON friendly.
+  witness: {
+    root: string;
+    leaf: string;
+    pathElements: string[][];
+    pathIndices: number[];
+    leafIndex: number;
+  };
+  root: string;
+};
+
+export type PendingTransactOutput = {
+  hex: string;
+  index: number;
+  root?: string;
+};
+
+export type PendingTransactJob = PendingJobBase & {
+  kind: "transact";
+  poolAddress: string;
+  calldata: string;
+  contexts: PendingTransactContext[];
+  predictedOutputs: PendingTransactOutput[];
+  expectedRoot?: string;
+};
+
+export type PendingJobRecord = PendingDepositJob | PendingTransactJob;
+
+export const DEFAULT_JOB_TIMEOUT_MS = 5 * 60 * 1000;

package/state/store/leaf-store.ts

@@ -0,0 +1,39 @@
+import { keys } from "../../keys.js";
+import type { Storage } from "../../types.js";
+import { getJson, putJson } from "../../utils/json-codec.js";
+import { ensureChainId, ensurePositiveInt } from "../../utils/validators.js";
+import type { LeafRecord } from "../store/records.js";
+
+export function createLeafStore(storage: Storage) {
+  return {
+    /**
+     * Cache public leaf data pulled from the on-chain Merkle tree.
+     */
+    async putLeaf(leaf: LeafRecord) {
+      ensureChainId(leaf.chainId);
+      ensurePositiveInt("leaf index", leaf.index);
+      await putJson(storage, keys.leaf(leaf.chainId, leaf.index), leaf);
+    },
+
+    /**
+     * Load a leaf commitment by tree index.
+     */
+    async getLeaf(chainId: number, index: number) {
+      ensureChainId(chainId);
+      ensurePositiveInt("leaf index", index);
+      return getJson<LeafRecord>(storage, keys.leaf(chainId, index));
+    },
+
+    /**
+     * Remove all cached leaves for a chain.
+     */
+    async clearLeaves(chainId: number) {
+      ensureChainId(chainId);
+      const prefix = `leaves:${chainId}:`;
+      const entries = await storage.iter({ prefix });
+      if (entries.length === 0) return;
+      const deletions = entries.map(({ key }) => ({ del: key }));
+      await storage.batch(deletions);
+    },
+  };
+}