@veilo/sdk-core 0.5.0 → 0.6.0

package/dist/esm/events.js

@@ -1,129 +1,3 @@
-import * as anchor from "@coral-xyz/anchor";
-import { MerkleTree } from "./merkle.js";
-// -----------------------------------------------------------------------------
-// Event Scanning
-// -----------------------------------------------------------------------------
-/**
- * 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 async function scanCommitmentEvents(params) {
-    const { program, mintAddress, before, until, limit = 1000 } = params;
-    const out = [];
-    const eventParser = new anchor.EventParser(program.programId, new anchor.BorshCoder(program.idl));
-    const sigs = await program.provider.connection.getSignaturesForAddress(program.programId, { before, until, limit });
-    for (const sigInfo of sigs) {
-        if (sigInfo.err)
-            continue;
-        const tx = await program.provider.connection.getTransaction(sigInfo.signature, { commitment: "confirmed", maxSupportedTransactionVersion: 0 });
-        if (!tx)
-            continue;
-        const events = Array.from(eventParser.parseLogs(tx.meta?.logMessages ?? []));
-        for (const ev of events) {
-            if (ev.name !== "commitmentEvent")
-                continue;
-            const d = ev.data;
-            const evMint = d.mintAddress;
-            if (mintAddress && !evMint.equals(mintAddress))
-                continue;
-            out.push({
-                commitment: new Uint8Array(d.commitment),
-                leafIndex: Number(d.leafIndex),
-                newRoot: new Uint8Array(d.newRoot),
-                timestamp: Number(d.timestamp),
-                mintAddress: evMint,
-                treeId: Number(d.treeId),
-                txSignature: sigInfo.signature,
-                slot: sigInfo.slot,
-            });
-        }
-    }
-    return out;
-}
-/**
- * Fetch and parse NullifierSpent events for a program, optionally filtered by mint.
- */
-export async function scanNullifierEvents(params) {
-    const { program, mintAddress, before, until, limit = 1000 } = params;
-    const out = [];
-    const eventParser = new anchor.EventParser(program.programId, new anchor.BorshCoder(program.idl));
-    const sigs = await program.provider.connection.getSignaturesForAddress(program.programId, { before, until, limit });
-    for (const sigInfo of sigs) {
-        if (sigInfo.err)
-            continue;
-        const tx = await program.provider.connection.getTransaction(sigInfo.signature, { commitment: "confirmed", maxSupportedTransactionVersion: 0 });
-        if (!tx)
-            continue;
-        const events = Array.from(eventParser.parseLogs(tx.meta?.logMessages ?? []));
-        for (const ev of events) {
-            if (ev.name !== "nullifierSpent")
-                continue;
-            const d = ev.data;
-            const evMint = d.mintAddress;
-            if (mintAddress && !evMint.equals(mintAddress))
-                continue;
-            out.push({
-                nullifier: new Uint8Array(d.nullifier),
-                timestamp: Number(d.timestamp),
-                mintAddress: evMint,
-                treeId: Number(d.treeId),
-                txSignature: sigInfo.signature,
-                slot: sigInfo.slot,
-            });
-        }
-    }
-    return out;
-}
-// -----------------------------------------------------------------------------
-// Tree Reconstruction
-// -----------------------------------------------------------------------------
-/**
- * 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 async function buildTreeFromEvents(params) {
-    const { program, mintAddress, treeId = 0, depth = 22 } = params;
-    // Fetch all commitment events for this pool (page until no more results).
-    // Oldest-first so we insert leaves in the correct order.
-    const allEvents = [];
-    let before;
-    while (true) {
-        const page = await scanCommitmentEvents({
-            program,
-            mintAddress,
-            before,
-            limit: 1000,
-        });
-        if (page.length === 0)
-            break;
-        allEvents.push(...page);
-        before = page[page.length - 1].txSignature;
-        if (page.length < 1000)
-            break;
-    }
-    // Keep only events for this treeId, sort by leafIndex ascending
-    const treeEvents = allEvents
-        .filter((e) => e.treeId === treeId)
-        .sort((a, b) => a.leafIndex - b.leafIndex);
-    const tree = new MerkleTree(depth);
-    for (const ev of treeEvents) {
-        tree.insert(ev.commitment);
-    }
-    const latestSignature = treeEvents.length > 0
-        ? treeEvents[treeEvents.length - 1].txSignature
-        : undefined;
-    return { tree, events: treeEvents, latestSignature };
-}
+// Backward-compatible entry point. Event parsing, scanning, and recovery live
+// in focused modules under src/events.
+export * from "./events/index.js";

package/dist/esm/identity/encoding.d.ts

@@ -0,0 +1,9 @@
+export declare function concatBytes(...parts: readonly Uint8Array[]): Uint8Array;
+export declare function utf8(value: string): Uint8Array;
+export declare function uint32Le(value: number, label?: string): Uint8Array;
+export declare function uint64Le(value: bigint, label?: string): Uint8Array;
+export declare function assertBytes(value: Uint8Array, length: number, label: string): void;
+export declare function bytesToHex(bytes: Uint8Array): string;
+export declare function hexToBytes(value: string, length?: number, label?: string): Uint8Array;
+/** Encode bytes using the Bitcoin/Solana base58 alphabet. */
+export declare function encodeBase58(bytes: Uint8Array): string;

