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

package/dist/v1/V1Builder.d.ts

@@ -1,7 +1,8 @@
-import * as ledger from '@midnightntwrk/ledger-v9';
+import * as ledger from '@midnight-ntwrk/ledger-v8';
 import { type Either, type Types } from 'effect';
 import { type NetworkId } from '@midnightntwrk/wallet-sdk-abstractions';
-import { type Variant, type VariantBuilder } from '@midnightntwrk/wallet-sdk-runtime/abstractions';
+import { type Variant, type VariantBuilder, type StartMaterial } from '@midnightntwrk/wallet-sdk-runtime/abstractions';
+import { type StateMigration } from './Migration.js';
 import { RunningV1Variant, V1Tag } from './RunningV1Variant.js';
 import { type SerializationCapability } from './Serialization.js';
 import { type DefaultSyncContext, type DefaultSyncConfiguration, type ChangesResult, type SyncCapability, type SyncService, type WalletSyncUpdate } from './Sync.js';
@@ -10,7 +11,7 @@ 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 { CoreWallet } from './CoreWallet.js';
+import { type CoreWallet } from './CoreWallet.js';
 import { type DefaultTransactionHistoryConfiguration, type TransactionHistoryService } from './TransactionHistory.js';
 export type BaseV1Configuration = {
     networkId: NetworkId.NetworkId;
@@ -19,40 +20,81 @@ export type DefaultV1Configuration = BaseV1Configuration & DefaultSyncConfigurat
 declare const V1BuilderSymbol: {
     readonly typeId: unique symbol;
 };
-export type V1Variant<TSerialized, TSyncUpdate, TTransaction, TAuxData> = Variant.Variant<typeof V1Tag, CoreWallet, null, RunningV1Variant<TSerialized, TSyncUpdate, TTransaction, TAuxData>> & {
+export type V1Variant<TSerialized, TSyncUpdate, TTransaction, TAuxData, TPreviousState = null> = Variant.Variant<typeof V1Tag, CoreWallet, TPreviousState, RunningV1Variant<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 AnyV1Variant = V1Variant<any, any, any, any>;
 export type DefaultV1Variant = V1Variant<string, WalletSyncUpdate, ledger.FinalizedTransaction, ledger.ZswapSecretKeys>;
 export type TransactionOf<T extends AnyV1Variant> = T extends V1Variant<any, any, infer TTransaction, any> ? TTransaction : never;
 export type AuxDataOf<T extends AnyV1Variant> = T extends V1Variant<any, any, any, infer TAuxData> ? TAuxData : never;
 export type SerializedStateOf<T extends AnyV1Variant> = T extends V1Variant<infer TSerialized, any, any, any> ? TSerialized : never;
-export type DefaultV1Builder = V1Builder<DefaultV1Configuration, RunningV1Variant.Context<string, WalletSyncUpdate, ledger.FinalizedTransaction, ledger.ZswapSecretKeys>, string, WalletSyncUpdate, ledger.FinalizedTransaction, ledger.ZswapSecretKeys>;
-export declare class V1Builder<TConfig extends BaseV1Configuration = BaseV1Configuration, TContext extends Partial<RunningV1Variant.AnyContext> = object, TSerialized = never, TSyncUpdate = never, TTransaction = never, TStartAux extends object = object> implements VariantBuilder.VariantBuilder<V1Variant<TSerialized, TSyncUpdate, TTransaction, TStartAux>, TConfig> {
+export type DefaultV1Builder<TPreviousState = null> = V1Builder<DefaultV1Configuration, RunningV1Variant.Context<string, WalletSyncUpdate, ledger.FinalizedTransaction, ledger.ZswapSecretKeys>, string, WalletSyncUpdate, ledger.FinalizedTransaction, ledger.ZswapSecretKeys, TPreviousState>;
+export declare class V1Builder<TConfig extends BaseV1Configuration = BaseV1Configuration, TContext extends Partial<RunningV1Variant.AnyContext> = object, TSerialized = never, TSyncUpdate = never, TTransaction = never, TStartAux extends object = object, TPreviousState = null> implements VariantBuilder.VariantBuilder<V1Variant<TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>, TConfig> {
     #private;
-    constructor(buildState?: V1Builder.PartialBuildState<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>);
-    withDefaults(): DefaultV1Builder;
-    withTransactionType<Transaction>(): V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, Transaction, TStartAux>;
-    withDefaultTransactionType(): V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, ledger.FinalizedTransaction, TStartAux>;
-    withSyncDefaults(): V1Builder<TConfig & DefaultSyncConfiguration, TContext & DefaultSyncContext, TSerialized, WalletSyncUpdate, TTransaction, ledger.ZswapSecretKeys>;
-    withSync<TSyncConfig, TSyncContext extends Partial<RunningV1Variant.AnyContext>, TSyncUpdate, TStartAux extends object>(syncService: (configuration: TSyncConfig, getContext: () => TSyncContext) => SyncService<CoreWallet, TStartAux, TSyncUpdate>, syncCapability: (configuration: TSyncConfig, getContext: () => TSyncContext) => SyncCapability<CoreWallet, TSyncUpdate, ChangesResult>): V1Builder<TConfig & TSyncConfig, TContext & TSyncContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
-    withSerializationDefaults(): V1Builder<TConfig, TContext, string, TSyncUpdate, TTransaction, TStartAux>;
-    withSerialization<TSerializationConfig, TSerializationContext extends Partial<RunningV1Variant.AnyContext>, TSerialized>(serializationCapability: (configuration: TSerializationConfig, getContext: () => TSerializationContext) => SerializationCapability<CoreWallet, null, TSerialized>): V1Builder<TConfig & TSerializationConfig, TContext & TSerializationContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
-    withTransactingDefaults(this: V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, ledger.FinalizedTransaction, TStartAux>): V1Builder<TConfig & DefaultTransactingConfiguration, TContext & DefaultTransactingContext, TSerialized, TSyncUpdate, ledger.FinalizedTransaction, TStartAux>;
-    withTransacting<TTransactingConfig, TTransactingContext extends Partial<RunningV1Variant.AnyContext>>(transactingCapability: (config: TTransactingConfig, getContext: () => TTransactingContext) => TransactingCapability<ledger.ZswapSecretKeys, CoreWallet, TTransaction>): V1Builder<TConfig & TTransactingConfig, TContext & TTransactingContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
-    withCoinSelection<TCoinSelectionConfig, TCoinSelectionContext extends Partial<RunningV1Variant.AnyContext>>(coinSelection: (config: TCoinSelectionConfig, getContext: () => TCoinSelectionContext) => CoinSelection<ledger.QualifiedShieldedCoinInfo>): V1Builder<TConfig & TCoinSelectionConfig, TContext & TCoinSelectionContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
-    withCoinSelectionDefaults(): V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
-    withCoinsAndBalancesDefaults(): V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
-    withCoinsAndBalances<TBalancesConfig, TBalancesContext extends Partial<RunningV1Variant.AnyContext>>(coinsAndBalancesCapability: (configuration: TBalancesConfig, getContext: () => TBalancesContext) => CoinsAndBalancesCapability<CoreWallet>): V1Builder<TConfig & TBalancesConfig, TContext & TBalancesContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
-    withTransactionHistoryDefaults(this: V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, ledger.FinalizedTransaction, TStartAux>): V1Builder<TConfig & DefaultTransactionHistoryConfiguration, TContext, TSerialized, TSyncUpdate, ledger.FinalizedTransaction, TStartAux>;
-    withTransactionHistory<TTransactionHistoryConfig, TTransactionHistoryContext extends Partial<RunningV1Variant.AnyContext>>(transactionHistoryService: (configuration: TTransactionHistoryConfig, getContext: () => TTransactionHistoryContext) => TransactionHistoryService): V1Builder<TConfig & TTransactionHistoryConfig, TContext & TTransactionHistoryContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
-    withKeysDefaults(): V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
-    withKeys<TKeysConfig, TKeysContext extends Partial<RunningV1Variant.AnyContext>>(keysCapability: (configuration: TKeysConfig, getContext: () => TKeysContext) => KeysCapability<CoreWallet>): V1Builder<TConfig & TKeysConfig, TContext & TKeysContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
-    build(this: V1Builder<TConfig, RunningV1Variant.Context<TSerialized, TSyncUpdate, TTransaction, TStartAux>, TSerialized, TSyncUpdate, TTransaction, TStartAux>, configuration: TConfig): V1Variant<TSerialized, TSyncUpdate, TTransaction, TStartAux>;
+    constructor(buildState?: V1Builder.PartialBuildState<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>);
+    withDefaults(this: V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, null>): DefaultV1Builder;
+    withTransactionType<Transaction>(): V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, Transaction, TStartAux, TPreviousState>;
+    withDefaultTransactionType(): V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, ledger.FinalizedTransaction, TStartAux, TPreviousState>;
+    withSyncDefaults(): V1Builder<TConfig & DefaultSyncConfiguration, TContext & DefaultSyncContext, TSerialized, WalletSyncUpdate, TTransaction, ledger.ZswapSecretKeys, TPreviousState>;
+    withSync<TSyncConfig, TSyncContext extends Partial<RunningV1Variant.AnyContext>, TSyncUpdate, TStartAux extends object>(syncService: (configuration: TSyncConfig, getContext: () => TSyncContext) => SyncService<CoreWallet, TStartAux, TSyncUpdate>, syncCapability: (configuration: TSyncConfig, getContext: () => TSyncContext) => SyncCapability<CoreWallet, TSyncUpdate, ChangesResult>): V1Builder<TConfig & TSyncConfig, TContext & TSyncContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    withSerializationDefaults(): V1Builder<TConfig, TContext, string, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    withSerialization<TSerializationConfig, TSerializationContext extends Partial<RunningV1Variant.AnyContext>, TSerialized>(serializationCapability: (configuration: TSerializationConfig, getContext: () => TSerializationContext) => SerializationCapability<CoreWallet, null, TSerialized>): V1Builder<TConfig & TSerializationConfig, TContext & TSerializationContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    withTransactingDefaults(this: V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, ledger.FinalizedTransaction, TStartAux, TPreviousState>): V1Builder<TConfig & DefaultTransactingConfiguration, TContext & DefaultTransactingContext, TSerialized, TSyncUpdate, ledger.FinalizedTransaction, TStartAux, TPreviousState>;
+    withTransacting<TTransactingConfig, TTransactingContext extends Partial<RunningV1Variant.AnyContext>>(transactingCapability: (config: TTransactingConfig, getContext: () => TTransactingContext) => TransactingCapability<ledger.ZswapSecretKeys, CoreWallet, TTransaction>): V1Builder<TConfig & TTransactingConfig, TContext & TTransactingContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    withCoinSelection<TCoinSelectionConfig, TCoinSelectionContext extends Partial<RunningV1Variant.AnyContext>>(coinSelection: (config: TCoinSelectionConfig, getContext: () => TCoinSelectionContext) => CoinSelection<ledger.QualifiedShieldedCoinInfo>): V1Builder<TConfig & TCoinSelectionConfig, TContext & TCoinSelectionContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    withCoinSelectionDefaults(): V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    withCoinsAndBalancesDefaults(): V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    withCoinsAndBalances<TBalancesConfig, TBalancesContext extends Partial<RunningV1Variant.AnyContext>>(coinsAndBalancesCapability: (configuration: TBalancesConfig, getContext: () => TBalancesContext) => CoinsAndBalancesCapability<CoreWallet>): V1Builder<TConfig & TBalancesConfig, TContext & TBalancesContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    withTransactionHistoryDefaults(this: V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, ledger.FinalizedTransaction, TStartAux, TPreviousState>): V1Builder<TConfig & DefaultTransactionHistoryConfiguration, TContext, TSerialized, TSyncUpdate, ledger.FinalizedTransaction, TStartAux, TPreviousState>;
+    withTransactionHistory<TTransactionHistoryConfig, TTransactionHistoryContext extends Partial<RunningV1Variant.AnyContext>>(transactionHistoryService: (configuration: TTransactionHistoryConfig, getContext: () => TTransactionHistoryContext) => TransactionHistoryService): V1Builder<TConfig & TTransactionHistoryConfig, TContext & TTransactionHistoryContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    withKeysDefaults(): V1Builder<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 V1Builder.withStartAux}.
+     */
+    withStartAuxDefaults(this: V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, ledger.ZswapSecretKeys, TPreviousState>): V1Builder<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>): V1Builder<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 V1Builder.withMigration} with {@link makeCrossLedgerMigration} instead.
+     */
+    withMigrationDefaults(this: V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, null>): V1Builder<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 V1Builder().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>): V1Builder<TConfig & TMigrationConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPrevious>;
+    withKeys<TKeysConfig, TKeysContext extends Partial<RunningV1Variant.AnyContext>>(keysCapability: (configuration: TKeysConfig, getContext: () => TKeysContext) => KeysCapability<CoreWallet>): V1Builder<TConfig & TKeysConfig, TContext & TKeysContext, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
+    build(this: V1Builder<TConfig, RunningV1Variant.Context<TSerialized, TSyncUpdate, TTransaction, TStartAux>, TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>, configuration: TConfig): V1Variant<TSerialized, TSyncUpdate, TTransaction, TStartAux, TPreviousState>;
 }
 /** @internal */
 declare namespace V1Builder {
@@ -80,9 +122,28 @@ declare namespace V1Builder {
     };
     /** The internal build state of {@link V1Builder}. */
     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>>;
-    type PartialBuildState<TConfig = object, TContext = object, TSerialized = never, TSyncUpdate = never, TTransaction = never, TStartAux = object> = {
+    /**
+     * 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 V1Builder}. */
     interface Variance<R> {
         readonly [V1BuilderSymbol.typeId]: {

package/dist/v1/V1Builder.js

@@ -10,9 +10,10 @@
 // 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 * as ledger from '@midnight-ntwrk/ledger-v8';
 import { Effect, Scope } from 'effect';
-import { WalletSeed } from '@midnightntwrk/wallet-sdk-abstractions';
+import { WalletRuntimeError, } from '@midnightntwrk/wallet-sdk-runtime/abstractions';
+import { makeEmptyWalletMigration } from './Migration.js';
 import { RunningV1Variant, V1Tag } from './RunningV1Variant.js';
 import { makeDefaultV1SerializationCapability } from './Serialization.js';
 import { makeEventsSyncService, makeEventsSyncCapability, } from './Sync.js';
@@ -20,7 +21,6 @@ import { makeDefaultTransactingCapability, } from './Transacting.js';
 import { makeDefaultCoinsAndBalancesCapability } from './CoinsAndBalances.js';
 import { makeDefaultKeysCapability } from './Keys.js';
 import { chooseCoin } from '@midnightntwrk/wallet-sdk-capabilities';
-import { CoreWallet, PublicKeys } from './CoreWallet.js';
 import { makeDefaultTransactionHistoryService, } from './TransactionHistory.js';
 const V1BuilderSymbol = {
     typeId: Symbol('@midnight-ntwrk/wallet#V1Builder'),
@@ -38,6 +38,12 @@ export class V1Builder {
             .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
+            // `RunningV1Variant.Context` that `DefaultV1Builder` 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() {
@@ -58,6 +64,9 @@ export class V1Builder {
             ...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() {
@@ -108,6 +117,63 @@ export class V1Builder {
     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 V1Builder.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 V1Builder({
+            ...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 V1Builder.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 V1Builder().withDefaults().withMigration(makeCrossLedgerMigration);
+     *   ```;
+     *
+     * @param migration Builds the migration from the configuration and the sibling capabilities.
+     */
+    withMigration(migration) {
+        const capabilities = this.#buildState;
+        return new V1Builder({
+            // 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 V1Builder({
             ...this.#buildState,
@@ -116,28 +182,63 @@ export class V1Builder {
     }
     build(configuration) {
         const v1Context = this.#buildContextFromBuildState(configuration);
-        const { networkId } = configuration;
+        const migration = this.#resolveMigration(configuration, () => v1Context);
         return {
             __polyTag__: V1Tag,
             coinsAndBalances: v1Context.coinsAndBalancesCapability,
             keys: v1Context.keysCapability,
             serialization: v1Context.serializationCapability,
             transactionHistory: v1Context.transactionHistoryService,
+            startAux: this.#resolveStartAux(),
             start(context) {
                 return Effect.gen(function* () {
                     const scope = yield* Scope.Scope;
                     return new RunningV1Variant(scope, context, v1Context);
                 });
             },
-            migrateState(_previousState) {
-                const seed = WalletSeed.fromString('0000000000000000000000000000000000000000000000000000000000000001');
-                return Effect.succeed(CoreWallet.empty(PublicKeys.fromSecretKeys(ledger.ZswapSecretKeys.fromSeed(seed)), networkId));
-            },
+            // 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 v1Context.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 V1 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 V1 Builder');

package/dist/v1/WalletError.d.ts

@@ -1,4 +1,4 @@
-import type * as ledger from '@midnightntwrk/ledger-v9';
+import type * as ledger from '@midnight-ntwrk/ledger-v8';
 import { type LedgerOps } from '@midnightntwrk/wallet-sdk-utilities';
 export declare const WalletError: {
     other(err: unknown): WalletError;

package/dist/v1/index.d.ts

@@ -3,10 +3,11 @@ 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 './RunningV1Variant.js';
-export * as Simulator from '@midnightntwrk/wallet-sdk-capabilities/simulation';
+export { V8 as Simulator } from '@midnightntwrk/wallet-sdk-capabilities/simulation';
 export * as WalletError from './WalletError.js';
 export * from './CoreWallet.js';
 export * from './TransactionOps.js';

package/dist/v1/index.js

@@ -10,15 +10,19 @@
 // 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 V1 variant: this wallet on `@midnight-ntwrk/ledger-v8`, run below `forks.v9`. Its twin is `../v2`.
 export * from './V1Builder.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 './RunningV1Variant.js';
-export * as Simulator from '@midnightntwrk/wallet-sdk-capabilities/simulation';
+// The V1 variant re-exports the ledger-v8 simulator twin, not the whole simulation index — the unqualified
+// names there are the ledger-v9 twin's.
+export { V8 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/CoinsAndBalances.d.ts

@@ -0,0 +1,24 @@
+import { type CoreWallet } from './CoreWallet.js';
+import type * as ledger from '@midnightntwrk/ledger-v9';
+export type AvailableCoin = {
+    coin: ledger.QualifiedShieldedCoinInfo;
+    commitment: ledger.CoinCommitment;
+    nullifier: ledger.Nullifier;
+};
+export type PendingCoin = {
+    coin: ledger.ShieldedCoinInfo;
+    ttl: Date | undefined;
+    commitment: ledger.CoinCommitment;
+    nullifier: ledger.Nullifier;
+};
+export type Coin = AvailableCoin | PendingCoin;
+export type Balances = Record<ledger.RawTokenType, bigint>;
+export type CoinsAndBalancesCapability<TState> = {
+    getAvailableBalances(state: TState): Balances;
+    getPendingBalances(state: TState): Balances;
+    getTotalBalances(state: TState): Balances;
+    getAvailableCoins(state: TState): readonly AvailableCoin[];
+    getPendingCoins(state: TState): readonly PendingCoin[];
+    getTotalCoins(state: TState): ReadonlyArray<AvailableCoin | PendingCoin>;
+};
+export declare const makeDefaultCoinsAndBalancesCapability: () => CoinsAndBalancesCapability<CoreWallet>;

package/dist/v2/CoinsAndBalances.js

@@ -0,0 +1,41 @@
+import { pipe, Array, Option } from 'effect';
+import { RecordOps } from '@midnightntwrk/wallet-sdk-utilities';
+const calculateBalances = (coins) => coins.reduce((acc, { coin }) => ({
+    ...acc,
+    [coin.type]: acc[coin.type] === undefined ? coin.value : acc[coin.type] + coin.value,
+}), {});
+export const makeDefaultCoinsAndBalancesCapability = () => {
+    const getAvailableBalances = (state) => {
+        const availableCoins = getAvailableCoins(state);
+        return calculateBalances(availableCoins);
+    };
+    const getPendingBalances = (state) => {
+        const pendingCoins = getPendingCoins(state);
+        return calculateBalances(pendingCoins);
+    };
+    const getTotalBalances = (state) => {
+        const availableBalances = getAvailableBalances(state);
+        const pendingBalances = getPendingBalances(state);
+        return pipe([availableBalances, pendingBalances], RecordOps.mergeWithAccumulator(0n, (a, b) => a + b));
+    };
+    // Both joins are total over the crossing window. A wallet that crossed the ledger-version boundary holds its full
+    // local state before it holds the hashes for it — computing a commitment or nullifier needs the secret keys the
+    // migration deliberately does not have — so a coin without its hash entry is not yet nameable and is left out of
+    // the view, rather than assumed present and dereferenced. The window closes on the first sync update, which
+    // carries the keys and both resolves the map and releases the spends the state crossed with, so a coin booked for a
+    // transaction the boundary stranded is available again by the time it can be named (see CoreWallet.completeCrossing).
+    const getAvailableCoins = (state) => {
+        const pendingSpends = new Set([...state.state.pendingSpends.values()].map(([coin]) => coin.nonce));
+        return pipe([...state.state.coins], Array.filter((coin) => !pendingSpends.has(coin.nonce)), Array.filterMap((coin) => pipe(Option.fromNullable(state.coinHashes[coin.nonce]), Option.map(({ commitment, nullifier }) => ({ coin, commitment, nullifier })))));
+    };
+    const getPendingCoins = (state) => pipe([...state.state.pendingOutputs.values()], Array.filterMap(([coin, ttl]) => pipe(Option.fromNullable(state.coinHashes[coin.nonce]), Option.map(({ commitment, nullifier }) => ({ coin, ttl, commitment, nullifier })))));
+    const getTotalCoins = (state) => [...getAvailableCoins(state), ...getPendingCoins(state)];
+    return {
+        getAvailableBalances,
+        getPendingBalances,
+        getTotalBalances,
+        getAvailableCoins,
+        getPendingCoins,
+        getTotalCoins,
+    };
+};

package/dist/v2/CoreWallet.d.ts

@@ -0,0 +1,162 @@
+import * as ledger from '@midnightntwrk/ledger-v9';
+import { ProtocolVersion, SyncProgress } from '@midnightntwrk/wallet-sdk-abstractions';
+import { Either } from 'effect';
+import { type WalletError } from './WalletError.js';
+export type PublicKeys = {
+    coinPublicKey: ledger.CoinPublicKey;
+    encryptionPublicKey: ledger.EncPublicKey;
+};
+export declare const PublicKeys: {
+    fromSecretKeys: (secretKeys: ledger.ZswapSecretKeys) => PublicKeys;
+};
+export type CoinHashesMap = Readonly<Record<ledger.Nonce, {
+    nullifier: ledger.Nullifier;
+    commitment: ledger.CoinCommitment;
+}>>;
+export declare const CoinHashesMap: {
+    empty: {};
+    pickAllCoins(state: ledger.ZswapLocalState): readonly ledger.ShieldedCoinInfo[];
+    assertValid(map: CoinHashesMap, state: ledger.ZswapLocalState): Either.Either<void, Set<ledger.Nonce>>;
+    updateWithCoins(secretKeys: ledger.ZswapSecretKeys, existing: CoinHashesMap, coins: Iterable<ledger.ShieldedCoinInfo>): CoinHashesMap;
+    updateWithNewCoins(secretKeys: ledger.ZswapSecretKeys, existing: CoinHashesMap, coins: Iterable<ledger.ShieldedCoinInfo>): CoinHashesMap;
+    init(secretKeys: ledger.ZswapSecretKeys, coins: Iterable<ledger.ShieldedCoinInfo>): CoinHashesMap;
+};
+export type CoreWallet = Readonly<{
+    state: ledger.ZswapLocalState;
+    publicKeys: PublicKeys;
+    protocolVersion: ProtocolVersion.ProtocolVersion;
+    progress: SyncProgress.SyncProgress;
+    networkId: string;
+    coinHashes: CoinHashesMap;
+    /**
+     * This wallet's coin hashes have never been computed, and {@link CoinHashesMap.empty} means "not yet", not "none".
+     *
+     * @remarks
+     *   Set by the cross-ledger migration and cleared by the first sync update, which is the first moment secret keys are
+     *   at hand — see {@link CoreWallet.fromPreviousVersion} and {@link CoreWallet.completeCrossing}. It is also what marks
+     *   the wallet as freshly crossed, which is how that step knows the reservations in its local state are ones no
+     *   inclusion can ever clear and releases them exactly once. Stated as a field rather than inferred from "empty map
+     *   beside a non-empty state" because an empty map is a perfectly good value for a wallet holding nothing, and
+     *   overloading it would make one shape mean two things. Being a field, it is also what lets a snapshot taken
+     *   mid-crossing declare itself: {@link CoreWallet.restoreWithCoinHashes} goes on rejecting a snapshot whose hashes do
+     *   not cover its coins, because only a wallet carrying this marker is permitted the gap. `true` is the only
+     *   inhabitant, so "pending" and "absent" are the only two states.
+     */
+    coinHashesPending?: true;
+}>;
+export declare const CoreWallet: {
+    init(localState: ledger.ZswapLocalState, secretKeys: ledger.ZswapSecretKeys, networkId: string): CoreWallet;
+    empty(publicKeys: PublicKeys, networkId: string): 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>;
+    /**
+     * Restores a wallet whose coin hashes were never computed — a snapshot taken mid-crossing.
+     *
+     * @remarks
+     *   The counterpart of {@link CoreWallet.restoreWithCoinHashes} for the one shape that validation would otherwise
+     *   refuse: a full local state, carried across the ledger-version boundary as bytes, beside an empty hash map. The
+     *   hashes are commitments and nullifiers, and computing them needs the secret keys a deserializer does not hold, so
+     *   the wallet comes back still marked pending and the first sync update fills them in
+     *   ({@link CoreWallet.resolveCoinHashes}). Total: there is nothing here to reject, which is exactly why it is a
+     *   separate entry point rather than a flag on the validating one.
+     * @param publicKeys The identity the snapshot declared.
+     * @param localState The local state the snapshot carried.
+     * @param syncProgress Where the snapshot's reading had got to.
+     * @param protocolVersion The version the snapshot was written under.
+     * @param networkId The network the snapshot claims.
+     * @returns A wallet holding that state, its coin hashes still pending.
+     */
+    restoreWithPendingCoinHashes(publicKeys: PublicKeys, localState: ledger.ZswapLocalState, syncProgress: SyncProgress.SyncProgressData, protocolVersion: bigint, networkId: string): CoreWallet;
+    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;
+    /**
+     * Adopts a wallet inherited from the previous ledger version: its local state, its identity, and its position.
+     *
+     * @remarks
+     *   The state passed in is this ledger version's own object, decoded from the previous version's bytes — the two majors
+     *   share the `zswap-local-state` codec, so the crossing is a round-trip rather than a reconstruction (see
+     *   `Migration.makeCrossLedgerMigration`, and the characterization test that pins the codec). So everything the
+     *   previous wallet's tree held arrives intact: its coins at the Merkle indices the chain gave them, the height it
+     *   had reached, and the outputs it was still expecting. What also crosses is the public keys, 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. The indexer
+     *   numbers ledger-v9 events onwards from whatever id it had reached when the fork happened, never from zero, so
+     *   resuming from the inherited cursor is what puts this wallet in front of them. 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.
+     *
+     *   The one thing the bytes cannot supply is the coin hashes: commitments and nullifiers are computed from the secret
+     *   keys, which a migration by design does not hold. They are therefore left empty and marked
+     *   {@link CoreWallet.coinHashesPending}, for {@link CoreWallet.completeCrossing} to fill in at the first sync update —
+     *   the first place in this variant where keys and state meet. The same step releases the spends the state crossed
+     *   with: those transactions belong to the ledger version the chain has left behind and can never be included, so
+     *   nothing else would ever free the coins they reserved.
+     * @param previous The identity and position read off the previous ledger version's wallet, and its decoded state.
+     * @returns A wallet of this ledger version holding what its predecessor held, positioned at the fork.
+     */
+    fromPreviousVersion(previous: {
+        readonly state: ledger.ZswapLocalState;
+        readonly publicKeys: PublicKeys;
+        readonly networkId: string;
+        readonly protocolVersion: bigint;
+        readonly progress: SyncProgress.SyncProgressData;
+    }): CoreWallet;
+    /**
+     * Finishes a crossing at the first sync update: the reservations released, then the coin hashes computed.
+     *
+     * @remarks
+     *   The other half of {@link CoreWallet.fromPreviousVersion}. A migrated wallet arrives holding its whole local state
+     *   but nothing it needs the secret keys for — no commitments or nullifiers, and no way to un-book the spends it
+     *   carried — because a migration is by design handed no key material. The first sync update carries it, so this is
+     *   where both gaps close: {@link releaseStrandedSpends} first, since a released coin is one more coin the hashes have
+     *   to name, and {@link CoreWallet.resolveCoinHashes} over the state that comes back. Applied at the head of both sync
+     *   capabilities, before anything else they do, so a batch that turns out to be empty still runs it: a wallet that
+     *   crossed into a quiet timeline must not be left unable to name or to spend the coins it crossed with.
+     *
+     *   Idempotent and self-clearing: without the marker this is the identity, so it costs a field read on every update
+     *   thereafter and nothing else. That is also what keeps it away from a reservation made on this side of the
+     *   boundary, whose transaction is live and whose coins are genuinely spoken for.
+     * @param wallet The wallet to complete.
+     * @param secretKeys The keys the update arrived with.
+     * @returns `wallet` unchanged if it never crossed, otherwise a copy whose coins are nameable and spendable again.
+     */
+    completeCrossing(wallet: CoreWallet, secretKeys: ledger.ZswapSecretKeys): CoreWallet;
+    /**
+     * Computes the coin hashes a wallet crossed the ledger-version boundary without.
+     *
+     * @remarks
+     *   The hash half of {@link CoreWallet.completeCrossing}, which is what the sync capabilities call: a crossing has a
+     *   second gap to close beside this one, so a caller finishing one should go through the combined step rather than
+     *   here. A migrated wallet arrives holding its whole local state but no commitments or nullifiers for it, because
+     *   deriving those needs the secret keys, and the first sync update is what carries them.
+     *
+     *   Idempotent and self-clearing: without the marker this is the identity.
+     * @param wallet The wallet to complete.
+     * @param secretKeys The keys the update arrived with.
+     * @returns `wallet` unchanged if its hashes were never pending, otherwise a copy holding them.
+     */
+    resolveCoinHashes(wallet: CoreWallet, secretKeys: ledger.ZswapSecretKeys): 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[]];
+    updateProgress(wallet: CoreWallet, { appliedIndex, highestRelevantWalletIndex, highestIndex, highestRelevantIndex, isConnected, }: Partial<SyncProgress.SyncProgressData>): CoreWallet;
+    addTransaction(wallet: CoreWallet, _tx: ledger.FinalizedTransaction): CoreWallet;
+    revertTransaction<TTx extends ledger.Transaction<ledger.Signaturish, ledger.Proofish, ledger.Bindingish>>(wallet: CoreWallet, tx: TTx): CoreWallet;
+    updateTxHistory(wallet: CoreWallet, _newTxs: readonly ledger.FinalizedTransaction[]): CoreWallet;
+    spendCoins(wallet: CoreWallet, secretKeys: ledger.ZswapSecretKeys, coins: ReadonlyArray<ledger.QualifiedShieldedCoinInfo>, segment: number): [ReadonlyArray<ledger.ZswapOffer<ledger.PreProof>>, CoreWallet];
+    watchCoins(wallet: CoreWallet, secretKeys: ledger.ZswapSecretKeys, coins: ReadonlyArray<ledger.ShieldedCoinInfo>): CoreWallet;
+};