@unlink-xyz/core 0.1.2 → 0.1.3-canary.0877bfe

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

@@ -0,0 +1,24 @@
+import type { HistoryEntry } from "../../history/types.js";
+import type { Storage } from "../../types.js";
+type HistoryEntryRecord = HistoryEntry;
+export declare function createHistoryStore(storage: Storage): {
+    putHistoryEntry(entry: HistoryEntryRecord): Promise<void>;
+    hasHistorySnapshot(options: {
+        chainId: number;
+        mpk: string;
+    }): Promise<boolean>;
+    listHistoryEntries(options: {
+        chainId: number;
+        mpk: string;
+    }): Promise<HistoryEntry[]>;
+    clearHistoryEntries(options: {
+        chainId: number;
+        mpk: string;
+    }): Promise<void>;
+    commitHistorySnapshot(options: {
+        chainId: number;
+        mpk: string;
+    }): Promise<void>;
+};
+export {};
+//# sourceMappingURL=history-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"history-store.d.ts","sourceRoot":"","sources":["../../../state/store/history-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAQ9C,KAAK,kBAAkB,GAAG,YAAY,CAAC;AAGvC,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO;2BASlB,kBAAkB;gCAOb;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;gCAShC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;iCAiB/B;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;mCAS9B;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;EAMxE"}

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

@@ -0,0 +1,53 @@
+import { keys } from "../../keys.js";
+import { decodeJson, encodeJson, } from "../../utils/json-codec.js";
+import { ensureChainId, ensureMpk } from "../../utils/validators.js";
+export function createHistoryStore(storage) {
+    async function putMeta(options) {
+        await storage.put(keys.historyMeta(options.chainId, options.mpk), encodeJson({ v: 1, updatedAtMs: Date.now() }));
+    }
+    return {
+        async putHistoryEntry(entry) {
+            ensureChainId(entry.chainId);
+            ensureMpk(entry.mpk);
+            const key = keys.historyEntry(entry.id);
+            await storage.put(key, encodeJson(entry));
+        },
+        async hasHistorySnapshot(options) {
+            ensureChainId(options.chainId);
+            ensureMpk(options.mpk);
+            const meta = await storage.get(keys.historyMeta(options.chainId, options.mpk));
+            return meta !== null;
+        },
+        async listHistoryEntries(options) {
+            ensureChainId(options.chainId);
+            ensureMpk(options.mpk);
+            const prefix = keys.historyPrefix(options.chainId, options.mpk);
+            const entries = await storage.iter({ prefix });
+            const decoded = entries
+                .filter(({ key }) => !key.endsWith(":__meta__"))
+                .map(({ value }) => decodeJson(value));
+            decoded.sort((a, b) => {
+                const at = a.timestamp ?? 0;
+                const bt = b.timestamp ?? 0;
+                if (at !== bt)
+                    return bt - at;
+                return b.txHash.localeCompare(a.txHash);
+            });
+            return decoded;
+        },
+        async clearHistoryEntries(options) {
+            ensureChainId(options.chainId);
+            ensureMpk(options.mpk);
+            const prefix = keys.historyPrefix(options.chainId, options.mpk);
+            const existing = await storage.iter({ prefix });
+            if (existing.length === 0)
+                return;
+            await storage.batch(existing.map(({ key }) => ({ del: key })));
+        },
+        async commitHistorySnapshot(options) {
+            ensureChainId(options.chainId);
+            ensureMpk(options.mpk);
+            await putMeta(options);
+        },
+    };
+}

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

@@ -1,10 +1,11 @@
-export { createStateStore } from "./store.js";
+export { createStateStore, type StateStore } 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 { createHistoryStore } from "./history-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 { DEFAULT_JOB_TIMEOUT_MS, type JobStatus, type JobKind, type JobRecord, type DepositRecord, type TransferRecord, type WithdrawRecord, type PoolTransactionRecord, type TransactContext, type TransactOutput, } 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

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../state/store/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC/D,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,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EACL,sBAAsB,EACtB,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,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

@@ -4,5 +4,6 @@ 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 { createHistoryStore } from "./history-store.js";
 export { createJobStore } from "./job-store.js";
 export { DEFAULT_JOB_TIMEOUT_MS, } from "./jobs.js";

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

@@ -1,12 +1,12 @@
 import type { Storage } from "../../types.js";
