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

package/dist/v2/V2Builder.d.ts

@@ -0,0 +1,154 @@
+import * as ledger from '@midnightntwrk/ledger-v9';
+import { type Either, type Types } from 'effect';
+import { type NetworkId } from '@midnightntwrk/wallet-sdk-abstractions';
+import { type Variant, type VariantBuilder, type StartMaterial } from '@midnightntwrk/wallet-sdk-runtime/abstractions';
+import { type StateMigration } from './Migration.js';
+import { RunningV2Variant, V2Tag } from './RunningV2Variant.js';
+import { type SerializationCapability } from './Serialization.js';
+import { type DefaultSyncContext, type DefaultSyncConfiguration, type ChangesResult, type SyncCapability, type SyncService, type WalletSyncUpdate } from './Sync.js';
+import { type DefaultTransactingConfiguration, type DefaultTransactingContext, type TransactingCapability } from './Transacting.js';
+import { type WalletError } from './WalletError.js';
+import { type CoinsAndBalancesCapability } from './CoinsAndBalances.js';
+import { type KeysCapability } from './Keys.js';
+import { type CoinSelection } from '@midnightntwrk/wallet-sdk-capabilities';
+import { type CoreWallet } from './CoreWallet.js';
+import { type DefaultTransactionHistoryConfiguration, type TransactionHistoryService } from './TransactionHistory.js';
+export type BaseV2Configuration = {
+    networkId: NetworkId.NetworkId;
+};
+export type DefaultV2Configuration = BaseV2Configuration & DefaultSyncConfiguration & DefaultTransactingConfiguration & DefaultTransactionHistoryConfiguration;
+declare const V2BuilderSymbol: {
+    readonly typeId: unique symbol;
+};
+export type V2Variant<TSerialized, TSyncUpdate, TTransaction, TAuxData, TPreviousState = null> = Variant.Variant<typeof V2Tag, CoreWallet, TPreviousState, RunningV2Variant<TSerialized, TSyncUpdate, TTransaction, TAuxData>> & {
+    deserializeState: (serialized: TSerialized) => Either.Either<CoreWallet, WalletError>;
+    coinsAndBalances: CoinsAndBalancesCapability<CoreWallet>;
+    keys: KeysCapability<CoreWallet>;
+    serialization: SerializationCapability<CoreWallet, null, TSerialized>;
+    transactionHistory: TransactionHistoryService;
+    startAux: StartMaterial.StartAuxCapability<TAuxData>;
+};
+export type AnyV2Variant = V2Variant<any, any, any, any>;
+export type DefaultV2Variant = V2Variant<string, WalletSyncUpdate, ledger.FinalizedTransaction, ledger.ZswapSecretKeys>;
+export type TransactionOf<T extends AnyV2Variant> = T extends V2Variant<any, any, infer TTransaction, any> ? TTransaction : never;
+export type AuxDataOf<T extends AnyV2Variant> = T extends V2Variant<any, any, any, infer TAuxData> ? TAuxData : never;
+export type SerializedStateOf<T extends AnyV2Variant> = T extends V2Variant<infer TSerialized, any, any, any> ? TSerialized : never;
+export type DefaultV2Builder<TPreviousState = null> = V2Builder<DefaultV2Configuration, RunningV2Variant.Context<string, WalletSyncUpdate, ledger.FinalizedTransaction, ledger.ZswapSecretKeys>, string, WalletSyncUpdate, ledger.FinalizedTransaction, ledger.ZswapSecretKeys, TPreviousState>;
+export declare class V2Builder<TConfig extends BaseV2Configuration = BaseV2Configuration, TContext extends Partial<RunningV2Variant.AnyContext> = object, TSerialized = never, TSyncUpdate = never, TTransaction = never, TStartAux extends object = object, TPreviousState = null> implements VariantBuilder.VariantBuilder<V2Variant<TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>, TConfig> {
+    #private;
+    constructor(buildState?: V2Builder.PartialBuildState<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>);
+    withDefaults(this: V2Builder<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, null>): DefaultV2Builder;
+    withTransactionType<Transaction>(): V2Builder<TConfig, TContext, TSerialized, TSyncUpdate, Transaction, TStartAux, TPreviousState>;
+    withDefaultTransactionType(): V2Builder<TConfig, TContext, TSerialized, TSyncUpdate, ledger.FinalizedTransaction, TStartAux, TPreviousState>;
+    withSyncDefaults(): V2Builder<TConfig & DefaultSyncConfiguration, TContext & DefaultSyncContext, TSerialized, WalletSyncUpdate, TTransaction, ledger.ZswapSecretKeys, TPreviousState>;
+    withSync<TSyncConfig, TSyncContext extends Partial<RunningV2Variant.AnyContext>, TSyncUpdate, TStartAux extends object>(syncService: (configuration: TSyncConfig, getContext: () => TSyncContext) => SyncService<CoreWallet, TStartAux, TSyncUpdate>, syncCapability: (configuration: TSyncConfig, getContext: () => TSyncContext) => SyncCapability<CoreWallet, TSyncUpdate, ChangesResult>): V2Builder<TConfig & TSyncConfig, TContext & TSyncContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    withSerializationDefaults(): V2Builder<TConfig, TContext, string, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    withSerialization<TSerializationConfig, TSerializationContext extends Partial<RunningV2Variant.AnyContext>, TSerialized>(serializationCapability: (configuration: TSerializationConfig, getContext: () => TSerializationContext) => SerializationCapability<CoreWallet, null, TSerialized>): V2Builder<TConfig & TSerializationConfig, TContext & TSerializationContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    withTransactingDefaults(this: V2Builder<TConfig, TContext, TSerialized, TSyncUpdate, ledger.FinalizedTransaction, TStartAux, TPreviousState>): V2Builder<TConfig & DefaultTransactingConfiguration, TContext & DefaultTransactingContext, TSerialized, TSyncUpdate, ledger.FinalizedTransaction, TStartAux, TPreviousState>;
+    withTransacting<TTransactingConfig, TTransactingContext extends Partial<RunningV2Variant.AnyContext>>(transactingCapability: (config: TTransactingConfig, getContext: () => TTransactingContext) => TransactingCapability<ledger.ZswapSecretKeys, CoreWallet, TTransaction>): V2Builder<TConfig & TTransactingConfig, TContext & TTransactingContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    withCoinSelection<TCoinSelectionConfig, TCoinSelectionContext extends Partial<RunningV2Variant.AnyContext>>(coinSelection: (config: TCoinSelectionConfig, getContext: () => TCoinSelectionContext) => CoinSelection<ledger.QualifiedShieldedCoinInfo>): V2Builder<TConfig & TCoinSelectionConfig, TContext & TCoinSelectionContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    withCoinSelectionDefaults(): V2Builder<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    withCoinsAndBalancesDefaults(): V2Builder<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    withCoinsAndBalances<TBalancesConfig, TBalancesContext extends Partial<RunningV2Variant.AnyContext>>(coinsAndBalancesCapability: (configuration: TBalancesConfig, getContext: () => TBalancesContext) => CoinsAndBalancesCapability<CoreWallet>): V2Builder<TConfig & TBalancesConfig, TContext & TBalancesContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    withTransactionHistoryDefaults(this: V2Builder<TConfig, TContext, TSerialized, TSyncUpdate, ledger.FinalizedTransaction, TStartAux, TPreviousState>): V2Builder<TConfig & DefaultTransactionHistoryConfiguration, TContext, TSerialized, TSyncUpdate, ledger.FinalizedTransaction, TStartAux, TPreviousState>;
+    withTransactionHistory<TTransactionHistoryConfig, TTransactionHistoryContext extends Partial<RunningV2Variant.AnyContext>>(transactionHistoryService: (configuration: TTransactionHistoryConfig, getContext: () => TTransactionHistoryContext) => TransactionHistoryService): V2Builder<TConfig & TTransactionHistoryConfig, TContext & TTransactionHistoryContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    withKeysDefaults(): V2Builder<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    /**
+     * Uses the default start-aux derivation: this ledger version's Zswap secret keys, derived from the seed.
+     *
+     * @remarks
+     *   The seed is the only key material that crosses a protocol boundary, so every variant must be able to produce its
+     *   own from one. This is that derivation for this ledger version; a builder whose sync service expects something
+     *   else supplies its own with {@link V2Builder.withStartAux}.
+     */
+    withStartAuxDefaults(this: V2Builder<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, ledger.ZswapSecretKeys, TPreviousState>): V2Builder<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, ledger.ZswapSecretKeys, TPreviousState>;
+    /**
+     * Chooses how this variant derives the key material its synchronization is started with from a seed.
+     *
+     * @param startAux The derivation.
+     * @returns A builder that produces a variant able to start sync from a seed alone.
+     */
+    withStartAux(startAux: StartMaterial.StartAuxCapability<TStartAux>): V2Builder<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    /**
+     * Uses the default migration: an empty wallet built from nothing.
+     *
+     * @remarks
+     *   This is what an unconfigured builder already does, so calling it changes no behaviour — it states the choice rather
+     *   than inheriting it. Registering this variant as the target of a real fork means calling
+     *   {@link V2Builder.withMigration} with {@link makeCrossLedgerMigration} instead.
+     */
+    withMigrationDefaults(this: V2Builder<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, null>): V2Builder<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, null>;
+    /**
+     * Chooses how this variant produces its first state from the state that preceded it.
+     *
+     * @remarks
+     *   The strategy's input type becomes the variant's `TPreviousState`, which is what the runtime type-checks a
+     *   registration against: a variant declaring it migrates from a ledger-v8 wallet cannot be registered after one that
+     *   produces something else.
+     * @example
+     *   ```typescript
+     *   const forkTarget = new V2Builder().withDefaults().withMigration(makeCrossLedgerMigration);
+     *   ```;
+     *
+     * @param migration Builds the migration from the configuration and the sibling capabilities.
+     */
+    withMigration<TMigrationConfig, TPrevious>(migration: (configuration: TMigrationConfig, getContext: () => TContext) => StateMigration<TPrevious>): V2Builder<TConfig & TMigrationConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPrevious>;
+    withKeys<TKeysConfig, TKeysContext extends Partial<RunningV2Variant.AnyContext>>(keysCapability: (configuration: TKeysConfig, getContext: () => TKeysContext) => KeysCapability<CoreWallet>): V2Builder<TConfig & TKeysConfig, TContext & TKeysContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    build(this: V2Builder<TConfig, RunningV2Variant.Context<TSerialized, TSyncUpdate, TTransaction, TStartAux>, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>, configuration: TConfig): V2Variant<TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+}
+/** @internal */
+declare namespace V2Builder {
+    type HasSync<TConfig, TContext, TSyncUpdate, TStartAux> = {
+        readonly syncService: (configuration: TConfig, getContext: () => TContext) => SyncService<CoreWallet, TStartAux, TSyncUpdate>;
+        readonly syncCapability: (configuration: TConfig, getContext: () => TContext) => SyncCapability<CoreWallet, TSyncUpdate, ChangesResult>;
+    };
+    type HasTransacting<TConfig, TContext, TTransaction> = {
+        readonly transactingCapability: (configuration: TConfig, getContext: () => TContext) => TransactingCapability<ledger.ZswapSecretKeys, CoreWallet, TTransaction>;
+    };
+    type HasCoinSelection<TConfig, TContext> = {
+        readonly coinSelection: (configuration: TConfig, getContext: () => TContext) => CoinSelection<ledger.QualifiedShieldedCoinInfo>;
+    };
+    type HasSerialization<TConfig, TContext, TSerialized> = {
+        readonly serializationCapability: (configuration: TConfig, getContext: () => TContext) => SerializationCapability<CoreWallet, null, TSerialized>;
+    };
+    type HasCoinsAndBalances<TConfig, TContext> = {
+        readonly coinsAndBalancesCapability: (configuration: TConfig, getContext: () => TContext) => CoinsAndBalancesCapability<CoreWallet>;
+    };
+    type HasTransactionHistory<TConfig, TContext> = {
+        readonly transactionHistoryService: (configuration: TConfig, getContext: () => TContext) => TransactionHistoryService;
+    };
+    type HasKeys<TConfig, TContext> = {
+        readonly keysCapability: (configuration: TConfig, getContext: () => TContext) => KeysCapability<CoreWallet>;
+    };
+    /** The internal build state of {@link V2Builder}. */
+    type FullBuildState<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux> = Types.Simplify<HasSync<TConfig, TContext, TSyncUpdate, TStartAux> & HasSerialization<TConfig, TContext, TSerialized> & HasTransacting<TConfig, TContext, TTransaction> & HasCoinSelection<TConfig, TContext> & HasCoinsAndBalances<TConfig, TContext> & HasKeys<TConfig, TContext> & HasTransactionHistory<TConfig, TContext>>;
+    /**
+     * The migration entry, kept out of {@link FullBuildState} on purpose: absent means "empty wallet", which is the
+     * behaviour every builder had before migrations were configurable, so a builder that never mentions migration must
+     * still be considered complete.
+     */
+    /**
+     * The start-aux entry, kept out of {@link FullBuildState} because it is not one of the context-producing capabilities:
+     * it takes neither configuration nor sibling capabilities, only a seed.
+     */
+    type HasStartAux<TStartAux> = {
+        readonly startAux: StartMaterial.StartAuxCapability<TStartAux>;
+    };
+    type HasMigration<TConfig, TContext, TPreviousState> = {
+        readonly migration: (configuration: TConfig, getContext: () => TContext) => StateMigration<TPreviousState>;
+    };
+    /** The capability half of the build state — everything that does not depend on the previous-state parameter. */
+    type CapabilityBuildState<TConfig = object, TContext = object, TSerialized = never, TSyncUpdate = never, TTransaction = never, TStartAux = object> = {
+        [K in keyof FullBuildState<never, never, never, never, never, never>]?: FullBuildState<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>[K] | undefined;
+    };
+    type PartialBuildState<TConfig = object, TContext = object, TSerialized = never, TSyncUpdate = never, TTransaction = never, TStartAux = object, TPreviousState = null> = {
+        [K in keyof (FullBuildState<never, never, never, never, never, never> & HasMigration<never, never, never> & HasStartAux<never>)]?: (FullBuildState<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux> & HasMigration<TConfig, TContext, TPreviousState> & HasStartAux<TStartAux>)[K] | undefined;
+    };
+    /** Utility interface that manages the type variance of {@link V2Builder}. */
+    interface Variance<R> {
+        readonly [V2BuilderSymbol.typeId]: {
+            readonly _R: Types.Covariant<R>;
+        };
+    }
+}
+export {};

