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

package/dist/validation/blockData.js

@@ -10,12 +10,62 @@
 // 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.
+import { LedgerParameters as V8LedgerParameters } from '@midnight-ntwrk/ledger-v8';
 import { LedgerParameters } from '@midnightntwrk/ledger-v9';
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
 import { BlockHash } from '@midnight-ntwrk/wallet-sdk-indexer-client';
 import { HttpQueryClient } from '@midnight-ntwrk/wallet-sdk-indexer-client/effect';
-import { Buffer } from 'buffer';
-import { Effect } from 'effect';
+import { Effect, Either, pipe } from 'effect';
+import { LedgerParametersCodec } from '../codecs/index.js';
 import { getLastBlock } from '../simulation/index.js';
+/**
+ * The ledger parameters codecs validation reads blocks with, split at the version the chain forks at.
+ *
+ * @remarks
+ *   A block's parameters are bytes of whichever ledger version produced the block, and the version the indexer reports
+ *   the block under is what says which. Below the fork version they are read with ledger-v8's deserializer and from it
+ *   with the current one, so that the object handed to a validator is always one its own `LedgerState` accepts.
+ *
+ *   Nothing in the resulting type distinguishes the two: the ledger versions' `LedgerParameters` are structurally
+ *   identical, so {@link AnyLedgerParameters} is a statement of intent rather than something the compiler enforces. The
+ *   distinction is nominal at run time — the classes differ, and each ledger's WASM boundary rejects the other's —
+ *   which is why the routing has to be right rather than merely well-typed.
+ * @param forkVersion The protocol version at which the chain hands over to the ledger-v9.
+ * @returns The registry blocks are read with.
+ */
+export const defaultLedgerParametersCodecs = (forkVersion) => Either.getOrThrow(LedgerParametersCodec.makeCodecs(forkVersion > ProtocolVersion.MinSupportedVersion
+    ? [
+        {
+            sinceVersion: ProtocolVersion.MinSupportedVersion,
+            codec: LedgerParametersCodec.fromDeserializer((bytes) => V8LedgerParameters.deserialize(bytes)),
+        },
+        {
+            sinceVersion: forkVersion,
+            codec: LedgerParametersCodec.fromDeserializer((bytes) => LedgerParameters.deserialize(bytes)),
+        },
+    ]
+    : // A chain whose boundary is at or below the minimum supported version has no ledger-v8 epoch to register for.
+        [
+            {
+                sinceVersion: ProtocolVersion.MinSupportedVersion,
+                codec: LedgerParametersCodec.fromDeserializer((bytes) => LedgerParameters.deserialize(bytes)),
+            },
+        ]));
+/**
+ * Reads an indexer block into {@link BlockData}, decoding its ledger parameters with whichever registered codec claims
+ * the protocol version the block was reported under.
+ *
+ * @param codecs The ledger parameters codecs the caller is willing to read with.
+ * @param block The block as the indexer served it.
+ * @returns The block data, or the typed reason its parameters could not be read.
+ */
+export const blockDataFrom = (codecs, block) => pipe(LedgerParametersCodec.decode(codecs, ProtocolVersion.ProtocolVersion(BigInt(block.protocolVersion)), block.ledgerParameters), Either.map((ledgerParameters) => ({
+    hash: block.hash,
+    height: block.height,
+    protocolVersion: block.protocolVersion,
+    ledgerParameters,
+    timestamp: new Date(block.timestamp),
+})));
 /**
  * Builds a `BlockDataFetcher` that queries the indexer over HTTP for the latest block.
  *
@@ -23,18 +73,14 @@ import { getLastBlock } from '../simulation/index.js';
  */
 export const makeDefaultBlockDataFetcher = (config) => {
     const url = config.indexerClientConnection.indexerHttpUrl;
+    const codecs = config.ledgerParametersCodecs ?? defaultLedgerParametersCodecs(config.forks.v9);
     return () => Effect.runPromise(Effect.gen(function* () {
         const query = yield* BlockHash;
         const result = yield* query({ offset: null });
         const block = result.block;
         if (!block)
             throw new Error('Unable to fetch latest block from indexer.');
-        return {
-            hash: block.hash,
-            height: block.height,
-            ledgerParameters: LedgerParameters.deserialize(Buffer.from(block.ledgerParameters, 'hex')),
-            timestamp: new Date(block.timestamp),
-        };
+        return yield* blockDataFrom(codecs, block);
     }).pipe(Effect.provide(HttpQueryClient.layer({ url })), Effect.scoped));
 };
 /**
@@ -50,6 +96,7 @@ export const makeSimulatorBlockDataFetcher = (simulator) => {
         return {
             hash: lastBlock.hash,
             height: Number(lastBlock.number),
+            protocolVersion: Number(lastBlock.protocolVersion),
             ledgerParameters: state.ledger.parameters,
             timestamp: state.currentTime,
         };

package/dist/validation/index.d.ts

@@ -1,2 +1,4 @@
 export * from './blockData.js';
+export * from './v8ValidationService.js';
 export * from './validationService.js';
+export * from './versionedValidation.js';

package/dist/validation/index.js

@@ -11,4 +11,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 export * from './blockData.js';
+export * from './v8ValidationService.js';
 export * from './validationService.js';
+export * from './versionedValidation.js';

package/dist/validation/v8ValidationService.d.ts

@@ -0,0 +1,29 @@
+import * as ledger from '@midnight-ntwrk/ledger-v8';
+import type { V8UnboundTransaction } from '../proving/v8ProvingService.js';
+import { type AnyLedgerParameters, type ValidationServiceDependencies, type ValidationServiceEffect, type WellFormedCheck } from './validationService.js';
+/**
+ * Every ledger-v8 transaction shape well-formedness can be asked about — the ledger-v8 counterpart of
+ * `AnyV9ValidatableTransaction`, and a genuinely different type from it: these are the other ledger version's classes,
+ * and neither ledger can read the other's.
+ */
+export type AnyV8ValidatableTransaction = ledger.FinalizedTransaction | V8UnboundTransaction | ledger.UnprovenTransaction;
+/**
+ * The ledger-v8's well-formedness check.
+ *
+ * @remarks
+ *   Structurally the same three steps as ledger-v9's, against a different ledger version's classes. It is the classes,
+ *   not the steps, that make this a separate check: a ledger-v8 transaction cannot be handed to ledger-v9's
+ *   `wellFormed`, nor ledger-v9 parameters to this one.
+ */
+export declare const v8WellFormedCheck: WellFormedCheck<AnyV8ValidatableTransaction, AnyLedgerParameters>;
+/**
+ * Builds the validator for ledger-v8 transactions.
+ *
+ * @remarks
+ *   Registered below the fork version by `makeDefaultValidationServices`, against a block-data fetcher whose codec
+ *   registry is split at the same version — so a block reported from before the boundary reaches this validator as
+ *   ledger-v8 parameters, which is the only kind its ledger version can build a state from.
+ * @param deps The network, clock, and the block-data fetcher, which decodes each block at the version it reports.
+ * @returns A validator to register in a `ValidationServices` registry for the version range before the v9 fork.
+ */
+export declare const makeV8ValidationServiceEffect: (deps: ValidationServiceDependencies<AnyLedgerParameters>) => ValidationServiceEffect<AnyV8ValidatableTransaction, AnyLedgerParameters>;

