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

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 '@midnight-ntwrk/wallet-sdk-abstractions';
-import { type Variant, type VariantBuilder } from '@midnight-ntwrk/wallet-sdk-runtime/abstractions';
+import { type Variant, type VariantBuilder, type StartMaterial } from '@midnight-ntwrk/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 '@midnight-ntwrk/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 '@midnight-ntwrk/wallet-sdk-abstractions';
+import { WalletRuntimeError, } from '@midnight-ntwrk/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 '@midnight-ntwrk/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,10 +1,10 @@
-import type * as ledger from '@midnightntwrk/ledger-v9';
+import type * as ledger from '@midnight-ntwrk/ledger-v8';
 import { type LedgerOps } from '@midnight-ntwrk/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;
+export type WalletError = OtherWalletError | InsufficientFundsError | SubmissionError | AddressError | SyncWalletError | InvalidCoinHashesError | TransactingError | OutOfOrderSyncUpdateError | 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>;
@@ -71,4 +71,29 @@ export declare class TransactionHistoryError extends TransactionHistoryError_bas
     cause?: unknown;
 }> {
 }
+declare const OutOfOrderSyncUpdateError_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.OutOfOrderSyncUpdate";
+} & Readonly<A>;
+/**
+ * A batch of zswap ledger events was not in ascending id order: an event arrived at or below the one before it, or at
+ * or below the applied cursor.
+ *
+ * @remarks
+ *   Order is all the wallet can check: zswap events share one id sequence with dust and contract events in the indexer,
+ *   so gaps in the stream are normal and a skipped event is only ever caught by the ledger's own insertion check. The
+ *   whole batch is refused, nothing is applied and the cursor stays, so the running variant retries from the same
+ *   place.
+ * @example
+ *   ```ts
+ *   if (error._tag === 'Wallet.OutOfOrderSyncUpdate') console.warn(`expected above ${error.expected}, got ${error.received}`);
+ *   ```
+ */
+export declare class OutOfOrderSyncUpdateError extends OutOfOrderSyncUpdateError_base<{
+    readonly message: string;
+    /** The id the delivered event had to exceed: its predecessor in the batch, or the applied cursor. */
+    readonly expected: bigint;
+    /** The event id the source delivered instead. */
+    readonly received: bigint;
+}> {
+}
 export {};

package/dist/v1/WalletError.js

@@ -51,3 +51,19 @@ export class TransactingError extends Data.TaggedError('Wallet.Transacting') {
 }
 export class TransactionHistoryError extends Data.TaggedError('Wallet.TransactionHistory') {
 }
+/**
+ * A batch of zswap ledger events was not in ascending id order: an event arrived at or below the one before it, or at
+ * or below the applied cursor.
+ *
+ * @remarks
+ *   Order is all the wallet can check: zswap events share one id sequence with dust and contract events in the indexer,
+ *   so gaps in the stream are normal and a skipped event is only ever caught by the ledger's own insertion check. The
+ *   whole batch is refused, nothing is applied and the cursor stays, so the running variant retries from the same
+ *   place.
+ * @example
+ *   ```ts
+ *   if (error._tag === 'Wallet.OutOfOrderSyncUpdate') console.warn(`expected above ${error.expected}, got ${error.received}`);
+ *   ```
+ */
+export class OutOfOrderSyncUpdateError extends Data.TaggedError('Wallet.OutOfOrderSyncUpdate') {
+}

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 '@midnight-ntwrk/wallet-sdk-capabilities/simulation';
+export { V8 as Simulator } from '@midnight-ntwrk/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 '@midnight-ntwrk/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 '@midnight-ntwrk/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 '@midnight-ntwrk/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,
+    };
+};