@heliuslabs/zolana-web-prover 0.2.0-alpha → 0.3.1-alpha

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.3.1-alpha — 2026-10-20
+
+- Published with npm provenance. No code changes.
+
+## 0.3.0-alpha — 2026-10-20
+
+The runtime ships in the package: an app installs it with npm, its bundler emits the worker, the Go bridge and the accelerator, and threaded proving works in a Chrome extension page.
+
+Breaking
+
+- `WasmProverOptions.wasmUrl` is gone; the worker loads the Go bridge and the accelerator from beside itself, where Vite and webpack 5 emit them.
+- `zolana-prover-assets` is now `zolana-prover-keys --output <directory> --keys <names>`, which installs proving keys for self-hosting and nothing else.
+
+Changed
+
+- Runtime 0.3.2, the 0.3.1 accelerator with Rayon's thread helpers for bundlers: its threads start from files the bundler emits rather than from `blob:` URLs, which an extension page refuses, so 0.2.0-alpha proves there only with `threads: 0`.
+- A thread pool that has not started after 30 s fails initialization with `wasm_init_failed` instead of waiting forever.
+- A key downloads in ranged parts of 8 MB kept in the cache as they arrive, so an interrupted download resumes where it stopped.
+- A kept decoded key is checked by its size instead of hashed on every load, about 0.02–0.05 s less per load after a page reload.
+
+Added
+
+- `neededKeys(maxInputs, outputs, maxMergeInputs)` names the keys spends and merges up to those limits prove with, for `prefetch`.
+- `prover.provingKeys()` lists every key with the bytes the browser keeps of it and whether its decoded form is kept; `ProvingKeyStatus` is exported.
+- `prover.clearKeys()` removes the kept keys, their decoded forms and interrupted downloads.
+
 ## 0.2.0-alpha — 2026-10-20
 
 The first release. `ZolanaWebProver` proves `@heliuslabs/zolana` 0.4.0-alpha transfer and merge requests in a browser worker with the threaded accelerator of runtime 0.3.1, verifies each proof before it returns it, and answers the SDK's `/prove` requests in the page through `createFetch()`. A warm proof takes 0.31 s for two notes to two outputs and 0.97 s for eight, in Chrome at four threads on an Apple M5 Pro.

package/README.md

@@ -2,23 +2,32 @@
 
 Local Groth16 proving and gnark verification in a browser worker. The core package has no protocol SDK or Solana dependencies. Transaction building, submission and benchmark orchestration live in the repository's browser example, not this package.
 
-## Install and serve assets
+## Install
 
 ```sh
 npm install @heliuslabs/zolana-web-prover
-npx --no-install zolana-prover-assets --output public --keys none
 ```
 
-The package contains the worker, the rebuilt Go Wasm bridge and its matching runtime shim. Proving keys and the threaded accelerator stay outside the core package. Keys load on first use from the pinned key set on the Zolana key CDN, which serves them with CORS, and are checked against the size and SHA-256 bundled in the package, so an app installs none. The asset command installs the bundled, sanitized Go bridge and sample request plus the pinned accelerator into your app's public directory; without `--keys none` it also installs the 2-input/2-output key for self-hosting. It checks the bundled bridge's manifest and verifies the release manifest's SHA-256 and size, then each downloaded file and key against the packaged lockfiles. It never installs the older Go bridge, shim or sample request from that release. It needs Node.js and network access, but no Go or Rust. Installation itself does not run downloads. For a local mirror, set `ZOLANA_RUNTIME_BASE_URL` and `ZOLANA_KEYS_BASE_URL` to `file:///.../` directories containing the release assets and keys respectively; the same digest checks apply.
+The package contains the worker, the sanitized Go Wasm bridge with its runtime shim, and the threaded accelerator. Import it, and the app's bundler emits them as files beside the worker; the packed-consumer CI builds an app with Vite and with webpack 5 and proves from both. A bundler that does not emit `new URL(…, import.meta.url)` assets and nested module workers (esbuild and Rollup without plugins) cannot load the runtime. Keys load on first use from the pinned key set on the Zolana key CDN, which serves them with CORS, and are checked against the size and SHA-256 bundled in the package, so an app installs none.
 
