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

package/dist/ShieldedWalletAPI.d.ts

@@ -0,0 +1,179 @@
+/**
+ * The contract every shielded wallet composition fulfils, and the state it emits.
+ *
+ * @remarks
+ *   Shared by the single-variant composition (`SingleVariantShieldedWallet.ts`) and the one that spans a protocol
+ *   boundary (`ShieldedWallet.ts`), and kept apart from both so that neither has to import the other to speak the same
+ *   API. Nothing here knows how many variants are running: a state emission arrives already bound to the capabilities
+ *   of the variant that produced it, and everything below that binding is plain data.
+ */
+import type * as ledger from '@midnightntwrk/ledger-v9';
+import { type AnyTx, type NetworkId, type ProtocolState, ProtocolVersion, type SyncProgress, type UnprovenTx } from '@midnightntwrk/wallet-sdk-abstractions';
+import { type ShieldedAddress, type ShieldedCoinPublicKey, type ShieldedEncryptionPublicKey } from '@midnightntwrk/wallet-sdk-address-format';
+import type { ChainVersionProbe } from '@midnightntwrk/wallet-sdk-capabilities/chainVersion';
+import type { V9UnboundTransaction } from '@midnightntwrk/wallet-sdk-capabilities/proving';
+import { type Duration } from 'effect';
+import type * as rx from 'rxjs';
+import { type CoreWallet as V1CoreWallet } from './v1/CoreWallet.js';
+import { type AvailableCoin, type CoinsAndBalancesCapability, type PendingCoin } from './v2/CoinsAndBalances.js';
+import { type CoreWallet } from './v2/index.js';
+import { type KeysCapability } from './v2/Keys.js';
+import { type SerializationCapability } from './v2/Serialization.js';
+import { type BatchUpdatesConfig, type IndexerClientConnection } from './v2/Sync.js';
+import { type TokenTransfer } from './v2/Transacting.js';
+import { type ShieldedHistoryStorage, type TransactionHistoryService } from './v2/TransactionHistory.js';
+export type ShieldedWalletCapabilities<TSerialized = string> = {
+    serialization: SerializationCapability<CoreWallet, null, TSerialized>;
+    coinsAndBalances: CoinsAndBalancesCapability<CoreWallet>;
+    keys: KeysCapability<CoreWallet>;
+};
+export type ShieldedWalletServices = {
+    transactionHistory: TransactionHistoryService;
+};
+/**
+ * A transaction that has been proven but not yet bound.
+ *
+ * @remarks
+ *   Owned by the proving capability, which is what produces one, and re-exported here so the name stays where callers
+ *   already reach for it. The shielded wallet neither builds nor consumes one itself.
+ */
+export type { V9UnboundTransaction };
+/** The core state of whichever shielded variant produced an emission. */
+export type ShieldedCoreState = V1CoreWallet | CoreWallet;
+/**
+ * Everything a state emission projects, already bound to the variant that produced it.
+ *
+ * @remarks
+ *   Binding is the point. The capabilities that understand a state and the state itself must be 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. Once bound there is
+ *   nothing left to mis-pair, and everything below is version-agnostic plain data.
+ */
+type ShieldedProjections<TSerialized> = Readonly<{
+    balances: () => Record<ledger.RawTokenType, bigint>;
+    totalCoins: () => readonly (AvailableCoin | PendingCoin)[];
+    availableCoins: () => readonly AvailableCoin[];
+    pendingCoins: () => readonly PendingCoin[];
+    coinPublicKey: () => ShieldedCoinPublicKey;
+    encryptionPublicKey: () => ShieldedEncryptionPublicKey;
+    address: () => ShieldedAddress;
+    serialize: () => TSerialized;
+}>;
+/** The capability set a variant exposes for reading and serializing its own state. */
+type ShieldedStateCapabilities<TState, TSerialized> = Readonly<{
+    serialization: SerializationCapability<TState, null, TSerialized>;
+    coinsAndBalances: CoinsAndBalancesCapability<TState>;
+    keys: KeysCapability<TState>;
+}>;
+export declare class ShieldedWalletState<TSerialized = string, _TTransaction = ledger.FinalizedTransaction> {
+    #private;
+    /**
+     * Wraps a state emission with the capabilities of the variant that produced it.
+     *
+     * @remarks
+     *   Call this inside a branch that has narrowed on the emission's `variantTag`, so `variant` and `state` are known to
+     *   belong together. It is generic over the state type precisely so that pairing is checked.
+     */
+    static readonly fromVariant: <TState, TSerialized_1 = string>(variant: ShieldedStateCapabilities<TState, TSerialized_1>, state: ProtocolState.ProtocolState<TState>) => ShieldedWalletState<TSerialized_1>;
+    readonly protocolVersion: ProtocolVersion.ProtocolVersion;
+    readonly state: ShieldedCoreState;
+    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(protocolVersion: ProtocolVersion.ProtocolVersion, state: ShieldedCoreState, projections: ShieldedProjections<TSerialized>);
+    serialize(): TSerialized;
+}
+/**
+ * What balancing a transaction with shielded coins produces: a transaction covering the shortfall, when there is one.
+ *
+ * @remarks
+ *   A handle rather than a ledger transaction, because which ledger version built it is the variant's business and not
+ *   the caller's. Absent when the wallet had nothing to add — the transaction was already balanced on the shielded
+ *   side.
+ */
+export type ShieldedBalancingResult = UnprovenTx | undefined;
+export type ShieldedWalletAPI<TStartAux extends ledger.ZswapSecretKeys = ledger.ZswapSecretKeys, TTransaction = ledger.FinalizedTransaction, TSerialized = string> = {
+    readonly state: rx.Observable<ShieldedWalletState<TSerialized, TTransaction>>;
+    start(secretKeys: TStartAux): Promise<void>;
+    /**
+     * Balances a transaction with shielded coins.
+     *
+     * @remarks
+     *   No key material is passed: the wallet derives what its current variant needs from what it was started with. A
+     *   caller-supplied key object could only ever belong to one ledger version, which is exactly what a wallet spanning
+     *   a protocol boundary cannot assume.
+     */
+    balanceTransaction(tx: AnyTx): Promise<ShieldedBalancingResult>;
+    transferTransaction(outputs: readonly TokenTransfer[]): Promise<UnprovenTx>;
+    initSwap(desiredInputs: Record<ledger.RawTokenType, bigint>, desiredOutputs: readonly TokenTransfer[]): Promise<UnprovenTx>;
+    serializeState(): Promise<TSerialized>;
+    waitForSyncedState(allowedGap?: bigint): Promise<ShieldedWalletState<TSerialized, TTransaction>>;
+    getAddress(): Promise<ShieldedAddress>;
+    revertTransaction(transaction: AnyTx): Promise<void>;
+    stop(): Promise<void>;
+};
+/**
+ * The protocol version a ledger-v9-native chain hands over at.
+ *
+ * @deprecated Use {@link ProtocolVersion.V9NativeForkVersion} from `@midnightntwrk/wallet-sdk-abstractions` (or the
+ *   umbrella package) — the value is a property of the chain, not of the shielded wallet, and lives with the version
+ *   type now. This alias is the same value and will be removed in a later release.
+ */
+export declare const V9_NATIVE_FORK_VERSION: ProtocolVersion.ProtocolVersion;
+/**
+ * The configuration a default {@link ShieldedWallet} is built from.
+ *
+ * @remarks
+ *   Declared by this package rather than aliased to a variant's configuration. A wallet that spans a protocol boundary is
+ *   built from more than one variant, so no single variant's configuration can be the wallet's public contract: the
+ *   package states what it asks an application for, and maps it onto whichever variants it registers.
+ *
+ *   The field types are still the ones the variants declare, because they are version-agnostic — `configuration.test.ts`
+ *   asserts that this type remains interchangeable with what _both_ variants are built from, so a divergence surfaces
+ *   as a compile error here instead of as a wallet that cannot be built for one of its variants.
+ */
+export type DefaultShieldedConfiguration = {
+    networkId: NetworkId.NetworkId;
+    indexerClientConnection: IndexerClientConnection;
+    batchUpdates?: BatchUpdatesConfig;
+    txHistoryStorage: ShieldedHistoryStorage;
+    transactionDetailsRetryWindow?: Duration.DurationInput;
+    /**
+     * Where each ledger version begins on this chain: under `v9`, the protocol version at which it hands over from
+     * ledger-v8 to ledger-v9.
+     *
+     * @remarks
+     *   Required, and deliberately without a default: the wallet registers one variant either side of the boundary, so a
+     *   wrong value does not degrade — it decides which ledger version reads the chain. Below `forks.v9` the ledger-v8
+     *   variant is active; from it, the ledger-v9 one. The SDK cannot guess it, because it is a property of the chain the
+     *   application points at, not of the SDK.
+     *
+     *   A map keyed by ledger version rather than a single number, so the next hard fork adds a key instead of changing the
+     *   shape of every application's configuration — see {@link ProtocolVersion.ForkSchedule}. A node reporting a 2.x
+     *   runtime version reports protocol version `2000000`, which is therefore the value for a ledger-v9-native chain —
+     *   published as `ProtocolVersion.V9NativeForkVersion`. The final mainnet fork constant is not yet fixed; it will
+     *   join that one once it is, and this field keeps working unchanged.
+     */
+    forks: ProtocolVersion.ForkSchedule;
+    /**
+     * How the wallet asks the chain which protocol version its timeline starts under, before it chooses a variant to
+     * start at.
+     *
+     * @remarks
+     *   Optional, and defaulted rather than absent: left unset, the wallet asks the indexer named by
+     *   {@link indexerClientConnection}, which it is about to synchronize from anyway. Supply one to ask something else —
+     *   a cache, a node RPC, a value the application already holds — and have it answer the same question: the version of
+     *   the chain's **first** block, not its latest. A fresh wallet reads history from the start, so the variant it needs
+     *   is the one that can deserialize the first event it fetches; a probe reporting the tip of a chain that forked over
+     *   its own history starts the wallet on a ledger version that cannot read what it is about to be served.
+     *
+     *   The answer is best-effort wherever it comes from: a chain that cannot be reached leaves the wallet starting exactly
+     *   where it started before there was a probe.
+     */
+    chainVersionProbe?: ChainVersionProbe;
+};

