@veilo/sdk-core 0.4.0 → 0.6.0

package/dist/esm/events/index.js

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./parsing.js";
+export * from "./position.js";
+export * from "./recovery.js";
+export * from "./scanning.js";
+export * from "./tree.js";

package/dist/esm/events/parsing.d.ts

@@ -0,0 +1,25 @@
+import { PublicKey } from "@solana/web3.js";
+import { type VersionedPrivacyPoolIdl } from "../idl/index.js";
+import type { CommitmentEvent, NullifierSpentEvent, ParsedVeiloEvent } from "./types.js";
+/**
+ * Decode logs using the current, legacy, and legacy-2 IDLs.
+ *
+ * IDLs are evaluated in the relayer's current/legacy/legacy-2 order. Anchor's
+ * Borsh decoder accepts trailing bytes, however, so every successful parse is
+ * considered and the richest result wins. That preserves the compact fields
+ * in legacy-2 events instead of misclassifying them as the shorter legacy form.
+ * Ties retain the relayer's order.
+ */
+export declare function parseVeiloEventsWithFallback(logMessages: readonly string[] | null | undefined, programId: PublicKey, idls?: readonly VersionedPrivacyPoolIdl[]): ParsedVeiloEvent[];
+export declare function parseCommitmentEventsFromLogs(params: {
+    logMessages: readonly string[] | null | undefined;
+    programId: PublicKey;
+    txSignature: string;
+    slot: number;
+}): CommitmentEvent[];
+export declare function parseNullifierEventsFromLogs(params: {
+    logMessages: readonly string[] | null | undefined;
+    programId: PublicKey;
+    txSignature: string;
+    slot: number;
+}): NullifierSpentEvent[];

package/dist/esm/events/parsing.js

@@ -0,0 +1,120 @@
+import * as anchor from "@coral-xyz/anchor";
+import { PublicKey } from "@solana/web3.js";
+import { PRIVACY_POOL_IDLS, } from "../idl/index.js";
+/**
+ * Decode logs using the current, legacy, and legacy-2 IDLs.
+ *
+ * IDLs are evaluated in the relayer's current/legacy/legacy-2 order. Anchor's
+ * Borsh decoder accepts trailing bytes, however, so every successful parse is
+ * considered and the richest result wins. That preserves the compact fields
+ * in legacy-2 events instead of misclassifying them as the shorter legacy form.
+ * Ties retain the relayer's order.
+ */
+export function parseVeiloEventsWithFallback(logMessages, programId, idls = PRIVACY_POOL_IDLS) {
+    if (!logMessages?.length)
+        return [];
+    let best = [];
+    let bestScore = -1;
+    for (const candidate of idls) {
+        try {
+            const parser = new anchor.EventParser(programId, new anchor.BorshCoder(candidate.idl));
+            const parsed = Array.from(parser.parseLogs([...logMessages])).map((event) => ({
+                name: event.name,
+                data: event.data,
+                idlVersion: candidate.version,
+            }));
+            const score = parsed.reduce((total, event) => total + decodedFieldCount(event.data), 0);
+            if (score > bestScore) {
+                best = parsed;
+                bestScore = score;
+            }
+        }
+        catch {
+            // The discriminator is shared while historical payload lengths differ.
+        }
+    }
+    return best;
+}
+export function parseCommitmentEventsFromLogs(params) {
+    const { logMessages, programId, txSignature, slot } = params;
+    const out = [];
+    for (const event of parseVeiloEventsWithFallback(logMessages, programId)) {
+        if (event.name.toLowerCase() !== "commitmentevent")
+            continue;
+        const data = event.data;
+        const mintAddress = toPublicKey(field(data, "mintAddress", "mint_address"));
+        const ephemeralPublicKey = optionalBytes(field(data, "ephemeralPublicKey", "ephemeral_public_key"));
+        const encryptedBlob = optionalBytes(field(data, "encryptedBlob", "encrypted_blob"));
+        const rawViewTag = field(data, "viewTag", "view_tag");
+        out.push({
+            commitment: toBytes(field(data, "commitment"), 32, "commitment"),
+            leafIndex: toSafeNumber(field(data, "leafIndex", "leaf_index"), "leafIndex"),
+            newRoot: toBytes(field(data, "newRoot", "new_root"), 32, "newRoot"),
+            timestamp: toSafeNumber(field(data, "timestamp"), "timestamp"),
+            mintAddress,
+            treeId: toSafeNumber(field(data, "treeId", "tree_id"), "treeId"),
+            txSignature,
+            slot,
+            ...(ephemeralPublicKey ? { ephemeralPublicKey } : {}),
+            ...(encryptedBlob ? { encryptedBlob } : {}),
+            ...(rawViewTag !== undefined
+                ? { viewTag: toSafeNumber(rawViewTag, "viewTag") }
+                : {}),
+            source: "emitted",
+            idlVersion: event.idlVersion,
+        });
+    }
+    return out;
+}
+export function parseNullifierEventsFromLogs(params) {
+    const { logMessages, programId, txSignature, slot } = params;
+    const out = [];
+    for (const event of parseVeiloEventsWithFallback(logMessages, programId)) {
+        if (event.name.toLowerCase() !== "nullifierspent")
+            continue;
+        const data = event.data;
+        out.push({
+            nullifier: toBytes(field(data, "nullifier"), 32, "nullifier"),
+            timestamp: toSafeNumber(field(data, "timestamp"), "timestamp"),
+            mintAddress: toPublicKey(field(data, "mintAddress", "mint_address")),
+            treeId: toSafeNumber(field(data, "treeId", "tree_id"), "treeId"),
+            txSignature,
+            slot,
+            idlVersion: event.idlVersion,
+        });
+    }
+    return out;
+}
+function field(data, camel, snake) {
+    return data[camel] ?? (snake ? data[snake] : undefined);
+}
+function optionalBytes(value) {
+    return value === undefined || value === null
+        ? undefined
+        : new Uint8Array(value);
+}
+function decodedFieldCount(value) {
+    return value && typeof value === "object" ? Object.keys(value).length : 0;
+}
+function toBytes(value, length, label) {
+    const bytes = new Uint8Array(value);
+    if (bytes.length !== length) {
+        throw new Error(`${label} must be ${length} bytes, got ${bytes.length}`);
+    }
+    return bytes;
+}
+function toPublicKey(value) {
+    if (value instanceof PublicKey)
+        return value;
+    return new PublicKey(value);
+}
+function toSafeNumber(value, label) {
+    if (value === undefined || value === null) {
+        throw new Error(`Missing ${label} in decoded event`);
+    }
+    const numeric = typeof value === "number" ? value : Number(value);
+    if (!Number.isSafeInteger(numeric)) {
+        throw new Error(`${label} is outside JavaScript's safe integer range`);
+    }
+    return numeric;
+}

