@veilo/sdk-core 0.3.3 → 0.5.0

package/dist/cjs/index.d.ts

@@ -1,13 +1,17 @@
-export * from "./client";
-export * from "./utxo";
-export * from "./config";
-export * from "./merkle";
-export * from "./proof";
-export * from "./events";
-export { createVeiloProgram, PRIVACY_POOL_IDL, PRIVACY_POOL_PROGRAM_ID, } from "./program";
-export { createTransactionProver, verifyProof } from "./prover";
-export type { CircuitArtifacts } from "./prover";
-export * from "./relayer";
-export { withRpcRetry, DEFAULT_RPC_RETRY } from "./retry";
-export type { RpcRetryPolicy } from "./retry";
-export { initPoseidon, getPoseidon, BN254_FR_MODULUS, bytesToBigIntBE, bigIntToBytesBE, frToBigInt, poseidon1, poseidon2, poseidon3, poseidon4, pubkeyToField, } from "./poseidon";
+export * from "./client.js";
+export * from "./utxo.js";
+export * from "./config.js";
+export * from "./merkle.js";
+export * from "./proof.js";
+export * from "./events.js";
+export { createVeiloProgram, createReadonlyVeiloProgram, PRIVACY_POOL_IDL, PRIVACY_POOL_PROGRAM_ID, } from "./program.js";
+export * from "./shield/index.js";
+export { createTransactionProver, createSwapProver, verifyProof, } from "./prover.js";
+export type { CircuitArtifacts } from "./prover.js";
+export * from "./compactNote.js";
+export { randomBytes, randomBytes32 } from "./random.js";
+export * from "./relayer.js";
+export * from "./cloak.js";
+export { withRpcRetry, DEFAULT_RPC_RETRY } from "./retry.js";
+export type { RpcRetryPolicy } from "./retry.js";
+export { initPoseidon, getPoseidon, BN254_FR_MODULUS, bytesToBigIntBE, bigIntToBytesBE, frToBigInt, poseidon1, poseidon2, poseidon3, poseidon4, pubkeyToField, } from "./poseidon.js";

package/dist/cjs/index.js

@@ -14,44 +14,57 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.pubkeyToField = exports.poseidon4 = exports.poseidon3 = exports.poseidon2 = exports.poseidon1 = exports.frToBigInt = exports.bigIntToBytesBE = exports.bytesToBigIntBE = exports.BN254_FR_MODULUS = exports.getPoseidon = exports.initPoseidon = exports.DEFAULT_RPC_RETRY = exports.withRpcRetry = exports.verifyProof = exports.createTransactionProver = exports.PRIVACY_POOL_PROGRAM_ID = exports.PRIVACY_POOL_IDL = exports.createVeiloProgram = void 0;
+exports.pubkeyToField = exports.poseidon4 = exports.poseidon3 = exports.poseidon2 = exports.poseidon1 = exports.frToBigInt = exports.bigIntToBytesBE = exports.bytesToBigIntBE = exports.BN254_FR_MODULUS = exports.getPoseidon = exports.initPoseidon = exports.DEFAULT_RPC_RETRY = exports.withRpcRetry = exports.randomBytes32 = exports.randomBytes = exports.verifyProof = exports.createSwapProver = exports.createTransactionProver = exports.PRIVACY_POOL_PROGRAM_ID = exports.PRIVACY_POOL_IDL = exports.createReadonlyVeiloProgram = exports.createVeiloProgram = void 0;
 // Core client functions
-__exportStar(require("./client"), exports);
+__exportStar(require("./client.js"), exports);
 // UTXO types and functions (replaces note.ts)
-__exportStar(require("./utxo"), exports);
+__exportStar(require("./utxo.js"), exports);
 // Configuration constants and types
-__exportStar(require("./config"), exports);
+__exportStar(require("./config.js"), exports);
 // Merkle tree implementation
-__exportStar(require("./merkle"), exports);
+__exportStar(require("./merkle.js"), exports);
 // Proof types and helpers
-__exportStar(require("./proof"), exports);
+__exportStar(require("./proof.js"), exports);
 // On-chain event scanning and tree reconstruction