package/dist/ShieldedWalletAPI.js

@@ -0,0 +1,75 @@
+// 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 '@midnightntwrk/wallet-sdk-abstractions';
+export class ShieldedWalletState {
+    /**
+     * Wraps a state emission with the capabilities of the variant that produced it.
+     *
+     * @remarks
+     *   Call this inside a branch that has narrowed on the emission's `variantTag`, so `variant` and `state` are known to
+     *   belong together. It is generic over the state type precisely so that pairing is checked.
+     */
+    static fromVariant = (variant, state) => new ShieldedWalletState(state.version, state.state, {
+        balances: () => variant.coinsAndBalances.getAvailableBalances(state.state),
+        totalCoins: () => variant.coinsAndBalances.getTotalCoins(state.state),
+        availableCoins: () => variant.coinsAndBalances.getAvailableCoins(state.state),
+        pendingCoins: () => variant.coinsAndBalances.getPendingCoins(state.state),
+        coinPublicKey: () => variant.keys.getCoinPublicKey(state.state),
+        encryptionPublicKey: () => variant.keys.getEncryptionPublicKey(state.state),
+        address: () => variant.keys.getAddress(state.state),
+        serialize: () => variant.serialization.serialize(state.state),
+    });
+    protocolVersion;
+    state;
+    #projections;
+    get balances() {
+        return this.#projections.balances();
+    }
+    get totalCoins() {
+        return this.#projections.totalCoins();
+    }
+    get availableCoins() {
+        return this.#projections.availableCoins();
+    }
+    get pendingCoins() {
+        return this.#projections.pendingCoins();
+    }
+    get coinPublicKey() {
+        return this.#projections.coinPublicKey();
+    }
+    get encryptionPublicKey() {
+        return this.#projections.encryptionPublicKey();
+    }
+    get address() {
+        return this.#projections.address();
+    }
+    get progress() {
+        return this.state.progress;
+    }
+    constructor(protocolVersion, state, projections) {
+        this.protocolVersion = protocolVersion;
+        this.state = state;
+        this.#projections = projections;
+    }
+    serialize() {
+        return this.#projections.serialize();
+    }
+}
+/**
+ * The protocol version a ledger-v9-native chain hands over at.
+ *
+ * @deprecated Use {@link ProtocolVersion.V9NativeForkVersion} from `@midnightntwrk/wallet-sdk-abstractions` (or the
+ *   umbrella package) — the value is a property of the chain, not of the shielded wallet, and lives with the version
+ *   type now. This alias is the same value and will be removed in a later release.
+ */
+export const V9_NATIVE_FORK_VERSION = ProtocolVersion.V9NativeForkVersion;

