@midnight-ntwrk/wallet-sdk-prover-client 2.0.0-beta.2 → 2.0.0-beta.4

package/README.md

@@ -57,6 +57,43 @@ class HttpProverClient {
 }
 ```
 
+### Proving providers, per ledger version
+
+A proof preimage is produced by the ledger version that built the transaction, and the request carrying it has to be
+framed and read back by that same version. `HttpProverClient` therefore offers one provider per ledger version:
+
+```typescript
+const client = await Effect.runPromise(HttpProverClient.create({ url: proofServerUrl }));
+
+client.asV9ProvingProvider(); // frames with @midnightntwrk/ledger-v9; asProvingProvider() is the same provider
+client.asV8ProvingProvider(); // frames with @midnight-ntwrk/ledger-v8
+```
+
+`WasmProver` offers both names too, and returns the same provider for each: the in-process prover drives a zkir runtime
+over bytes and never looks at a ledger version. Its key material, though, is per ledger version: each ledger version's
+circuits were generated as their own generation, and a node rejects a proof made with another's. Create the prover with
+the key material of the ledger version it proves for:
+
+```typescript
+WasmProver.makeV9KeyMaterialProvider(); // ledger-v9: circuit generation 10
+WasmProver.makeV8KeyMaterialProvider(); // ledger-v8: circuit generation 9
+WasmProver.makeDefaultKeyMaterialProvider(); // the same as makeV9KeyMaterialProvider()
+```
+
+Each reads from `https://srs.midnight.network/`, the host the ledger's own data provider reads, and checks every file
+against the SHA-256 its ledger release declares before handing it back; a file that does not match is refused with
+`KeyMaterialIntegrityError`. To serve the files yourself — a mirror, or your page's own origin, since that host sends no
+CORS headers — pass `{ source }`; the files are checked all the same:
+
+```typescript
+WasmProver.makeV9KeyMaterialProvider({ source: 'https://example.com/midnight-keys/' });
+```
+
+Checking needs Web Crypto (`crypto.subtle`): Node 19 or later, or a browser page served from a secure context.
+
+> This package depends on both ledger runtimes, `@midnight-ntwrk/ledger-v8` and `@midnightntwrk/ledger-v9`. Both are
+> WASM modules, so a direct consumer bundling this package ships both.
+
 ## Exports
 
 ### Default Export

package/dist/effect/HttpProverClient.js

@@ -15,9 +15,20 @@ import { FetchHttpClient, HttpBody, HttpClient, HttpClientRequest } from '@effec
 import { ProverClient } from './ProverClient.js';
 import { ClientError, HttpURL, ServerError, } from '@midnight-ntwrk/wallet-sdk-utilities/networking';
 import { BlobOps, EitherOps } from '@midnight-ntwrk/wallet-sdk-utilities';
-import * as ledger from '@midnightntwrk/ledger-v9';
+import * as ledgerV8 from '@midnight-ntwrk/ledger-v8';
+import * as ledgerV9 from '@midnightntwrk/ledger-v9';
 const PROVE_TX_PATH = '/prove';
 const CHECK_TX_PATH = '/check';