-Serve `public/prover`, `public/keys` if you self-host keys, and, for the demo, `public/fixtures` without flattening the accelerator's `snippets` directory. Serve `.wasm` as `application/wasm`, `.js` as JavaScript, and the document with:
+Serve the document with:
 
 ```text
 Cross-Origin-Opener-Policy: same-origin
 Cross-Origin-Embedder-Policy: require-corp
 ```
 
-Use HTTPS (localhost is suitable for development) and a bundler that preserves the emitted module worker asset URL; the packed-consumer CI tests Vite's production build. The accelerator must remain beside `zolana-prover.wasm` at `accelerator/gnark_kernel.js`. These headers are required for threaded proving. Set `threads: 0` for Go-only proving without cross-origin isolation. Apply compatible CORS/CORP policies if you host assets on another origin. Every key is checked against the size and SHA-256 bundled in the package from the pinned proving-keys lockfile, so the key host does not need to be trusted for integrity.
+Use HTTPS (localhost is suitable for development). These headers are required for threaded proving; set `threads: 0` for Go-only proving without cross-origin isolation. Every key is checked against the size and SHA-256 bundled in the package from the pinned proving-keys lockfile, so the key host does not need to be trusted for integrity.
+
+In a Chrome extension, prove from an extension page; an extension's service worker cannot start workers. Give the manifest the same isolation and allow WebAssembly:
+
+```json
+"cross_origin_embedder_policy": { "value": "require-corp" },
+"cross_origin_opener_policy": { "value": "same-origin" },
+"content_security_policy": { "extension_pages": "script-src 'self' 'wasm-unsafe-eval'; object-src 'self'" }
+```
+
+The packed-consumer CI proves from such a page with Go and with threads.
 
 ## Prove locally
 
@@ -26,7 +35,6 @@ Use HTTPS (localhost is suitable for development) and a bundler that preserves t
 import { ZolanaWebProver, WasmProverError } from "@heliuslabs/zolana-web-prover";
 
 const prover = new ZolanaWebProver({
-  wasmUrl: new URL("/prover/zolana-prover.wasm", location.href).href,
   proverUrl: "https://local-prover.invalid",
 });
 
