@veilo/sdk-core 0.5.0 → 0.6.0

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}`);
+    }
+}

package/dist/esm/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/esm/events/tree.js

@@ -0,0 +1,58 @@
+import { MerkleTree } from "../merkle.js";
+import { mergeProtectedCommitmentEvents } from "./recovery.js";
+import { scanAllCommitmentEvents } from "./scanning.js";
+/** Rebuild a local Veilo tree from emitted, computed, and protected history. */
+export async function buildTreeFromEvents(params) {
+    const { program, mintAddress, treeId = 0, depth = 22, additionalEvents = [], includeProtectedEvents = true, strictLeafIndices = true, } = params;
+    const emitted = await 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 = mergeProtectedCommitmentEvents(treeEvents, {
+            mintAddress,
+            treeId,
+        });
+    }
+    const tree = reconstructTreeFromCommitmentEvents(treeEvents, {
+        depth,
+        strictLeafIndices,
+    });
+    return {
+        tree,
+        events: treeEvents,
+        latestSignature: treeEvents[treeEvents.length - 1]?.txSignature,
+    };
+}
+export 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. */
+export function reconstructTreeFromCommitmentEvents(events, options = {}) {
+    const tree = new 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;
+}

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

@@ -0,0 +1,39 @@
+import type { PublicKey } from "@solana/web3.js";
+import type { PrivacyPoolIdlVersion } from "../idl/index.js";
+export type CommitmentEventSource = "emitted" | "computed" | "protected";
+/**
+ * A commitment appended to a Veilo Merkle tree.
+ *
+ * Compact recovery fields are optional because they were added across two
+ * program upgrades. Historical events remain valid without them.
+ */
+export type CommitmentEvent = {
+    commitment: Uint8Array;
+    leafIndex: number;
+    newRoot: Uint8Array;
+    timestamp: number;
+    mintAddress: PublicKey;
+    treeId: number;
+    txSignature: string;
+    slot: number;
+    ephemeralPublicKey?: Uint8Array;
+    encryptedBlob?: Uint8Array;
+    viewTag?: number;
+    source?: CommitmentEventSource;
+    idlVersion?: PrivacyPoolIdlVersion;
+};
+/** On-chain event emitted when a private note is consumed. */
+export type NullifierSpentEvent = {
+    nullifier: Uint8Array;
+    timestamp: number;
+    mintAddress: PublicKey;
+    treeId: number;
+    txSignature: string;
+    slot: number;
+    idlVersion?: PrivacyPoolIdlVersion;
+};
+export type ParsedVeiloEvent = {
+    name: string;
+    data: unknown;
+    idlVersion: PrivacyPoolIdlVersion;
+};

package/dist/esm/events/types.js

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

package/dist/esm/events.d.ts

@@ -1,77 +1 @@
-import { PublicKey } from "@solana/web3.js";
-import { Program, Idl } from "@coral-xyz/anchor";
-import { MerkleTree } from "./merkle.js";
-/**
- * On-chain CommitmentEvent emitted by `transact` and `transact_swap`.
- * Mirrors the IDL CommitmentEvent struct.
- */
-export type CommitmentEvent = {
-    commitment: Uint8Array;
-    leafIndex: number;
-    newRoot: Uint8Array;
-    timestamp: number;
-    mintAddress: PublicKey;
-    treeId: number;
-    txSignature: string;
-    slot: number;
-};
-/**
- * On-chain NullifierSpent event emitted when a UTXO is consumed.
- * Mirrors the IDL NullifierSpent struct.
- */
-export type NullifierSpentEvent = {
-    nullifier: Uint8Array;
-    timestamp: number;
-    mintAddress: PublicKey;
-    treeId: number;
-    txSignature: string;
-    slot: number;
-};
-/**
- * Fetch and parse CommitmentEvents for a program, optionally filtered by mint.
- *
- * @param program     - Anchor program instance
- * @param mintAddress - Filter to a specific pool; omit to get all pools
- * @param before      - Start paging before this signature (exclusive)
- * @param until       - Stop paging at this signature (exclusive)
- * @param limit       - Max signatures to fetch per page (default 1000)
- */
-export declare function scanCommitmentEvents<T extends Idl>(params: {
-    program: Program<T>;
-    mintAddress?: PublicKey;
-    before?: string;
-    until?: string;
-    limit?: number;
-}): Promise<CommitmentEvent[]>;
-/**
- * Fetch and parse NullifierSpent events for a program, optionally filtered by mint.
- */
-export declare function scanNullifierEvents<T extends Idl>(params: {
-    program: Program<T>;
-    mintAddress?: PublicKey;
-    before?: string;
-    until?: string;
-    limit?: number;
-}): Promise<NullifierSpentEvent[]>;
-/**
- * Rebuild a local MerkleTree from on-chain CommitmentEvents.
- * Use this to get a valid inclusion proof for spending any UTXO.
- *
- * CommitmentEvents are sorted by (treeId, leafIndex) so the local tree
- * matches the on-chain state exactly.
- *
- * @param program     - Anchor program instance
- * @param mintAddress - Pool to reconstruct
- * @param treeId      - Which tree to reconstruct (default 0)
- * @param depth       - Merkle tree depth (default 22, must match on-chain)
- */
-export declare function buildTreeFromEvents<T extends Idl>(params: {
-    program: Program<T>;
-    mintAddress: PublicKey;
-    treeId?: number;
-    depth?: number;
-}): Promise<{
-    tree: MerkleTree;
-    events: CommitmentEvent[];
-    latestSignature?: string;
-}>;
+export * from "./events/index.js";