@chainvue/verus-sapling 0.0.0

package/dist/index.js

@@ -0,0 +1,35 @@
+/**
+ * @chainvue/verus-sapling
+ *
+ * Offline signing of Verus shielded (Sapling) transactions — t→z, z→z, z→t,
+ * with memo — plus client-side note detection and memo reading. Companion to
+ * @chainvue/verus-sdk: it builds and signs bytes; the consumer broadcasts. No
+ * full node on the signing host (z→z / z→t need witness data from a Verus
+ * lightwalletd, reached through a `LightwalletdTransport`).
+ *
+ * Verus shielded = stock Zcash Sapling (stock circuit, byte-identical MPC
+ * params, consensus branch id 0x76b809bb).
+ *
+ * The API:
+ *  - `initSapling` + the wasm builders (`shieldT2z` / `spendShielded` /
+ *    `detectNotesWasm` / `readNote`) — the prover boundary (`wasm.ts`).
+ *  - the lightwalletd-driven orchestration (`detectNotes`, `buildShieldedSpend`)
+ *    over a `LightwalletdTransport` (`wallet.ts`).
+ *  - pure helpers: v4/tree parsers, `parseSats`/`toSafeNumber`, hex, `zs` decode.
+ *
+ * Entry points: the package root is browser-safe and pulls in no `@grpc/grpc-js`.
+ * Browser consumers also import `@chainvue/verus-sapling/browser` (gRPC-web
+ * client + Web Worker prover); Node consumers import
+ * `@chainvue/verus-sapling/lightwalletd` (the gRPC client).
+ */
+export * from './types.js';
+export * from './errors.js';
+// Pure helpers (dependency-free, browser-safe).
+export * from './parse.js';
+export { CONSENSUS_BRANCH_ID, parseSats, toSafeNumber } from './money.js';
+export { bytesToHex, hexToBytes, reverseBytes } from './hex.js';
+export { decodeSaplingAddress, saplingAddressToHex } from './zaddr.js';
+// wasm prover loaders + low-level builders (init once, then call).
+export { initSapling, shieldT2z, spendShielded, detectNotes as detectNotesWasm, readNote, verifyCanonicalParams, PARAM_SHA256, } from './wasm.js';
+// Shielded wallet orchestration (transport- and prover-agnostic).
+export { detectNotes, buildShieldedSpend, } from './wallet.js';

package/dist/lightwalletd.d.ts

