@unlink-xyz/core 0.1.3 → 0.1.4

package/state/store/job-store.ts

@@ -1,162 +0,0 @@
-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

@@ -1,64 +0,0 @@
-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

@@ -1,39 +0,0 @@
-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);
-    },
-  };
-}

package/state/store/note-store.ts

@@ -1,177 +0,0 @@
-import { CoreError } from "../../errors.js";
-import { keys } from "../../keys.js";
-import type { BatchOp, Storage } from "../../types.js";
-import {
-  decodeJson,
-  encodeJson,
-  getJson,
-  type JsonRecord,
-} from "../../utils/json-codec.js";
-import {
-  ensureBigIntString,
-  ensureChainId,
-  ensureMpk,
-  ensurePositiveInt,
-} from "../../utils/validators.js";
-import type { NoteInsert, NoteRecord } from "../store/records.js";
-
-export const emptyBytes = () => new Uint8Array(0);
-
-export function createNoteStore(storage: Storage) {
-  const persistNote = async (record: NoteRecord) => {
-    ensureChainId(record.chainId);
-    ensurePositiveInt("note index", record.index);
-    ensureMpk(record.mpk);
-    ensureBigIntString("note value", record.value);
-    if (record.spentAt !== undefined) {
-      ensurePositiveInt("note spentAt", record.spentAt);
-    }
-
-    const noteKey = keys.note(record.chainId, record.index);
-    const previous = await getJson<NoteRecord>(storage, noteKey);
-
-    const ops: BatchOp[] = [
-      { put: [noteKey, encodeJson(record as JsonRecord)] },
-    ];
-
-    if (previous && previous.spentAt === undefined) {
-      ops.push({
-        del: keys.unspent(previous.chainId, previous.mpk, previous.index),
-      });
-    }
-
-    if (record.spentAt === undefined) {
-      // idx:notes:unspent functions as a set, so we only persist the sentinel bytes.
-      ops.push({
-        put: [
-          keys.unspent(record.chainId, record.mpk, record.index),
-          emptyBytes(),
-        ],
-      });
-    } else {
-      ops.push({
-        del: keys.unspent(record.chainId, record.mpk, record.index),
-      });
-    }
-
-    await storage.batch(ops);
-  };
-
-  const store = {
-    /**
-     * Upsert a note record and maintain the unspent-note index for fast balance queries.
-     * If the note already exists and is marked as spent, preserve the spentAt field.
-     */
-    async putNote(note: NoteInsert) {
-      const noteKey = keys.note(note.chainId, note.index);
-      const existing = await getJson<NoteRecord>(storage, noteKey);
-      if (existing?.spentAt !== undefined) {
-        // Preserve spentAt if note was already marked as spent
-        await persistNote({ ...note, spentAt: existing.spentAt });
-      } else {
-        await persistNote({ ...note });
-      }
-    },
-
-    /**
-     * Fetch a note by (chainId, index) if it exists in local storage.
-     */
-    async getNote(chainId: number, index: number) {
-      ensureChainId(chainId);
-      ensurePositiveInt("note index", index);
-      return getJson<NoteRecord>(storage, keys.note(chainId, index));
-    },
-
-    /**
-     * List notes matching optional filters (by chainId, mpk) and spent state.
-     */
-    async listNotes(
-      options: {
-        chainId?: number;
-        mpk?: string;
-        token?: string;
-        includeSpent?: boolean;
-      } = {},
-    ) {
-      const { chainId, mpk, token, includeSpent = true } = options;
-      if (chainId !== undefined) {
-        ensureChainId(chainId);
-      }
-      if (mpk !== undefined) {
-        ensureMpk(mpk);
-      }
-
-      const prefix = chainId !== undefined ? `notes:${chainId}:` : "notes:";
-      const entries = await storage.iter({ prefix });
-      const filtered = entries
-        .map(({ value }) => decodeJson<NoteRecord>(value))
-        .filter(
-          (note) =>
-            (chainId === undefined || note.chainId === chainId) &&
-            (mpk === undefined || note.mpk === mpk) &&
-            (token === undefined || note.token === token) &&
-            (includeSpent || note.spentAt === undefined),
-        );
-      filtered.sort((a, b) => a.index - b.index);
-      return filtered;
-    },
-
-    /**
-     * Mark a cached note as spent by setting its timestamp and re-indexing metadata.
-     */
-    async markNoteSpent(chainId: number, index: number, spentAt = Date.now()) {
-      ensureChainId(chainId);
-      ensurePositiveInt("note index", index);
-      ensurePositiveInt("note spentAt", spentAt);
-      const existing = await store.getNote(chainId, index);
-      if (!existing) {
-        throw new CoreError("note not found");
-      }
-      if (existing.spentAt === spentAt) {
-        return existing;
-      }
-      const updated: NoteRecord = { ...existing, spentAt };
-      await persistNote(updated);
-      return updated;
-    },
-
-    /**
-     * Drop the spent marker from a cached note, returning it to the unspent index.
-     */
-    async markNoteUnspent(chainId: number, index: number) {
-      ensureChainId(chainId);
-      ensurePositiveInt("note index", index);
-      const existing = await store.getNote(chainId, index);
-      if (!existing) {
-        throw new CoreError("note not found");
-      }
-      if (existing.spentAt === undefined) {
-        return existing;
-      }
-      const updated: NoteRecord = { ...existing };
-      delete updated.spentAt;
-      await persistNote(updated);
-      return updated;
-    },
-
-    /**
-     * Aggregate unspent note balances per token for a given master public key.
-     */
-    async getZkBalances(mpk: string, options: { chainId?: number } = {}) {
-      ensureMpk(mpk);
-      const notes = await store.listNotes({
-        chainId: options.chainId,
-        mpk,
-        includeSpent: false,
-      });
-      const totals: Record<string, bigint> = {};
-      for (const note of notes) {
-        const amount = BigInt(note.value);
-        totals[note.token] = (totals[note.token] ?? 0n) + amount;
-      }
-      return totals;
-    },
-  };
-
-  return store;
-}

