@veilo/sdk-core 0.3.3 → 0.5.0

package/dist/esm/compactNote.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Compact note ciphers — the 80-byte payload carried inside the on-chain
+ * `transact` instruction (`note_ciphers: Option<NoteCiphers>`) and re-emitted in
+ * `CommitmentEvent`.
+ *
+ * This is what makes a note recoverable from chain data alone: a recipient who
+ * was never told about a deposit can still find it by scanning `view_tag` and
+ * decrypting the blob. Without it, note delivery depends on someone calling the
+ * relayer, which a third-party integrator cannot be trusted to do.
+ *
+ * ## Byte-compatibility is load-bearing
+ *
+ * Four sibling implementations already exist (relayer-server, extension ×2,
+ * wallet-app). This is the canonical one, and it MUST agree with them byte for
+ * byte in both directions:
+ *
+ *   - disagree on encrypt → new notes are invisible to every existing client
+ *   - disagree on decrypt → the entire historical note corpus becomes unreadable
+ *
+ * Three details are easy to get wrong and are individually fatal:
+ *
+ *  1. The KDF is `nacl.hash(x).slice(0, 32)` — **truncated SHA-512**, despite the
+ *     sibling helper being named `sha256ForNotes`. See `kdfSHA512_256` in utxo.ts.
+ *  2. The ephemeral key published on-chain is **Ed25519**; it is converted to
+ *     X25519 only for the Diffie-Hellman. Scanners convert it back.
+ *  3. `viewTag` is the first byte of the hash of the **raw shared secret**, not of
+ *     the derived key. A wrong view tag makes every note invisible to the scan
+ *     loop, which rejects ~255/256 candidates on this byte alone.
+ *
+ * The ECDH primitives are imported from `utxo.ts` rather than reimplemented — a
+ * fifth independent Edwards→Montgomery implementation is exactly how the current
+ * drift risk between the four siblings arose.
+ *
+ * Verified against the siblings by `tests/compact-note.test.ts` (golden vectors)
+ * and `scripts/verify-compact-cipher-parity.mjs` (differential).
+ */
+/** Size of the on-chain compact blob: nonce[24] || secretbox(40-byte plaintext)[56]. */
+export declare const COMPACT_BLOB_LENGTH = 80;
+export type CompactNoteCipher = {
+    /** Ed25519 ephemeral public key, published on-chain. */
+    ephemeralPublicKey: Uint8Array;
+    /** 80 bytes: nonce[24] || ciphertext[56]. */
+    compactBlob: Uint8Array;
+    /** 1-byte scan filter. */
+    viewTag: number;
+};
+/** The optional pair of compact note ciphers carried by `transact` instructions. */
+export type NoteCiphers = {
+    note0EphemeralKey: Uint8Array;
+    note0Encrypted: Uint8Array;
+    note0ViewTag: number;
+    note1EphemeralKey: Uint8Array;
+    note1Encrypted: Uint8Array;
+    note1ViewTag: number;
+};
+/** Plaintext note material needed to create one compact on-chain cipher. */
+export type NoteCipherInput = {
+    recipientWalletPubkey: Uint8Array;
+    blinding: Uint8Array;
+    amount: bigint;
+};
+/**
+ * Test-only determinism hook. NOT part of the public contract — it exists so
+ * golden vectors can pin exact bytes against the sibling implementations, which
+ * is the only way to prove byte-compatibility rather than assume it.
+ *
+ * @internal
+ */
+export type CompactNoteDeterminism = {
+    ephemeralSeed: Uint8Array;
+    nonce: Uint8Array;
+};
+/**
+ * Encrypt a note's secret material to a recipient's Solana wallet key.
+ *
+ * The recipient does not need to be the signer of the transaction, or to have
+ * any prior relationship with the sender — this is what makes shielding to an
+ * arbitrary owner possible.
+ *
+ * @param recipientWalletPubkey 32-byte Ed25519 Solana wallet public key
+ * @param blinding              32-byte big-endian blinding factor
+ * @param amount                note amount in base units
+ */
+export declare function createCompactNoteCipher(recipientWalletPubkey: Uint8Array, blinding: Uint8Array, amount: bigint, 
+/** @internal */ __det?: CompactNoteDeterminism): CompactNoteCipher;
+/**
+ * Recover a note's blinding and amount from an on-chain compact cipher.
+ *
+ * Returns `null` when the blob was not encrypted to this key — the expected
+ * outcome for the overwhelming majority of candidates during a scan, so callers
+ * should filter on `viewTag` first (see {@link matchesViewTag}) and only attempt
+ * decryption on the ~1/256 that survive.
+ *
+ * @param walletSecretKey 32-byte Ed25519 seed or 64-byte secret key
+ */
+export declare function decryptCompactNoteCipher(walletSecretKey: Uint8Array, ephemeralPublicKey: Uint8Array, compactBlob: Uint8Array, precomputed?: {
+    sharedSecret?: Uint8Array;
+    x25519Private?: Uint8Array;
+}): {
+    blinding: Uint8Array;
+    amount: bigint;
+} | null;
+/**
+ * Cheap scan filter: does this on-chain cipher plausibly belong to us?
+ *
+ * Rejects ~255/256 candidates for the cost of one scalar multiplication and one
+ * hash, versus a full secretbox open. Hoist `x25519Private` across a scan loop
+ * with {@link toX25519Private}.
+ */
+export declare function matchesViewTag(walletSecretKey: Uint8Array, ephemeralPublicKey: Uint8Array, viewTag: number, precomputed?: {
+    x25519Private?: Uint8Array;
+}): {
+    matches: boolean;
+    sharedSecret: Uint8Array;
+};
+/**
+ * Convert an Ed25519 wallet secret key to its X25519 scalar once, for reuse
+ * across a scan loop.
+ */
+export declare function toX25519Private(walletSecretKey: Uint8Array): Uint8Array;
+/** The all-zero cipher the program treats as "no note here". */
+export declare function emptyNoteCipher(): CompactNoteCipher;
+/**
+ * Build the two-note payload accepted by `transact` and `transact_swap`.
+ * A missing side is encoded with the program's all-zero sentinel. If both
+ * sides are missing, `null` is returned so Anchor encodes `Option::None`.
+ */
+export declare function createNoteCiphers(note0: NoteCipherInput | null, note1: NoteCipherInput | null): NoteCiphers | null;