-__exportStar(require("./events"), exports);
+__exportStar(require("./events.js"), exports);
 // Program factory and IDL
-var program_1 = require("./program");
-Object.defineProperty(exports, "createVeiloProgram", { enumerable: true, get: function () { return program_1.createVeiloProgram; } });
-Object.defineProperty(exports, "PRIVACY_POOL_IDL", { enumerable: true, get: function () { return program_1.PRIVACY_POOL_IDL; } });
-Object.defineProperty(exports, "PRIVACY_POOL_PROGRAM_ID", { enumerable: true, get: function () { return program_1.PRIVACY_POOL_PROGRAM_ID; } });
+var program_js_1 = require("./program.js");
+Object.defineProperty(exports, "createVeiloProgram", { enumerable: true, get: function () { return program_js_1.createVeiloProgram; } });
+Object.defineProperty(exports, "createReadonlyVeiloProgram", { enumerable: true, get: function () { return program_js_1.createReadonlyVeiloProgram; } });
+Object.defineProperty(exports, "PRIVACY_POOL_IDL", { enumerable: true, get: function () { return program_js_1.PRIVACY_POOL_IDL; } });
+Object.defineProperty(exports, "PRIVACY_POOL_PROGRAM_ID", { enumerable: true, get: function () { return program_js_1.PRIVACY_POOL_PROGRAM_ID; } });
+// Wallet-agnostic shielding — build an unsigned deposit for any external wallet
+__exportStar(require("./shield/index.js"), exports);
 // Proof generation (requires snarkjs peer dependency)
-var prover_1 = require("./prover");
-Object.defineProperty(exports, "createTransactionProver", { enumerable: true, get: function () { return prover_1.createTransactionProver; } });
-Object.defineProperty(exports, "verifyProof", { enumerable: true, get: function () { return prover_1.verifyProof; } });
+var prover_js_1 = require("./prover.js");
+Object.defineProperty(exports, "createTransactionProver", { enumerable: true, get: function () { return prover_js_1.createTransactionProver; } });
+Object.defineProperty(exports, "createSwapProver", { enumerable: true, get: function () { return prover_js_1.createSwapProver; } });
+Object.defineProperty(exports, "verifyProof", { enumerable: true, get: function () { return prover_js_1.verifyProof; } });
+// Compact note ciphers — the on-chain payload that makes notes recoverable
+// from chain data alone, without any relayer involvement.
+__exportStar(require("./compactNote.js"), exports);
+// Cross-platform CSPRNG (no node:crypto import — safe in browser bundles)
+var random_js_1 = require("./random.js");
+Object.defineProperty(exports, "randomBytes", { enumerable: true, get: function () { return random_js_1.randomBytes; } });
+Object.defineProperty(exports, "randomBytes32", { enumerable: true, get: function () { return random_js_1.randomBytes32; } });
 // Relayer API client
-__exportStar(require("./relayer"), exports);
+__exportStar(require("./relayer.js"), exports);
+// Veilo Cloak Partner API client and helpers
+__exportStar(require("./cloak.js"), exports);
 // RPC retry / resilience
-var retry_1 = require("./retry");
-Object.defineProperty(exports, "withRpcRetry", { enumerable: true, get: function () { return retry_1.withRpcRetry; } });
-Object.defineProperty(exports, "DEFAULT_RPC_RETRY", { enumerable: true, get: function () { return retry_1.DEFAULT_RPC_RETRY; } });
+var retry_js_1 = require("./retry.js");
+Object.defineProperty(exports, "withRpcRetry", { enumerable: true, get: function () { return retry_js_1.withRpcRetry; } });
+Object.defineProperty(exports, "DEFAULT_RPC_RETRY", { enumerable: true, get: function () { return retry_js_1.DEFAULT_RPC_RETRY; } });
 // Poseidon hash functions