package/dist/esm/events/position.d.ts

@@ -0,0 +1,26 @@
+import type { Idl, Program } from "@coral-xyz/anchor";
+import { PublicKey } from "@solana/web3.js";
+import type { CommitmentEvent } from "./types.js";
+/**
+ * Privacy-pool mints copied from the relayer's global position-tree classifier.
+ * Position commitments use non-pool destination mints at the same tree ID.
+ */
+export declare const POSITION_TREE_POOL_MINTS: readonly PublicKey[];
+export declare function isGlobalPositionCommitment(event: CommitmentEvent): boolean;
+/**
+ * Rebuild the one global position tree shared across every position mint.
+ * This mirrors the relayer: scan all mints for the position tree ID, then drop
+ * normal privacy-pool mint events before sorting by the global leaf index.
+ */
+export declare function buildGlobalPositionTreeFromEvents<T extends Idl>(params: {
+    program: Program<T>;
+    positionTreeId?: number;
+    depth?: number;
+    additionalEvents?: readonly CommitmentEvent[];
+    includeProtectedEvents?: boolean;
+    strictLeafIndices?: boolean;
+}): Promise<{
+    tree: import("../merkle.js").MerkleTree;
+    events: CommitmentEvent[];
+    latestSignature: string;
+}>;

package/dist/esm/events/position.js