package/state/store/nullifier-store.ts

@@ -1,39 +0,0 @@
-import { keys } from "../../keys.js";
-import type { Storage } from "../../types.js";
-import { getJson, putJson } from "../../utils/json-codec.js";
-import { ensureChainId } from "../../utils/validators.js";
-import type { NullifierRecord } from "../store/records.js";
-
-export function createNullifierStore(storage: Storage) {
-  return {
-    /**
-     * Record a nullifier observation so later syncs can de-duplicate work.
-     */
-    async putNullifier(nullifier: NullifierRecord) {
-      ensureChainId(nullifier.chainId);
-      await putJson(
-        storage,
-        keys.nullifier(nullifier.chainId, nullifier.nullifier),
-        nullifier,
-      );
-    },
-
-    /**
-     * Lookup a previously observed nullifier by value.
-     */
-    async getNullifier(chainId: number, value: string) {
-      ensureChainId(chainId);
-      return getJson<NullifierRecord>(storage, keys.nullifier(chainId, value));
-    },
-
-    /**
-     * Count all nullifiers stored locally for a given chain.
-     */
-    async countNullifiers(chainId: number): Promise<number> {
-      ensureChainId(chainId);
-      const prefix = `nullifiers:${chainId}:`;
-      const entries = await storage.iter({ prefix });
-      return entries.length;
-    },
-  };
-}

package/state/store/records.ts

