@chainvue/verus-sapling 0.0.0

package/dist/wallet.js

@@ -0,0 +1,179 @@
+/**
+ * Shielded wallet orchestration — the typed home for the flows proven end to end
+ * on Verus testnet, sourcing ALL chain data from lightwalletd (no full node):
+ *
+ *  - `detectNotes`       — find the wallet's own notes by trial-decrypting the
+ *                          compact blocks of a height range, and drop any already
+ *                          spent within that range. Replaces `z_listunspent`.
+ *  - `buildShieldedSpend`— assemble and prove a z→z / z→t spend of one detected
+ *                          note (fetches the note's creating output, tree state,
+ *                          and block cmus, then calls the prover).
+ *
+ * This module is transport- and prover-agnostic: it depends only on the
+ * `LightwalletdTransport` interface and a prover callback. That keeps the money
+ * invariant and marshalling here (bigint sats, checked crossings) while letting
+ * the caller decide where the wasm runs — directly in Node, or in a Web Worker
+ * in the browser (spend proving is ~5–20 s; detection is milliseconds).
+ *
+ * Proven reference: the fully-lightwalletd-sourced z→z (txid 07e3b38e…f996) and
+ * the note-detection cross-check whose predicted nullifier matched that spend's
+ * on-chain nullifier byte-for-byte.
+ */
+import { ShieldedInputError } from './errors.js';
+import { bytesToHex, reverseBytes } from './hex.js';
+import { CONSENSUS_BRANCH_ID, toSafeNumber } from './money.js';
+/** Enforce the money invariant at the boundary: a `bigint`, and >= 0. */
+function assertSats(label, sats) {
+    if (typeof sats !== 'bigint') {
+        throw new ShieldedInputError(`${label} must be a bigint (satoshis), got ${typeof sats}`);
+    }
+    if (sats < 0n)
+        throw new ShieldedInputError(`${label} must be >= 0, got ${sats}`);
+}
+import { parseSaplingOutput, parseTreeState } from './parse.js';
+import { saplingAddressToHex } from './zaddr.js';
+const toHex = (b) => bytesToHex(b);
+/**
+ * Find the wallet's own notes in `[fromHeight, toHeight]` by trial-decryption,
+ * excluding notes whose nullifier is spent within the same range.
+ *
+ * Sources everything from `transport`: the tree state before the range (for
+ * absolute positions) plus every compact block in the range. `prover` is the
+ * wasm `detectNotes` (cheap; may run on the main thread).
+ *
+ * Note: spends are only observed within the scanned range. Scan from the wallet
+ * birthday to the tip for a complete unspent set.
+ */
+export async function detectNotes(transport, prover, params) {
+    const toHeight = params.toHeight ?? (await transport.getLatestHeight());
+    if (toHeight < params.fromHeight)
+        return [];
+    const treeState = await transport.getTreeState(params.fromHeight - 1);
+    const tree = parseTreeState(treeState.tree);
+    const outputs = [];
+    const spentNullifiers = new Set();
+    const txidByKey = new Map(); // `${height}:${tx_index}` -> display txid
+    for await (const block of transport.getBlockRange(params.fromHeight, toHeight)) {
+        const height = Number(block.height);
+        for (const tx of block.vtx) {
+            const txIndex = Number(tx.index);
+            txidByKey.set(`${height}:${txIndex}`, bytesToHex(reverseBytes(tx.hash)));
+            for (const s of tx.spends)
+                spentNullifiers.add(toHex(s.nf));
+            tx.outputs.forEach((o, outputIndex) => {
+                outputs.push({
+                    height,
+                    tx_index: txIndex,
+                    output_index: outputIndex,
+                    cmu: toHex(o.cmu),
+                    epk: toHex(o.epk),
+                    ciphertext: toHex(o.ciphertext),
+                });
+            });
+        }
+    }
+    const keyField = 'extskHex' in params.key
+        ? { extsk_hex: params.key.extskHex }
+        : { dfvk_hex: params.key.dfvkHex };
+    const spec = JSON.stringify({ ...keyField, tree, outputs });
+    const detected = await prover(spec);
+    return detected
+        .filter((n) => !spentNullifiers.has(n.nullifier_hex))
+        .map((n) => {
+        const txid = txidByKey.get(`${n.height}:${n.tx_index}`);
+        if (txid === undefined) {
+            throw new ShieldedInputError(`detected note at ${n.height}:${n.tx_index} has no matching block tx (transport/scan mismatch)`);
+        }
+        // Compact-output values are server-controlled and unauthenticated. Guard the
+        // float64 crossing (JSON number) so an out-of-range value throws instead of
+        // silently rounding — the money invariant, at this inbound boundary.
+        if (!Number.isSafeInteger(n.value)) {
+            throw new ShieldedInputError(`detected note value ${n.value} is not a safe integer`);
+        }
+        return {
+            txid,
+            outputIndex: n.output_index,
+            height: n.height,
+            position: n.position,
+            valueSats: BigInt(n.value),
+            recipientHex: n.recipient_hex,
+            nullifierHex: n.nullifier_hex,
+        };
+    });
+}
+/** Default sanity ceiling on the fee: 0.1 coin. Overridable via `maxFeeSats`. */
+const DEFAULT_MAX_FEE_SATS = 10000000n;
+/**
+ * Build + sign a z→z / z→t spend of a single detected note. Fetches the note's
+ * creating output (via `getTransaction`), the tree state at its block − 1, and
+ * that block's ordered cmus (to place the note), assembles the prover spec, and
+ * runs `prover` (wasm `spendShielded`, typically in a Web Worker). Returns the
+ * broadcastable transaction hex.
+ *
+ * Value conservation is enforced HERE, before signing: `note.valueSats` must
+ * equal Σ shielded-output + Σ transparent-output + `feeSats`. The daemon only
+ * rejects a *negative* fee at broadcast; a positive overshoot (e.g. a forgotten
+ * change output) is a valid, eagerly-mined transaction that donates the excess
+ * to miners. Requiring an explicit `feeSats` and checking the balance turns that
+ * silent loss into a caught error.
+ */
+export async function buildShieldedSpend(transport, prover, params) {
+    const shieldedOutputs = params.shieldedOutputs ?? [];
+    const transparentOutputs = params.transparentOutputs ?? [];
+    if (shieldedOutputs.length === 0 && transparentOutputs.length === 0) {
+        throw new ShieldedInputError('at least one shielded or transparent output is required');
+    }
+    shieldedOutputs.forEach((o, i) => assertSats(`shieldedOutputs[${i}].valueSats`, o.valueSats));
+    transparentOutputs.forEach((o, i) => assertSats(`transparentOutputs[${i}].valueSats`, o.valueSats));
+    assertSats('note.valueSats', params.note.valueSats);
+    assertSats('feeSats', params.feeSats);
+    // Value conservation + a fee sanity ceiling — see the doc comment above.
+    const maxFee = params.maxFeeSats ?? DEFAULT_MAX_FEE_SATS;
+    if (params.feeSats > maxFee) {
+        throw new ShieldedInputError(`feeSats ${params.feeSats} exceeds maxFeeSats ${maxFee} — pass maxFeeSats to override`);
+    }
+    const outSum = shieldedOutputs.reduce((a, o) => a + o.valueSats, 0n) +
+        transparentOutputs.reduce((a, o) => a + o.valueSats, 0n);
+    if (params.note.valueSats !== outSum + params.feeSats) {
+        throw new ShieldedInputError(`value conservation failed: note ${params.note.valueSats} != outputs ${outSum} + fee ${params.feeSats}`);
+    }
+    const tx = await transport.getTransaction(params.note.txid);
+    const height = Number(tx.height);
+    const out = parseSaplingOutput(tx.data, params.note.outputIndex);
+    const treeState = await transport.getTreeState(height - 1);
+    const tree = parseTreeState(treeState.tree);
+    const blockCmus = [];
+    for await (const block of transport.getBlockRange(height, height)) {
+        for (const btx of block.vtx)
+            for (const o of btx.outputs)
+                blockCmus.push(toHex(o.cmu));
+    }
+    const myCmuIndex = blockCmus.indexOf(out.cmu);
+    if (myCmuIndex < 0) {
+        throw new ShieldedInputError(`note cmu not found in block ${height} compact outputs`);
+    }
+    const expiryHeight = params.expiryHeight ?? (await transport.getLatestHeight()) + 40;
+    const spec = {
+        extsk_hex: params.note.extskHex,
+        out,
+        tree,
+        block_cmus: blockCmus,
+        my_cmu_index: myCmuIndex,
+        shielded_outputs: shieldedOutputs.map((o) => ({
+            recipient_hex: saplingAddressToHex(o.address),
+            value: toSafeNumber(o.valueSats),
+            ...(o.memoHex !== undefined ? { memo_hex: o.memoHex } : { memo: o.memo ?? '' }),
+        })),
+        transparent_outputs: transparentOutputs.map((o) => ({
+            value: toSafeNumber(o.valueSats),
+            script_hex: o.scriptHex,
+        })),
+        // The Rust builder re-checks conservation against the DECRYPTED note value
+        // (authoritative) once the wasm is rebuilt to read this field.
+        fee: toSafeNumber(params.feeSats),
+        expiry_height: expiryHeight,
+        branch_id: params.branchId ?? CONSENSUS_BRANCH_ID,
+    };
+    const hex = await prover(JSON.stringify(spec));
+    return { hex };
+}

