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

package/README.md

@@ -32,18 +32,22 @@ while maintaining verifiability. It provides:
 
 ```typescript
 import { ShieldedWallet } from '@midnight-ntwrk/wallet-sdk-shielded';
-import * as ledger from '@midnight-ntwrk/ledger-v7';
+import { InMemoryTransactionHistoryStorage, ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { TransactionHistory } from '@midnight-ntwrk/wallet-sdk-shielded/v2';
+import * as ledger from '@midnightntwrk/ledger-v9';
 import { randomBytes } from 'node:crypto';
 
 // Configuration for the wallet
 const configuration = {
   networkId: 'preview',
-  provingServerUrl: new URL('http://localhost:6300'),
-  relayURL: new URL('ws://localhost:9944'),
   indexerClientConnection: {
-    indexerHttpUrl: 'http://localhost:8088/api/v3/graphql',
-    indexerWsUrl: 'ws://localhost:8088/api/v3/graphql/ws',
+    indexerHttpUrl: 'http://localhost:8088/api/v4/graphql',
+    indexerWsUrl: 'ws://localhost:8088/api/v4/graphql/ws',
   },
+  txHistoryStorage: new InMemoryTransactionHistoryStorage(TransactionHistory.ShieldedTransactionHistoryEntrySchema),
+  // Where this chain hands over to ledger-v9: the schedule of a chain born on ledger-v9, as a 2.x node runs. The
+  // final mainnet fork constant is not yet fixed, so a chain that hands over elsewhere states `{ v9: ... }` here.
+  forks: ProtocolVersion.V9NativeForkSchedule,
 };
 
 // Create secret keys from a shielded seed
@@ -85,8 +89,10 @@ wallet.state.subscribe((state) => {
 ### Creating Transfer Transactions
 
 ```typescript
+// tokenType: the shielded token type (raw hex) of a token you hold,
+// e.g. one minted by a contract — NIGHT is unshielded and cannot appear here
 const tx = await wallet.transferTransaction(shieldedSecretKeys, [
-  { type: 'NIGHT', receiverAddress: 'mn_shield-addr1...', amount: 1000n },
+  { type: tokenType, receiverAddress: 'mn_shield-addr1...', amount: 1000n },
 ]);
 ```
 
@@ -99,10 +105,12 @@ const balancingTx = await wallet.balanceTransaction(shieldedSecretKeys, transact
 ### Creating Swap Offers
 
 ```typescript
