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

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));
+    }
+}

package/dist/simulation/LedgerTranslation.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Translating a ledger-v8 state into a ledger-v9 one.
+ *
+ * The translation itself is a ledger-side tool reached across a WASM boundary, so this module only describes the seam,
+ * never the mechanism: serialized bytes in, serialized bytes out, as an `Effect`. Bytes because that is the only thing
+ * that crosses the boundary — neither ledger's state objects exist in the other's WASM module. An `Effect` because the
+ * tool has to be loaded and then run to completion (it translates incrementally, under a cost budget per step), and
+ * both are the translator's business rather than the caller's.
+ */
+import { Effect } from 'effect';
+declare const LedgerTranslationError_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: "LedgerTranslationError";
+} & Readonly<A>;
+/** Thrown when a ledger-v8 state cannot be translated into a ledger-v9 one. */
+export declare class LedgerTranslationError extends LedgerTranslationError_base<{
+    message: string;
+    cause?: unknown;
+}> {
+}
+/**
+ * Translates a serialized ledger-v8 state into a serialized ledger-v9 one.
+ *
+ * Implementations own loading whatever performs the translation and running it to completion. Deserializing the result
+ * is the caller's, so bytes that are not valid ledger-v9 state are reported as a translation failure.
+ */
+export type LedgerStateTranslator = (v8State: Uint8Array) => Effect.Effect<Uint8Array, LedgerTranslationError>;
+/**
+ * Build a translator from an async function, turning anything it throws or rejects with into a
+ * {@link LedgerTranslationError}.
+ *
+ * This is how the WASM tool is meant to be plugged in: its call is asynchronous and it signals failure by throwing, so
+ * this is the whole adapter.
+ *
+ * @example
+ *   ```typescript
+ *   const translator = translatorFromAsync(async (bytes) => {
+ *     const tool = await loadStateTranslation();
+ *     return tool.translate(bytes);
+ *   });
+ *   ```;
+ *
+ * @param translate - Async translation of serialized ledger-v8 state into serialized ledger-v9 state
+ * @returns A translator over that function
+ */
+export declare const translatorFromAsync: (translate: (v8State: Uint8Array) => Promise<Uint8Array>) => LedgerStateTranslator;
+/**
+ * A translator that always fails, standing in for the real tool until it exists.
+ *
+ * Useful as an explicit default: a fork configured with it fails loudly at the boundary, rather than silently crossing
+ * it with state that was never translated.
+ */
+export declare const unavailableTranslator: LedgerStateTranslator;
+export {};

package/dist/simulation/LedgerTranslation.js

@@ -0,0 +1,56 @@
+// 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.
+/**
+ * Translating a ledger-v8 state into a ledger-v9 one.
+ *
+ * The translation itself is a ledger-side tool reached across a WASM boundary, so this module only describes the seam,
+ * never the mechanism: serialized bytes in, serialized bytes out, as an `Effect`. Bytes because that is the only thing
+ * that crosses the boundary — neither ledger's state objects exist in the other's WASM module. An `Effect` because the
+ * tool has to be loaded and then run to completion (it translates incrementally, under a cost budget per step), and
+ * both are the translator's business rather than the caller's.
+ */
+import { Data, Effect } from 'effect';
+/** Thrown when a ledger-v8 state cannot be translated into a ledger-v9 one. */
+export class LedgerTranslationError extends Data.TaggedError('LedgerTranslationError') {
+}
+/**
+ * Build a translator from an async function, turning anything it throws or rejects with into a
+ * {@link LedgerTranslationError}.
+ *
+ * This is how the WASM tool is meant to be plugged in: its call is asynchronous and it signals failure by throwing, so
+ * this is the whole adapter.
+ *
+ * @example
+ *   ```typescript
+ *   const translator = translatorFromAsync(async (bytes) => {
+ *     const tool = await loadStateTranslation();
+ *     return tool.translate(bytes);
+ *   });
+ *   ```;
+ *
+ * @param translate - Async translation of serialized ledger-v8 state into serialized ledger-v9 state
+ * @returns A translator over that function
+ */
+export const translatorFromAsync = (translate) => (v8State) => Effect.tryPromise({
+    try: () => translate(v8State),
+    catch: (cause) => new LedgerTranslationError({ message: 'Ledger state translation failed', cause }),
+});
+/**
+ * A translator that always fails, standing in for the real tool until it exists.
+ *
+ * Useful as an explicit default: a fork configured with it fails loudly at the boundary, rather than silently crossing
+ * it with state that was never translated.
+ */
+export const unavailableTranslator = () => Effect.fail(new LedgerTranslationError({
+    message: 'A v8-to-v9 ledger state translation is not yet available; supply a translator explicitly',
+}));