@@ -0,0 +1,113 @@
+/**
+ * lightwalletd gRPC adapter — the production data source for shielded spends.
+ *
+ * Replaces the daemon-RPC "gather" shortcut used in testing. Talks to a
+ * `lightwalletd` (VerusCoin/lightwalletd) over gRPC and supplies everything the
+ * prover needs without a full node on the signing host:
+ *  - getTreeState(h)   → the note-commitment tree at height h (witness/anchor base)
+ *  - getBlockRange     → compact blocks (cmus for witness position + note scanning)
+ *  - getTransaction    → full raw tx (to extract the full output of a note to spend)
+ *  - sendTransaction   → broadcast the signed tx
+ *
+ * Verified against a live Verus testnet lightwalletd: GetLightdInfo, GetTreeState
+ * (238-byte tree = the finalState our witness builder parses), GetBlockRange
+ * (cmus + nullifiers), and GetTransaction (full raw tx) all return correctly.
+ *
+ * gRPC over Node: uses @grpc/grpc-js + @grpc/proto-loader with the `.proto`
+ * files in `../proto`. A *browser* consumer needs a gRPC-web proxy in front of
+ * lightwalletd; a Node/server consumer connects directly (optionally over an
+ * SSH tunnel in dev).
+ */
+import * as grpc from '@grpc/grpc-js';
+/** TreeState (from lightwalletd, derived from z_gettreestate). `tree` is the
+ *  commitment-tree finalState hex our witness builder parses. */
+export interface TreeState {
+    network: string;
+    height: string;
+    hash: string;
+    time: number;
+    tree: string;
+}
+/** One Sapling output in a compact block. */
+export interface CompactOutput {
+    cmu: Uint8Array;
+    epk: Uint8Array;
+    ciphertext: Uint8Array;
+}
+export interface CompactTx {
+    index: string;
+    hash: Uint8Array;
+    spends: {
+        nf: Uint8Array;
+    }[];
+    outputs: CompactOutput[];
+}
+export interface CompactBlock {
+    height: string;
+    hash: Uint8Array;
+    vtx: CompactTx[];
+}
+export interface LightdInfo {
+    chainName: string;
+    consensusBranchId: string;
+    blockHeight: string;
+    saplingActivationHeight: string;
+    estimatedHeight: string;
+}
+/**
+ * The minimal lightwalletd RPC surface the shielded orchestration (`../wallet`)
+ * depends on. Abstracting it keeps the wallet logic free of any concrete
+ * transport: `LightwalletdClient` implements it over Node `@grpc/grpc-js`; a
+ * browser consumer implements the same interface over a gRPC-web proxy.
+ */
+export interface LightwalletdTransport {
+    getLatestHeight(): Promise<number>;
+    getTreeState(height: number): Promise<TreeState>;
+    getTransaction(txidDisplayHex: string): Promise<{
+        data: Uint8Array;
+        height: string;
+    }>;
+    getBlockRange(start: number, end: number): AsyncGenerator<CompactBlock>;
+    sendTransaction(txHex: string): Promise<{
+        errorCode: number;
+        errorMessage: string;
+    }>;
+}
+/** Thin, typed client over the lightwalletd CompactTxStreamer service. */
+export declare class LightwalletdClient implements LightwalletdTransport {
+    private readonly svc;
+    /**
+     * @param target host:port of lightwalletd (e.g. "lightwalletd:9067").
+     * @param opts  `credentials` to supply channel credentials explicitly, or
+     *   `insecure: true` for a plaintext channel (dev tunnels only). The default is
+     *   **TLS** (`createSsl()`): an unencrypted channel lets a network observer see
+     *   which notes/txids the wallet fetches and lets a MITM feed fabricated tree
+     *   state. The spending key never crosses this channel, but privacy and
+     *   integrity do.
+     */
+    constructor(target: string, opts?: {
+        credentials?: grpc.ChannelCredentials;
+        insecure?: boolean;
+    });
+    private unary;
+    getLightdInfo(): Promise<LightdInfo>;
+    getLatestHeight(): Promise<number>;
+    /** Tree state at `height` — the witness/anchor base. */
+    getTreeState(height: number): Promise<TreeState>;
+    /** Full raw transaction by txid (display-order hex string). Needed to extract
+     *  the full Sapling output (cv/cmu/epk/enc/out/proof) of a note being spent. */
+    getTransaction(txidDisplayHex: string): Promise<{
+        data: Uint8Array;
+        height: string;
+    }>;
+    /** Stream compact blocks in [start, end]. Used for note detection
+     *  (trial-decrypt outputs) and to collect a block's ordered cmus for witness
+     *  construction. */
+    getBlockRange(start: number, end: number): AsyncGenerator<CompactBlock>;
+    /** Broadcast a signed transaction (hex). Returns {errorCode, errorMessage}. */
+    sendTransaction(txHex: string): Promise<{
+        errorCode: number;
+        errorMessage: string;
+    }>;
+    close(): void;
+}

package/dist/lightwalletd.js