package/dist/validation/v8ValidationService.js

@@ -0,0 +1,48 @@
+// 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.
+import * as ledger from '@midnight-ntwrk/ledger-v8';
+import { makeValidationServiceEffect, } from './validationService.js';
+const buildStrictness = (flags) => {
+    const strictness = new ledger.WellFormedStrictness();
+    strictness.enforceBalancing = flags.enforceBalancing;
+    strictness.verifySignatures = flags.verifySignatures;
+    strictness.enforceLimits = flags.enforceLimits;
+    return strictness;
+};
+const buildBlankLedgerState = (networkId, parameters) => {
+    const state = ledger.LedgerState.blank(networkId);
+    state.parameters = parameters;
+    return state;
+};
+/**
+ * The ledger-v8's well-formedness check.
+ *
+ * @remarks
+ *   Structurally the same three steps as ledger-v9's, against a different ledger version's classes. It is the classes,
+ *   not the steps, that make this a separate check: a ledger-v8 transaction cannot be handed to ledger-v9's
+ *   `wellFormed`, nor ledger-v9 parameters to this one.
+ */
+export const v8WellFormedCheck = (tx, { networkId, ledgerParameters, flags, now }) => {
+    tx.wellFormed(buildBlankLedgerState(networkId, ledgerParameters), buildStrictness(flags), now);
+};
+/**
+ * Builds the validator for ledger-v8 transactions.
+ *
+ * @remarks
+ *   Registered below the fork version by `makeDefaultValidationServices`, against a block-data fetcher whose codec
+ *   registry is split at the same version — so a block reported from before the boundary reaches this validator as
+ *   ledger-v8 parameters, which is the only kind its ledger version can build a state from.
+ * @param deps The network, clock, and the block-data fetcher, which decodes each block at the version it reports.
+ * @returns A validator to register in a `ValidationServices` registry for the version range before the v9 fork.
+ */
+export const makeV8ValidationServiceEffect = (deps) => makeValidationServiceEffect(v8WellFormedCheck, deps);