package/dist/esm/identity/encoding.js

@@ -0,0 +1,75 @@
+const BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+export function concatBytes(...parts) {
+    const output = new Uint8Array(parts.reduce((length, part) => length + part.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        output.set(part, offset);
+        offset += part.length;
+    }
+    return output;
+}
+export function utf8(value) {
+    return new TextEncoder().encode(value);
+}
+export function uint32Le(value, label = "value") {
+    if (!Number.isSafeInteger(value) || value < 0 || value > 4294967295) {
+        throw new RangeError(`${label} must be an unsigned 32-bit integer`);
+    }
+    const bytes = new Uint8Array(4);
+    new DataView(bytes.buffer).setUint32(0, value, true);
+    return bytes;
+}
+export function uint64Le(value, label = "value") {
+    if (value < 0n || value > 0xffffffffffffffffn) {
+        throw new RangeError(`${label} must be an unsigned 64-bit integer`);
+    }
+    const bytes = new Uint8Array(8);
+    new DataView(bytes.buffer).setBigUint64(0, value, true);
+    return bytes;
+}
+export function assertBytes(value, length, label) {
+    if (value.length !== length) {
+        throw new RangeError(`${label} must be ${length} bytes, got ${value.length}`);
+    }
+}
+export function bytesToHex(bytes) {
+    return Array.from(bytes, (value) => value.toString(16).padStart(2, "0")).join("");
+}
+export function hexToBytes(value, length, label = "hex value") {
+    const clean = value.startsWith("0x") ? value.slice(2) : value;
+    if (!/^[0-9a-f]*$/i.test(clean) || clean.length % 2 !== 0) {
+        throw new TypeError(`${label} must be an even-length hexadecimal string`);
+    }
+    const bytes = Uint8Array.from({ length: clean.length / 2 }, (_, index) => Number.parseInt(clean.slice(index * 2, index * 2 + 2), 16));
+    if (length !== undefined)
+        assertBytes(bytes, length, label);
+    return bytes;
+}
+/** Encode bytes using the Bitcoin/Solana base58 alphabet. */
+export function encodeBase58(bytes) {
+    if (bytes.length === 0)
+        return "";
+    let zeroes = 0;
+    while (zeroes < bytes.length && bytes[zeroes] === 0)
+        zeroes++;
+    if (zeroes === bytes.length)
+        return "1".repeat(zeroes);
+    const digits = [0];
+    for (let index = zeroes; index < bytes.length; index++) {
+        let carry = bytes[index];
+        for (let digit = 0; digit < digits.length; digit++) {
+            const value = digits[digit] * 256 + carry;
+            digits[digit] = value % 58;
+            carry = Math.floor(value / 58);
+        }
+        while (carry > 0) {
+            digits.push(carry % 58);
+            carry = Math.floor(carry / 58);
+        }
+    }
+    let encoded = "1".repeat(zeroes);
+    for (let index = digits.length - 1; index >= 0; index--) {
+        encoded += BASE58_ALPHABET[digits[index]];
+    }
+    return encoded;
+}

package/dist/esm/identity/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./encoding.js";
+export * from "./spending.js";
+export * from "./noteKey.js";
+export * from "./viewKey.js";

package/dist/esm/identity/index.js

@@ -0,0 +1,4 @@
+export * from "./encoding.js";
+export * from "./spending.js";
+export * from "./noteKey.js";
+export * from "./viewKey.js";

package/dist/esm/identity/noteKey.d.ts

@@ -0,0 +1,33 @@
+/** Domain-separation label. Permanent — see the header. */
+export declare const VEILO_NOTE_KEY_LABEL = "veilo_note_key_v1";
+/** The note spending key plus the Poseidon public key derived from it. */
+export interface NoteKeypair {
+    /** Raw 32-byte scalar, strictly below the BN254 Fr modulus. */
+    noteSecretKey: Uint8Array;
+    /** Hex form, matching how the relayer has always returned this key. */
+    noteSecretKeyHex: string;
+    /** Poseidon(noteSecretKey) — the note's committed owner. */
+    notePublicKey: bigint;
+    /** Decimal string form, as the relayer and note scanner expect it. */
+    notePublicKeyString: string;
+}
+/**
+ * Derive the note spending key from a spending-key root.
+ *
+ * @param spendingKey 32 bytes from `deriveSpendingKeyFromSignature` or a sibling
+ */
+export declare function deriveNoteKeyFromSpendingKey(spendingKey: Uint8Array): Uint8Array;
+/**
+ * Derive the note spending key and its Poseidon public key.
+ *
+ * Call `initPoseidon()` once before this, as with `derivePositionKeys`.
+ */
+export declare function deriveNoteKeypairFromSpendingKey(spendingKey: Uint8Array): NoteKeypair;
+/**
+ * One-shot derivation for a dapp holding only a wallet-standard `signMessage`.
+ *
+ * Prompts a single signature, then returns spend authority for the account.
+ * The signature is secret material: keep it in memory, never persist it, and
+ * never expose the result on a global.
+ */
+export declare function deriveNoteKeypairWithSigner(signMessage: (message: Uint8Array) => Promise<Uint8Array>, index?: number): Promise<NoteKeypair>;

package/dist/esm/identity/noteKey.js

@@ -0,0 +1,91 @@
+/**
+ * Derivation of the Veilo NOTE SPENDING KEY from a spending-key root.
+ *
+ * ⚠ BYTE-FOR-BYTE PORT — must agree with
+ *   veilo-browser-extension/extension-ui/src/lib/veiloNoteKey.ts
+ *   wallet-app/src/lib/veiloNoteKey.ts
+ * An account created in one client must be spendable from the others, so the
+ * label, the HMAC construction and the rejection rule are all load-bearing.
+ * `tests/identity-keys.test.ts` re-implements the client algorithm
+ * independently and asserts equality, plus pins a known-answer vector.
+ *
+ * WHAT THIS KEY IS
+ * ----------------
+ * `zk-circuits/keypair.circom` defines publicKey = Poseidon(privateKey), and
+ * `transaction.circom` constrains Poseidon(privateKey) === the note's committed
+ * owner before it will emit a proof, then derives the nullifier from the same
+ * key. This one scalar is both proof of ownership and spend authority; there is
+ * no second factor anywhere in the circuit. Treat it exactly as you would a
+ * wallet secret key.
+ *
+ * Derivation:
+ *   spendingKey     = deriveSpendingKeyFromSignature(sig)          // ./spending.js
+ *   veiloPrivateKey = rejectionSample(hmac_sha256(spendingKey, "veilo_note_key_v1|N"))
+ *   veiloPublicKey  = Poseidon(veiloPrivateKey)
+ *
+ * WHY REJECTION SAMPLING AND NOT `mod Fr`
+ * ---------------------------------------
+ * Reducing a 256-bit hash modulo Fr biases the low end of the range. Note that
+ * `derivePositionKeys` uses modular reduction; this key follows the stricter
+ * convention because it is a SPENDING key, matching how real note secrets are
+ * generated. About 0.3% of draws are retried.
+ *
+ * ⚠ THE LABEL IS PERMANENT. Once one note exists under "veilo_note_key_v1",
+ * changing the label or the sampling method makes that note unspendable
+ * forever. Version it, never edit it.
+ *
+ * ⚠ APPLIES TO `derived-v3` ACCOUNTS ONLY. Accounts whose relayer record has
+ * `veiloKeySource` absent or "legacy" have a SERVER-GENERATED note key that no
+ * derivation can reproduce — those clients must decrypt the key the relayer
+ * serves them. Check the account's key source before assuming this function
+ * yields a usable key.
+ */
+import { hmac } from "@noble/hashes/hmac";
+import { sha256 } from "@noble/hashes/sha256";
+import { BN254_FR_MODULUS, bytesToBigIntBE, poseidon1 } from "../poseidon.js";
+import { assertBytes, bytesToHex, utf8 } from "./encoding.js";
+import { deriveSpendingKeyWithSigner } from "./spending.js";
+/** Domain-separation label. Permanent — see the header. */
+export const VEILO_NOTE_KEY_LABEL = "veilo_note_key_v1";
+/** Practically unreachable: 256 consecutive rejections is ~1e-640. */
+const MAX_REJECTION_ROUNDS = 256;
+/**
+ * Derive the note spending key from a spending-key root.
+ *
+ * @param spendingKey 32 bytes from `deriveSpendingKeyFromSignature` or a sibling
+ */
+export function deriveNoteKeyFromSpendingKey(spendingKey) {
+    assertBytes(spendingKey, 32, "spending key");
+    for (let counter = 0; counter < MAX_REJECTION_ROUNDS; counter++) {
+        const candidate = hmac(sha256, spendingKey, utf8(`${VEILO_NOTE_KEY_LABEL}|${counter}`));
+        if (bytesToBigIntBE(candidate) < BN254_FR_MODULUS)
+            return candidate;
+    }
+    // Reaching here means HMAC-SHA256 is broken, not that we were unlucky.
+    throw new Error(`Failed to derive a field element for "${VEILO_NOTE_KEY_LABEL}"`);
+}
+/**
+ * Derive the note spending key and its Poseidon public key.
+ *
+ * Call `initPoseidon()` once before this, as with `derivePositionKeys`.
+ */
+export function deriveNoteKeypairFromSpendingKey(spendingKey) {
+    const noteSecretKey = deriveNoteKeyFromSpendingKey(spendingKey);
+    const notePublicKey = poseidon1(bytesToBigIntBE(noteSecretKey));
+    return {
+        noteSecretKey,
+        noteSecretKeyHex: bytesToHex(noteSecretKey),
+        notePublicKey,
+        notePublicKeyString: notePublicKey.toString(),
+    };
+}
+/**
+ * One-shot derivation for a dapp holding only a wallet-standard `signMessage`.
+ *
+ * Prompts a single signature, then returns spend authority for the account.
+ * The signature is secret material: keep it in memory, never persist it, and
+ * never expose the result on a global.
+ */
+export async function deriveNoteKeypairWithSigner(signMessage, index = 0) {
+    return deriveNoteKeypairFromSpendingKey(await deriveSpendingKeyWithSigner(signMessage, index));
+}

package/dist/esm/identity/spending.d.ts

@@ -0,0 +1,18 @@
+import { Keypair } from "@solana/web3.js";
+export declare const VEILO_SPENDING_KEY_DOMAIN = "veilo_spending_key_v1";
+/** Exact message signed by Veilo clients to derive a spending-key root. */
+export declare function getSpendingKeyMessage(index?: number): Uint8Array;
+/** Convert the deterministic 64-byte wallet signature into a spending key. */
+export declare function deriveSpendingKeyFromSignature(signature: Uint8Array): Uint8Array;
+/**
+ * Wallet-standard-friendly spending-key derivation.
+ * The callback owns signing; the SDK never receives the wallet secret key.
+ */
+export declare function deriveSpendingKeyWithSigner(signMessage: (message: Uint8Array) => Promise<Uint8Array>, index?: number): Promise<Uint8Array>;
+/**
+ * Keypair convenience matching the wallet-app and extension implementation.
+ * Keep the keypair on the user's device and never send it to a service.
+ */
+export declare function deriveSpendingKeyFromKeypair(keypair: Keypair, index?: number): Uint8Array;
+/** Serialize an ephemeral claimant secret for an encrypted relayer request. */
+export declare function encodeClaimantSecretKey(keypairOrSecret: Keypair | Uint8Array): string;

package/dist/esm/identity/spending.js

@@ -0,0 +1,35 @@
+import { sha256 } from "@noble/hashes/sha256";
+import nacl from "tweetnacl";
+import { assertBytes, concatBytes, encodeBase58, uint32Le, utf8, } from "./encoding.js";
+export const VEILO_SPENDING_KEY_DOMAIN = "veilo_spending_key_v1";
+/** Exact message signed by Veilo clients to derive a spending-key root. */
+export function getSpendingKeyMessage(index = 0) {
+    return concatBytes(utf8(VEILO_SPENDING_KEY_DOMAIN), uint32Le(index, "spending-key index"));
+}
+/** Convert the deterministic 64-byte wallet signature into a spending key. */
+export function deriveSpendingKeyFromSignature(signature) {
+    assertBytes(signature, 64, "spending-key signature");
+    return sha256(signature);
+}
+/**
+ * Wallet-standard-friendly spending-key derivation.
+ * The callback owns signing; the SDK never receives the wallet secret key.
+ */
+export async function deriveSpendingKeyWithSigner(signMessage, index = 0) {
+    return deriveSpendingKeyFromSignature(await signMessage(getSpendingKeyMessage(index)));
+}
+/**
+ * Keypair convenience matching the wallet-app and extension implementation.
+ * Keep the keypair on the user's device and never send it to a service.
+ */
+export function deriveSpendingKeyFromKeypair(keypair, index = 0) {
+    return deriveSpendingKeyFromSignature(nacl.sign.detached(getSpendingKeyMessage(index), keypair.secretKey));
+}
+/** Serialize an ephemeral claimant secret for an encrypted relayer request. */
+export function encodeClaimantSecretKey(keypairOrSecret) {
+    const secret = keypairOrSecret instanceof Uint8Array
+        ? keypairOrSecret
+        : keypairOrSecret.secretKey;
+    assertBytes(secret, 64, "claimant secret key");
+    return encodeBase58(secret);
+}

package/dist/esm/identity/viewKey.d.ts

@@ -0,0 +1,38 @@
+import type { CompactNoteCipher } from "../compactNote.js";
+/** HKDF salt. Provisional — see the header. */
+export declare const VEILO_VIEW_KEY_SALT = "veilo_view_v1";
+/** HKDF info. Provisional — see the header. */
+export declare const VEILO_VIEW_KEY_INFO = "x25519";
+/** An X25519 keypair used only to decrypt notes. */
+export interface ViewKeypair {
+    /** 32-byte clamped X25519 scalar. Secret: decrypts every note sent to it. */
+    viewSecretKey: Uint8Array;
+    /** 32-byte X25519 public key — the value senders encrypt to. */
+    viewPublicKey: Uint8Array;
+}
+/** Derive the view keypair from a spending-key root. */
+export declare function deriveViewKeypairFromSpendingKey(spendingKey: Uint8Array): ViewKeypair;
+/**
+ * One-shot derivation for a dapp holding only a wallet-standard `signMessage`.
+ *
+ * Uses the same signature as `deriveNoteKeypairWithSigner`, so a client that
+ * wants both prompts once and derives the spending key itself rather than
+ * calling both helpers.
+ */
+export declare function deriveViewKeypairWithSigner(signMessage: (message: Uint8Array) => Promise<Uint8Array>, index?: number): Promise<ViewKeypair>;
+/**
+ * Scan one candidate cipher with a view key.
+ *
+ * Returns `null` both for a view-tag miss and for a blob that was not encrypted
+ * to this key — the expected outcome for nearly every candidate. The shared
+ * secret is computed once and reused for the tag check and the open, which is
+ * the cheapest correct order for a scan loop: the tag rejects ~255/256
+ * candidates for one scalar multiplication and one hash.
+ *
+ * ⚠ Only decrypts notes encrypted TO `viewPublicKey`. Notes sealed to a wallet
+ * Ed25519 key — every note written before the v2 format — will not open here.
+ */
+export declare function openCompactNoteWithViewKey(viewSecretKey: Uint8Array, cipher: CompactNoteCipher): {
+    blinding: Uint8Array;
+    amount: bigint;
+} | null;

package/dist/esm/identity/viewKey.js

@@ -0,0 +1,96 @@
+/**
+ * Derivation of a VIEW-ONLY note decryption key from a spending-key root.
+ *
+ * ⚠ PROVISIONAL — NOT YET CONSUMED BY ANY NOTE FORMAT.
+ * Today's compact note ciphers are ECDH'd to the recipient's *wallet* Ed25519
+ * key (see `createCompactNoteCipher`), so nothing on-chain or in the relayer is
+ * encrypted to the key this module derives. It exists so the v2 note format —
+ * where senders encrypt to a published `viewPublicKey` instead of the wallet
+ * key — can be built and tested against a fixed derivation. The labels below
+ * become permanent the moment the first note is written under them; until then
+ * they are safe to change.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Note decryption currently requires the wallet Ed25519 secret, which is the
+ * one thing a dapp cannot have. Spend authority, by contrast, is already
+ * signature-derived (`./noteKey.js`). So a dapp can reconstruct the ability to
+ * spend but not the ability to *read*, and since a spend witness needs each
+ * note's amount and blinding, reading gates spending. Publishing a
+ * signature-derived `viewPublicKey` and encrypting to it closes that gap.
+ *
+ * Splitting viewing from spending is the point: `viewSecretKey` decrypts notes
+ * and nothing more. It cannot produce a nullifier, so it cannot spend, and it
+ * cannot determine on its own whether a note is already spent — a view-only
+ * client relies on the relayer's `spent` flag for that.
+ *
+ * Derivation:
+ *   viewSecretKey = clamp(HKDF-SHA256(ikm=spendingKey, salt="veilo_view_v1",
+ *                                     info="x25519", len=32))
+ *   viewPublicKey = X25519_base(viewSecretKey)
+ *
+ * Both salt and info are given explicitly rather than left empty, so a sibling
+ * implementation never has to guess how its HKDF library treats an absent salt.
+ */
+import { hkdf } from "@noble/hashes/hkdf";
+import { sha256 } from "@noble/hashes/sha256";
+import nacl from "tweetnacl";
+import { decryptCompactNoteCipher } from "../compactNote.js";
+import { ed25519PublicKeyToX25519 } from "../notes/mailbox.js";
+import { assertBytes, utf8 } from "./encoding.js";
+import { deriveSpendingKeyWithSigner } from "./spending.js";
+/** HKDF salt. Provisional — see the header. */
+export const VEILO_VIEW_KEY_SALT = "veilo_view_v1";
+/** HKDF info. Provisional — see the header. */
+export const VEILO_VIEW_KEY_INFO = "x25519";
+/**
+ * Apply RFC 7748 clamping so the stored scalar is canonical.
+ *
+ * TweetNaCl clamps internally on every scalar multiplication, so this changes
+ * no result; it means the bytes we hand out are the bytes actually used, which
+ * keeps a sibling implementation from disagreeing about what was stored.
+ */
+function clampX25519(scalar) {
+    const clamped = new Uint8Array(scalar);
+    clamped[0] &= 248;
+    clamped[31] &= 127;
+    clamped[31] |= 64;
+    return clamped;
+}
+/** Derive the view keypair from a spending-key root. */
+export function deriveViewKeypairFromSpendingKey(spendingKey) {
+    assertBytes(spendingKey, 32, "spending key");
+    const viewSecretKey = clampX25519(hkdf(sha256, spendingKey, utf8(VEILO_VIEW_KEY_SALT), utf8(VEILO_VIEW_KEY_INFO), 32));
+    return { viewSecretKey, viewPublicKey: nacl.scalarMult.base(viewSecretKey) };
+}
+/**
+ * One-shot derivation for a dapp holding only a wallet-standard `signMessage`.
+ *
+ * Uses the same signature as `deriveNoteKeypairWithSigner`, so a client that
+ * wants both prompts once and derives the spending key itself rather than
+ * calling both helpers.
+ */
+export async function deriveViewKeypairWithSigner(signMessage, index = 0) {
+    return deriveViewKeypairFromSpendingKey(await deriveSpendingKeyWithSigner(signMessage, index));
+}
+/**
+ * Scan one candidate cipher with a view key.
+ *
+ * Returns `null` both for a view-tag miss and for a blob that was not encrypted
+ * to this key — the expected outcome for nearly every candidate. The shared
+ * secret is computed once and reused for the tag check and the open, which is
+ * the cheapest correct order for a scan loop: the tag rejects ~255/256
+ * candidates for one scalar multiplication and one hash.
+ *
+ * ⚠ Only decrypts notes encrypted TO `viewPublicKey`. Notes sealed to a wallet
+ * Ed25519 key — every note written before the v2 format — will not open here.
+ */
+export function openCompactNoteWithViewKey(viewSecretKey, cipher) {
+    assertBytes(viewSecretKey, 32, "view secret key");
+    assertBytes(cipher.ephemeralPublicKey, 32, "ephemeral public key");
+    const sharedSecret = nacl.scalarMult(viewSecretKey, ed25519PublicKeyToX25519(cipher.ephemeralPublicKey));
+    if (nacl.hash(sharedSecret)[0] !== cipher.viewTag)
+        return null;
+    // walletSecretKey is unused once `sharedSecret` is supplied.
+    return decryptCompactNoteCipher(viewSecretKey, cipher.ephemeralPublicKey, cipher.compactBlob, { sharedSecret });
+}

package/dist/esm/idl/index.d.ts

@@ -0,0 +1,18 @@
+import type { Idl } from "@coral-xyz/anchor";
+/** Protocol generations used to decode Veilo's historical on-chain data. */
+export type PrivacyPoolIdlVersion = "current" | "legacy" | "legacy2";
+export type VersionedPrivacyPoolIdl = {
+    version: PrivacyPoolIdlVersion;
+    idl: Idl;
+};
+/** Current IDL used for building new instructions. */
+export declare const PRIVACY_POOL_CURRENT_IDL: Idl;
+/** Original event shape without compact note recovery fields. */
+export declare const PRIVACY_POOL_LEGACY_IDL: Idl;
+/** Intermediate event shape with compact cipher fields but no view tag. */
+export declare const PRIVACY_POOL_LEGACY2_IDL: Idl;
+/**
+ * IDLs in the same newest-to-oldest fallback order used by the relayer indexer.
+ * All three target the same deployed program address.
+ */
+export declare const PRIVACY_POOL_IDLS: readonly VersionedPrivacyPoolIdl[];

package/dist/esm/idl/index.js

@@ -0,0 +1,18 @@
+import currentIdl from "./privacy_pool.js";
+import legacyIdl from "./privacy_pool_legacy.js";
+import legacy2Idl from "./privacy_pool_legacy2.js";
+/** Current IDL used for building new instructions. */
+export const PRIVACY_POOL_CURRENT_IDL = currentIdl;
+/** Original event shape without compact note recovery fields. */
+export const PRIVACY_POOL_LEGACY_IDL = legacyIdl;
+/** Intermediate event shape with compact cipher fields but no view tag. */
+export const PRIVACY_POOL_LEGACY2_IDL = legacy2Idl;
+/**
+ * IDLs in the same newest-to-oldest fallback order used by the relayer indexer.
+ * All three target the same deployed program address.
+ */
+export const PRIVACY_POOL_IDLS = [
+    { version: "current", idl: PRIVACY_POOL_CURRENT_IDL },
+    { version: "legacy", idl: PRIVACY_POOL_LEGACY_IDL },
+    { version: "legacy2", idl: PRIVACY_POOL_LEGACY2_IDL },
+];