@veilo/sdk-core 0.1.17 → 0.3.3

package/dist/esm/relayer.js

@@ -0,0 +1,238 @@
+import nacl from "tweetnacl";
+// =============================================================================
+// Structured Error
+// =============================================================================
+/** Structured error thrown by VeiloRelayerClient on API failures. */
+export class VeiloApiError extends Error {
+    constructor(code, message, status) {
+        super(message);
+        this.name = "VeiloApiError";
+        this.code = code;
+        this.status = status;
+    }
+}
+const DEFAULT_RETRY = {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    retryableStatuses: [429, 502, 503, 504],
+};
+// =============================================================================
+// Base64 helpers (no dependency on tweetnacl-util)
+// =============================================================================
+function toBase64(bytes) {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(bytes).toString("base64");
+    }
+    return btoa(String.fromCharCode(...bytes));
+}
+function fromBase64(str) {
+    if (typeof Buffer !== "undefined") {
+        return new Uint8Array(Buffer.from(str, "base64"));
+    }
+    const binary = atob(str);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+// =============================================================================
+// Encryption
+// =============================================================================
+/**
+ * Encrypt a JSON-serializable payload for the relayer using NaCl box.
+ * Layout: [ephemeralPubKey (32)] [nonce (24)] [ciphertext (...)]
+ */
+function encryptForRelayer(data, relayerPublicKey) {
+    const ephemeral = nacl.box.keyPair();
+    const message = new TextEncoder().encode(JSON.stringify(data));
+    const nonce = nacl.randomBytes(nacl.box.nonceLength);
+    const ciphertext = nacl.box(message, nonce, relayerPublicKey, ephemeral.secretKey);
+    const payload = new Uint8Array(ephemeral.publicKey.length + nonce.length + ciphertext.length);
+    payload.set(ephemeral.publicKey, 0);
+    payload.set(nonce, ephemeral.publicKey.length);
+    payload.set(ciphertext, ephemeral.publicKey.length + nonce.length);
+    return toBase64(payload);
+}
+// =============================================================================
+// Relayer Client
+// =============================================================================
+/**
+ * HTTP client for the Veilo relayer API.
+ *
+ * Handles auth, notes, merkle, and encrypted transact endpoints with
+ * automatic retry on transient failures and NaCl box payload encryption.
+ *
+ * @example
+ * ```ts
+ * const client = new VeiloRelayerClient({
+ *   relayerUrl: "https://relayer.veilo.io",
+ *   apiKey: "your-api-key",
+ *   relayerPublicKey: "<base64 NaCl public key>",
+ * });
+ * const root = await client.getMerkleRoot("So111...");
+ * ```
+ */
+export class VeiloRelayerClient {
+    constructor(config, retry) {
+        this.baseUrl = config.relayerUrl.replace(/\/+$/, "");
+        this.apiKey = config.apiKey;
+        this.relayerPubKey = fromBase64(config.relayerPublicKey);
+        this.authToken = config.authToken;
+        this.retry = { ...DEFAULT_RETRY, ...retry };
+    }
+    /** Update the auth token (e.g. after register/restore). */
+    setAuthToken(token) {
+        this.authToken = token;
+    }
+    // ---------------------------------------------------------------------------
+    // Internal helpers
+    // ---------------------------------------------------------------------------
+    headers(authenticated) {
+        const h = {
+            "Content-Type": "application/json",
+            "x-api-key": this.apiKey,
+        };
+        if (authenticated && this.authToken) {
+            h["Authorization"] = `Bearer ${this.authToken}`;
+        }
+        return h;
+    }
+    async request(method, path, opts = {}) {
+        const url = `${this.baseUrl}/api${path}`;
+        const { body, authenticated = false, retryable = true } = opts;
+        const maxAttempts = retryable ? this.retry.maxRetries + 1 : 1;
+        let lastError;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            if (attempt > 0) {
+                const delay = this.retry.baseDelayMs * Math.pow(2, attempt - 1) +
+                    Math.random() * 200;
+                await new Promise((r) => setTimeout(r, delay));
+            }
+            let res;
+            try {
+                res = await fetch(url, {
+                    method,
+                    headers: this.headers(authenticated),
+                    body: body != null ? JSON.stringify(body) : undefined,
+                });
+            }
+            catch (err) {
+                lastError = new VeiloApiError("NETWORK_ERROR", err.message || "Network request failed", 0);
+                continue;
+            }
+            const data = await res.json().catch(() => ({}));
+            if (res.ok && data.success !== false) {
+                return data;
+            }
+            lastError = new VeiloApiError(data.error || "UNKNOWN", data.message || data.error || `Request failed: ${res.status}`, res.status);
+            // Only retry on transient statuses
+            if (!this.retry.retryableStatuses.includes(res.status)) {
+                throw lastError;
+            }
+        }
+        throw lastError;
+    }
+    encrypt(data) {
+        return encryptForRelayer({
+            ...data,
+            timestamp: Date.now(),
+            nonce: toBase64(nacl.randomBytes(32)),
+        }, this.relayerPubKey);
+    }
+    // ---------------------------------------------------------------------------
+    // Auth
+    // ---------------------------------------------------------------------------
+    /** Request a signature challenge for wallet authentication. */
+    async getChallenge(walletPublicKey) {
+        return this.request("POST", "/auth/challenge", {
+            body: { walletPublicKey },
+        });
+    }
+    /** Register a new account with a signed challenge. Returns a JWT auth token. */
+    async register(data) {
+        return this.request("POST", "/auth/register", { body: data });
+    }
+    /** Restore an existing account using a signed challenge. Returns a JWT auth token. */
+    async restore(data) {
+        return this.request("POST", "/auth/restore", { body: data });
+    }
+    /** Check whether a username is available for registration. */
+    async checkUsername(username) {
+        return this.request("GET", `/auth/checkUsername?username=${encodeURIComponent(username)}`);
+    }
+    /** Look up a user's Veilo public key by username or wallet public key. */
+    async getVeiloPublicKey(params) {
+        const query = "username" in params && params.username
+            ? `username=${encodeURIComponent(params.username)}`
+            : `publicKey=${encodeURIComponent(params.publicKey)}`;
+        return this.request("GET", `/auth/veiloPublicKey?${query}`);
+    }
+    // ---------------------------------------------------------------------------
+    // Notes
+    // ---------------------------------------------------------------------------
+    /** Save an encrypted note to the relayer's database. */
+    async saveEncryptedNote(data) {
+        return this.request("POST", "/notes/save", { body: data });
+    }
+    /** Query encrypted notes for the authenticated user. Requires auth token. */
+    async queryEncryptedNotes(params = {}) {
+        return this.request("POST", "/notes/query", {
+            body: params,
+            authenticated: true,
+        });
+    }
+    /** Delete all stored data for the authenticated user. Requires auth token. */
+    async deleteUserData() {
+        return this.request("POST", "/notes/delete", { authenticated: true });
+    }
+    // ---------------------------------------------------------------------------
+    // Merkle
+    // ---------------------------------------------------------------------------
+    /** Fetch the current Merkle root for a pool, optionally filtered by mint and tree ID. */
+    async getMerkleRoot(mintAddress, treeId) {
+        const params = new URLSearchParams();
+        if (mintAddress)
+            params.append("mintAddress", mintAddress);
+        if (treeId !== undefined)
+            params.append("treeId", treeId.toString());
+        const qs = params.toString();
+        return this.request("GET", `/merkle/root${qs ? `?${qs}` : ""}`);
+    }
+    /** Fetch the full Merkle tree (all leaves) for a pool. */
+    async getMerkleTree(mintAddress, treeId) {
+        const params = new URLSearchParams();
+        if (mintAddress)
+            params.append("mintAddress", mintAddress);
+        if (treeId !== undefined)
+            params.append("treeId", treeId.toString());
+        const qs = params.toString();
+        return this.request("GET", `/merkle/tree${qs ? `?${qs}` : ""}`);
+    }
+    // ---------------------------------------------------------------------------
+    // Transact (encrypted payloads)
+    // ---------------------------------------------------------------------------
+    /** Submit an encrypted withdrawal request to the relayer. Not retried on failure. */
+    async submitWithdraw(data) {
+        const encryptedPayload = this.encrypt(data);
+        return this.request("POST", "/transact/withdra", {
+            body: { encryptedPayload },
+            retryable: false,
+        });
+    }
+    /** Submit an encrypted private transfer request. Not retried on failure. */
+    async submitPrivateTransfer(data) {
+        const encryptedPayload = this.encrypt(data);
+        return this.request("POST", "/transact/private-transfer", {
+            body: { encryptedPayload },
+            retryable: false,
+        });
+    }
+    /** Submit an encrypted private swap request. Not retried on failure. */
+    async submitPrivateSwap(data) {
+        const encryptedPayload = this.encrypt(data);
+        return this.request("POST", "/transact/private-swap", {
+            body: { encryptedPayload },
+            retryable: false,
+        });
+    }
+}