+const v9Framing = {
+    createProvingPayload: (preimage, binding) => ledgerV9.createProvingPayload(preimage, binding),
+    createCheckPayload: (preimage) => ledgerV9.createCheckPayload(preimage),
+    parseCheckResult: (result) => ledgerV9.parseCheckResult(result),
+};
+const v8Framing = {
+    createProvingPayload: (preimage, binding) => ledgerV8.createProvingPayload(preimage, binding),
+    createCheckPayload: (preimage) => ledgerV8.createCheckPayload(preimage),
+    parseCheckResult: (result) => ledgerV8.parseCheckResult(result),
+};
 /**
  * Creates a layer for a {@link ProverClient} that sends requests to a Proof Server over HTTP.
  *
@@ -65,15 +76,15 @@ class HttpProverClientImpl {
             ResponseError: (err) => Effect.orElseSucceed(err.response.text, () => 'Unknown server error').pipe(Effect.flatMap((message) => new ServerError({ message }))),
         }), Effect.provide(FetchHttpClient.layer));
     }
-    serverProverProvider = () => ({
-        check: async (serializedPreimage, _keyLocation) => pipe(Effect.succeed(ledger.createCheckPayload(serializedPreimage)), Effect.flatMap((tx) => this.request(CHECK_TX_PATH, tx, 'Failed to check')), Effect.map((response) => ledger.parseCheckResult(response)), Effect.runPromise),
-        prove: async (serializedPreimage, _keyLocation, overwriteBindingInput) => pipe(Effect.succeed(ledger.createProvingPayload(serializedPreimage, overwriteBindingInput)), Effect.flatMap((tx) => this.request(PROVE_TX_PATH, tx, 'Failed to prove')), Effect.runPromise),
+    serverProverProvider = (framing) => ({
+        check: async (serializedPreimage, _keyLocation) => pipe(Effect.succeed(framing.createCheckPayload(serializedPreimage)), Effect.flatMap((tx) => this.request(CHECK_TX_PATH, tx, 'Failed to check')), Effect.map((response) => framing.parseCheckResult(response)), Effect.runPromise),
+        prove: async (serializedPreimage, _keyLocation, overwriteBindingInput) => pipe(Effect.succeed(framing.createProvingPayload(serializedPreimage, overwriteBindingInput)), Effect.flatMap((tx) => this.request(PROVE_TX_PATH, tx, 'Failed to prove')), Effect.runPromise),
         // The proof server holds its own key material and resolves circuits from the
         // preimage's key location, so there is never local key material to provide.
         lookupKey: (_keyLocation) => Promise.resolve(undefined),
     });
     proveTransaction(transaction, costModel) {
-        return pipe(Effect.succeed(this.serverProverProvider()), Effect.flatMap((provider) => Effect.tryPromise({
+        return pipe(Effect.succeed(this.serverProverProvider(v9Framing)), Effect.flatMap((provider) => Effect.tryPromise({
             try: () => transaction.prove(provider, costModel),
             catch: (error) => error instanceof ClientError || error instanceof ServerError
                 ? error
@@ -81,6 +92,12 @@ class HttpProverClientImpl {
         })));
     }
     asProvingProvider() {
-        return this.serverProverProvider();
+        return this.serverProverProvider(v9Framing);
+    }
+    asV9ProvingProvider() {
+        return this.asProvingProvider();
+    }
+    asV8ProvingProvider() {
+        return this.serverProverProvider(v8Framing);
     }
 }

package/dist/effect/KeyMaterial.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The key material each ledger version's circuits were generated with, and a provider that reads it and checks it.
+ *
+ * @remarks
+ *   A node verifies a proof against the verifier keys of the circuit generation its ledger version was built with, so a
+ *   proof has to be made with that generation's key material, byte for byte. Which generation that is, and what every
+ *   file of it hashes to, is declared by the ledger release itself (`midnight-ledger`: `static/version`,
+ *   `ledger/static/dust/*.sha256`, `zswap/static/*.sha256`, and the parameter hashes in `base-crypto`'s data provider);
+ *   the descriptors below are copies of those declarations, one per ledger version. Nothing at runtime can re-derive
+ *   them: the published ledger packages neither expose the generation nor embed the Dust spend verifier key.
+ */
+import type { KeyMaterialProvider } from '@midnight-ntwrk/zkir-v2';
+import { Cause, Schedule } from 'effect';
+/** The host the ledger's own data provider reads key material from: its `MIDNIGHT_PARAM_SOURCE` default. */
+export declare const DefaultKeyMaterialSource = "https://srs.midnight.network/";
+/** A circuit whose key material the ledger resolves by location, named as the host lays it out. */
+export type Circuit = 'zswap/spend' | 'zswap/output' | 'zswap/sign' | 'dust/spend';
+/** The three files a circuit's key material is made of. */
+type KeyFileKind = 'prover' | 'verifier' | 'bzkir';
+/** One file of one circuit's key material, named as the ledger names its hash (`<family>/<name>.<kind>`). */
+export type KeyFile = `${Circuit}.${KeyFileKind}`;
+/** A SHA-256 digest, as lowercase hex. */
+type Sha256 = string;
+/**
+ * The key material one ledger version's circuits were generated with.
+ *
+ * @remarks
+ *   A copy of what one ledger release declares. `ledgerRelease` records which: the pins hold for that release, and a test
+ *   compares it with the ledger package installed, so that a ledger upgrade cannot leave them behind unnoticed.
+ */
+export type KeyMaterialDescriptor = Readonly<{
+    /** The ledger release the pins were copied from: its npm package and version, and its `midnight-ledger` tag. */
+    ledgerRelease: Readonly<{
+        packageName: string;
+        version: string;
+        tag: string;
+    }>;
+    /** The circuit generation the ledger's key locations resolve to (`static/version`). */
+    generation: number;
+    /** What each file of each circuit hashes to. */
+    files: Readonly<Record<KeyFile, Sha256>>;
+    /** What the public parameters for each size `k` hash to. */
+    params: Readonly<Record<number, Sha256>>;
+}>;
+/** Ledger-v9's key material: circuit generation 10, as `midnight-ledger` `ledger-9.1.0.0-rc.5` declares it. */
+export declare const V9KeyMaterial: KeyMaterialDescriptor;
+/** Ledger-v8's key material: circuit generation 9, as `midnight-ledger` `ledger-8.1.0` declares it. */
+export declare const V8KeyMaterial: KeyMaterialDescriptor;
+declare const KeyMaterialIntegrityError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "@midnight-ntwrk/wallet-sdk-prover-client/effect/KeyMaterial/KeyMaterialIntegrityError";
+} & Readonly<A>;
+/** Raised when a key material file does not hash to what the ledger release declares for it. */
+export declare class KeyMaterialIntegrityError extends KeyMaterialIntegrityError_base<{
+    readonly message: string;
+    /** The file whose bytes did not match. */
+    readonly url: string;
+    /** What the ledger release declares the file hashes to. */
+    readonly expected: string;
+    /** What the bytes received hash to. */
+    readonly actual: string;
+}> {
+}
+declare const KeyMaterialFetchError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "@midnight-ntwrk/wallet-sdk-prover-client/effect/KeyMaterial/KeyMaterialFetchError";
+} & Readonly<A>;
+/** Raised when the host answers a request for key material with anything but success. */
+export declare class KeyMaterialFetchError extends KeyMaterialFetchError_base<{
+    readonly message: string;
+    /** The file that was asked for. */
+    readonly url: string;
+    /** The HTTP status the host answered with. */
+    readonly status: number;
+}> {
+}
+declare const KeyMaterialTransferError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "@midnight-ntwrk/wallet-sdk-prover-client/effect/KeyMaterial/KeyMaterialTransferError";
+} & Readonly<A>;
+/**
+ * Raised when no complete answer arrives for a request for key material: the host was unreachable, or the transfer
+ * broke off.
+ */
+export declare class KeyMaterialTransferError extends KeyMaterialTransferError_base<{
+    readonly message: string;
+    /** The file that was asked for. */
+    readonly url: string;
+    readonly cause: unknown;
+}> {
+}
+declare const UnknownPublicParametersError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "@midnight-ntwrk/wallet-sdk-prover-client/effect/KeyMaterial/UnknownPublicParametersError";
+} & Readonly<A>;
+/** Raised when public parameters are asked for at a size `k` the ledger does not publish. */
+export declare class UnknownPublicParametersError extends UnknownPublicParametersError_base<{
+    readonly message: string;
+    /** The size that was asked for. */
+    readonly k: number;
+}> {
+}
+/** Everything reading key material can fail with. */
+export type KeyMaterialError = KeyMaterialIntegrityError | KeyMaterialFetchError | KeyMaterialTransferError | UnknownPublicParametersError;
+/** How a provider reads key material. */
+export type KeyMaterialProviderOptions = Readonly<{
+    /** Where to read from. A path is kept: `https://example.com/keys` reads `https://example.com/keys/dust/…`. */
+    source: URL | string;
+    /** How often, and how far apart, to ask again after a failure that may pass. */
+    retrySchedule?: Schedule.Schedule<unknown, unknown>;
+}>;
+/**
+ * A key material provider for the ledger version a descriptor describes.
+ *
+ * @remarks
+ *   Every file is checked against the descriptor before it is handed back, and kept once it has been: a circuit or a
+ *   parameter size is read once per provider, however often and however concurrently it is asked for. A failure is not
+ *   kept. Checking needs Web Crypto (`crypto.subtle`): Node 19 or later, or a browser page served from a secure
+ *   context.
+ * @param descriptor The key material to read, and what each file must hash to.
+ * @param options Where to read from, and how to retry.
+ * @returns A provider for the zkir runtime. Its lookups reject with a {@link KeyMaterialError}.
+ * @throws TypeError if `options.source` is not a URL.
+ */
+export declare const makeKeyMaterialProvider: (descriptor: KeyMaterialDescriptor, options: KeyMaterialProviderOptions) => KeyMaterialProvider;
+export {};

