@zbase-protocol/core 0.1.0

package/dist/merkle.js

@@ -0,0 +1,84 @@
+/**
+ * @zbase-protocol/core — Chain-agnostic Merkle tree operations
+ *
+ * Uses Lean Incremental Merkle Tree (lean-imt) with Poseidon hashing.
+ * Same tree structure works for both EVM and Solana verifiers.
+ */
+import { LeanIMT } from "@zk-kit/lean-imt";
+import { poseidon2 } from "poseidon-lite";
+const TREE_DEPTH = 32;
+/**
+ * Build a Merkle tree from leaf values (commitments).
+ * The hash function (Poseidon2) is identical across chains.
+ */
+export function buildMerkleTree(leaves) {
+    const hash = (a, b) => poseidon2([a, b]);
+    const tree = new LeanIMT(hash);
+    for (const leaf of leaves) {
+        tree.insert(leaf);
+    }
+    return tree;
+}
+/**
+ * Generate a Merkle proof for a leaf, shaped for `note_spend.circom`'s
+ * `LeanIMTInclusionProof(levels=TREE_DEPTH)`.
+ *
+ * B3 fix (audit-sweep-2026-06-17): zk-kit's `generateProof` returns a
+ * **compacted** proof — levels where the leaf has no right sibling are DROPPED
+ * from `siblings`, and `proof.index` is **recomputed** over only the surviving
+ * path bits (it is NOT the raw `leafIndex`). The circuit walks `actualDepth`
+ * real levels, decomposing `index` into bits and pairing bit `lvl` with
+ * `siblings[lvl]` — exactly the compacted shape. The previous implementation
+ * fed the RAW `leafIndex` bits alongside the compacted-then-zero-padded
+ * siblings; for any leaf whose path crosses a dropped level the index bits and
+ * siblings misaligned, producing a wrong root and an unsatisfiable witness.
+ * (It only worked for left-spine leaves where `proof.index === leafIndex` and
+ * no level is dropped — which is why the original committed fixture passed.)
+ *
+ * Correct mapping, matching zk-kit's own `verifyProof`:
+ *   - `index`       = proof.index            (compacted path, NOT leafIndex)
+ *   - `actualDepth` = siblings.length        (number of real levels)
+ *   - `siblings`    = proof.siblings, zero-padded to TREE_DEPTH
+ *   - `pathIndices` = bits of proof.index over TREE_DEPTH levels
+ *
+ * `actualDepth` and `index` are returned alongside so the witness builder can
+ * feed the circuit's `actualDepth`/`index` inputs directly.
+ */
+export function generateMerkleProof(tree, leafIndex) {
+    const proof = tree.generateProof(leafIndex);
+    const siblings = proof.siblings.map((s) => Array.isArray(s) ? s[0] : s);
+    // F12: a LeanIMT proof has `depth` siblings (variable with tree size), but the
+    // fixed-depth circuit expects exactly TREE_DEPTH padded siblings. Validate we
+    // don't EXCEED the circuit depth (would silently truncate / produce a wrong
+    // root), then zero-pad up to TREE_DEPTH (the LeanIMT "no right sibling"
+    // sentinel is 0, matching the circuit's padding convention).
+    if (siblings.length > TREE_DEPTH) {
+        throw new Error(`merkle: proof depth ${siblings.length} exceeds circuit TREE_DEPTH ${TREE_DEPTH}`);
+    }
+    const actualDepth = siblings.length;
+    const index = proof.index; // compacted path index (NOT leafIndex)
+    // pathIndices = bits of the COMPACTED index over TREE_DEPTH levels. Bits at or
+    // above actualDepth are 0 (the circuit's `active[lvl]` gate ignores them).
+    const pathIndices = [];
+    let idx = index;
+    for (let i = 0; i < TREE_DEPTH; i++) {
+        pathIndices.push(idx & 1);
+        idx >>= 1;
+    }
+    const paddedElements = siblings.slice();
+    while (paddedElements.length < TREE_DEPTH)
+        paddedElements.push(0n);
+    return {
+        pathElements: paddedElements,
+        pathIndices,
+        index,
+        actualDepth,
+        root: tree.root,
+    };
+}
+/**
+ * Get the tree depth constant.
+ */
+export function getTreeDepth() {
+    return TREE_DEPTH;
+}

package/dist/noteScanner.d.ts