-var poseidon_1 = require("./poseidon");
-Object.defineProperty(exports, "initPoseidon", { enumerable: true, get: function () { return poseidon_1.initPoseidon; } });
-Object.defineProperty(exports, "getPoseidon", { enumerable: true, get: function () { return poseidon_1.getPoseidon; } });
-Object.defineProperty(exports, "BN254_FR_MODULUS", { enumerable: true, get: function () { return poseidon_1.BN254_FR_MODULUS; } });
-Object.defineProperty(exports, "bytesToBigIntBE", { enumerable: true, get: function () { return poseidon_1.bytesToBigIntBE; } });
-Object.defineProperty(exports, "bigIntToBytesBE", { enumerable: true, get: function () { return poseidon_1.bigIntToBytesBE; } });
-Object.defineProperty(exports, "frToBigInt", { enumerable: true, get: function () { return poseidon_1.frToBigInt; } });
-Object.defineProperty(exports, "poseidon1", { enumerable: true, get: function () { return poseidon_1.poseidon1; } });
-Object.defineProperty(exports, "poseidon2", { enumerable: true, get: function () { return poseidon_1.poseidon2; } });
-Object.defineProperty(exports, "poseidon3", { enumerable: true, get: function () { return poseidon_1.poseidon3; } });
-Object.defineProperty(exports, "poseidon4", { enumerable: true, get: function () { return poseidon_1.poseidon4; } });
-Object.defineProperty(exports, "pubkeyToField", { enumerable: true, get: function () { return poseidon_1.pubkeyToField; } });
+var poseidon_js_1 = require("./poseidon.js");
+Object.defineProperty(exports, "initPoseidon", { enumerable: true, get: function () { return poseidon_js_1.initPoseidon; } });
+Object.defineProperty(exports, "getPoseidon", { enumerable: true, get: function () { return poseidon_js_1.getPoseidon; } });
+Object.defineProperty(exports, "BN254_FR_MODULUS", { enumerable: true, get: function () { return poseidon_js_1.BN254_FR_MODULUS; } });
+Object.defineProperty(exports, "bytesToBigIntBE", { enumerable: true, get: function () { return poseidon_js_1.bytesToBigIntBE; } });
+Object.defineProperty(exports, "bigIntToBytesBE", { enumerable: true, get: function () { return poseidon_js_1.bigIntToBytesBE; } });
+Object.defineProperty(exports, "frToBigInt", { enumerable: true, get: function () { return poseidon_js_1.frToBigInt; } });
+Object.defineProperty(exports, "poseidon1", { enumerable: true, get: function () { return poseidon_js_1.poseidon1; } });
+Object.defineProperty(exports, "poseidon2", { enumerable: true, get: function () { return poseidon_js_1.poseidon2; } });
+Object.defineProperty(exports, "poseidon3", { enumerable: true, get: function () { return poseidon_js_1.poseidon3; } });
+Object.defineProperty(exports, "poseidon4", { enumerable: true, get: function () { return poseidon_js_1.poseidon4; } });
+Object.defineProperty(exports, "pubkeyToField", { enumerable: true, get: function () { return poseidon_js_1.pubkeyToField; } });

package/dist/cjs/merkle.d.ts

@@ -62,3 +62,16 @@ export declare class MerkleTree {
      */
     getCircuitPath(index: number): CircuitMerklePath;
 }
+/**
+ * The Poseidon zero chain: `z[0] = 0`, `z[i+1] = Poseidon(z[i], z[i])`.
+ *
+ * This is the `zeroes` array a `MerkleTree` builds in its constructor, without
+ * the tree. Deposits need a Merkle path for their dummy inputs, but the circuit
+ * disables the path check when a input amount is zero (`enabled <== 1 - IsZero(amount)`
+ * in transaction.circom), so the values are never constrained — only their
+ * count is.
+ *
+ * Allocating a full depth-22 `MerkleTree` for this costs ~130 MB and several
+ * seconds. This costs 22 hashes. Any deposit-shaped transaction should use it.
+ */
+export declare function poseidonZeroChain(depth?: number): Uint8Array[];

package/dist/cjs/merkle.js

