@veilo/sdk-core 0.4.0 → 0.6.0

package/dist/esm/identity/viewKey.js

@@ -0,0 +1,96 @@
+/**
+ * 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.
+ */
+import { hkdf } from "@noble/hashes/hkdf";
+import { sha256 } from "@noble/hashes/sha256";
+import nacl from "tweetnacl";
+import { decryptCompactNoteCipher } from "../compactNote.js";
+import { ed25519PublicKeyToX25519 } from "../notes/mailbox.js";
+import { assertBytes, utf8 } from "./encoding.js";
+import { deriveSpendingKeyWithSigner } from "./spending.js";
+/** HKDF salt. Provisional — see the header. */
+export const VEILO_VIEW_KEY_SALT = "veilo_view_v1";
+/** HKDF info. Provisional — see the header. */
+export const 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. */
+export function deriveViewKeypairFromSpendingKey(spendingKey) {
+    assertBytes(spendingKey, 32, "spending key");
+    const viewSecretKey = clampX25519(hkdf(sha256, spendingKey, utf8(VEILO_VIEW_KEY_SALT), utf8(VEILO_VIEW_KEY_INFO), 32));
+    return { viewSecretKey, viewPublicKey: nacl.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.
+ */
+export async function deriveViewKeypairWithSigner(signMessage, index = 0) {
+    return deriveViewKeypairFromSpendingKey(await 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.
+ */
+export function openCompactNoteWithViewKey(viewSecretKey, cipher) {
+    assertBytes(viewSecretKey, 32, "view secret key");
+    assertBytes(cipher.ephemeralPublicKey, 32, "ephemeral public key");
+    const sharedSecret = nacl.scalarMult(viewSecretKey, ed25519PublicKeyToX25519(cipher.ephemeralPublicKey));
+    if (nacl.hash(sharedSecret)[0] !== cipher.viewTag)
+        return null;
+    // walletSecretKey is unused once `sharedSecret` is supplied.
+    return decryptCompactNoteCipher(viewSecretKey, cipher.ephemeralPublicKey, cipher.compactBlob, { sharedSecret });
+}

package/dist/esm/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/esm/idl/index.js

@@ -0,0 +1,18 @@
+import currentIdl from "./privacy_pool.js";
+import legacyIdl from "./privacy_pool_legacy.js";
+import legacy2Idl from "./privacy_pool_legacy2.js";
+/** Current IDL used for building new instructions. */
+export const PRIVACY_POOL_CURRENT_IDL = currentIdl;
+/** Original event shape without compact note recovery fields. */
+export const PRIVACY_POOL_LEGACY_IDL = legacyIdl;
+/** Intermediate event shape with compact cipher fields but no view tag. */
+export const PRIVACY_POOL_LEGACY2_IDL = legacy2Idl;
+/**
+ * IDLs in the same newest-to-oldest fallback order used by the relayer indexer.
+ * All three target the same deployed program address.
+ */
+export const PRIVACY_POOL_IDLS = [
+    { version: "current", idl: PRIVACY_POOL_CURRENT_IDL },
+    { version: "legacy", idl: PRIVACY_POOL_LEGACY_IDL },
+    { version: "legacy2", idl: PRIVACY_POOL_LEGACY2_IDL },
+];