package/dist/validation/validationService.d.ts

@@ -1,27 +1,49 @@
-import * as ledger from '@midnightntwrk/ledger-v9';
+import type * as ledgerV8 from '@midnight-ntwrk/ledger-v8';
+import * as ledgerV9 from '@midnightntwrk/ledger-v9';
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
 import type { Clock } from '@midnight-ntwrk/wallet-sdk-utilities';
 import { Cause, Effect } from 'effect';
-import type { UnboundTransaction } from '../proving/provingService.js';
+import type { V9UnboundTransaction } from '../proving/provingService.js';
+/**
+ * Ledger parameters as either ledger version reads them: what a block-data fetch spanning a protocol boundary yields.
+ *
+ * @remarks
+ *   The two ledger versions' `LedgerParameters` are structurally identical, so this union carries no information the
+ *   compiler can act on — it names, at the one place a block's parameters cross into validation, that which ledger
+ *   version produced them is a run-time fact settled by the block's reported protocol version. Each ledger's
+ *   `LedgerState` still insists on its own class, so handing over the wrong one fails at the WASM boundary and is
+ *   reported as a {@link WellFormedError}.
+ */
+export type AnyLedgerParameters = ledgerV8.LedgerParameters | ledgerV9.LedgerParameters;
 /**
  * Snapshot of chain state required for transaction validation. Structurally identical to the dust-wallet's `BlockData`
  * — a separate declaration here keeps the validation service decoupled from dust-wallet. The two can be passed
  * interchangeably via structural typing.
+ *
+ * @typeParam TParameters The `LedgerParameters` type of the ledger version the parameters were decoded at. Defaults to
+ *   ledger-v9's, so `BlockData` unqualified still names exactly what it always did.
  */