@@ -1,18 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MerkleTree = void 0;
-const poseidon_1 = require("./poseidon");
+exports.poseidonZeroChain = poseidonZeroChain;
+const poseidon_js_1 = require("./poseidon.js");
 // Poseidon-based hash of two 32-byte field elements.
 function hashPair(left, right) {
     if (left.length !== 32 || right.length !== 32) {
         throw new Error("hashPair expects 32-byte inputs");
     }
-    const poseidon = (0, poseidon_1.getPoseidon)();
-    const lf = (0, poseidon_1.bytesToBigIntBE)(left) % poseidon_1.BN254_FR_MODULUS;
-    const rf = (0, poseidon_1.bytesToBigIntBE)(right) % poseidon_1.BN254_FR_MODULUS;
+    const poseidon = (0, poseidon_js_1.getPoseidon)();
+    const lf = (0, poseidon_js_1.bytesToBigIntBE)(left) % poseidon_js_1.BN254_FR_MODULUS;
+    const rf = (0, poseidon_js_1.bytesToBigIntBE)(right) % poseidon_js_1.BN254_FR_MODULUS;
     const fe = poseidon([lf, rf]);
-    const outBig = (0, poseidon_1.frToBigInt)(fe) % poseidon_1.BN254_FR_MODULUS;
-    return (0, poseidon_1.bigIntToBytesBE)(outBig);
+    const outBig = (0, poseidon_js_1.frToBigInt)(fe) % poseidon_js_1.BN254_FR_MODULUS;
+    return (0, poseidon_js_1.bigIntToBytesBE)(outBig);
 }
 /**
  * Fixed-depth binary Merkle tree over BN254 Fr:
@@ -32,7 +33,7 @@ class MerkleTree {
         this.zeroes = [];
         this.layers = [];
         // zero[0] = 0 (Fr), then zero[i+1] = Poseidon(zero[i], zero[i])
-        let zero = (0, poseidon_1.bigIntToBytesBE)(0n);
+        let zero = (0, poseidon_js_1.bigIntToBytesBE)(0n);
         this.zeroes.push(zero);
         for (let level = 1; level <= depth; level++) {
             zero = hashPair(zero, zero);
@@ -126,8 +127,30 @@ class MerkleTree {
         const merklePath = this.getPath(index);
         return {
             pathIndex: index,
-            pathElements: merklePath.path.map((p) => (0, poseidon_1.bytesToBigIntBE)(p) % poseidon_1.BN254_FR_MODULUS),
+            pathElements: merklePath.path.map((p) => (0, poseidon_js_1.bytesToBigIntBE)(p) % poseidon_js_1.BN254_FR_MODULUS),
         };
     }
 }
 exports.MerkleTree = MerkleTree;
+/**
+ * The Poseidon zero chain: `z[0] = 0`, `z[i+1] = Poseidon(z[i], z[i])`.
+ *
+ * This is the `zeroes` array a `MerkleTree` builds in its constructor, without
+ * the tree. Deposits need a Merkle path for their dummy inputs, but the circuit
+ * disables the path check when a input amount is zero (`enabled <== 1 - IsZero(amount)`
+ * in transaction.circom), so the values are never constrained — only their
+ * count is.
+ *
+ * Allocating a full depth-22 `MerkleTree` for this costs ~130 MB and several
+ * seconds. This costs 22 hashes. Any deposit-shaped transaction should use it.
+ */
+function poseidonZeroChain(depth = 22) {
+    const zeroes = [];
+    let zero = (0, poseidon_js_1.bigIntToBytesBE)(0n);
+    zeroes.push(zero);
+    for (let level = 1; level <= depth; level++) {
+        zero = hashPair(zero, zero);
+        zeroes.push(zero);
+    }
+    return zeroes;
+}

package/dist/cjs/notes/encryption.d.ts

