@midnight-ntwrk/wallet-sdk-capabilities 4.0.0-beta.2 → 4.0.0-beta.3

package/dist/proving/provingService.d.ts

@@ -1,7 +1,8 @@
 import * as ledger from '@midnightntwrk/ledger-v9';
 import type { KeyMaterialProvider } from '@midnight-ntwrk/zkir-v2';
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
 import { type InvalidProtocolSchemeError } from '@midnight-ntwrk/wallet-sdk-utilities/networking';
-import { Effect } from 'effect';
+import { Effect, Either } from 'effect';
 declare const ProvingError_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]; }>) => import("effect/Cause").YieldableError & {
     readonly _tag: "Wallet.Proving";
 } & Readonly<A>;
@@ -10,28 +11,187 @@ export declare class ProvingError extends ProvingError_base<{
     cause: Error;
 }> {
 }
-export interface ProvingServiceEffect<TTransaction> {
-    prove(transaction: ledger.UnprovenTransaction): Effect.Effect<TTransaction, ProvingError>;
+declare const ProvingEpochMismatchError_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]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "@midnight-ntwrk/wallet-sdk-capabilities/proving/provingService/ProvingEpochMismatchError";
+} & Readonly<A>;
+/**
+ * Raised when a proving backend is handed a transaction from the other side of a protocol boundary.
+ *
+ * @remarks
+ *   Every backend is written against exactly one ledger version, and the two ledger versions' transactions are different
+ *   classes that neither can read. The router has already chosen a backend by the version stamped on the transaction,
+ *   so reaching this error means the stamp and the bytes disagreed — which is worth saying out loud, and in terms of
+ *   the epoch the backend serves, rather than letting a foreign object reach the wasm-bindgen boundary and fail there
+ *   as something unreadable.
+ */
+export declare class ProvingEpochMismatchError extends ProvingEpochMismatchError_base<{
+    readonly message: string;
+    /** The range of protocol versions the backend that refused the transaction serves. */
+    readonly epoch: ProtocolVersion.ProtocolVersion.Range;
+}> {
+}
+/** Everything a proving backend can fail with. */
+export type ProvingFailure = ProvingError | ProvingEpochMismatchError;
+/**
+ * Turns an unproven transaction into a proven one.
+ *
+ * @typeParam TProven The proven transaction this backend produces.
+ * @typeParam TUnproven The unproven transaction it accepts. Defaults to ledger-v9's, because a proving backend is only
+ *   ever written against one ledger version — which is exactly why choosing between backends is
+ *   {@link VersionedProvingServiceEffect}'s job and not this interface's.
+ */
+export interface ProvingServiceEffect<TProven, TUnproven = ledger.UnprovenTransaction> {
+    prove(transaction: TUnproven): Effect.Effect<TProven, ProvingFailure>;
+}
+export interface ProvingService<TProven, TUnproven = ledger.UnprovenTransaction> {
+    prove(transaction: TUnproven): Promise<TProven>;
+}
+declare const UnsupportedProvingVersionError_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]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "@midnight-ntwrk/wallet-sdk-capabilities/proving/provingService/UnsupportedProvingVersionError";
+} & Readonly<A>;
+/** Raised when no proving backend is registered for the protocol version a transaction was built for. */
+export declare class UnsupportedProvingVersionError extends UnsupportedProvingVersionError_base<{
+    readonly message: string;
+    /** The version the transaction was built for, which no registered backend serves. */
+    readonly protocolVersion: ProtocolVersion.ProtocolVersion;
+}> {
 }