package/dist/effect/KeyMaterial.js

@@ -0,0 +1,187 @@
+import { Cache, Cause, Data, Duration, Effect, Exit, Option, Record as ERecord, Schedule, pipe } from 'effect';
+/** The host the ledger's own data provider reads key material from: its `MIDNIGHT_PARAM_SOURCE` default. */
+export const DefaultKeyMaterialSource = 'https://srs.midnight.network/';
+/** The public parameters `bls_midnight_2p<k>`, as `base-crypto` declares them; no ledger release has changed them. */
+const publicParameters = {
+    0: '59b30b3114a34ccbbfb599376e178fb8d9b3366cae2174c2f1da20e75847f823',
+    1: 'bbe04fe3c70d0c138447cb086b4baddc30cb8bb2a004114bc02e6f739516280e',
+    2: '80e15568fa1a0117db893239be7fa5e34a6bcc3a8c3bfa7709534b9cb88eb6c1',
+    3: '4be827a6472193df80d8f08b4b25a85baef436fdd1965d89b6af89f4ec4e99e2',
+    4: '232f401fad10c7ddf8828d2aa4c85c6506c5da09795998cecaeb9f75fc8f6ada',
+    5: '0a1c9229f315fc1868ff25f668fb83aec4d09f4f23a706b5197c692c619d72c6',
+    6: 'cf2ad6be7d0fedf5bec2aaa35f6be4aca33053d74268fdf5aa54fcb2891ea6df',
+    7: 'e82ae890c080188355f37feaffe91372584cd810615082d9143d4dec0453fd9d',
+    8: '909b707551eaaea79828e883cde6fc46ab15986c3b1d791bed462c9e2805c933',
+    9: 'b9009f1098bcefffec3c461ab3a5e3a17f7e5599f0f08c70fcdc55a89227bcbd',
+    10: '46b2290933cbed4c378889e4ba971f1a92888331ffb09466acd4ff61a1e2cb42',
+    11: '9901589d7956ff58be0d85569b2f455b77b58c3758026ffb5bbe4807000b96d1',
+    12: 'ef08eb3fcf62df8f72c515cffa027e681808b530cb016eea104115545ef6d5c8',
+    13: 'd3324910969c4cc54143b8045b649e5c3a4bd5fb7b8f85fe1b770f640ce1c803',
+    14: 'fc253016885ec830e97808c9ec920bb5cab5c21af590380a6cb5eb0538e2b244',
+    15: '724c7c3d779148bb113c7ee9c034b2f27db16e6bdf315fde90105a9bad00b1de',
+    16: '09c877216d6589b370263e18af40a030a901b41a7a7c37ef58c9901db41f05c6',
+    17: '4a9ef6c7c0619aab74eede44b13e753e3ba54508a02dd3b7106a949aabb73b74',
+    18: 'e8436dc5d8b598f169c127c745135d889744007e6d384ff126df8d1332522f86',
+    19: '8e8dc15c4362f05c912f1e770559a3945db3e58a374def416ed5d3e65ad5b10e',
+    20: '1cc62978558fdc1e445cd70cfd9a86ec3c2e2151b6d74811232d37faf9133ff1',
+    21: '9cf1644a87f0f027ae5fc6278f91d823a6334ff3e338a29e2f2ef57d071ed64d',
+    22: 'e8ad5eed936d657a0fb59d2a55ba19f81a3083bb3554ef88f464f5377e9b2c2f',
+    23: '09399d05f9f50875dfdd87dc9903d40c897eaafa9ec8cbb08bace853ecc36c0c',
+    24: 'b0e6fa7a4ab4a79a1e6560966f267556409db44bab6d5fab3711ad6c6b623207',
+    25: '3289a751c938988cd2f54154d8722d1eda2cd11593064afdde82099b24ff4a58',
+};
+/** Zswap's key material: the same bytes in circuit generations 9 and 10. */
+const zswapFiles = {
+    'zswap/spend.prover': '19d234b5c68b7212ad6b0ec9334a95594748154128f3704eb576bcc843cc5c45',
+    'zswap/spend.verifier': '544554effd7ae9fb9063be52a9ec2a986756301071fcd97bb4598fb45a335658',
+    'zswap/spend.bzkir': '7cb5bbcf67cb212a3336fb439a77e8f32f0aa8a56185c8e1247d6cbfc7300205',
+    'zswap/output.prover': 'd992b04f13c3fd432f55fb8bfe6466d87bc181f1a2acf233ec228030bbdd4ed8',
+    'zswap/output.verifier': '72e8074856f2f5c504ade25a86a2b8902c64aeb9497c4c8e6b26dea842a0ab08',
+    'zswap/output.bzkir': '91dc8b401dd8385e8d29eaac018c70b578505f48c7952452ef319bc397fa1f1b',
+    'zswap/sign.prover': 'fe7268dd2bdd107f862f881ac3c5bc71a6df77ce80bfed51cf71514648e660e0',
+    'zswap/sign.verifier': 'e39a727caa0de167e6dd6122a9e3b758fecf48f9093ab77c0309648de8ce07e1',
+    'zswap/sign.bzkir': '37ea2094516e145a738126307cf92bd293f7cb524b1ccd49fa6f3225a9ec3a50',
+};
+/** Ledger-v9's key material: circuit generation 10, as `midnight-ledger` `ledger-9.1.0.0-rc.5` declares it. */
+export const V9KeyMaterial = {
+    ledgerRelease: { packageName: '@midnightntwrk/ledger-v9', version: '1.0.0-rc.5', tag: 'ledger-9.1.0.0-rc.5' },
+    generation: 10,
+    files: {
+        ...zswapFiles,
+        'dust/spend.prover': '3dff9f54add761350ad02621a425d67fe3d656c8145fef8ef147870489ffdc81',
+        'dust/spend.verifier': 'd15a1295780549f534287a39c938005e1faa3232be21861573bd0cdb148949cb',
+        'dust/spend.bzkir': 'd211cacb22391b9db60f945787d98c16d344cbb4790246132117084c080399c1',
+    },
+    params: publicParameters,
+};
+/** Ledger-v8's key material: circuit generation 9, as `midnight-ledger` `ledger-8.1.0` declares it. */
+export const V8KeyMaterial = {
+    ledgerRelease: { packageName: '@midnight-ntwrk/ledger-v8', version: '8.1.0', tag: 'ledger-8.1.0' },
+    generation: 9,
+    files: {
+        ...zswapFiles,
+        'dust/spend.prover': '996602da7ca386284e656c78ea03e55bffdba29475e6a67965c50de05e13efc2',
+        'dust/spend.verifier': '3f1569ebcab0655c5c145b28947c74edc4e3f5c6b276e4404b661cf0905b49d3',
+        'dust/spend.bzkir': '904181287e75b0fb596ba5fcc116c882ee5d28e3115304c93ebd913722ce5841',
+    },
+    params: publicParameters,
+};
+/** Raised when a key material file does not hash to what the ledger release declares for it. */
+export class KeyMaterialIntegrityError extends Data.TaggedError('@midnight-ntwrk/wallet-sdk-prover-client/effect/KeyMaterial/KeyMaterialIntegrityError') {
+}
+/** Raised when the host answers a request for key material with anything but success. */
+export class KeyMaterialFetchError extends Data.TaggedError('@midnight-ntwrk/wallet-sdk-prover-client/effect/KeyMaterial/KeyMaterialFetchError') {
+}
+/**
+ * Raised when no complete answer arrives for a request for key material: the host was unreachable, or the transfer
+ * broke off.
+ */
+export class KeyMaterialTransferError extends Data.TaggedError('@midnight-ntwrk/wallet-sdk-prover-client/effect/KeyMaterial/KeyMaterialTransferError') {
+}
+/** Raised when public parameters are asked for at a size `k` the ledger does not publish. */
+export class UnknownPublicParametersError extends Data.TaggedError('@midnight-ntwrk/wallet-sdk-prover-client/effect/KeyMaterial/UnknownPublicParametersError') {
+}
+/** Four more attempts after the first, one, two, four and eight seconds apart. */
+const defaultRetrySchedule = pipe(Schedule.exponential(Duration.seconds(1), 2), Schedule.intersect(Schedule.recurs(4)));
+/** Room for every circuit and every parameter size a descriptor names. */
+const cacheCapacity = 64;
+const circuitsByKeyLocation = {
+    'midnight/zswap/spend': 'zswap/spend',
+    'midnight/zswap/output': 'zswap/output',
+    'midnight/zswap/sign': 'zswap/sign',
+    'midnight/dust/spend': 'dust/spend',
+};
+/** A failure that asking again may cure: no complete answer, a server error, or being asked to slow down. */
+const mayPass = (error) => error instanceof KeyMaterialTransferError || error.status >= 500 || error.status === 429;
+/** Resolves a path against the source, keeping any path the source has. */
+const sourceBase = (source) => {
+    const href = source.toString();
+    return new URL(href.endsWith('/') ? href : `${href}/`);
+};
+const fetchBytes = (url) => pipe(Effect.tryPromise({
+    try: (signal) => globalThis.fetch(url, { signal }),
+    catch: (cause) => new KeyMaterialTransferError({
+        message: `Could not fetch ${url.href}: ${String(cause)}`,
+        url: url.href,
+        cause,
+    }),
+}), Effect.filterOrFail((response) => response.ok, (response) => new KeyMaterialFetchError({
+    message: `${url.href} answered ${response.status}${response.statusText === '' ? '' : ` ${response.statusText}`}`,
+    url: url.href,
+    status: response.status,
+})), Effect.flatMap((response) => Effect.tryPromise({
+    try: () => response.arrayBuffer(),
+    catch: (cause) => new KeyMaterialTransferError({
+        message: `The transfer of ${url.href} broke off: ${String(cause)}`,
+        url: url.href,
+        cause,
+    }),
+})), Effect.map((buffer) => new Uint8Array(buffer)));
+const sha256Of = (bytes) => pipe(Effect.promise(() => globalThis.crypto.subtle.digest('SHA-256', bytes)), Effect.map((digest) => Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('')));
+/** Reads one file, asking again while the failure may pass, and hands it back only if it hashes to `expected`. */
+const fetchVerified = (url, expected, retrySchedule) => pipe(fetchBytes(url), Effect.tapError((error) => mayPass(error) ? Effect.logWarning(`${error.message} (asking again while retries remain)`) : Effect.void), Effect.retry({ schedule: retrySchedule, while: mayPass }), Effect.flatMap((bytes) => pipe(sha256Of(bytes), Effect.filterOrFail((actual) => actual === expected, (actual) => new KeyMaterialIntegrityError({
+    message: `${url.href} hashes to ${actual}, but the ledger release declares ${expected}`,
+    url: url.href,
+    expected,
+    actual,
+})), Effect.as(bytes))));
+/**
+ * Runs a read at the Promise boundary the zkir runtime calls through, rejecting with the error itself rather than
+ * Effect's wrapper around it.
+ */
+const runAtBoundary = (effect) => Effect.runPromiseExit(effect).then(Exit.match({
+    onSuccess: (value) => Promise.resolve(value),
+    onFailure: (cause) => {
+        const error = Cause.squash(cause);
+        return Promise.reject(error instanceof Error ? error : new Error(String(error)));
+    },
+}));
+/**
+ * Reads through a cache that keeps what was read for good but forgets a failure at once, so that the next request reads
+ * again. The failure is dropped explicitly: a cache entry that expires "now" can still be served within the same
+ * instant.
+ */
+const readThrough = (cache, key) => pipe(cache.get(key), Effect.tapError(() => cache.invalidate(key)));
+/**
+ * A key material provider for the ledger version a descriptor describes.
+ *
+ * @remarks
+ *   Every file is checked against the descriptor before it is handed back, and kept once it has been: a circuit or a
+ *   parameter size is read once per provider, however often and however concurrently it is asked for. A failure is not
+ *   kept. Checking needs Web Crypto (`crypto.subtle`): Node 19 or later, or a browser page served from a secure
+ *   context.
+ * @param descriptor The key material to read, and what each file must hash to.
+ * @param options Where to read from, and how to retry.
+ * @returns A provider for the zkir runtime. Its lookups reject with a {@link KeyMaterialError}.
+ * @throws TypeError if `options.source` is not a URL.
+ */
+export const makeKeyMaterialProvider = (descriptor, options) => {
+    const base = sourceBase(options.source);
+    const retrySchedule = options.retrySchedule ?? defaultRetrySchedule;
+    const readFile = (circuit, kind) => {
+        const file = `${circuit}.${kind}`;
+        const path = `${circuit.replace('/', `/${descriptor.generation}/`)}.${kind}`;
+        return fetchVerified(new URL(path, base), descriptor.files[file], retrySchedule);
+    };
+    const readCircuit = (circuit) => Effect.all({
+        proverKey: readFile(circuit, 'prover'),
+        verifierKey: readFile(circuit, 'verifier'),
+        ir: readFile(circuit, 'bzkir'),
+    });
+    const readParams = (k) => Option.match(Option.fromNullable(descriptor.params[k]), {
+        onNone: () => Effect.fail(new UnknownPublicParametersError({
+            message: `The ledger publishes no public parameters for k = ${k}`,
+            k,
+        })),
+        onSome: (expected) => fetchVerified(new URL(`bls_midnight_2p${k}`, base), expected, retrySchedule),
+    });
+    const circuits = Effect.runSync(Cache.make({ capacity: cacheCapacity, timeToLive: Duration.infinity, lookup: readCircuit }));
+    const params = Effect.runSync(Cache.make({ capacity: cacheCapacity, timeToLive: Duration.infinity, lookup: readParams }));
+    return {
+        lookupKey: (keyLocation) => Option.match(ERecord.get(circuitsByKeyLocation, keyLocation), {
+            onNone: () => Promise.resolve(undefined),
+            onSome: (circuit) => runAtBoundary(readThrough(circuits, circuit)),
+        }),
+        getParams: (k) => runAtBoundary(readThrough(params, k)),
+    };
+};