package/dist/v2/V2Builder.js

@@ -0,0 +1,273 @@
+// 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 * as ledger from '@midnightntwrk/ledger-v9';
+import { Effect, Scope } from 'effect';
+import { WalletRuntimeError, } from '@midnightntwrk/wallet-sdk-runtime/abstractions';
+import { makeEmptyWalletMigration } from './Migration.js';
+import { RunningV2Variant, V2Tag } from './RunningV2Variant.js';
+import { makeDefaultV2SerializationCapability } from './Serialization.js';
+import { makeEventsSyncService, makeEventsSyncCapability, } from './Sync.js';
+import { makeDefaultTransactingCapability, } from './Transacting.js';
+import { makeDefaultCoinsAndBalancesCapability } from './CoinsAndBalances.js';
+import { makeDefaultKeysCapability } from './Keys.js';
+import { chooseCoin } from '@midnightntwrk/wallet-sdk-capabilities';
+import { makeDefaultTransactionHistoryService, } from './TransactionHistory.js';
+const V2BuilderSymbol = {
+    typeId: Symbol('@midnight-ntwrk/wallet#V2Builder'),
+};
+export class V2Builder {
+    #buildState;
+    constructor(buildState = {}) {
+        this.#buildState = buildState;
+    }
+    withDefaults() {
+        return this.withDefaultTransactionType()
+            .withSyncDefaults()
+            .withSerializationDefaults()
+            .withTransactingDefaults()
+            .withCoinsAndBalancesDefaults()
+            .withTransactionHistoryDefaults()
+            .withKeysDefaults()
+            .withStartAuxDefaults()
+            // Type cast required because: the chain accumulates `TContext` as an intersection of the individual
+            // `Default*Context` fragments, which is a structurally weaker type than the complete
+            // `RunningV2Variant.Context` that `DefaultV2Builder` names — the defaults do produce a full context, but the
+            // chain's type cannot express that. Routing through `unknown` because the added `migration` key put the two
+            // sides past what TypeScript will accept as directly comparable; the widening itself predates it.
+            .withCoinSelectionDefaults();
+    }
+    withTransactionType() {
+        return new V2Builder({
+            ...this.#buildState,
+            transactingCapability: undefined,
+            transactionHistoryService: undefined,
+        });
+    }
+    withDefaultTransactionType() {
+        return this.withTransactionType();
+    }
+    withSyncDefaults() {
+        return this.withSync(makeEventsSyncService, makeEventsSyncCapability);
+    }
+    withSync(syncService, syncCapability) {
+        return new V2Builder({
+            ...this.#buildState,
+            syncService,
+            syncCapability,
+            // The derivation is typed against the *old* start-aux parameter, so it cannot ride along into a builder whose
+            // sync service expects something else — exactly as the migration cannot ride along through `withMigration`.
+            startAux: undefined,
+        });
+    }
+    withSerializationDefaults() {
+        return this.withSerialization(makeDefaultV2SerializationCapability);
+    }
+    withSerialization(serializationCapability) {
+        return new V2Builder({
+            ...this.#buildState,
+            serializationCapability,
+        });
+    }
+    withTransactingDefaults() {
+        return this.withTransacting(makeDefaultTransactingCapability);
+    }
+    withTransacting(transactingCapability) {
+        return new V2Builder({
+            ...this.#buildState,
+            transactingCapability,
+        });
+    }
+    withCoinSelection(coinSelection) {
+        return new V2Builder({
+            ...this.#buildState,
+            coinSelection,
+        });
+    }
+    withCoinSelectionDefaults() {
+        return this.withCoinSelection(() => chooseCoin);
+    }
+    withCoinsAndBalancesDefaults() {
+        return this.withCoinsAndBalances(makeDefaultCoinsAndBalancesCapability);
+    }
+    withCoinsAndBalances(coinsAndBalancesCapability) {
+        return new V2Builder({
+            ...this.#buildState,
+            coinsAndBalancesCapability,
+        });
+    }
+    withTransactionHistoryDefaults() {
+        return this.withTransactionHistory(makeDefaultTransactionHistoryService);
+    }
+    withTransactionHistory(transactionHistoryService) {
+        return new V2Builder({
+            ...this.#buildState,
+            transactionHistoryService,
+        });
+    }
+    withKeysDefaults() {
+        return this.withKeys(makeDefaultKeysCapability);
+    }
+    /**
+     * Uses the default start-aux derivation: this ledger version's Zswap secret keys, derived from the seed.
+     *
+     * @remarks
+     *   The seed is the only key material that crosses a protocol boundary, so every variant must be able to produce its
+     *   own from one. This is that derivation for this ledger version; a builder whose sync service expects something
+     *   else supplies its own with {@link V2Builder.withStartAux}.
+     */
+    withStartAuxDefaults() {
+        return this.withStartAux({ fromSeed: (seed) => ledger.ZswapSecretKeys.fromSeed(seed) });
+    }
+    /**
+     * Chooses how this variant derives the key material its synchronization is started with from a seed.
+     *
+     * @param startAux The derivation.
+     * @returns A builder that produces a variant able to start sync from a seed alone.
+     */
+    withStartAux(startAux) {
+        return new V2Builder({
+            ...this.#buildState,
+            startAux,
+        });
+    }
+    /**
+     * Uses the default migration: an empty wallet built from nothing.
+     *
+     * @remarks
+     *   This is what an unconfigured builder already does, so calling it changes no behaviour — it states the choice rather
+     *   than inheriting it. Registering this variant as the target of a real fork means calling
+     *   {@link V2Builder.withMigration} with {@link makeCrossLedgerMigration} instead.
+     */
+    withMigrationDefaults() {
+        return this.withMigration((configuration) => makeEmptyWalletMigration(configuration));
+    }
+    /**
+     * Chooses how this variant produces its first state from the state that preceded it.
+     *
+     * @remarks
+     *   The strategy's input type becomes the variant's `TPreviousState`, which is what the runtime type-checks a
+     *   registration against: a variant declaring it migrates from a ledger-v8 wallet cannot be registered after one that
+     *   produces something else.
+     * @example
+     *   ```typescript
+     *   const forkTarget = new V2Builder().withDefaults().withMigration(makeCrossLedgerMigration);
+     *   ```;
+     *
+     * @param migration Builds the migration from the configuration and the sibling capabilities.
+     */
+    withMigration(migration) {
+        const capabilities = this.#buildState;
+        return new V2Builder({
+            // Only the capability half crosses: the strategy being replaced is typed against the *old* previous-state
+            // parameter, so it cannot ride along even though it is about to be overwritten.
+            ...capabilities,
+            migration,
+        });
+    }
+    withKeys(keysCapability) {
+        return new V2Builder({
+            ...this.#buildState,
+            keysCapability,
+        });
+    }
+    build(configuration) {
+        const v2Context = this.#buildContextFromBuildState(configuration);
+        const migration = this.#resolveMigration(configuration, () => v2Context);
+        return {
+            __polyTag__: V2Tag,
+            coinsAndBalances: v2Context.coinsAndBalancesCapability,
+            keys: v2Context.keysCapability,
+            serialization: v2Context.serializationCapability,
+            transactionHistory: v2Context.transactionHistoryService,
+            startAux: this.#resolveStartAux(),
+            start(context) {
+                return Effect.gen(function* () {
+                    const scope = yield* Scope.Scope;
+                    return new RunningV2Variant(scope, context, v2Context);
+                });
+            },
+            // An unconfigured builder keeps producing an empty wallet, which is what `startEmpty` has always relied on.
+            // Anything else — carrying state within a ledger version, or projecting it across one — is the injected
+            // strategy's business, and its failures are reported on the runtime's state stream rather than thrown.
+            migrateState: (previousState) => migration.migrate(previousState).pipe(Effect.mapError((error) => new WalletRuntimeError({
+                message: 'Failed to migrate shielded wallet state into this variant',
+                cause: error,
+            }))),
+            deserializeState: (serialized) => {
+                return v2Context.serializationCapability.deserialize(null, serialized);
+            },
+        };
+    }
+    /**
+     * Resolves the configured migration, or the empty-wallet fallback when none was configured.
+     *
+     * @remarks
+     *   The fallback is written as a nullary function on purpose. It ignores whatever preceded it — it builds an empty
+     *   wallet from nothing — which makes it a valid migration from _any_ previous state, but a `StateMigration<null>`
+     *   value could only be widened to `StateMigration<TPreviousState>` through a cast. Declaring no parameter says the
+     *   same thing to the type system without one.
+     */
+    /**
+     * Resolves the configured start-aux derivation.
+     *
+     * @remarks
+     *   Unlike the migration there is no sensible fallback: the default derivation produces this ledger version's secret
+     *   keys, which is only correct for a builder that kept a sync service expecting them. A builder that replaced sync
+     *   and did not say how to derive its own key material is misconfigured, and is told so at build time rather than
+     *   silently handed key objects of the wrong shape at the first migration.
+     */
+    #resolveStartAux() {
+        const configured = this.#buildState.startAux;
+        if (configured === undefined) {
+            throw new Error('Not all components are configured in V2 Builder: startAux');
+        }
+        return configured;
+    }
+    #resolveMigration(configuration, getContext) {
+        const configured = this.#buildState.migration;
+        return configured === undefined
+            ? { migrate: () => makeEmptyWalletMigration(configuration).migrate(null) }
+            : configured(configuration, getContext);
+    }
+    #buildContextFromBuildState(configuration) {
+        if (!isBuildStateFull(this.#buildState)) {
+            throw new Error('Not all components are configured in V2 Builder');
+        }
+        const { syncCapability, syncService, transactingCapability, serializationCapability, coinSelection, coinsAndBalancesCapability, keysCapability, transactionHistoryService, } = this.#buildState;
+        const getContext = () => context;
+        const context = {
+            serializationCapability: serializationCapability(configuration, getContext),
+            syncCapability: syncCapability(configuration, getContext),
+            syncService: syncService(configuration, getContext),
+            transactingCapability: transactingCapability(configuration, getContext),
+            coinsAndBalancesCapability: coinsAndBalancesCapability(configuration, getContext),
+            keysCapability: keysCapability(configuration, getContext),
+            coinSelection: coinSelection(configuration, getContext),
+            transactionHistoryService: transactionHistoryService(configuration, getContext),
+        };
+        return context;
+    }
+}
+const isBuildStateFull = (buildState) => {
+    const allBuildStateKeys = [
+        'syncService',
+        'syncCapability',
+        'transactingCapability',
+        'coinSelection',
+        'serializationCapability',
+        'coinsAndBalancesCapability',
+        'keysCapability',
+        'transactionHistoryService',
+    ];
+    return allBuildStateKeys.every((key) => typeof buildState[key] == 'function');
+};

