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

package/dist/ShieldedWallet.js

@@ -10,108 +10,367 @@
 // 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 { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
-import { V1Builder, V1Tag, CoreWallet, } from './v1/index.js';
-import * as ledger from '@midnightntwrk/ledger-v9';
-import { Effect, Either } from 'effect';
-import * as rx from 'rxjs';
+import { ProtocolVersion, WalletSeed, WalletTransaction, } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { makeIndexerChainVersionProbe, } from '@midnight-ntwrk/wallet-sdk-capabilities/chainVersion';
 import { WalletBuilder } from '@midnight-ntwrk/wallet-sdk-runtime';
-export class ShieldedWalletState {
-    static mapState = (variant) => (state) => {
-        const { serialization, coinsAndBalances, keys } = variant;
-        const { transactionHistory } = variant;
-        return new ShieldedWalletState(state, { serialization, coinsAndBalances, keys }, { transactionHistory });
-    };
-    protocolVersion;
-    state;
-    capabilities;
-    services;
-    get balances() {
-        return this.capabilities.coinsAndBalances.getAvailableBalances(this.state);
-    }
-    get totalCoins() {
-        return this.capabilities.coinsAndBalances.getTotalCoins(this.state);
-    }
-    get availableCoins() {
-        return this.capabilities.coinsAndBalances.getAvailableCoins(this.state);
-    }
-    get pendingCoins() {
-        return this.capabilities.coinsAndBalances.getPendingCoins(this.state);
-    }
-    get coinPublicKey() {
-        return this.capabilities.keys.getCoinPublicKey(this.state);
-    }
-    get encryptionPublicKey() {
-        return this.capabilities.keys.getEncryptionPublicKey(this.state);
-    }
-    get address() {
-        return this.capabilities.keys.getAddress(this.state);
-    }
-    get progress() {
-        return this.state.progress;
-    }
-    constructor(state, capabilities, services) {
-        this.protocolVersion = state.version;
-        this.state = state.state;
-        this.capabilities = capabilities;
-        this.services = services;
-    }
-    serialize() {
-        return this.capabilities.serialization.serialize(this.state);
-    }
-}
-export function ShieldedWallet(configuration) {
-    return CustomShieldedWallet(configuration, new V1Builder().withDefaults());
-}
-export function CustomShieldedWallet(configuration, builder) {
-    const buildArgs = [configuration];
+import { StartMaterial, Variant, } from '@midnight-ntwrk/wallet-sdk-runtime/abstractions';
+import { EitherOps, HList } from '@midnight-ntwrk/wallet-sdk-utilities';
+import { Duration, Effect, Either, Option, Ref, pipe } from 'effect';
+import * as rx from 'rxjs';
+import { variantForSnapshot } from './Restore.js';
+import { ShieldedWalletState, } from './ShieldedWalletAPI.js';
+import { CoreWallet as V1CoreWallet, V1Builder, V1Tag } from './v1/index.js';
+import { CoreWallet, Migration, V2Builder, V2Tag } from './v2/index.js';
+/**
+ * Builds a shielded wallet class over a variant either side of a protocol boundary.
+ *
+ * @remarks
+ *   The boundary is `configuration.forks.v9` and nothing else: the V1 variant is registered from the minimum supported
+ *   version and the ledger-v9 one from the fork version, so the version at which the runtime hands over and the version
+ *   at which each variant stops applying are the same number, taken from one place.
+ *
+ *   Each variant is built from its own configuration. What the wallet layer needs — the network it is on and where the
+ *   boundary lies — it takes separately, because neither variant knows there is another one.
+ * @example
+ *   ```typescript
+ *   const Wallet = CustomForkingShieldedWallet(
+ *     { networkId, forks },
+ *     { builder: new V1Builder().withDefaults(), configuration: v1Configuration },
+ *     { builder: new V2Builder().withDefaults().withMigration(makeCrossLedgerMigration), configuration: v2Configuration },
+ *   );
+ *   const wallet = Wallet.startWithSeed(seed);
+ *   ```;
+ *
+ * @param configuration What the wallet layer needs: the network, and where the boundary lies.
+ * @param v1 The variant that reads the chain below the boundary, with the configuration it is built from.
+ * @param v2 The variant that reads it from the boundary, with the configuration it is built from.
+ * @returns The wallet class.
+ */
+export function CustomForkingShieldedWallet(configuration, v1, v2) {
+    // Registered through the shape the builder states rather than through the one this function was handed. The two are
+    // the same builder; what is dropped is the configuration *type*, which the parameter types have already paired with
+    // its builder — and which, left generic, keeps `build`'s "nothing further is owed" argument list unresolvable.
+    const v1Builder = v1.builder;
+    const v2Builder = v2.builder;
     const BaseWallet = WalletBuilder.init()
-        .withVariant(ProtocolVersion.MinSupportedVersion, builder)
-        .build(...buildArgs);
-    return class CustomShieldedWalletImplementation extends BaseWallet {
-        static startWithSecretKeys(secretKeys) {
-            return CustomShieldedWalletImplementation.startFirst(CustomShieldedWalletImplementation, CoreWallet.initEmpty(secretKeys, CustomShieldedWalletImplementation.configuration.networkId));
+        .withVariant(ProtocolVersion.MinSupportedVersion, v1Builder, v1.configuration)
+        .withVariant(configuration.forks.v9, v2Builder, v2.configuration)
+        .build();
+    const variants = BaseWallet.allVariantsRecord();
+    /** Nothing retained: never started, or stopped. */
+    const noKeys = { v8: Option.none(), v9: Option.none() };
+    /** Both sides, derived from one seed. */
+    const keysFromSeed = (seed) => ({
+        v8: Option.some(variants[V1Tag].variant.startAux.fromSeed(seed)),
+        v9: Option.some(variants[V2Tag].variant.startAux.fromSeed(seed)),
+    });
+    /**
+     * What a variant can be started with, or why it cannot be.
+     *
+     * @remarks
+     *   Two different failures, deliberately distinguished: a wallet that was never started (or has been stopped) holds
+     *   nothing at all, while one started with the other side's key objects holds something it must not use here.
+     */
+    const auxFor = (retained, side, variantTag) => Either.fromOption(side, () => new StartMaterial.MissingStartAuxError({
+        message: Option.isNone(retained.v8) && Option.isNone(retained.v9)
+            ? `This wallet holds no key material: it has not been started, or it has been stopped. Start it ` +
+                `before asking it to synchronize or to build a transaction.`
+            : `This wallet holds key material of the other protocol version only, which the variant ` +
+                `${String(variantTag)} cannot use: key objects belong to one ledger version's runtime. Start this ` +
+                `wallet with material that answers for either side — startWithSeed(seed), or ` +
+                `startWithKeys({ v8, v9 }).`,
+        variantTag,
+    }));
+    const v8Aux = (retained) => auxFor(retained, retained.v8, V1Tag);
+    const v9Aux = (retained) => auxFor(retained, retained.v9, V2Tag);
+    /**
+     * The protocol versions each variant owns, and the version a transaction it builds is stamped with.
+     *
+     * @remarks
+     *   The stamp is the version at which the variant that built the transaction became current — the floor of its epoch —
+     *   rather than the block height the chain happened to be at. Every decision the stamp is later read for asks which
+     *   side of the boundary the bytes belong to: which prover proves them, which validator checks them, which variant
+     *   may unwrap them. The epoch floor is the one value guaranteed to answer that the same way as any other version in
+     *   the same epoch, and it is derived here from the same `forks.v9` the variants are registered at.
+     */
+    const v8Epoch = ProtocolVersion.epochOf(ProtocolVersion.MinSupportedVersion, configuration.forks.v9);
+    const v9Epoch = ProtocolVersion.epochOf(configuration.forks.v9, configuration.forks.v9);
+    const [v8Stamp] = v8Epoch;
+    const [v9Stamp] = v9Epoch;
+    /** Seals a balancing result, which is absent when the wallet had nothing of its own to add. */
+    const sealV8 = (result) => result === undefined ? undefined : WalletTransaction.adopt('Unproven', result, v8Stamp);
+    const sealV9 = (result) => result === undefined ? undefined : WalletTransaction.adopt('Unproven', result, v9Stamp);
+    /**
+     * How long a start waits for the chain to say which version it is on.
+     *
+     * @remarks
+     *   Short, because what is being bought is small: the alternative to an answer is the hand-over this wallet has always
+     *   done, which costs one migration and no correctness on a chain that produces events. It is a ceiling rather than a
+     *   typical cost — an unreachable indexer refuses a connection long before this — and it exists so that a probe which
+     *   neither answers nor fails cannot hold a start open indefinitely.
+     */
+    const probeTimeout = Duration.seconds(5);
+    /**
+     * The variant the chain's current version belongs to, or nothing.
+     *
+     * @remarks
+     *   Nothing covers every way the question can fail to produce an answer, and they are deliberately not distinguished:
+     *   no probe configured, a probe that rejected, a probe that outlived the wallet's patience, or a version no
+     *   registered variant claims. Each means the same thing to a caller — start where a wallet with no history starts —
+     *   and none of them is a reason to fail.
+     */
+    const probedStart = configuration.chainVersionProbe === undefined
+        ? Effect.succeedNone
+        : pipe(Effect.tryPromise(configuration.chainVersionProbe), Effect.timeout(probeTimeout), Effect.map((version) => Option.map(BaseWallet.variantFor(version), (variant) => ({ version, variant }))), Effect.orElseSucceed(() => Option.none()));
+    /**
+     * A fresh state of the variant a probed start begins at, recording the version the chain reported.
+     *
+     * @remarks
+     *   Built exactly as the head-variant boot path builds its own — an empty state of that variant, from that ledger
+     *   version's keys — and then annotated with the observed version, which is what keeps a variant from starting
+     *   outside its own activation range and signalling backwards on sight.
+     */
+    const freshStateAt = (variant, keys, version) => Variant.getVersionedVariantTag(variant) === V2Tag
+        ? CoreWallet.withProtocolVersion(CoreWallet.initEmpty(keys.v9, configuration.networkId), version)
+        : V1CoreWallet.withProtocolVersion(V1CoreWallet.initEmpty(keys.v8, configuration.networkId), version);
+    return class ForkingShieldedWalletImplementation extends BaseWallet {
+        static configuration = configuration;
+        /**
+         * Starts at the variant the chain says it is on, or at the head variant when it does not say.
+         *
+         * @remarks
+         *   The second branch is the whole of this wallet's previous behaviour, unchanged and reached whenever the chain was
+         *   not asked or did not answer: the V1 variant, an empty state, and a hand-over on the first batch that reports a
+         *   version it does not own.
+         * @param keys One ledger version's keys per side of the boundary, since either side may be the one that runs.
+         * @returns The started wallet.
+         */
+        static #startProbed(keys) {
+            return pipe(probedStart, Effect.map(Option.match({
+                onNone: () => ForkingShieldedWalletImplementation.startFirst(ForkingShieldedWalletImplementation, V1CoreWallet.initEmpty(keys.v8, configuration.networkId)),
+                onSome: ({ version, variant }) => ForkingShieldedWalletImplementation.startAtVariant(ForkingShieldedWalletImplementation, variant, freshStateAt(variant, keys, version)),
+            })), Effect.runPromise);
+        }
+        static async startWithSeed(seed) {
+            const derived = keysFromSeed(WalletSeed.WalletSeed(seed));
+            const wallet = await ForkingShieldedWalletImplementation.#startProbed({
+                v8: Option.getOrThrow(derived.v8),
+                v9: Option.getOrThrow(derived.v9),
+            });
+            // Both sides derived here and now, and the seed reference dropped with this frame: from this point the wallet
+            // holds key objects only, which is strictly less than it held before and does the same work.
+            wallet.#retainKeys(derived);
+            return wallet;
+        }
+        static async startWithKeys(keys) {
+            const wallet = await ForkingShieldedWalletImplementation.#startProbed(keys);
+            wallet.#retainKeys({ v8: Option.some(keys.v8), v9: Option.some(keys.v9) });
+            return wallet;
         }
-        static startWithSeed(seed) {
-            const secretKeys = ledger.ZswapSecretKeys.fromSeed(seed);
-            return CustomShieldedWalletImplementation.startWithSecretKeys(secretKeys);
+        static tryRestore(serializedState) {
+            const headVariant = HList.head(ForkingShieldedWalletImplementation.allVariants());
+            return variantForSnapshot(serializedState, (version) => ForkingShieldedWalletImplementation.variantFor(version), headVariant).pipe(
+            // Stated with its result type because the resolved variant is either of the two, so its deserializer is
+            // either of theirs: what comes back is a state of whichever one wrote the snapshot, which is what
+            // `startAtVariant` takes.
+            Either.flatMap((variant) => {
+                // Annotated rather than inferred because the resolved variant is either of the two, so its deserializer is
+                // either of theirs: what comes back is a state of whichever one wrote the snapshot, which is what
+                // `startAtVariant` takes.
+                const deserialized = variant.variant.deserializeState(serializedState);
+                return Either.map(deserialized, (state) => ForkingShieldedWalletImplementation.startAtVariant(ForkingShieldedWalletImplementation, variant, state));
+            }));
         }
         static restore(serializedState) {
-            const deserialized = CustomShieldedWalletImplementation.allVariantsRecord()[V1Tag].variant.deserializeState(serializedState)
-                .pipe(Either.getOrThrow);
-            return CustomShieldedWalletImplementation.startFirst(CustomShieldedWalletImplementation, deserialized);
+            return Either.getOrThrow(ForkingShieldedWalletImplementation.tryRestore(serializedState));
         }
         state;
+        /**
+         * What the application started this wallet with, kept so synchronization can be started again.
+         *
+         * @remarks
+         *   A migration starts a fresh variant whose sync has never run, and sync needs key material that is deliberately
+         *   absent from anything the wallet serializes. A retained seed answers for both variants; retained key objects
+         *   answer only for the ledger-v9 one, which is the ledger version this wallet's public API speaks. Cleared by
+         *   {@link stop} so a stopped wallet cannot be resurrected by a late activation.
+         */
+        #retainedKeys = Ref.unsafeMake(noKeys);
+        /** Remembers key material for both sides of the boundary. */
+        #retainKeys(keys) {
+            Ref.set(this.#retainedKeys, keys).pipe(Effect.runSync);
+        }
+        /**
+         * Starts synchronization on a variant that has just become current, with key material it can use.
+         *
+         * @param running The variant to start.
+         * @param auxFor That variant's own resolution of what it can be started with.
+         */
+        #resumeSyncOn(running, keysFor) {
+            return Ref.get(this.#retainedKeys).pipe(Effect.flatMap((retained) => 
+            // Stopped, or never started: there is nothing to resume and nothing to resume it with.
+            Option.isNone(retained.v8) && Option.isNone(retained.v9)
+                ? Effect.void
+                : EitherOps.toEffect(keysFor(retained)).pipe(Effect.flatMap((aux) => running.startSyncInBackground(aux)))));
+        }
+        /**
+         * Whether the activation watcher has been registered.
+         *
+         * @remarks
+         *   Registration is per wallet, not per `start`: watchers accumulate, so registering on every call would restart sync
+         *   once per historical `start` on the next activation. Flipped with `getAndSet` so concurrent `start` calls cannot
+         *   both observe it unset.
+         */
+        #watcherRegistered = Ref.unsafeMake(false);
         constructor(runtime, scope) {
             super(runtime, scope);
-            this.state = this.rawState.pipe(rx.map(ShieldedWalletState.mapState(CustomShieldedWalletImplementation.allVariantsRecord()[V1Tag].variant)), rx.shareReplay({ refCount: true, bufferSize: 1 }));
+            this.state = this.rawState.pipe(rx.map((emission) => 
+            // The capabilities that understand a state and the state itself are chosen together, in the branch where
+            // the producing variant is known. The two variants' capability types are structurally identical, so a
+            // capability of one would type-check against a state of the other and be wrong at runtime.
+            emission.variantTag === V2Tag
+                ? ShieldedWalletState.fromVariant(variants[V2Tag].variant, emission)
+                : ShieldedWalletState.fromVariant(variants[V1Tag].variant, emission)), rx.shareReplay({ refCount: true, bufferSize: 1 }));
+        }
+        /**
+         * Everything a start does once the wallet holds its key material: watch for the next variant, synchronize on this
+         * one.
+         *
+         * @remarks
+         *   The same work whichever start was called — what the three differ in is only what they retained a moment earlier —
+         *   so it is stated once. The watcher is registered before the first dispatch and only once per wallet:
+         *   `onVariantActivation` resolves only after its subscription is live, so an activation racing a start is queued
+         *   rather than missed, and watchers accumulate, so registering per call would restart synchronization once per
+         *   historical start.
+         *
+         *   Both branches of the dispatch resolve their keys from what was retained rather than from what the caller passed,
+         *   because the variant that is current is not the caller's to know: a wallet restored below the boundary is on the
+         *   ledger-v8 one whatever the application holds.
+         */
+        #startSynchronizing() {
+            return Effect.gen(this, function* () {
+                const alreadyRegistered = yield* Ref.getAndSet(this.#watcherRegistered, true);
+                if (!alreadyRegistered) {
+                    yield* this.runtime.onVariantActivation({
+                        [V1Tag]: (v1) => this.#resumeSyncOn(v1, v8Aux),
+                        [V2Tag]: (v2) => this.#resumeSyncOn(v2, v9Aux),
+                    });
+                }
+                yield* this.runtime.dispatch({
+                    [V1Tag]: (v1) => this.#resumeSyncOn(v1, v8Aux),
+                    [V2Tag]: (v2) => this.#resumeSyncOn(v2, v9Aux),
+                });
+            });
         }
+        /**
+         * Starts background synchronization on whichever variant is current, and keeps the keys for the next one.
+         *
+         * @remarks
+         *   The keys are ledger-v9's, so they are retained against that variant alone and answer for it alone. A wallet still
+         *   on the V1 variant is started from whatever it holds for _that_ side — which a wallet built from a seed, or from
+         *   both versions' keys, can always answer and one holding only these cannot.
+         *
+         *   That is the position of a wallet restored from a snapshot written below the boundary: a snapshot carries no key
+         *   material, so these keys leave it with nothing the running variant can use, and it says so rather than
+         *   pretending to have started. {@link ForkingShieldedWallet.startWithSeed} and
+         *   {@link ForkingShieldedWallet.startWithKeys} are the same wallet started with material that answers for either
+         *   side.
+         * @param secretKeys The ledger-v9's Zswap secret keys.
+         */
         start(secretKeys) {
-            return this.runtime.dispatch({ [V1Tag]: (v1) => v1.startSyncInBackground(secretKeys) }).pipe(Effect.runPromise);
+            return Effect.gen(this, function* () {
+                // The ledger-v9 side only: these keys belong to that ledger version's runtime. Whatever the wallet already
+                // holds for the ledger-v8 side is left as it is, so a wallet built from a seed keeps the ability to read a
+                // chain that has not forked yet.
+                yield* Ref.update(this.#retainedKeys, (retained) => ({ ...retained, v9: Option.some(secretKeys) }));
+                yield* this.#startSynchronizing();
+            }).pipe(Effect.runPromise);
+        }
+        startWithSeed(seed) {
+            return Effect.gen(this, function* () {
+                // Replaced rather than merged: a seed answers for every variant, so whatever partial material the wallet held
+                // has nothing left to contribute.
+                yield* Ref.set(this.#retainedKeys, keysFromSeed(WalletSeed.WalletSeed(seed)));
+                yield* this.#startSynchronizing();
+            }).pipe(Effect.runPromise);
+        }
+        startWithKeys(keys) {
+            return Effect.gen(this, function* () {
+                yield* Ref.set(this.#retainedKeys, { v8: Option.some(keys.v8), v9: Option.some(keys.v9) });
+                yield* this.#startSynchronizing();
+            }).pipe(Effect.runPromise);
+        }
+        async stop() {
+            // Released before the runtime is torn down: the key material outlives neither the wallet nor an in-flight
+            // activation.
+            Ref.set(this.#retainedKeys, noKeys).pipe(Effect.runSync);
+            await super.stop();
+        }
+        /**
+         * The key material the variant that is current can use, from what this wallet retained.
+         *
+         * @remarks
+         *   Transacting needs the same secrets synchronization does, and for the same reason: coin selection reads coins only
+         *   their owner can decrypt. A wallet that was never started, or one holding key objects of the other ledger
+         *   version, has none the current variant can use and says so by name.
+         */
+        #requireAux(keysFor) {
+            return Ref.get(this.#retainedKeys).pipe(Effect.flatMap((retained) => EitherOps.toEffect(keysFor(retained))));
         }
-        balanceTransaction(secretKeys, tx) {
+        /**
+         * Balances a transaction with shielded coins, on whichever side of the boundary it was built.
+         *
+         * @param tx The transaction to balance, which must have been built in the epoch this wallet is currently in.
+         * @returns The balancing transaction, stamped with the version it was built at, or nothing when none is needed.
+         */
+        balanceTransaction(tx) {
             return this.runtime
                 .dispatch({
-                [V1Tag]: (v1) => v1.balanceTransaction(secretKeys, tx),
+                [V1Tag]: (v1) => Effect.all([
+                    this.#requireAux(v8Aux),
+                    EitherOps.toEffect(WalletTransaction.unwrapWithin(tx, v8Epoch)),
+                ]).pipe(Effect.flatMap(([keys, unwrapped]) => v1.balanceTransaction(keys, unwrapped)), Effect.map(sealV8)),
+                [V2Tag]: (v2) => Effect.all([
+                    this.#requireAux(v9Aux),
+                    EitherOps.toEffect(WalletTransaction.unwrapWithin(tx, v9Epoch)),
+                ]).pipe(Effect.flatMap(([keys, unwrapped]) => v2.balanceTransaction(keys, unwrapped)), Effect.map(sealV9)),
             })
                 .pipe(Effect.runPromise);
         }
-        transferTransaction(secretKeys, outputs) {
+        transferTransaction(outputs) {
             return this.runtime
                 .dispatch({
-                [V1Tag]: (v1) => v1.transferTransaction(secretKeys, outputs),
+                [V1Tag]: (v1) => this.#requireAux(v8Aux).pipe(Effect.flatMap((keys) => v1.transferTransaction(keys, outputs)), Effect.map((tx) => WalletTransaction.adopt('Unproven', tx, v8Stamp))),
+                [V2Tag]: (v2) => this.#requireAux(v9Aux).pipe(Effect.flatMap((keys) => v2.transferTransaction(keys, outputs)), Effect.map((tx) => WalletTransaction.adopt('Unproven', tx, v9Stamp))),
             })
                 .pipe(Effect.runPromise);
         }
-        initSwap(secretKeys, desiredInputs, desiredOutputs) {
+        initSwap(desiredInputs, desiredOutputs) {
             return this.runtime
-                .dispatch({ [V1Tag]: (v1) => v1.initSwap(secretKeys, desiredInputs, desiredOutputs) })
+                .dispatch({
+                [V1Tag]: (v1) => this.#requireAux(v8Aux).pipe(Effect.flatMap((keys) => v1.initSwap(keys, desiredInputs, desiredOutputs)), Effect.map((tx) => WalletTransaction.adopt('Unproven', tx, v8Stamp))),
+                [V2Tag]: (v2) => this.#requireAux(v9Aux).pipe(Effect.flatMap((keys) => v2.initSwap(keys, desiredInputs, desiredOutputs)), Effect.map((tx) => WalletTransaction.adopt('Unproven', tx, v9Stamp))),
+            })
                 .pipe(Effect.runPromise);
         }
+        /**
+         * Un-records a transaction this wallet produced, releasing the coins it had booked.
+         *
+         * @remarks
+         *   A transaction built on the other side of the boundary is not one the current variant could have booked coins for,
+         *   so there is nothing of it to release and this resolves having done nothing. That is the one place a version
+         *   mismatch is not an error: the facade reverts all three wallets together when a submission fails, and a refusal
+         *   here would strand that whole path over a transaction this wallet was never holding anything for.
+         *
+         *   The coins a ledger-v8 transaction did book are not left behind by that no-op: they crossed the boundary as
+         *   reservations, and the first sync update after the crossing releases every one of them, because no transaction
+         *   of that ledger version can be included any more (`v2/CoreWallet.completeCrossing`).
+         * @param transaction The transaction to un-record.
+         */
         revertTransaction(transaction) {
             return this.runtime
                 .dispatch({
-                [V1Tag]: (v1) => v1.revertTransaction(transaction),
+                [V1Tag]: (v1) => Either.match(WalletTransaction.unwrapWithin(transaction, v8Epoch), { onLeft: () => Effect.void, onRight: (unwrapped) => v1.revertTransaction(unwrapped) }),
+                [V2Tag]: (v2) => Either.match(WalletTransaction.unwrapWithin(transaction, v9Epoch), { onLeft: () => Effect.void, onRight: (unwrapped) => v2.revertTransaction(unwrapped) }),
             })
                 .pipe(Effect.runPromise);
         }
@@ -119,8 +378,8 @@ export function CustomShieldedWallet(configuration, builder) {
             return rx.firstValueFrom(this.state.pipe(rx.filter((state) => state.state.progress.isCompleteWithin(allowedGap))));
         }
         /**
-         * Serializes the most recent state It's preferable to use [[ShieldedWalletState.serialize]] instead, to know
-         * exactly, which state is serialized
+         * Serializes the most recent state. It's preferable to use [[ShieldedWalletState.serialize]] instead, to know
+         * exactly which state is serialized.
          */
         serializeState() {
             return rx.firstValueFrom(this.state).then((state) => state.serialize());
@@ -130,3 +389,34 @@ export function CustomShieldedWallet(configuration, builder) {
         }
     };
 }
+/**
+ * Builds the shielded wallet this package ships: the default variant either side of `configuration.forks.v9`.
+ *
+ * @remarks
+ *   Both variants read the chain through the indexer and record transaction history in the same storage; each is built
+ *   from the same application configuration, because what they ask for happens to coincide. The V2 variant is
+ *   registered with the cross-ledger migration, which is what makes the hand-over carry identity and a cursor onto a
+ *   fresh state rather than start a wallet from nothing.
+ *
+ *   **Transacting works on either side of the boundary**: the active variant builds with its own ledger and its own
+ *   derived keys, and every result travels as a handle stamped with the epoch that built it. Proving a ledger-v8
+ *   transaction still requires a proving server registered below the boundary.
+ *
+ *   **The chain is asked where it is before a variant is chosen.** The indexer this wallet already syncs from answers
+ *   which protocol version the chain is on, so a start on a chain past the boundary begins on V2 rather than handing
+ *   over immediately. An application that would rather ask something else — a cache, a value it already holds —
+ *   supplies its own `chainVersionProbe`; one whose chain cannot be reached loses nothing, because the answer is
+ *   best-effort and its absence is the behaviour this wallet had before.
+ * @param configuration What the wallet and both its variants are built from, including where the boundary lies.
+ * @returns The wallet class.
+ */
+export function ShieldedWallet(configuration) {
+    const withProbe = {
+        ...configuration,
+        chainVersionProbe: configuration.chainVersionProbe ?? makeIndexerChainVersionProbe(configuration),
+    };
+    return CustomForkingShieldedWallet(withProbe, { builder: new V1Builder().withDefaults(), configuration }, {
+        builder: new V2Builder().withDefaults().withMigration(() => Migration.makeCrossLedgerMigration()),
+        configuration,
+    });
+}