-export interface ProvingService<TTransaction> {
-    prove(transaction: ledger.UnprovenTransaction): Promise<TTransaction>;
+/**
+ * Proves a transaction with the backend registered for the protocol version it was built for.
+ *
+ * @remarks
+ *   The version is the transaction's own stamp, taken when it was built, and never the version the chain has reached by
+ *   the time proving happens. A fork can land between balancing and proving; the bytes the prover has to read were
+ *   fixed before it did.
+ */
+export interface VersionedProvingServiceEffect<TProven, TUnproven = ledger.UnprovenTransaction> {
+    prove(transaction: TUnproven, protocolVersion: ProtocolVersion.ProtocolVersion): Effect.Effect<TProven, ProvingFailure | UnsupportedProvingVersionError>;
 }
-export type UnboundTransaction = ledger.Transaction<ledger.SignatureEnabled, ledger.Proof, ledger.PreBinding>;
-export declare const fromProvingProviderEffect: (provider: Effect.Effect<ledger.ProvingProvider, InvalidProtocolSchemeError>) => ProvingServiceEffect<UnboundTransaction>;
-export declare const fromProvingProvider: (provider: ledger.ProvingProvider) => ProvingServiceEffect<UnboundTransaction>;
+export interface VersionedProvingService<TProven, TUnproven = ledger.UnprovenTransaction> {
+    prove(transaction: TUnproven, protocolVersion: ProtocolVersion.ProtocolVersion): Promise<TProven>;
+}
+/** The proving backends a wallet can use, keyed by the protocol version range each one serves. */
+export type ProvingServices<TProven, TUnproven = ledger.UnprovenTransaction> = ProtocolVersion.Registry<ProvingServiceEffect<TProven, TUnproven>>;
+/**
+ * Builds a proving service that routes on the version a transaction was built for.
+ *
+ * @param services The backends and the version ranges they serve.
+ * @returns A proving service that fails with {@link UnsupportedProvingVersionError} for a version nothing serves.
+ */
+export declare const makeVersionedProvingServiceEffect: <TProven, TUnproven>(services: ProvingServices<TProven, TUnproven>) => VersionedProvingServiceEffect<TProven, TUnproven>;
+/**
+ * Lets one backend answer for every protocol version.
+ *
+ * @remarks
+ *   Says out loud what an unversioned proving service was implicitly claiming: that it can prove anything, whatever
+ *   version produced it. True for a wallet on one side of a fork, and a lie the moment it crosses — so it has to be
+ *   written down rather than assumed.
+ * @param service The backend to use for every version.
+ * @returns The same backend, addressed by version.
+ */
+export declare const singleVersionProvingServiceEffect: <TProven, TUnproven>(service: ProvingServiceEffect<TProven, TUnproven>) => VersionedProvingServiceEffect<TProven, TUnproven>;
+export type V9UnboundTransaction = ledger.Transaction<ledger.SignatureEnabled, ledger.Proof, ledger.PreBinding>;
+/** Adapts a version-routed proving service to the promise-facing surface the facade exposes. */
+export declare const wrapVersionedEffectService: <TProven, TUnproven>(effectService: VersionedProvingServiceEffect<TProven, TUnproven>) => VersionedProvingService<TProven, TUnproven>;
+export declare const fromV9ProvingProviderEffect: (provider: Effect.Effect<ledger.ProvingProvider, InvalidProtocolSchemeError>) => ProvingServiceEffect<V9UnboundTransaction>;
+export declare const fromV9ProvingProvider: (provider: ledger.ProvingProvider) => ProvingServiceEffect<V9UnboundTransaction>;
 export type ServerProvingConfiguration = {
     provingServerUrl: URL;
 };
 export type WasmProvingConfiguration = {
     keyMaterialProvider?: KeyMaterialProvider;
 };
-export type DefaultProvingConfiguration = ServerProvingConfiguration;
-export declare const makeServerProvingServiceEffect: (configuration: ServerProvingConfiguration) => ProvingServiceEffect<UnboundTransaction>;
-export declare const makeWasmProvingServiceEffect: (configuration?: WasmProvingConfiguration) => ProvingServiceEffect<UnboundTransaction>;
+/**
+ * Where proving happens: at a proof server over HTTP, or in this process.
+ *
+ * @remarks
+ *   Deliberately says nothing about a ledger version. Which ledger drives a backend follows from the key it is registered
+ *   under in {@link ProvingBackends}, so the same description can be named for either side of a fork and mean the right
+ *   thing both times.
+ */
+export type ProvingBackend = Readonly<{
+    kind: 'server';
+    url: URL;
+}> | Readonly<{
+    kind: 'wasm';
+    keyMaterialProvider?: KeyMaterialProvider;
+}>;
+/**
+ * Which proving backend proves the transactions each ledger version authors.
+ *
+ * @remarks
+ *   Keyed the way {@link ProtocolVersion.ForkSchedule} is, so a configuration states each boundary once: `v8` proves below
+ *   `forks.v9` and `v9` from it, and where one ends and the next begins is read off the schedule rather than restated
+ *   here. The newest ledger version's backend is required, because it is what every new transaction is proved with; an
+ *   older one may be left out on a chain whose history below the boundary the wallet will never author for, and a
+ *   transaction stamped there then fails with {@link UnsupportedProvingVersionError}. The next hard fork adds a key
+ *   (`v10`) rather than changing this shape.
+ */
+export type ProvingBackends = Readonly<{
+    /** Proves the transactions ledger-v8 authored, below `forks.v9`. */
+    v8?: ProvingBackend;
+    /** Proves the transactions ledger-v9 authored, from `forks.v9`. */
+    v9: ProvingBackend;
+}>;
+/**
+ * Which proving backend serves which ledger version.
+ *
+ * @remarks
+ *   The two settings are alternatives, not a set: `provers` is the general form and `provingServerUrl` the shorthand for
+ *   "this one proof server, for every ledger version". Giving both is not an error — `provers` wins — but naming
+ *   neither is, because there is then nothing to prove with.
+ *
+ *   The single URL is registered once per ledger version and driven by each in turn, which is what makes it frame its
+ *   requests correctly on both sides of a fork. Whether a given proof server can in fact serve both is an operational
+ *   fact about that server, not something the SDK can know or enforce — today's images serve one side each, so a chain
+ *   that spans a fork wants `provers` with a server per side.
+ */
+export type DefaultProvingConfiguration = {
+    /** One proof server for every ledger version. */
+    provingServerUrl?: URL;
+    /** A proving backend per ledger version. */
+    provers?: ProvingBackends;
+};
+declare const ProvingConfigurationError_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]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "@midnight-ntwrk/wallet-sdk-capabilities/proving/provingService/ProvingConfigurationError";
+} & Readonly<A>;
+/** Raised when the proving configuration names no backend at all. */
+export declare class ProvingConfigurationError extends ProvingConfigurationError_base<{
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+}
+/**
+ * Reads a proving configuration as the backend it names for each ledger version.
+ *
+ * @remarks
+ *   Where the precedence between the two settings is decided, once, so that reading a configuration and building services
+ *   from it cannot disagree about which one was meant. Says nothing about protocol versions: which range each backend
+ *   serves is the fork schedule's to say, and `makeDefaultProvingServices` reads it there.
+ * @param configuration The proving configuration.
+ * @returns The backend per ledger version, or the reason the configuration names none.
+ */
+export declare const resolveProvingBackends: (configuration: DefaultProvingConfiguration) => Either.Either<ProvingBackends, ProvingConfigurationError>;
+/**
+ * Registers the in-process WASM prover, driven by ledger-v9, from a given protocol version upwards.
+ *
+ * @remarks
+ *   Every entry here is ledger-v9's backend, so `sinceVersion` should not be below a protocol boundary: what a version
+ *   below it needs is the ledger-v8 driver, which `makeDefaultProvingServices` registers for the epoch the fork
+ *   schedule it is given places below `forks.v9`. Registering nothing below is what turns that into an
+ *   {@link UnsupportedProvingVersionError} naming the version, rather than a ledger-v8 transaction handed to a ledger
+ *   that cannot read it.
+ * @param sinceVersion The first protocol version to register the bundled prover for.
+ * @param configuration Optional key material override.
+ * @returns The proving backends, keyed by version.
+ */
+export declare const makeWasmProvingServices: (sinceVersion: ProtocolVersion.ProtocolVersion, configuration?: WasmProvingConfiguration) => ProvingServices<V9UnboundTransaction>;
+export declare const makeV9ServerProvingServiceEffect: (configuration: ServerProvingConfiguration) => ProvingServiceEffect<V9UnboundTransaction>;
+export declare const makeV9WasmProvingServiceEffect: (configuration?: WasmProvingConfiguration) => ProvingServiceEffect<V9UnboundTransaction>;
 export declare const makeSimulatorProvingServiceEffect: () => ProvingServiceEffect<ledger.ProofErasedTransaction>;