package/dist/esm/retry.js

@@ -0,0 +1,71 @@
+// -----------------------------------------------------------------------------
+// RPC Retry / Resilience
+// -----------------------------------------------------------------------------
+export const DEFAULT_RPC_RETRY = {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 10000,
+};
+/** Error messages / patterns that indicate a transient RPC failure worth retrying. */
+const RETRYABLE_PATTERNS = [
+    "blockhash not found",
+    "block height exceeded",
+    "blockhash already expired",
+    "node is behind",
+    "service unavailable",
+    "too many requests",
+    "429",
+    "502",
+    "503",
+    "504",
+    "timeout",
+    "timed out",
+    "econnreset",
+    "econnrefused",
+    "socket hang up",
+    "fetch failed",
+];
+function isRetryableError(error) {
+    const msg = (error instanceof Error ? error.message : String(error)).toLowerCase();
+    return RETRYABLE_PATTERNS.some((p) => msg.includes(p));
+}
+/**
+ * Execute an async function with retries on transient RPC failures.
+ *
+ * Retries on: BlockhashNotFound, HTTP 429/502/503/504, timeouts, connection resets.
+ * Does NOT retry on: program errors (6xxx), signature verification failures, or other
+ * deterministic errors that would fail again.
+ *
+ * @param fn      The async operation to execute
+ * @param policy  Retry configuration (uses sensible defaults if omitted)
+ * @returns       The result of the async operation
+ *
+ * @example
+ * ```ts
+ * const txSig = await withRpcRetry(
+ *   () => program.methods.transact(...).accounts({...}).signers([...]).rpc(),
+ *   { maxRetries: 5 },
+ * );
+ * ```
+ */
+export async function withRpcRetry(fn, policy) {
+    const { maxRetries, baseDelayMs, maxDelayMs } = {
+        ...DEFAULT_RPC_RETRY,
+        ...policy,
+    };
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= maxRetries || !isRetryableError(error)) {
+                throw error;
+            }
+            const delay = Math.min(baseDelayMs * Math.pow(2, attempt) + Math.random() * 200, maxDelayMs);
+            await new Promise((r) => setTimeout(r, delay));
+        }
+    }
+    throw lastError;
+}