package/dist/wasm.d.ts

@@ -0,0 +1,91 @@
+/**
+ * TypeScript loader for the Sapling proving wasm module.
+ *
+ * The wasm (built from `crate/` via `wasm-pack build --target web`, output in
+ * `crate/pkg/`) exposes two builders. The caller supplies the two Sapling params
+ * files (byte-identical to Zcash's `sapling-spend.params` / `sapling-output.params`,
+ * ~50MB total) and a JSON request; the builders return the signed transaction hex.
+ *
+ * Proving is CPU-heavy (~5s single-threaded per tx) — run it off the main thread
+ * (a Web Worker in the browser); see `browser/worker-prover.ts`.
+ *
+ * STATUS: verified end-to-end — a t->z built through this wasm in Node was
+ * accepted by the Verus testnet daemon (txid d142edf8…a0ef).
+ */
+/** SHA-256 of the canonical Zcash Sapling proving parameters (byte-identical for
+ *  Verus). See NOTICE / README. */
+export declare const PARAM_SHA256: {
+    readonly spend: "8e48ffd23abb3a5fd9c5589204f32d9c31285a04b78096ba40a79b75677efc13";
+    readonly output: "2f0ebbcbb9bb0bcffe95a397e7eba89c29eb4dde6191c339db88570e3f3fb0e4";
+};
+/**
+ * Verify caller-supplied proving parameters are the canonical Sapling params
+ * before they are fed to the prover. The prover reads them WITHOUT group-element
+ * checks (for speed), so an unverified/malicious params file is attack surface;
+ * this hash gate is the cheap defense (one SHA-256 of ~50 MB). Throws on mismatch.
+ * Call once after loading params (the browser Web Worker does this on init).
+ */
+export declare function verifyCanonicalParams(params: SaplingParams): Promise<void>;
+/**
+ * Initialize the wasm module. Pass the `.wasm` bytes/URL/Response; in Node,
+ * read `crate/pkg/verus_sapling_prover_bg.wasm` and pass the bytes.
+ */
+export declare function initSapling(wasm: BufferSource | URL | Response | Promise<Response>): Promise<void>;
+/** Params, loaded by the caller (fetch / fs). */
+export interface SaplingParams {
+    spend: Uint8Array;
+    output: Uint8Array;
+}
+/**
+ * Build + sign a t->z shielding tx from a JSON spec (see the Rust
+ * `json_api::build_t2z_from_json` shape). Returns tx hex; the consumer still has
+ * the daemon fill the transparent scriptSig via `signrawtransaction`.
+ * Call `initSapling` first.
+ */
+export declare function shieldT2z(specJson: string, params: SaplingParams): string;
+/**
+ * Build + sign a z->z / z->t tx that spends a shielded note (JSON spec per
+ * `json_api::build_zspend_from_json`). Complete after this (no transparent
+ * inputs) — broadcast directly. Call `initSapling` first.
+ */
+export declare function spendShielded(specJson: string, params: SaplingParams): string;
+/** A note detected by trial-decryption (see `detectNotes`). All 32-byte fields hex. */
+export interface DetectedNoteRaw {
+    height: number;
+    tx_index: number;
+    output_index: number;
+    /** 0-based leaf position in the note-commitment tree. */
+    position: number;
+    /** Note value in zatoshi (safe: below 2^53 for VRSC supply). */
+    value: number;
+    /** 43-byte Sapling payment address the note pays to (one of the wallet's). */
+    recipient_hex: string;
+    /** Note nullifier — appears in a future spend's vShieldedSpend. */
+    nullifier_hex: string;
+}
+/**
+ * Trial-decrypt compact Sapling outputs to find the wallet's own notes (read
+ * path — no params, no proving; runs in milliseconds). `specJson` is the
+ * note-detection request (see the Rust `json_api::detect_notes_from_json`).
+ * Does NOT require `initSapling` params, but the wasm module must be
+ * initialized. Safe on the main thread.
+ */
+export declare function detectNotes(specJson: string): DetectedNoteRaw[];
+/** A fully-decrypted incoming note (see `readNote`). */
+export interface ReadNoteResult {
+    /** Note value in zatoshi. */
+    value: number;
+    /** 43-byte Sapling payment address the note pays to (hex). */
+    recipient_hex: string;
+    /** Full 512-byte memo as hex. */
+    memo_hex: string;
+    /** Memo decoded as UTF-8 text (trimmed at the first 0x00/0xf6 pad byte). */
+    memo_text: string;
+}
+/**
+ * Fully decrypt one incoming output — value + recipient + memo — with the
+ * wallet's viewing key. `specJson` is the read request (see the Rust
+ * `json_api::read_note_from_json`): `{ extsk_hex | dfvk_hex, out:{cv,cmu,epk,enc,ct,proof} }`.
+ * Returns `null` if the output is not for this key. Cheap (no params, no proving).
+ */
+export declare function readNote(specJson: string): ReadNoteResult | null;