package/dist/SingleVariantShieldedWallet.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A shielded wallet composed from a single variant, which answers for the whole protocol timeline.
+ *
+ * @remarks
+ *   The composition for a wallet that is not expected to meet a protocol boundary — a test harness, a simulator-driven
+ *   wallet, an application pinned to one protocol version. Its one variant is registered from the minimum supported
+ *   version, so it stamps every transaction at that floor and accepts one of any version; the price is that it cannot
+ *   cross a protocol boundary. The wallet that can is `ShieldedWallet`, in `ShieldedWallet.ts`.
+ */
+import * as ledger from '@midnightntwrk/ledger-v9';
+import { type Variant, type VariantBuilder, type WalletLike } from '@midnightntwrk/wallet-sdk-runtime/abstractions';
+import { type DefaultShieldedConfiguration, type ShieldedWalletAPI } from './ShieldedWalletAPI.js';
+import { type BaseV2Configuration, type DefaultV2Configuration, type V2Variant } from './v2/index.js';
+import { type WalletSyncUpdate } from './v2/Sync.js';
+export type CustomizedShieldedWallet<TStartAux extends ledger.ZswapSecretKeys = ledger.ZswapSecretKeys, TTransaction = ledger.FinalizedTransaction, TSyncUpdate = WalletSyncUpdate, TSerialized = string> = ShieldedWalletAPI<TStartAux, TTransaction, TSerialized> & WalletLike.WalletLike<[Variant.VersionedVariant<V2Variant<TSerialized, TSyncUpdate, TTransaction, TStartAux>>]>;
+export interface CustomizedShieldedWalletClass<TStartAux extends ledger.ZswapSecretKeys = ledger.ZswapSecretKeys, TTransaction = ledger.FinalizedTransaction, TSyncUpdate = WalletSyncUpdate, TSerialized = string, TConfig extends BaseV2Configuration = DefaultShieldedConfiguration> extends WalletLike.BaseWalletClass<[
+    Variant.VersionedVariant<V2Variant<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>;
+}
+/**
+ * Builds a shielded wallet class over a single variant.
+ *
+ * @remarks
+ *   One variant, and therefore one ledger version: this is the composition for a wallet that is not expected to meet a
+ *   protocol boundary — a test harness, a simulator-driven wallet, an application pinned to one protocol version. The
+ *   wallet this package ships is `ShieldedWallet`, which registers a variant either side of the boundary.
+ * @param configuration What the variant is built from.
+ * @param builder The variant builder.
+ * @returns The wallet class.
+ */
+export declare function CustomShieldedWallet<TConfig extends BaseV2Configuration = DefaultV2Configuration, TStartAux extends ledger.ZswapSecretKeys = ledger.ZswapSecretKeys, TTransaction = ledger.FinalizedTransaction, TSyncUpdate = WalletSyncUpdate, TSerialized = string>(configuration: TConfig, builder: VariantBuilder.VariantBuilder<V2Variant<TSerialized, TSyncUpdate, TTransaction, TStartAux>, TConfig>): CustomizedShieldedWalletClass<TStartAux, TTransaction, TSyncUpdate, TSerialized, TConfig>;

