@veilo/sdk-core 0.3.3 → 0.5.0

package/dist/cjs/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/cjs/compactNote.js

@@ -0,0 +1,191 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPACT_BLOB_LENGTH = void 0;
+exports.createCompactNoteCipher = createCompactNoteCipher;
+exports.decryptCompactNoteCipher = decryptCompactNoteCipher;
+exports.matchesViewTag = matchesViewTag;
+exports.toX25519Private = toX25519Private;
+exports.emptyNoteCipher = emptyNoteCipher;
+exports.createNoteCiphers = createNoteCiphers;
+const tweetnacl_1 = __importDefault(require("tweetnacl"));
+const mailbox_js_1 = require("./notes/mailbox.js");
+const random_js_1 = require("./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]. */
+exports.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
+ */
+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 ?? (0, random_js_1.randomBytes)(32);
+    const ephemeralPublicKey = tweetnacl_1.default.sign.keyPair.fromSeed(ephemeralSeed).publicKey;
+    const sharedSecret = deriveSharedSecret(ephemeralSeed, recipientWalletPubkey);
+    const key = (0, mailbox_js_1.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 ?? tweetnacl_1.default.randomBytes(NONCE_LENGTH);
+    const encrypted = tweetnacl_1.default.secretbox(plaintext, nonce, key);
+    const compactBlob = new Uint8Array(exports.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 = tweetnacl_1.default.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
+ */
+function decryptCompactNoteCipher(walletSecretKey, ephemeralPublicKey, compactBlob, precomputed) {
+    if (compactBlob.length !== exports.COMPACT_BLOB_LENGTH)
+        return null;
+    const sharedSecret = precomputed?.sharedSecret ??
+        (precomputed?.x25519Private
+            ? tweetnacl_1.default.scalarMult(precomputed.x25519Private, (0, mailbox_js_1.ed25519PublicKeyToX25519)(ephemeralPublicKey))
+            : deriveSharedSecret(walletSecretKey, ephemeralPublicKey));
+    const key = (0, mailbox_js_1.kdfSHA512_256)(sharedSecret);
+    const nonce = compactBlob.slice(0, NONCE_LENGTH);
+    const encrypted = compactBlob.slice(NONCE_LENGTH);
+    const plaintext = tweetnacl_1.default.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}.
+ */
+function matchesViewTag(walletSecretKey, ephemeralPublicKey, viewTag, precomputed) {
+    const sharedSecret = precomputed?.x25519Private
+        ? tweetnacl_1.default.scalarMult(precomputed.x25519Private, (0, mailbox_js_1.ed25519PublicKeyToX25519)(ephemeralPublicKey))
+        : deriveSharedSecret(walletSecretKey, ephemeralPublicKey);
+    return { matches: tweetnacl_1.default.hash(sharedSecret)[0] === viewTag, sharedSecret };
+}
+/**
+ * Convert an Ed25519 wallet secret key to its X25519 scalar once, for reuse
+ * across a scan loop.
+ */
+function toX25519Private(walletSecretKey) {
+    return (0, mailbox_js_1.ed25519SeedToX25519Private)(seedOf(walletSecretKey));
+}
+/** The all-zero cipher the program treats as "no note here". */
+function emptyNoteCipher() {
+    return {
+        ephemeralPublicKey: new Uint8Array(32),
+        compactBlob: new Uint8Array(exports.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`.
+ */
+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 tweetnacl_1.default.scalarMult((0, mailbox_js_1.ed25519SeedToX25519Private)(seedOf(mySecretKey)), (0, mailbox_js_1.ed25519PublicKeyToX25519)(theirEd25519PublicKey));
+}

package/dist/cjs/events.d.ts

@@ -1,6 +1,6 @@
 import { PublicKey } from "@solana/web3.js";
 import { Program, Idl } from "@coral-xyz/anchor";
-import { MerkleTree } from "./merkle";
+import { MerkleTree } from "./merkle.js";
 /**
  * On-chain CommitmentEvent emitted by `transact` and `transact_swap`.
  * Mirrors the IDL CommitmentEvent struct.

package/dist/cjs/events.js

@@ -37,7 +37,7 @@ exports.scanCommitmentEvents = scanCommitmentEvents;
 exports.scanNullifierEvents = scanNullifierEvents;
 exports.buildTreeFromEvents = buildTreeFromEvents;
 const anchor = __importStar(require("@coral-xyz/anchor"));
-const merkle_1 = require("./merkle");
+const merkle_js_1 = require("./merkle.js");
 // -----------------------------------------------------------------------------
 // Event Scanning
 // -----------------------------------------------------------------------------
@@ -156,7 +156,7 @@ async function buildTreeFromEvents(params) {
     const treeEvents = allEvents
         .filter((e) => e.treeId === treeId)
         .sort((a, b) => a.leafIndex - b.leafIndex);
-    const tree = new merkle_1.MerkleTree(depth);
+    const tree = new merkle_js_1.MerkleTree(depth);
     for (const ev of treeEvents) {
         tree.insert(ev.commitment);
     }

package/dist/cjs/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;