-export interface BlockData {
+export interface BlockData<TParameters = ledgerV9.LedgerParameters> {
     hash: string;
     height: number;
-    ledgerParameters: ledger.LedgerParameters;
+    /** The protocol version the indexer reported this block under, and so the ledger version its parameters are in. */
+    protocolVersion: number;
+    ledgerParameters: TParameters;
     timestamp: Date;
 }
 /**
- * Configurable subset of {@link ledger.WellFormedStrictness}. Proof-verification flags (`verifyNativeProofs`,
+ * Configurable subset of {@link ledgerV9.WellFormedStrictness}. Proof-verification flags (`verifyNativeProofs`,
  * `verifyContractProofs`) are intentionally omitted — proof verification requires the complete ledger state and will be
  * addressed in a future task.
  */
-export type WellFormedStrictnessFlags = Pick<ledger.WellFormedStrictness, 'enforceBalancing' | 'verifySignatures' | 'enforceLimits'>;
-export type ValidateTxOptions = {
+export type WellFormedStrictnessFlags = Pick<ledgerV9.WellFormedStrictness, 'enforceBalancing' | 'verifySignatures' | 'enforceLimits'>;
+/**
+ * @typeParam TParameters The `LedgerParameters` type of the ledger version `blockData` was decoded at — necessarily the
+ *   version the validator being called speaks, since well-formedness is checked against a state built from them.
+ */
+export type ValidateTxOptions<TParameters = ledgerV9.LedgerParameters> = {
     flags: WellFormedStrictnessFlags;
-    blockData?: BlockData | undefined;
+    blockData?: BlockData<TParameters> | undefined;
 };
 declare const WellFormedError_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-capabilities/validation/validationService/WellFormedError";
@@ -39,21 +61,114 @@ export declare class ValidationFetchError extends ValidationFetchError_base<{
     cause: unknown;
 }> {
 }
-export type AnyValidatableTransaction = ledger.FinalizedTransaction | UnboundTransaction | ledger.UnprovenTransaction;
-export interface ValidationServiceEffect {
-    validateTx(tx: AnyValidatableTransaction, options: ValidateTxOptions): Effect.Effect<void, WellFormedError | ValidationFetchError>;
+export type AnyV9ValidatableTransaction = ledgerV9.FinalizedTransaction | V9UnboundTransaction | ledgerV9.UnprovenTransaction;
+/**
+ * Checks a transaction for well-formedness.
+ *
+ * @typeParam TTransaction The transactions this validator accepts. Defaults to ledger-v9's, because a validator is only
+ *   ever written against one ledger version — which is exactly why choosing between validators is
+ *   {@link VersionedValidationServiceEffect}'s job and not this interface's.
+ * @typeParam TParameters The `LedgerParameters` type of that same ledger version.
+ */
+export interface ValidationServiceEffect<TTransaction = AnyV9ValidatableTransaction, TParameters = ledgerV9.LedgerParameters> {
+    validateTx(tx: TTransaction, options: ValidateTxOptions<TParameters>): Effect.Effect<void, WellFormedError | ValidationFetchError>;
+}
+export interface ValidationService<TTransaction = AnyV9ValidatableTransaction, TParameters = ledgerV9.LedgerParameters> {
+    validateTx(tx: TTransaction, options: ValidateTxOptions<TParameters>): Promise<void>;
+}
+declare const UnsupportedValidationVersionError_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-capabilities/validation/validationService/UnsupportedValidationVersionError";
+} & Readonly<A>;
+/** Raised when no validator is registered for the protocol version a transaction was authored for. */
+export declare class UnsupportedValidationVersionError extends UnsupportedValidationVersionError_base<{
+    readonly message: string;
+    /** The version the transaction was authored for, which no registered validator serves. */
+    readonly protocolVersion: ProtocolVersion.ProtocolVersion;
+}> {
+}
+/**
+ * Checks a transaction with the validator registered for the protocol version it was authored for.
+ *
+ * @remarks
+ *   The version is the transaction's own stamp, taken when it was authored, and never the version the chain has reached
+ *   by the time it is validated. Well-formedness asks whether the ledger that produced these bytes would accept them; a
+ *   fork landing between authoring and validation does not rewrite the bytes, so it cannot change the answer or who
+ *   gives it.
+ */
+export interface VersionedValidationServiceEffect<TTransaction = AnyV9ValidatableTransaction, TParameters = ledgerV9.LedgerParameters> {
+    validateTx(tx: TTransaction, protocolVersion: ProtocolVersion.ProtocolVersion, options: ValidateTxOptions<TParameters>): Effect.Effect<void, WellFormedError | ValidationFetchError | UnsupportedValidationVersionError>;
 }
-export interface ValidationService {
-    validateTx(tx: AnyValidatableTransaction, options: ValidateTxOptions): Promise<void>;
+export interface VersionedValidationService<TTransaction = AnyV9ValidatableTransaction, TParameters = ledgerV9.LedgerParameters> {
+    validateTx(tx: TTransaction, protocolVersion: ProtocolVersion.ProtocolVersion, options: ValidateTxOptions<TParameters>): Promise<void>;
 }
+/**
+ * The validators a caller is willing to check with, keyed by the protocol version range each one serves.
+ *
+ * @remarks
+ *   Registration is per caller, not global, and a caller registers only the ledger versions its own types are written
+ *   against — the same rule the ledger-parameters codecs follow, and for the same reason: a `LedgerState` belongs to
+ *   one ledger version, so a validator that speaks two would have nothing to build. A version outside every registered
+ *   range therefore means "this transaction belongs to a different variant", and the router says so with
+ *   {@link UnsupportedValidationVersionError} instead of handing the bytes to a checker that could only reject them.
+ */
+export type ValidationServices<TTransaction = AnyV9ValidatableTransaction, TParameters = ledgerV9.LedgerParameters> = ProtocolVersion.Registry<ValidationServiceEffect<TTransaction, TParameters>>;
+/**
+ * Builds a validation service that routes on the version a transaction was authored for.
+ *
+ * @param services The validators and the version ranges they serve.
+ * @returns A validation service that fails with {@link UnsupportedValidationVersionError} for a version nothing serves.
+ */
+export declare const makeVersionedValidationServiceEffect: <TTransaction, TParameters>(services: ValidationServices<TTransaction, TParameters>) => VersionedValidationServiceEffect<TTransaction, TParameters>;
+/**
+ * Lets one validator answer for every protocol version.
+ *
+ * @remarks
+ *   Says out loud what an unversioned validation service was implicitly claiming: that it can judge anything, whatever
+ *   version authored 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 validator to use for every version.
+ * @returns The same validator, addressed by version.
+ */
+export declare const singleVersionValidationServiceEffect: <TTransaction, TParameters>(service: ValidationServiceEffect<TTransaction, TParameters>) => VersionedValidationServiceEffect<TTransaction, TParameters>;
 export type DefaultValidationConfiguration = {
     networkId: string;
 };
-export type ValidationServiceDependencies = {
-    fetchBlockData: () => Promise<BlockData>;
+/**
+ * @typeParam TParameters The `LedgerParameters` type of the ledger version this validator speaks, and so the version
+ *   its `fetchBlockData` must decode at.
+ */
+export type ValidationServiceDependencies<TParameters = ledgerV9.LedgerParameters> = {
+    fetchBlockData: () => Promise<BlockData<TParameters>>;
     networkId: string;
     clock: Clock.Clock;
 };
-export declare const makeDefaultValidationServiceEffect: (deps: ValidationServiceDependencies) => ValidationServiceEffect;
-export declare const makeDefaultValidationService: (deps: ValidationServiceDependencies) => ValidationService;
+/**
+ * The one thing a ledger version has to supply for its transactions to be checked: run its own well-formedness check
+ * against a blank state carrying the block's parameters, throwing whatever that ledger throws.
+ *
+ * @remarks
+ *   Deliberately allowed to throw, exactly like a {@link LedgerParametersCodec}: it wraps a WASM call whose failure mode
+ *   is an exception. {@link makeValidationServiceEffect} is the only way to reach one, and it turns that into a typed
+ *   {@link WellFormedError}.
+ */
+export type WellFormedCheck<TTransaction, TParameters> = (transaction: TTransaction, context: Readonly<{
+    networkId: string;
+    ledgerParameters: TParameters;
+    flags: WellFormedStrictnessFlags;
+    now: Date;
+}>) => void;
+/**
+ * Builds a validation service for one ledger version from that version's well-formedness check.
+ *
+ * @param check The ledger version's well-formedness check.
+ * @param deps The network, clock, and the block-data fetcher that decodes at the same ledger version.
+ * @returns A validator for that ledger version, ready to register in {@link ValidationServices}.
+ */
+export declare const makeValidationServiceEffect: <TTransaction, TParameters>(check: WellFormedCheck<TTransaction, TParameters>, deps: ValidationServiceDependencies<TParameters>) => ValidationServiceEffect<TTransaction, TParameters>;
+/** The ledger-v9's well-formedness check. */
+export declare const v9WellFormedCheck: WellFormedCheck<AnyV9ValidatableTransaction, AnyLedgerParameters>;
+export declare const makeV9ValidationServiceEffect: (deps: ValidationServiceDependencies<AnyLedgerParameters>) => ValidationServiceEffect<AnyV9ValidatableTransaction, AnyLedgerParameters>;
+export declare const makeV9ValidationService: (deps: ValidationServiceDependencies<AnyLedgerParameters>) => ValidationService<AnyV9ValidatableTransaction, AnyLedgerParameters>;
+/** Adapts a version-routed validation service to the promise-facing surface the facade exposes. */
+export declare const wrapVersionedValidationService: <TTransaction, TParameters>(effectService: VersionedValidationServiceEffect<TTransaction, TParameters>) => VersionedValidationService<TTransaction, TParameters>;
 export {};

package/dist/validation/validationService.js

@@ -1,16 +1,5 @@
-// 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.
-import * as ledger from '@midnightntwrk/ledger-v9';
+import * as ledgerV9 from '@midnightntwrk/ledger-v9';
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
 import { Cause, Data, Effect, Exit, Option, pipe } from 'effect';
 /** Thrown when a transaction fails the structural well-formedness check. */
 export class WellFormedError extends Data.TaggedError('@midnight-ntwrk/wallet-sdk-capabilities/validation/validationService/WellFormedError') {
@@ -18,19 +7,45 @@ export class WellFormedError extends Data.TaggedError('@midnight-ntwrk/wallet-sd
 /** Thrown when validation cannot complete because the block-data fetch failed. */
 export class ValidationFetchError extends Data.TaggedError('@midnight-ntwrk/wallet-sdk-capabilities/validation/validationService/ValidationFetchError') {
 }
-const buildStrictness = (flags) => {
-    const strictness = new ledger.WellFormedStrictness();
-    strictness.enforceBalancing = flags.enforceBalancing;
-    strictness.verifySignatures = flags.verifySignatures;
-    strictness.enforceLimits = flags.enforceLimits;
-    return strictness;
-};
-const buildBlankLedgerState = (networkId, parameters) => {
-    const state = ledger.LedgerState.blank(networkId);
-    state.parameters = parameters;
-    return state;
-};
-export const makeDefaultValidationServiceEffect = (deps) => ({
+/** Raised when no validator is registered for the protocol version a transaction was authored for. */
+export class UnsupportedValidationVersionError extends Data.TaggedError('@midnight-ntwrk/wallet-sdk-capabilities/validation/validationService/UnsupportedValidationVersionError') {
+}
+/**
+ * Builds a validation service that routes on the version a transaction was authored for.
+ *
+ * @param services The validators and the version ranges they serve.
+ * @returns A validation service that fails with {@link UnsupportedValidationVersionError} for a version nothing serves.
+ */
+export const makeVersionedValidationServiceEffect = (services) => ({
+    validateTx: (tx, protocolVersion, options) => Option.match(ProtocolVersion.select(services, protocolVersion), {
+        onNone: () => Effect.fail(new UnsupportedValidationVersionError({
+            message: `No validator is registered for protocol version ${protocolVersion}.`,
+            protocolVersion,
+        })),
+        onSome: (service) => service.validateTx(tx, options),
+    }),
+});
+/**
+ * Lets one validator answer for every protocol version.
+ *
+ * @remarks
+ *   Says out loud what an unversioned validation service was implicitly claiming: that it can judge anything, whatever
+ *   version authored 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 validator to use for every version.
+ * @returns The same validator, addressed by version.
+ */
+export const singleVersionValidationServiceEffect = (service) => ({
+    validateTx: (tx, _protocolVersion, options) => service.validateTx(tx, options),
+});
+/**
+ * Builds a validation service for one ledger version from that version's well-formedness check.
+ *
+ * @param check The ledger version's well-formedness check.
+ * @param deps The network, clock, and the block-data fetcher that decodes at the same ledger version.
+ * @returns A validator for that ledger version, ready to register in {@link ValidationServices}.
+ */
+export const makeValidationServiceEffect = (check, deps) => ({
     validateTx(tx, options) {
         const fetchOrUse = options.blockData
             ? Effect.succeed(options.blockData)
@@ -39,26 +54,57 @@ export const makeDefaultValidationServiceEffect = (deps) => ({
                 catch: (cause) => new ValidationFetchError({ cause }),
             });
         return pipe(fetchOrUse, Effect.flatMap((blockData) => Effect.try({
-            try: () => {
-                const ledgerState = buildBlankLedgerState(deps.networkId, blockData.ledgerParameters);
-                const strictness = buildStrictness(options.flags);
-                tx.wellFormed(ledgerState, strictness, deps.clock.now());
-            },
+            try: () => check(tx, {
+                networkId: deps.networkId,
+                ledgerParameters: blockData.ledgerParameters,
+                flags: options.flags,
+                now: deps.clock.now(),
+            }),
             catch: (cause) => new WellFormedError({ cause }),
         })));
     },
 });
-export const makeDefaultValidationService = (deps) => {
-    const effectService = makeDefaultValidationServiceEffect(deps);
+const buildStrictness = (flags) => {
+    const strictness = new ledgerV9.WellFormedStrictness();
+    strictness.enforceBalancing = flags.enforceBalancing;
+    strictness.verifySignatures = flags.verifySignatures;
+    strictness.enforceLimits = flags.enforceLimits;
+    return strictness;
+};
+const buildBlankLedgerState = (networkId, parameters) => {
+    const state = ledgerV9.LedgerState.blank(networkId);
+    state.parameters = parameters;
+    return state;
+};
+/** The ledger-v9's well-formedness check. */
+export const v9WellFormedCheck = (tx, { networkId, ledgerParameters, flags, now }) => {
+    tx.wellFormed(buildBlankLedgerState(networkId, ledgerParameters), buildStrictness(flags), now);
+};
+/**
+ * Rejects a promise with the typed failure itself rather than the fiber wrapper around it, so a caller can `catch` the
+ * error class the signature names.
+ *
+ * @remarks
+ *   `E extends Error` is what makes that rejection legitimate rather than a thrown bare value, and every failure on this
+ *   surface is a `Data.TaggedError`, which is one.
+ */
+const runPromiseThrowingFailure = async (effect) => {
+    const exit = await Effect.runPromiseExit(effect);
+    if (Exit.isSuccess(exit))
+        return exit.value;
+    const failure = Cause.failureOption(exit.cause);
+    if (Option.isSome(failure))
+        throw failure.value;
+    throw new Error(Cause.pretty(exit.cause));
+};
+export const makeV9ValidationServiceEffect = (deps) => makeValidationServiceEffect(v9WellFormedCheck, deps);
+export const makeV9ValidationService = (deps) => {
+    const effectService = makeV9ValidationServiceEffect(deps);
     return {
-        validateTx: async (tx, options) => {
-            const exit = await Effect.runPromiseExit(effectService.validateTx(tx, options));
-            if (Exit.isSuccess(exit))
-                return;
-            const failure = Cause.failureOption(exit.cause);
-            if (Option.isSome(failure))
-                throw failure.value;
-            throw new Error(Cause.pretty(exit.cause));
-        },
+        validateTx: (tx, options) => runPromiseThrowingFailure(effectService.validateTx(tx, options)),
     };
 };
+/** Adapts a version-routed validation service to the promise-facing surface the facade exposes. */
+export const wrapVersionedValidationService = (effectService) => ({
+    validateTx: (tx, protocolVersion, options) => runPromiseThrowingFailure(effectService.validateTx(tx, protocolVersion, options)),
+});

package/dist/validation/versionedValidation.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Well-formedness for an SDK that spans a protocol boundary: one validator per ledger version, chosen by the version a
+ * transaction was authored for.
+ *
+ * @remarks
+ *   The two halves already exist and are each written against one ledger version. What this module supplies is the only
+ *   thing neither of them can: the registration that says which range of protocol versions each one answers for, taken
+ *   from the same fork version the wallets are built with.
+ */
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { type AnyV8ValidatableTransaction } from './v8ValidationService.js';
+import { type AnyLedgerParameters, type AnyV9ValidatableTransaction, type ValidationServiceDependencies, type ValidationServiceEffect, type ValidationServices, type VersionedValidationService, type VersionedValidationServiceEffect } from './validationService.js';
+/**
+ * Every transaction shape either ledger version can be asked about.
+ *
+ * @remarks
+ *   A genuine union, unlike {@link AnyLedgerParameters}: the two ledger versions' transaction types are nominally
+ *   distinct, so a caller holding one of them is holding something the other version's validator provably cannot read.
+ */
+export type AnyVersionValidatableTransaction = AnyV9ValidatableTransaction | AnyV8ValidatableTransaction;
+/** A validator registered in a two-version registry, whichever ledger version it was written against. */
+export type VersionValidationServiceEffect = ValidationServiceEffect<AnyVersionValidatableTransaction, AnyLedgerParameters>;
+/**
+ * Registers a validator either side of the protocol boundary.
+ *
+ * @remarks
+ *   Both validators are handed the same block-data fetcher, and that is correct rather than a shortcut: the fetcher
+ *   decodes a block's parameters with the codec registered for the version the block itself was reported under, so it
+ *   already yields the ledger version whose validator will be chosen for a transaction authored in the same epoch. A
+ *   transaction authored on the other side of the boundary from the chain's current block is the case neither can
+ *   serve, and it fails at the ledger rather than silently checking against the wrong parameters.
+ * @param deps The network, clock, and the block-data fetcher shared by both validators.
+ * @param forkVersion The protocol version at which the chain hands over to the ledger-v9.
+ * @returns The validators and the version ranges they serve.
+ */
+export declare const makeDefaultValidationServices: (deps: ValidationServiceDependencies<AnyLedgerParameters>, forkVersion: ProtocolVersion.ProtocolVersion) => ValidationServices<AnyVersionValidatableTransaction, AnyLedgerParameters>;
+/**
+ * Builds the version-routed validator an SDK spanning a protocol boundary checks with.
+ *
+ * @param deps The network, clock, and the block-data fetcher shared by both validators.
+ * @param forkVersion The protocol version at which the chain hands over to the ledger-v9.
+ * @returns A validator that routes on the version a transaction was authored for.
+ */
+export declare const makeDefaultVersionedValidationServiceEffect: (deps: ValidationServiceDependencies<AnyLedgerParameters>, forkVersion: ProtocolVersion.ProtocolVersion) => VersionedValidationServiceEffect<AnyVersionValidatableTransaction, AnyLedgerParameters>;
+/** The promise-facing surface of {@link makeDefaultVersionedValidationServiceEffect}, for the facade to expose. */
+export declare const makeDefaultVersionedValidationService: (deps: ValidationServiceDependencies<AnyLedgerParameters>, forkVersion: ProtocolVersion.ProtocolVersion) => VersionedValidationService<AnyVersionValidatableTransaction, AnyLedgerParameters>;

package/dist/validation/versionedValidation.js

@@ -0,0 +1,55 @@
+// 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.
+/**
+ * Well-formedness for an SDK that spans a protocol boundary: one validator per ledger version, chosen by the version a
+ * transaction was authored for.
+ *
+ * @remarks
+ *   The two halves already exist and are each written against one ledger version. What this module supplies is the only
+ *   thing neither of them can: the registration that says which range of protocol versions each one answers for, taken
+ *   from the same fork version the wallets are built with.
+ */
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { Either } from 'effect';
+import { makeV8ValidationServiceEffect } from './v8ValidationService.js';
+import { makeV9ValidationServiceEffect, makeVersionedValidationServiceEffect, wrapVersionedValidationService, } from './validationService.js';
+/**
+ * Registers a validator either side of the protocol boundary.
+ *
+ * @remarks
+ *   Both validators are handed the same block-data fetcher, and that is correct rather than a shortcut: the fetcher
+ *   decodes a block's parameters with the codec registered for the version the block itself was reported under, so it
+ *   already yields the ledger version whose validator will be chosen for a transaction authored in the same epoch. A
+ *   transaction authored on the other side of the boundary from the chain's current block is the case neither can
+ *   serve, and it fails at the ledger rather than silently checking against the wrong parameters.
+ * @param deps The network, clock, and the block-data fetcher shared by both validators.
+ * @param forkVersion The protocol version at which the chain hands over to the ledger-v9.
+ * @returns The validators and the version ranges they serve.
+ */
+export const makeDefaultValidationServices = (deps, forkVersion) => Either.getOrThrow(ProtocolVersion.makeRegistryFromActivations(forkVersion > ProtocolVersion.MinSupportedVersion
+    ? [
+        { sinceVersion: ProtocolVersion.MinSupportedVersion, value: makeV8ValidationServiceEffect(deps) },
+        { sinceVersion: forkVersion, value: makeV9ValidationServiceEffect(deps) },
+    ]
+    : // A chain whose boundary is at or below the minimum supported version has no ledger-v8 epoch to register for.
+        [{ sinceVersion: ProtocolVersion.MinSupportedVersion, value: makeV9ValidationServiceEffect(deps) }]));
+/**
+ * Builds the version-routed validator an SDK spanning a protocol boundary checks with.
+ *
+ * @param deps The network, clock, and the block-data fetcher shared by both validators.
+ * @param forkVersion The protocol version at which the chain hands over to the ledger-v9.
+ * @returns A validator that routes on the version a transaction was authored for.
+ */
+export const makeDefaultVersionedValidationServiceEffect = (deps, forkVersion) => makeVersionedValidationServiceEffect(makeDefaultValidationServices(deps, forkVersion));
+/** The promise-facing surface of {@link makeDefaultVersionedValidationServiceEffect}, for the facade to expose. */
+export const makeDefaultVersionedValidationService = (deps, forkVersion) => wrapVersionedValidationService(makeDefaultVersionedValidationServiceEffect(deps, forkVersion));