@@ -0,0 +1,48 @@
+import { PublicKey } from "@solana/web3.js";
+import { getAllProtectedCommitmentEvents } from "./recovery.js";
+import { scanAllCommitmentEvents } from "./scanning.js";
+import { dedupeCommitmentEvents, reconstructTreeFromCommitmentEvents, } from "./tree.js";
+/**
+ * Privacy-pool mints copied from the relayer's global position-tree classifier.
+ * Position commitments use non-pool destination mints at the same tree ID.
+ */
+export const POSITION_TREE_POOL_MINTS = [
+    PublicKey.default,
+    new PublicKey("So11111111111111111111111111111111111111112"),
+    new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"),
+    new PublicKey("Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB"),
+    new PublicKey("USD1ttGY1N17NEEHLmELoaybftRBUSErhqYiQzvEmuB"),
+    new PublicKey("JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN"),
+    new PublicKey("ARXwZkNAtzPfdcoqQiduJn8EPv9fKiDfGn2KyggyDrFs"),
+];
+const POOL_MINTS = new Set(POSITION_TREE_POOL_MINTS.map((mint) => mint.toBase58()));
+export function isGlobalPositionCommitment(event) {
+    return !POOL_MINTS.has(event.mintAddress.toBase58());
+}
+/**
+ * Rebuild the one global position tree shared across every position mint.
+ * This mirrors the relayer: scan all mints for the position tree ID, then drop
+ * normal privacy-pool mint events before sorting by the global leaf index.
+ */
+export async function buildGlobalPositionTreeFromEvents(params) {
+    const { program, positionTreeId = 0, depth = 22, additionalEvents = [], includeProtectedEvents = true, strictLeafIndices = true, } = params;
+    const emitted = await scanAllCommitmentEvents({ program });
+    const protectedEvents = includeProtectedEvents
+        ? getAllProtectedCommitmentEvents()
+        : [];
+    const events = dedupeCommitmentEvents([
+        ...emitted,
+        ...additionalEvents,
+        ...protectedEvents,
+    ])
+        .filter((event) => event.treeId === positionTreeId && isGlobalPositionCommitment(event))
+        .sort((a, b) => a.leafIndex - b.leafIndex);
+    return {
+        tree: reconstructTreeFromCommitmentEvents(events, {
+            depth,
+            strictLeafIndices,
+        }),
+        events,
+        latestSignature: events[events.length - 1]?.txSignature,
+    };
+}

package/dist/esm/events/recovery.d.ts

@@ -0,0 +1,87 @@
+import type { Connection } from "@solana/web3.js";
+import { PublicKey } from "@solana/web3.js";
+import { MerkleTree } from "../merkle.js";
+import type { CommitmentEvent } from "./types.js";
+/**
+ * Historical leaves repaired manually in the relayer.
+ *
+ * The deployed `open_position` instruction appended these commitments without
+ * emitting CommitmentEvent. They must be retained when rebuilding history.
+ * Values are copied byte-for-byte from relayer-server/src/db/service.ts.
+ */
+export declare const PROTECTED_COMMITMENT_EVENTS: readonly [{
+    readonly leafIndex: 3738;
+    readonly commitmentHex: "0c7850c9360e041ceeba27297e0fd49fa6a224a651c2fff8c56b22c70a319a94";
+}, {
+    readonly leafIndex: 4;
+    readonly commitmentHex: "15e182d12e044ef2a469ccda88d903304a4e3e69f72765a29e4e6df9c206b0bf";
+    readonly mintAddressHex: "e272b88fb18eaf1994acb885bdba76820c567c3467300f0cd320a0c15ebf9d2f";
+    readonly onChainTreeId: 0;
+}];
+/** @deprecated Use PROTECTED_COMMITMENT_EVENTS. */
+export declare const PROTECTED_COMMITMENT_EVENT: {
+    readonly leafIndex: 3738;
+    readonly commitmentHex: "0c7850c9360e041ceeba27297e0fd49fa6a224a651c2fff8c56b22c70a319a94";
+};
+/** Return protected records as normal SDK events for a particular tree. */
+export declare function getProtectedCommitmentEvents(params: {
+    mintAddress: PublicKey;
+    treeId?: number;
+}): CommitmentEvent[];
+/** Return every protected leaf, including the global position-tree repair. */
+export declare function getAllProtectedCommitmentEvents(): CommitmentEvent[];
+/**
+ * Add the protected historical leaves without duplicating records already read
+ * from an indexer. A conflicting commitment at a protected index is rejected.
+ */
+export declare function mergeProtectedCommitmentEvents(events: readonly CommitmentEvent[], params: {
+    mintAddress: PublicKey;
+    treeId?: number;
+}): CommitmentEvent[];
+/**
+ * Insert expected commitments and prefer authoritative emitted metadata when it
+ * exists. Missing events are computed from the local tree exactly like the
+ * relayer's `insertAndPersistCommitments` fallback.
+ *
+ * This function mutates `tree`.
+ */
+export declare function resolveCommitmentEvents(params: {
+    commitments: readonly Uint8Array[];
+    tree: MerkleTree;
+    logMessages?: readonly string[] | null;
+    programId: PublicKey;
+    mintAddress: PublicKey;
+    treeId: number;
+    txSignature: string;
+    slot: number;
+    timestamp?: number;
+    requireAllInLogs?: boolean;
+}): CommitmentEvent[];
+export type EventlessOpenPositionCommitments = {
+    sourceMint: PublicKey;
+    sourceTreeId: number;
+    sourceCommitment: Uint8Array;
+    positionMint: PublicKey;
+    positionTreeId: number;
+    positionCommitment: Uint8Array;
+    positionPdaKey: Uint8Array;
+};
+/** Decode the two commitments hidden in a current `open_position` instruction. */
+export declare function decodeEventlessOpenPositionCommitments(instructionData: Uint8Array): EventlessOpenPositionCommitments | null;
+export declare function getPositionPda(programId: PublicKey, positionPdaKey: Uint8Array): PublicKey;
+/** Read PositionPDA.leaf_index at the same byte offset used by the relayer. */
+export declare function readPositionLeafIndex(accountData: Uint8Array): number;
+/**
+ * Recover the two events omitted by the deployed `open_position` instruction.
+ * The source tree must already contain every earlier source-mint commitment.
+ * This function inserts the source commitment into that tree.
+ */
+export declare function recoverEventlessOpenPositionEvents(params: {
+    instructionData: Uint8Array;
+    sourceTree: MerkleTree;
+    connection: Pick<Connection, "getAccountInfo">;
+    programId: PublicKey;
+    txSignature: string;
+    slot: number;
+    timestamp?: number;
+}): Promise<CommitmentEvent[]>;