@@ -0,0 +1,41 @@
+import { PublicKey } from "@solana/web3.js";
+import type { SerializedUTXO } from "./model.js";
+/**
+ * Encrypted UTXO note — can be broadcast alongside a transaction so the
+ * recipient can recover their note without a server.
+ */
+export type EncryptedNote = {
+    /** 24-byte NaCl box nonce */
+    nonce: Uint8Array;
+    /** Ciphertext containing amount + blinding + privateKey */
+    ciphertext: Uint8Array;
+    /** Sender's ephemeral 32-byte X25519 public key */
+    senderEphemeralPubkey: Uint8Array;
+};
+/**
+ * Derive a NaCl X25519 encryption keypair from a UTXO private key.
+ * The keypair is deterministic: same privateKey always yields the same pair.
+ */
+export declare function deriveEncryptionKeypair(privateKey: bigint): {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+};
+/**
+ * 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 declare function encryptUTXONote(utxo: SerializedUTXO & {
+    privateKey: bigint;
+}, recipientEncPubkey: Uint8Array): EncryptedNote;
+/**
+ * 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 declare function decryptUTXONote(note: EncryptedNote, recipientPrivateKey: bigint, commitment: Uint8Array, mintAddress: PublicKey): SerializedUTXO | null;

package/dist/cjs/notes/encryption.js

@@ -0,0 +1,75 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveEncryptionKeypair = deriveEncryptionKeypair;
+exports.encryptUTXONote = encryptUTXONote;
+exports.decryptUTXONote = decryptUTXONote;
+const sha256_1 = require("@noble/hashes/sha256");
+const tweetnacl_1 = __importDefault(require("tweetnacl"));
+const poseidon_js_1 = require("../poseidon.js");
+const model_js_1 = require("./model.js");
+/**
+ * Derive a NaCl X25519 encryption keypair from a UTXO private key.
+ * The keypair is deterministic: same privateKey always yields the same pair.
+ */
+function deriveEncryptionKeypair(privateKey) {
+    const seed = (0, sha256_1.sha256)((0, poseidon_js_1.bigIntToBytesBE)(privateKey));
+    return tweetnacl_1.default.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.
+ */
+function encryptUTXONote(utxo, recipientEncPubkey) {
+    const nonce = tweetnacl_1.default.randomBytes(tweetnacl_1.default.box.nonceLength); // 24 bytes
+    const ephemeral = tweetnacl_1.default.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((0, poseidon_js_1.bigIntToBytesBE)(utxo.blinding), 8);
+    plaintext.set((0, poseidon_js_1.bigIntToBytesBE)(utxo.privateKey), 40);
+    const sharedKey = tweetnacl_1.default.box.before(recipientEncPubkey, ephemeral.secretKey);
+    const ciphertext = tweetnacl_1.default.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.
+ */
+function decryptUTXONote(note, recipientPrivateKey, commitment, mintAddress) {
+    const { secretKey } = deriveEncryptionKeypair(recipientPrivateKey);
+    const sharedKey = tweetnacl_1.default.box.before(note.senderEphemeralPubkey, secretKey);
+    const plaintext = tweetnacl_1.default.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 = (0, poseidon_js_1.bytesToBigIntBE)(plaintext.slice(8, 40)) % poseidon_js_1.BN254_FR_MODULUS;
+    const privateKey = (0, poseidon_js_1.bytesToBigIntBE)(plaintext.slice(40, 72)) % poseidon_js_1.BN254_FR_MODULUS;
+    const pubkey = (0, model_js_1.derivePublicKey)(privateKey);
+    const utxo = {
+        amount,
+        pubkey,
+        blinding,
+        mintAddress: (0, poseidon_js_1.pubkeyToField)(mintAddress),
+    };
+    const expectedCommitment = (0, model_js_1.commitUTXO)(utxo);
+    if (!expectedCommitment.every((b, i) => b === commitment[i]))
+        return null;
+    return { ...utxo, commitment, privateKey };
+}

package/dist/cjs/notes/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./model.js";
+export * from "./nullifier.js";
+export * from "./encryption.js";
+export * from "./mailbox.js";
+export * from "./recovery.js";

package/dist/cjs/notes/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./model.js"), exports);
+__exportStar(require("./nullifier.js"), exports);
+__exportStar(require("./encryption.js"), exports);
+__exportStar(require("./mailbox.js"), exports);
+__exportStar(require("./recovery.js"), exports);

package/dist/cjs/notes/mailbox.d.ts

@@ -0,0 +1,70 @@
+/** Note data stored inside a Blind Mailbox encrypted blob */
+export type BlindMailboxNoteData = {
+    blinding: Uint8Array;
+    leafIndex: number;
+    commitment: Uint8Array;
+    amount: bigint;
+    mintAddress: string;
+    treeId: number;
+};
+/** Encrypted note as returned by the relayer's /api/notes endpoint */
+export type BlindMailboxNote = {
+    commitment: string;
+    ephemeralPublicKey: string;
+    encryptedBlob: string;
+    timestamp?: number;
+    blockHeight?: number;
+    txSignature?: string;
+};
+/** Decrypted note data after calling decryptBlindMailboxNote */
+export type DecryptedNote = {
+    blinding: Uint8Array;
+    leafIndex: number;
+    commitment: Uint8Array;
+    amount: bigint;
+    timestamp: number;
+    mintAddress?: string;
+    treeId: number;
+};
+/** 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].
+ *
+ *  DO NOT "fix" this to real SHA-256. The name in the sibling implementations
+ *  (`sha256ForNotes`) is a misnomer, but the bytes are load-bearing: changing the
+ *  KDF makes every historical note undecryptable.
+ *
+ *  @internal Exported for `compactNote.ts`. Not part of the stable public API. */
+export declare function kdfSHA512_256(secret: Uint8Array): Uint8Array;
+/** Convert an Ed25519 private seed (32 bytes) to an X25519 scalar.
+ *  Equivalent to ed2curve.convertSecretKey(seed).
+ *
+ *  @internal Exported for `compactNote.ts`. Not part of the stable public API. */
+export declare function ed25519SeedToX25519Private(seed: Uint8Array): Uint8Array;
+/** 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).
+ *
+ *  @internal Exported for `compactNote.ts`. Not part of the stable public API. */
+export declare function ed25519PublicKeyToX25519(pubkey: Uint8Array): Uint8Array;
+/**
+ * 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 declare function encryptBlindMailboxNote(recipientWalletPubkey: Uint8Array, noteData: BlindMailboxNoteData): {
+    ephemeralPublicKey: Uint8Array;
+    encryptedBlob: string;
+};
+/**
+ * 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 declare function decryptBlindMailboxNote(walletSecretKey: Uint8Array, ephemeralPublicKey: Uint8Array, encryptedBlob: string): DecryptedNote;

package/dist/cjs/notes/mailbox.js

@@ -0,0 +1,164 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.kdfSHA512_256 = kdfSHA512_256;
+exports.ed25519SeedToX25519Private = ed25519SeedToX25519Private;
+exports.ed25519PublicKeyToX25519 = ed25519PublicKeyToX25519;
+exports.encryptBlindMailboxNote = encryptBlindMailboxNote;
+exports.decryptBlindMailboxNote = decryptBlindMailboxNote;
+const tweetnacl_1 = __importDefault(require("tweetnacl"));
+const random_js_1 = require("../random.js");
+// -- 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].
+ *
+ *  DO NOT "fix" this to real SHA-256. The name in the sibling implementations
+ *  (`sha256ForNotes`) is a misnomer, but the bytes are load-bearing: changing the
+ *  KDF makes every historical note undecryptable.
+ *
+ *  @internal Exported for `compactNote.ts`. Not part of the stable public API. */
+function kdfSHA512_256(secret) {
+    return tweetnacl_1.default.hash(secret).slice(0, 32);
+}
+/** Convert an Ed25519 private seed (32 bytes) to an X25519 scalar.
+ *  Equivalent to ed2curve.convertSecretKey(seed).
+ *
+ *  @internal Exported for `compactNote.ts`. Not part of the stable public API. */
+function ed25519SeedToX25519Private(seed) {
+    const h = tweetnacl_1.default.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).
+ *
+ *  @internal Exported for `compactNote.ts`. Not part of the stable public API. */
+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
+ */
+function encryptBlindMailboxNote(recipientWalletPubkey, noteData) {
+    // 1. Generate ephemeral Ed25519 keypair seed
+    const ephemeralSeed = (0, random_js_1.randomBytes)(32);
+    // Ed25519 public key stored by relayer; dapp recovers X25519 via ed2curve.convertPublicKey()
+    const ephemeralEdPublicKey = tweetnacl_1.default.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 = tweetnacl_1.default.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 = tweetnacl_1.default.randomBytes(24);
+    const plaintext = new TextEncoder().encode(noteJson);
+    const encrypted = tweetnacl_1.default.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
+ */
+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 = tweetnacl_1.default.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 = tweetnacl_1.default.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,
+    };
+}