+// tokenTypeA / tokenTypeB: shielded token types (raw hex) — both sides of a
+// shielded swap are shielded tokens; NIGHT is unshielded and cannot appear here
 const swapTx = await wallet.initSwap(
   shieldedSecretKeys,
-  { NIGHT: 500n }, // inputs
-  [{ type: 'TOKEN_A', receiverAddress: shieldedAddress, amount: 100n }], // outputs
+  { [tokenTypeA]: 500n }, // inputs
+  [{ type: tokenTypeB, receiverAddress: shieldedAddress, amount: 100n }], // outputs
 );
 ```
 
@@ -124,7 +132,8 @@ While still proving:
 
 - `ShieldedWallet` - Main wallet class
 - `ShieldedWalletState` - Wallet state type
-- Version 1 exports via `@midnight-ntwrk/wallet-sdk-shielded/v1`
+- V2 (ledger-v9) variant internals via `@midnight-ntwrk/wallet-sdk-shielded/v2`
+- V1 (ledger-v8) variant internals via `@midnight-ntwrk/wallet-sdk-shielded/v1`
 
 ## License
 

package/dist/Restore.d.ts

@@ -0,0 +1,40 @@
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { Either, Option } from 'effect';
+declare const UnsupportedSnapshotVersionError_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-shielded/Restore/UnsupportedSnapshotVersionError";
+} & Readonly<A>;
+/**
+ * Raised when a snapshot declares a protocol version that no registered variant is able to read.
+ *
+ * @remarks
+ *   A wallet built for one range of protocol versions cannot invent a reader for a snapshot written outside it, and
+ *   guessing — handing the bytes to whichever variant happens to be registered — would decode them with the wrong
+ *   ledger. The version is carried on the error so an application can say which one it was.
+ */
+export declare class UnsupportedSnapshotVersionError extends UnsupportedSnapshotVersionError_base<{
+    readonly message: string;
+    readonly protocolVersion: ProtocolVersion.ProtocolVersion;
+}> {
+}
+/**
+ * Reads the protocol version a serialized wallet snapshot declares.
+ *
+ * @param serialized The serialized wallet state.
+ * @returns The declared version, or `Option.none()` when the snapshot declares none or cannot be read at all.
+ */
+export declare const peekProtocolVersion: (serialized: string) => Option.Option<ProtocolVersion.ProtocolVersion>;
+/**
+ * Chooses the variant that should read a serialized wallet snapshot.
+ *
+ * @remarks
+ *   A snapshot that declares no version predates snapshots declaring one, and can only have been written by the variant
+ *   that shipped before the question arose — the head variant. The same fallback covers an envelope this function
+ *   cannot read at all: refusing it here would replace the deserializer's precise error with a vaguer one.
+ * @param serialized The serialized wallet state.
+ * @param variantFor Resolves the variant registered for a protocol version.
+ * @param headVariant The variant a snapshot with no declared version is restored into.
+ * @returns The variant to restore with, or {@link UnsupportedSnapshotVersionError} when the declared version is one no
+ *   registered variant owns.
+ */
+export declare const variantForSnapshot: <TVariant>(serialized: string, variantFor: (version: ProtocolVersion.ProtocolVersion) => Option.Option<TVariant>, headVariant: TVariant) => Either.Either<TVariant, UnsupportedSnapshotVersionError>;
+export {};

package/dist/Restore.js

@@ -0,0 +1,63 @@
+// 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 { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { Data, Either, Option, Schema } from 'effect';
+/**
+ * Raised when a snapshot declares a protocol version that no registered variant is able to read.
+ *
+ * @remarks
+ *   A wallet built for one range of protocol versions cannot invent a reader for a snapshot written outside it, and
+ *   guessing — handing the bytes to whichever variant happens to be registered — would decode them with the wrong
+ *   ledger. The version is carried on the error so an application can say which one it was.
+ */
+export class UnsupportedSnapshotVersionError extends Data.TaggedError('@midnight-ntwrk/wallet-sdk-shielded/Restore/UnsupportedSnapshotVersionError') {
+}
+/**
+ * The envelope the peek reads.
+ *
+ * @remarks
+ *   Deliberately the smallest possible description of a snapshot: one optional field, every other ignored. It has to read
+ *   snapshots written by _any_ variant, including ones whose full schema this build does not have, so it must not
+ *   assert anything it does not need. Everything it cannot make sense of is reported as "no version declared", leaving
+ *   the real diagnosis to the deserializer that eventually reads the whole thing.
+ */
+const EnvelopeSchema = Schema.Struct({
+    protocolVersion: Schema.optional(ProtocolVersion.ProtocolVersionSchema),
+});
+/**
+ * Reads the protocol version a serialized wallet snapshot declares.
+ *
+ * @param serialized The serialized wallet state.
+ * @returns The declared version, or `Option.none()` when the snapshot declares none or cannot be read at all.
+ */
+export const peekProtocolVersion = (serialized) => Schema.decodeUnknownOption(Schema.parseJson(EnvelopeSchema))(serialized).pipe(Option.flatMap((envelope) => Option.fromNullable(envelope.protocolVersion)));
+/**
+ * Chooses the variant that should read a serialized wallet snapshot.
+ *
+ * @remarks
+ *   A snapshot that declares no version predates snapshots declaring one, and can only have been written by the variant
+ *   that shipped before the question arose — the head variant. The same fallback covers an envelope this function
+ *   cannot read at all: refusing it here would replace the deserializer's precise error with a vaguer one.
+ * @param serialized The serialized wallet state.
+ * @param variantFor Resolves the variant registered for a protocol version.
+ * @param headVariant The variant a snapshot with no declared version is restored into.
+ * @returns The variant to restore with, or {@link UnsupportedSnapshotVersionError} when the declared version is one no
+ *   registered variant owns.
+ */
+export const variantForSnapshot = (serialized, variantFor, headVariant) => Option.match(peekProtocolVersion(serialized), {
+    onNone: () => Either.right(headVariant),
+    onSome: (protocolVersion) => Either.fromOption(variantFor(protocolVersion), () => new UnsupportedSnapshotVersionError({
+        message: `No registered variant reads shielded wallet snapshots of protocol version ${protocolVersion}.`,
+        protocolVersion,
+    })),
+});

package/dist/ShieldedWallet.d.ts

@@ -1,65 +1,251 @@
-import { type ProtocolState, ProtocolVersion, type SyncProgress } from '@midnight-ntwrk/wallet-sdk-abstractions';
-import { type BaseV1Configuration, type DefaultV1Configuration, type V1Variant, CoreWallet } from './v1/index.js';
-import * as ledger from '@midnightntwrk/ledger-v9';
-import * as rx from 'rxjs';
-import { type BalancingResult } from './v1/Transacting.js';
-import { type SerializationCapability } from './v1/Serialization.js';
-import { type TransactionHistoryService } from './v1/TransactionHistory.js';
-import { type AvailableCoin, type CoinsAndBalancesCapability, type PendingCoin } from './v1/CoinsAndBalances.js';
-import { type KeysCapability } from './v1/Keys.js';
-import { type ShieldedAddress, type ShieldedCoinPublicKey, type ShieldedEncryptionPublicKey } from '@midnight-ntwrk/wallet-sdk-address-format';
-import { type TokenTransfer } from './v1/Transacting.js';
-import { type WalletSyncUpdate } from './v1/Sync.js';
-import { type Variant, type VariantBuilder, type WalletLike } from '@midnight-ntwrk/wallet-sdk-runtime/abstractions';
-export type ShieldedWalletCapabilities<TSerialized = string> = {
-    serialization: SerializationCapability<CoreWallet, null, TSerialized>;
-    coinsAndBalances: CoinsAndBalancesCapability<CoreWallet>;
-    keys: KeysCapability<CoreWallet>;
+/**
+ * A shielded wallet that registers a variant either side of a protocol boundary and follows the chain across it.
+ *
+ * @remarks
+ *   One wallet, two ledger versions. Before the boundary the V1 variant reads the chain with the ledger version that
+ *   produced it; from the boundary the V2 variant does, having been handed identity and a place in the timeline and
+ *   nothing else. Which one is running is the runtime's business, not the application's: the wallet's public API speaks
+ *   ledger-v9 throughout, and where the two sides genuinely differ — the key material each variant's synchronization
+ *   needs — the wallet resolves it per variant from what it retained.
+ *
+ *   `ShieldedWallet(configuration)` at the bottom is how this package ships it. `CustomForkingShieldedWallet` is the same
+ *   wallet over builders the caller chooses, and `SingleVariantShieldedWallet.ts` is the composition that gives up the
+ *   crossing to run one variant only.
+ */
+import type * as ledgerV8 from '@midnight-ntwrk/ledger-v8';
+import type * as ledgerV9 from '@midnightntwrk/ledger-v9';
+import { type NetworkId, ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { type ChainVersionProbe } from '@midnight-ntwrk/wallet-sdk-capabilities/chainVersion';
+import { Variant, type VariantBuilder, type WalletLike } from '@midnight-ntwrk/wallet-sdk-runtime/abstractions';
+import { Either } from 'effect';
+import { type UnsupportedSnapshotVersionError } from './Restore.js';
+import { type DefaultShieldedConfiguration, type ShieldedWalletAPI } from './ShieldedWalletAPI.js';
+import { type V1Variant } from './v1/index.js';
+import { type WalletSyncUpdate as V1SyncUpdate } from './v1/Sync.js';
+import { Migration, type V2Variant } from './v2/index.js';
+import { type WalletSyncUpdate as V2SyncUpdate } from './v2/Sync.js';
+import { type WalletError as V1WalletError } from './v1/WalletError.js';
+import { type WalletError } from './v2/WalletError.js';
+/**
+ * What restoring a shielded wallet from a snapshot can fail with.
+ *
+ * @remarks
+ *   Two failures, and they mean different things. The snapshot may declare a protocol version no registered variant
+ *   reads, which is a fact about this build of the SDK rather than about the snapshot; or the variant that owns it may
+ *   be unable to make sense of the bytes, which is a fact about the snapshot. Either is an ordinary thing to meet when
+ *   restoring something a user supplied, which is why `tryRestore` reports them rather than throwing.
+ */
+export type ShieldedRestoreError = UnsupportedSnapshotVersionError | V1WalletError | WalletError;
+/** The V1 variant a forking shielded wallet registers: the one that reads the chain before the boundary. */
+export type V1ShieldedVariant<TSyncUpdate> = V1Variant<string, TSyncUpdate, ledgerV8.FinalizedTransaction, ledgerV8.ZswapSecretKeys>;
+/** The V2 variant a forking shielded wallet registers: the one the V1 wallet is migrated into. */
+export type V2ShieldedVariant<TSyncUpdate> = V2Variant<string, TSyncUpdate, ledgerV9.FinalizedTransaction, ledgerV9.ZswapSecretKeys, Migration.PreviousLedgerWallet>;
+/** The two variants a forking shielded wallet runs, in registration order. */
+export type ForkingShieldedVariants<TV1SyncUpdate, TV2SyncUpdate> = [
+    Variant.VersionedVariant<V1ShieldedVariant<TV1SyncUpdate>>,
+    Variant.VersionedVariant<V2ShieldedVariant<TV2SyncUpdate>>
+];
+/**
+ * A variant builder registered together with the configuration it alone is built from.
+ *
+ * @remarks
+ *   Per-variant rather than shared, because two variants either side of a protocol boundary can mean different and
+ *   mutually unassignable things by the same configuration key — a `simulator` or an indexer connection belonging to
+ *   one ledger version or the other. A wallet-wide intersection of those is a configuration no single variant can
+ *   consume.
+ */
+export type SelfConfiguredShieldedVariant<TVariant extends Variant.AnyVariant, TConfiguration extends object> = Readonly<{
+    builder: VariantBuilder.VariantBuilder<TVariant, TConfiguration>;
+    configuration: TConfiguration;
+}>;
+/** What a forking shielded wallet needs to know about itself, whatever its variants are built from. */
+export type ForkingShieldedConfiguration = {
+    networkId: NetworkId.NetworkId;
+    /** Where each ledger version begins on this chain — see {@link ProtocolVersion.ForkSchedule}. */
+    forks: ProtocolVersion.ForkSchedule;
+    /**
+     * How the wallet asks the chain which protocol version it is on, before it chooses a variant to start at.
+     *
+     * @remarks
+     *   Optional, and best-effort where present: a wallet with no probe — or one whose probe does not answer in time —
+     *   starts on the V1 variant and learns the version from the first event it sees, which is what a wallet with no
+     *   history has always done. What a probe buys is the two things that guess costs: a hand-over per start on a chain
+     *   entirely past the boundary, and, on a chain that has shown this wallet no events at all, an epoch that never gets
+     *   corrected.
+     *
+     *   Nothing about it can make a start fail. A rejection, a timeout, a version no registered variant covers: each leaves
+     *   the wallet exactly where a wallet that never asked would be.
+     */
+    chainVersionProbe?: ChainVersionProbe;
 };
-export type ShieldedWalletServices = {
-    transactionHistory: TransactionHistoryService;
+/**
+ * One ledger version's shielded key objects per side of a protocol boundary.
+ *
+ * @remarks
+ *   Both sides are required. A caller holding key objects rather than a seed has to hold both, because the two belong to
+ *   different ledger runtimes and neither can be derived from the other; a product with one side optional would let a
+ *   wallet be built that cannot read half the chain, which is the shape this replaced.
+ */
+export type ShieldedKeysByEpoch = Readonly<{
+    /** The ledger-v8's Zswap secret keys. */
+    v8: ledgerV8.ZswapSecretKeys;
+    /** The ledger-v9's Zswap secret keys. */
+    v9: ledgerV9.ZswapSecretKeys;
+}>;
+/**
+ * A running shielded wallet that spans a protocol boundary.
+ *
+ * @remarks
+ *   Its two extra starts are the instance counterparts of the class-level ones, and they are here rather than on
+ *   {@link ShieldedWalletAPI} because only a wallet with a variant either side of a boundary has anything to do with
+ *   them: a single-variant wallet speaks one ledger version, and the key material `start` takes is always the right
+ *   one.
+ */
+export type ForkingShieldedWallet<TV1SyncUpdate, TV2SyncUpdate> = ShieldedWalletAPI<ledgerV9.ZswapSecretKeys, ledgerV9.FinalizedTransaction, string> & WalletLike.WalletLike<ForkingShieldedVariants<TV1SyncUpdate, TV2SyncUpdate>> & {
+    /**
+     * Starts this wallet from a seed, which answers for the variant either side of the boundary.
+     *
+     * @remarks
+     *   The instance counterpart of {@link ForkingShieldedWalletClass.startWithSeed}, and what a wallet restored from a
+     *   snapshot written below the boundary is started with. A snapshot carries no key material by design, and the
+     *   variant it restores onto is the ledger-v8 one, whose synchronization the ledger-v9 keys
+     *   {@link ShieldedWalletAPI.start} takes cannot serve. The class-level start answers for both sides too — but it
+     *   builds a _fresh_ wallet, which is the opposite of what a caller who has just restored one wants.
+     *
+     *   The seed itself is not kept: both ledger versions' keys are derived from it here and retained instead, which is
+     *   the same capability with a shorter-lived secret.
+     * @example
+     *   ```typescript
+     *   const wallet = ShieldedWallet(configuration).restore(snapshot);
+     *   await wallet.startWithSeed(seed);
+     *   ```;
+     *
+     * @param seed The seed to derive both ledger versions' keys from.
+     * @returns Nothing; resolves once synchronization has been started on whichever variant is current.
+     */
+    startWithSeed(seed: Uint8Array): Promise<void>;
+    /**
+     * Starts this wallet from key objects of both ledger versions.
+     *
+     * @remarks
+     *   The instance counterpart of {@link ForkingShieldedWalletClass.startWithKeys}, for a caller that will not part with
+     *   a seed. Both sides are required for the same reason they are there: key objects belong to one ledger version's
+     *   runtime, so a wallet given one side alone could not read the other side of the chain.
+     * @example
+     *   ```typescript
+     *   const wallet = ShieldedWallet(configuration).restore(snapshot);
+     *   await wallet.startWithKeys({ v8: v8Keys, v9: v9Keys });
+     *   ```;
+     *
+     * @param keys One ledger version's Zswap secret keys per side of the boundary.
+     * @returns Nothing; resolves once synchronization has been started on whichever variant is current.
+     */
+    startWithKeys(keys: ShieldedKeysByEpoch): Promise<void>;
 };
-export type UnboundTransaction = ledger.Transaction<ledger.SignatureEnabled, ledger.Proof, ledger.PreBinding>;
-export declare class ShieldedWalletState<TSerialized = string, _TTransaction = ledger.FinalizedTransaction> {
-    static readonly mapState: <TSerialized_1 = string>(variant: ShieldedWalletCapabilities<TSerialized_1> & ShieldedWalletServices) => (state: ProtocolState.ProtocolState<CoreWallet>) => ShieldedWalletState<TSerialized_1>;
-    readonly protocolVersion: ProtocolVersion.ProtocolVersion;
-    readonly state: CoreWallet;
-    readonly capabilities: ShieldedWalletCapabilities<TSerialized>;
-    readonly services: ShieldedWalletServices;
-    get balances(): Record<ledger.RawTokenType, bigint>;
-    get totalCoins(): readonly (AvailableCoin | PendingCoin)[];
-    get availableCoins(): readonly AvailableCoin[];
-    get pendingCoins(): readonly PendingCoin[];
-    get coinPublicKey(): ShieldedCoinPublicKey;
-    get encryptionPublicKey(): ShieldedEncryptionPublicKey;
-    get address(): ShieldedAddress;
-    get progress(): SyncProgress.SyncProgress;
-    constructor(state: ProtocolState.ProtocolState<CoreWallet>, capabilities: ShieldedWalletCapabilities<TSerialized>, services: ShieldedWalletServices);
-    serialize(): TSerialized;
+/** The class a forking shielded wallet is started from. */
+export interface ForkingShieldedWalletClass<TV1SyncUpdate, TV2SyncUpdate, TConfiguration extends ForkingShieldedConfiguration = ForkingShieldedConfiguration> extends WalletLike.BaseWalletClass<ForkingShieldedVariants<TV1SyncUpdate, TV2SyncUpdate>, TConfiguration> {
+    /**
+     * Builds a wallet from a seed, and remembers the seed.
+     *
+     * @remarks
+     *   The only start that can follow the chain the whole way. The seed is the one piece of key material that crosses a
+     *   protocol boundary — each variant derives its own from it — so a wallet built this way can synchronize on either
+     *   side of the fork.
+     *
+     *   Asynchronous because choosing where to begin can mean asking the chain: with a
+     *   {@link ForkingShieldedConfiguration.chainVersionProbe} configured, the wallet starts at the variant that owns the
+     *   version the chain reports, which on a chain already past the boundary is the ledger-v9 one from the first moment.
+     *   Without one, or when the question goes unanswered, it begins on the V1 variant and is handed over when the chain
+     *   reports a version the V2 variant owns — on a chain that has already forked, the first batch it sees.
+     * @param seed The seed to derive both ledger versions' keys from.
+     * @returns A wallet started at the variant the chain is on, or on the V1 variant when the chain was not asked or did
+     *   not say.
+     */
+    startWithSeed(seed: Uint8Array): Promise<ForkingShieldedWallet<TV1SyncUpdate, TV2SyncUpdate>>;
+    /**
+     * Builds a wallet from key objects of both ledger versions.
+     *
+     * @remarks
+     *   The escape hatch for a caller that will not hand over a seed. Both sides are required, and that is the whole point:
+     *   key objects belong to one ledger version's runtime, so a wallet given one side alone could not read the other
+     *   side of the chain — and a partial product here would be exactly the foot-gun the single-key start was. It costs
+     *   the caller an import of both ledger packages and the same derivation done twice; a seed costs neither.
+     * @param keys One ledger version's Zswap secret keys per side of the boundary.
+     * @returns A wallet started at the variant the chain is on, or on the V1 variant — where a wallet with no history
+     *   belongs — when the chain was not asked or did not say.
+     */
+    startWithKeys(keys: ShieldedKeysByEpoch): Promise<ForkingShieldedWallet<TV1SyncUpdate, TV2SyncUpdate>>;
+    /**
+     * Restores a wallet from a snapshot, into whichever registered variant wrote it.
+     *
+     * @param serializedState The serialized wallet state.
+     * @returns A wallet started from that state, on the variant that owns its protocol version.
+     * @throws UnsupportedSnapshotVersionError if the snapshot declares a version no registered variant reads.
+     */
+    restore(serializedState: string): ForkingShieldedWallet<TV1SyncUpdate, TV2SyncUpdate>;
+    /**
+     * Restores a wallet from a snapshot, reporting what it could not read rather than throwing.
+     *
+     * @remarks
+     *   Additive alongside {@link restore}, which is unchanged and still the right shape for a snapshot the application has
+     *   just written itself. This is the shape for one it has not: a snapshot a user supplied, or one written by a build
+     *   of the SDK that is no longer the one running, where "I cannot read this" is an ordinary answer rather than a bug.
+     *   The two cannot disagree — `restore` is this, with the reason thrown.
+     * @param serializedState The serialized wallet state.
+     * @returns A wallet started from that state, or the reason the snapshot could not be read. See
+     *   {@link ShieldedRestoreError}.
+     */
+    tryRestore(serializedState: string): Either.Either<ForkingShieldedWallet<TV1SyncUpdate, TV2SyncUpdate>, ShieldedRestoreError>;
 }
-export type ShieldedWallet = CustomizedShieldedWallet<ledger.ZswapSecretKeys, ledger.FinalizedTransaction, WalletSyncUpdate, string>;
-export type ShieldedWalletClass = CustomizedShieldedWalletClass<ledger.ZswapSecretKeys, ledger.FinalizedTransaction, WalletSyncUpdate, string>;
-export type ShieldedWalletAPI<TStartAux = ledger.ZswapSecretKeys, TTransaction = ledger.FinalizedTransaction, TSerialized = string> = {
-    readonly state: rx.Observable<ShieldedWalletState<TSerialized, TTransaction>>;
-    start(secretKeys: TStartAux): Promise<void>;
-    balanceTransaction(secretKeys: ledger.ZswapSecretKeys, tx: ledger.Transaction<ledger.Signaturish, ledger.Proofish, ledger.Bindingish>): Promise<BalancingResult>;
-    transferTransaction(secretKeys: ledger.ZswapSecretKeys, outputs: readonly TokenTransfer[]): Promise<ledger.UnprovenTransaction>;
-    initSwap(secretKeys: ledger.ZswapSecretKeys, desiredInputs: Record<ledger.RawTokenType, bigint>, desiredOutputs: readonly TokenTransfer[]): Promise<ledger.UnprovenTransaction>;
-    serializeState(): Promise<TSerialized>;
-    waitForSyncedState(allowedGap?: bigint): Promise<ShieldedWalletState<TSerialized, TTransaction>>;
-    getAddress(): Promise<ShieldedAddress>;
-    revertTransaction(transaction: ledger.Transaction<ledger.Signaturish, ledger.Proofish, ledger.Bindingish>): Promise<void>;
-    stop(): Promise<void>;
-};
-export type CustomizedShieldedWallet<TStartAux = ledger.ZswapSecretKeys, TTransaction = ledger.FinalizedTransaction, TSyncUpdate = WalletSyncUpdate, TSerialized = string> = ShieldedWalletAPI<TStartAux, TTransaction, TSerialized> & WalletLike.WalletLike<[Variant.VersionedVariant<V1Variant<TSerialized, TSyncUpdate, TTransaction, TStartAux>>]>;
-export type DefaultShieldedConfiguration = DefaultV1Configuration;
-export interface CustomizedShieldedWalletClass<TStartAux = ledger.ZswapSecretKeys, TTransaction = ledger.FinalizedTransaction, TSyncUpdate = WalletSyncUpdate, TSerialized = string, TConfig extends BaseV1Configuration = DefaultShieldedConfiguration> extends WalletLike.BaseWalletClass<[
-    Variant.VersionedVariant<V1Variant<TSerialized, TSyncUpdate, TTransaction, TStartAux>>
-]> {
-    configuration: TConfig;
-    startWithSeed(seed: Uint8Array): CustomizedShieldedWallet<TStartAux, TTransaction, TSyncUpdate, TSerialized>;
-    startWithSecretKeys(secretKeys: ledger.ZswapSecretKeys): CustomizedShieldedWallet<TStartAux, TTransaction, TSyncUpdate, TSerialized>;
-    restore(serializedState: TSerialized): CustomizedShieldedWallet<TStartAux, TTransaction, TSyncUpdate, TSerialized>;
-}
-export declare function ShieldedWallet(configuration: DefaultV1Configuration): ShieldedWalletClass;
-export declare function CustomShieldedWallet<TConfig extends BaseV1Configuration = DefaultV1Configuration, TStartAux = ledger.ZswapSecretKeys, TTransaction = ledger.FinalizedTransaction, TSyncUpdate = WalletSyncUpdate, TSerialized = string>(configuration: TConfig, builder: VariantBuilder.VariantBuilder<V1Variant<TSerialized, TSyncUpdate, TTransaction, TStartAux>, TConfig>): CustomizedShieldedWalletClass<TStartAux, TTransaction, TSyncUpdate, TSerialized, TConfig>;
+/**
+ * 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 declare function CustomForkingShieldedWallet<TV1SyncUpdate, TV2SyncUpdate, TV1Config extends object, TV2Config extends object, TConfiguration extends ForkingShieldedConfiguration = ForkingShieldedConfiguration>(configuration: TConfiguration, v1: SelfConfiguredShieldedVariant<V1ShieldedVariant<TV1SyncUpdate>, TV1Config>, v2: SelfConfiguredShieldedVariant<V2ShieldedVariant<TV2SyncUpdate>, TV2Config>): ForkingShieldedWalletClass<TV1SyncUpdate, TV2SyncUpdate, TConfiguration>;
+/** A shielded wallet built the way this package ships it: one variant either side of the protocol boundary. */
+export type ShieldedWallet = ForkingShieldedWallet<V1SyncUpdate, V2SyncUpdate>;
+/** The class {@link ShieldedWallet} builds. */
+export type ShieldedWalletClass = ForkingShieldedWalletClass<V1SyncUpdate, V2SyncUpdate, DefaultShieldedConfiguration>;
+/**
+ * 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 declare function ShieldedWallet(configuration: DefaultShieldedConfiguration): ShieldedWalletClass;