@unlink-xyz/core 0.1.0

package/dist/state/index.js

@@ -0,0 +1,2 @@
+export * from "./merkle/index.js";
+export * from "./store/index.js";

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

@@ -0,0 +1,17 @@
+import type { Storage } from "../types.js";
+import type { LeafRecord } from "./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/leaf-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leaf-store.d.ts","sourceRoot":"","sources":["../../state/leaf-store.ts"],"names":[],"mappings":"AACA,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;IAM9B;;OAEG;qBACoB,MAAM,SAAS,MAAM;IAM5C;;OAEG;yBACwB,MAAM;EASpC"}

package/dist/state/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/merkle/hydrator.d.ts

@@ -0,0 +1,27 @@
+export type LeafLoader = (chainId: number, index: number) => Promise<{
+    commitment: string;
+} | null>;
+export declare 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;
+}): Promise<number>;
+export type HydrateChainParams = {
+    chainId: number;
+    trees: {
+        reset(chainId: number): void;
+        addLeaf(chainId: number, value: bigint): {
+            index: number;
+        };
+    };
+    loadLeaf: LeafLoader;
+    hydrated: Set<number>;
+};
+export declare function hydrateChain({ chainId, trees, loadLeaf, hydrated, }: HydrateChainParams): Promise<void>;
+//# sourceMappingURL=hydrator.d.ts.map

package/dist/state/merkle/hydrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrator.d.ts","sourceRoot":"","sources":["../../../state/merkle/hydrator.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,UAAU,GAAG,CACvB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,KACV,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAAC;AAE5C,wBAAsB,oBAAoB,CAAC,EACzC,OAAO,EACP,KAAK,EACL,QAAQ,GACT,EAAE;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QACL,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG;YAAE,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;QAC3D,YAAY,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;KACxC,CAAC;IACF,QAAQ,EAAE,UAAU,CAAC;CACtB,mBAeA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QACL,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG;YAAE,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;KAC5D,CAAC;IACF,QAAQ,EAAE,UAAU,CAAC;IACrB,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACvB,CAAC;AAKF,wBAAsB,YAAY,CAAC,EACjC,OAAO,EACP,KAAK,EACL,QAAQ,EACR,QAAQ,GACT,EAAE,kBAAkB,iBAcpB"}

package/dist/state/merkle/hydrator.js

@@ -0,0 +1,36 @@
+import { parseHexToBigInt } from "../../utils/bigint.js";
+export async function rebuildTreeFromStore({ chainId, trees, loadLeaf, }) {
+    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;
+}
+// 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, }) {
+    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/dist/state/merkle/index.d.ts

@@ -0,0 +1,3 @@
+export { createLocalMerkleTree, createMerkleTrees, type LocalMerkleTree, type LocalMerkleTrees, type MerkleProof, } from "./merkle-tree.js";
+export { hydrateChain, rebuildTreeFromStore, type HydrateChainParams, } from "./hydrator.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../state/merkle/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,WAAW,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,KAAK,kBAAkB,GACxB,MAAM,eAAe,CAAC"}

package/dist/state/merkle/index.js

@@ -0,0 +1,2 @@
+export { createLocalMerkleTree, createMerkleTrees, } from "./merkle-tree.js";
+export { hydrateChain, rebuildTreeFromStore, } from "./hydrator.js";

package/dist/state/merkle/merkle-tree.d.ts

@@ -0,0 +1,34 @@
+import { IMTMerkleProof } from "@zk-kit/imt";
+export type AddLeafResult = {
+    index: number;
+    root: string;
+};
+export type MerkleProof = {
+    root: string;
+    leaf: string;
+    pathElements: string[][];
+    pathIndices: number[];
+    leafIndex: number;
+};
+export declare function createLocalMerkleTree(): {
+    addLeaf: (value: bigint) => AddLeafResult;
+    getRoot: () => string;
+    getLeafCount: () => number;
+    getLeaf: (index: number) => string;
+    createMerkleProof: (index: number) => IMTMerkleProof;
+    getZero(level: number): string;
+    readonly depth: number;
+    readonly capacity: number;
+};
+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 declare function createMerkleTrees(): LocalMerkleTrees;
+//# sourceMappingURL=merkle-tree.d.ts.map

package/dist/state/merkle/merkle-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merkle-tree.d.ts","sourceRoot":"","sources":["../../../state/merkle/merkle-tree.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,cAAc,EAGf,MAAM,aAAa,CAAC;AAWrB,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,EAAE,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAaF,wBAAgB,qBAAqB;qBAUX,MAAM,KAAG,aAAa;;;qBAsBtB,MAAM;+BAQI,MAAM,KAAG,cAAc;mBAUxC,MAAM;;;EAiBxB;AAED,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEvE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IAClD,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAAC;IAC9C,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC;IACvD,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC;IAClE,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACtC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,CAAC;AAEF,wBAAgB,iBAAiB,IAAI,gBAAgB,CAwCpD"}

package/dist/state/merkle/merkle-tree.js

