@zbase-protocol/core 0.1.0

package/dist/notes.js

@@ -0,0 +1,547 @@
+/**
+ * @zbase-protocol/core — UTXO note primitives (Shipment A.1 scaffold)
+ *
+ * v0: in-memory note model + viewing-key encryption for storing notes off-chain
+ * and posting their ciphertext alongside the spend's `NoteCommitted` event.
+ *
+ * Mirrors Railgun's note model (https://docs.railgun.org/wiki/learn/privacy-system).
+ * The on-chain commitment encoding is intentionally identical to the current
+ * single-value commitment in `account.ts` so the same Poseidon helpers stay in
+ * use and the Anchor program's `crypto.rs` continues to apply without change:
+ *
+ *   precommitment = Poseidon2(nullifier, secret)
+ *   commitment    = Poseidon3(amount, label, precommitment)
+ *
+ * Cryptographic envelope chosen for cold-start performance over libsodium.js
+ * (no WASM init, no async load) — see /docs/utxo-notes-design.md §4.1.
+ *
+ *   * X25519 key agreement   (`@noble/curves/ed25519` → `x25519`)
+ *   * XChaCha20-Poly1305     (`@noble/ciphers/chacha`)
+ *   * 2-byte view-tag        (Railgun-style fast scan filter)
+ *
+ * Status: scaffold. Do NOT use the encryption helpers in production until
+ * (a) the bytes layout has been pinned by a wallet review and
+ * (b) the trusted-setup ceremony for `note_spend.circom` has completed.
+ */
+import { poseidon1, poseidon2, poseidon3 } from "poseidon-lite";
+import { x25519 } from "@noble/curves/ed25519";
+import { xchacha20poly1305 } from "@noble/ciphers/chacha";
+import { keccak_256 } from "@noble/hashes/sha3";
+import { randomBytes } from "@noble/hashes/utils";
+// Shared, unbiased (rejection-sampling) field sampler — see account.ts (audit F7).
+import { randomFieldElement } from "./account.js";
+// -----------------------------------------------------------------------------
+// Note creation
+// -----------------------------------------------------------------------------
+/**
+ * Create a fresh note with random nullifier + secret.
+ *
+ * `amount` + `label` come from a deposit or a parent note being split. The NPK
+ * inputs (`spendingPK`, `viewingPKBlind`) identify the RECIPIENT and bind the
+ * label privately — they default to 0 here for the self-spend / scaffold case,
+ * but a real transfer MUST pass the recipient's derived NPK inputs.
+ *
+ * ⚠️ Deriving spendingPK/viewingPKBlind from a recipient's viewing key is the
+ * auditor-scoped gap (see the Note doc). Until that lands, callers either pass
+ * 0 (change-back-to-self placeholder) or supply explicit values.
+ */
+export function createNote(amount, label, npk) {
+    return {
+        amount,
+        label,
+        spendingPK: npk?.spendingPK ?? 0n,
+        viewingPKBlind: npk?.viewingPKBlind ?? 0n,
+        nullifier: randomFieldElement(),
+        secret: randomFieldElement(),
+    };
+}
+/**
+ * Create a zero-value dummy note. Used as a placeholder input/output to fill
+ * the fixed N=2/M=2 slots of the v0 spend circuit when the spender does not
+ * actually need 2 inputs or 2 outputs.
+ *
+ * A dummy carries amount=0 and label=0; the circuit's `inIsDummy[i]` flag
+ * must be set to 1 for input dummies. (Output dummies are valid as-is because
+ * a 0-amount output commitment hashes deterministically and inserts harmlessly
+ * into the state tree — though wallets should treat amount=0 commitments as
+ * unspendable noise.)
+ */
+export function createDummyNote() {
+    return {
+        amount: 0n,
+        label: 0n,
+        spendingPK: 0n,
+        viewingPKBlind: 0n,
+        nullifier: randomFieldElement(),
+        secret: randomFieldElement(),
+    };
+}
+// -----------------------------------------------------------------------------
+// Commitment + nullifier helpers — v1 Railgun NPK recipe (matches note_spend.circom)
+// -----------------------------------------------------------------------------
+/**
+ * `NPK = Poseidon2(spendingPK, viewingPKBlind)`. The note-public-key the
+ * circuit's `NpkBuilder` template computes (note_spend.circom NpkBuilder).
+ */
+export function npkOf(note) {
+    return poseidon2([note.spendingPK, note.viewingPKBlind]);
+}
+/**
+ * v1 UTXO commitment (audit C3): `commitment = Poseidon3(amount, NPK, secret)`,
+ * `NPK = Poseidon2(spendingPK, viewingPKBlind)`.
+ *
+ * This now matches `CommitmentHasher` in `note_spend.circom` EXACTLY (Poseidon3
+ * over `[amount, npk, secret]`). The prior v0 recipe
+ * `Poseidon3(amount, label, Poseidon2(nullifier, secret))` did NOT match the
+ * circuit and would have made every UTXO proof unverifiable.
+ *
+ * NOTE: this is the UTXO-pool recipe. The legacy single-value pool keeps its own
+ * (correct, deployed) recipe in `account.ts::computeCommitment` — do not unify
+ * them; they back two different pools.
+ */
+export function commitmentOf(note) {
+    const npk = npkOf(note);
+    return poseidon3([note.amount, npk, note.secret]);
+}
+/**
+ * `nullifierHash = Poseidon1(nullifier)`. Imported from account.ts. Repeated
+ * here only for convenient note-centric API.
+ */
+export function nullifierHashOf(note) {
+    return poseidon1([note.nullifier]);
+}
+// -----------------------------------------------------------------------------
+// Split / merge helpers (pure value arithmetic, no circuit invocation)
+// -----------------------------------------------------------------------------
+export class NoteValueError extends Error {
+}
+/**
+ * Circuit range bound (audit F11): `note_spend.circom` range-checks every output
+ * amount and the withdrawn amount to 64 bits (`Num2Bits(64)`). Amounts at or
+ * above 2^64 would fail proof generation with an opaque error, or — if a caller
+ * skipped the SDK — risk field-wraparound creating value. We validate here so
+ * bad amounts are rejected up front with a clear message.
+ */
+export const MAX_NOTE_AMOUNT = 1n << 64n;
+/**
+ * Split a single note into two new notes that conserve the parent value and
+ * inherit its label. The two outputs are returned in the order
+ * `[primary, change]`; pass them straight into a 2-output spend.
+ */
+export function splitNote(parent, primaryAmount) {
+    if (primaryAmount < 0n) {
+        throw new NoteValueError("splitNote: primaryAmount must be non-negative");
+    }
+    if (primaryAmount > parent.amount) {
+        throw new NoteValueError(`splitNote: primaryAmount ${primaryAmount} > parent.amount ${parent.amount}`);
+    }
+    // Carry the parent's NPK material so both children remain addressable to the
+    // same owner (change-back-to-self semantics). A real outbound transfer
+    // overrides the primary output's NPK with the recipient's at proof-build time.
+    const npk = { spendingPK: parent.spendingPK, viewingPKBlind: parent.viewingPKBlind };
+    return [
+        createNote(primaryAmount, parent.label, npk),
+        createNote(parent.amount - primaryAmount, parent.label, npk),
+    ];
+}
+/**
+ * Merge two notes (with matching label) into one. Returns the merged note.
+ * The caller must spend the two inputs and mint this one output via a spend.
+ */
+export function mergeNotes(a, b) {
+    if (a.label !== b.label) {
+        throw new NoteValueError("mergeNotes: labels must match (cannot mix ASP attestations across pools)");
+    }
+    return createNote(a.amount + b.amount, a.label, {
+        spendingPK: a.spendingPK,
+        viewingPKBlind: a.viewingPKBlind,
+    });
+}
+/**
+ * Plan the inputs/outputs for paying `payAmount` out of an array of available
+ * notes. Returns the (≤2) input notes and (≤2) output notes for a v0 spend.
+ *
+ * Strategy:
+ *  - Pick the smallest single note ≥ payAmount if possible (minimises change).
+ *  - Otherwise merge the two largest notes — error if their sum is still
+ *    insufficient (caller must perform multiple spends; defer to a future
+ *    "PaymentPlanner" helper).
+ *
+ * This is a v0 heuristic; production wallets should use a coin-selection
+ * algorithm tuned for anonymity-set size (e.g., randomised LIFO).
+ */
+export function planSpend(available, payAmount) {
+    if (payAmount < 0n) {
+        throw new NoteValueError("planSpend: payAmount must be non-negative");
+    }
+    if (payAmount >= MAX_NOTE_AMOUNT) {
+        throw new NoteValueError(`planSpend: payAmount ${payAmount} exceeds the 64-bit circuit range bound`);
+    }
+    if (available.length === 0) {
+        throw new NoteValueError("planSpend: no notes available");
+    }
+    for (const n of available) {
+        if (n.amount < 0n || n.amount >= MAX_NOTE_AMOUNT) {
+            throw new NoteValueError(`planSpend: note amount ${n.amount} out of the valid 64-bit range`);
+        }
+    }
+    const single = [...available]
+        .filter((n) => n.amount >= payAmount)
+        .sort((a, b) => (a.amount < b.amount ? -1 : a.amount > b.amount ? 1 : 0))[0];
+    if (single) {
+        const change = single.amount - payAmount;
+        // Phase 1A: returns [payAmount, change] not [change, 0]; downstream binding to outputCommitment[0]/[1]
+        return {
+            inputs: [single, createDummyNote()],
+            outputAmounts: [payAmount, change],
+        };
+    }
+    const sorted = [...available].sort((a, b) => a.amount > b.amount ? -1 : a.amount < b.amount ? 1 : 0);
+    if (sorted.length < 2 || sorted[0].amount + sorted[1].amount < payAmount) {
+        throw new NoteValueError(`planSpend: insufficient note balance for payment ${payAmount}`);
+    }
+    const change = sorted[0].amount + sorted[1].amount - payAmount;
+    // Phase 1A: returns [payAmount, change] not [change, 0]; downstream binding to outputCommitment[0]/[1]
+    return {
+        inputs: [sorted[0], sorted[1]],
+        outputAmounts: [payAmount, change],
+    };
+}
+/**
+ * Plan one dust-consolidation step (Phase 1C operational fix).
+ *
+ * Fragmented wallets leak: every spend that has to merge two inputs reveals
+ * (via the conservation law) that the spender held exactly those two note
+ * values, and a wallet forced into many small spends produces a recognisable
+ * on-chain cadence. Keeping the note count low ahead of time means real
+ * payments can take the single-input path, which is the quietest shape.
+ *
+ * Given the available notes and a target count, returns the inputs/outputs
+ * for ONE 2-in/1-out merge spend (the v0 circuit is fixed at 2×2, so a merge
+ * consumes two notes and mints one; the second output slot carries 0):
+ *
+ *  - Only notes with amount > 0 count toward the threshold (zero-amount
+ *    commitments are unspendable noise by convention — see createDummyNote).
+ *  - Returns null when the spendable count is already ≤ threshold, or when
+ *    no two spendable notes share a label (merging across labels would mix
+ *    ASP attestations — same rule as mergeNotes).
+ *  - Within the most-fragmented label group, the two SMALLEST notes merge
+ *    first: dust is the priority, and small notes are the ones whose values
+ *    are most identifiable in conservation-law analysis.
+ *
+ * Repeat-callable: apply the plan (spend the two inputs, keep the merged
+ * output), then call again with the updated set. Each round reduces the
+ * spendable count by exactly one, so looping until null terminates.
+ */
+export function consolidateNotes(available, threshold = 3) {
+    if (threshold < 1) {
+        throw new NoteValueError("consolidateNotes: threshold must be >= 1");
+    }
+    const spendable = available.filter((n) => n.amount > 0n);
+    if (spendable.length <= threshold)
+        return null;
+    // Group by label; only same-label notes can merge (ASP attestation rule).
+    const byLabel = new Map();
+    for (const n of spendable) {
+        const group = byLabel.get(n.label);
+        if (group)
+            group.push(n);
+        else
+            byLabel.set(n.label, [n]);
+    }
+    // Pick the most-fragmented mergeable group; tie-break on smallest member
+    // so the choice is deterministic for a given note set.
+    let chosen = null;
+    for (const group of byLabel.values()) {
+        if (group.length < 2)
+            continue;
+        group.sort((a, b) => (a.amount < b.amount ? -1 : a.amount > b.amount ? 1 : 0));
+        if (!chosen ||
+            group.length > chosen.length ||
+            (group.length === chosen.length && group[0].amount < chosen[0].amount)) {
+            chosen = group;
+        }
+    }
+    if (!chosen)
+        return null; // every label holds a single note — nothing merges
+    const [a, b] = chosen;
+    return {
+        inputs: [a, b],
+        outputAmounts: [a.amount + b.amount, 0n],
+    };
+}
+// -----------------------------------------------------------------------------
+// Serialization (off-chain wallet storage, not the on-chain encrypted form)
+// -----------------------------------------------------------------------------
+/**
+ * Serialize a note to a compact JSON-friendly form. BigInts are encoded as
+ * decimal strings; the round-trip is exact. Used for localStorage today; will
+ * back the facilitator's encrypted note cache later.
+ */
+export function serializeNote(n) {
+    return JSON.stringify({
+        amount: n.amount.toString(),
+        label: n.label.toString(),
+        spendingPK: n.spendingPK.toString(),
+        viewingPKBlind: n.viewingPKBlind.toString(),
+        nullifier: n.nullifier.toString(),
+        secret: n.secret.toString(),
+    });
+}
+export function deserializeNote(s) {
+    const o = JSON.parse(s);
+    return {
+        amount: BigInt(o.amount),
+        label: BigInt(o.label),
+        // Tolerate pre-v1 serialized notes (no NPK fields) by defaulting to 0 —
+        // they predate the UTXO pool and never carried recipient NPK material.
+        spendingPK: o.spendingPK !== undefined ? BigInt(o.spendingPK) : 0n,
+        viewingPKBlind: o.viewingPKBlind !== undefined ? BigInt(o.viewingPKBlind) : 0n,
+        nullifier: BigInt(o.nullifier),
+        secret: BigInt(o.secret),
+    };
+}
+// -----------------------------------------------------------------------------
+// Viewing-key cryptography
+// -----------------------------------------------------------------------------
+/**
+ * Generate a fresh X25519 viewing keypair. Private key is sampled from
+ * `randomBytes` (= crypto.getRandomValues underneath). Curve constraints
+ * (clamping) are handled by `x25519`'s scalar multiplication.
+ */
+export function generateViewingKey() {
+    const privateKey = randomBytes(32);
+    const publicKey = x25519.getPublicKey(privateKey);
+    return { privateKey, publicKey };
+}
+/**
+ * Encrypt a note to a recipient's viewing public key.
+ *
+ * Returns the on-chain blob (see `EncryptedNote` layout above).
+ *
+ * Caveats:
+ *  - The output is non-deterministic (ephemeral key + random nonce).
+ *  - Includes a 2-byte view-tag to make recipient scanning O(N) trial-decrypt
+ *    instead of O(N) full AEAD-decrypt.
+ *  - Does NOT bind the ciphertext to any on-chain commitment. If you want
+ *    AAD binding (preventing a malicious relayer from swapping ciphertexts
+ *    between commitments) pass the commitment hash as `aad`.
+ */
+export function encryptNote(note, recipientPublicKey, aad) {
+    if (recipientPublicKey.length !== 32) {
+        throw new Error("encryptNote: recipientPublicKey must be 32 bytes (X25519)");
+    }
+    // Ephemeral keypair
+    const ephPriv = randomBytes(32);
+    const ephPub = x25519.getPublicKey(ephPriv);
+    // Diffie-Hellman: shared = X25519(ephPriv, recipientPub)
+    const shared = x25519.getSharedSecret(ephPriv, recipientPublicKey);
+    // Symmetric key = keccak(shared) for domain separation from any other use
+    // of `shared` (e.g., view-tag).
+    const symKey = keccak_256(shared);
+    // View-tag = first 2 bytes of keccak(0x01 || shared)
+    // Domain-separated so a scanner can compute it without revealing it can also
+    // produce the symKey.
+    const viewTagInput = new Uint8Array(33);
+    viewTagInput[0] = 0x01;
+    viewTagInput.set(shared, 1);
+    const viewTag = keccak_256(viewTagInput).slice(0, 2);
+    // Nonce: 24 random bytes (XChaCha20)
+    const nonce = randomBytes(24);
+    const plaintext = new TextEncoder().encode(serializeNote(note));
+    const cipher = xchacha20poly1305(symKey, nonce, aad);
+    const ciphertext = cipher.encrypt(plaintext);
+    // Assemble: [ephPub (32)][viewTag (2)][nonce (24)][ciphertext]
+    const out = new Uint8Array(32 + 2 + 24 + ciphertext.length);
+    out.set(ephPub, 0);
+    out.set(viewTag, 32);
+    out.set(nonce, 34);
+    out.set(ciphertext, 58);
+    return out;
+}
+/**
+ * Attempt to decrypt a note using a viewing private key. Returns `null` on
+ * view-tag mismatch (fast path: 99.998% of foreign notes reject here) or on
+ * AEAD failure (cryptographically authenticated decryption).
+ *
+ * `aad` must match what the sender supplied at encryption time (commonly the
+ * commitment hash as bytes).
+ */
+export function decryptNote(encrypted, viewingPrivateKey, aad) {
+    if (encrypted.length < 58 + 16)
+        return null; // need at least the AEAD tag
+    const ephPub = encrypted.slice(0, 32);
+    const viewTag = encrypted.slice(32, 34);
+    const nonce = encrypted.slice(34, 58);
+    const ciphertext = encrypted.slice(58);
+    const shared = x25519.getSharedSecret(viewingPrivateKey, ephPub);
+    // Fast reject via view-tag.
+    const viewTagInput = new Uint8Array(33);
+    viewTagInput[0] = 0x01;
+    viewTagInput.set(shared, 1);
+    const expectedTag = keccak_256(viewTagInput).slice(0, 2);
+    if (expectedTag[0] !== viewTag[0] || expectedTag[1] !== viewTag[1]) {
+        return null;
+    }
+    const symKey = keccak_256(shared);
+    const cipher = xchacha20poly1305(symKey, nonce, aad);
+    let plaintext;
+    try {
+        plaintext = cipher.decrypt(ciphertext);
+    }
+    catch {
+        // AEAD authentication failure — wrong key, corrupted blob, or wrong AAD.
+        return null;
+    }
+    return deserializeNote(new TextDecoder().decode(plaintext));
+}
+/**
+ * Scan an array of (commitment, encryptedNote) pairs and decrypt all notes
+ * addressed to the viewing key. Convenience helper for the wallet/facilitator.
+ *
+ * `aadFor` allows AAD binding to the commitment (default: no AAD).
+ */
+export function scanNotes(entries, viewingPrivateKey, aadFor) {
+    const out = [];
+    for (const entry of entries) {
+        const aad = aadFor ? aadFor(entry.commitment) : undefined;
+        const note = decryptNote(entry.encrypted, viewingPrivateKey, aad);
+        if (note)
+            out.push({ commitment: entry.commitment, note });
+    }
+    return out;
+}
+// -----------------------------------------------------------------------------
+// Phase 1B: AAD-bound transfer encryption
+// -----------------------------------------------------------------------------
+/**
+ * Encode a 256-bit field element as a 32-byte big-endian buffer. Mirrors
+ * Solidity's `abi.encode(uint256)` layout exactly (32 bytes, MSB first,
+ * zero-padded). Pulled in as a private helper so this module stays
+ * dependency-free of `account.ts`'s on-chain encoding utilities.
+ */
+function uint256ToBE32(value) {
+    if (value < 0n) {
+        throw new Error(`uint256ToBE32: value must be non-negative, got ${value}`);
+    }
+    const out = new Uint8Array(32);
+    let v = value;
+    for (let i = 31; i >= 0 && v > 0n; i--) {
+        out[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    if (v > 0n) {
+        throw new Error("uint256ToBE32: value exceeds 256 bits");
+    }
+    return out;
+}
+/**
+ * Build the AAD that binds a ciphertext to its on-chain commitment.
+ *
+ * Must match the value the UTXOPool contract verifies in `transfer()`:
+ *
+ *   aad = keccak256(abi.encode(outputCommitment))   (Solidity)
+ *       = keccak256(uint256ToBE32(commitment))      (TypeScript, here)
+ *
+ * Returns the 32-byte keccak256 digest. Passing the bare commitment bytes
+ * instead would still bind to the commitment but would NOT match the contract
+ * — the on-chain hash is mandatory for the Phase 1B Fix 3 ciphertext-shuffle
+ * defense to engage.
+ */
+export function commitmentAAD(commitment) {
+    return keccak_256(uint256ToBE32(commitment));
+}
+/**
+ * Convenience wrapper around `encryptNote` for the transfer use case.
+ * Auto-derives the AAD from the commitment so callers can't accidentally
+ * forget to bind. Equivalent to:
+ *
+ *   encryptNote(note, recipientPub, commitmentAAD(commitment))
+ *
+ * Use this everywhere the SDK builds `CommitmentCiphertext` for `transfer()`.
+ */
+export function encryptNoteForTransfer(note, recipientViewingPubKey, commitment) {
+    return encryptNote(note, recipientViewingPubKey, commitmentAAD(commitment));
+}
+/**
+ * Decrypt a transfer-bound ciphertext, requiring the AAD to match the given
+ * commitment. Returns `null` on:
+ *
+ *  - view-tag mismatch (fast path — not this key's note),
+ *  - AEAD authentication failure (wrong key, corrupted blob),
+ *  - AAD mismatch (relayer attempted to shuffle ciphertexts between
+ *    commitments — Phase 1B Fix 3).
+ *
+ * Callers should ALWAYS use this in the scanner, never the bare `decryptNote`,
+ * for `Transferred`-event ciphertexts. The bare form is reserved for legacy
+ * `NoteCommitted` payloads (Shipment A.1 v0) which predate AAD binding.
+ */
+export function decryptNoteWithAAD(encrypted, viewingPrivateKey, expectedCommitment) {
+    return decryptNote(encrypted, viewingPrivateKey, commitmentAAD(expectedCommitment));
+}
+// -----------------------------------------------------------------------------
+// On-chain ciphertext packing (UTXO transfer wire format)
+// -----------------------------------------------------------------------------
+//
+// The on-chain `CommitmentCiphertext.ciphertext` field is a variable-length
+// `bytes` (widened 2026-07-04 from Railgun's fixed `bytes32[4]`, which could not
+// hold zBase's ~208-byte XChaCha20 envelope — see UTXOPool.sol). The contract
+// does NOT parse these bytes; it only checks `aad`. So packing is an SDK↔scanner
+// concern: we frame the raw `EncryptedNote` blob with a 1-byte version + a
+// 4-byte big-endian length prefix, so the scanner can (a) reject a version it
+// doesn't understand and (b) validate the payload arrived intact.
+//
+//   packed = [version:1][len:4 BE][EncryptedNote blob:len]
+//
+// This is deliberately NOT Railgun's fixed 4-word slotting — that assumes a
+// fixed-size plaintext zBase doesn't have. A length-prefixed blob round-trips
+// any envelope size and is forward-compatible.
+/** Wire-format version for packed transfer ciphertexts. */
+export const CIPHERTEXT_WIRE_VERSION = 1;
+/**
+ * Frame an EncryptedNote for the on-chain `CommitmentCiphertext.ciphertext`
+ * field. Returns a 0x-hex string ready to pass as Solidity `bytes`.
+ */
+export function packCiphertext(encrypted) {
+    if (!(encrypted instanceof Uint8Array) || encrypted.length === 0) {
+        throw new Error("packCiphertext: EncryptedNote must be a non-empty Uint8Array");
+    }
+    if (encrypted.length > 0xffffffff) {
+        throw new Error("packCiphertext: envelope too large");
+    }
+    const out = new Uint8Array(5 + encrypted.length);
+    out[0] = CIPHERTEXT_WIRE_VERSION;
+    const len = encrypted.length;
+    out[1] = (len >>> 24) & 0xff;
+    out[2] = (len >>> 16) & 0xff;
+    out[3] = (len >>> 8) & 0xff;
+    out[4] = len & 0xff;
+    out.set(encrypted, 5);
+    let hex = "0x";
+    for (const b of out)
+        hex += b.toString(16).padStart(2, "0");
+    return hex;
+}
+/**
+ * Inverse of packCiphertext: recover the EncryptedNote blob from the on-chain
+ * `bytes`. Returns null on malformed / wrong-version / length-mismatch input
+ * (a scanner should skip, not throw, on a payload it can't parse).
+ */
+export function unpackCiphertext(packedHex) {
+    const hex = packedHex.startsWith("0x") ? packedHex.slice(2) : packedHex;
+    if (hex.length % 2 !== 0 || hex.length < 10)
+        return null; // need at least the 5-byte header
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        const byte = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+        if (Number.isNaN(byte))
+            return null;
+        bytes[i] = byte;
+    }
+    if (bytes[0] !== CIPHERTEXT_WIRE_VERSION)
+        return null;
+    const len = (bytes[1] << 24) | (bytes[2] << 16) | (bytes[3] << 8) | bytes[4];
+    if (len <= 0 || 5 + len !== bytes.length)
+        return null; // length must match exactly
+    return bytes.slice(5);
+}

package/dist/npk.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @zbase-protocol/core — Recipient NPK derivation (audit C3).
+ *
+ * The v1 UTXO commitment is `Poseidon3(amount, NPK, secret)` where
+ * `NPK = Poseidon2(spendingPK, viewingPKBlind)` (matches `note_spend.circom`
+ * NpkBuilder + CommitmentHasher — see `notes.ts`). Phase 1A pinned the *hash
+ * structure*; this module closes the remaining "auditor-scoped gap" noted in
+ * `notes.ts`: HOW `spendingPK` / `viewingPKBlind` are DERIVED from a recipient's
+ * published key material.
+ *
+ * ## Recipe (Railgun-style note-public-key)
+ *
+ *   spendingPK     = field(keccak("zBase/npk/spendingPK/v1" || recipientSpendPub))
+ *   ephemeral      = fresh X25519 keypair (per note)
+ *   shared         = X25519(ephemeralPriv, recipientViewingPub)
+ *   viewingPKBlind = field(keccak("zBase/npk/viewingPKBlind/v1" || shared))
+ *   NPK            = Poseidon2(spendingPK, viewingPKBlind)
+ *
+ * Two properties this buys:
+ *
+ *  1. **Unlinkability.** `viewingPKBlind` is a fresh ECDH blind per note, so two
+ *     notes to the same recipient produce different NPKs → different commitments.
+ *     An on-chain observer cannot cluster a recipient's incoming notes.
+ *  2. **Recoverability.** The recipient publishes `ephemeralPublicKey` alongside
+ *     the note (it already rides in the `encryptNote` blob — see `notes.ts`
+ *     EncryptedNote layout, bytes [0..32)). With their viewing PRIVATE key they
+ *     recompute the same `shared` → the same `viewingPKBlind` → the same NPK →
+ *     the same commitment, confirming the note is theirs and that they can later
+ *     prove `NPK = Poseidon2(spendingPK, viewingPKBlind)` in-circuit.
+ *
+ * `spendingPK` is long-lived (it identifies the recipient's spend authority and
+ * is constant across their notes); only `viewingPKBlind` is per-note. This is the
+ * standard Railgun split: the spending key authorizes movement, the blinded
+ * viewing key provides per-note privacy.
+ *
+ * ## What this is NOT
+ *
+ * The recipient's `spendingPublicKey` is a field element the recipient publishes
+ * (e.g., a Poseidon/Baby-Jubjub spend pubkey in a full wallet). zBase does not
+ * yet ship a spending-key HD scheme (only the X25519 viewing key — see
+ * `viewingKeyHD.ts`), so callers supply `recipientSpendingPubKey` explicitly.
+ * Until a spending-key tree lands, a recipient MAY reuse a stable field element
+ * (e.g., a hash of their viewing pubkey) as their spendingPK — at the cost of the
+ * spend-authority separation, NOT of the per-note unlinkability (which comes from
+ * the viewing blind). The derivation here is agnostic to that choice.
+ *
+ * ⚠️ AUDITOR NOTE: this is the SDK-side NPK derivation the circuit comment in
+ * `note_spend.circom` (NpkBuilder) and `notes.ts` defer to the external audit.
+ * The *circuit* only sees the resulting `NPK` field element; this module decides
+ * how it is built off-chain. It must be reviewed before the UTXO pool goes live.
+ */
+/**
+ * Reduce arbitrary bytes to a BN254 scalar-field element via a domain-separated
+ * keccak, using DETERMINISTIC rejection sampling for a uniform result.
+ *
+ * audit-sweep-2026-06-17 (was a latent MED): the previous version did a naive
+ * `keccak(...) % SNARK_SCALAR_FIELD` and a comment claimed the bias was
+ * "< 2^-253". That was wrong by ~250 bits: r ≈ 2^253.6, so 2^256 / r = 5 with a
+ * large remainder — the lowest ~29% of the field is over-represented, giving a
+ * statistical distance of ~2^-4.2 (~5.4%), not 2^-253. For `spendingPK` (public
+ * input) the bias is cosmetic, but `viewingPKBlind` is derived from a SECRET
+ * (the X25519 shared secret), so a biased reduction on a secret-derived witness
+ * is a real (if bounded) uniformity weakness. We now reject any digest in the
+ * "extra" top band [LIMIT, 2^256) and re-hash with an incrementing counter byte,
+ * so every accepted value is uniform over [0, r). The counter keeps it fully
+ * deterministic — the recipient recomputes the identical element. Expected
+ * iterations ≈ 1.25; the loop is bounded defensively.
+ */
+export declare function bytesToField(domain: string, bytes: Uint8Array): bigint;
+/** The NPK inputs plus the ephemeral pubkey the recipient needs to recover them. */
+export interface DerivedNPK {
+    /** Long-lived recipient spend authority, as a field element. */
+    spendingPK: bigint;
+    /** Per-note blinded viewing pubkey, as a field element. */
+    viewingPKBlind: bigint;
+    /**
+     * Sender's per-note ephemeral X25519 public key (32 bytes). MUST be published
+     * with the note so the recipient can recompute `viewingPKBlind`. In a transfer
+     * this is the same ephemeral key `encryptNote` embeds; callers MAY pass that
+     * key in via `ephemeralPrivateKey` to avoid generating two.
+     */
+    ephemeralPublicKey: Uint8Array;
+}
+export interface DeriveRecipientNPKParams {
+    /**
+     * Recipient's published viewing PUBLIC key (32-byte X25519). Same key used by
+     * `encryptNote` to encrypt the note payload.
+     */
+    recipientViewingPubKey: Uint8Array;
+    /**
+     * Recipient's long-lived spending public key, as a field element. The caller
+     * obtains this from the recipient's published address material. See the module
+     * doc for the "reuse a stable field element" interim option.
+     */
+    recipientSpendingPubKey: bigint;
+    /**
+     * Optional: reuse a specific ephemeral private key (e.g., the one `encryptNote`
+     * will use) so the note carries ONE ephemeral pubkey. If omitted, a fresh
+     * 32-byte key is generated. MUST be 32 bytes.
+     */
+    ephemeralPrivateKey?: Uint8Array;
+}
+/**
+ * Derive a recipient's NPK inputs for a fresh outbound note.
+ *
+ * Deterministic given (recipientViewingPubKey, recipientSpendingPubKey,
+ * ephemeralPrivateKey): pass a fixed ephemeral key to get reproducible output
+ * (used by tests + by the witness fixture builder). With no ephemeral key it is
+ * non-deterministic (fresh per-note blind), which is the production default.
+ */
+export declare function deriveRecipientNPK(params: DeriveRecipientNPKParams): DerivedNPK;
+/**
+ * Recipient-side recovery of `viewingPKBlind` from the published ephemeral
+ * pubkey + the recipient's viewing PRIVATE key. Recomputes the same ECDH shared
+ * secret the sender used, so the recipient can reconstruct the NPK (and hence the
+ * commitment) and confirm the note is addressed to them.
+ *
+ *   shared = X25519(viewingPriv, ephemeralPub)   // == sender's X25519(ephPriv, viewingPub)
+ *   viewingPKBlind = field(keccak(DST || shared))
+ */
+export declare function recoverViewingPKBlind(viewingPrivateKey: Uint8Array, ephemeralPublicKey: Uint8Array): bigint;