@zbase-protocol/core 0.1.0

package/dist/npk.js

@@ -0,0 +1,166 @@
+/**
+ * @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.
+ */
+import { x25519 } from "@noble/curves/ed25519";
+import { keccak_256 } from "@noble/hashes/sha3";
+import { randomBytes } from "@noble/hashes/utils";
+import { SNARK_SCALAR_FIELD } from "./account.js";
+// Domain-separation tags — keep each derivation distinct so no two keccak uses of
+// the same input can collide (mirrors notes.ts's view-tag domain separation).
+const DST_SPENDING_PK = "zBase/npk/spendingPK/v1";
+const DST_VIEWING_BLIND = "zBase/npk/viewingPKBlind/v1";
+/**
+ * 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 function bytesToField(domain, bytes) {
+    const tag = new TextEncoder().encode(domain);
+    // Largest multiple of r that fits in 256 bits; digests >= LIMIT are rejected
+    // so the accepted range maps uniformly onto [0, r).
+    const TWO_256 = 1n << 256n;
+    const LIMIT = TWO_256 - (TWO_256 % SNARK_SCALAR_FIELD);
+    // 256 counter values is astronomically more than ever needed (P(reject) < 1/5
+    // per try); throw rather than bias if somehow exhausted.
+    for (let counter = 0; counter < 256; counter++) {
+        const input = new Uint8Array(tag.length + bytes.length + 1);
+        input.set(tag, 0);
+        input.set(bytes, tag.length);
+        input[tag.length + bytes.length] = counter; // domain ⊕ bytes ⊕ counter
+        const h = keccak_256(input);
+        let v = 0n;
+        for (const byte of h)
+            v = (v << 8n) | BigInt(byte);
+        if (v < LIMIT)
+            return v % SNARK_SCALAR_FIELD;
+    }
+    throw new Error("bytesToField: rejection sampling exhausted (unreachable)");
+}
+/**
+ * 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 function deriveRecipientNPK(params) {
+    const { recipientViewingPubKey, recipientSpendingPubKey } = params;
+    if (recipientViewingPubKey.length !== 32) {
+        throw new Error("deriveRecipientNPK: recipientViewingPubKey must be 32 bytes (X25519)");
+    }
+    if (recipientSpendingPubKey < 0n ||
+        recipientSpendingPubKey >= SNARK_SCALAR_FIELD) {
+        throw new Error("deriveRecipientNPK: recipientSpendingPubKey must be a field element in [0, r)");
+    }
+    const ephPriv = params.ephemeralPrivateKey ?? randomBytes(32);
+    if (ephPriv.length !== 32) {
+        throw new Error("deriveRecipientNPK: ephemeralPrivateKey must be 32 bytes");
+    }
+    const ephemeralPublicKey = x25519.getPublicKey(ephPriv);
+    // spendingPK: long-lived, domain-separated reduction of the recipient's spend
+    // pubkey into the field. Constant across the recipient's notes.
+    const spendingPK = bytesToField(DST_SPENDING_PK, feToBE32(recipientSpendingPubKey));
+    // viewingPKBlind: per-note ECDH blind. shared = X25519(ephPriv, recipientView).
+    const shared = x25519.getSharedSecret(ephPriv, recipientViewingPubKey);
+    const viewingPKBlind = bytesToField(DST_VIEWING_BLIND, shared);
+    return { spendingPK, viewingPKBlind, ephemeralPublicKey };
+}
+/**
+ * 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 function recoverViewingPKBlind(viewingPrivateKey, ephemeralPublicKey) {
+    if (viewingPrivateKey.length !== 32) {
+        throw new Error("recoverViewingPKBlind: viewingPrivateKey must be 32 bytes");
+    }
+    if (ephemeralPublicKey.length !== 32) {
+        throw new Error("recoverViewingPKBlind: ephemeralPublicKey must be 32 bytes");
+    }
+    const shared = x25519.getSharedSecret(viewingPrivateKey, ephemeralPublicKey);
+    return bytesToField(DST_VIEWING_BLIND, shared);
+}
+/**
+ * Big-endian 32-byte encoding of a field element. Local copy of `account.ts`'s
+ * `feToBE32` value semantics (kept here to avoid a string round-trip — account's
+ * takes string|bigint and returns via a different path) so the spendingPK
+ * reduction has a fixed-width, canonical input.
+ */
+function feToBE32(value) {
+    if (value < 0n)
+        throw new Error("feToBE32: value must be non-negative");
+    const out = new Uint8Array(32);
+    let v = value;
+    for (let i = 31; i >= 0; i--) {
+        out[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    if (v !== 0n)
+        throw new Error("feToBE32: value exceeds 32 bytes");
+    return out;
+}

package/dist/proofs.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @zbase-protocol/core — Chain-agnostic ZK proof generation
+ *
+ * Uses snarkjs for Groth16 proof generation. The circuits are universal:
+ * same WASM + zkey files work regardless of which chain the proof is verified on.
+ *
+ * snarkjs is an OPTIONAL dependency (SDK audit 2026-07-09): it is ~9 MB and only
+ * needed by consumers who actually GENERATE a proof. It is loaded LAZILY inside
+ * the two functions below, so a consumer using only the Poseidon/Merkle/stealth/
+ * facilitator primitives never pulls it in. If snarkjs isn't installed, the lazy
+ * import throws a clear message pointing the consumer to add it.
+ */
+/**
+ * Inputs to the upstream withdraw.circom (template `Withdraw(maxTreeDepth=32)`).
+ * Order and names mirror the circuit's signal declarations exactly. Padding:
+ * `stateSiblings` and `ASPSiblings` MUST be padded with zeros to length 32.
+ *
+ * Public signals returned by snarkjs (in order):
+ *   [0] newCommitmentHash       (output)
+ *   [1] existingNullifierHash   (output)
+ *   [2] withdrawnValue
+ *   [3] stateRoot
+ *   [4] stateTreeDepth
+ *   [5] ASPRoot
+ *   [6] ASPTreeDepth
+ *   [7] context
+ */
+export interface ProofInput {
+    withdrawnValue: string;
+    stateRoot: string;
+    stateTreeDepth: string;
+    ASPRoot: string;
+    ASPTreeDepth: string;
+    context: string;
+    label: string;
+    existingValue: string;
+    existingNullifier: string;
+    existingSecret: string;
+    newNullifier: string;
+    newSecret: string;
+    stateSiblings: string[];
+    stateIndex: string;
+    ASPSiblings: string[];
+    ASPIndex: string;
+}
+export interface Groth16Proof {
+    pi_a: [string, string];
+    pi_b: [[string, string], [string, string]];
+    pi_c: [string, string];
+    protocol: "groth16";
+    curve: "bn128";
+}
+export interface ProofResult {
+    proof: Groth16Proof;
+    publicSignals: string[];
+    proofTimeMs: number;
+}
+/**
+ * Generate a Groth16 withdrawal proof.
+ * Chain-agnostic: works for both EVM and Solana verifiers.
+ */
+export declare function generateWithdrawalProof(input: ProofInput, wasmPath: string, zkeyPath: string): Promise<ProofResult>;
+/**
+ * Verify a Groth16 proof locally (for testing, not on-chain verification).
+ */
+export declare function verifyProofLocally(proof: Groth16Proof, publicSignals: string[], vkeyPath: string): Promise<boolean>;

package/dist/proofs.js

@@ -0,0 +1,45 @@
+/**
+ * @zbase-protocol/core — Chain-agnostic ZK proof generation
+ *
+ * Uses snarkjs for Groth16 proof generation. The circuits are universal:
+ * same WASM + zkey files work regardless of which chain the proof is verified on.
+ *
+ * snarkjs is an OPTIONAL dependency (SDK audit 2026-07-09): it is ~9 MB and only
+ * needed by consumers who actually GENERATE a proof. It is loaded LAZILY inside
+ * the two functions below, so a consumer using only the Poseidon/Merkle/stealth/
+ * facilitator primitives never pulls it in. If snarkjs isn't installed, the lazy
+ * import throws a clear message pointing the consumer to add it.
+ */
+import { createRequire } from "node:module";
+async function loadSnarkjs() {
+    try {
+        const requireCjs = createRequire(import.meta.url);
+        return requireCjs("snarkjs");
+    }
+    catch {
+        throw new Error("snarkjs is required for proof generation but is not installed. " +
+            "It is an optional dependency of @zbase-protocol/core — run `npm i snarkjs` to enable generateWithdrawalProof/verifyProofLocally.");
+    }
+}
+/**
+ * Generate a Groth16 withdrawal proof.
+ * Chain-agnostic: works for both EVM and Solana verifiers.
+ */
+export async function generateWithdrawalProof(input, wasmPath, zkeyPath) {
+    const startTime = Date.now();
+    const snarkjs = await loadSnarkjs();
+    const { proof, publicSignals } = await snarkjs.groth16.fullProve(input, wasmPath, zkeyPath);
+    return {
+        proof: proof,
+        publicSignals: publicSignals,
+        proofTimeMs: Date.now() - startTime,
+    };
+}
+/**
+ * Verify a Groth16 proof locally (for testing, not on-chain verification).
+ */
+export async function verifyProofLocally(proof, publicSignals, vkeyPath) {
+    const snarkjs = await loadSnarkjs();
+    const vkey = await fetch(vkeyPath).then((r) => r.json());
+    return snarkjs.groth16.verify(vkey, publicSignals, proof);
+}

package/dist/stealth.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @zbase-protocol/core — ERC-5564 stealth addresses (scheme id 1, secp256k1)
+ *
+ * Implements the canonical ERC-5564 scheme 1 ("secp256k1-1") as deployed by
+ * ScopeLift / Umbra / Fluidkey, the same scheme audited by Trail of Bits.
+ * Spec: https://eips.ethereum.org/EIPS/eip-5564
+ *
+ * The scheme:
+ *   - Provider holds two secp256k1 keypairs: spending (k_s, K_s) and viewing (k_v, K_v).
+ *   - Meta-address encodes the two compressed public keys as
+ *       st:<chain>:0x<spendingPubKey:33B><viewingPubKey:33B>      // 132 hex chars
+ *   - For each payment the facilitator (sender) generates a fresh ephemeral
+ *     keypair (r, R = r·G), computes the ECDH shared point S = r · K_v,
+ *     hashes it: s_h = keccak256(S_compressed). The view tag is s_h[0].
+ *   - The stealth public key is P = K_s + s_h · G. The stealth Ethereum
+ *     address is the standard keccak256(uncompressed-pub-key-without-prefix)[12:].
+ *   - The provider scans Announcement events, recomputes S = k_v · R for
+ *     each ephemeral pubkey, checks the view tag, and (on match) derives the
+ *     stealth private key as k = (k_s + s_h) mod n.
+ *
+ * Why this matters: today every payment to OpenAI's x402 endpoint pays the
+ * same address; an outside observer maps "wallet X pays Nansen every 60s".
+ * After this ship, every payment to the same provider lands on a different
+ * stealth address derived from their registered meta-address — the buyer
+ * sees a single endpoint, the chain sees N unrelated recipients.
+ *
+ * Security boundary: the viewing private key never leaves the provider.
+ * An attacker who controls the facilitator AND knows the viewing key can
+ * correlate ephemeralPubkey → stealth recipient. Without the viewing key,
+ * the link is computationally hidden by the discrete-log assumption on
+ * secp256k1 (same assumption Ethereum signatures rely on).
+ */
+/** ERC-5564 scheme identifier. Only scheme 1 (secp256k1 + keccak256) is supported. */
+export declare const STEALTH_SCHEME_ID: 1;
+/** Default chain tag used in meta-address URIs ("st:<chain>:0x..."). */
+export declare const DEFAULT_CHAIN_TAG = "base";
+export interface StealthMetaAddress {
+    /** "st:base:0x<spendingPubKey:33B><viewingPubKey:33B>" */
+    metaAddress: string;
+    /** Hex-encoded compressed public key (66 hex chars, with 0x prefix). */
+    spendingPublicKey: string;
+    /** Hex-encoded compressed public key (66 hex chars, with 0x prefix). */
+    viewingPublicKey: string;
+}
+export interface StealthMetaAddressWithPrivate extends StealthMetaAddress {
+    /** Provider-only. Required to compute stealth private keys; NEVER share. */
+    spendingPrivateKey: string;
+    /** Provider-only. Required to scan; can be delegated to a view-only scanner. */
+    viewingPrivateKey: string;
+}
+export interface DerivedStealthAddress {
+    /** 0x-prefixed 20-byte Ethereum address. */
+    stealthAddress: string;
+    /** Hex-encoded compressed ephemeral public key R = r·G (66 hex chars). */
+    ephemeralPublicKey: string;
+    /** 1 byte (2 hex chars), most-significant byte of the hashed shared secret. */
+    viewTag: string;
+}
+export interface ScanMatch {
+    /** Index into the input `recentEphemeralPubkeys` array. */
+    index: number;
+    /** The ephemeral pubkey that produced this match (echoed back for convenience). */
+    ephemeralPublicKey: string;
+    /** The stealth Ethereum address derived from this ephemeral pubkey. */
+    stealthAddress: string;
+    /** The view tag observed for this ephemeral pubkey. */
+    viewTag: string;
+}
+/**
+ * Produce a fresh ERC-5564 meta-address from an optional seed.
+ *
+ * The seed is intentionally optional: passing a deterministic seed enables
+ * reproducible tests; omitting it pulls 64 bytes of OS randomness. Either
+ * way, both keys live for the life of the provider — they are NOT rotated
+ * per call.
+ *
+ * @param seed Optional 64-byte Uint8Array. First 32 bytes seed the spending
+ *   key, last 32 bytes seed the viewing key. If omitted, secure random.
+ */
+export declare function generateMetaAddress(seed?: Uint8Array, chainTag?: string): StealthMetaAddressWithPrivate;
+/**
+ * Parse a "st:<chain>:0x<spending:33B><viewing:33B>" meta-address URI.
+ * Accepts either the full URI or a bare 0x-prefixed 132-hex-char string.
+ */
+export declare function parseMetaAddress(metaAddress: string): {
+    chainTag: string;
+    spendingPublicKey: Uint8Array;
+    viewingPublicKey: Uint8Array;
+};
+/**
+ * Quick sniff test: is this string an ERC-5564 meta-address (vs a plain
+ * 0x-address)? Used by the facilitator to decide which path to take.
+ */
+export declare function isStealthMetaAddress(s: unknown): s is string;
+/**
+ * Derive a fresh stealth address for a provider, given their meta-address
+ * and a 32-byte ephemeral nonce (= ephemeral private key r).
+ *
+ * The facilitator publishes `ephemeralPublicKey` on-chain alongside the
+ * payment; the provider scans for it and recovers the funds. The nonce
+ * MUST be unpredictable to anyone but the facilitator and MUST NOT repeat
+ * (a repeat collapses two payments to the same stealth address, leaking
+ * the link). Pass `undefined` to generate a fresh CSPRNG nonce.
+ *
+ * @param metaAddress provider's "st:base:0x..." meta-address
+ * @param ephemeralNonce 32-byte scalar, or undefined for fresh randomness
+ */
+export declare function deriveStealthAddress(metaAddress: string, ephemeralNonce?: Uint8Array): DerivedStealthAddress;
+/**
+ * Given the provider's viewing private key and a batch of recent ephemeral
+ * pubkeys (from on-chain Announcement events or facilitator settle logs),
+ * return the stealth addresses that belong to this provider.
+ *
+ * View-tag optimization: if `expectedViewTags` is supplied, each candidate
+ * is filtered on its 1-byte view tag before the (more expensive) point add.
+ * This reduces scan cost by ~256× when most announcements aren't ours.
+ *
+ * @param viewingPrivateKey provider's viewing private key (32 bytes or hex)
+ * @param recentEphemeralPubkeys array of compressed ephemeral pubkeys
+ * @param spendingPublicKey provider's spending public key (needed to derive
+ *        the stealth address from the shared secret)
+ * @param expectedViewTags optional array (same length as recentEphemeralPubkeys);
+ *        if a tag is provided and doesn't match, the entry is skipped without
+ *        doing the point arithmetic
+ */
+export declare function scanForPayments(viewingPrivateKey: Uint8Array | string, recentEphemeralPubkeys: Array<Uint8Array | string>, spendingPublicKey: Uint8Array | string, expectedViewTags?: Array<Uint8Array | string | undefined>): ScanMatch[];
+/**
+ * Given the provider's spending+viewing private keys and an ephemeral pubkey
+ * that's known to belong to this provider, derive the stealth address's
+ * private key. With this key the provider can sweep funds to a treasury.
+ *
+ *   k_stealth = (k_s + keccak256(k_v · R)) mod n
+ *
+ * @returns 32-byte stealth private key (raw bytes; 0x-encode if you need hex)
+ */
+export declare function computeStealthPrivateKey(spendingPrivateKey: Uint8Array | string, viewingPrivateKey: Uint8Array | string, ephemeralPublicKey: Uint8Array | string): Uint8Array;