@@ -0,0 +1,206 @@
+/**
+ * @zbase-protocol/core — WebSocket UTXO note scanner (Phase 1B)
+ *
+ * Subscribes to a UTXOPool's `Spent` and `Transferred` events over a WS RPC,
+ * trial-decrypts every transferred ciphertext with the user's viewing key,
+ * and yields decrypted notes as an async iterable. Wallets and facilitators
+ * use this to track balance + spendable notes without polling.
+ *
+ * Naming: this file is `noteScanner.ts` (NOT `scanner.ts`) because
+ * `scanner.ts` is already in use for the chain-agnostic x402-exposure scorer.
+ * The two scanners do unrelated things; consolidating later is a separate
+ * refactor and would break public API.
+ *
+ * Transport: we depend ONLY on the WHATWG `WebSocket` global (available in
+ * browser, Node ≥22 native, Cloudflare Workers, Bun). No `ethers` or `viem`
+ * import is needed for the WS layer — both libraries would force a heavier
+ * dependency surface and we already speak JSON-RPC. ABI encoding/decoding of
+ * event logs is done by hand for the two specific events we care about. If
+ * this proves brittle, the next iteration can swap to viem's `decodeEventLog`
+ * (already a root dependency of the consuming Next.js app).
+ *
+ * Reconnect policy: exponential backoff capped at 30 s. The async iterable
+ * yields a `{type:"connected"}` marker on every successful (re)connect so
+ * callers can persist the last-seen block and replay if they care about
+ * historical correctness across disconnects.
+ */
+import { type Note, type ViewingKeyPair } from "./notes.js";
+/** Connection lifecycle marker. Emitted on every (re)connect. */
+export interface ScannerConnectedEvent {
+    type: "connected";
+    reconnectAttempt: number;
+    /** Block height to start replaying historical events from, if any. */
+    startBlock: bigint;
+}
+/** A `Spent` log was observed. No ciphertext to decrypt — just nullifier hashes. */
+export interface ScannerSpentEvent {
+    type: "spent";
+    nullifierHash0: bigint;
+    nullifierHash1: bigint;
+    withdrawnAmount: bigint;
+    outputCommitment0: bigint;
+    outputCommitment1: bigint;
+    blockNumber: bigint;
+    txHash: string;
+    logIndex: number;
+}
+/** A `Transferred` log was observed AND one ciphertext decrypted for us. */
+export interface ScannerTransferredInEvent {
+    type: "transferred-in";
+    /** Which of the two outputs decrypted (0 or 1). */
+    outputIndex: 0 | 1;
+    commitment: bigint;
+    note: Note;
+    /** The other nullifier hash from the same spend — useful for de-duping. */
+    siblingNullifierHash: bigint;
+    blockNumber: bigint;
+    txHash: string;
+    logIndex: number;
+}
+/** A `Transferred` log was observed but neither ciphertext was ours. */
+export interface ScannerTransferredOtherEvent {
+    type: "transferred-other";
+    outputCommitment0: bigint;
+    outputCommitment1: bigint;
+    blockNumber: bigint;
+    txHash: string;
+    logIndex: number;
+}
+/** Non-fatal error (parse failure, malformed log, etc.) — caller may ignore. */
+export interface ScannerErrorEvent {
+    type: "error";
+    message: string;
+    cause?: unknown;
+}
+export type ScannerEvent = ScannerConnectedEvent | ScannerSpentEvent | ScannerTransferredInEvent | ScannerTransferredOtherEvent | ScannerErrorEvent;
+/**
+ * Spent(uint256,uint256,uint256,uint256,uint256)
+ * Two indexed nullifier hashes + non-indexed (amount, commitment0, commitment1).
+ */
+export declare const SPENT_TOPIC: string;
+/**
+ * Transferred(uint256,uint256,uint256,uint256,(bytes32[4],bytes32,bytes32,bytes32,bytes32),(bytes32[4],bytes32,bytes32,bytes32,bytes32))
+ *
+ * The two `CommitmentCiphertext` structs are ABI-encoded as tuples. This is
+ * the canonical event-signature form Solidity uses for keccak256(topic[0]).
+ */
+export declare const TRANSFERRED_TOPIC: string;
+export interface ScannerOptions {
+    /** ws:// or wss:// JSON-RPC endpoint. */
+    wsUrl: string;
+    /** UTXOPool contract address (0x-prefixed, 20 bytes). */
+    utxoPoolAddress: string;
+    /** Viewing key to trial-decrypt every Transferred ciphertext against. */
+    viewingKey: Pick<ViewingKeyPair, "privateKey">;
+    /** Block to start subscription from (default: latest). */
+    fromBlock?: bigint;
+    /** Custom abort signal to terminate the scanner. */
+    signal?: AbortSignal;
+    /** Override the reconnect backoff sequence (ms). Default: [1000, 2000, 4000, 8000, 16000, 30000] capped. */
+    reconnectBackoffMs?: readonly number[];
+    /** Pluggable WebSocket constructor (for tests). Default: globalThis.WebSocket. */
+    webSocketCtor?: typeof WebSocket;
+}
+/**
+ * Decode the data field of a `Spent` log:
+ *   words: [withdrawnAmount, outputCommitment0, outputCommitment1]
+ * The two indexed nullifier hashes live in `topics[1..3]`, not in data.
+ */
+export declare function decodeSpentLog(log: {
+    topics: readonly string[];
+    data: string;
+    blockNumber: string;
+    transactionHash: string;
+    logIndex: string;
+}): Omit<ScannerSpentEvent, "type">;
+/**
+ * Decode a Transferred log into raw fields + the two ciphertext blobs ready
+ * for trial decryption.
+ *
+ * Layout (non-indexed args, packed as one ABI-encoded tuple):
+ *
+ *   word 0   outputCommitment0
+ *   word 1   outputCommitment1
+ *   word 2   ciphertext0.ciphertext[0]
+ *   word 3   ciphertext0.ciphertext[1]
+ *   word 4   ciphertext0.ciphertext[2]
+ *   word 5   ciphertext0.ciphertext[3]
+ *   word 6   ciphertext0.blindedSenderViewingKey
+ *   word 7   ciphertext0.blindedReceiverViewingKey
+ *   word 8   ciphertext0.memo
+ *   word 9   ciphertext0.aad
+ *   word 10  ciphertext1.ciphertext[0]
+ *   ...
+ *   word 17  ciphertext1.aad
+ *
+ * The 8-word `CommitmentCiphertext` struct is encoded inline (no offset
+ * indirection) because every field is a fixed-size value type — Solidity
+ * inlines such tuples.
+ *
+ * The ciphertext blob we feed to `decryptNoteWithAAD` is the concatenation
+ * of bytes32[4] (the four word ciphertext slots). See UTXOPool.sol comment
+ * on `CommitmentCiphertext` for the per-word convention.
+ */
+export interface DecodedTransferredLog {
+    nullifierHash0: bigint;
+    nullifierHash1: bigint;
+    outputCommitment0: bigint;
+    outputCommitment1: bigint;
+    ciphertext0Blob: Uint8Array;
+    ciphertext0Aad: Uint8Array;
+    ciphertext1Blob: Uint8Array;
+    ciphertext1Aad: Uint8Array;
+    blockNumber: bigint;
+    txHash: string;
+    logIndex: number;
+}
+export declare function decodeTransferredLog(log: {
+    topics: readonly string[];
+    data: string;
+    blockNumber: string;
+    transactionHash: string;
+    logIndex: string;
+}): DecodedTransferredLog;
+/**
+ * Trial-decrypt both ciphertexts of a Transferred log against the viewing
+ * key. Returns the matching event or `null` if neither ciphertext belongs to
+ * this wallet.
+ *
+ * The encrypted blob fed to `decryptNoteWithAAD` is the on-chain wire format
+ * that `encryptNoteForTransfer` produces — see notes.ts `EncryptedNote`
+ * layout. The contract stores it spread across four bytes32 words; we
+ * reassemble it back into the linear byte buffer here.
+ *
+ * Phase 1B caveat: the v0 `encryptNote` envelope (ephPub|viewTag|nonce|ct)
+ * does not yet fit neatly inside bytes32[4]. A follow-up will define a
+ * compact wire layout; the v0 wire is the linear blob and that's what we
+ * decode here. The hand-decoder above is a placeholder that will need to
+ * track that schema once it's frozen.
+ */
+export declare function tryDecryptTransferred(decoded: DecodedTransferredLog, viewingPrivateKey: Uint8Array): ScannerTransferredInEvent | ScannerTransferredOtherEvent;
+/**
+ * Create an async iterable scanner over a UTXOPool's events.
+ *
+ * Usage:
+ * ```ts
+ * for await (const ev of createScanner({ wsUrl, utxoPoolAddress, viewingKey })) {
+ *   if (ev.type === "transferred-in") {
+ *     wallet.addNote(ev.commitment, ev.note);
+ *   } else if (ev.type === "spent") {
+ *     wallet.markSpent(ev.nullifierHash0, ev.nullifierHash1);
+ *   }
+ * }
+ * ```
+ *
+ * Cancellation: pass `signal: AbortSignal` (or break out of the for-await).
+ * On abort, the underlying WebSocket is closed cleanly.
+ */
+export declare function createScanner(options: ScannerOptions): AsyncIterable<ScannerEvent>;
+/**
+ * In-memory equivalent of the live scanner: feed it an array of already-decoded
+ * Transferred logs and the user's viewing key, get back exactly the events
+ * the live scanner would have yielded. Used by tests and by historical replay
+ * callers that have already fetched logs via `eth_getLogs`.
+ */
+export declare function scanTransferredLogs(logs: readonly DecodedTransferredLog[], viewingPrivateKey: Uint8Array): Array<ScannerTransferredInEvent | ScannerTransferredOtherEvent>;
+export type { EncryptedNote, Note, ViewingKeyPair } from "./notes.js";