@unlink-xyz/core 0.1.0

package/dist/state/records.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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;
+};
+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;
+};
+//# sourceMappingURL=records.d.ts.map

package/dist/state/records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.d.ts","sourceRoot":"","sources":["../../state/records.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAGF,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;AAErD;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;CACd,CAAC"}

package/dist/state/records.js

@@ -0,0 +1 @@
+export {};

package/dist/state/root-store.d.ts

@@ -0,0 +1,13 @@
+import type { Storage } from "../types.js";
+import type { RootRecord } from "./records.js";
+export declare function createRootStore(storage: Storage): {
+    /**
+     * Persist a historical root snapshot for proof generation.
+     */
+    putRoot(root: RootRecord): Promise<void>;
+    /**
+     * Retrieve a root snapshot by Merkle root value.
+     */
+    getRoot(chainId: number, value: string): Promise<RootRecord | null>;
+};
+//# sourceMappingURL=root-store.d.ts.map

package/dist/state/root-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-store.d.ts","sourceRoot":"","sources":["../../state/root-store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO;IAE5C;;OAEG;kBACiB,UAAU;IAU9B;;OAEG;qBACoB,MAAM,SAAS,MAAM;EAQ/C"}

package/dist/state/root-store.js

@@ -0,0 +1,30 @@
+import { CoreError } from "../errors.js";
+import { keys, validateKey } from "../keys.js";
+import { getJson, putJson } from "../utils/json-codec.js";
+import { ensureChainId } from "../utils/validators.js";
+export function createRootStore(storage) {
+    return {
+        /**
+         * Persist a historical root snapshot for proof generation.
+         */
+        async putRoot(root) {
+            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, value) {
+            ensureChainId(chainId);
+            if (typeof value !== "string" || value.length === 0) {
+                throw new CoreError("root value must be a non-empty string");
+            }
+            return getJson(storage, keys.root(chainId, value));
+        },
+    };
+}

package/dist/state/store/ciphertext-store.d.ts

@@ -0,0 +1,12 @@
+import type { Storage } from "../../types.js";
+export declare function createCiphertextStore(storage: Storage): {
+    /**
+     * Store encrypted note payloads alongside their on-chain commitments.
+     */
+    putCiphertext(chainId: number, index: number, payload: Uint8Array): Promise<void>;
+    /**
+     * Retrieve encrypted note payloads; returns null when the ciphertext is missing.
+     */
+    getCiphertext(chainId: number, index: number): Promise<Uint8Array<ArrayBuffer> | null>;
+};
+//# sourceMappingURL=ciphertext-store.d.ts.map

package/dist/state/store/ciphertext-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ciphertext-store.d.ts","sourceRoot":"","sources":["../../../state/store/ciphertext-store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAG9C,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO;IAElD;;OAEG;2BAC0B,MAAM,SAAS,MAAM,WAAW,UAAU;IAQvE;;OAEG;2BAC0B,MAAM,SAAS,MAAM;EAOrD"}

package/dist/state/store/ciphertext-store.js

@@ -0,0 +1,25 @@
+import { keys, validateKey } from "../../keys.js";
+import { ensureChainId, ensurePositiveInt } from "../../utils/validators.js";
+export function createCiphertextStore(storage) {
+    return {
+        /**
+         * Store encrypted note payloads alongside their on-chain commitments.
+         */
+        async putCiphertext(chainId, index, payload) {
+            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, index) {
+            ensureChainId(chainId);
+            ensurePositiveInt("ciphertext index", index);
+            const data = await storage.get(keys.ciphertext(chainId, index));
+            return data ? new Uint8Array(data) : null;
+        },
+    };
+}

package/dist/state/store/index.d.ts

@@ -0,0 +1,10 @@
+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";
+//# sourceMappingURL=index.d.ts.map

package/dist/state/store/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../state/store/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EACL,sBAAsB,EACtB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,UAAU,EACV,UAAU,EACV,UAAU,EACV,eAAe,EACf,UAAU,GACX,MAAM,cAAc,CAAC"}

package/dist/state/store/index.js

@@ -0,0 +1,8 @@
+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, } from "./jobs.js";

package/dist/state/store/job-store.d.ts

@@ -0,0 +1,12 @@
+import type { Storage } from "../../types.js";
+import type { JobStatus, PendingJobKind, PendingJobRecord } from "../store/jobs.js";
+export declare function createJobStore(storage: Storage): {
+    putPendingJob(job: PendingJobRecord): Promise<void>;
+    getPendingJob(relayId: string): Promise<PendingJobRecord | null>;
+    listPendingJobs(filter?: {
+        kind?: PendingJobKind;
+        statuses?: JobStatus[];
+    }): Promise<PendingJobRecord[]>;
+    deletePendingJob(relayId: string): Promise<void>;
+};
+//# sourceMappingURL=job-store.d.ts.map

package/dist/state/store/job-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-store.d.ts","sourceRoot":"","sources":["../../../state/store/job-store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAO9C,OAAO,KAAK,EACV,SAAS,EAET,cAAc,EACd,gBAAgB,EAGjB,MAAM,kBAAkB,CAAC;AA4G1B,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO;uBAElB,gBAAgB;2BASZ,MAAM;6BAKzB;QACN,IAAI,CAAC,EAAE,cAAc,CAAC;QACtB,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC;KACxB;8BAe6B,MAAM;EAIzC"}