package/dist/v2/WalletError.d.ts

@@ -0,0 +1,74 @@
+import type * as ledger from '@midnightntwrk/ledger-v9';
+import { type LedgerOps } from '@midnightntwrk/wallet-sdk-utilities';
+export declare const WalletError: {
+    other(err: unknown): WalletError;
+    submission(err: unknown): WalletError;
+};
+export type WalletError = OtherWalletError | InsufficientFundsError | SubmissionError | AddressError | SyncWalletError | InvalidCoinHashesError | TransactingError | LedgerOps.LedgerError;
+declare const OtherWalletError_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: "Wallet.Other";
+} & Readonly<A>;
+export declare class OtherWalletError extends OtherWalletError_base<{
+    message: string;
+    cause?: unknown;
+}> {
+}
+declare const SyncWalletError_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: "Wallet.Sync";
+} & Readonly<A>;
+export declare class SyncWalletError extends SyncWalletError_base<{
+    message: string;
+    cause?: unknown;
+}> {
+}
+declare const SubmissionError_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: "Wallet.SubmissionWalletError";
+} & Readonly<A>;
+export declare class SubmissionError extends SubmissionError_base<{
+    message: string;
+    cause?: unknown;
+}> {
+}
+declare const InsufficientFundsError_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: "Wallet.InsufficientFunds";
+} & Readonly<A>;
+export declare class InsufficientFundsError extends InsufficientFundsError_base<{
+    message: string;
+    tokenType: ledger.RawTokenType;
+    amount: bigint;
+}> {
+}
+declare const AddressError_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: "Wallet.Address";
+} & Readonly<A>;
+export declare class AddressError extends AddressError_base<{
+    message: string;
+    originalAddress: string;
+    cause?: unknown;
+}> {
+}
+declare const InvalidCoinHashesError_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: "Wallet.InvalidCoinHashes";
+} & Readonly<A>;
+export declare class InvalidCoinHashesError extends InvalidCoinHashesError_base<{
+    message: string;
+    missingNonces: Set<ledger.Nonce>;
+}> {
+}
+declare const TransactingError_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: "Wallet.Transacting";
+} & Readonly<A>;
+export declare class TransactingError extends TransactingError_base<{
+    message: string;
+    cause?: unknown;
+}> {
+}
+declare const TransactionHistoryError_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: "Wallet.TransactionHistory";
+} & Readonly<A>;
+export declare class TransactionHistoryError extends TransactionHistoryError_base<{
+    message: string;
+    cause?: unknown;
+}> {
+}
+export {};

