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

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';

package/dist/signatures/index.js

@@ -0,0 +1,14 @@
+// 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.
+export * as Signing from './signing.js';
+export * from './v8Signatures.js';

package/dist/signatures/signing.d.ts

@@ -0,0 +1,37 @@
+/**
+ * How the SDK writes a signature, whichever ledger version is underneath.
+ *
+ * @remarks
+ *   The one scalar that genuinely changed shape at the protocol boundary. Ledger-v8 has a single signature scheme and
+ *   writes a signature as bare hexadecimal; ledger-v9 has more than one and names the scheme alongside the bytes.
+ *   Everything else an application reads — token types, addresses, nullifiers, transaction identifiers — is
+ *   byte-identical across the two.
+ *
+ *   The SDK speaks the ledger-v9 shape everywhere and lowers it for the V1 variant, rather than the reverse. Lifting is
+ *   total — ledger-v8 has exactly one scheme, so naming it is never a guess — while lowering is partial, and a scheme
+ *   ledger-v8 has never heard of is refused rather than handed over as bytes it would misread. Speaking the ledger-v8
+ *   shape would have made the common case lossy instead.
+ *
+ *   Kept beside that lifting and lowering rather than among the abstractions a variant implements, because this is the
+ *   vocabulary those two functions are stated in and nothing else in the SDK is defined against it. It names no ledger
+ *   version itself, so an application can annotate a signer without importing one, and nothing on the way to it loads
+ *   either ledger's WebAssembly. These are structurally ledger-v9's own types: a signer already written against them
+ *   compiles unchanged.
+ */
+/** The signature schemes the chain knows. Only `schnorr` exists before the protocol boundary. */
+export type SignatureKind = 'schnorr' | 'ecdsa';
+/** A signature: the scheme that produced it, and its bytes as hexadecimal. */
+export type Signature = Readonly<{
+    tag: SignatureKind;
+    value: string;
+}>;
+/** The public half of a signing key, named with the scheme it belongs to. */
+export type SignatureVerifyingKey = Readonly<{
+    tag: SignatureKind;
+    value: string;
+}>;
+/** A signing key, named with the scheme it belongs to. */
+export type SigningKey = Readonly<{
+    tag: SignatureKind;
+    value: string;
+}>;

package/dist/signatures/signing.js

@@ -0,0 +1,13 @@
+// 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.
+export {};

package/dist/signatures/v8Signatures.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Signatures and verifying keys across a protocol boundary.
+ *
+ * @remarks
+ *   The one scalar that genuinely changed shape at the fork. Ledger-v8 has a single signature scheme and writes a
+ *   signature as bare hex; ledger-v9 names the scheme alongside the bytes, because it has more than one. So the SDK
+ *   speaks the ledger-v9 shape everywhere and lowers it for the V1 variant, which is a total operation in one direction
+ *   and a partial one in the other: a signature of a scheme ledger-v8 has never heard of cannot be lowered at all, and
+ *   says so rather than being handed over as bytes it would misread.
+ */
+import type * as ledgerV8 from '@midnight-ntwrk/ledger-v8';
+import { Either } from 'effect';
+import type * as Signing from './signing.js';
+declare const UnsupportedSignatureKindError_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/signatures/v8Signatures/UnsupportedSignatureKindError";
+} & Readonly<A>;
+/** Raised when a signature or verifying key names a scheme ledger-v8 does not have. */
+export declare class UnsupportedSignatureKindError extends UnsupportedSignatureKindError_base<{
+    readonly message: string;
+    /** The scheme that was named. */
+    readonly kind: Signing.SignatureKind;
+}> {
+}
+/**
+ * Lowers a signature to ledger-v8's shape.
+ *
+ * @param signature The signature, as ledger-v9 writes it.
+ * @returns The bare hex ledger-v8 reads, or the reason it cannot be expressed there.
+ */
+export declare const lowerSignature: (signature: Signing.Signature) => Either.Either<ledgerV8.Signature, UnsupportedSignatureKindError>;
+/**
+ * Lowers a signature verifying key to ledger-v8's shape.
+ *
+ * @param key The verifying key, as ledger-v9 writes it.
+ * @returns The bare hex ledger-v8 reads, or the reason it cannot be expressed there.
+ */
+export declare const lowerSignatureVerifyingKey: (key: Signing.SignatureVerifyingKey) => Either.Either<ledgerV8.SignatureVerifyingKey, UnsupportedSignatureKindError>;
+/**
+ * Lifts a ledger-v8 signature into ledger-v9's shape.
+ *
+ * @remarks
+ *   Total, unlike lowering: ledger-v8 has exactly one scheme, so naming it is never a guess.
+ * @param signature The signature, as ledger-v8 writes it.
+ * @returns The same signature, with the scheme it necessarily used named.
+ */
+export declare const liftSignature: (signature: ledgerV8.Signature) => Signing.Signature;
+/**
+ * Lifts a ledger-v8 verifying key into ledger-v9's shape.
+ *
+ * @param key The verifying key, as ledger-v8 writes it.
+ * @returns The same key, with the scheme it necessarily used named.
+ */
+export declare const liftSignatureVerifyingKey: (key: ledgerV8.SignatureVerifyingKey) => Signing.SignatureVerifyingKey;
+export {};