package/dist/esm/events/recovery.js

@@ -0,0 +1,237 @@
+import * as anchor from "@coral-xyz/anchor";
+import { PublicKey } from "@solana/web3.js";
+import { PRIVACY_POOL_CURRENT_IDL } from "../idl/index.js";
+import { parseCommitmentEventsFromLogs } from "./parsing.js";
+/**
+ * Historical leaves repaired manually in the relayer.
+ *
+ * The deployed `open_position` instruction appended these commitments without
+ * emitting CommitmentEvent. They must be retained when rebuilding history.
+ * Values are copied byte-for-byte from relayer-server/src/db/service.ts.
+ */
+export const PROTECTED_COMMITMENT_EVENTS = [
+    {
+        leafIndex: 3738,
+        commitmentHex: "0c7850c9360e041ceeba27297e0fd49fa6a224a651c2fff8c56b22c70a319a94",
+    },
+    {
+        leafIndex: 4,
+        commitmentHex: "15e182d12e044ef2a469ccda88d903304a4e3e69f72765a29e4e6df9c206b0bf",
+        mintAddressHex: "e272b88fb18eaf1994acb885bdba76820c567c3467300f0cd320a0c15ebf9d2f",
+        onChainTreeId: 0,
+    },
+];
+/** @deprecated Use PROTECTED_COMMITMENT_EVENTS. */
+export const PROTECTED_COMMITMENT_EVENT = PROTECTED_COMMITMENT_EVENTS[0];
+/** Return protected records as normal SDK events for a particular tree. */
+export function getProtectedCommitmentEvents(params) {
+    const { mintAddress, treeId = 0 } = params;
+    const mintHex = bytesToHex(mintAddress.toBytes());
+    return getAllProtectedCommitmentEvents().filter((event) => bytesToHex(event.mintAddress.toBytes()) === mintHex &&
+        event.treeId === treeId);
+}
+/** Return every protected leaf, including the global position-tree repair. */
+export function getAllProtectedCommitmentEvents() {
+    return PROTECTED_COMMITMENT_EVENTS.map((record) => {
+        const mintBytes = "mintAddressHex" in record
+            ? hexToBytes(record.mintAddressHex)
+            : PublicKey.default.toBytes();
+        return {
+            commitment: hexToBytes(record.commitmentHex),
+            leafIndex: record.leafIndex,
+            newRoot: new Uint8Array(32),
+            timestamp: 0,
+            mintAddress: new PublicKey(mintBytes),
+            treeId: "onChainTreeId" in record ? record.onChainTreeId : 0,
+            txSignature: "protected-backfill",
+            slot: 0,
+            source: "protected",
+        };
+    });
+}
+/**
+ * Add the protected historical leaves without duplicating records already read
+ * from an indexer. A conflicting commitment at a protected index is rejected.
+ */
+export function mergeProtectedCommitmentEvents(events, params) {
+    const merged = [...events];
+    for (const protectedEvent of getProtectedCommitmentEvents(params)) {
+        const sameCommitment = merged.find((event) => bytesEqual(event.commitment, protectedEvent.commitment));
+        if (sameCommitment)
+            continue;
+        const atIndex = merged.find((event) => event.treeId === protectedEvent.treeId &&
+            event.leafIndex === protectedEvent.leafIndex);
+        if (atIndex) {
+            throw new Error(`Protected commitment conflicts with leaf ${protectedEvent.leafIndex}`);
+        }
+        merged.push(protectedEvent);
+    }
+    return merged.sort((a, b) => a.leafIndex - b.leafIndex);
+}
+/**
+ * Insert expected commitments and prefer authoritative emitted metadata when it
+ * exists. Missing events are computed from the local tree exactly like the
+ * relayer's `insertAndPersistCommitments` fallback.
+ *
+ * This function mutates `tree`.
+ */
+export function resolveCommitmentEvents(params) {
+    const { commitments, tree, logMessages, programId, mintAddress, treeId, txSignature, slot, timestamp = 0, requireAllInLogs = false, } = params;
+    const emitted = parseCommitmentEventsFromLogs({
+        logMessages,
+        programId,
+        txSignature,
+        slot,
+    });
+    const emittedByCommitment = new Map(emitted.map((event) => [bytesToHex(event.commitment), event]));
+    if (requireAllInLogs) {
+        const missing = commitments.filter((commitment) => !emittedByCommitment.has(bytesToHex(commitment)));
+        if (missing.length > 0) {
+            throw new Error(`Missing ${missing.length}/${commitments.length} commitment event(s) in transaction logs`);
+        }
+    }
+    return commitments.map((commitment) => {
+        const { index, root } = tree.insert(commitment);
+        return (emittedByCommitment.get(bytesToHex(commitment)) ?? {
+            commitment: new Uint8Array(commitment),
+            leafIndex: index,
+            newRoot: new Uint8Array(root),
+            timestamp,
+            mintAddress,
+            treeId,
+            txSignature,
+            slot,
+            source: "computed",
+        });
+    });
+}
+/** Decode the two commitments hidden in a current `open_position` instruction. */
+export function decodeEventlessOpenPositionCommitments(instructionData) {
+    const coder = new anchor.BorshInstructionCoder(PRIVACY_POOL_CURRENT_IDL);
+    let decoded;
+    try {
+        decoded = coder.decode(Buffer.from(instructionData));
+    }
+    catch {
+        return null;
+    }
+    if (!decoded || !/open_?position/i.test(decoded.name))
+        return null;
+    const data = decoded.data;
+    return {
+        sourceMint: toPublicKey(field(data, "sourceMint", "source_mint")),
+        sourceTreeId: toSafeNumber(field(data, "sourceTreeId", "source_tree_id") ?? 0, "sourceTreeId"),
+        sourceCommitment: toBytes(field(data, "outputCommitment0", "output_commitment_0"), 32, "outputCommitment0"),
+        positionMint: toPublicKey(field(data, "destMint", "dest_mint")),
+        positionTreeId: toSafeNumber(field(data, "positionTreeId", "position_tree_id") ?? 0, "positionTreeId"),
+        positionCommitment: toBytes(field(data, "outputCommitment1", "output_commitment_1"), 32, "outputCommitment1"),
+        positionPdaKey: toBytes(field(data, "positionPdaKey", "position_pda_key"), 32, "positionPdaKey"),
+    };
+}
+export function getPositionPda(programId, positionPdaKey) {
+    return PublicKey.findProgramAddressSync([new TextEncoder().encode("position_pda_v1"), positionPdaKey], programId)[0];
+}
+/** Read PositionPDA.leaf_index at the same byte offset used by the relayer. */
+export function readPositionLeafIndex(accountData) {
+    if (accountData.length < 57) {
+        throw new Error(`PositionPDA data is too short: ${accountData.length} bytes`);
+    }
+    const expected = getPositionPdaDiscriminator();
+    if (!bytesEqual(accountData.slice(0, 8), expected)) {
+        throw new Error("PositionPDA discriminator mismatch");
+    }
+    const leafIndex = new DataView(accountData.buffer, accountData.byteOffset, accountData.byteLength).getBigUint64(49, true);
+    if (leafIndex > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new Error("PositionPDA leaf index exceeds JavaScript's safe integer range");
+    }
+    return Number(leafIndex);
+}
+/**
+ * Recover the two events omitted by the deployed `open_position` instruction.
+ * The source tree must already contain every earlier source-mint commitment.
+ * This function inserts the source commitment into that tree.
+ */
+export async function recoverEventlessOpenPositionEvents(params) {
+    const decoded = decodeEventlessOpenPositionCommitments(params.instructionData);
+    if (!decoded)
+        return [];
+    const positionPda = getPositionPda(params.programId, decoded.positionPdaKey);
+    const account = (await params.connection.getAccountInfo(positionPda));
+    if (account && !account.owner.equals(params.programId)) {
+        throw new Error("PositionPDA is not owned by the Veilo program");
+    }
+    const positionLeafIndex = account
+        ? readPositionLeafIndex(new Uint8Array(account.data))
+        : undefined;
+    const { index, root } = params.sourceTree.insert(decoded.sourceCommitment);
+    const sourceEvent = {
+        commitment: decoded.sourceCommitment,
+        leafIndex: index,
+        newRoot: new Uint8Array(root),
+        timestamp: params.timestamp ?? 0,
+        mintAddress: decoded.sourceMint,
+        treeId: decoded.sourceTreeId,
+        txSignature: params.txSignature,
+        slot: params.slot,
+        source: "computed",
+    };
+    if (positionLeafIndex === undefined)
+        return [sourceEvent];
+    return [
+        sourceEvent,
+        {
+            commitment: decoded.positionCommitment,
+            leafIndex: positionLeafIndex,
+            newRoot: new Uint8Array(32),
+            timestamp: params.timestamp ?? 0,
+            mintAddress: decoded.positionMint,
+            treeId: decoded.positionTreeId,
+            txSignature: params.txSignature,
+            slot: params.slot,
+            source: "computed",
+        },
+    ];
+}
+function getPositionPdaDiscriminator() {
+    const account = (PRIVACY_POOL_CURRENT_IDL.accounts ?? []).find((entry) => entry.name === "PositionPDA");
+    if (!account?.discriminator) {
+        throw new Error("Current IDL does not define PositionPDA");
+    }
+    return new Uint8Array(account.discriminator);
+}
+function field(data, camel, snake) {
+    return data[camel] ?? data[snake];
+}
+function toPublicKey(value) {
+    if (value instanceof PublicKey)
+        return value;
+    return new PublicKey(value);
+}
+function toBytes(value, length, label) {
+    const bytes = new Uint8Array(value);
+    if (bytes.length !== length) {
+        throw new Error(`${label} must be ${length} bytes, got ${bytes.length}`);
+    }
+    return bytes;
+}
+function toSafeNumber(value, label) {
+    const number = typeof value === "number" ? value : Number(value);
+    if (!Number.isSafeInteger(number)) {
+        throw new Error(`${label} is outside JavaScript's safe integer range`);
+    }
+    return number;
+}
+function hexToBytes(hex) {
+    if (!/^[0-9a-f]{64}$/i.test(hex)) {
+        throw new Error("Commitment hex must contain exactly 32 bytes");
+    }
+    return Uint8Array.from({ length: 32 }, (_, index) => Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16));
+}
+function bytesToHex(bytes) {
+    return Array.from(bytes, (value) => value.toString(16).padStart(2, "0")).join("");
+}
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return a.every((value, index) => value === b[index]);
+}