package/dist/effect/ProverClient.d.ts

@@ -1,5 +1,6 @@
 import { type Effect, Context } from 'effect';
-import type * as ledger from '@midnightntwrk/ledger-v9';
+import type * as ledgerV8 from '@midnight-ntwrk/ledger-v8';
+import type * as ledgerV9 from '@midnightntwrk/ledger-v9';
 import { type ClientError, type ServerError } from '@midnight-ntwrk/wallet-sdk-utilities/networking';
 import type { KeyMaterialProvider } from '@midnight-ntwrk/zkir-v2';
 declare const ProverClient_base: Context.TagClass<ProverClient, "@midnight-ntwrk/prover-client#ProverClient", ProverClient.Service>;
@@ -25,8 +26,21 @@ export declare namespace ProverClient {
          * @returns An `Effect` that yields with a serialized transaction representing the proven version of `transaction`;
          *   or fails with a client or server side error.
          */
-        proveTransaction<S extends ledger.Signaturish, B extends ledger.Bindingish>(tx: ledger.Transaction<S, ledger.PreProof, B>, costModel?: ledger.CostModel): Effect.Effect<ledger.Transaction<S, ledger.Proof, B>, ClientError | ServerError>;
-        asProvingProvider(): ledger.ProvingProvider;
+        proveTransaction<S extends ledgerV9.Signaturish, B extends ledgerV9.Bindingish>(tx: ledgerV9.Transaction<S, ledgerV9.PreProof, B>, costModel?: ledgerV9.CostModel): Effect.Effect<ledgerV9.Transaction<S, ledgerV9.Proof, B>, ClientError | ServerError>;
+        /** A proving provider that frames its requests with ledger-v9. */
+        asProvingProvider(): ledgerV9.ProvingProvider;
+        /** The same provider as {@link asProvingProvider}, named for the ledger version it frames with. */
+        asV9ProvingProvider(): ledgerV9.ProvingProvider;
+        /**
+         * A proving provider that frames its requests with ledger-v8.
+         *
+         * @remarks
+         *   A preimage is produced by the ledger version that built the transaction, and has to be framed and read back by
+         *   that same version — so a client serving a ledger-v8 transaction is asked for this provider rather than the
+         *   other. An in-process prover frames nothing: it works on bytes, and offers the same provider for both. What it
+         *   proves for is decided by the key material it was created with, which is per ledger version.
+         */
+        asV8ProvingProvider(): ledgerV8.ProvingProvider;
     }
 }
 export {};