-import type { JobStatus, PendingJobKind, PendingJobRecord } from "../store/jobs.js";
+import type { JobKind, JobRecord, JobStatus } 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;
+    putJob(job: JobRecord): Promise<void>;
+    getJob(relayId: string): Promise<JobRecord | null>;
+    listJobs(filter?: {
+        kind?: JobKind;
         statuses?: JobStatus[];
-    }): Promise<PendingJobRecord[]>;
-    deletePendingJob(relayId: string): Promise<void>;
+    }): Promise<JobRecord[]>;
+    deleteJob(relayId: string): Promise<void>;
 };
 //# sourceMappingURL=job-store.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"job-store.d.ts","sourceRoot":"","sources":["../../../state/store/job-store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAQ9C,OAAO,KAAK,EAEV,OAAO,EACP,SAAS,EACT,SAAS,EAEV,MAAM,kBAAkB,CAAC;AAwI1B,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO;gBAEzB,SAAS;oBASL,MAAM;sBAKlB;QACN,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC;KACxB;uBAesB,MAAM;EAIlC"}

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

@@ -1,6 +1,7 @@
+import { CoreError } from "../../errors.js";
 import { keys } from "../../keys.js";
 import { decodeJson, encodeJson, getJson } from "../../utils/json-codec.js";