@@ -0,0 +1,104 @@
+import { poseidon } from "@railgun-community/circomlibjs";
+import { IMT, } from "@zk-kit/imt";
+import { ByteLength, ByteUtils } from "../../key-derivation/bytes.js";
+import { ensureChainId } from "../../utils/validators.js";
+const DEFAULT_DEPTH = 16;
+const DEFAULT_ARITY = 2;
+const ZERO_BYTE_LENGTH = ByteLength.UINT_256;
+// Simple adapter: IMTNode[] -> poseidon(bigint[])
+const hash = (values) => poseidon(values.map((v) => BigInt(v)));
+const formatNode = (value) => 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);
+    function addLeaf(value) {
+        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) {
+        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) {
+        return tree.createProof(index);
+    }
+    return {
+        addLeaf,
+        getRoot,
+        getLeafCount,
+        getLeaf,
+        createMerkleProof,
+        getZero(level) {
+            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 function createMerkleTrees() {
+    const trees = new Map();
+    const resetTree = (chainId) => {
+        ensureChainId(chainId);
+        const tree = createLocalMerkleTree();
+        trees.set(chainId, tree);
+        return tree;
+    };
+    const getOrCreate = (chainId) => {
+        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/dist/state/merkle-tree.d.ts

@@ -0,0 +1,34 @@
+import { IMTMerkleProof } from "@zk-kit/imt";
+export type AddLeafResult = {
+    index: number;
+    root: string;
+};
+export type MerkleProof = {
+    root: string;
+    leaf: string;
+    pathElements: string[][];
+    pathIndices: number[];
+    leafIndex: number;
+};
+export declare function createLocalMerkleTree(): {
+    addLeaf: (value: bigint) => AddLeafResult;
+    getRoot: () => string;
+    getLeafCount: () => number;
+    getLeaf: (index: number) => string;
+    createMerkleProof: (index: number) => IMTMerkleProof;
+    getZero(level: number): string;
+    readonly depth: number;
+    readonly capacity: number;
+};
+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 declare function createMerkleTrees(): LocalMerkleTrees;
+//# sourceMappingURL=merkle-tree.d.ts.map

package/dist/state/merkle-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merkle-tree.d.ts","sourceRoot":"","sources":["../../state/merkle-tree.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,cAAc,EAGf,MAAM,aAAa,CAAC;AAWrB,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,EAAE,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAaF,wBAAgB,qBAAqB;qBAUX,MAAM,KAAG,aAAa;;;qBAsBtB,MAAM;+BAQI,MAAM,KAAG,cAAc;mBAUxC,MAAM;;;EAiBxB;AAED,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEvE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IAClD,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAAC;IAC9C,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC;IACvD,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC;IAClE,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACtC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,CAAC;AAEF,wBAAgB,iBAAiB,IAAI,gBAAgB,CAwCpD"}

package/dist/state/merkle-tree.js

@@ -0,0 +1,104 @@
+import { poseidon } from "@railgun-community/circomlibjs";
+import { IMT, } from "@zk-kit/imt";
+import { ByteLength, ByteUtils } from "../key-derivation/bytes.js";
+import { ensureChainId } from "../utils/validators.js";
+const DEFAULT_DEPTH = 16;
+const DEFAULT_ARITY = 2;
+const ZERO_BYTE_LENGTH = ByteLength.UINT_256;
+// Simple adapter: IMTNode[] -> poseidon(bigint[])
+const hash = (values) => poseidon(values.map((v) => BigInt(v)));
+const formatNode = (value) => 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);
+    function addLeaf(value) {
+        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) {
+        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) {
+        return tree.createProof(index);
+    }
+    return {
+        addLeaf,
+        getRoot,
+        getLeafCount,
+        getLeaf,
+        createMerkleProof,
+        getZero(level) {
+            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 function createMerkleTrees() {
+    const trees = new Map();
+    const resetTree = (chainId) => {
+        ensureChainId(chainId);
+        const tree = createLocalMerkleTree();
+        trees.set(chainId, tree);
+        return tree;
+    };
+    const getOrCreate = (chainId) => {
+        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/dist/state/note-store.d.ts

@@ -0,0 +1,37 @@
+import type { Storage } from "../types.js";
+import type { NoteInsert, NoteRecord } from "./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.
+     */
+    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/note-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"note-store.d.ts","sourceRoot":"","sources":["../../state/note-store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAW,OAAO,EAAE,MAAM,aAAa,CAAC;AAapD,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE3D,eAAO,MAAM,UAAU,+BAA0B,CAAC;AAElD,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO;IAyC5C;;OAEG;kBACiB,UAAU;IAI9B;;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/note-store.js

@@ -0,0 +1,133 @@
+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.
+         */
+        async putNote(note) {
+            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/nullifier-store.d.ts

@@ -0,0 +1,13 @@
+import type { Storage } from "../types.js";
+import type { NullifierRecord } from "./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>;
+};
+//# sourceMappingURL=nullifier-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nullifier-store.d.ts","sourceRoot":"","sources":["../../state/nullifier-store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO;IAEjD;;OAEG;4BAC2B,eAAe;IAS7C;;OAEG;0BACyB,MAAM,SAAS,MAAM;EAKpD"}

package/dist/state/nullifier-store.js

@@ -0,0 +1,21 @@
+import { keys } from "../keys.js";
+import { getJson, putJson } from "../utils/json-codec.js";
+import { ensureChainId } from "../utils/validators.js";
+export function createNullifierStore(storage) {
+    return {
+        /**
+         * Record a nullifier observation so later syncs can de-duplicate work.
+         */
+        async putNullifier(nullifier) {
+            ensureChainId(nullifier.chainId);
+            await putJson(storage, keys.nullifier(nullifier.chainId, nullifier.nullifier), nullifier);
+        },
+        /**
+         * Lookup a previously observed nullifier by value.
+         */
+        async getNullifier(chainId, value) {
+            ensureChainId(chainId);
+            return getJson(storage, keys.nullifier(chainId, value));
+        },
+    };
+}