package/dist/wasm.js

@@ -0,0 +1,90 @@
+/**
+ * TypeScript loader for the Sapling proving wasm module.
+ *
+ * The wasm (built from `crate/` via `wasm-pack build --target web`, output in
+ * `crate/pkg/`) exposes two builders. The caller supplies the two Sapling params
+ * files (byte-identical to Zcash's `sapling-spend.params` / `sapling-output.params`,
+ * ~50MB total) and a JSON request; the builders return the signed transaction hex.
+ *
+ * Proving is CPU-heavy (~5s single-threaded per tx) — run it off the main thread
+ * (a Web Worker in the browser); see `browser/worker-prover.ts`.
+ *
+ * STATUS: verified end-to-end — a t->z built through this wasm in Node was
+ * accepted by the Verus testnet daemon (txid d142edf8…a0ef).
+ */
+// The generated glue is ESM (wasm-pack, crate/pkg). In a bundler/browser, import
+// the pkg directly.
+import initWasm, { shield_t2z, spend_shielded, detect_notes, read_note, } from '../crate/pkg/verus_sapling_prover.js';
+import { ShieldedError } from './errors.js';
+let ready;
+/** SHA-256 of the canonical Zcash Sapling proving parameters (byte-identical for
+ *  Verus). See NOTICE / README. */
+export const PARAM_SHA256 = {
+    spend: '8e48ffd23abb3a5fd9c5589204f32d9c31285a04b78096ba40a79b75677efc13',
+    output: '2f0ebbcbb9bb0bcffe95a397e7eba89c29eb4dde6191c339db88570e3f3fb0e4',
+};
+async function sha256Hex(bytes) {
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Verify caller-supplied proving parameters are the canonical Sapling params
+ * before they are fed to the prover. The prover reads them WITHOUT group-element
+ * checks (for speed), so an unverified/malicious params file is attack surface;
+ * this hash gate is the cheap defense (one SHA-256 of ~50 MB). Throws on mismatch.
+ * Call once after loading params (the browser Web Worker does this on init).
+ */
+export async function verifyCanonicalParams(params) {
+    const [spend, output] = await Promise.all([sha256Hex(params.spend), sha256Hex(params.output)]);
+    if (spend !== PARAM_SHA256.spend) {
+        throw new ShieldedError('ERR_SHIELDED_PARAMS', `sapling-spend.params SHA-256 mismatch (got ${spend})`);
+    }
+    if (output !== PARAM_SHA256.output) {
+        throw new ShieldedError('ERR_SHIELDED_PARAMS', `sapling-output.params SHA-256 mismatch (got ${output})`);
+    }
+}
+/**
+ * Initialize the wasm module. Pass the `.wasm` bytes/URL/Response; in Node,
+ * read `crate/pkg/verus_sapling_prover_bg.wasm` and pass the bytes.
+ */
+export function initSapling(wasm) {
+    if (!ready)
+        ready = initWasm({ module_or_path: wasm }).then(() => undefined);
+    return ready;
+}
+/**
+ * Build + sign a t->z shielding tx from a JSON spec (see the Rust
+ * `json_api::build_t2z_from_json` shape). Returns tx hex; the consumer still has
+ * the daemon fill the transparent scriptSig via `signrawtransaction`.
+ * Call `initSapling` first.
+ */
+export function shieldT2z(specJson, params) {
+    return shield_t2z(specJson, params.spend, params.output);
+}
+/**
+ * Build + sign a z->z / z->t tx that spends a shielded note (JSON spec per
+ * `json_api::build_zspend_from_json`). Complete after this (no transparent
+ * inputs) — broadcast directly. Call `initSapling` first.
+ */
+export function spendShielded(specJson, params) {
+    return spend_shielded(specJson, params.spend, params.output);
+}
+/**
+ * Trial-decrypt compact Sapling outputs to find the wallet's own notes (read
+ * path — no params, no proving; runs in milliseconds). `specJson` is the
+ * note-detection request (see the Rust `json_api::detect_notes_from_json`).
+ * Does NOT require `initSapling` params, but the wasm module must be
+ * initialized. Safe on the main thread.
+ */
+export function detectNotes(specJson) {
+    return JSON.parse(detect_notes(specJson));
+}
+/**
+ * Fully decrypt one incoming output — value + recipient + memo — with the
+ * wallet's viewing key. `specJson` is the read request (see the Rust
+ * `json_api::read_note_from_json`): `{ extsk_hex | dfvk_hex, out:{cv,cmu,epk,enc,ct,proof} }`.
+ * Returns `null` if the output is not for this key. Cheap (no params, no proving).
+ */
+export function readNote(specJson) {
+    return JSON.parse(read_note(specJson));
+}

package/dist/zaddr.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Decode a Verus Sapling bech32 address to its raw 43-byte payment-address
+ * payload — the form the Rust/wasm prover expects.
+ *
+ * HRP note (verified against a live daemon, not the stock-zcash source): real
+ * Verus uses the `zs` prefix on BOTH mainnet and vrsctest — there is no
+ * HRP-level network distinction, so the payload alone determines the recipient.
+ * We also tolerate stock-zcash `ztestsapling` for compatibility, but Verus
+ * itself never emits it. The bech32 checksum is the only guard against a
+ * mistyped address; `bech32Decode` verifies it.
+ *
+ * Minimal bech32 (BIP-173) decoder, no dependency (keeps the tiny-dep ethos).
+ * Sapling addresses use bech32 (not bech32m) and carry an 88-symbol data part
+ * that converts to 43 bytes (11-byte diversifier + 32-byte pk_d).
+ */
+/** Decode a `zs`/`ztestsapling` address to its 43-byte payload. */
+export declare function decodeSaplingAddress(addr: string): Uint8Array;
+/** Hex of the 43-byte payload (convenience for JSON specs). */
+export declare function saplingAddressToHex(addr: string): string;

package/dist/zaddr.js

@@ -0,0 +1,107 @@
+/**
+ * Decode a Verus Sapling bech32 address to its raw 43-byte payment-address
+ * payload — the form the Rust/wasm prover expects.
+ *
+ * HRP note (verified against a live daemon, not the stock-zcash source): real
+ * Verus uses the `zs` prefix on BOTH mainnet and vrsctest — there is no
+ * HRP-level network distinction, so the payload alone determines the recipient.
+ * We also tolerate stock-zcash `ztestsapling` for compatibility, but Verus
+ * itself never emits it. The bech32 checksum is the only guard against a
+ * mistyped address; `bech32Decode` verifies it.
+ *
+ * Minimal bech32 (BIP-173) decoder, no dependency (keeps the tiny-dep ethos).
+ * Sapling addresses use bech32 (not bech32m) and carry an 88-symbol data part
+ * that converts to 43 bytes (11-byte diversifier + 32-byte pk_d).
+ */
+import { bytesToHex } from './hex.js';
+const CHARSET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
+const BECH32_GENERATOR = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3];
+/** BIP-173 polymod over 5-bit values (bit ops stay within 30 bits, safe in JS). */
+function bech32Polymod(values) {
+    let chk = 1;
+    for (const v of values) {
+        const top = chk >>> 25;
+        chk = ((chk & 0x1ffffff) << 5) ^ v;
+        for (let i = 0; i < 5; i++)
+            if ((top >> i) & 1)
+                chk ^= BECH32_GENERATOR[i];
+    }
+    return chk >>> 0;
+}
+function hrpExpand(hrp) {
+    const out = [];
+    for (let i = 0; i < hrp.length; i++)
+        out.push(hrp.charCodeAt(i) >> 5);
+    out.push(0);
+    for (let i = 0; i < hrp.length; i++)
+        out.push(hrp.charCodeAt(i) & 31);
+    return out;
+}
+function bech32Decode(addr) {
+    const raw = addr.trim();
+    // BIP-173: a decoder MUST reject a string that mixes upper- and lower-case.
+    if (/[a-z]/.test(raw) && /[A-Z]/.test(raw))
+        throw new Error('bech32: mixed case');
+    const s = raw.toLowerCase();
+    const sep = s.lastIndexOf('1');
+    if (sep < 1)
+        throw new Error('invalid bech32: no separator');
+    const hrp = s.slice(0, sep);
+    const data = [];
+    for (const ch of s.slice(sep + 1)) {
+        const v = CHARSET.indexOf(ch);
+        if (v === -1)
+            throw new Error(`invalid bech32 char: ${ch}`);
+        data.push(v);
+    }
+    if (data.length < 6)
+        throw new Error('bech32 data too short');
+    // Verify the 6-symbol checksum (Sapling uses bech32, constant 1 — not bech32m)
+    // BEFORE stripping it. Skipping this would let a single mistyped character
+    // decode to a valid-looking but WRONG 43-byte payload — on mainnet, funds
+    // encrypted to an unspendable key.
+    if (bech32Polymod([...hrpExpand(hrp), ...data]) !== 1) {
+        throw new Error('invalid bech32 checksum');
+    }
+    return { hrp, data: data.slice(0, -6) };
+}
+function convertBits(data, from, to, pad) {
+    let acc = 0;
+    let bits = 0;
+    const out = [];
+    const maxv = (1 << to) - 1;
+    for (const value of data) {
+        acc = (acc << from) | value;
+        bits += from;
+        while (bits >= to) {
+            bits -= to;
+            out.push((acc >> bits) & maxv);
+        }
+    }
+    if (pad) {
+        if (bits > 0)
+            out.push((acc << (to - bits)) & maxv);
+    }
+    else if (bits >= from || ((acc << (to - bits)) & maxv) !== 0) {
+        // BIP-173: reject non-canonical trailing bits (too many leftover, or padding
+        // bits not zero) so a valid-checksum address can't have a malleable encoding.
+        throw new Error('bech32: non-canonical padding');
+    }
+    return out;
+}
+/** Decode a `zs`/`ztestsapling` address to its 43-byte payload. */
+export function decodeSaplingAddress(addr) {
+    const { hrp, data } = bech32Decode(addr);
+    if (hrp !== 'zs' && hrp !== 'ztestsapling') {
+        throw new Error(`not a Sapling address (hrp=${hrp})`);
+    }
+    const bytes = convertBits(data, 5, 8, false);
+    if (bytes.length !== 43) {
+        throw new Error(`expected 43-byte payload, got ${bytes.length}`);
+    }
+    return Uint8Array.from(bytes);
+}
+/** Hex of the 43-byte payload (convenience for JSON specs). */
+export function saplingAddressToHex(addr) {
+    return bytesToHex(decodeSaplingAddress(addr));
+}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@chainvue/verus-sapling",
+  "version": "0.0.0",
+  "description": "Offline signing of Verus shielded (Sapling) transactions — t→z, z→z, z→t, with memo. Companion to @chainvue/verus-sdk. Builds and signs bytes; consumers broadcast. WASM prover, no full node on the signing host.",
+  "license": "Apache-2.0",
+  "author": "Robert Lech",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chainvue/verus-sapling.git"
+  },
+  "homepage": "https://github.com/chainvue/verus-sapling#readme",
+  "bugs": {
+    "url": "https://github.com/chainvue/verus-sapling/issues"
+  },
+  "keywords": [
+    "verus",
+    "zcash",
+    "sapling",
+    "shielded",
+    "zk-snark",
+    "offline-signing",
+    "wasm",
+    "typescript"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "crate/pkg",
+    "proto",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./lightwalletd": {
+      "types": "./dist/lightwalletd.d.ts",
+      "default": "./dist/lightwalletd.js"
+    },
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "default": "./dist/browser/index.js"
+    },
+    "./prover-worker": {
+      "types": "./dist/browser/prover-worker.d.ts",
+      "default": "./dist/browser/prover-worker.js"
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:ext": "tsc && node examples/extension/build.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "@chainvue/verus-sdk": ">=0.14.0"
+  },
+  "optionalDependencies": {
+    "@grpc/grpc-js": "^1.10.0",
+    "@grpc/proto-loader": "^0.7.0"
+  },
+  "devDependencies": {
+    "@chainvue/verus-sdk": ">=0.14.0",
+    "@grpc/grpc-js": "^1.10.0",
+    "@grpc/proto-loader": "^0.7.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/exec": "^7.1.0",
+    "@semantic-release/git": "^10.0.1",
+    "@types/node": "^22",
+    "esbuild": "^0.24.2",
+    "semantic-release": "^25.0.7",
+    "typescript": "^5",
+    "vitest": "^2"
+  },
+  "//": "The concrete lightwalletd gRPC client (@chainvue/verus-sapling/lightwalletd) needs @grpc/grpc-js — an OPTIONAL dependency: the browser path implements LightwalletdTransport over gRPC-web instead, and the package root pulls in no gRPC at runtime.",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/proto/compact_formats.proto