-export declare const makeDefaultProvingServiceEffect: (configuration: DefaultProvingConfiguration) => ProvingServiceEffect<UnboundTransaction>;
-export declare const makeDefaultProvingService: (configuration: DefaultProvingConfiguration) => ProvingService<UnboundTransaction>;
-export declare const makeServerProvingService: (configuration: ServerProvingConfiguration) => ProvingService<UnboundTransaction>;
-export declare const makeWasmProvingService: (configuration?: WasmProvingConfiguration) => ProvingService<UnboundTransaction>;
+export declare const makeDefaultProvingServiceEffect: (configuration: ServerProvingConfiguration) => ProvingServiceEffect<V9UnboundTransaction>;
+export declare const makeDefaultProvingService: (configuration: ServerProvingConfiguration) => ProvingService<V9UnboundTransaction>;
+export declare const makeV9ServerProvingService: (configuration: ServerProvingConfiguration) => ProvingService<V9UnboundTransaction>;
+export declare const makeV9WasmProvingService: (configuration?: WasmProvingConfiguration) => ProvingService<V9UnboundTransaction>;
 export declare const makeSimulatorProvingService: () => ProvingService<ledger.ProofErasedTransaction>;
 export {};

package/dist/proving/provingService.js

@@ -11,15 +11,63 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 import * as ledger from '@midnightntwrk/ledger-v9';
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
 import { HttpProverClient, WasmProver } from '@midnight-ntwrk/wallet-sdk-prover-client/effect';
 import { ClientError, ServerError, } from '@midnight-ntwrk/wallet-sdk-utilities/networking';
-import { Data, Effect, pipe } from 'effect';
+import { Data, Effect, Either, Option, pipe } from 'effect';
 export class ProvingError extends Data.TaggedError('Wallet.Proving') {
 }