package/dist/signatures/v8Signatures.js

@@ -0,0 +1,62 @@
+// 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 { Data, Either } from 'effect';
+/** The signature scheme ledger-v8 has, and the only one a lowered value can name. */
+const V8_SIGNATURE_KIND = 'schnorr';
+/** Raised when a signature or verifying key names a scheme ledger-v8 does not have. */
+export class UnsupportedSignatureKindError extends Data.TaggedError('@midnight-ntwrk/wallet-sdk-capabilities/signatures/v8Signatures/UnsupportedSignatureKindError') {
+}
+const lower = (value, what) => value.tag === V8_SIGNATURE_KIND
+    ? Either.right(value.value)
+    : Either.left(new UnsupportedSignatureKindError({
+        message: `This ${what} names the ${value.tag} signature scheme, which the ledger version before the protocol ` +
+            `boundary does not have: it has ${V8_SIGNATURE_KIND} and nothing else. Sign with ` +
+            `${V8_SIGNATURE_KIND} while the chain is still on ledger-v8.`,
+        kind: value.tag,
+    }));
+/**
+ * Lowers a signature to ledger-v8's shape.
+ *
+ * @param signature The signature, as ledger-v9 writes it.
+ * @returns The bare hex ledger-v8 reads, or the reason it cannot be expressed there.
+ */
+export const lowerSignature = (signature) => lower(signature, 'signature');
+/**
+ * Lowers a signature verifying key to ledger-v8's shape.
+ *
+ * @param key The verifying key, as ledger-v9 writes it.
+ * @returns The bare hex ledger-v8 reads, or the reason it cannot be expressed there.
+ */
+export const lowerSignatureVerifyingKey = (key) => lower(key, 'verifying key');
+/**
+ * Lifts a ledger-v8 signature into ledger-v9's shape.
+ *
+ * @remarks
+ *   Total, unlike lowering: ledger-v8 has exactly one scheme, so naming it is never a guess.
+ * @param signature The signature, as ledger-v8 writes it.
+ * @returns The same signature, with the scheme it necessarily used named.
+ */
+export const liftSignature = (signature) => ({
+    tag: V8_SIGNATURE_KIND,
+    value: signature,
+});
+/**
+ * Lifts a ledger-v8 verifying key into ledger-v9's shape.
+ *
+ * @param key The verifying key, as ledger-v8 writes it.
+ * @returns The same key, with the scheme it necessarily used named.
+ */
+export const liftSignatureVerifyingKey = (key) => ({
+    tag: V8_SIGNATURE_KIND,
+    value: key,
+});

package/dist/simulation/ForkSimulator.d.ts