@@ -0,0 +1,62 @@
+// Copyright (c) 2019-2020 The Zcash developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or https://www.opensource.org/licenses/mit-license.php .
+
+syntax = "proto3";
+package cash.z.wallet.sdk.rpc;
+option go_package = "lightwalletd/walletrpc";
+option swift_prefix = "";
+// Remember that proto3 fields are all optional. A field that is not present will be set to its zero value.
+// bytes fields of hashes are in canonical little-endian format.
+
+// Information about the state of the chain as of a given block.
+message ChainMetadata {
+    optional uint64 saplingCommitmentTreeSize = 1; // the size of the Sapling note commitment tree as of the end of this block
+}
+
+// CompactBlock is a packaging of ONLY the data from a block that's needed to:
+//   1. Detect a payment to your shielded Sapling address
+//   2. Detect a spend of your shielded Sapling notes
+//   3. Update your witnesses to generate new Sapling spend proofs.
+message CompactBlock {
+    uint32 protoVersion = 1;
+    uint64 height = 2;
+    bytes hash = 3;
+    bytes prevHash = 4;
+    uint32 time = 5;
+    bytes header = 6;
+    repeated CompactTx vtx = 7;
+    ChainMetadata chainMetadata = 8;
+}
+
+// CompactTx contains the minimum information for a wallet to know if this transaction
+// is relevant to it (either pays to it or spends from it) via shielded elements
+// only. This message will not encode a transparent-to-transparent transaction.
+message CompactTx {
+    uint64 index = 1;   // the index within the full block
+    bytes hash = 2;     // the ID (hash) of this transaction, same as in block explorers
+
+    // The transaction fee: present if server can provide. In the case of a
+    // stateless server and a transaction with transparent inputs, this will be
+    // unset because the calculation requires reference to prior transactions.
+    // in a pure-Sapling context, the fee will be calculable as:
+    //    valueBalance + (sum(vPubNew) - sum(vPubOld) - sum(tOut))
+    uint32 fee = 3;
+
+    repeated CompactSpend spends = 4;   // inputs
+    repeated CompactOutput outputs = 5; // outputs
+}
+
+// CompactSpend is a Sapling Spend Description as described in 7.3 of the Zcash
+// protocol specification.
+message CompactSpend {
+    bytes nf = 1;   // nullifier (see the Zcash protocol specification)
+}
+
+// output is a Sapling Output Description as described in section 7.4 of the
+// Zcash protocol spec. Total size is 948.
+message CompactOutput {
+    bytes cmu = 1;          // note commitment u-coordinate
+    bytes epk = 2;          // ephemeral public key
+    bytes ciphertext = 3;   // ciphertext and zkproof
+}