package/dist/v2/WalletError.js

@@ -0,0 +1,53 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// You may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import { Data } from 'effect';
+export const WalletError = {
+    other(err) {
+        let message;
+        if (err) {
+            if (typeof err == 'object' && 'message' in err) {
+                message = String(err.message);
+            }
+            else if (typeof err == 'string') {
+                message = err;
+            }
+            else {
+                message = '';
+            }
+        }
+        else {
+            message = '';
+        }
+        return new OtherWalletError({ message: `Other wallet error: ${message}`, cause: err });
+    },
+    submission(err) {
+        const message = err && typeof err == 'object' && 'message' in err ? String(err.message) : '';
+        return new SubmissionError({ message: `Transaction submission error: ${message}`, cause: err });
+    },
+};
+export class OtherWalletError extends Data.TaggedError('Wallet.Other') {
+}
+export class SyncWalletError extends Data.TaggedError('Wallet.Sync') {
+}
+export class SubmissionError extends Data.TaggedError('Wallet.SubmissionWalletError') {
+}
+export class InsufficientFundsError extends Data.TaggedError('Wallet.InsufficientFunds') {
+}
+export class AddressError extends Data.TaggedError('Wallet.Address') {
+}
+export class InvalidCoinHashesError extends Data.TaggedError('Wallet.InvalidCoinHashes') {
+}
+export class TransactingError extends Data.TaggedError('Wallet.Transacting') {
+}
+export class TransactionHistoryError extends Data.TaggedError('Wallet.TransactionHistory') {
+}