-import { ensureAddress, ensureChainId, ensurePositiveInt, } from "../../utils/validators.js";
+import { ensureAddress, ensureChainId, ensureMpk, ensurePositiveInt, } from "../../utils/validators.js";
 import { DEFAULT_JOB_TIMEOUT_MS } from "../store/jobs.js";
 const VALID_STATUSES = [
     "pending",
@@ -10,14 +11,15 @@ const VALID_STATUSES = [
     "failed",
     "dead",
 ];
+const VALID_KINDS = ["deposit", "transfer", "withdraw"];
 function assertStatus(status) {
     if (!VALID_STATUSES.includes(status)) {
-        throw new Error(`invalid job status: ${status}`);
+        throw new CoreError(`invalid job status: ${status}`);
     }
 }
 function assertKind(kind) {
-    if (kind !== "deposit" && kind !== "transact") {
-        throw new Error(`invalid job kind: ${kind}`);
+    if (!VALID_KINDS.includes(kind)) {
+        throw new CoreError(`invalid job kind: ${kind}`);
     }
 }
 function normalizeTimestamps(job) {
@@ -33,47 +35,71 @@ function normalizeTimestamps(job) {
         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) {
+function validatePoolTransactionRecord(job) {
     ensureAddress("pool address", job.poolAddress);
     if (!job.calldata) {
-        throw new Error("calldata is required for transact job");
+        throw new CoreError("calldata is required for pool transaction record");
     }
-    job.contexts.forEach(validateTransactContext);
-    job.predictedOutputs.forEach((output) => {
-        if (!output.hex) {
-            throw new Error("predicted output hex is required");
+    if (!Array.isArray(job.transactions) || !job.transactions.length) {
+        throw new CoreError("transactions array is required");
+    }
+    for (let i = 0; i < job.transactions.length; i++) {
+        const tx = job.transactions[i];
+        ensureAddress(`transaction token at ${i}`, tx.token);
+        if (!Array.isArray(tx.nullifiers) || !tx.nullifiers.length) {
+            throw new CoreError(`nullifiers array is required at index ${i}`);
+        }
+        // predictedCommitments can be empty for withdrawals with no change
+        if (!Array.isArray(tx.predictedCommitments)) {
+            throw new CoreError(`predicted commitments array is required at index ${i}`);
+        }
+        // Only require non-empty commitments if there's no withdrawal
+        if (!tx.predictedCommitments.length && !tx.withdrawal) {
+            throw new CoreError(`predicted commitments are required at index ${i}`);
         }
-        ensurePositiveInt("predicted output index", output.index);
-    });
+        for (let j = 0; j < tx.predictedCommitments.length; j++) {
+            const c = tx.predictedCommitments[j];
+            if (!c.hex) {
+                throw new CoreError(`predicted commitment hex is required at index ${i}.${j}`);
+            }
+        }
+        if (tx.withdrawal) {
+            if (!tx.withdrawal.amount) {
+                throw new CoreError(`withdrawal amount is required at index ${i}`);
+            }
+            if (!tx.withdrawal.recipient) {
+                throw new CoreError(`withdrawal recipient is required at index ${i}`);
+            }
+        }
+    }
 }
-function validateDepositJob(job) {
-    if (!job.predictedCommitment?.hex) {
-        throw new Error("predicted commitment hex is required");
+function validateDepositRecord(job) {
+    if (!Array.isArray(job.predictedCommitments) ||
+        !job.predictedCommitments.length) {
+        throw new CoreError("predicted commitments array is required for deposit");
     }
-    if (job.predictedCommitment.index !== undefined) {
-        ensurePositiveInt("predicted commitment index", job.predictedCommitment.index);
+    for (let i = 0; i < job.predictedCommitments.length; i++) {
+        const c = job.predictedCommitments[i];
+        if (!c.hex) {
+            throw new CoreError(`predicted commitment hex is required at index ${i}`);
+        }
+        ensureAddress(`predicted commitment token at ${i}`, c.token);
+        if (!c.amount) {
+            throw new CoreError(`predicted commitment amount is required at index ${i}`);
+        }
+        if (c.index !== undefined) {
+            ensurePositiveInt(`predicted commitment index at ${i}`, c.index);
+        }
     }
 }
 function validateJob(job) {
     if (!job.relayId) {
-        throw new Error("relayId is required");
+        throw new CoreError("relayId is required");
     }
     ensureChainId(job.chainId);
+    if (job.mpk !== undefined) {
+        ensureMpk(job.mpk);
+    }
     assertStatus(job.status);
     assertKind(job.kind);
     ensurePositiveInt("job createdAt", job.createdAt);
@@ -82,10 +108,10 @@ function validateJob(job) {
         ensurePositiveInt("job lastCheckedAt", job.lastCheckedAt);
     }
     if (job.kind === "deposit") {
-        validateDepositJob(job);
+        validateDepositRecord(job);
     }
     else {
-        validateTransactJob(job);
+        validatePoolTransactionRecord(job);
     }
 }
 function buildJobKey(relayId) {
@@ -93,15 +119,15 @@ function buildJobKey(relayId) {
 }
 export function createJobStore(storage) {
     return {
-        async putPendingJob(job) {
+        async putJob(job) {
             const normalized = normalizeTimestamps(job);
             validateJob(normalized);
             await storage.put(buildJobKey(normalized.relayId), encodeJson(normalized));
         },
-        async getPendingJob(relayId) {
+        async getJob(relayId) {
             return getJson(storage, buildJobKey(relayId));
         },
-        async listPendingJobs(filter = {}) {
+        async listJobs(filter = {}) {
             const entries = await storage.iter({ prefix: "jobs:" });
             const statuses = filter.statuses ?? VALID_STATUSES;
             const filtered = entries
@@ -111,7 +137,7 @@ export function createJobStore(storage) {
             filtered.sort((a, b) => a.createdAt - b.createdAt);
             return filtered;
         },
-        async deletePendingJob(relayId) {
+        async deleteJob(relayId) {
             await storage.delete(buildJobKey(relayId));
         },
     };

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

@@ -1,26 +1,48 @@
 export type JobStatus = "pending" | "submitted" | "broadcasting" | "succeeded" | "failed" | "dead";
-export type PendingJobKind = "deposit" | "transact";
-export type PendingJobBase = {
+export type JobKind = "deposit" | "transfer" | "withdraw";
+export type JobRecordBase = {
     relayId: string;
-    kind: PendingJobKind;
+    kind: JobKind;
     chainId: number;
+    /** Master public key (hex string) for correlating jobs with history/account views. */
+    mpk?: string;
     status: JobStatus;
-    broadcasterRelayId?: string | null;
     txHash?: string | null;
     createdAt: number;
     lastCheckedAt?: number;
     timeoutMs: number;
     error?: string | null;
+    /**
+     * Optional history preview so UIs can show pending/failed history rows before notes are indexed.
+     * Amount deltas follow HistoryAmount semantics (positive receive, negative send).
+     */
+    historyPreview?: {
+        kind: "Deposit" | "Receive" | "Send" | "SelfSend" | "Withdraw";
+        amounts: Array<{
+            token: string;
+            delta: string;
+        }>;
+    };
+};
+/**
+ * Predicted commitment info for deposits.
+ */
+export type PredictedCommitment = {
+    hex: string;
+    token: string;
+    amount: string;
+    index?: number;
+    root?: string;
 };
-export type PendingDepositJob = PendingJobBase & {
+/**
+ * Record for tracking deposits
+ */
+export type DepositRecord = JobRecordBase & {
     kind: "deposit";
-    predictedCommitment: {
-        hex: string;
-        index?: number;
-        root?: string;
-    };
+    /** Predicted commitments for each note */
+    predictedCommitments: PredictedCommitment[];
 };
-export type PendingTransactContext = {
+export type TransactContext = {
     index: number;
     nullifier: string;
     witness: {
@@ -32,19 +54,44 @@ export type PendingTransactContext = {
     };
     root: string;
 };
-export type PendingTransactOutput = {
+export type TransactOutput = {
     hex: string;
     index: number;
     root?: string;
 };
-export type PendingTransactJob = PendingJobBase & {
-    kind: "transact";
+/**
+ * Individual transaction info within a transact job.
+ */
+export type TransactJobTransaction = {
+    token: string;
+    nullifiers: string[];
+    predictedCommitments: Array<{
+        hex: string;
+        index?: number;
+    }>;
+    /** For withdrawals: amount and recipient */
+    withdrawal?: {
+        amount: string;
+        recipient: string;
+    };
+};
+/** Fields shared by transfer and withdraw records */
+type PoolTransactionFields = {
     poolAddress: string;
     calldata: string;
-    contexts: PendingTransactContext[];
-    predictedOutputs: PendingTransactOutput[];
-    expectedRoot?: string;
+    /** Individual transactions in the batch */
+    transactions: TransactJobTransaction[];
+};
+export type TransferRecord = JobRecordBase & PoolTransactionFields & {
+    kind: "transfer";
+};
+export type WithdrawRecord = JobRecordBase & PoolTransactionFields & {
+    kind: "withdraw";
 };
-export type PendingJobRecord = PendingDepositJob | PendingTransactJob;
+/** Union of all pool transaction records (transfer or withdraw) */
+export type PoolTransactionRecord = TransferRecord | WithdrawRecord;
+/** Union of all job records */
+export type JobRecord = DepositRecord | TransferRecord | WithdrawRecord;
 export declare const DEFAULT_JOB_TIMEOUT_MS: number;
+export {};
 //# sourceMappingURL=jobs.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"jobs.d.ts","sourceRoot":"","sources":["../../../state/store/jobs.ts"],"names":[],"mappings":"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"}

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

@@ -1 +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"}
+{"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;IAI5C;;OAEG;yBACwB,MAAM;EAQpC"}

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

@@ -15,15 +15,12 @@ export function createLeafStore(storage) {
          * 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)

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

@@ -4,7 +4,9 @@ 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.
+     * If the note already exists and is marked as spent, preserve spentAt unless the caller
+     * provides an explicit spentAt value (eg. upgrading from a local observation time to an
+     * on-chain timestamp from the indexer).
      */
     putNote(note: NoteInsert): Promise<void>;
     /**
@@ -21,18 +23,16 @@ export declare function createNoteStore(storage: Storage): {
         includeSpent?: boolean;
     }): Promise<NoteRecord[]>;
     /**
-     * Mark a cached note as spent by setting its timestamp and re-indexing metadata.
+     * Mark a cached note as spent by setting its timestamp and transaction hash.
      */
-    markNoteSpent(chainId: number, index: number, spentAt?: number): Promise<NoteRecord>;
+    markNoteSpent(chainId: number, index: number, spentAt?: number, spentTxHash?: string): 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.
+     * Remove all cached notes and their unspent indices for a chain.
      */
-    getZkBalances(mpk: string, options?: {
-        chainId?: number;
-    }): Promise<Record<string, bigint>>;
+    clearNotes(chainId: number): Promise<void>;
 };
 //# sourceMappingURL=note-store.d.ts.map

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

@@ -1 +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"}
+{"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;AAevD,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAElE,eAAO,MAAM,UAAU,+BAA0B,CAAC;AAElD,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO;IA2D5C;;;;;OAKG;kBACiB,UAAU;IAW9B;;OAEG;qBACoB,MAAM,SAAS,MAAM;IAI5C;;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;IAkBH;;OAEG;2BAEQ,MAAM,SACR,MAAM,kCAEC,MAAM;IAiBtB;;OAEG;6BAC4B,MAAM,SAAS,MAAM;IAcpD;;OAEG;wBACuB,MAAM;EAmBnC"}

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

@@ -9,9 +9,23 @@ export function createNoteStore(storage) {
         ensurePositiveInt("note index", record.index);
         ensureMpk(record.mpk);
         ensureBigIntString("note value", record.value);
+        if (record.createdAt !== undefined) {
+            ensurePositiveInt("note createdAt", record.createdAt);
+        }
         if (record.spentAt !== undefined) {
             ensurePositiveInt("note spentAt", record.spentAt);
         }
+        if (record.createdTxHash !== undefined &&
+            record.createdTxHash.length === 0) {
+            throw new CoreError("note createdTxHash must be a non-empty string");
+        }
+        if (record.createdEventType !== undefined &&
+            record.createdEventType.length === 0) {
+            throw new CoreError("note createdEventType must be a non-empty string");
+        }
+        if (record.spentTxHash !== undefined && record.spentTxHash.length === 0) {
+            throw new CoreError("note spentTxHash must be a non-empty string");
+        }
         const noteKey = keys.note(record.chainId, record.index);
         const previous = await getJson(storage, noteKey);
         const ops = [
@@ -41,13 +55,15 @@ export function createNoteStore(storage) {
     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.
+         * If the note already exists and is marked as spent, preserve spentAt unless the caller
+         * provides an explicit spentAt value (eg. upgrading from a local observation time to an
+         * on-chain timestamp from the indexer).
          */
         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
+            if (existing?.spentAt !== undefined && note.spentAt === undefined) {
+                // Preserve spentAt if caller doesn't provide a value.
                 await persistNote({ ...note, spentAt: existing.spentAt });
             }
             else {
@@ -58,8 +74,6 @@ export function createNoteStore(storage) {
          * 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));
         },
         /**
@@ -67,12 +81,6 @@ export function createNoteStore(storage) {
          */
         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
@@ -85,20 +93,18 @@ export function createNoteStore(storage) {
             return filtered;
         },
         /**
-         * Mark a cached note as spent by setting its timestamp and re-indexing metadata.
+         * Mark a cached note as spent by setting its timestamp and transaction hash.
          */
-        async markNoteSpent(chainId, index, spentAt = Date.now()) {
-            ensureChainId(chainId);
-            ensurePositiveInt("note index", index);
-            ensurePositiveInt("note spentAt", spentAt);
+        async markNoteSpent(chainId, index, spentAt = Date.now(), spentTxHash) {
             const existing = await store.getNote(chainId, index);
             if (!existing) {
                 throw new CoreError("note not found");
             }
-            if (existing.spentAt === spentAt) {
+            if (existing.spentAt === spentAt &&
+                existing.spentTxHash === spentTxHash) {
                 return existing;
             }
-            const updated = { ...existing, spentAt };
+            const updated = { ...existing, spentAt, spentTxHash };
             await persistNote(updated);
             return updated;
         },
@@ -106,8 +112,6 @@ export function createNoteStore(storage) {
          * 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");
@@ -121,21 +125,21 @@ export function createNoteStore(storage) {
             return updated;
         },
         /**
-         * Aggregate unspent note balances per token for a given master public key.
+         * Remove all cached notes and their unspent indices for a chain.
          */
-        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;
+        async clearNotes(chainId) {
+            const notePrefix = `notes:${chainId}:`;
+            const noteEntries = await storage.iter({ prefix: notePrefix });
+            // Also clear unspent indices for this chain (all mpks)
+            const unspentPrefix = `idx:notes:unspent:${chainId}:`;
+            const unspentEntries = await storage.iter({ prefix: unspentPrefix });
+            if (noteEntries.length === 0 && unspentEntries.length === 0)
+                return;
+            const deletions = [
+                ...noteEntries.map(({ key }) => ({ del: key })),
+                ...unspentEntries.map(({ key }) => ({ del: key })),
+            ];
+            await storage.batch(deletions);
         },
     };
     return store;

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

@@ -13,5 +13,14 @@ export declare function createNullifierStore(storage: Storage): {
      * Count all nullifiers stored locally for a given chain.
      */
     countNullifiers(chainId: number): Promise<number>;
+    /**
+     * Remove all cached nullifiers for a chain.
+     */
+    clearNullifiers(chainId: number): Promise<void>;
+    /**
+     * Remove cached nullifiers whose noteIndex >= fromIndex.
+     * Used by partial resync to keep the count-based optimization accurate.
+     */
+    clearNullifiersFromIndex(chainId: number, fromIndex: number): Promise<void>;
 };
 //# sourceMappingURL=nullifier-store.d.ts.map