@veilo/sdk-core 0.5.0 → 0.7.0

package/dist/cjs/events/position.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POSITION_TREE_POOL_MINTS = void 0;
+exports.isGlobalPositionCommitment = isGlobalPositionCommitment;
+exports.buildGlobalPositionTreeFromEvents = buildGlobalPositionTreeFromEvents;
+const web3_js_1 = require("@solana/web3.js");
+const recovery_js_1 = require("./recovery.js");
+const scanning_js_1 = require("./scanning.js");
+const tree_js_1 = require("./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.
+ */
+exports.POSITION_TREE_POOL_MINTS = [
+    web3_js_1.PublicKey.default,
+    new web3_js_1.PublicKey("So11111111111111111111111111111111111111112"),
+    new web3_js_1.PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"),
+    new web3_js_1.PublicKey("Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB"),
+    new web3_js_1.PublicKey("USD1ttGY1N17NEEHLmELoaybftRBUSErhqYiQzvEmuB"),
+    new web3_js_1.PublicKey("JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN"),
+    new web3_js_1.PublicKey("ARXwZkNAtzPfdcoqQiduJn8EPv9fKiDfGn2KyggyDrFs"),
+];
+const POOL_MINTS = new Set(exports.POSITION_TREE_POOL_MINTS.map((mint) => mint.toBase58()));
+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.
+ */
+async function buildGlobalPositionTreeFromEvents(params) {
+    const { program, positionTreeId = 0, depth = 22, additionalEvents = [], includeProtectedEvents = true, strictLeafIndices = true, } = params;
+    const emitted = await (0, scanning_js_1.scanAllCommitmentEvents)({ program });
+    const protectedEvents = includeProtectedEvents
+        ? (0, recovery_js_1.getAllProtectedCommitmentEvents)()
+        : [];
+    const events = (0, tree_js_1.dedupeCommitmentEvents)([
+        ...emitted,
+        ...additionalEvents,
+        ...protectedEvents,
+    ])
+        .filter((event) => event.treeId === positionTreeId && isGlobalPositionCommitment(event))
+        .sort((a, b) => a.leafIndex - b.leafIndex);
+    return {
+        tree: (0, tree_js_1.reconstructTreeFromCommitmentEvents)(events, {
+            depth,
+            strictLeafIndices,
+        }),
+        events,
+        latestSignature: events[events.length - 1]?.txSignature,
+    };
+}

package/dist/cjs/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/cjs/events/recovery.js

@@ -0,0 +1,281 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROTECTED_COMMITMENT_EVENT = exports.PROTECTED_COMMITMENT_EVENTS = void 0;
+exports.getProtectedCommitmentEvents = getProtectedCommitmentEvents;
+exports.getAllProtectedCommitmentEvents = getAllProtectedCommitmentEvents;
+exports.mergeProtectedCommitmentEvents = mergeProtectedCommitmentEvents;
+exports.resolveCommitmentEvents = resolveCommitmentEvents;
+exports.decodeEventlessOpenPositionCommitments = decodeEventlessOpenPositionCommitments;
+exports.getPositionPda = getPositionPda;
+exports.readPositionLeafIndex = readPositionLeafIndex;
+exports.recoverEventlessOpenPositionEvents = recoverEventlessOpenPositionEvents;
+const anchor = __importStar(require("@coral-xyz/anchor"));
+const web3_js_1 = require("@solana/web3.js");
+const index_js_1 = require("../idl/index.js");
+const parsing_js_1 = require("./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.
+ */
+exports.PROTECTED_COMMITMENT_EVENTS = [
+    {
+        leafIndex: 3738,
+        commitmentHex: "0c7850c9360e041ceeba27297e0fd49fa6a224a651c2fff8c56b22c70a319a94",
+    },
+    {
+        leafIndex: 4,
+        commitmentHex: "15e182d12e044ef2a469ccda88d903304a4e3e69f72765a29e4e6df9c206b0bf",
+        mintAddressHex: "e272b88fb18eaf1994acb885bdba76820c567c3467300f0cd320a0c15ebf9d2f",
+        onChainTreeId: 0,
+    },
+];
+/** @deprecated Use PROTECTED_COMMITMENT_EVENTS. */
+exports.PROTECTED_COMMITMENT_EVENT = exports.PROTECTED_COMMITMENT_EVENTS[0];
+/** Return protected records as normal SDK events for a particular tree. */
+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. */
+function getAllProtectedCommitmentEvents() {
+    return exports.PROTECTED_COMMITMENT_EVENTS.map((record) => {
+        const mintBytes = "mintAddressHex" in record
+            ? hexToBytes(record.mintAddressHex)
+            : web3_js_1.PublicKey.default.toBytes();
+        return {
+            commitment: hexToBytes(record.commitmentHex),
+            leafIndex: record.leafIndex,
+            newRoot: new Uint8Array(32),
+            timestamp: 0,
+            mintAddress: new web3_js_1.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.
+ */
+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`.
+ */
+function resolveCommitmentEvents(params) {
+    const { commitments, tree, logMessages, programId, mintAddress, treeId, txSignature, slot, timestamp = 0, requireAllInLogs = false, } = params;
+    const emitted = (0, parsing_js_1.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. */
+function decodeEventlessOpenPositionCommitments(instructionData) {
+    const coder = new anchor.BorshInstructionCoder(index_js_1.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"),
+    };
+}
+function getPositionPda(programId, positionPdaKey) {
+    return web3_js_1.PublicKey.findProgramAddressSync([new TextEncoder().encode("position_pda_v1"), positionPdaKey], programId)[0];
+}
+/** Read PositionPDA.leaf_index at the same byte offset used by the relayer. */
+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.
+ */
+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 = (index_js_1.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 web3_js_1.PublicKey)
+        return value;
+    return new web3_js_1.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/cjs/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/cjs/events/scanning.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanCommitmentEventPage = scanCommitmentEventPage;
+exports.scanCommitmentEvents = scanCommitmentEvents;
+exports.scanAllCommitmentEvents = scanAllCommitmentEvents;
+exports.scanNullifierEvents = scanNullifierEvents;
+const parsing_js_1 = require("./parsing.js");
+/** Scan one RPC page and retain a correct pagination cursor. */
+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 (0, parsing_js_1.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.
+ */
+async function scanCommitmentEvents(params) {
+    return (await scanCommitmentEventPage(params)).events;
+}
+/** Scan all historical pages without using event count as the RPC cursor. */
+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. */
+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 (0, parsing_js_1.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}`);
+    }
+}

package/dist/cjs/events/tree.d.ts

@@ -0,0 +1,27 @@
+import type { Idl, Program } from "@coral-xyz/anchor";
+import type { PublicKey } from "@solana/web3.js";
+import { MerkleTree } from "../merkle.js";
+import type { CommitmentEvent } from "./types.js";
+/** Rebuild a local Veilo tree from emitted, computed, and protected history. */
+export declare function buildTreeFromEvents<T extends Idl>(params: {
+    program: Program<T>;
+    mintAddress: PublicKey;
+    treeId?: number;
+    depth?: number;
+    /** Eventless commitments recovered with the helpers in `events/recovery`. */
+    additionalEvents?: readonly CommitmentEvent[];
+    /** Includes the relayer's two protected historical repairs. Defaults to true. */
+    includeProtectedEvents?: boolean;
+    /** Reject missing or duplicate leaf indices instead of building a wrong root. */
+    strictLeafIndices?: boolean;
+}): Promise<{
+    tree: MerkleTree;
+    events: CommitmentEvent[];
+    latestSignature?: string;
+}>;
+export declare function dedupeCommitmentEvents(events: readonly CommitmentEvent[]): CommitmentEvent[];
+/** Build a Merkle tree from already-collected events in authoritative order. */
+export declare function reconstructTreeFromCommitmentEvents(events: readonly CommitmentEvent[], options?: {
+    depth?: number;
+    strictLeafIndices?: boolean;
+}): MerkleTree;

package/dist/cjs/events/tree.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTreeFromEvents = buildTreeFromEvents;
+exports.dedupeCommitmentEvents = dedupeCommitmentEvents;
+exports.reconstructTreeFromCommitmentEvents = reconstructTreeFromCommitmentEvents;
+const merkle_js_1 = require("../merkle.js");
+const recovery_js_1 = require("./recovery.js");
+const scanning_js_1 = require("./scanning.js");
+/** Rebuild a local Veilo tree from emitted, computed, and protected history. */
+async function buildTreeFromEvents(params) {
+    const { program, mintAddress, treeId = 0, depth = 22, additionalEvents = [], includeProtectedEvents = true, strictLeafIndices = true, } = params;
+    const emitted = await (0, scanning_js_1.scanAllCommitmentEvents)({ program, mintAddress });
+    let treeEvents = dedupeCommitmentEvents([...emitted, ...additionalEvents])
+        .filter((event) => event.treeId === treeId && event.mintAddress.equals(mintAddress))
+        .sort((a, b) => a.leafIndex - b.leafIndex);
+    if (includeProtectedEvents) {
+        treeEvents = (0, recovery_js_1.mergeProtectedCommitmentEvents)(treeEvents, {
+            mintAddress,
+            treeId,
+        });
+    }
+    const tree = reconstructTreeFromCommitmentEvents(treeEvents, {
+        depth,
+        strictLeafIndices,
+    });
+    return {
+        tree,
+        events: treeEvents,
+        latestSignature: treeEvents[treeEvents.length - 1]?.txSignature,
+    };
+}
+function dedupeCommitmentEvents(events) {
+    const byCommitment = new Map();
+    for (const event of events) {
+        const key = Array.from(event.commitment, (value) => value.toString(16).padStart(2, "0")).join("");
+        const existing = byCommitment.get(key);
+        if (!existing || eventPriority(event) > eventPriority(existing)) {
+            byCommitment.set(key, event);
+        }
+    }
+    return [...byCommitment.values()];
+}
+function eventPriority(event) {
+    // Events created before `source` was added came from on-chain log scans and
+    // are therefore treated as authoritative emitted records.
+    if (event.source === "protected")
+        return 1;
+    if (event.source === "computed")
+        return 2;
+    return 3;
+}
+/** Build a Merkle tree from already-collected events in authoritative order. */
+function reconstructTreeFromCommitmentEvents(events, options = {}) {
+    const tree = new merkle_js_1.MerkleTree(options.depth ?? 22);
+    for (const event of [...events].sort((a, b) => a.leafIndex - b.leafIndex)) {
+        if ((options.strictLeafIndices ?? true) &&
+            event.leafIndex !== tree.nextIndex) {
+            throw new Error(`Commitment history gap: expected leaf ${tree.nextIndex}, got ${event.leafIndex}`);
+        }
+        tree.insert(event.commitment);
+    }
+    return tree;
+}