package/dist/SingleVariantShieldedWallet.js

@@ -0,0 +1,240 @@
+// 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 shielded wallet composed from a single variant, which answers for the whole protocol timeline.
+ *
+ * @remarks
+ *   The composition for a wallet that is not expected to meet a protocol boundary — a test harness, a simulator-driven
+ *   wallet, an application pinned to one protocol version. Its one variant is registered from the minimum supported
+ *   version, so it stamps every transaction at that floor and accepts one of any version; the price is that it cannot
+ *   cross a protocol boundary. The wallet that can is `ShieldedWallet`, in `ShieldedWallet.ts`.
+ */
+import * as ledger from '@midnightntwrk/ledger-v9';
+import { ProtocolVersion, WalletSeed, WalletTransaction, } from '@midnightntwrk/wallet-sdk-abstractions';
+import { WalletBuilder } from '@midnightntwrk/wallet-sdk-runtime';
+import { StartMaterial, } from '@midnightntwrk/wallet-sdk-runtime/abstractions';
+import { EitherOps, HList, Poly } from '@midnightntwrk/wallet-sdk-utilities';
+import { Effect, Either, Option, Ref } from 'effect';
+import * as rx from 'rxjs';
+import { variantForSnapshot } from './Restore.js';
+import { ShieldedWalletState, } from './ShieldedWalletAPI.js';
+import { V2Tag, CoreWallet, } from './v2/index.js';
+/**
+ * Builds a shielded wallet class over a single variant.
+ *
+ * @remarks
+ *   One variant, and therefore one ledger version: this is the composition for a wallet that is not expected to meet a
+ *   protocol boundary — a test harness, a simulator-driven wallet, an application pinned to one protocol version. The
+ *   wallet this package ships is `ShieldedWallet`, which registers a variant either side of the boundary.
+ * @param configuration What the variant is built from.
+ * @param builder The variant builder.
+ * @returns The wallet class.
+ */
+export function CustomShieldedWallet(configuration, builder) {
+    const buildArgs = [configuration];
+    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));
+        }
+        /**
+         * Builds a wallet from a seed, and remembers the seed.
+         *
+         * @remarks
+         *   The seed is the only key material that crosses a protocol boundary, so a wallet built this way can start
+         *   synchronization on any variant it is ever migrated to — each derives its own from the seed. A wallet built from
+         *   key objects instead can only start the variants it was given objects for.
+         */
+        static startWithSeed(seed) {
+            const walletSeed = WalletSeed.WalletSeed(seed);
+            const secretKeys = ledger.ZswapSecretKeys.fromSeed(walletSeed);
+            const wallet = CustomShieldedWalletImplementation.startWithSecretKeys(secretKeys);
+            wallet.#retainSeed(walletSeed);
+            return wallet;
+        }
+        /**
+         * Restores a wallet from a snapshot, into whichever registered variant wrote it.
+         *
+         * @remarks
+         *   The snapshot declares the protocol version it was written at, so the variant that can read it is a lookup rather
+         *   than an assumption. A snapshot written before snapshots declared a version, or a serialization format this
+         *   wallet does not recognise as an envelope at all, restores into the head variant — which is what every restore
+         *   did before there was more than one variant to choose between.
+         * @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.
+         */
+        static restore(serializedState) {
+            const headVariant = HList.head(CustomShieldedWalletImplementation.allVariants());
+            const routed = 
+            // Routing reads a serialized envelope, which only a wallet keeping the default string serialization has. A
+            // custom format is left with the behaviour it has always had.
+            typeof serializedState === 'string'
+                ? variantForSnapshot(serializedState, (version) => CustomShieldedWalletImplementation.variantFor(version), headVariant)
+                : Either.right(headVariant);
+            const variant = routed.pipe(Either.getOrThrow);
+            const deserialized = variant.variant.deserializeState(serializedState).pipe(Either.getOrThrow);
+            return CustomShieldedWalletImplementation.startAtVariant(CustomShieldedWalletImplementation, variant, deserialized);
+        }
+        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 material cannot
+         *   come from the state — it is deliberately absent from anything serialized — and does not exist when the wallet
+         *   is first constructed, so it is held here, in memory, for the lifetime of the wallet. Cleared by {@link stop} so
+         *   a stopped wallet cannot be silently resurrected by a late activation.
+         *
+         *   A retained seed answers for every variant. Retained key objects answer only for the variants they were supplied
+         *   for, and accumulate per variant tag as `start` is called, which is the same product a caller holding key
+         *   objects for both protocol versions would hand over at once.
+         */
+        #retainedStartMaterial = Ref.unsafeMake(Option.none());
+        /** Remembers a seed, which supersedes any key objects retained for individual variants. */
+        #retainSeed(seed) {
+            Ref.set(this.#retainedStartMaterial, Option.some(StartMaterial.fromSeed(seed))).pipe(Effect.runSync);
+        }
+        /**
+         * Starts synchronization on a variant that has just become current, with key material it can use.
+         *
+         * @remarks
+         *   The derivation is the activating variant's own, so a wallet retaining a seed hands each variant key material
+         *   built by its own ledger version. A wallet retaining key objects for other variants only cannot answer, and says
+         *   so rather than handing over keys the variant would silently misuse.
+         */
+        #resumeSyncOn(variantTag, running) {
+            return Ref.get(this.#retainedStartMaterial).pipe(Effect.flatMap(Option.match({
+                // Stopped, or never started: there is nothing to resume and nothing to resume it with.
+                onNone: () => Effect.void,
+                onSome: (retained) => EitherOps.toEffect(StartMaterial.requireAuxFor(retained, variantTag, (seed) => CustomShieldedWalletImplementation.allVariantsRecord()[variantTag].variant.startAux.fromSeed(seed))).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((emission) => 
+            // One variant, so the pairing is trivial here; the forking wallet narrows on `variantTag` first.
+            ShieldedWalletState.fromVariant(CustomShieldedWalletImplementation.allVariantsRecord()[V2Tag].variant, emission)), rx.shareReplay({ refCount: true, bufferSize: 1 }));
+        }
+        start(secretKeys) {
+            return Effect.gen(this, function* () {
+                const current = yield* this.runtime.currentVariant;
+                yield* Ref.update(this.#retainedStartMaterial, (retained) => Option.some(Option.match(retained, {
+                    onNone: () => StartMaterial.forVariant(Poly.getTag(current), secretKeys),
+                    // A retained seed already answers for every variant, including ones this wallet has not met, so key
+                    // objects for one of them add nothing. Otherwise the objects accumulate per variant tag.
+                    onSome: (existing) => existing._tag === 'FromSeed'
+                        ? existing
+                        : StartMaterial.forVariants([...existing.byTag, [Poly.getTag(current), secretKeys]]),
+                })));
+                // Registered before the first dispatch, and only once: `onVariantActivation` resolves only after its
+                // subscription is live, so an activation racing this call is queued rather than missed.
+                const alreadyRegistered = yield* Ref.getAndSet(this.#watcherRegistered, true);
+                if (!alreadyRegistered) {
+                    yield* this.runtime.onVariantActivation({
+                        [V2Tag]: (v2) => this.#resumeSyncOn(V2Tag, v2),
+                    });
+                }
+                yield* this.runtime.dispatch({ [V2Tag]: (v2) => v2.startSyncInBackground(secretKeys) });
+            }).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.#retainedStartMaterial, Option.none()).pipe(Effect.runSync);
+            await super.stop();
+        }
+        /**
+         * The key material this wallet's one variant uses, from what it was started with.
+         *
+         * @remarks
+         *   Typed as the variant's own start-aux, which for a single-variant wallet is whatever the application handed to
+         *   `start` — there is no other variant to derive for, so a retained seed is only ever used through the variant's
+         *   own derivation.
+         */
+        #requireAux() {
+            return Effect.gen(this, function* () {
+                const current = yield* this.runtime.currentVariant;
+                const variantTag = Poly.getTag(current);
+                const retained = yield* Ref.get(this.#retainedStartMaterial);
+                return yield* Option.match(retained, {
+                    onNone: () => Effect.fail(new StartMaterial.MissingStartAuxError({
+                        message: `This wallet holds no key material: it has not been started, or it has been stopped. Start it ` +
+                            `before asking it to build a transaction.`,
+                        variantTag,
+                    })),
+                    onSome: (material) => EitherOps.toEffect(StartMaterial.requireAuxFor(material, variantTag, (seed) => CustomShieldedWalletImplementation.allVariantsRecord()[V2Tag].variant.startAux.fromSeed(seed))),
+                });
+            });
+        }
+        /** The whole of the protocol timeline: one variant answers for every version this wallet will ever see. */
+        static #epoch = ProtocolVersion.epochOf(ProtocolVersion.MinSupportedVersion, ProtocolVersion.MinSupportedVersion);
+        balanceTransaction(tx) {
+            return this.runtime
+                .dispatch({
+                [V2Tag]: (v2) => Effect.all([
+                    this.#requireAux(),
+                    EitherOps.toEffect(WalletTransaction.unwrapWithin(tx, CustomShieldedWalletImplementation.#epoch)),
+                ]).pipe(Effect.flatMap(([keys, unwrapped]) => v2.balanceTransaction(keys, unwrapped)), Effect.map((result) => result === undefined
+                    ? undefined
+                    : WalletTransaction.adopt('Unproven', result, ProtocolVersion.MinSupportedVersion))),
+            })
+                .pipe(Effect.runPromise);
+        }
+        transferTransaction(outputs) {
+            return this.runtime
+                .dispatch({
+                [V2Tag]: (v2) => this.#requireAux().pipe(Effect.flatMap((keys) => v2.transferTransaction(keys, outputs)), Effect.map((tx) => WalletTransaction.adopt('Unproven', tx, ProtocolVersion.MinSupportedVersion))),
+            })
+                .pipe(Effect.runPromise);
+        }
+        initSwap(desiredInputs, desiredOutputs) {
+            return this.runtime
+                .dispatch({
+                [V2Tag]: (v2) => this.#requireAux().pipe(Effect.flatMap((keys) => v2.initSwap(keys, desiredInputs, desiredOutputs)), Effect.map((tx) => WalletTransaction.adopt('Unproven', tx, ProtocolVersion.MinSupportedVersion))),
+            })
+                .pipe(Effect.runPromise);
+        }
+        revertTransaction(transaction) {
+            return this.runtime
+                .dispatch({
+                [V2Tag]: (v2) => Either.match(WalletTransaction.unwrapWithin(transaction, CustomShieldedWalletImplementation.#epoch), { onLeft: () => Effect.void, onRight: (unwrapped) => v2.revertTransaction(unwrapped) }),
+            })
+                .pipe(Effect.runPromise);
+        }
+        waitForSyncedState(allowedGap = 0n) {
+            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
+         */
+        serializeState() {
+            return rx.firstValueFrom(this.state).then((state) => state.serialize());
+        }
+        getAddress() {
+            return rx.firstValueFrom(this.state).then((state) => state.address);
+        }
+    };
+}

package/dist/index.d.ts

@@ -1,2 +1,5 @@
+export * from './ShieldedWalletAPI.js';
+export * from './SingleVariantShieldedWallet.js';
 export * from './ShieldedWallet.js';
-export { type ShieldedTransactionHistoryEntry, ShieldedSectionSchema, mergeShieldedSections, } from './v1/TransactionHistory.js';
+export * as Restore from './Restore.js';
+export { type ShieldedTransactionHistoryEntry, ShieldedSectionSchema, mergeShieldedSections, } from './v2/TransactionHistory.js';

package/dist/index.js

@@ -10,5 +10,8 @@
 // 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 * from './ShieldedWalletAPI.js';
+export * from './SingleVariantShieldedWallet.js';
 export * from './ShieldedWallet.js';
-export { ShieldedSectionSchema, mergeShieldedSections, } from './v1/TransactionHistory.js';
+export * as Restore from './Restore.js';
+export { ShieldedSectionSchema, mergeShieldedSections, } from './v2/TransactionHistory.js';

package/dist/v1/CoinsAndBalances.d.ts

@@ -1,5 +1,5 @@
 import { type CoreWallet } from './CoreWallet.js';
-import type * as ledger from '@midnightntwrk/ledger-v9';
+import type * as ledger from '@midnight-ntwrk/ledger-v8';
 export type AvailableCoin = {
     coin: ledger.QualifiedShieldedCoinInfo;
     commitment: ledger.CoinCommitment;

package/dist/v1/CoreWallet.d.ts

@@ -1,4 +1,4 @@
-import * as ledger from '@midnightntwrk/ledger-v9';
+import * as ledger from '@midnight-ntwrk/ledger-v8';
 import { ProtocolVersion, SyncProgress } from '@midnightntwrk/wallet-sdk-abstractions';
 import { Either } from 'effect';
 import { type WalletError } from './WalletError.js';
@@ -35,6 +35,53 @@ export declare const CoreWallet: {
     restore(localState: ledger.ZswapLocalState, secretKeys: ledger.ZswapSecretKeys, syncProgress: Omit<SyncProgress.SyncProgressData, "isConnected">, protocolVersion: bigint, networkId: string): CoreWallet;
     restoreWithCoinHashes(publicKeys: PublicKeys, localState: ledger.ZswapLocalState, coinHashes: CoinHashesMap, syncProgress: SyncProgress.SyncProgressData, protocolVersion: bigint, networkId: string): Either.Either<CoreWallet, WalletError>;
     initEmpty(keys: ledger.ZswapSecretKeys, networkId: string): CoreWallet;
+    /**
+     * Records an observed protocol version on the wallet, never going backwards.
+     *
+     * @remarks
+     *   The version is a signal, not a measurement: writing one outside the running variant's activation range is what
+     *   makes it hand over to the next variant. A source that briefly reports an older version — a reconnect replaying
+     *   from an earlier cursor, say — must therefore not be able to drag the wallet back below a boundary it has already
+     *   crossed, which would ask the runtime to migrate backwards. Taking the maximum makes that unrepresentable.
+     * @param wallet The wallet to annotate.
+     * @param version The protocol version just observed.
+     * @returns `wallet` unchanged if it already records `version` or a later one, otherwise a copy recording `version`.
+     */
+    withProtocolVersion(wallet: CoreWallet, version: ProtocolVersion.ProtocolVersion): CoreWallet;
+    /**
+     * Projects a wallet inherited from the previous ledger version onto a fresh state of this one.
+     *
+     * @remarks
+     *   No coin data crosses the boundary here, and that is a decision rather than an oversight. This is the oldest variant
+     *   the wallet registers and no ledger version below it exists, so nothing ever hands a state to this projection: it
+     *   is shape parity with the twin at `src/v2`, which is the variant a real crossing lands in. That twin adopts the
+     *   previous wallet's local state whole, by deserializing its bytes — the two ledger majors share the
+     *   `zswap-local-state` codec — because the chain's state translation continues the commitment tree across the fork
+     *   and the indexer re-emits none of the ledger-v8 timeline (see `src/v2/Migration.ts`). Mirroring that into a seam
+     *   no chain can reach would buy nothing, so this side stays as it is.
+     *
+     *   What crosses is therefore identity and position: the public keys — which decide whose coins the far side can
+     *   decrypt — the network, the protocol version that triggered the hand-over, kept so the new variant starts inside
+     *   its own activation range rather than immediately signalling backwards, and the cursor the previous variant
+     *   stopped at.
+     *
+     *   **Sync progress is parked at the fork, not rewound**: the previous wallet's cursor crosses unchanged. A fork does
+     *   not restart the timeline — event ids run onwards from whatever the indexer had reached when it happened, never
+     *   from zero — so resuming from the inherited cursor is what puts this wallet in front of what comes next. Rewinding
+     *   to zero would park it on a stretch of history that this ledger version's events do not occupy. What does not
+     *   cross is `isConnected`: no sync is running behind this state yet.
+     *
+     *   Coin hashes start empty for the same reason the tree does: they are commitments and nullifiers computed under the
+     *   previous ledger's codec, and this version recomputes its own from the keys and whatever state it ends up with.
+     * @param previous The plain data read off the previous ledger version's wallet.
+     * @returns A wallet of this ledger version holding no coins, positioned at the fork.
+     */
+    fromPreviousVersion(previous: {
+        readonly publicKeys: PublicKeys;
+        readonly networkId: string;
+        readonly protocolVersion: bigint;
+        readonly progress: SyncProgress.SyncProgressData;
+    }): CoreWallet;
     applyCollapsedUpdate(wallet: CoreWallet, collapsed: ledger.MerkleTreeCollapsedUpdate): CoreWallet;
     apply<TOffer extends ledger.ZswapOffer<ledger.Proofish>>(wallet: CoreWallet, secretKeys: ledger.ZswapSecretKeys, offer: TOffer): CoreWallet;
     replayEventsWithChanges(wallet: CoreWallet, secretKeys: ledger.ZswapSecretKeys, events: ledger.Event[]): [CoreWallet, ledger.ZswapStateChanges[]];