@@ -0,0 +1,114 @@
+/**
+ * A simulated chain that crosses a hard fork.
+ *
+ * Ledger-v8 the chain runs on ledger-v8, ledger-v9 on ledger-v9, with real ledger bytes on both sides — enough for a
+ * wallet under test to observe the version change, migrate, and go on transacting.
+ */
+import { Effect, Option, Scope, type Array as Arr } from 'effect';
+import { NetworkId, ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { type LedgerOps } from '@midnight-ntwrk/wallet-sdk-utilities';
+import { LedgerTranslationError, type LedgerStateTranslator } from './LedgerTranslation.js';
+import { Simulator } from './v9/Simulator.js';
+import { type BlockProducer } from './v9/SimulatorState.js';
+import * as V8 from './v8/index.js';
+/** {@link ForkSimulator} initialization configuration. */
+export type ForkSimulatorConfig = Readonly<{
+    /**
+     * Height at which the chain forks.
+     *
+     * The ledger-v8 chain's block at this height is a ledger-v8 block stamped with {@link forkVersion} — the signal a
+     * wallet's V1 variant migrates on, which it observes but does not apply. The ledger-v9 chain then begins at the same
+     * height, re-delivering it with ledger-v9 content, mirroring a wallet re-fetching the boundary with its new codec.
+     */
+    forkBlock: bigint;
+    /**
+     * Protocol version the fork activates.
+     *
+     * Required, and never defaulted: the protocol version of the real fork is not final, so every caller states which
+     * version it means.
+     */
+    forkVersion: ProtocolVersion.ProtocolVersion;
+    /**
+     * How the ledger-v8 chain's ledger state becomes the ledger-v9 chain's starting point.
+     *
+     * Receives the final ledger-v8 state, serialized, and returns the ledger-v9 one. See {@link LedgerStateTranslator} for
+     * why the seam is stated in bytes rather than state objects.
+     */
+    translator: LedgerStateTranslator;
+    /** Protocol version the ledger-v8 chain runs on. Defaults to {@link ProtocolVersion.MinSupportedVersion}. */
+    v8Version?: ProtocolVersion.ProtocolVersion;
+    /** Network identifier, shared by both chains. Defaults to Undeployed. */
+    networkId?: NetworkId.NetworkId;
+    /** Pre-funded accounts on the ledger-v8 chain. */
+    v8GenesisMints?: Arr.NonEmptyArray<V8.GenesisMint>;
+    /** Block producer for the ledger-v8 chain. */
+    v8BlockProducer?: V8.BlockProducer;
+    /** Block producer for the ledger-v9 chain. */
+    v9BlockProducer?: BlockProducer;
+}>;
+/**
+ * A simulated chain that crosses a hard fork, built from the two simulator twins.
+ *
+ * The ledger-v8 chain is available immediately and is driven like any other simulator. Once it reaches
+ * {@link ForkSimulatorConfig.forkBlock} the handover runs and the ledger-v9 chain appears; both remain alive for the
+ * simulator's scope, so assertions can read either side of the boundary.
+ *
+ * Nothing stops the ledger-v8 chain producing blocks past the boundary, which a real chain could not do — drive it only
+ * up to the fork.
+ *
+ * @example
+ *   ```typescript
+ *   const fork = yield* ForkSimulator.init({
+ *     forkBlock: 3n,
+ *     forkVersion: ProtocolVersion.ProtocolVersion(7n),
+ *     v8GenesisMints: [{ type: 'shielded', tokenType, amount: 1_000n, recipient: v8Keys }],
+ *     translator: translatorFromAsync(translateLedgerState),
+ *   });
+ *
+ *   yield* fork.v8.submitTransaction(v8Transfer);
+ *   const v9 = yield* fork.advanceToFork();
+ *   yield* v9.submitTransaction(v9Transfer);
+ *   ```;
+ */
+export declare class ForkSimulator {
+    #private;
+    /**
+     * Initialize a forking chain. The ledger-v8 chain starts immediately with the fork already scheduled; the ledger-v9
+     * chain is constructed when the ledger-v8 chain reaches the fork block.
+     *
+     * @param config - Configuration options
+     * @returns Effect that produces a ForkSimulator
+     */
+    static init(config: ForkSimulatorConfig): Effect.Effect<ForkSimulator, never, Scope.Scope>;
+    /** The ledger-v8 chain. */
+    readonly v8: V8.Simulator;
+    /** Height at which the chain forks. */
+    readonly forkBlock: bigint;
+    /** Protocol version the fork activates. */
+    readonly forkVersion: ProtocolVersion.ProtocolVersion;
+    private constructor();
+    /**
+     * The ledger-v9 chain, if the fork has happened.
+     *
+     * @returns `Option.some` once the handover has completed, `Option.none` before
+     */
+    v9(): Effect.Effect<Option.Option<Simulator>>;
+    /**
+     * Wait until the fork has happened, however the ledger-v8 chain is driven to it.
+     *
+     * Fails with the handover's own failure if it could not produce a ledger-v9 chain, so a broken handover surfaces here
+     * rather than leaving waiters blocked forever.
+     *
+     * @returns The ledger-v9 chain
+     */
+    awaitV9(): Effect.Effect<Simulator, LedgerTranslationError>;
+    /**
+     * Drive the ledger-v8 chain to the fork block with empty blocks and wait for the handover.
+     *
+     * Blocks the chain has already produced count towards the boundary, so this composes with transaction-driven
+     * production: submit what the test needs, then advance the rest of the way.
+     *
+     * @returns The ledger-v9 chain
+     */
+    advanceToFork(): Effect.Effect<Simulator, LedgerOps.LedgerError | LedgerTranslationError>;
+}

package/dist/simulation/ForkSimulator.js

@@ -0,0 +1,209 @@
+// 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.
+/**
+ * A simulated chain that crosses a hard fork.
+ *
+ * Ledger-v8 the chain runs on ledger-v8, ledger-v9 on ledger-v9, with real ledger bytes on both sides — enough for a
+ * wallet under test to observe the version change, migrate, and go on transacting.
+ */
+import { Deferred, Effect, Option, pipe, Scope, Stream, SubscriptionRef } from 'effect';
+import { LedgerState } from '@midnightntwrk/ledger-v9';
+import { NetworkId, ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { LedgerTranslationError } from './LedgerTranslation.js';
+import { Simulator } from './v9/Simulator.js';
+import { blankState, updateLedger } from './v9/SimulatorState.js';
+import * as V8 from './v8/index.js';
+// =============================================================================
+// Fork Simulator
+// =============================================================================
+/**
+ * A simulated chain that crosses a hard fork, built from the two simulator twins.
+ *
+ * The ledger-v8 chain is available immediately and is driven like any other simulator. Once it reaches
+ * {@link ForkSimulatorConfig.forkBlock} the handover runs and the ledger-v9 chain appears; both remain alive for the
+ * simulator's scope, so assertions can read either side of the boundary.
+ *
+ * Nothing stops the ledger-v8 chain producing blocks past the boundary, which a real chain could not do — drive it only
+ * up to the fork.
+ *
+ * @example
+ *   ```typescript
+ *   const fork = yield* ForkSimulator.init({
+ *     forkBlock: 3n,
+ *     forkVersion: ProtocolVersion.ProtocolVersion(7n),
+ *     v8GenesisMints: [{ type: 'shielded', tokenType, amount: 1_000n, recipient: v8Keys }],
+ *     translator: translatorFromAsync(translateLedgerState),
+ *   });
+ *
+ *   yield* fork.v8.submitTransaction(v8Transfer);
+ *   const v9 = yield* fork.advanceToFork();
+ *   yield* v9.submitTransaction(v9Transfer);
+ *   ```;
+ */
+export class ForkSimulator {
+    // ===========================================================================
+    // Static Methods
+    // ===========================================================================
+    /**
+     * Initialize a forking chain. The ledger-v8 chain starts immediately with the fork already scheduled; the ledger-v9
+     * chain is constructed when the ledger-v8 chain reaches the fork block.
+     *
+     * @param config - Configuration options
+     * @returns Effect that produces a ForkSimulator
+     */
+    static init(config) {
+        return Effect.gen(function* () {
+            const networkId = config.networkId ?? NetworkId.NetworkId.Undeployed;
+            const v8Version = config.v8Version ?? ProtocolVersion.MinSupportedVersion;
+            const v8 = yield* V8.Simulator.init({
+                networkId,
+                protocolVersion: v8Version,
+                ...(config.v8GenesisMints !== undefined ? { genesisMints: config.v8GenesisMints } : {}),
+                ...(config.v8BlockProducer !== undefined ? { blockProducer: config.v8BlockProducer } : {}),
+            });
+            // Scheduled up front, so the boundary block carries the fork version however the chain is driven to it.
+            yield* v8.scheduleFork(config.forkBlock, config.forkVersion);
+            const v9Ref = yield* SubscriptionRef.make(Option.none());
+            const v9Ready = yield* Deferred.make();
+            const forkSimulator = new ForkSimulator(config, networkId, v8, v9Ref, v9Ready);
+            // The handover must outlive the watcher fiber, so it is built in the simulator's own scope.
+            const scope = yield* Effect.scope;
+            const runHandover = Effect.gen(function* () {
+                const atFork = yield* forkSimulator.#awaitForkBlock();
+                const v9 = yield* Scope.extend(
+                // Suspended so that a handover built from a throwing caller-supplied callback fails this effect rather than
+                // escaping as a synchronous exception.
+                Effect.suspend(() => forkSimulator.#handover(atFork)), scope);
+                // The reference is set first: anything woken by the deferred must already see the ledger-v9 chain.
+                yield* SubscriptionRef.set(v9Ref, Option.some(v9));
+                return v9;
+            });
+            // The handover runs detached, so its outcome has to be handed to whoever is waiting for the fork — including when
+            // it fails or dies. `intoDeferred` transfers the whole exit; completing the deferred by hand on the success path
+            // only would leave every waiter blocked forever on a broken handover, which reads as a hang rather than an error.
+            yield* Effect.forkScoped(Effect.intoDeferred(runHandover, v9Ready));
+            return forkSimulator;
+        });
+    }
+    // ===========================================================================
+    // Instance Properties
+    // ===========================================================================
+    #config;
+    #networkId;
+    #v9Ref;
+    #v9Ready;
+    /** The ledger-v8 chain. */
+    v8;
+    /** Height at which the chain forks. */
+    forkBlock;
+    /** Protocol version the fork activates. */
+    forkVersion;
+    constructor(config, networkId, v8, v9Ref, v9Ready) {
+        this.#config = config;
+        this.#networkId = networkId;
+        this.#v9Ref = v9Ref;
+        this.#v9Ready = v9Ready;
+        this.v8 = v8;
+        this.forkBlock = config.forkBlock;
+        this.forkVersion = config.forkVersion;
+    }
+    // ===========================================================================
+    // Instance Methods
+    // ===========================================================================
+    /**
+     * The ledger-v9 chain, if the fork has happened.
+     *
+     * @returns `Option.some` once the handover has completed, `Option.none` before
+     */
+    v9() {
+        return SubscriptionRef.get(this.#v9Ref);
+    }
+    /**
+     * Wait until the fork has happened, however the ledger-v8 chain is driven to it.
+     *
+     * Fails with the handover's own failure if it could not produce a ledger-v9 chain, so a broken handover surfaces here
+     * rather than leaving waiters blocked forever.
+     *
+     * @returns The ledger-v9 chain
+     */
+    awaitV9() {
+        return Deferred.await(this.#v9Ready);
+    }
+    /**
+     * Drive the ledger-v8 chain to the fork block with empty blocks and wait for the handover.
+     *
+     * Blocks the chain has already produced count towards the boundary, so this composes with transaction-driven
+     * production: submit what the test needs, then advance the rest of the way.
+     *
+     * @returns The ledger-v9 chain
+     */
+    advanceToFork() {
+        const v8 = this.v8;
+        const forkBlock = this.forkBlock;
+        const driveToForkBlock = () => Effect.gen(function* () {
+            const state = yield* v8.getLatestState();
+            if (V8.getCurrentBlockNumber(state) >= forkBlock)
+                return;
+            yield* v8.produceEmptyBlock();
+            yield* driveToForkBlock();
+        });
+        return pipe(driveToForkBlock(), Effect.flatMap(() => this.awaitV9()));
+    }
+    // ===========================================================================
+    // Internal
+    // ===========================================================================
+    /**
+     * Resolve once the ledger-v8 chain has reached the fork block, with the state at that point.
+     *
+     * The current state is checked before subscribing, and the ledger-v8 chain's shared state stream replays its latest
+     * value to new subscribers, so the boundary cannot slip past between the two.
+     */
+    #awaitForkBlock() {
+        const v8 = this.v8;
+        const forkBlock = this.forkBlock;
+        return Effect.gen(function* () {
+            const current = yield* v8.getLatestState();
+            if (V8.getCurrentBlockNumber(current) >= forkBlock)
+                return current;
+            const reached = yield* pipe(v8.state$, Stream.filter((state) => V8.getCurrentBlockNumber(state) >= forkBlock), Stream.take(1), Stream.runHead);
+            return yield* Option.match(reached, {
+                onNone: () => Effect.die(new Error('Ledger-v8 state stream ended before reaching the fork block')),
+                onSome: Effect.succeed,
+            });
+        });
+    }
+    /** Run the handover and construct the ledger-v9 chain, numbered and timed to continue from the fork point. */
+    #handover(v8State) {
+        const { forkVersion, forkBlock, v9BlockProducer } = this.#config;
+        const networkId = this.#networkId;
+        // The ledger-v9 chain resumes the ledger-v8 chain's height and clock, so the boundary is re-delivered rather than
+        // restarted. `blankState` takes the network id positionally, so it is not part of this.
+        const genesis = {
+            protocolVersion: forkVersion,
+            genesisBlockNumber: forkBlock,
+            genesisTime: v8State.currentTime,
+        };
+        /** A ledger-v9 chain whose genesis block already holds the given ledger, rather than one built by minting into it. */
+        const chainStartingFrom = (ledger) => pipe(Effect.promise(() => blankState(networkId, genesis)), Effect.map((state) => updateLedger(state, ledger)), Effect.flatMap((state) => Simulator.fromState(state, v9BlockProducer)));
+        return pipe(this.#config.translator(v8State.ledger.serialize()), 
+        // Deserializing is the harness's job, not the translator's, so bytes ledger-v9 rejects are a
+        // translation failure rather than a crash out of the handover fiber.
+        Effect.flatMap((translated) => Effect.try({
+            try: () => LedgerState.deserialize(translated),
+            catch: (cause) => new LedgerTranslationError({
+                message: 'Translated bytes are not a valid ledger-v9 state',
+                cause,
+            }),
+        })), Effect.flatMap(chainStartingFrom));
+    }
+}