package/dist/effect/WasmProver.d.ts

@@ -44,4 +44,73 @@ export declare const GetParamsOperationResultSchema: Schema.Struct<{
     k: typeof Schema.Number;
     result: typeof Schema.Uint8Array;
 }>;
-export declare const makeDefaultKeyMaterialProvider: () => KeyMaterialProvider;
+export { DefaultKeyMaterialSource, KeyMaterialFetchError, KeyMaterialIntegrityError, KeyMaterialTransferError, UnknownPublicParametersError, type KeyMaterialError, } from './KeyMaterial.js';
+/** Where the bundled key material providers read from. */
+export type KeyMaterialConfig = {
+    /**
+     * The host to read key material from, in place of {@link DefaultKeyMaterialSource}.
+     *
+     * @remarks
+     *   For serving the files yourself — a mirror, or the page's own origin in a browser, since the default host sends no
+     *   CORS headers. The files are laid out as the default host lays them out (`dust/10/spend.prover`,
+     *   `bls_midnight_2p14`, …), and a path is kept: `https://example.com/keys` reads `https://example.com/keys/dust/…`.
+     *   Whatever the host, every file is checked against the hash its ledger release declares.
+     */
+    readonly source?: URL | string;
+};
+/**
+ * The key material ledger-v9's circuits were generated with: circuit generation 10.
+ *
+ * @remarks
+ *   Every file is read from the host the ledger's own data provider reads (or from `config.source`) and checked against
+ *   the SHA-256 the ledger release declares before it is handed back; a file that does not match is refused with
+ *   {@link KeyMaterialIntegrityError}, since a proof made with it would be rejected by a node. Each circuit and each
+ *   parameter size is read once per provider. Checking needs Web Crypto (`crypto.subtle`): Node 19 or later, or a
+ *   browser page served from a secure context.
+ * @example
+ *   ```typescript
+ *   const prover = yield* WasmProver.create({ keyMaterialProvider: WasmProver.makeV9KeyMaterialProvider() });
+ *   const proven = yield* prover.proveTransaction(unprovenV9Transaction, ledger.CostModel.initialCostModel());
+ *   ```;
+ *
+ * @param config Where to read from; the default host when left out.
+ * @returns A provider for {@link create} whose prover proves ledger-v9 transactions.
+ * @throws TypeError if `config.source` is not a URL.
+ */
+export declare const makeV9KeyMaterialProvider: (config?: KeyMaterialConfig) => KeyMaterialProvider;
+/**
+ * The key material ledger-v8's circuits were generated with: circuit generation 9.
+ *
+ * @remarks
+ *   The ledger-v8 twin of {@link makeV9KeyMaterialProvider}, read and checked the same way. A prover created with it
+ *   proves ledger-v8 transactions, through `asV8ProvingProvider()`; ledger-v9's Dust spend circuit is a different
+ *   generation, and a node rejects a Dust spend proved with the other version's key material.
+ * @example
+ *   ```typescript
+ *   const prover = yield* WasmProver.create({ keyMaterialProvider: WasmProver.makeV8KeyMaterialProvider() });
+ *   const proven = yield* Effect.promise(() =>
+ *     unprovenV8Transaction.prove(prover.asV8ProvingProvider(), ledgerV8.CostModel.initialCostModel()),
+ *   );
+ *   ```;
+ *
+ * @param config Where to read from; the default host when left out.
+ * @returns A provider for {@link create} whose prover proves ledger-v8 transactions.
+ * @throws TypeError if `config.source` is not a URL.
+ */
+export declare const makeV8KeyMaterialProvider: (config?: KeyMaterialConfig) => KeyMaterialProvider;
+/**
+ * The same provider as {@link makeV9KeyMaterialProvider}.
+ *
+ * @remarks
+ *   Ledger-v9's, because ledger-v9 is what this prover's own surface — `proveTransaction`, `asProvingProvider` — is typed
+ *   with. A prover that proves ledger-v8 transactions wants {@link makeV8KeyMaterialProvider} instead.
+ * @example
+ *   ```typescript
+ *   const prover = yield* WasmProver.create({ keyMaterialProvider: WasmProver.makeDefaultKeyMaterialProvider() });
+ *   ```;
+ *
+ * @param config Where to read from; the default host when left out.
+ * @returns A provider for {@link create} whose prover proves ledger-v9 transactions.
+ * @throws TypeError if `config.source` is not a URL.
+ */
+export declare const makeDefaultKeyMaterialProvider: (config?: KeyMaterialConfig) => KeyMaterialProvider;