@@ -0,0 +1,99 @@
+/**
+ * lightwalletd gRPC adapter — the production data source for shielded spends.
+ *
+ * Replaces the daemon-RPC "gather" shortcut used in testing. Talks to a
+ * `lightwalletd` (VerusCoin/lightwalletd) over gRPC and supplies everything the
+ * prover needs without a full node on the signing host:
+ *  - getTreeState(h)   → the note-commitment tree at height h (witness/anchor base)
+ *  - getBlockRange     → compact blocks (cmus for witness position + note scanning)
+ *  - getTransaction    → full raw tx (to extract the full output of a note to spend)
+ *  - sendTransaction   → broadcast the signed tx
+ *
+ * Verified against a live Verus testnet lightwalletd: GetLightdInfo, GetTreeState
+ * (238-byte tree = the finalState our witness builder parses), GetBlockRange
+ * (cmus + nullifiers), and GetTransaction (full raw tx) all return correctly.
+ *
+ * gRPC over Node: uses @grpc/grpc-js + @grpc/proto-loader with the `.proto`
+ * files in `../proto`. A *browser* consumer needs a gRPC-web proxy in front of
+ * lightwalletd; a Node/server consumer connects directly (optionally over an
+ * SSH tunnel in dev).
+ */
+import { fileURLToPath } from 'node:url';
+import * as path from 'node:path';
+import * as grpc from '@grpc/grpc-js';
+import * as protoLoader from '@grpc/proto-loader';
+import { ShieldedInputError } from './errors.js';
+const PROTO_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'proto');
+/** Thin, typed client over the lightwalletd CompactTxStreamer service. */
+export class LightwalletdClient {
+    svc;
+    /**
+     * @param target host:port of lightwalletd (e.g. "lightwalletd:9067").
+     * @param opts  `credentials` to supply channel credentials explicitly, or
+     *   `insecure: true` for a plaintext channel (dev tunnels only). The default is
+     *   **TLS** (`createSsl()`): an unencrypted channel lets a network observer see
+     *   which notes/txids the wallet fetches and lets a MITM feed fabricated tree
+     *   state. The spending key never crosses this channel, but privacy and
+     *   integrity do.
+     */
+    constructor(target, opts) {
+        const def = protoLoader.loadSync('service.proto', {
+            keepCase: true,
+            longs: String,
+            enums: String,
+            defaults: true,
+            oneofs: true,
+            includeDirs: [PROTO_DIR],
+        });
+        const pkg = grpc.loadPackageDefinition(def);
+        const Ctor = pkg.cash.z.wallet.sdk.rpc.CompactTxStreamer;
+        const credentials = opts?.credentials ??
+            (opts?.insecure ? grpc.credentials.createInsecure() : grpc.credentials.createSsl());
+        this.svc = new Ctor(target, credentials);
+    }
+    unary(method, arg) {
+        return new Promise((resolve, reject) => this.svc[method](arg, (err, res) => err ? reject(err) : resolve(res)));
+    }
+    getLightdInfo() {
+        return this.unary('GetLightdInfo', {});
+    }
+    getLatestHeight() {
+        return this.unary('GetLatestBlock', {}).then((b) => Number(b.height));
+    }
+    /** Tree state at `height` — the witness/anchor base. */
+    getTreeState(height) {
+        return this.unary('GetTreeState', { height });
+    }
+    /** Full raw transaction by txid (display-order hex string). Needed to extract
+     *  the full Sapling output (cv/cmu/epk/enc/out/proof) of a note being spent. */
+    getTransaction(txidDisplayHex) {
+        // Validate before Buffer.from, which silently truncates at the first non-hex
+        // char and would query a wrong (shorter) hash.
+        if (!/^[0-9a-fA-F]{64}$/.test(txidDisplayHex)) {
+            throw new ShieldedInputError(`getTransaction: txid must be 64 hex chars, got ${txidDisplayHex.length}`);
+        }
+        const hash = Buffer.from(txidDisplayHex, 'hex').reverse(); // internal byte order
+        return this.unary('GetTransaction', { hash });
+    }
+    /** Stream compact blocks in [start, end]. Used for note detection
+     *  (trial-decrypt outputs) and to collect a block's ordered cmus for witness
+     *  construction. */
+    async *getBlockRange(start, end) {
+        const stream = this.svc.GetBlockRange({ start: { height: start }, end: { height: end } });
+        try {
+            for await (const block of stream) {
+                yield block;
+            }
+        }
+        finally {
+            stream.cancel?.();
+        }
+    }
+    /** Broadcast a signed transaction (hex). Returns {errorCode, errorMessage}. */
+    sendTransaction(txHex) {
+        return this.unary('SendTransaction', { data: Buffer.from(txHex, 'hex'), height: 0 });
+    }
+    close() {
+        this.svc.close();
+    }
+}