@@ -1,61 +0,0 @@
-/**
- * Locally cached metadata for a deposit note we consider owned.
- */
-export type NoteRecord = {
-  chainId: number;
-  /** Leaf index within the on-chain tree (zero-based, monotonic). */
-  index: number;
-  /** Canonical asset identifier, typically the ERC-20 address lowercased. */
-  token: string;
-  /** Amount expressed as an unsigned BigInt serialized to a base-10 string. */
-  value: string;
-  /** Commitment stored on-chain (Poseidon(note)). */
-  commitment: string;
-  /** Note public key derived from the master public key. */
-  npk: string;
-  /**
-   * Master public key for the account (Poseidon(spendingPk.public, nullifyingKey)).
-   * Acts as the stable account identifier when grouping notes locally.
-   */
-  mpk: string;
-  /** Randomizer used when committing the note. */
-  random: string;
-  /** Nullifier that will be revealed when the note is spent. */
-  nullifier: string;
-  /** Optional timestamp when the note was marked as spent. */
-  spentAt?: number;
-};
-
-// prettier-ignore
-export type NoteInsert = Omit<NoteRecord, 'spentAt'>;
-
-/**
- * Details about a nullifier observed on-chain, whether or not we own the note.
- */
-export type NullifierRecord = {
-  chainId: number;
-  /** Nullifier value (expected to match NoteRecord.nullifier). */
-  nullifier: string;
-  /** Leaf index of the corresponding note when known. */
-  noteIndex?: number;
-};
-
-/**
- * Public information about a leaf commitment inserted into the pool's tree.
- */
-export type LeafRecord = {
-  chainId: number;
-  /** Leaf index inside the tree (zero-based). */
-  index: number;
-  /** Commitment value stored in the tree. */
-  commitment: string;
-};
-
-/**
- * Historical merkle root snapshot used for proof construction.
- */
-export type RootRecord = {
-  chainId: number;
-  /** Merkle root value committed on-chain. */
-  root: string;
-};

package/state/store/root-store.ts

@@ -1,34 +0,0 @@
-import { CoreError } from "../../errors.js";
-import { keys, validateKey } from "../../keys.js";
-import type { Storage } from "../../types.js";
-import { getJson, putJson } from "../../utils/json-codec.js";
-import { ensureChainId } from "../../utils/validators.js";
-import type { RootRecord } from "../store/records.js";
-
-export function createRootStore(storage: Storage) {
-  return {
-    /**
-     * Persist a historical root snapshot for proof generation.
-     */
-    async putRoot(root: RootRecord) {
-      ensureChainId(root.chainId);
-      if (typeof root.root !== "string" || root.root.length === 0) {
-        throw new CoreError("root value must be a non-empty string");
-      }
-      const key = keys.root(root.chainId, root.root);
-      validateKey(key);
-      await putJson(storage, key, root);
-    },
-
-    /**
-     * Retrieve a root snapshot by Merkle root value.
-     */
-    async getRoot(chainId: number, value: string) {
-      ensureChainId(chainId);
-      if (typeof value !== "string" || value.length === 0) {
-        throw new CoreError("root value must be a non-empty string");
-      }
-      return getJson<RootRecord>(storage, keys.root(chainId, value));
-    },
-  };
-}

package/state/store/store.ts

@@ -1,25 +0,0 @@
-import type { Storage } from "../../types.js";
-import { createCiphertextStore } from "./ciphertext-store.js";
-import { createJobStore } from "./job-store.js";
-import { createLeafStore } from "./leaf-store.js";
-import { createNoteStore } from "./note-store.js";
-import { createNullifierStore } from "./nullifier-store.js";
-import { createRootStore } from "./root-store.js";
-
-export function createStateStore(storage: Storage) {
-  const notes = createNoteStore(storage);
-  const nullifiers = createNullifierStore(storage);
-  const leaves = createLeafStore(storage);
-  const roots = createRootStore(storage);
-  const ciphertexts = createCiphertextStore(storage);
-  const jobs = createJobStore(storage);
-
-  return {
-    ...notes,
-    ...nullifiers,
-    ...leaves,
-    ...roots,
-    ...ciphertexts,
-    ...jobs,
-  };
-}