package/dist/state/store/job-store.js

@@ -0,0 +1,118 @@
+import { keys } from "../../keys.js";
+import { decodeJson, encodeJson, getJson } from "../../utils/json-codec.js";
+import { ensureAddress, ensureChainId, ensurePositiveInt, } from "../../utils/validators.js";
+import { DEFAULT_JOB_TIMEOUT_MS } from "../store/jobs.js";
+const VALID_STATUSES = [
+    "pending",
+    "submitted",
+    "broadcasting",
+    "succeeded",
+    "failed",
+    "dead",
+];
+function assertStatus(status) {
+    if (!VALID_STATUSES.includes(status)) {
+        throw new Error(`invalid job status: ${status}`);
+    }
+}
+function assertKind(kind) {
+    if (kind !== "deposit" && kind !== "transact") {
+        throw new Error(`invalid job kind: ${kind}`);
+    }
+}
+function normalizeTimestamps(job) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    return keys.job(relayId);
+}
+export function createJobStore(storage) {
+    return {
+        async putPendingJob(job) {
+            const normalized = normalizeTimestamps(job);
+            validateJob(normalized);
+            await storage.put(buildJobKey(normalized.relayId), encodeJson(normalized));
+        },
+        async getPendingJob(relayId) {
+            return getJson(storage, buildJobKey(relayId));
+        },
+        async listPendingJobs(filter = {}) {
+            const entries = await storage.iter({ prefix: "jobs:" });
+            const statuses = filter.statuses ?? VALID_STATUSES;
+            const filtered = entries
+                .map(({ value }) => decodeJson(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) {
+            await storage.delete(buildJobKey(relayId));
+        },
+    };
+}

package/dist/state/store/jobs.d.ts

@@ -0,0 +1,50 @@
+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;
+    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 declare const DEFAULT_JOB_TIMEOUT_MS: number;
+//# sourceMappingURL=jobs.d.ts.map

package/dist/state/store/jobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.d.ts","sourceRoot":"","sources":["../../../state/store/jobs.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,WAAW,GACX,cAAc,GACd,WAAW,GACX,QAAQ,GACR,MAAM,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,CAAC;AAEpD,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAAG;IAC/C,IAAI,EAAE,SAAS,CAAC;IAChB,mBAAmB,EAAE;QACnB,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAElB,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,YAAY,EAAE,MAAM,EAAE,EAAE,CAAC;QACzB,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,cAAc,GAAG;IAChD,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,sBAAsB,EAAE,CAAC;IACnC,gBAAgB,EAAE,qBAAqB,EAAE,CAAC;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAEtE,eAAO,MAAM,sBAAsB,QAAgB,CAAC"}

package/dist/state/store/jobs.js

@@ -0,0 +1 @@
+export const DEFAULT_JOB_TIMEOUT_MS = 5 * 60 * 1000;

package/dist/state/store/leaf-store.d.ts

@@ -0,0 +1,17 @@
+import type { Storage } from "../../types.js";
+import type { LeafRecord } from "../store/records.js";
+export declare function createLeafStore(storage: Storage): {
+    /**
+     * Cache public leaf data pulled from the on-chain Merkle tree.
+     */
+    putLeaf(leaf: LeafRecord): Promise<void>;
+    /**
+     * Load a leaf commitment by tree index.
+     */
+    getLeaf(chainId: number, index: number): Promise<LeafRecord | null>;
+    /**
+     * Remove all cached leaves for a chain.
+     */
+    clearLeaves(chainId: number): Promise<void>;
+};
+//# sourceMappingURL=leaf-store.d.ts.map

package/dist/state/store/leaf-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leaf-store.d.ts","sourceRoot":"","sources":["../../../state/store/leaf-store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAG9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO;IAE5C;;OAEG;kBACiB,UAAU;IAM9B;;OAEG;qBACoB,MAAM,SAAS,MAAM;IAM5C;;OAEG;yBACwB,MAAM;EASpC"}

package/dist/state/store/leaf-store.js

@@ -0,0 +1,35 @@
+import { keys } from "../../keys.js";
+import { getJson, putJson } from "../../utils/json-codec.js";
+import { ensureChainId, ensurePositiveInt } from "../../utils/validators.js";
+export function createLeafStore(storage) {
+    return {
+        /**
+         * Cache public leaf data pulled from the on-chain Merkle tree.
+         */
+        async putLeaf(leaf) {
+            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, index) {
+            ensureChainId(chainId);
+            ensurePositiveInt("leaf index", index);
+            return getJson(storage, keys.leaf(chainId, index));
+        },
+        /**
+         * Remove all cached leaves for a chain.
+         */
+        async clearLeaves(chainId) {
+            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/dist/state/store/note-store.d.ts

@@ -0,0 +1,38 @@
+import type { Storage } from "../../types.js";
+import type { NoteInsert, NoteRecord } from "../store/records.js";
+export declare const emptyBytes: () => Uint8Array<ArrayBuffer>;
+export declare function createNoteStore(storage: Storage): {
+    /**
+     * 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.
+     */
+    putNote(note: NoteInsert): Promise<void>;
+    /**
+     * Fetch a note by (chainId, index) if it exists in local storage.
+     */
+    getNote(chainId: number, index: number): Promise<NoteRecord | null>;
+    /**
+     * List notes matching optional filters (by chainId, mpk) and spent state.
+     */
+    listNotes(options?: {
+        chainId?: number;
+        mpk?: string;
+        token?: string;
+        includeSpent?: boolean;
+    }): Promise<NoteRecord[]>;
+    /**
+     * Mark a cached note as spent by setting its timestamp and re-indexing metadata.
+     */
+    markNoteSpent(chainId: number, index: number, spentAt?: number): Promise<NoteRecord>;
+    /**
+     * Drop the spent marker from a cached note, returning it to the unspent index.
+     */
+    markNoteUnspent(chainId: number, index: number): Promise<NoteRecord>;
+    /**
+     * Aggregate unspent note balances per token for a given master public key.
+     */
+    getZkBalances(mpk: string, options?: {
+        chainId?: number;
+    }): Promise<Record<string, bigint>>;
+};
+//# sourceMappingURL=note-store.d.ts.map

package/dist/state/store/note-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"note-store.d.ts","sourceRoot":"","sources":["../../../state/store/note-store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAW,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAavD,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAElE,eAAO,MAAM,UAAU,+BAA0B,CAAC;AAElD,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO;IAyC5C;;;OAGG;kBACiB,UAAU;IAW9B;;OAEG;qBACoB,MAAM,SAAS,MAAM;IAM5C;;OAEG;wBAEQ;QACP,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB;IAyBH;;OAEG;2BAC0B,MAAM,SAAS,MAAM;IAgBlD;;OAEG;6BAC4B,MAAM,SAAS,MAAM;IAgBpD;;OAEG;uBACsB,MAAM,YAAW;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE;EAiBjE"}

package/dist/state/store/note-store.js

@@ -0,0 +1,142 @@
+import { CoreError } from "../../errors.js";
+import { keys } from "../../keys.js";
+import { decodeJson, encodeJson, getJson, } from "../../utils/json-codec.js";
+import { ensureBigIntString, ensureChainId, ensureMpk, ensurePositiveInt, } from "../../utils/validators.js";
+export const emptyBytes = () => new Uint8Array(0);
+export function createNoteStore(storage) {
+    const persistNote = async (record) => {
+        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(storage, noteKey);
+        const ops = [
+            { put: [noteKey, encodeJson(record)] },
+        ];
+        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) {
+            const noteKey = keys.note(note.chainId, note.index);
+            const existing = await getJson(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, index) {
+            ensureChainId(chainId);
+            ensurePositiveInt("note index", index);
+            return getJson(storage, keys.note(chainId, index));
+        },
+        /**
+         * List notes matching optional filters (by chainId, mpk) and spent state.
+         */
+        async listNotes(options = {}) {
+            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(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, index, 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 = { ...existing, spentAt };
+            await persistNote(updated);
+            return updated;
+        },
+        /**
+         * Drop the spent marker from a cached note, returning it to the unspent index.
+         */
+        async markNoteUnspent(chainId, index) {
+            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 = { ...existing };
+            delete updated.spentAt;
+            await persistNote(updated);
+            return updated;
+        },
+        /**
+         * Aggregate unspent note balances per token for a given master public key.
+         */
+        async getZkBalances(mpk, options = {}) {
+            ensureMpk(mpk);
+            const notes = await store.listNotes({
+                chainId: options.chainId,
+                mpk,
+                includeSpent: false,
+            });
+            const totals = {};
+            for (const note of notes) {
+                const amount = BigInt(note.value);
+                totals[note.token] = (totals[note.token] ?? 0n) + amount;
+            }
+            return totals;
+        },
+    };
+    return store;
+}

package/dist/state/store/nullifier-store.d.ts

@@ -0,0 +1,17 @@
+import type { Storage } from "../../types.js";
+import type { NullifierRecord } from "../store/records.js";
+export declare function createNullifierStore(storage: Storage): {
+    /**
+     * Record a nullifier observation so later syncs can de-duplicate work.
+     */
+    putNullifier(nullifier: NullifierRecord): Promise<void>;
+    /**
+     * Lookup a previously observed nullifier by value.
+     */
+    getNullifier(chainId: number, value: string): Promise<NullifierRecord | null>;
+    /**
+     * Count all nullifiers stored locally for a given chain.
+     */
+    countNullifiers(chainId: number): Promise<number>;
+};
+//# sourceMappingURL=nullifier-store.d.ts.map

package/dist/state/store/nullifier-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nullifier-store.d.ts","sourceRoot":"","sources":["../../../state/store/nullifier-store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAG9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO;IAEjD;;OAEG;4BAC2B,eAAe;IAS7C;;OAEG;0BACyB,MAAM,SAAS,MAAM;IAKjD;;OAEG;6BAC4B,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;EAO1D"}