package/dist/v2/index.d.ts

@@ -0,0 +1,13 @@
+export * from './V2Builder.js';
+export * as Sync from './Sync.js';
+export * as Transacting from './Transacting.js';
+export * as TransactionHistory from './TransactionHistory.js';
+export * as Serialization from './Serialization.js';
+export * as Migration from './Migration.js';
+export * as CoinsAndBalances from './CoinsAndBalances.js';
+export * as Keys from './Keys.js';
+export * from './RunningV2Variant.js';
+export * as Simulator from '@midnightntwrk/wallet-sdk-capabilities/simulation';
+export * as WalletError from './WalletError.js';
+export * from './CoreWallet.js';
+export * from './TransactionOps.js';

package/dist/v2/index.js

@@ -0,0 +1,26 @@
+// 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.
+// The V2 variant: this wallet on `@midnightntwrk/ledger-v9`, run from `forks.v9`. Its twin is `../v1`.
+export * from './V2Builder.js';
+export * as Sync from './Sync.js';
+export * as Transacting from './Transacting.js';
+export * as TransactionHistory from './TransactionHistory.js';
+export * as Serialization from './Serialization.js';
+export * as Migration from './Migration.js';
+export * as CoinsAndBalances from './CoinsAndBalances.js';
+export * as Keys from './Keys.js';
+export * from './RunningV2Variant.js';
+export * as Simulator from '@midnightntwrk/wallet-sdk-capabilities/simulation';
+export * as WalletError from './WalletError.js';
+export * from './CoreWallet.js';
+export * from './TransactionOps.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midnightntwrk/wallet-sdk-shielded",
-  "version": "4.0.0-beta.2",
+  "version": "4.0.0-beta.3",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -27,19 +27,27 @@
     "./v1": {
       "types": "./dist/v1/index.d.ts",
       "import": "./dist/v1/index.js"
+    },
+    "./v2": {
+      "types": "./dist/v2/index.d.ts",
+      "import": "./dist/v2/index.js"
     }
   },
   "dependencies": {
-    "@midnightntwrk/ledger-v9": "1.0.0-rc.3",
-    "@midnightntwrk/wallet-sdk-abstractions": "3.0.0-beta.0",
-    "@midnightntwrk/wallet-sdk-address-format": "4.0.0-beta.2",
-    "@midnightntwrk/wallet-sdk-capabilities": "4.0.0-beta.2",
-    "@midnightntwrk/wallet-sdk-indexer-client": "1.3.0-beta.1",
-    "@midnightntwrk/wallet-sdk-runtime": "1.0.6-beta.0",
-    "@midnightntwrk/wallet-sdk-utilities": "1.2.0",
+    "@midnight-ntwrk/ledger-v8": "^8.1.0",
+    "@midnightntwrk/ledger-v9": "1.0.0-rc.4",
+    "@midnightntwrk/wallet-sdk-abstractions": "3.0.0-beta.1",
+    "@midnightntwrk/wallet-sdk-address-format": "4.0.0-beta.3",
+    "@midnightntwrk/wallet-sdk-capabilities": "4.0.0-beta.3",
+    "@midnightntwrk/wallet-sdk-indexer-client": "2.0.0-beta.2",
+    "@midnightntwrk/wallet-sdk-runtime": "1.1.0-beta.1",
+    "@midnightntwrk/wallet-sdk-utilities": "1.2.2-beta.0",
     "effect": "^3.19.19",
     "rxjs": "^7.8.2"
   },
+  "devDependencies": {
+    "@midnightntwrk/wallet-sdk-state-translation": "workspace:^"
+  },
   "scripts": {
     "typecheck": "tsc -b ./tsconfig.json --noEmit --force",
     "test": "vitest run",