@veilo/sdk-core 0.5.0 → 0.6.0

package/dist/cjs/identity/viewKey.js

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

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

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

package/dist/cjs/idl/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRIVACY_POOL_IDLS = exports.PRIVACY_POOL_LEGACY2_IDL = exports.PRIVACY_POOL_LEGACY_IDL = exports.PRIVACY_POOL_CURRENT_IDL = void 0;
+const privacy_pool_js_1 = __importDefault(require("./privacy_pool.js"));
+const privacy_pool_legacy_js_1 = __importDefault(require("./privacy_pool_legacy.js"));
+const privacy_pool_legacy2_js_1 = __importDefault(require("./privacy_pool_legacy2.js"));
+/** Current IDL used for building new instructions. */
+exports.PRIVACY_POOL_CURRENT_IDL = privacy_pool_js_1.default;
+/** Original event shape without compact note recovery fields. */
+exports.PRIVACY_POOL_LEGACY_IDL = privacy_pool_legacy_js_1.default;
+/** Intermediate event shape with compact cipher fields but no view tag. */
+exports.PRIVACY_POOL_LEGACY2_IDL = privacy_pool_legacy2_js_1.default;
+/**
+ * IDLs in the same newest-to-oldest fallback order used by the relayer indexer.
+ * All three target the same deployed program address.
+ */
+exports.PRIVACY_POOL_IDLS = [
+    { version: "current", idl: exports.PRIVACY_POOL_CURRENT_IDL },
+    { version: "legacy", idl: exports.PRIVACY_POOL_LEGACY_IDL },
+    { version: "legacy2", idl: exports.PRIVACY_POOL_LEGACY2_IDL },
+];