@@ -44,15 +52,17 @@ try {
 
 ## Self-host proving keys
 
-To serve keys yourself, for offline use, a mirror or your own CDN, install the shapes your application's requests need and pass their location as `keyBaseUrl` (for example `keyBaseUrl: "/keys"`). Without `--keys`, the asset command installs only the demo's 2x2 key; real transfer shapes may differ (for example, 1x2):
+To serve keys yourself, for offline use, a mirror or your own CDN, install the shapes your application's requests need and pass their location as `keyBaseUrl` (for example `keyBaseUrl: "/keys"`):
 
 ```sh
-npx --no-install zolana-prover-assets --output public --keys transfer_confidential_1_2.key,transfer_confidential_2_2.key
+npx --no-install zolana-prover-keys --output public/keys --keys transfer_confidential_1_2.key,transfer_confidential_2_2.key
 ```
 
-`--keys` replaces the default selection. Names must be confidential-transfer or merge keys present in the pinned proving-keys lockfile; arbitrary names, paths and unsupported circuits are rejected before installation. Bytes still undergo size and SHA-256 checks. Use `keyForProveRequest` or `observeProofRequests` to identify needed shapes without logging witness bodies. A missing key fails rather than substituting a different circuit. Previously downloaded files are not deleted when selecting a new list.
+Names must be confidential-transfer or merge keys present in the pinned proving-keys lockfile; arbitrary names, paths and unsupported circuits are rejected before installation. Bytes still undergo size and SHA-256 checks. Use `keyForProveRequest` or `observeProofRequests` to identify needed shapes without logging witness bodies. A missing key fails rather than substituting a different circuit. Previously downloaded files are not deleted when selecting a new list. The command needs Node.js and network access; for a local mirror of the key set, set `ZOLANA_KEYS_BASE_URL` to a `file:///.../` directory, and the same checks apply.
+
+Keys are 9–362 MB each for confidential transfers (16 MB for 2x2, 94 MB for 12x8) and 56–380 MB for merge; deserialized circuits and proving work need additional memory. Only one deserialized key is retained, and changing shapes reloads it. The first load of a shape decompresses the key's curve points on the accelerator's thread pool (1.4 s for 2x2 and 4.9 s for 8x2 in Chrome at four threads on an Apple M5 Pro; slower with `threads: 0`, where Go decompresses them) and stores the decoded raw form in the browser Cache API in place of the downloaded file; later loads, including after a reload, read the raw form in 0.15 s (2x2) and 0.5 s (8x2), plus about 0.15 s to read it from the cache; it is checked by size, not hashed again, since a damaged entry fails its load and is rebuilt from the pinned key. The raw form is about 1.6× the file's size, and storage is subject to the browser's quota. Keys live in the Cache API store `zolana-proving-keys-<key set>`, and stores left by other key sets are deleted on first use. Pass `persistStorage: true` to ask the browser not to evict them under storage pressure (`navigator.storage.persist()`; Firefox asks the user). Install only the shapes you use, and budget separately for download/storage size and runtime memory.
 
-Keys are 9–362 MB each for confidential transfers (16 MB for 2x2, 94 MB for 12x8) and 56–380 MB for merge; deserialized circuits and proving work need additional memory. Only one deserialized key is retained, and changing shapes reloads it. The first load of a shape decompresses the key's curve points on the accelerator's thread pool (1.4 s for 2x2 and 4.9 s for 8x2 in Chrome at four threads on an Apple M5 Pro; slower with `threads: 0`, where Go decompresses them) and stores the decoded raw form in the browser Cache API in place of the downloaded file; later loads, including after a reload, read the raw form in 0.15 s (2x2) and 0.5 s (8x2), plus about 0.2 s to read and check it. The raw form is about 1.6× the file's size, and storage is subject to the browser's quota. Keys live in the Cache API store `zolana-proving-keys-<key set>`, and stores left by other key sets are deleted on first use. Pass `persistStorage: true` to ask the browser not to evict them under storage pressure (`navigator.storage.persist()`; Firefox asks the user). Install only the shapes you use, and budget separately for download/storage size and runtime memory.
+A key downloads in ranged parts of 8 MB, each kept in the cache as it arrives, so a download that a closed tab, a lost connection or an abort interrupted resumes where it stopped; a host that ignores ranges sends the whole key instead. The key is checked against the lockfile once it is whole, and a download that resumed from a damaged part starts over once.
 
 ## Prefetch keys
 
@@ -67,6 +77,14 @@ await prover.prefetch({
 
 `stage` is `download` while bytes arrive and `decode` once the worker starts loading the key. Pass `onKeyProgress` to the constructor to receive the same events for every load, including the ones a proof triggers. Without the Cache API only the last prefetched shape stays loaded.
 
+`neededKeys(maxInputs, outputs, maxMergeInputs)` names the shapes that spends of up to `maxInputs` notes with `outputs` outputs, and merges of up to `maxMergeInputs` notes, prove with, smallest first, for `prefetch`; a transfer has two outputs, the payment and the change. `provingKeys()` lists every key the prover can load with its size, the bytes the browser keeps of it and whether its decoded form is kept, without starting the worker. `clearKeys()` removes the kept keys, their decoded forms and interrupted downloads after any work in progress. These follow the mobile SDK's `ProvingKeys.needed`, `status` and `clear`:
+
+```ts
+const shapes = neededKeys(8, [2], 24); // spends of up to 8 notes, merges of up to 24
+await prover.prefetch({ shapes });
+const kept = (await prover.provingKeys()).reduce((sum, key) => sum + key.downloaded, 0);
+```
+
 ## Lifecycle and failures
 
 - First use initializes the worker automatically. Requests are serialized; only one deserialized key is resident at a time.
@@ -75,4 +93,4 @@ await prover.prefetch({
 - `terminate()` rejects outstanding work, clears the factory and disables automatic restart. Create a new prover, or explicitly call `start(factory)` to reuse the object. A supplied single `Worker` cannot be recreated automatically.
 - `WasmProverError.code` and its fixed message identify failures without serializing backend messages, witness values, causes or stacks from the backend. Core code does not log errors. The fetch adapter returns a JSON 500 with the safe `code` and `message`; cancellation rejects instead. Caller-provided abort reasons and callback errors remain caller-controlled and should not contain secrets.
 
-The accelerator comes from the `runtime-v0.3.1` release; the Go bridge is rebuilt from source and bundled, so that release's older bridge, shim and sample request are ignored. The TypeScript worker/API boundary additionally redacts backend errors as defense in depth.
+The accelerator comes from the `runtime-v0.3.2` release, built with Rayon's thread helpers for bundlers; the Go bridge is built from source. The TypeScript worker/API boundary additionally redacts backend errors as defense in depth.

package/dist/abortable.d.ts

@@ -1,2 +1,4 @@
 /** Race work against cancellation even when an I/O implementation ignores signals. */
 export declare function abortable<T>(work: Promise<T>, signal?: AbortSignal): Promise<T>;
+/** Rethrows a cancellation, so a caller that swallows other errors still stops. */
+export declare function rethrowAbort(error: unknown, signal?: AbortSignal): void;

package/dist/abortable.js

@@ -0,0 +1,30 @@
+/** Race work against cancellation even when an I/O implementation ignores signals. */
+export function abortable(work, signal) {
+    if (signal === undefined)
+        return work;
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason);
+        const cleanup = () => signal.removeEventListener("abort", abort);
+        // Always observe work, including when the signal was already aborted.
+        work.then((value) => {
+            cleanup();
+            if (signal.aborted)
+                reject(signal.reason);
+            else
+                resolve(value);
+        }, (error) => {
+            cleanup();
+            reject(signal.aborted ? signal.reason : error);
+        });
+        if (signal.aborted)
+            abort();
+        else
+            signal.addEventListener("abort", abort, { once: true });
+    });
+}
+/** Rethrows a cancellation, so a caller that swallows other errors still stops. */
+export function rethrowAbort(error, signal) {
+    signal?.throwIfAborted();
+    if (error instanceof Error && error.name === "AbortError")
+        throw error;
+}

package/dist/errors.js

@@ -0,0 +1,38 @@
+const messages = {
+    wasm_prover_error: "Prover operation failed",
+    wasm_init_failed: "Prover initialization failed; check runtime assets, threads and isolation headers",
+    wasm_worker_failed: "Prover worker failed",
+    wasm_worker_not_started: "Prover worker is not started",
+    wasm_worker_terminated: "Prover worker terminated",
+    wasm_invalid_response: "Invalid prover response",
+    wasm_invalid_request: "Unsupported circuit or malformed request",
+    wasm_key_manifest_error: "The proving key is not in the pinned key set",
+    wasm_key_download_failed: "Proving-key download failed",
+    wasm_key_digest_mismatch: "Proving key does not match the lockfile; stage the pinned assets",
+    wasm_key_load_failed: "Proving-key loading failed",
+    wasm_prove_failed: "Proof generation failed",
+    wasm_verify_failed: "Native gnark verification rejected the proof",
+};
+export class WasmProverError extends Error {
+    code;
+    constructor(code = "wasm_prover_error") {
+        const safeCode = Object.hasOwn(messages, code) ? code : "wasm_prover_error";
+        super(messages[safeCode]);
+        this.name = "WasmProverError";
+        this.code = safeCode;
+    }
+}
+export function operationError(kind) {
+    switch (kind) {
+        case "init":
+            return new WasmProverError("wasm_init_failed");
+        case "loadKey":
+            return new WasmProverError("wasm_key_load_failed");
+        case "prove":
+            return new WasmProverError("wasm_prove_failed");
+        case "verify":
+            return new WasmProverError("wasm_verify_failed");
+        default:
+            return new WasmProverError("wasm_worker_failed");
+    }
+}

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-export { TRANSFER_SHAPES, MERGE_KEY_BYTES, MERGE_KEY_FILE, MERGE_SHAPE, MERGE_SHAPES, keyForProveRequest, canonicalShape, formatBytes, shapeByLabel, type Shape, type ShapeKey, } from "./shapes.js";
+export { TRANSFER_SHAPES, MERGE_KEY_BYTES, MERGE_KEY_FILE, MERGE_SHAPE, MERGE_SHAPES, keyForProveRequest, canonicalShape, formatBytes, neededKeys, shapeByLabel, type Shape, type ShapeKey, } from "./shapes.js";
 export { KEY_BASE_URL } from "./key-digests.js";
 export type { KeyProgress, Measurement } from "./measurement.js";
 export type { WasmProverErrorCode } from "./errors.js";
 export { WasmProver, WasmProver as ZolanaWebProver, WasmProverError, type WasmProverOptions, type WorkerRequest, type WorkerResponse, } from "./wasm-prover.js";
+export type { ProvingKeyStatus } from "./key-store.js";
 export { automaticProvingThreads } from "./proving-threads.js";
 export { observeProofRequests } from "./proof-requests.js";