package/dist/esm/compactNote.js

@@ -0,0 +1,179 @@
+import nacl from "tweetnacl";
+import { ed25519PublicKeyToX25519, ed25519SeedToX25519Private, kdfSHA512_256, } from "./notes/mailbox.js";
+import { randomBytes } from "./random.js";
+/**
+ * Compact note ciphers — the 80-byte payload carried inside the on-chain
+ * `transact` instruction (`note_ciphers: Option<NoteCiphers>`) and re-emitted in
+ * `CommitmentEvent`.
+ *
+ * This is what makes a note recoverable from chain data alone: a recipient who
+ * was never told about a deposit can still find it by scanning `view_tag` and
+ * decrypting the blob. Without it, note delivery depends on someone calling the
+ * relayer, which a third-party integrator cannot be trusted to do.
+ *
+ * ## Byte-compatibility is load-bearing
+ *
+ * Four sibling implementations already exist (relayer-server, extension ×2,
+ * wallet-app). This is the canonical one, and it MUST agree with them byte for
+ * byte in both directions:
+ *
+ *   - disagree on encrypt → new notes are invisible to every existing client
+ *   - disagree on decrypt → the entire historical note corpus becomes unreadable
+ *
+ * Three details are easy to get wrong and are individually fatal:
+ *
+ *  1. The KDF is `nacl.hash(x).slice(0, 32)` — **truncated SHA-512**, despite the
+ *     sibling helper being named `sha256ForNotes`. See `kdfSHA512_256` in utxo.ts.
+ *  2. The ephemeral key published on-chain is **Ed25519**; it is converted to
+ *     X25519 only for the Diffie-Hellman. Scanners convert it back.
+ *  3. `viewTag` is the first byte of the hash of the **raw shared secret**, not of
+ *     the derived key. A wrong view tag makes every note invisible to the scan
+ *     loop, which rejects ~255/256 candidates on this byte alone.
+ *
+ * The ECDH primitives are imported from `utxo.ts` rather than reimplemented — a
+ * fifth independent Edwards→Montgomery implementation is exactly how the current
+ * drift risk between the four siblings arose.
+ *
+ * Verified against the siblings by `tests/compact-note.test.ts` (golden vectors)
+ * and `scripts/verify-compact-cipher-parity.mjs` (differential).
+ */
+/** Size of the on-chain compact blob: nonce[24] || secretbox(40-byte plaintext)[56]. */
+export const COMPACT_BLOB_LENGTH = 80;
+/** Plaintext layout: blinding[32] || amount as little-endian u64[8]. */
+const COMPACT_PLAINTEXT_LENGTH = 40;
+const NONCE_LENGTH = 24;
+/**
+ * Encrypt a note's secret material to a recipient's Solana wallet key.
+ *
+ * The recipient does not need to be the signer of the transaction, or to have
+ * any prior relationship with the sender — this is what makes shielding to an
+ * arbitrary owner possible.
+ *
+ * @param recipientWalletPubkey 32-byte Ed25519 Solana wallet public key
+ * @param blinding              32-byte big-endian blinding factor
+ * @param amount                note amount in base units
+ */
+export function createCompactNoteCipher(recipientWalletPubkey, blinding, amount, 
+/** @internal */ __det) {
+    if (recipientWalletPubkey.length !== 32) {
+        throw new Error(`recipientWalletPubkey must be 32 bytes, got ${recipientWalletPubkey.length}`);
+    }
+    if (blinding.length < 32) {
+        throw new Error(`blinding must be at least 32 bytes, got ${blinding.length}`);
+    }
+    if (amount < 0n || amount > 0xffffffffffffffffn) {
+        throw new Error(`amount ${amount} does not fit in a u64`);
+    }
+    // Ed25519 ephemeral keypair. `nacl.sign.keyPair.fromSeed(seed)` produces the
+    // same public key as web3.js `Keypair.generate()` for the same seed, which is
+    // what the sibling implementations use — but without pulling @solana/web3.js
+    // into the crypto path.
+    const ephemeralSeed = __det?.ephemeralSeed ?? randomBytes(32);
+    const ephemeralPublicKey = nacl.sign.keyPair.fromSeed(ephemeralSeed).publicKey;
+    const sharedSecret = deriveSharedSecret(ephemeralSeed, recipientWalletPubkey);
+    const key = kdfSHA512_256(sharedSecret);
+    const plaintext = new Uint8Array(COMPACT_PLAINTEXT_LENGTH);
+    plaintext.set(blinding.slice(0, 32), 0);
+    let amt = amount;
+    for (let i = 0; i < 8; i++) {
+        plaintext[32 + i] = Number(amt & 0xffn);
+        amt >>= 8n;
+    }
+    const nonce = __det?.nonce ?? nacl.randomBytes(NONCE_LENGTH);
+    const encrypted = nacl.secretbox(plaintext, nonce, key);
+    const compactBlob = new Uint8Array(COMPACT_BLOB_LENGTH);
+    compactBlob.set(nonce, 0);
+    compactBlob.set(encrypted, NONCE_LENGTH);
+    // First byte of the hash of the RAW shared secret — not of `key`.
+    const viewTag = nacl.hash(sharedSecret)[0];
+    return { ephemeralPublicKey, compactBlob, viewTag };
+}
+/**
+ * Recover a note's blinding and amount from an on-chain compact cipher.
+ *
+ * Returns `null` when the blob was not encrypted to this key — the expected
+ * outcome for the overwhelming majority of candidates during a scan, so callers
+ * should filter on `viewTag` first (see {@link matchesViewTag}) and only attempt
+ * decryption on the ~1/256 that survive.
+ *
+ * @param walletSecretKey 32-byte Ed25519 seed or 64-byte secret key
+ */
+export function decryptCompactNoteCipher(walletSecretKey, ephemeralPublicKey, compactBlob, precomputed) {
+    if (compactBlob.length !== COMPACT_BLOB_LENGTH)
+        return null;
+    const sharedSecret = precomputed?.sharedSecret ??
+        (precomputed?.x25519Private
+            ? nacl.scalarMult(precomputed.x25519Private, ed25519PublicKeyToX25519(ephemeralPublicKey))
+            : deriveSharedSecret(walletSecretKey, ephemeralPublicKey));
+    const key = kdfSHA512_256(sharedSecret);
+    const nonce = compactBlob.slice(0, NONCE_LENGTH);
+    const encrypted = compactBlob.slice(NONCE_LENGTH);
+    const plaintext = nacl.secretbox.open(encrypted, nonce, key);
+    if (!plaintext)
+        return null;
+    const blinding = new Uint8Array(plaintext.slice(0, 32));
+    let amount = 0n;
+    for (let i = 7; i >= 0; i--) {
+        amount = (amount << 8n) | BigInt(plaintext[32 + i]);
+    }
+    return { blinding, amount };
+}
+/**
+ * Cheap scan filter: does this on-chain cipher plausibly belong to us?
+ *
+ * Rejects ~255/256 candidates for the cost of one scalar multiplication and one
+ * hash, versus a full secretbox open. Hoist `x25519Private` across a scan loop
+ * with {@link toX25519Private}.
+ */
+export function matchesViewTag(walletSecretKey, ephemeralPublicKey, viewTag, precomputed) {
+    const sharedSecret = precomputed?.x25519Private
+        ? nacl.scalarMult(precomputed.x25519Private, ed25519PublicKeyToX25519(ephemeralPublicKey))
+        : deriveSharedSecret(walletSecretKey, ephemeralPublicKey);
+    return { matches: nacl.hash(sharedSecret)[0] === viewTag, sharedSecret };
+}
+/**
+ * Convert an Ed25519 wallet secret key to its X25519 scalar once, for reuse
+ * across a scan loop.
+ */
+export function toX25519Private(walletSecretKey) {
+    return ed25519SeedToX25519Private(seedOf(walletSecretKey));
+}
+/** The all-zero cipher the program treats as "no note here". */
+export function emptyNoteCipher() {
+    return {
+        ephemeralPublicKey: new Uint8Array(32),
+        compactBlob: new Uint8Array(COMPACT_BLOB_LENGTH),
+        viewTag: 0,
+    };
+}
+/**
+ * Build the two-note payload accepted by `transact` and `transact_swap`.
+ * A missing side is encoded with the program's all-zero sentinel. If both
+ * sides are missing, `null` is returned so Anchor encodes `Option::None`.
+ */
+export function createNoteCiphers(note0, note1) {
+    if (!note0 && !note1)
+        return null;
+    const cipher0 = note0
+        ? createCompactNoteCipher(note0.recipientWalletPubkey, note0.blinding, note0.amount)
+        : emptyNoteCipher();
+    const cipher1 = note1
+        ? createCompactNoteCipher(note1.recipientWalletPubkey, note1.blinding, note1.amount)
+        : emptyNoteCipher();
+    return {
+        note0EphemeralKey: cipher0.ephemeralPublicKey,
+        note0Encrypted: cipher0.compactBlob,
+        note0ViewTag: cipher0.viewTag,
+        note1EphemeralKey: cipher1.ephemeralPublicKey,
+        note1Encrypted: cipher1.compactBlob,
+        note1ViewTag: cipher1.viewTag,
+    };
+}
+// -- internal -----------------------------------------------------------------
+/** Accept either a 32-byte Ed25519 seed or a 64-byte secret key, as the siblings do. */
+function seedOf(secretKey) {
+    return secretKey.length === 64 ? secretKey.slice(0, 32) : secretKey;
+}
+function deriveSharedSecret(mySecretKey, theirEd25519PublicKey) {
+    return nacl.scalarMult(ed25519SeedToX25519Private(seedOf(mySecretKey)), ed25519PublicKeyToX25519(theirEd25519PublicKey));
+}