package/dist/esm/events/scanning.d.ts

@@ -0,0 +1,35 @@
+import type { Idl, Program } from "@coral-xyz/anchor";
+import type { PublicKey } from "@solana/web3.js";
+import type { CommitmentEvent, NullifierSpentEvent } from "./types.js";
+export type EventScanPage<T> = {
+    events: T[];
+    /** Oldest signature examined, even when it emitted no matching event. */
+    nextBefore?: string;
+    scannedSignatures: number;
+};
+export type EventScanParams<T extends Idl> = {
+    program: Program<T>;
+    mintAddress?: PublicKey;
+    before?: string;
+    until?: string;
+    /** Number of program signatures to inspect. Maximum 1,000. */
+    limit?: number;
+};
+/** Scan one RPC page and retain a correct pagination cursor. */
+export declare function scanCommitmentEventPage<T extends Idl>(params: EventScanParams<T>): Promise<EventScanPage<CommitmentEvent>>;
+/**
+ * Scan a single page of CommitmentEvents.
+ *
+ * Use `scanAllCommitmentEvents` when reconstructing a complete historical tree.
+ */
+export declare function scanCommitmentEvents<T extends Idl>(params: EventScanParams<T>): Promise<CommitmentEvent[]>;
+/** Scan all historical pages without using event count as the RPC cursor. */
+export declare function scanAllCommitmentEvents<T extends Idl>(params: {
+    program: Program<T>;
+    mintAddress?: PublicKey;
+    before?: string;
+    until?: string;
+    pageSize?: number;
+}): Promise<CommitmentEvent[]>;
+/** Scan one RPC page of NullifierSpent events using all historical IDLs. */
+export declare function scanNullifierEvents<T extends Idl>(params: EventScanParams<T>): Promise<NullifierSpentEvent[]>;