package/dist/money.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Money helpers, kept LOCAL and dependency-free so the browser-reachable core
+ * (wallet orchestration) bundles without pulling @chainvue/verus-sdk — whose
+ * published `dist/bundle.js` bundles @bitgo/utxo-lib and Node builtins
+ * (`crypto`/`buffer`/`os`), which don't belong in a browser extension.
+ *
+ * These mirror the SDK's semantics exactly (same money invariant): satoshi
+ * amounts are `bigint` end to end; `toSafeNumber` is the ONLY checked crossing
+ * into a float64 boundary. Node consumers who already have the SDK can keep
+ * using its versions — these exist so the shielded package stays self-contained.
+ */
+/** Verus consensus branch id for the ZIP-243 sighash / binding sig (0x76b809bb). */
+export declare const CONSENSUS_BRANCH_ID = 1991772603;
+/**
+ * Exact decimal-string → satoshi `bigint`. No float math (no `coins * 1e8`).
+ * Rejects malformed input and more than 8 fractional digits.
+ */
+export declare function parseSats(amount: string): bigint;
+/**
+ * Checked crossing from `bigint` satoshis into a JS `number` (the only place a
+ * satoshi value becomes float64). Throws outside `[0, 2^53)`.
+ */
+export declare function toSafeNumber(sats: bigint): number;

package/dist/money.js

@@ -0,0 +1,40 @@
+/**
+ * Money helpers, kept LOCAL and dependency-free so the browser-reachable core
+ * (wallet orchestration) bundles without pulling @chainvue/verus-sdk — whose
+ * published `dist/bundle.js` bundles @bitgo/utxo-lib and Node builtins
+ * (`crypto`/`buffer`/`os`), which don't belong in a browser extension.
+ *
+ * These mirror the SDK's semantics exactly (same money invariant): satoshi
+ * amounts are `bigint` end to end; `toSafeNumber` is the ONLY checked crossing
+ * into a float64 boundary. Node consumers who already have the SDK can keep
+ * using its versions — these exist so the shielded package stays self-contained.
+ */
+/** Verus consensus branch id for the ZIP-243 sighash / binding sig (0x76b809bb). */
+export const CONSENSUS_BRANCH_ID = 0x76b809bb; // 1991772603
+const SATS_PER_COIN = 100000000n;
+const MAX_DECIMALS = 8;
+/**
+ * Exact decimal-string → satoshi `bigint`. No float math (no `coins * 1e8`).
+ * Rejects malformed input and more than 8 fractional digits.
+ */
+export function parseSats(amount) {
+    const s = amount.trim();
+    if (!/^\d+(\.\d+)?$/.test(s))
+        throw new Error(`invalid amount: "${amount}"`);
+    const [intPart, fracPart = ''] = s.split('.');
+    if (fracPart.length > MAX_DECIMALS) {
+        throw new Error(`amount "${amount}" has more than ${MAX_DECIMALS} decimals`);
+    }
+    const frac = (fracPart + '00000000').slice(0, MAX_DECIMALS);
+    return BigInt(intPart) * SATS_PER_COIN + BigInt(frac);
+}
+/**
+ * Checked crossing from `bigint` satoshis into a JS `number` (the only place a
+ * satoshi value becomes float64). Throws outside `[0, 2^53)`.
+ */
+export function toSafeNumber(sats) {
+    if (sats < 0n || sats > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new Error(`satoshi value ${sats} outside safe range [0, 2^53)`);
+    }
+    return Number(sats);
+}

package/dist/parse.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Pure byte parsers for the two pieces of chain data a shielded spend needs from
+ * lightwalletd, with no external dependency:
+ *
+ *  - `parseTreeState`  — the note-commitment tree `finalState` (zcashd/Verus
+ *    serialization) → { left, right, parents }, the witness base the prover
+ *    reconstructs into a `CommitmentTree`.
+ *  - `parseSaplingOutput` — the full 948-byte Sapling output description at a
+ *    given index of a raw v4 transaction (cv/cmu/epk/enc/ct/proof), needed to
+ *    re-derive and spend a note.
+ *
+ * These were validated end to end: the parsed outputs and tree fed a wasm
+ * `spend_shielded` that produced an on-chain-accepted z→z (txid 07e3b38e…f996).
+ * Kept dependency-free and unit-tested so the byte layout is pinned.
+ */
+/** The note-commitment tree state, parts as raw-wire hex (nulls for empty slots). */
+export interface ParsedTreeState {
+    left: string | null;
+    right: string | null;
+    parents: (string | null)[];
+}
+/**
+ * Parse a zcashd/Verus commitment-tree `finalState` (hex) — as returned by
+ * `z_gettreestate` / lightwalletd `GetTreeState` — into { left, right, parents }.
+ * Layout: `EmptyOrValue<Node> left; EmptyOrValue<Node> right;
+ * vector<EmptyOrValue<Node>> parents`, each `EmptyOrValue` = 1 tag byte then
+ * (if 1) 32 bytes.
+ */
+export declare function parseTreeState(finalStateHex: string): ParsedTreeState;
+/** A full Sapling output description, fields as raw-wire hex. */
+export interface SaplingOutputBytes {
+    cv: string;
+    cmu: string;
+    epk: string;
+    enc: string;
+    ct: string;
+    proof: string;
+}
+/**
+ * Extract the Sapling output description at `index` from a raw Sapling **v4**
+ * transaction. Walks the transparent inputs/outputs and shielded spends to reach
+ * `vShieldedOutput`, then returns the 948-byte description split into fields.
+ * Throws if the tx has fewer than `index + 1` shielded outputs.
+ */
+export declare function parseSaplingOutput(rawTx: Uint8Array, index: number): SaplingOutputBytes;