package/dist/effect/WasmProver.js

@@ -13,6 +13,7 @@
 import Worker from 'web-worker';
 import { Effect, Layer, Schema, pipe } from 'effect';
 import { ClientError } from '@midnight-ntwrk/wallet-sdk-utilities/networking';
+import { DefaultKeyMaterialSource, makeKeyMaterialProvider, V8KeyMaterial, V9KeyMaterial } from './KeyMaterial.js';
 import { ProverClient } from './ProverClient.js';
 /**
  * Creates a layer for a {@link ProverClient} that sends requests to a Wasm Prover.
@@ -142,60 +143,77 @@ class WasmProverImpl {
     asProvingProvider() {
         return this.wasmProverProvider();
     }
+    /**
+     * The same provider {@link asProvingProvider} returns.
+     *
+     * @remarks
+     *   The in-process prover drives a zkir runtime over bytes and never looks at a ledger version, so the provider is the
+     *   same under both names — but the key material it proves with is not interchangeable. Each ledger version's
+     *   circuits were generated as their own generation, and a node rejects a proof made with another's, so a prover
+     *   proves for the ledger version whose key material it was created with: {@link makeV9KeyMaterialProvider} for
+     *   ledger-v9, {@link makeV8KeyMaterialProvider} for ledger-v8.
+     */
+    asV9ProvingProvider() {
+        return this.wasmProverProvider();
+    }
+    asV8ProvingProvider() {
+        return this.wasmProverProvider();
+    }
 }