package/dist/esm/events/scanning.js

@@ -0,0 +1,92 @@
+import { parseCommitmentEventsFromLogs, parseNullifierEventsFromLogs, } from "./parsing.js";
+/** Scan one RPC page and retain a correct pagination cursor. */
+export async function scanCommitmentEventPage(params) {
+    const { program, mintAddress, before, until, limit = 1000 } = params;
+    assertPageSize(limit);
+    const signatures = await program.provider.connection.getSignaturesForAddress(program.programId, { before, until, limit });
+    const events = [];
+    for (const signature of signatures) {
+        if (signature.err)
+            continue;
+        const tx = await program.provider.connection.getTransaction(signature.signature, { commitment: "confirmed", maxSupportedTransactionVersion: 0 });
+        if (!tx)
+            continue;
+        for (const event of parseCommitmentEventsFromLogs({
+            logMessages: tx.meta?.logMessages,
+            programId: program.programId,
+            txSignature: signature.signature,
+            slot: signature.slot,
+        })) {
+            if (!mintAddress || event.mintAddress.equals(mintAddress)) {
+                events.push(event);
+            }
+        }
+    }
+    return {
+        events,
+        nextBefore: signatures[signatures.length - 1]?.signature,
+        scannedSignatures: signatures.length,
+    };
+}
+/**
+ * Scan a single page of CommitmentEvents.
+ *
+ * Use `scanAllCommitmentEvents` when reconstructing a complete historical tree.
+ */
+export async function scanCommitmentEvents(params) {
+    return (await scanCommitmentEventPage(params)).events;
+}
+/** Scan all historical pages without using event count as the RPC cursor. */
+export async function scanAllCommitmentEvents(params) {
+    const { program, mintAddress, until, pageSize = 1000 } = params;
+    assertPageSize(pageSize);
+    const events = [];
+    let before = params.before;
+    while (true) {
+        const page = await scanCommitmentEventPage({
+            program,
+            mintAddress,
+            before,
+            until,
+            limit: pageSize,
+        });
+        events.push(...page.events);
+        if (page.scannedSignatures < pageSize || !page.nextBefore)
+            break;
+        if (page.nextBefore === before) {
+            throw new Error("Commitment event pagination cursor did not advance");
+        }
+        before = page.nextBefore;
+    }
+    return events;
+}
+/** Scan one RPC page of NullifierSpent events using all historical IDLs. */
+export async function scanNullifierEvents(params) {
+    const { program, mintAddress, before, until, limit = 1000 } = params;
+    assertPageSize(limit);
+    const signatures = await program.provider.connection.getSignaturesForAddress(program.programId, { before, until, limit });
+    const events = [];
+    for (const signature of signatures) {
+        if (signature.err)
+            continue;
+        const tx = await program.provider.connection.getTransaction(signature.signature, { commitment: "confirmed", maxSupportedTransactionVersion: 0 });
+        if (!tx)
+            continue;
+        for (const event of parseNullifierEventsFromLogs({
+            logMessages: tx.meta?.logMessages,
+            programId: program.programId,
+            txSignature: signature.signature,
+            slot: signature.slot,
+        })) {
+            if (!mintAddress || event.mintAddress.equals(mintAddress)) {
+                events.push(event);
+            }
+        }
+    }
+    return events;
+}
+function assertPageSize(value) {
+    if (!Number.isInteger(value) || value < 1 || value > 1000) {
+        throw new RangeError(`Event scan page size must be an integer from 1 to 1000, got ${value}`);
+    }
+}