package/dist/parse.js

@@ -0,0 +1,129 @@
+/**
+ * Pure byte parsers for the two pieces of chain data a shielded spend needs from
+ * lightwalletd, with no external dependency:
+ *
+ *  - `parseTreeState`  — the note-commitment tree `finalState` (zcashd/Verus
+ *    serialization) → { left, right, parents }, the witness base the prover
+ *    reconstructs into a `CommitmentTree`.
+ *  - `parseSaplingOutput` — the full 948-byte Sapling output description at a
+ *    given index of a raw v4 transaction (cv/cmu/epk/enc/ct/proof), needed to
+ *    re-derive and spend a note.
+ *
+ * These were validated end to end: the parsed outputs and tree fed a wasm
+ * `spend_shielded` that produced an on-chain-accepted z→z (txid 07e3b38e…f996).
+ * Kept dependency-free and unit-tested so the byte layout is pinned.
+ */
+import { bytesToHex, hexToBytes } from './hex.js';
+/** Minimal sequential byte reader over a `Uint8Array` (little-endian ints). */
+class ByteReader {
+    buf;
+    off = 0;
+    constructor(buf) {
+        this.buf = buf;
+    }
+    view() {
+        return new DataView(this.buf.buffer, this.buf.byteOffset, this.buf.byteLength);
+    }
+    u8() {
+        if (this.off >= this.buf.length)
+            throw new RangeError('ByteReader: read past end');
+        return this.buf[this.off++];
+    }
+    slice(n) {
+        if (this.off + n > this.buf.length)
+            throw new RangeError('ByteReader: slice past end');
+        const s = this.buf.subarray(this.off, this.off + n);
+        this.off += n;
+        return s;
+    }
+    skip(n) {
+        if (this.off + n > this.buf.length)
+            throw new RangeError('ByteReader: skip past end');
+        this.off += n;
+    }
+    /** Bitcoin/Zcash CompactSize varint. */
+    varint() {
+        const b = this.u8();
+        if (b < 0xfd)
+            return b;
+        if (b === 0xfd) {
+            const v = this.view().getUint16(this.off, true);
+            this.off += 2;
+            return v;
+        }
+        if (b === 0xfe) {
+            const v = this.view().getUint32(this.off, true);
+            this.off += 4;
+            return v;
+        }
+        const v = this.view().getBigUint64(this.off, true);
+        this.off += 8;
+        if (v > BigInt(Number.MAX_SAFE_INTEGER))
+            throw new RangeError('varint exceeds MAX_SAFE_INTEGER');
+        return Number(v);
+    }
+}
+const toHex = (b) => bytesToHex(b);
+/**
+ * Parse a zcashd/Verus commitment-tree `finalState` (hex) — as returned by
+ * `z_gettreestate` / lightwalletd `GetTreeState` — into { left, right, parents }.
+ * Layout: `EmptyOrValue<Node> left; EmptyOrValue<Node> right;
+ * vector<EmptyOrValue<Node>> parents`, each `EmptyOrValue` = 1 tag byte then
+ * (if 1) 32 bytes.
+ */
+export function parseTreeState(finalStateHex) {
+    const r = new ByteReader(hexToBytes(finalStateHex));
+    const opt = () => (r.u8() === 1 ? toHex(r.slice(32)) : null);
+    const left = opt();
+    const right = opt();
+    const n = r.varint();
+    const parents = [];
+    for (let i = 0; i < n; i++)
+        parents.push(opt());
+    return { left, right, parents };
+}
+/**
+ * Extract the Sapling output description at `index` from a raw Sapling **v4**
+ * transaction. Walks the transparent inputs/outputs and shielded spends to reach
+ * `vShieldedOutput`, then returns the 948-byte description split into fields.
+ * Throws if the tx has fewer than `index + 1` shielded outputs.
+ */
+export function parseSaplingOutput(rawTx, index) {
+    const r = new ByteReader(rawTx);
+    r.skip(8); // header (4) + versionGroupId (4)
+    const nIn = r.varint();
+    for (let i = 0; i < nIn; i++) {
+        r.skip(36); // prevout: txid(32) + vout(4)
+        const scriptLen = r.varint();
+        r.skip(scriptLen);
+        r.skip(4); // sequence
+    }
+    const nOut = r.varint();
+    for (let i = 0; i < nOut; i++) {
+        r.skip(8); // value
+        const scriptLen = r.varint();
+        r.skip(scriptLen);
+    }
+    r.skip(4 + 4 + 8); // lockTime + expiryHeight + valueBalance(i64)
+    const nSpend = r.varint();
+    r.skip(nSpend * 384); // each SpendDescription is 384 bytes in a full tx
+    const nShieldedOut = r.varint();
+    if (index >= nShieldedOut) {
+        throw new RangeError(`shielded output index ${index} out of range (have ${nShieldedOut})`);
+    }
+    let found;
+    for (let i = 0; i < nShieldedOut; i++) {
+        const d = r.slice(948);
+        if (i === index)
+            found = d;
+    }
+    const d = found;
+    return {
+        cv: toHex(d.subarray(0, 32)),
+        cmu: toHex(d.subarray(32, 64)),
+        epk: toHex(d.subarray(64, 96)),
+        enc: toHex(d.subarray(96, 676)),
+        ct: toHex(d.subarray(676, 756)),
+        proof: toHex(d.subarray(756, 948)),
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared domain vocabulary for the shielded package.
+ *
+ * Money invariant (inherited from @chainvue/verus-sdk): ALL satoshi amounts are
+ * `bigint`, end to end — never `number`. The only checked crossing into a
+ * float64 boundary is `toSafeNumber` (see `money.ts`).
+ *
+ * The concrete request/result shapes live with the functions that use them:
+ * `SpendableNote` / `ShieldedRecipient` / `BuildShieldedSpendParams` in
+ * `wallet.ts`, `SaplingParams` / `ReadNoteResult` in `wasm.ts`.
+ */
+/** Sapling payment address, Bech32: `zs`-prefixed (mainnet) / `ztestsapling` (testnet). */
+export type SaplingAddress = string;
+/** Transparent Verus address (R-address, P2PKH). */
+export type TransparentAddress = string;
+/**
+ * Sapling extended spending key (ZIP-32) as 169-byte hex — the full spend
+ * authority. Same trust surface as a transparent WIF: it is present on the
+ * signing host; callers must protect it accordingly.
+ */
+export type SaplingSpendingKey = string;
+/**
+ * A Sapling memo. A `string` is UTF-8-encoded then zero-padded to 512 bytes; a
+ * hex string via a recipient's `memoHex` carries raw bytes verbatim (for
+ * structured/binary memos). Max 512 bytes either way.
+ */
+export type Memo = string;
+/** Max memo size in bytes (Zcash/Verus Sapling note-plaintext memo field). */
+export declare const MEMO_MAX_BYTES = 512;

package/dist/types.js

@@ -0,0 +1,13 @@
+/**
+ * Shared domain vocabulary for the shielded package.
+ *
+ * Money invariant (inherited from @chainvue/verus-sdk): ALL satoshi amounts are
+ * `bigint`, end to end — never `number`. The only checked crossing into a
+ * float64 boundary is `toSafeNumber` (see `money.ts`).
+ *
+ * The concrete request/result shapes live with the functions that use them:
+ * `SpendableNote` / `ShieldedRecipient` / `BuildShieldedSpendParams` in
+ * `wallet.ts`, `SaplingParams` / `ReadNoteResult` in `wasm.ts`.
+ */
+/** Max memo size in bytes (Zcash/Verus Sapling note-plaintext memo field). */
+export const MEMO_MAX_BYTES = 512;

package/dist/wallet.d.ts

@@ -0,0 +1,124 @@
+/**
+ * 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 type { LightwalletdTransport } from './lightwalletd.js';
+import type { DetectedNoteRaw } from './wasm.js';
+/** A viewing/spending key for detection: an extended spending key (169-byte hex)
+ *  or a diversifiable full viewing key (128-byte hex, read-only). */
+export type DetectKey = {
+    extskHex: string;
+} | {
+    dfvkHex: string;
+};
+/** Trial-decrypt the compact outputs (read path). Returns raw detected notes. */
+export type DetectProver = (specJson: string) => DetectedNoteRaw[] | Promise<DetectedNoteRaw[]>;
+/** Prove + sign a shielded spend. Returns the signed transaction hex. The caller
+ *  binds the proving parameters (and may run this in a Web Worker). */
+export type SpendProver = (specJson: string) => string | Promise<string>;
+export interface DetectNotesParams {
+    readonly key: DetectKey;
+    /** First block to scan (inclusive). Use the wallet's birthday height. */
+    readonly fromHeight: number;
+    /** Last block to scan (inclusive). Defaults to the chain tip. */
+    readonly toHeight?: number;
+}
+/** A spendable note the wallet owns, with everything a later spend needs. */
+export interface SpendableNote {
+    /** Creating transaction id (display/big-endian hex). */
+    readonly txid: string;
+    readonly outputIndex: number;
+    readonly height: number;
+    /** 0-based leaf position in the note-commitment tree. */
+    readonly position: number;
+    readonly valueSats: bigint;
+    /** 43-byte Sapling payment address the note pays to (hex). */
+    readonly recipientHex: string;
+    /** Note nullifier (hex) — its appearance in a block marks the note spent. */
+    readonly nullifierHex: string;
+}
+/**
+ * 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 declare function detectNotes(transport: LightwalletdTransport, prover: DetectProver, params: DetectNotesParams): Promise<SpendableNote[]>;
+/** A shielded (z) recipient of a spend. */
+export interface ShieldedRecipient {
+    readonly address: string;
+    readonly valueSats: bigint;
+    /** UTF-8 text memo (≤ 512 bytes). Ignored if `memoHex` is set. */
+    readonly memo?: string;
+    /** Raw memo bytes as hex (≤ 512 bytes) — for structured/binary memos (e.g. a
+     *  messenger frame). Takes precedence over `memo`. */
+    readonly memoHex?: string;
+}
+/** A transparent recipient of a spend, by raw output script. */
+export interface TransparentRecipient {
+    readonly scriptHex: string;
+    readonly valueSats: bigint;
+}
+export interface BuildShieldedSpendParams {
+    /** The note to spend, from `detectNotes` (its value + spending key). */
+    readonly note: {
+        readonly txid: string;
+        readonly outputIndex: number;
+        readonly extskHex: string;
+        /** The note's value in satoshis (from the detected `SpendableNote`). Used to
+         *  enforce value conservation before signing. */
+        readonly valueSats: bigint;
+    };
+    readonly shieldedOutputs?: readonly ShieldedRecipient[];
+    readonly transparentOutputs?: readonly TransparentRecipient[];
+    /** The miner fee in satoshis. **Required and explicit**: the fee is the note
+     *  value minus every output, so an unstated fee is silently whatever is left
+     *  over — a forgotten change output would donate it to miners. This value must
+     *  equal `note.valueSats − Σ outputs`, and is bounded by `maxFeeSats`. */
+    readonly feeSats: bigint;
+    /** Sanity ceiling on `feeSats` to catch a mis-computed fee (default 0.1 coin). */
+    readonly maxFeeSats?: bigint;
+    /** nExpiryHeight. Defaults to chain tip + 40. */
+    readonly expiryHeight?: number;
+    /** Consensus branch id. Defaults to Verus `CONSENSUS_BRANCH_ID` (0x76b809bb). */
+    readonly branchId?: number;
+}
+/**
+ * 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 declare function buildShieldedSpend(transport: LightwalletdTransport, prover: SpendProver, params: BuildShieldedSpendParams): Promise<{
+    hex: string;
+}>;