package/dist/esm/utxo.js

@@ -0,0 +1,372 @@
+import { randomBytes } from "crypto";
+import nacl from "tweetnacl";
+import { sha256 } from "@noble/hashes/sha256";
+import { BN254_FR_MODULUS, bigIntToBytesBE, bytesToBigIntBE, poseidon1, poseidon3, poseidon4, pubkeyToField, } from "./poseidon";
+// -----------------------------------------------------------------------------
+// Keypair Functions
+// -----------------------------------------------------------------------------
+/**
+ * Generate a random keypair.
+ * Private key is a random 32-byte scalar.
+ * Public key is derived via Poseidon: pubkey = Poseidon(privateKey)
+ */
+export function generateKeypair() {
+    const privateKeyBytes = new Uint8Array(randomBytes(32));
+    const privateKey = bytesToBigIntBE(privateKeyBytes) % BN254_FR_MODULUS;
+    const publicKey = derivePublicKey(privateKey);
+    return { privateKey, publicKey };
+}
+/**
+ * Derive public key from private key.
+ * Matches circuit's Keypair template: publicKey = Poseidon(privateKey)
+ */
+export function derivePublicKey(privateKey) {
+    return poseidon1(privateKey);
+}
+/**
+ * Create keypair from a known private key.
+ */
+export function keypairFromPrivateKey(privateKey) {
+    return {
+        privateKey: privateKey % BN254_FR_MODULUS,
+        publicKey: derivePublicKey(privateKey % BN254_FR_MODULUS),
+    };
+}
+// -----------------------------------------------------------------------------
+// UTXO Commitment Functions
+// -----------------------------------------------------------------------------
+/**
+ * Compute UTXO commitment.
+ * Matches circuit's UTXOCommitment template:
+ *   commitment = Poseidon(amount, pubkey, blinding, mintAddress)
+ */
+export function commitUTXO(utxo) {
+    const commitment = poseidon4(utxo.amount, utxo.pubkey, utxo.blinding, utxo.mintAddress);
+    return bigIntToBytesBE(commitment);
+}
+/**
+ * Create a random UTXO with the given parameters.
+ */
+export function createUTXO(params) {
+    const blindingBytes = new Uint8Array(randomBytes(32));
+    const blinding = bytesToBigIntBE(blindingBytes) % BN254_FR_MODULUS;
+    const utxo = {
+        amount: params.amount,
+        pubkey: params.pubkey,
+        blinding,
+        mintAddress: pubkeyToField(params.mintAddress),
+    };
+    const commitment = commitUTXO(utxo);
+    return {
+        ...utxo,
+        commitment,
+    };
+}
+/**
+ * Create a UTXO with a specified private key (for owned UTXOs).
+ */
+export function createOwnedUTXO(params) {
+    const keypair = keypairFromPrivateKey(params.privateKey);
+    const utxo = createUTXO({
+        amount: params.amount,
+        pubkey: keypair.publicKey,
+        mintAddress: params.mintAddress,
+    });
+    return {
+        ...utxo,
+        privateKey: keypair.privateKey,
+    };
+}
+/**
+ * Create a zero UTXO (for deposits where no input exists).
+ * Zero UTXOs have amount=0 and are used as placeholders in 2-in-2-out transactions.
+ */
+export function createZeroUTXO(pubkey, mintAddress) {
+    return createUTXO({
+        amount: 0n,
+        pubkey,
+        mintAddress,
+    });
+}
+/**
+ * Create a zero UTXO with private key (for owned zero UTXOs).
+ */
+export function createOwnedZeroUTXO(privateKey, mintAddress) {
+    const keypair = keypairFromPrivateKey(privateKey);
+    const utxo = createZeroUTXO(keypair.publicKey, mintAddress);
+    return {
+        ...utxo,
+        privateKey: keypair.privateKey,
+    };
+}
+// -----------------------------------------------------------------------------
+// Nullifier Functions
+// -----------------------------------------------------------------------------
+/**
+ * Compute signature for nullifier derivation.
+ * Matches circuit's Signature template:
+ *   signature = Poseidon(privateKey, commitment, pathIndex)
+ */
+export function computeSignature(privateKey, commitment, pathIndex) {
+    return poseidon3(privateKey, commitment, pathIndex);
+}
+/**
+ * Derive nullifier for a UTXO.
+ * Matches circuit's UTXONullifier template:
+ *   signature = Poseidon(privateKey, commitment, pathIndex)
+ *   nullifier = Poseidon(commitment, pathIndex, signature)
+ *
+ * The signature-based nullifier ensures only the private key holder can spend.
+ */
+export function deriveNullifier(utxo, pathIndex, privateKey) {
+    const commitment = bytesToBigIntBE(utxo.commitment) % BN254_FR_MODULUS;
+    const pathIndexField = BigInt(pathIndex) % BN254_FR_MODULUS;
+    const signature = computeSignature(privateKey, commitment, pathIndexField);
+    const nullifier = poseidon3(commitment, pathIndexField, signature);
+    return bigIntToBytesBE(nullifier);
+}
+/**
+ * Convert InputUTXO to the format expected by the circuit.
+ */
+export function inputUTXOToCircuitFormat(input) {
+    return {
+        amount: input.amount,
+        pubkey: input.pubkey,
+        blinding: input.blinding,
+        pathElements: input.pathElements.map((e) => bytesToBigIntBE(e) % BN254_FR_MODULUS),
+        pathIndex: input.pathIndex,
+        privateKey: input.privateKey,
+    };
+}
+/**
+ * Derive a NaCl X25519 encryption keypair from a UTXO private key.
+ * The keypair is deterministic: same privateKey always yields the same pair.
+ */
+export function deriveEncryptionKeypair(privateKey) {
+    const seed = sha256(bigIntToBytesBE(privateKey));
+    return nacl.box.keyPair.fromSecretKey(seed);
+}
+/**
+ * Encrypt a UTXO so the recipient can recover it from on-chain events.
+ *
+ * Plaintext layout (72 bytes):
+ *   [0..8]   amount  — 8-byte little-endian u64
+ *   [8..40]  blinding — 32-byte big-endian field element
+ *   [40..72] privateKey — 32-byte big-endian field element
+ *
+ * Uses ephemeral-key NaCl box so the sender key is single-use.
+ */
+export function encryptUTXONote(utxo, recipientEncPubkey) {
+    const nonce = nacl.randomBytes(nacl.box.nonceLength); // 24 bytes
+    const ephemeral = nacl.box.keyPair();
+    const amountBuf = new Uint8Array(8);
+    let v = utxo.amount;
+    for (let i = 0; i < 8; i++) {
+        amountBuf[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    const plaintext = new Uint8Array(72);
+    plaintext.set(amountBuf, 0);
+    plaintext.set(bigIntToBytesBE(utxo.blinding), 8);
+    plaintext.set(bigIntToBytesBE(utxo.privateKey), 40);
+    const sharedKey = nacl.box.before(recipientEncPubkey, ephemeral.secretKey);
+    const ciphertext = nacl.box.after(plaintext, nonce, sharedKey);
+    return { nonce, ciphertext, senderEphemeralPubkey: ephemeral.publicKey };
+}
+/**
+ * Try to decrypt an encrypted UTXO note using the recipient's private key.
+ * Returns the SerializedUTXO if decryption succeeds and the commitment
+ * matches, or `null` if the note was not intended for this key.
+ */
+export function decryptUTXONote(note, recipientPrivateKey, commitment, mintAddress) {
+    const { secretKey } = deriveEncryptionKeypair(recipientPrivateKey);
+    const sharedKey = nacl.box.before(note.senderEphemeralPubkey, secretKey);
+    const plaintext = nacl.box.open.after(note.ciphertext, note.nonce, sharedKey);
+    if (!plaintext || plaintext.length < 72)
+        return null;
+    let amount = 0n;
+    for (let i = 7; i >= 0; i--)
+        amount = (amount << 8n) | BigInt(plaintext[i]);
+    const blinding = bytesToBigIntBE(plaintext.slice(8, 40)) % BN254_FR_MODULUS;
+    const privateKey = bytesToBigIntBE(plaintext.slice(40, 72)) % BN254_FR_MODULUS;
+    const pubkey = derivePublicKey(privateKey);
+    const utxo = {
+        amount,
+        pubkey,
+        blinding,
+        mintAddress: pubkeyToField(mintAddress),
+    };
+    const expectedCommitment = commitUTXO(utxo);
+    if (!expectedCommitment.every((b, i) => b === commitment[i]))
+        return null;
+    return { ...utxo, commitment, privateKey };
+}
+// -- Internal crypto helpers (no extra dependencies) --------------------------
+/** Derive 32-byte encryption key from a shared secret using SHA-512 truncated.
+ *  Must match the production "sha256" helper which uses nacl.hash (SHA-512) [0:32]. */
+function kdfSHA512_256(secret) {
+    return nacl.hash(secret).slice(0, 32);
+}
+/** Convert an Ed25519 private seed (32 bytes) to an X25519 scalar.
+ *  Equivalent to ed2curve.convertSecretKey(seed). */
+function ed25519SeedToX25519Private(seed) {
+    const h = nacl.hash(seed); // SHA-512
+    const scalar = h.slice(0, 32);
+    scalar[0] &= 248;
+    scalar[31] &= 127;
+    scalar[31] |= 64;
+    return scalar;
+}
+const P25519 = (1n << 255n) - 19n;
+function modpow25519(b, e) {
+    let r = 1n;
+    b = b % P25519;
+    while (e > 0n) {
+        if (e & 1n)
+            r = (r * b) % P25519;
+        e >>= 1n;
+        b = (b * b) % P25519;
+    }
+    return r;
+}
+/** Convert an Ed25519 compressed public key (32 bytes) to X25519.
+ *  Equivalent to ed2curve.convertPublicKey(pubkey).
+ *  Edwards y-coord → Montgomery u via: u = (1 + y) / (1 - y) (mod p). */
+function ed25519PublicKeyToX25519(pubkey) {
+    const pk = new Uint8Array(pubkey);
+    pk[31] &= 0x7f; // clear sign bit to get y as LE integer
+    // Decode little-endian y
+    let y = 0n;
+    for (let i = 31; i >= 0; i--)
+        y = (y << 8n) | BigInt(pk[i]);
+    // u = (1 + y) / (1 - y) mod p
+    const num = (1n + y) % P25519;
+    const den = (((1n - y) % P25519) + P25519) % P25519;
+    const u = (num * modpow25519(den, P25519 - 2n)) % P25519;
+    // Encode as 32-byte LE
+    const out = new Uint8Array(32);
+    let v = u;
+    for (let i = 0; i < 32; i++) {
+        out[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    return out;
+}
+// -- Public API ---------------------------------------------------------------
+/**
+ * Encrypt a UTXO note for a recipient identified by their Solana wallet public key.
+ * Produces a blob the relayer will store and serve via POST /notes/save.
+ *
+ * @param recipientWalletPubkey  32-byte Ed25519 public key (wallet.publicKey.toBytes())
+ * @param noteData               UTXO details to encrypt
+ */
+export function encryptBlindMailboxNote(recipientWalletPubkey, noteData) {
+    // 1. Generate ephemeral Ed25519 keypair seed
+    const ephemeralSeed = randomBytes(32);
+    // Ed25519 public key stored by relayer; dapp recovers X25519 via ed2curve.convertPublicKey()
+    const ephemeralEdPublicKey = nacl.sign.keyPair.fromSeed(new Uint8Array(ephemeralSeed)).publicKey;
+    // X25519 scalar (ed2curve.convertSecretKey equivalent)
+    const ephemeralX25519Private = ed25519SeedToX25519Private(new Uint8Array(ephemeralSeed));
+    // X25519 public key (ed2curve.convertPublicKey equivalent)
+    const recipientX25519Public = ed25519PublicKeyToX25519(recipientWalletPubkey);
+    const sharedSecret = nacl.scalarMult(ephemeralX25519Private, recipientX25519Public);
+    const key = kdfSHA512_256(sharedSecret);
+    // JSON format matches production relayer notes schema
+    const hexArr = (b) => Array.from(b)
+        .map((x) => x.toString(16).padStart(2, "0"))
+        .join("");
+    const noteJson = JSON.stringify({
+        blinding: hexArr(noteData.blinding),
+        leafIndex: noteData.leafIndex,
+        commitment: hexArr(noteData.commitment),
+        amount: noteData.amount.toString(),
+        mintAddress: noteData.mintAddress,
+        timestamp: Date.now(),
+        treeId: noteData.treeId,
+    });
+    const nonce = nacl.randomBytes(24);
+    const plaintext = new TextEncoder().encode(noteJson);
+    const encrypted = nacl.secretbox(plaintext, nonce, key);
+    const combined = new Uint8Array(nonce.length + encrypted.length);
+    combined.set(nonce);
+    combined.set(encrypted, nonce.length);
+    const encryptedBlob = Buffer.from(combined).toString("base64");
+    // Return Ed25519 public key (dapp calls ed2curve.convertPublicKey() to recover X25519)
+    return { ephemeralPublicKey: ephemeralEdPublicKey, encryptedBlob };
+}
+/**
+ * Decrypt a Blind Mailbox note using the recipient's Solana wallet private seed.
+ *
+ * @param walletSecretKey  Full 64-byte wallet.secretKey — the first 32 bytes are the seed
+ * @param ephemeralPublicKey  32-byte raw public key stored alongside the encrypted blob.
+ *                            This may be either an Ed25519 pubkey (from Keypair.generate())
+ *                            or a raw X25519 pubkey — the decryption path handles both:
+ *                            if it is an Ed25519 key it is converted; otherwise used directly.
+ * @param encryptedBlob      Base64 string as stored by the relayer
+ */
+export function decryptBlindMailboxNote(walletSecretKey, ephemeralPublicKey, encryptedBlob) {
+    // 1. Derive recipient X25519 from Ed25519 seed
+    const seed = walletSecretKey.slice(0, 32);
+    const myX25519Private = ed25519SeedToX25519Private(seed);
+    // ephemeralPublicKey may be an Ed25519 pubkey (dapp's Keypair.generate()) or raw X25519;
+    // try Ed25519→X25519 conversion first, fall back to using it directly.
+    let theirPublic;
+    try {
+        theirPublic = ed25519PublicKeyToX25519(ephemeralPublicKey);
+    }
+    catch {
+        theirPublic = ephemeralPublicKey; // already X25519
+    }
+    const sharedSecret = nacl.scalarMult(myX25519Private, theirPublic);
+    const key = kdfSHA512_256(sharedSecret);
+    const combined = Buffer.from(encryptedBlob, "base64");
+    const nonce = combined.slice(0, 24);
+    const ciphertext = combined.slice(24);
+    const decrypted = nacl.secretbox.open(new Uint8Array(ciphertext), new Uint8Array(nonce), key);
+    if (!decrypted) {
+        throw new Error("decryptBlindMailboxNote: decryption failed — wrong key or corrupted blob");
+    }
+    const parsed = JSON.parse(new TextDecoder().decode(decrypted));
+    const hexToBytes = (hex) => {
+        const out = new Uint8Array(hex.length / 2);
+        for (let i = 0; i < hex.length; i += 2)
+            out[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+        return out;
+    };
+    return {
+        blinding: hexToBytes(parsed.blinding),
+        leafIndex: parsed.leafIndex,
+        commitment: hexToBytes(parsed.commitment),
+        amount: BigInt(parsed.amount),
+        timestamp: parsed.timestamp ?? 0,
+        mintAddress: parsed.mintAddress,
+        treeId: parsed.treeId,
+    };
+}
+/**
+ * Fetch all encrypted notes for a wallet from the relayer's Blind Mailbox endpoint
+ * and decrypt them using the wallet's secret key.
+ *
+ * @param walletPublicKey  Base58 wallet address used to query the relayer
+ * @param walletSecretKey  Full 64-byte keypair.secretKey for decryption
+ * @param relayerUrl       Relayer base URL (e.g. "https://relay.veilo.app")
+ */
+export async function fetchAndDecryptNotes(walletPublicKey, walletSecretKey, relayerUrl) {
+    const resp = await fetch(`${relayerUrl}/api/notes?recipientPublicKey=${walletPublicKey}`);
+    if (!resp.ok) {
+        throw new Error(`fetchAndDecryptNotes: ${resp.status} ${resp.statusText}`);
+    }
+    const { notes } = (await resp.json());
+    const results = [];
+    for (const note of notes) {
+        try {
+            const epk = Buffer.from(note.ephemeralPublicKey, "base64");
+            const decrypted = decryptBlindMailboxNote(walletSecretKey, new Uint8Array(epk), note.encryptedBlob);
+            results.push(decrypted);
+        }
+        catch {
+            // Note not for this key or corrupted — skip silently
+        }
+    }
+    return results;
+}