+/**
+ * Raised when a proving backend is handed a transaction from the other side of a protocol boundary.
+ *
+ * @remarks
+ *   Every backend is written against exactly one ledger version, and the two ledger versions' transactions are different
+ *   classes that neither can read. The router has already chosen a backend by the version stamped on the transaction,
+ *   so reaching this error means the stamp and the bytes disagreed — which is worth saying out loud, and in terms of
+ *   the epoch the backend serves, rather than letting a foreign object reach the wasm-bindgen boundary and fail there
+ *   as something unreadable.
+ */
+export class ProvingEpochMismatchError extends Data.TaggedError('@midnight-ntwrk/wallet-sdk-capabilities/proving/provingService/ProvingEpochMismatchError') {
+}
+/** Raised when no proving backend is registered for the protocol version a transaction was built for. */
+export class UnsupportedProvingVersionError extends Data.TaggedError('@midnight-ntwrk/wallet-sdk-capabilities/proving/provingService/UnsupportedProvingVersionError') {
+}
+/**
+ * Builds a proving service that routes on the version a transaction was built for.
+ *
+ * @param services The backends and the version ranges they serve.
+ * @returns A proving service that fails with {@link UnsupportedProvingVersionError} for a version nothing serves.
+ */
+export const makeVersionedProvingServiceEffect = (services) => ({
+    prove: (transaction, protocolVersion) => Option.match(ProtocolVersion.select(services, protocolVersion), {
+        onNone: () => Effect.fail(new UnsupportedProvingVersionError({
+            message: `No proving backend is registered for protocol version ${protocolVersion}.`,
+            protocolVersion,
+        })),
+        onSome: (service) => service.prove(transaction),
+    }),
+});
+/**
+ * Lets one backend answer for every protocol version.
+ *
+ * @remarks
+ *   Says out loud what an unversioned proving service was implicitly claiming: that it can prove anything, whatever
+ *   version produced it. True for a wallet on one side of a fork, and a lie the moment it crosses — so it has to be
+ *   written down rather than assumed.
+ * @param service The backend to use for every version.
+ * @returns The same backend, addressed by version.
+ */
+export const singleVersionProvingServiceEffect = (service) => ({
+    prove: (transaction) => service.prove(transaction),
+});
 const wrapEffectService = (effectService) => ({
     prove: (transaction) => Effect.runPromise(effectService.prove(transaction)),
 });