package/dist/esm/config.d.ts

@@ -0,0 +1,82 @@
+import { PublicKey } from "@solana/web3.js";
+/** Default relayer fee in basis points (50 = 0.5%). */
+export declare const DEFAULT_FEE_BPS = 50;
+/** Merkle tree depth - matches on-chain MerkleTreeAccount subtrees array size */
+export declare const MERKLE_TREE_DEPTH = 22;
+/** Root history size - matches on-chain MerkleTreeAccount root_history array size */
+export declare const ROOT_HISTORY_SIZE = 256;
+/** Native SOL mint address (Pubkey::default() = all zeros) */
+export declare const NATIVE_SOL_MINT: PublicKey;
+/** Convert SOL to lamports (e.g. `sol(1.5)` → `1_500_000_000n`). */
+export declare function sol(n: number): bigint;
+/** Configuration for initializing a privacy pool */
+export type PoolInitConfig = {
+    /** Fee in basis points (0-10000, where 10000 = 100%) */
+    feeBps?: number;
+    /** Token mint address (use NATIVE_SOL_MINT for SOL pools) */
+    mintAddress: PublicKey;
+    /** Minimum deposit amount in lamports/token units */
+    minDepositAmount?: bigint;
+    /** Maximum deposit amount in lamports/token units */
+    maxDepositAmount?: bigint;
+    /** Minimum withdrawal amount in lamports/token units */
+    minWithdrawAmount?: bigint;
+    /** Maximum withdrawal amount in lamports/token units */
+    maxWithdrawAmount?: bigint;
+};
+/** On-chain PrivacyConfig account structure */
+export type PrivacyConfigAccount = {
+    bump: number;
+    vaultBump: number;
+    admin: PublicKey;
+    feeBps: number;
+    feeErrorMarginBps: number;
+    minWithdrawalFee: bigint;
+    /** Minimum fee kept by relayer on swaps (in destination token base units) */
+    minSwapFee: bigint;
+    /** Fee rate applied to swap output in basis points */
+    swapFeeBps: number;
+    totalTvl: bigint;
+    mintAddress: PublicKey;
+    minDepositAmount: bigint;
+    maxDepositAmount: bigint;
+    minWithdrawAmount: bigint;
+    maxWithdrawAmount: bigint;
+    numRelayers: number;
+    relayers: PublicKey[];
+    numTrees: number;
+    nextTreeIndex: number;
+};
+/** On-chain GlobalConfig account structure */
+export type GlobalConfigAccount = {
+    bump: number;
+    admin: PublicKey;
+    relayerEnabled: boolean;
+};
+/**
+ * Compute the relayer fee for a withdrawal.
+ * Mirrors the formula in the relayer-server:
+ *   fee = max(amount * feeBps / 10_000, minWithdrawalFee)
+ *
+ * @returns fee in base token units, and the amount that reaches the recipient
+ */
+export declare function computeWithdrawalFee(amount: bigint, feeBps: number, minWithdrawalFee: bigint): {
+    fee: bigint;
+    toRecipient: bigint;
+};
+/**
+ * Compute the relayer fee for a cross-pool swap.
+ * Mirrors the formula in the relayer-server:
+ *   relayerFee = max(estimatedOutput * swapFeeBps / 10_000, minSwapFee)
+ *   destAmount  = minAmountOut - relayerFee
+ *
+ * @param estimatedOutput  Jupiter quote output amount
+ * @param swapFeeBps       From the destination pool's PrivacyConfigAccount
+ * @param minSwapFee       From the destination pool's PrivacyConfigAccount
+ * @param minAmountOut     User-agreed minimum swap output (after slippage)
+ * @returns relayerFee and the amount committed into the destination UTXO
+ */
+export declare function computeSwapFee(estimatedOutput: bigint, swapFeeBps: number, minSwapFee: bigint, minAmountOut: bigint): {
+    relayerFee: bigint;
+    destAmount: bigint;
+};

package/dist/esm/events.d.ts

@@ -0,0 +1,77 @@
+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;
+}>;

package/dist/esm/events.js

@@ -1,5 +1,5 @@
 import * as anchor from "@coral-xyz/anchor";
-import { MerkleTree } from "./merkle";
+import { MerkleTree } from "./merkle.js";
 // -----------------------------------------------------------------------------
 // Event Scanning
 // -----------------------------------------------------------------------------

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

@@ -0,0 +1,5 @@
+import type { Idl } from "@coral-xyz/anchor";
+declare const IDL_JSON: Idl & {
+    address: string;
+};
+export default IDL_JSON;