-export const makeDefaultKeyMaterialProvider = () => {
-    const cache = new Map();
-    const s3 = 'https://midnight-s3-fileshare-dev-eu-west-1.s3.eu-west-1.amazonaws.com';
-    const ver = 9;
-    const fetchWithRetry = async (url, retries = 5) => {
-        for (let i = 0; i < retries; i++) {
-            try {
-                return await fetch(url);
-            }
-            catch (e) {
-                // eslint-disable-next-line no-console
-                console.error('Failed to fetch at attempt', i + 1, url, e);
-                // cooldown a bit before retrying
-                await new Promise((resolve) => setTimeout(resolve, 1000 * Math.pow(2, i + 1)));
-            }
-        }
-        throw new Error(`Failed to fetch ${url} after ${retries} attempts`);
-    };
-    const keyMaterialProvider = {
-        lookupKey: async (keyLocation) => {
-            const pth = {
-                'midnight/zswap/spend': `zswap/${ver}/spend`,
-                'midnight/zswap/output': `zswap/${ver}/output`,
-                'midnight/zswap/sign': `zswap/${ver}/sign`,
-                'midnight/dust/spend': `dust/${ver}/spend`,
-            }[keyLocation];
-            if (pth === undefined) {
-                return undefined;
-            }
-            if (cache.has(pth)) {
-                return cache.get(pth);
-            }
-            const pk = await fetchWithRetry(`${s3}/${pth}.prover`);
-            const vk = await fetchWithRetry(`${s3}/${pth}.verifier`);
-            const ir = await fetchWithRetry(`${s3}/${pth}.bzkir`);
-            const result = {
-                proverKey: new Uint8Array(await pk.arrayBuffer()),
-                verifierKey: new Uint8Array(await vk.arrayBuffer()),
-                ir: new Uint8Array(await ir.arrayBuffer()),
-            };
-            cache.set(pth, result);
-            return result;
-        },
-        getParams: async (k) => {
-            const cacheKey = `params-${k}`;
-            if (cache.has(cacheKey)) {
-                return cache.get(cacheKey);
-            }
-            const data = await fetchWithRetry(`${s3}/bls_midnight_2p${k}`);
-            const result = new Uint8Array(await data.arrayBuffer());
-            cache.set(cacheKey, result);
-            return result;
-        },
-    };
-    return keyMaterialProvider;
-};
+export { DefaultKeyMaterialSource, KeyMaterialFetchError, KeyMaterialIntegrityError, KeyMaterialTransferError, UnknownPublicParametersError, } from './KeyMaterial.js';
+/**
+ * The key material ledger-v9's circuits were generated with: circuit generation 10.
+ *
+ * @remarks
+ *   Every file is read from the host the ledger's own data provider reads (or from `config.source`) and checked against
+ *   the SHA-256 the ledger release declares before it is handed back; a file that does not match is refused with
+ *   {@link KeyMaterialIntegrityError}, since a proof made with it would be rejected by a node. Each circuit and each
+ *   parameter size is read once per provider. Checking needs Web Crypto (`crypto.subtle`): Node 19 or later, or a
+ *   browser page served from a secure context.
+ * @example
+ *   ```typescript
+ *   const prover = yield* WasmProver.create({ keyMaterialProvider: WasmProver.makeV9KeyMaterialProvider() });
+ *   const proven = yield* prover.proveTransaction(unprovenV9Transaction, ledger.CostModel.initialCostModel());
+ *   ```;
+ *
+ * @param config Where to read from; the default host when left out.
+ * @returns A provider for {@link create} whose prover proves ledger-v9 transactions.
+ * @throws TypeError if `config.source` is not a URL.
+ */
+export const makeV9KeyMaterialProvider = (config) => makeKeyMaterialProvider(V9KeyMaterial, { source: config?.source ?? DefaultKeyMaterialSource });
+/**
+ * The key material ledger-v8's circuits were generated with: circuit generation 9.
+ *
+ * @remarks
+ *   The ledger-v8 twin of {@link makeV9KeyMaterialProvider}, read and checked the same way. A prover created with it
+ *   proves ledger-v8 transactions, through `asV8ProvingProvider()`; ledger-v9's Dust spend circuit is a different
+ *   generation, and a node rejects a Dust spend proved with the other version's key material.
+ * @example
+ *   ```typescript
+ *   const prover = yield* WasmProver.create({ keyMaterialProvider: WasmProver.makeV8KeyMaterialProvider() });
+ *   const proven = yield* Effect.promise(() =>
+ *     unprovenV8Transaction.prove(prover.asV8ProvingProvider(), ledgerV8.CostModel.initialCostModel()),
+ *   );
+ *   ```;
+ *
+ * @param config Where to read from; the default host when left out.
+ * @returns A provider for {@link create} whose prover proves ledger-v8 transactions.
+ * @throws TypeError if `config.source` is not a URL.
+ */
+export const makeV8KeyMaterialProvider = (config) => makeKeyMaterialProvider(V8KeyMaterial, { source: config?.source ?? DefaultKeyMaterialSource });
+/**
+ * The same provider as {@link makeV9KeyMaterialProvider}.
+ *
+ * @remarks
+ *   Ledger-v9's, because ledger-v9 is what this prover's own surface — `proveTransaction`, `asProvingProvider` — is typed
+ *   with. A prover that proves ledger-v8 transactions wants {@link makeV8KeyMaterialProvider} instead.
+ * @example
+ *   ```typescript
+ *   const prover = yield* WasmProver.create({ keyMaterialProvider: WasmProver.makeDefaultKeyMaterialProvider() });
+ *   ```;
+ *
+ * @param config Where to read from; the default host when left out.
+ * @returns A provider for {@link create} whose prover proves ledger-v9 transactions.
+ * @throws TypeError if `config.source` is not a URL.
+ */
+export const makeDefaultKeyMaterialProvider = (config) => makeV9KeyMaterialProvider(config);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midnight-ntwrk/wallet-sdk-prover-client",
-  "version": "2.0.0-beta.2",
+  "version": "2.0.0-beta.4",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -30,10 +30,11 @@
     }
   },
   "dependencies": {
-    "@effect/platform": "^0.96.0",
+    "@effect/platform": "^0.97.0",
+    "@midnight-ntwrk/ledger-v8": "^8.1.0",
     "@midnight-ntwrk/zkir-v2": "^2.1.0",
-    "@midnightntwrk/ledger-v9": "1.0.0-rc.3",
-    "@midnight-ntwrk/wallet-sdk-utilities": "1.2.0",
+    "@midnightntwrk/ledger-v9": "1.0.0-rc.5",
+    "@midnight-ntwrk/wallet-sdk-utilities": "1.2.2-beta.0",
     "effect": "^3.19.19",
     "web-worker": "^1.5.0"
   },