-export const fromProvingProviderEffect = (provider) => {
+/** Adapts a version-routed proving service to the promise-facing surface the facade exposes. */
+export const wrapVersionedEffectService = (effectService) => ({
+    prove: (transaction, protocolVersion) => Effect.runPromise(effectService.prove(transaction, protocolVersion)),
+});
+export const fromV9ProvingProviderEffect = (provider) => {
     return {
         prove(transaction) {
             return pipe(provider, Effect.flatMap((provider) => Effect.tryPromise({
@@ -34,18 +82,63 @@ export const fromProvingProviderEffect = (provider) => {
         },
     };
 };
-export const fromProvingProvider = (provider) => {
-    return fromProvingProviderEffect(Effect.succeed(provider));
+export const fromV9ProvingProvider = (provider) => {
+    return fromV9ProvingProviderEffect(Effect.succeed(provider));
 };
-export const makeServerProvingServiceEffect = (configuration) => {
+/** Raised when the proving configuration names no backend at all. */
+export class ProvingConfigurationError extends Data.TaggedError('@midnight-ntwrk/wallet-sdk-capabilities/proving/provingService/ProvingConfigurationError') {
+}
+const noBackendNamed = () => new ProvingConfigurationError({
+    message: "Missing required configuration: set 'provers' (or 'provingServerUrl'), or provide a custom provingService in init parameters.",
+});
+/**
+ * Reads a proving configuration as the backend it names for each ledger version.
+ *
+ * @remarks
+ *   Where the precedence between the two settings is decided, once, so that reading a configuration and building services
+ *   from it cannot disagree about which one was meant. Says nothing about protocol versions: which range each backend
+ *   serves is the fork schedule's to say, and `makeDefaultProvingServices` reads it there.
+ * @param configuration The proving configuration.
+ * @returns The backend per ledger version, or the reason the configuration names none.
+ */
+export const resolveProvingBackends = (configuration) => configuration.provers !== undefined
+    ? Either.right(configuration.provers)
+    : configuration.provingServerUrl !== undefined
+        ? Either.right({
+            v8: { kind: 'server', url: configuration.provingServerUrl },
+            v9: { kind: 'server', url: configuration.provingServerUrl },
+        })
+        : Either.left(noBackendNamed());
+/**
+ * Registers the in-process WASM prover, driven by ledger-v9, from a given protocol version upwards.
+ *
+ * @remarks
+ *   Every entry here is ledger-v9's backend, so `sinceVersion` should not be below a protocol boundary: what a version
+ *   below it needs is the ledger-v8 driver, which `makeDefaultProvingServices` registers for the epoch the fork
+ *   schedule it is given places below `forks.v9`. Registering nothing below is what turns that into an
+ *   {@link UnsupportedProvingVersionError} naming the version, rather than a ledger-v8 transaction handed to a ledger
+ *   that cannot read it.
+ * @param sinceVersion The first protocol version to register the bundled prover for.
+ * @param configuration Optional key material override.
+ * @returns The proving backends, keyed by version.
+ */
+export const makeWasmProvingServices = (sinceVersion, configuration) => ({
+    entries: [
+        {
+            range: ProtocolVersion.makeRange(sinceVersion, ProtocolVersion.MaxSupportedVersion),
+            value: makeV9WasmProvingServiceEffect(configuration),
+        },
+    ],
+});
+export const makeV9ServerProvingServiceEffect = (configuration) => {
     return pipe(HttpProverClient.create({
         url: configuration.provingServerUrl,
-    }), Effect.map((client) => client.asProvingProvider()), fromProvingProviderEffect);
+    }), Effect.map((client) => client.asProvingProvider()), fromV9ProvingProviderEffect);
 };
-export const makeWasmProvingServiceEffect = (configuration) => {
+export const makeV9WasmProvingServiceEffect = (configuration) => {
     return pipe(WasmProver.create({
         keyMaterialProvider: configuration?.keyMaterialProvider ?? WasmProver.makeDefaultKeyMaterialProvider(),
-    }), Effect.map((prover) => prover.asProvingProvider()), fromProvingProviderEffect);
+    }), Effect.map((prover) => prover.asProvingProvider()), fromV9ProvingProviderEffect);
 };
 export const makeSimulatorProvingServiceEffect = () => {
     return {
@@ -54,8 +147,8 @@ export const makeSimulatorProvingServiceEffect = () => {
         },
     };
 };
-export const makeDefaultProvingServiceEffect = (configuration) => makeServerProvingServiceEffect(configuration);
+export const makeDefaultProvingServiceEffect = (configuration) => makeV9ServerProvingServiceEffect(configuration);
 export const makeDefaultProvingService = (configuration) => wrapEffectService(makeDefaultProvingServiceEffect(configuration));
-export const makeServerProvingService = (configuration) => wrapEffectService(makeServerProvingServiceEffect(configuration));
-export const makeWasmProvingService = (configuration) => wrapEffectService(makeWasmProvingServiceEffect(configuration));
+export const makeV9ServerProvingService = (configuration) => wrapEffectService(makeV9ServerProvingServiceEffect(configuration));
+export const makeV9WasmProvingService = (configuration) => wrapEffectService(makeV9WasmProvingServiceEffect(configuration));
 export const makeSimulatorProvingService = () => wrapEffectService(makeSimulatorProvingServiceEffect());

package/dist/proving/v8ProvingService.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Proving on ledger-v8.
+ *
+ * @remarks
+ *   The ledger-v8 twin of the backends in `provingService.ts`: structurally the same three steps — obtain a proving
+ *   provider, drive the transaction's own `prove` with that ledger version's cost model, report failures as a
+ *   {@link ProvingError} — against a different ledger version's classes. It is the classes that make this a separate
+ *   module: a ledger-v8 transaction handed ledger-v9's cost model fails at the wasm-bindgen boundary, and a
+ *   proof-server request framed by ledger-v9 is not the request ledger-v8 would have sent.
+ */
+import * as ledger from '@midnight-ntwrk/ledger-v8';
+import { type InvalidProtocolSchemeError } from '@midnight-ntwrk/wallet-sdk-utilities/networking';
+import { Effect } from 'effect';
+import { type ProvingServiceEffect, type ServerProvingConfiguration, type WasmProvingConfiguration } from './provingService.js';
+/** A ledger-v8 transaction that has not been proved yet. */
+export type V8UnprovenTransaction = ledger.UnprovenTransaction;
+/** A ledger-v8 transaction that has been proved but not yet bound. */
+export type V8UnboundTransaction = ledger.Transaction<ledger.SignatureEnabled, ledger.Proof, ledger.PreBinding>;
+/** A proving backend written against ledger-v8. */
+export type V8ProvingServiceEffect = ProvingServiceEffect<V8UnboundTransaction, V8UnprovenTransaction>;
+/**
+ * Drives a ledger-v8 transaction's proving with a low-level proving provider.
+ *
+ * @param provider The proving provider, or the reason one could not be built.
+ * @returns A backend that proves ledger-v8 transactions.
+ */
+export declare const fromV8ProvingProviderEffect: (provider: Effect.Effect<ledger.ProvingProvider, InvalidProtocolSchemeError>) => V8ProvingServiceEffect;
+/**
+ * Drives a ledger-v8 transaction's proving with a low-level proving provider.
+ *
+ * @param provider The proving provider.
+ * @returns A backend that proves ledger-v8 transactions.
+ */
+export declare const fromV8ProvingProvider: (provider: ledger.ProvingProvider) => V8ProvingServiceEffect;
+/**
+ * Proves ledger-v8 transactions at a proof server.
+ *
+ * @param configuration The proof server to send ledger-v8 proving requests to.
+ * @returns A backend that proves ledger-v8 transactions over HTTP.
+ */
+export declare const makeV8ServerProvingServiceEffect: (configuration: ServerProvingConfiguration) => V8ProvingServiceEffect;
+/**
+ * Proves ledger-v8 transactions in this process.
+ *
+ * @remarks
+ *   The zkir runtime the bundled prover drives is shared by both ledger lines, so there is nothing version-specific about
+ *   the proving loop — and the key material ledger-v8 accepts turns out to be the same line the current one uses, which
+ *   is why no key-material override is applied here. See the ledger-v8 spike in `prover-client`'s
+ *   `v8WasmProver.integration.test.ts` for the evidence.
+ * @param configuration Optional key material override.
+ * @returns A backend that proves ledger-v8 transactions in-process.
+ */
+export declare const makeV8WasmProvingServiceEffect: (configuration?: WasmProvingConfiguration) => V8ProvingServiceEffect;

package/dist/proving/v8ProvingService.js

@@ -0,0 +1,71 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// You may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+/**
+ * Proving on ledger-v8.
+ *
+ * @remarks
+ *   The ledger-v8 twin of the backends in `provingService.ts`: structurally the same three steps — obtain a proving
+ *   provider, drive the transaction's own `prove` with that ledger version's cost model, report failures as a
+ *   {@link ProvingError} — against a different ledger version's classes. It is the classes that make this a separate
+ *   module: a ledger-v8 transaction handed ledger-v9's cost model fails at the wasm-bindgen boundary, and a
+ *   proof-server request framed by ledger-v9 is not the request ledger-v8 would have sent.
+ */
+import * as ledger from '@midnight-ntwrk/ledger-v8';
+import { HttpProverClient, WasmProver } from '@midnight-ntwrk/wallet-sdk-prover-client/effect';
+import { ClientError, ServerError, } from '@midnight-ntwrk/wallet-sdk-utilities/networking';
+import { Effect, pipe } from 'effect';
+import { ProvingError, } from './provingService.js';
+/**
+ * Drives a ledger-v8 transaction's proving with a low-level proving provider.
+ *
+ * @param provider The proving provider, or the reason one could not be built.
+ * @returns A backend that proves ledger-v8 transactions.
+ */
+export const fromV8ProvingProviderEffect = (provider) => ({
+    prove(transaction) {
+        return pipe(provider, Effect.flatMap((provider) => Effect.tryPromise({
+            try: () => transaction.prove(provider, ledger.CostModel.initialCostModel()),
+            catch: (error) => error instanceof ClientError || error instanceof ServerError
+                ? error
+                : new ClientError({ message: 'Failed to prove transaction', cause: error }),
+        })), Effect.catchAll((error) => Effect.fail(new ProvingError({ message: error.message, cause: error }))));
+    },
+});
+/**
+ * Drives a ledger-v8 transaction's proving with a low-level proving provider.
+ *
+ * @param provider The proving provider.
+ * @returns A backend that proves ledger-v8 transactions.
+ */
+export const fromV8ProvingProvider = (provider) => fromV8ProvingProviderEffect(Effect.succeed(provider));
+/**
+ * Proves ledger-v8 transactions at a proof server.
+ *
+ * @param configuration The proof server to send ledger-v8 proving requests to.
+ * @returns A backend that proves ledger-v8 transactions over HTTP.
+ */
+export const makeV8ServerProvingServiceEffect = (configuration) => pipe(HttpProverClient.create({ url: configuration.provingServerUrl }), Effect.map((client) => client.asV8ProvingProvider()), fromV8ProvingProviderEffect);
+/**
+ * Proves ledger-v8 transactions in this process.
+ *
+ * @remarks
+ *   The zkir runtime the bundled prover drives is shared by both ledger lines, so there is nothing version-specific about
+ *   the proving loop — and the key material ledger-v8 accepts turns out to be the same line the current one uses, which
+ *   is why no key-material override is applied here. See the ledger-v8 spike in `prover-client`'s
+ *   `v8WasmProver.integration.test.ts` for the evidence.
+ * @param configuration Optional key material override.
+ * @returns A backend that proves ledger-v8 transactions in-process.
+ */
+export const makeV8WasmProvingServiceEffect = (configuration) => pipe(WasmProver.create({
+    keyMaterialProvider: configuration?.keyMaterialProvider ?? WasmProver.makeDefaultKeyMaterialProvider(),
+}), Effect.map((prover) => prover.asProvingProvider()), fromV8ProvingProviderEffect);

package/dist/proving/versionedProving.d.ts

@@ -0,0 +1,42 @@
+import * as ledgerV9 from '@midnightntwrk/ledger-v9';
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { Either } from 'effect';
+import { type V8UnboundTransaction, type V8UnprovenTransaction } from './v8ProvingService.js';
+import { type DefaultProvingConfiguration, type ProvingConfigurationError, type ProvingServiceEffect, type ProvingServices, type V9UnboundTransaction, type VersionedProvingService, type VersionedProvingServiceEffect } from './provingService.js';
+/**
+ * Every unproven transaction either ledger version can be asked to prove.
+ *
+ * @remarks
+ *   A genuine union: the two ledger versions' transaction types are nominally distinct, so a caller holding one of them
+ *   is holding something the other version's backend provably cannot read.
+ */
+/** Ledger-v9's unproven transaction, named for symmetry with {@link V8UnprovenTransaction}. */
+export type V9UnprovenTransaction = ledgerV9.UnprovenTransaction;
+export type AnyVersionUnprovenTransaction = V9UnprovenTransaction | V8UnprovenTransaction;
+/** Every proved-but-unbound transaction either ledger version can hand back. */
+export type AnyVersionUnboundTransaction = V9UnboundTransaction | V8UnboundTransaction;
+/** A backend registered in a two-version registry, whichever ledger version it was written against. */
+export type VersionProvingServiceEffect = ProvingServiceEffect<AnyVersionUnboundTransaction, AnyVersionUnprovenTransaction>;
+/**
+ * Registers a proving backend either side of the protocol boundary.
+ *
+ * @remarks
+ *   The configuration names a backend per ledger version and the fork schedule says where each ledger version begins; the
+ *   range a backend serves is the meeting of the two, computed here and nowhere else, so the wallets and their provers
+ *   cannot place the boundary differently.
+ * @param configuration The proving configuration.
+ * @param forks Where each ledger version begins on the chain.
+ * @returns The backends and the version ranges they serve, or the reason the configuration names none.
+ */
+export declare const makeDefaultProvingServices: (configuration: DefaultProvingConfiguration, forks: ProtocolVersion.ForkSchedule) => Either.Either<ProvingServices<AnyVersionUnboundTransaction, AnyVersionUnprovenTransaction>, ProvingConfigurationError>;
+/**
+ * Builds the version-routed proving service an SDK spanning a protocol boundary proves with.
+ *
+ * @param configuration The proving configuration.
+ * @param forks Where each ledger version begins on the chain.
+ * @returns A proving service that routes on the version a transaction was built for, or the reason the configuration
+ *   names no backend.
+ */
+export declare const makeDefaultVersionedProvingServiceEffect: (configuration: DefaultProvingConfiguration, forks: ProtocolVersion.ForkSchedule) => Either.Either<VersionedProvingServiceEffect<AnyVersionUnboundTransaction, AnyVersionUnprovenTransaction>, ProvingConfigurationError>;
+/** The promise-facing surface of {@link makeDefaultVersionedProvingServiceEffect}, for the facade to expose. */
+export declare const makeDefaultVersionedProvingService: (configuration: DefaultProvingConfiguration, forks: ProtocolVersion.ForkSchedule) => Either.Either<VersionedProvingService<AnyVersionUnboundTransaction, AnyVersionUnprovenTransaction>, ProvingConfigurationError>;

package/dist/proving/versionedProving.js

@@ -0,0 +1,103 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// You may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+/**
+ * Proving for an SDK that spans a protocol boundary: one backend per ledger version, chosen by the version a
+ * transaction was built for.
+ *
+ * @remarks
+ *   The routing already existed and the backends already existed; what this module supplies is the only thing neither
+ *   could: the registration that says which range of protocol versions each backend answers for, taken from the same
+ *   fork schedule the wallets are built with. Written the same way validation's `versionedValidation.ts` is, because it
+ *   is the same problem.
+ */
+import * as ledgerV8 from '@midnight-ntwrk/ledger-v8';
+import * as ledgerV9 from '@midnightntwrk/ledger-v9';
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { Effect, Either, Option } from 'effect';
+import { makeV8ServerProvingServiceEffect, makeV8WasmProvingServiceEffect, } from './v8ProvingService.js';
+import { makeV9ServerProvingServiceEffect, makeVersionedProvingServiceEffect, makeV9WasmProvingServiceEffect, ProvingEpochMismatchError, resolveProvingBackends, wrapVersionedEffectService, } from './provingService.js';
+/**
+ * Narrows a backend written against one ledger version to the union the registry is keyed by.
+ *
+ * @remarks
+ *   The router has already chosen this backend by the version stamped on the transaction, so the check is a restatement
+ *   of that choice rather than a second one — but it is where a transaction that does not belong is refused rather than
+ *   handed to a ledger that cannot read it. What comes back from a wasm-bindgen boundary handed a foreign object is not
+ *   an error anyone can act on; this is.
+ * @param service The backend, written against one ledger version.
+ * @param isOwn Whether a transaction is that ledger version's.
+ * @param epoch The range of protocol versions this backend answers for.
+ * @returns The same backend, in terms of the union.
+ */
+const onlyFrom = (service, isOwn, epoch) => ({
+    prove: (transaction) => isOwn(transaction)
+        ? service.prove(transaction)
+        : Effect.fail(new ProvingEpochMismatchError({
+            message: `The proving backend registered for protocol versions [${epoch[0]}, ${epoch[1]}) was handed a transaction built by the other ledger version.`,
+            epoch,
+        })),
+});
+const isV8Transaction = (transaction) => transaction instanceof ledgerV8.Transaction;
+const isV9Transaction = (transaction) => transaction instanceof ledgerV9.Transaction;
+/** The in-process backend's configuration, with a key material override only when one was named. */
+const wasmConfigurationOf = (backend) => backend.keyMaterialProvider === undefined ? {} : { keyMaterialProvider: backend.keyMaterialProvider };
+/** Builds the backend a description names, driven by ledger-v8, for the epoch below `forks.v9`. */
+const makeV8Backend = (backend, epoch) => onlyFrom(backend.kind === 'server'
+    ? makeV8ServerProvingServiceEffect({ provingServerUrl: backend.url })
+    : makeV8WasmProvingServiceEffect(wasmConfigurationOf(backend)), isV8Transaction, epoch);
+/** Builds the backend a description names, driven by ledger-v9, for the epoch from `forks.v9`. */
+const makeV9Backend = (backend, epoch) => onlyFrom(backend.kind === 'server'
+    ? makeV9ServerProvingServiceEffect({ provingServerUrl: backend.url })
+    : makeV9WasmProvingServiceEffect(wasmConfigurationOf(backend)), isV9Transaction, epoch);
+/**
+ * The range of protocol versions each ledger version reads on a chain, from where the chain says the hand-over is.
+ *
+ * @remarks
+ *   A chain whose boundary is at or below the minimum supported version has no history ledger-v8 authored, so there is no
+ *   ledger-v8 epoch on it and a ledger-v8 backend has nothing to serve.
+ */
+const epochsOf = (forks) => ({
+    v8: forks.v9 > ProtocolVersion.MinSupportedVersion
+        ? Option.some(ProtocolVersion.epochOf(ProtocolVersion.MinSupportedVersion, forks.v9))
+        : Option.none(),
+    v9: ProtocolVersion.epochOf(forks.v9, forks.v9),
+});
+/**
+ * Registers a proving backend either side of the protocol boundary.
+ *
+ * @remarks
+ *   The configuration names a backend per ledger version and the fork schedule says where each ledger version begins; the
+ *   range a backend serves is the meeting of the two, computed here and nowhere else, so the wallets and their provers
+ *   cannot place the boundary differently.
+ * @param configuration The proving configuration.
+ * @param forks Where each ledger version begins on the chain.
+ * @returns The backends and the version ranges they serve, or the reason the configuration names none.
+ */
+export const makeDefaultProvingServices = (configuration, forks) => resolveProvingBackends(configuration).pipe(Either.map((backends) => {
+    const epochs = epochsOf(forks);
+    const v8Entry = Option.all([Option.fromNullable(backends.v8), epochs.v8]).pipe(Option.map(([backend, range]) => ({ range, value: makeV8Backend(backend, range) })));
+    return {
+        entries: [...Option.toArray(v8Entry), { range: epochs.v9, value: makeV9Backend(backends.v9, epochs.v9) }],
+    };
+}));
+/**
+ * Builds the version-routed proving service an SDK spanning a protocol boundary proves with.
+ *
+ * @param configuration The proving configuration.
+ * @param forks Where each ledger version begins on the chain.
+ * @returns A proving service that routes on the version a transaction was built for, or the reason the configuration
+ *   names no backend.
+ */
+export const makeDefaultVersionedProvingServiceEffect = (configuration, forks) => makeDefaultProvingServices(configuration, forks).pipe(Either.map(makeVersionedProvingServiceEffect));
+/** The promise-facing surface of {@link makeDefaultVersionedProvingServiceEffect}, for the facade to expose. */
+export const makeDefaultVersionedProvingService = (configuration, forks) => makeDefaultVersionedProvingServiceEffect(configuration, forks).pipe(Either.map(wrapVersionedEffectService));

package/dist/signatures/index.d.ts

@@ -0,0 +1,2 @@
+export * as Signing from './signing.js';
+export * from './v8Signatures.js';