@midnight-ntwrk/wallet-sdk-runtime 1.0.0-beta.10

package/dist/Runtime.d.ts

@@ -0,0 +1,51 @@
+import { Effect, Scope, Stream, SynchronizedRef } from 'effect';
+import { ProtocolState, ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { Variant, WalletRuntimeError } from './abstractions/index.js';
+import { HList, Poly } from '@midnight-ntwrk/wallet-sdk-utilities';
+/**
+ * The {@link Runtime} service type.
+ */
+export interface Runtime<Variants extends Variant.AnyVersionedVariantArray> {
+    readonly stateChanges: Stream.Stream<ProtocolState.ProtocolState<Variant.StateOf<HList.Each<Variants>>>, WalletRuntimeError>;
+    readonly progress: Effect.Effect<Progress>;
+    readonly currentVariant: Effect.Effect<EachRunningVariant<Variants>>;
+    dispatch<TResult, E = never>(impl: Poly.PolyFunction<Variant.RunningVariantOf<HList.Each<Variants>>, Effect.Effect<TResult, E>>): Effect.Effect<TResult, WalletRuntimeError | E>;
+}
+export type RunningVariant<TVariant extends Variant.AnyVersionedVariant, TRest extends Variant.AnyVersionedVariantArray> = Poly.WithTagFrom<TVariant['variant']> & {
+    variant: TVariant;
+    runningVariant: Variant.RunningVariantOf<TVariant>;
+    initialState: Variant.StateOf<TVariant>;
+    variantScope: Scope.CloseableScope;
+    currentStateRef: SynchronizedRef.SynchronizedRef<Variant.StateOf<TVariant>>;
+    restVariants: TRest;
+    initProtocolVersion: ProtocolVersion.ProtocolVersion;
+    validVersionRange: ProtocolVersion.ProtocolVersion.Range;
+    nextProtocolVersion: ProtocolVersion.ProtocolVersion | null;
+};
+type EachRunningVariant<TAll extends Variant.AnyVersionedVariantArray> = TAll extends [
+    infer THead extends Variant.AnyVersionedVariant,
+    ...infer TRest extends Variant.AnyVersionedVariantArray
+] ? RunningVariant<THead, TRest> | EachRunningVariant<TRest> : never;
+/**
+ * A type that represents the reported progress of a variant expressed in terms of gaps to reaching synced
+ * progress in application site and data source site
+ */
+type Progress = {
+    readonly sourceGap: bigint;
+    readonly applyGap: bigint;
+};
+export type InitRuntimeHeadArgs<Variants extends Variant.AnyVersionedVariantArray> = {
+    variants: Variants;
+    state: Variant.StateOf<HList.Head<Variants>>;
+};
+export declare const initHead: <Variants extends Variant.AnyVersionedVariantArray>(initArgs: InitRuntimeHeadArgs<Variants>) => Effect.Effect<Runtime<Variants>, WalletRuntimeError, Scope.Scope>;
+export type InitRuntimeArgs<Variants extends Variant.AnyVersionedVariantArray, InitTag extends string | symbol> = {
+    variants: Variants;
+    tag: InitTag;
+    state: Variant.StateOf<HList.Find<Variants, {
+        variant: Poly.WithTag<InitTag>;
+    }>>;
+};
+export declare const init: <Variants extends Variant.AnyVersionedVariantArray, InitTag extends string | symbol>(initArgs: InitRuntimeArgs<Variants, InitTag>) => Effect.Effect<Runtime<Variants>, WalletRuntimeError, Scope.Scope>;
+export declare const dispatch: <Variants extends Variant.AnyVersionedVariantArray, TResult, E = never>(runtime: Runtime<Variants>, impl: Poly.PolyFunction<Variant.RunningVariantOf<HList.Each<Variants>>, Effect.Effect<TResult, E>>) => Effect.Effect<TResult, WalletRuntimeError | E>;
+export {};

package/dist/Runtime.js

@@ -0,0 +1,172 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 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 { Effect, Either, Exit, Option, Scope, Stream, SubscriptionRef, SynchronizedRef } from 'effect';
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { StateChange, VersionChangeType, WalletRuntimeError } from './abstractions/index.js';
+import { EitherOps, HList, Poly } from '@midnight-ntwrk/wallet-sdk-utilities';
+export const initHead = (initArgs) => {
+    const headVariant = HList.head(initArgs.variants);
+    return init({
+        variants: initArgs.variants,
+        tag: Poly.getTag(headVariant.variant),
+        state: initArgs.state,
+    });
+};
+export const init = (initArgs) => {
+    //Rewritten from generators to better track type issues reported
+    return Effect.Do.pipe(Effect.bind('initiatedFirstVariant', () => initVariant(initArgs)), Effect.bind('currentStateRef', ({ initiatedFirstVariant }) => initiatedFirstVariant.currentStateRef.get.pipe(Effect.flatMap((state) => SubscriptionRef.make(Either.right({ version: initiatedFirstVariant.initProtocolVersion, state }))))), Effect.bind('progressRef', () => SynchronizedRef.make({ applyGap: 0n, sourceGap: 0n })), Effect.bind('currentVariantRef', ({ initiatedFirstVariant }) => Effect.acquireRelease(SynchronizedRef.make(initiatedFirstVariant), (ref, exit) => Effect.gen(function* () {
+        // This is needed to properly close variant scope when whole runtime closes
+        // Otherwise variant would be running in the background
+        const runningVariant = yield* SynchronizedRef.get(ref);
+        yield* Scope.close(runningVariant.variantScope, exit);
+    }))), Effect.bind('runningStream', ({ initiatedFirstVariant, currentStateRef, progressRef, currentVariantRef }) => {
+        return runVariantStream(initiatedFirstVariant, currentStateRef, progressRef, currentVariantRef).pipe(Effect.catchAll((error) => {
+            return SubscriptionRef.set(currentStateRef, Either.left(error));
+        }), Effect.forkScoped);
+    }), Effect.flatMap(({ currentStateRef, progressRef, currentVariantRef }) => {
+        return Effect.gen(function* () {
+            const changesStream = yield* currentStateRef.changes.pipe(Stream.mapEffect((value) => EitherOps.toEffect(value)), Stream.share({ capacity: 'unbounded', replay: 1 }));
+            const runtime = {
+                stateChanges: changesStream,
+                progress: progressRef.get,
+                currentVariant: currentVariantRef.get,
+                dispatch: (impl) => dispatch(runtime, impl),
+            };
+            return runtime;
+        });
+    }));
+};
+export const dispatch = (runtime, impl) => {
+    return runtime.currentVariant.pipe(Effect.flatMap((current) => Poly.dispatch(current.runningVariant, impl)));
+};
+const migrateToNextVariant = (migrateArgs) => {
+    return Effect.gen(function* () {
+        const [headVersionedVariant] = migrateArgs.variants;
+        if (!headVersionedVariant) {
+            yield* Effect.fail(new WalletRuntimeError({ message: 'No variant to init' }));
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- It seems that TS is defaulting to the constraint provided for a generic type with its inference, which includes any
+        const newState = yield* headVersionedVariant.variant.migrateState(migrateArgs.state);
+        return yield* initHeadVariant({
+            variants: migrateArgs.variants,
+            state: newState,
+            initProtocolVersion: migrateArgs.initProtocolVersion,
+        });
+    });
+};
+// Arguments are gathered to a separate type because presence of HList.Find is crashing TS compiler ¯\_(ツ)_/¯
+const initVariant = (init) => {
+    return Effect.gen(function* () {
+        const index = init.variants.findIndex((variant) => Poly.getTag(variant.variant) === init.tag);
+        const theRest = init.variants.toSpliced(0, index);
+        //These casts are terrible, but they allow to call the initHeadVariant
+        return yield* initHeadVariant({
+            variants: theRest,
+            state: init.state,
+            initProtocolVersion: undefined,
+        });
+    });
+};
+// Following pattern from `initVariant` for consistency
+const initHeadVariant = (init) => {
+    return Effect.gen(function* () {
+        const [anyHeadVersionedVariant, maybeNextVersionedVariant] = init.variants;
+        if (!anyHeadVersionedVariant) {
+            yield* Effect.fail(new WalletRuntimeError({ message: 'No variant to init' }));
+        }
+        const headVersionedVariant = anyHeadVersionedVariant;
+        const actualInitProtocolVersion = init.initProtocolVersion ?? headVersionedVariant.sinceVersion;
+        const nextActivationVersion = maybeNextVersionedVariant
+            ? maybeNextVersionedVariant.sinceVersion
+            : ProtocolVersion.MaxSupportedVersion;
+        const validVersionRange = ProtocolVersion.makeRange(headVersionedVariant.sinceVersion, nextActivationVersion);
+        const stateRef = yield* SubscriptionRef.make(init.state);
+        const variantScope = yield* Scope.make();
+        const runningVariant = yield* headVersionedVariant.variant
+            .start({ stateRef })
+            .pipe(Effect.provideService(Scope.Scope, variantScope));
+        //This type declaration helps with setting right properties...
+        const out = {
+            __polyTag__: headVersionedVariant.variant.__polyTag__,
+            variant: headVersionedVariant,
+            initialState: init.state,
+            runningVariant: runningVariant,
+            currentStateRef: stateRef,
+            restVariants: HList.tail(init.variants),
+            initProtocolVersion: actualInitProtocolVersion,
+            validVersionRange,
+            nextProtocolVersion: maybeNextVersionedVariant ? maybeNextVersionedVariant.sinceVersion : null,
+            variantScope,
+        };
+        // ...while this type casting makes things bearable in the rest of the code (TS's type inference is great, but still limited)
+        return out;
+    });
+};
+const runVariantStream = (initiatedVariant, stateRef, progressRef, currentVariantRef) => {
+    const initialAcc = {
+        protocolVersion: initiatedVariant.initProtocolVersion,
+        shouldInitChange: false,
+        followEffect: Effect.void,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        lastState: initiatedVariant.initialState,
+    };
+    return initiatedVariant.runningVariant.state.pipe(Stream.scanEffect(initialAcc, (accumulator, change) => {
+        return StateChange.match(change, {
+            State: ({ state }) => {
+                return SubscriptionRef.set(stateRef, Either.right({ version: accumulator.protocolVersion, state })).pipe(Effect.as({ ...accumulator, lastState: state }));
+            },
+            ProgressUpdate: (progress) => {
+                return SynchronizedRef.set(progressRef, progress).pipe(Effect.as(accumulator));
+            },
+            VersionChange: ({ change }) => {
+                const newProtocolVersion = VersionChangeType.match(change, {
+                    Version: ({ version }) => version,
+                    Next: () => initiatedVariant.nextProtocolVersion,
+                });
+                if (newProtocolVersion != null &&
+                    !ProtocolVersion.withinRange(newProtocolVersion, initiatedVariant.validVersionRange)) {
+                    return Effect.succeed({
+                        ...accumulator,
+                        protocolVersion: newProtocolVersion,
+                        shouldInitChange: true,
+                        followEffect: Effect.gen(function* () {
+                            yield* Scope.close(initiatedVariant.variantScope, Exit.void);
+                            const newInitiatedVariant = yield* migrateToNextVariant({
+                                variants: initiatedVariant.restVariants,
+                                state: accumulator.lastState,
+                                initProtocolVersion: newProtocolVersion,
+                            });
+                            yield* SynchronizedRef.set(currentVariantRef, newInitiatedVariant);
+                            return yield* runVariantStream(newInitiatedVariant, stateRef, progressRef, currentVariantRef);
+                        }),
+                    });
+                }
+                else {
+                    return Effect.succeed({
+                        ...accumulator,
+                        protocolVersion: newProtocolVersion ?? accumulator.protocolVersion,
+                    });
+                }
+            },
+        });
+    }), Stream.filter((streamAcc) => streamAcc.shouldInitChange), Stream.runHead, Effect.flatMap((streamAccOption) => {
+        return Option.match(streamAccOption, {
+            onSome: (value) => {
+                return value.followEffect;
+            },
+            onNone: () => {
+                return Effect.void;
+            },
+        });
+    }));
+};

package/dist/WalletBuilder.d.ts

@@ -0,0 +1,45 @@
+import { Types } from 'effect';
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { VariantBuilder, WalletLike } from './abstractions/index.js';
+import { HList } from '@midnight-ntwrk/wallet-sdk-utilities';
+/**
+ * Builds a wallet-like implementation from a collection of wallet-like variants, each specific
+ * to a given version of the Midnight protocol.
+ *
+ * @typeParam TBuilders The sequence of variant builders that will manage the wallet state
+ */
+export declare class WalletBuilder<TBuilders extends VariantBuilder.AnyVersionedVariantBuilder[]> {
+    #private;
+    private constructor();
+    static init(): WalletBuilder<[]>;
+    /**
+     * Ensures that the built wallet uses a given variant.
+     *
+     * @param sinceVersion The Midnight protocol version that the variant should operate from.
+     * @param variantBuilder A {@link VariantBuilder} that builds the variant.
+     * @returns A new {@link WalletBuilder} that uses the variant that will be built from `variantBuilder`.
+     */
+    withVariant<TBuilder extends VariantBuilder.AnyVariantBuilder>(sinceVersion: ProtocolVersion.ProtocolVersion, variantBuilder: TBuilder): WalletBuilder<HList.Append<TBuilders, VariantBuilder.VersionedVariantBuilder<TBuilder>>>;
+    /**
+     * Builds a wallet like implementation.
+     */
+    build(...[maybeConfiguration]: WalletBuilder.BuildArguments<TBuilders>): WalletLike.BaseWalletClass<VariantBuilder.VersionedVariantsOf<TBuilders>, WalletBuilder.FullConfiguration<TBuilders>>;
+}
+export declare namespace WalletBuilder {
+    /**
+     * The internal build state of {@link WalletBuilder}.
+     *
+     * @remarks
+     * Represents the collection of configured variants and their configuration.
+     */
+    type BuildState<TBuilders extends VariantBuilder.AnyVersionedVariantBuilder[]> = {
+        readonly variants: TBuilders;
+    };
+    /**
+     * Allows properly expressing no need for configuration if an empty one needs to be provided
+     */
+    type BuildArguments<TBuilders extends VariantBuilder.AnyVersionedVariantBuilder[]> = VoidIfEmpty<FullConfiguration<TBuilders>> extends undefined ? [] : [FullConfiguration<TBuilders>];
+    type FullConfiguration<TBuilders extends VariantBuilder.AnyVersionedVariantBuilder[]> = Types.UnionToIntersection<Configurations<TBuilders>>;
+    type VoidIfEmpty<TObject> = keyof TObject extends never ? undefined : TObject;
+    type Configurations<TBuilders extends VariantBuilder.AnyVersionedVariantBuilder[]> = VariantBuilder.ConfigurationOf<HList.Each<TBuilders>>;
+}

package/dist/WalletBuilder.js

@@ -0,0 +1,112 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 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 { Effect, Exit, Scope } from 'effect';
+import * as rx from 'rxjs';
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { Variant, WalletRuntimeError } from './abstractions/index.js';
+import { ObservableOps, HList } from '@midnight-ntwrk/wallet-sdk-utilities';
+import * as Runtime from './Runtime.js';
+/**
+ * Builds a wallet-like implementation from a collection of wallet-like variants, each specific
+ * to a given version of the Midnight protocol.
+ *
+ * @typeParam TBuilders The sequence of variant builders that will manage the wallet state
+ */
+export class WalletBuilder {
+    constructor(buildState) {
+        this.#buildState = buildState;
+    }
+    static init() {
+        return new WalletBuilder({
+            variants: [],
+        });
+    }
+    #buildState;
+    /**
+     * Ensures that the built wallet uses a given variant.
+     *
+     * @param sinceVersion The Midnight protocol version that the variant should operate from.
+     * @param variantBuilder A {@link VariantBuilder} that builds the variant.
+     * @returns A new {@link WalletBuilder} that uses the variant that will be built from `variantBuilder`.
+     */
+    withVariant(sinceVersion, variantBuilder) {
+        const { sinceVersion: previousVersion } = this.#buildState.variants.at(-1) ?? {
+            sinceVersion: ProtocolVersion.ProtocolVersion(-1n),
+        };
+        if (sinceVersion <= previousVersion) {
+            throw new Error('ProtocolMismatch: sinceVersion is prior to previously registered version');
+        }
+        const newBuilder = { sinceVersion, variantBuilder };
+        return new WalletBuilder({
+            variants: HList.append(this.#buildState.variants, newBuilder),
+        });
+    }
+    /**
+     * Builds a wallet like implementation.
+     */
+    build(...[maybeConfiguration]) {
+        if (this.#buildState.variants.length == 0) {
+            throw new WalletRuntimeError({ message: 'Empty variants list' });
+        }
+        const variants = this.#buildState.variants.map(({ sinceVersion, variantBuilder }) => ({
+            sinceVersion,
+            variant: variantBuilder.build(maybeConfiguration ?? {}),
+        }));
+        return class BaseWallet {
+            static configuration = (maybeConfiguration ??
+                {});
+            static allVariants() {
+                return variants;
+            }
+            static allVariantsRecord() {
+                return Variant.makeVersionedRecord(BaseWallet.allVariants());
+            }
+            static startEmpty(WalletClass) {
+                return Effect.gen(this, function* () {
+                    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+                    const initialState = yield* HList.head(BaseWallet.allVariants()).variant.migrateState(null);
+                    return BaseWallet.startFirst(WalletClass, initialState);
+                }).pipe(Effect.runSync);
+            }
+            static startFirst(WalletClass, state) {
+                return Effect.gen(this, function* () {
+                    const scope = yield* Scope.make();
+                    const runtime = yield* Runtime.initHead({ variants, state }).pipe(Effect.provideService(Scope.Scope, scope));
+                    return new WalletClass(runtime, scope);
+                }).pipe(Effect.runSync);
+            }
+            static start(WalletClass, tag, state) {
+                return Effect.gen(this, function* () {
+                    const scope = yield* Scope.make();
+                    const runtime = yield* Runtime.init({ variants, tag, state }).pipe(Effect.provideService(Scope.Scope, scope));
+                    return new WalletClass(runtime, scope);
+                }).pipe(Effect.runSync);
+            }
+            runtime;
+            runtimeScope;
+            rawState;
+            get syncComplete() {
+                const { sourceGap, applyGap } = Effect.runSync(this.runtime.progress);
+                return sourceGap === 0n && applyGap === 0n;
+            }
+            constructor(runtime, runtimeScope) {
+                this.runtime = runtime;
+                this.runtimeScope = runtimeScope;
+                this.rawState = ObservableOps.fromStream(runtime.stateChanges).pipe(rx.shareReplay({ refCount: true, bufferSize: 1 }));
+            }
+            stop() {
+                return Scope.close(this.runtimeScope, Exit.void).pipe(Effect.runPromise);
+            }
+        };
+    }
+}

package/dist/abstractions/StateChange.d.ts

@@ -0,0 +1,167 @@
+import { Data } from 'effect';
+import { VersionChangeType } from './VersionChangeType.js';
+/**
+ * A tagged enum data type that represents the state changes across wallet implementation variants.
+ *
+ * @remarks
+ * A variant can report changes in state using the {@link StateChange.State} enum variant. The
+ * {@link StateChange.ProgressUpdate} and {@link StateChange.VersionChange} enum variants should be used when a
+ * variant needs to report a sync progress update, or a detected change in protocol version respectively.
+ */
+export type StateChange<TState> = Data.TaggedEnum<{
+    /** A change in state. */
+    State: {
+        readonly state: TState;
+    };
+    /** A change in reported progress. */
+    ProgressUpdate: {
+        /**
+         * The number of blocks that remain for the underlying datasource to process in order to be fully synchronized.
+         */
+        readonly sourceGap: bigint;
+        /**
+         * The number of blocks that remain for the variant to apply in order to be fully synchronized.
+         */
+        readonly applyGap: bigint;
+    };
+    /** A change in Midnight protocol version. */
+    VersionChange: {
+        readonly change: VersionChangeType;
+    };
+}>;
+/**
+ * A type predicate that determines if a given value is a {@link StateChange.State} enum variant.
+ */
+export declare const isState: {
+    <T extends {
+        readonly _tag: "State";
+        readonly state: any;
+    } | {
+        readonly _tag: "ProgressUpdate";
+        readonly sourceGap: bigint;
+        readonly applyGap: bigint;
+    } | {
+        readonly _tag: "VersionChange";
+        readonly change: VersionChangeType;
+    }>(u: T): u is T & {
+        readonly _tag: "State";
+    };
+    (u: unknown): u is {
+        readonly _tag: "State";
+        readonly state: unknown;
+    };
+};
+/**
+ * A type predicate that determines if a given value is a {@link StateChange.ProgressUpdate} enum variant.
+ */
+export declare const isProgressUpdate: {
+    <T extends {
+        readonly _tag: "State";
+        readonly state: any;
+    } | {
+        readonly _tag: "ProgressUpdate";
+        readonly sourceGap: bigint;
+        readonly applyGap: bigint;
+    } | {
+        readonly _tag: "VersionChange";
+        readonly change: VersionChangeType;
+    }>(u: T): u is T & {
+        readonly _tag: "ProgressUpdate";
+    };
+    (u: unknown): u is {
+        readonly _tag: "ProgressUpdate";
+        readonly sourceGap: bigint;
+        readonly applyGap: bigint;
+    };
+};
+/**
+ * A type predicate that determines if a given value is a {@link StateChange.VersionChange} enum variant.
+ */
+export declare const isVersionChange: {
+    <T extends {
+        readonly _tag: "State";
+        readonly state: any;
+    } | {
+        readonly _tag: "ProgressUpdate";
+        readonly sourceGap: bigint;
+        readonly applyGap: bigint;
+    } | {
+        readonly _tag: "VersionChange";
+        readonly change: VersionChangeType;
+    }>(u: T): u is T & {
+        readonly _tag: "VersionChange";
+    };
+    (u: unknown): u is {
+        readonly _tag: "VersionChange";
+        readonly change: VersionChangeType;
+    };
+};
+export declare const match: {
+    <A, B, C, D, Cases extends {
+        readonly State: (args: {
+            readonly _tag: "State";
+            readonly state: A;
+        }) => any;
+        readonly ProgressUpdate: (args: {
+            readonly _tag: "ProgressUpdate";
+            readonly sourceGap: bigint;
+            readonly applyGap: bigint;
+        }) => any;
+        readonly VersionChange: (args: {
+            readonly _tag: "VersionChange";
+            readonly change: VersionChangeType;
+        }) => any;
+    }>(cases: Cases & { [K in Exclude<keyof Cases, "State" | "ProgressUpdate" | "VersionChange">]: never; }): (self: {
+        readonly _tag: "State";
+        readonly state: A;
+    } | {
+        readonly _tag: "ProgressUpdate";
+        readonly sourceGap: bigint;
+        readonly applyGap: bigint;
+    } | {
+        readonly _tag: "VersionChange";
+        readonly change: VersionChangeType;
+    }) => import("effect/Unify").Unify<ReturnType<Cases["State" | "ProgressUpdate" | "VersionChange"]>>;
+    <A, B, C, D, Cases extends {
+        readonly State: (args: {
+            readonly _tag: "State";
+            readonly state: A;
+        }) => any;
+        readonly ProgressUpdate: (args: {
+            readonly _tag: "ProgressUpdate";
+            readonly sourceGap: bigint;
+            readonly applyGap: bigint;
+        }) => any;
+        readonly VersionChange: (args: {
+            readonly _tag: "VersionChange";
+            readonly change: VersionChangeType;
+        }) => any;
+    }>(self: {
+        readonly _tag: "State";
+        readonly state: A;
+    } | {
+        readonly _tag: "ProgressUpdate";
+        readonly sourceGap: bigint;
+        readonly applyGap: bigint;
+    } | {
+        readonly _tag: "VersionChange";
+        readonly change: VersionChangeType;
+    }, cases: Cases & { [K in Exclude<keyof Cases, "State" | "ProgressUpdate" | "VersionChange">]: never; }): import("effect/Unify").Unify<ReturnType<Cases["State" | "ProgressUpdate" | "VersionChange"]>>;
+}, State: <A>(args: {
+    readonly state: A;
+}) => {
+    readonly _tag: "State";
+    readonly state: A;
+}, ProgressUpdate: <A>(args: {
+    readonly sourceGap: bigint;
+    readonly applyGap: bigint;
+}) => {
+    readonly _tag: "ProgressUpdate";
+    readonly sourceGap: bigint;
+    readonly applyGap: bigint;
+}, VersionChange: <A>(args: {
+    readonly change: VersionChangeType;
+}) => {
+    readonly _tag: "VersionChange";
+    readonly change: VersionChangeType;
+};

package/dist/abstractions/StateChange.js

@@ -0,0 +1,27 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 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';
+const StateChange = Data.taggedEnum();
+/**
+ * A type predicate that determines if a given value is a {@link StateChange.State} enum variant.
+ */
+export const isState = StateChange.$is('State');
+/**
+ * A type predicate that determines if a given value is a {@link StateChange.ProgressUpdate} enum variant.
+ */
+export const isProgressUpdate = StateChange.$is('ProgressUpdate');
+/**
+ * A type predicate that determines if a given value is a {@link StateChange.VersionChange} enum variant.
+ */
+export const isVersionChange = StateChange.$is('VersionChange');
+export const { $match: match, State, ProgressUpdate, VersionChange } = StateChange;

package/dist/abstractions/Variant.d.ts

@@ -0,0 +1,57 @@
+import { Scope, SubscriptionRef } from 'effect';
+import type { Effect } from 'effect/Effect';
+import type { Stream } from 'effect/Stream';
+import { Poly } from '@midnight-ntwrk/wallet-sdk-utilities';
+import type { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { WalletRuntimeError } from './WalletRuntimeError.js';
+import * as StateChange from './StateChange.js';
+export interface VariantContext<TState> {
+    stateRef: SubscriptionRef.SubscriptionRef<TState>;
+}
+/**
+ * Encapsulates a variant of a wallet implementation.
+ *
+ * @typeParam TTState The type of state that the variant will operate over.
+ * @typeParam TPreviousState The type of state that the variant can migrate from.
+ * @typeParam TDomain The variant-specific functionality
+ */
+export type Variant<TTag extends string | symbol, TState, TPreviousState, TRunning extends RunningVariant<TTag, TState>> = Poly.WithTag<TTag> & {
+    start(context: VariantContext<TState>): Effect<TRunning, WalletRuntimeError, Scope.Scope>;
+    migrateState(previousState: TPreviousState): Effect<TState>;
+};
+export type RunningVariant<TTag extends symbol | string, TState> = Poly.WithTag<TTag> & {
+    state: Stream<StateChange.StateChange<TState>, WalletRuntimeError>;
+};
+/**
+ * A utility type that represents any {@link Variant}.
+ */
+export type AnyVariant = Variant<string | symbol, any, any, AnyRunningVariant>;
+export type AnyRunningVariant = RunningVariant<string | symbol, any>;
+export type RunningVariantOf<T> = T extends VersionedVariant<infer V> ? RunningVariantOf<V> : T extends Variant<string | symbol, any, any, infer Running> ? Running : never;
+export type StateOf<T> = T extends Variant<any, infer S, any, AnyRunningVariant> ? S : T extends VersionedVariant<infer V> ? StateOf<V> : never;
+export type PreviousStateOf<T> = T extends VersionedVariant<infer V> ? PreviousStateOf<V> : T extends Variant<string | symbol, unknown, infer S, any> ? S : never;
+/**
+ * An array of {@link Variant} instances.
+ */
+export type AnyVariantArray = AnyVariant[];
+/**
+ * A type that associates a {@link Variant} with a given version of the Midnight protocol.
+ */
+export type VersionedVariant<T extends AnyVariant> = Readonly<{
+    sinceVersion: ProtocolVersion.ProtocolVersion;
+    variant: T;
+}>;
+export type AnyVersionedVariant = VersionedVariant<AnyVariant>;
+/**
+ * An ordered array of types that associates a {@link Variant} with a given version of the Midnight protocol.
+ *
+ * @remarks
+ * The expected order of the variants will be ascending on `sinceVersion`.
+ */
+export type AnyVersionedVariantArray = AnyVersionedVariant[];
+export type VariantTag<T> = T extends VersionedVariant<infer V> ? VariantTag<V> : T extends Poly.WithTag<infer Tag> ? Tag : never;
+export type VariantRecord<Variants> = Variants extends [infer THead, ...infer TRest] ? {
+    readonly [K in VariantTag<THead>]: THead;
+} & VariantRecord<TRest> : Variants extends [] ? object : never;
+export declare const getVersionedVariantTag: <Variant extends AnyVariant>(v: VersionedVariant<Variant>) => VariantTag<Variant>;
+export declare const makeVersionedRecord: <Variants extends AnyVersionedVariantArray>(variants: Variants) => VariantRecord<Variants>;

package/dist/abstractions/Variant.js

@@ -0,0 +1,7 @@
+import { Poly } from '@midnight-ntwrk/wallet-sdk-utilities';
+export const getVersionedVariantTag = (v) => Poly.getTag(v.variant);
+export const makeVersionedRecord = (variants) => {
+    return variants.reduce((acc, variant) => {
+        return { ...acc, [getVersionedVariantTag(variant)]: variant };
+    }, {});
+};

package/dist/abstractions/VariantBuilder.d.ts

@@ -0,0 +1,39 @@
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { AnyVariant, VersionedVariant } from './Variant.js';
+/**
+ * Builds a target {@link Variant} object from internal build state.
+ *
+ * @typeParam TTState The type of state that the variant will operate over.
+ * @typeParam TPreviousState The type of state that the variant can migrate from.
+ * @typeParam TConfiguration A type representing the configuration required by the variant.
+ */
+export interface VariantBuilder<TVariant extends AnyVariant, TConfiguration extends object = object> {
+    /**
+     * Builds the target variant object from the internal build state.
+     *
+     * @param configuration The configuration to use when building the target variant.
+     *
+     * @returns An instance of {@link Variant} that operates over `TState`.
+     */
+    build(configuration: TConfiguration): TVariant;
+}
+/**
+ * Base type that represents variant configuration.
+ */
+export type AnyBuilderConfiguration = object;
+/**
+ * A utility type that represents any {@link VariantBuilder}.
+ */
+export type AnyVariantBuilder = VariantBuilder<AnyVariant, AnyBuilderConfiguration>;
+export type VariantOf<T> = T extends VersionedVariantBuilder<infer TBuilder> ? VariantOf<TBuilder> : T extends VariantBuilder<infer TVariant, object> ? TVariant : never;
+export type VersionedVariantBuilder<TBuilder extends AnyVariantBuilder> = Readonly<{
+    sinceVersion: ProtocolVersion.ProtocolVersion;
+    variantBuilder: TBuilder;
+}>;
+export type VariantsOf<T> = T extends [infer THead, ...infer TRest] ? [VariantOf<THead>, ...VariantsOf<TRest>] : T extends [] ? [] : never;
+export type VersionedVariantsOf<T> = T extends [infer THead, ...infer Rest] ? [VersionedVariant<VariantOf<THead>>, ...VersionedVariantsOf<Rest>] : T extends [] ? [] : never;
+export type ConfigurationOf<T> = T extends VariantBuilder<any, infer Config> ? Config : T extends VersionedVariantBuilder<infer Builder> ? ConfigurationOf<Builder> : never;
+/**
+ * A type that associates a {@link VariantBuilder} with a given version of the Midnight protocol.
+ */
+export type AnyVersionedVariantBuilder = VersionedVariantBuilder<AnyVariantBuilder>;

package/dist/abstractions/VariantBuilder.js

@@ -0,0 +1 @@
+export {};

package/dist/abstractions/VersionChangeType.d.ts

@@ -0,0 +1,67 @@
+import { Data } from 'effect';
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+/**
+ * A tagged enum data type that represents a change in Midnight protocol versions.
+ *
+ * @remarks
+ * A specific protocol version can be specified using the {@link VersionChangeType.Version} enum variant. It has a
+ * `version` property that accepts a {@link ProtocolVersion} value for a known protocol version.
+ * For use cases where a specific protocol version cannot be given, the {@link VersionChangeType.Next} enum variant
+ * can be used. Its use is context specific.
+ */
+export type VersionChangeType = Data.TaggedEnum<{
+    /** A change to a particular protocol version. */
+    Version: {
+        readonly version: ProtocolVersion.ProtocolVersion;
+    };
+    /** A change to the 'next' protocol version. Particularly useful in testing */
+    Next: {};
+}>;
+/**
+ * A type predicate that determines if a given value is a {@link VersionChangeType.Version} enum variant.
+ */
+export declare const isVersion: (u: unknown) => u is {
+    readonly _tag: "Version";
+    readonly version: ProtocolVersion.ProtocolVersion;
+};
+/**
+ * A type predicate that determines if a given value is a {@link VersionChangeType.Next} enum variant.
+ */
+export declare const isNext: (u: unknown) => u is {
+    readonly _tag: "Next";
+};
+export declare const match: {
+    <const Cases extends {
+        readonly Version: (args: {
+            readonly _tag: "Version";
+            readonly version: ProtocolVersion.ProtocolVersion;
+        }) => any;
+        readonly Next: (args: {
+            readonly _tag: "Next";
+        }) => any;
+    }>(cases: Cases & { [K in Exclude<keyof Cases, "Version" | "Next">]: never; }): (value: {
+        readonly _tag: "Version";
+        readonly version: ProtocolVersion.ProtocolVersion;
+    } | {
+        readonly _tag: "Next";
+    }) => import("effect/Unify").Unify<ReturnType<Cases["Version" | "Next"]>>;
+    <const Cases extends {
+        readonly Version: (args: {
+            readonly _tag: "Version";
+            readonly version: ProtocolVersion.ProtocolVersion;
+        }) => any;
+        readonly Next: (args: {
+            readonly _tag: "Next";
+        }) => any;
+    }>(value: {
+        readonly _tag: "Version";
+        readonly version: ProtocolVersion.ProtocolVersion;
+    } | {
+        readonly _tag: "Next";
+    }, cases: Cases & { [K in Exclude<keyof Cases, "Version" | "Next">]: never; }): import("effect/Unify").Unify<ReturnType<Cases["Version" | "Next"]>>;
+}, Version: Data.Case.Constructor<{
+    readonly _tag: "Version";
+    readonly version: ProtocolVersion.ProtocolVersion;
+}, "_tag">, Next: Data.Case.Constructor<{
+    readonly _tag: "Next";
+}, "_tag">;

package/dist/abstractions/VersionChangeType.js

@@ -0,0 +1,23 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 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';
+const VersionChangeType = Data.taggedEnum();
+/**
+ * A type predicate that determines if a given value is a {@link VersionChangeType.Version} enum variant.
+ */
+export const isVersion = VersionChangeType.$is('Version');
+/**
+ * A type predicate that determines if a given value is a {@link VersionChangeType.Next} enum variant.
+ */
+export const isNext = VersionChangeType.$is('Next');
+export const { $match: match, Version, Next } = VersionChangeType;

package/dist/abstractions/WalletLike.d.ts

@@ -0,0 +1,45 @@
+import { Scope } from 'effect';
+import { Observable } from 'rxjs';
+import { Runtime } from '../Runtime.js';
+import { AnyVersionedVariantArray, StateOf, VariantRecord } from './Variant.js';
+import { HList, Poly } from '@midnight-ntwrk/wallet-sdk-utilities';
+import { ProtocolState } from '@midnight-ntwrk/wallet-sdk-abstractions';
+/**
+ * Defines the static portion of base wallet class definition
+ */
+export interface BaseWalletClass<TVariants extends AnyVersionedVariantArray, TConfiguration = object> {
+    readonly configuration: Readonly<TConfiguration>;
+    new (runtime: Runtime<TVariants>, scope: Scope.CloseableScope): WalletLike<TVariants>;
+    allVariants(): TVariants;
+    allVariantsRecord(): VariantRecord<TVariants>;
+    startEmpty<T extends WalletClassLike<TVariants, any>>(walletClass: T): WalletOf<T>;
+    startFirst<T extends WalletClassLike<TVariants, any>>(walletClass: T, state: StateOf<HList.Head<TVariants>>): WalletOf<T>;
+    start<T extends WalletClassLike<TVariants, any>, Tag extends string | symbol>(walletClass: T, tag: Tag, state: StateOf<HList.Find<TVariants, {
+        variant: Poly.WithTag<Tag>;
+    }>>): WalletOf<T>;
+}
+/**
+ * Defines the static portion of wallet-like definition
+ */
+export interface WalletClassLike<TVariants extends AnyVersionedVariantArray, TWallet extends WalletLike<TVariants>> extends BaseWalletClass<TVariants> {
+    new (runtime: Runtime<TVariants>, scope: Scope.CloseableScope): TWallet;
+}
+export type AnyWalletClass<Variants extends AnyVersionedVariantArray> = WalletClassLike<Variants, WalletLike<Variants>>;
+export type WalletOf<T> = T extends WalletClassLike<any, infer TWallet> ? TWallet : never;
+/**
+ * Defines a base wallet-like implementation.
+ *
+ * @typeParam TVariants Underlying variants
+ */
+export interface WalletLike<TVariants extends AnyVersionedVariantArray> {
+    readonly runtime: Runtime<TVariants>;
+    readonly runtimeScope: Scope.CloseableScope;
+    /**
+     * A stream of state changes over any amount of time that have been processed by the wallet.
+     */
+    readonly rawState: Observable<ProtocolState.ProtocolState<StateOf<HList.Each<TVariants>>>>;
+    /**
+     * Stops the wallet
+     */
+    stop(): Promise<void>;
+}

package/dist/abstractions/WalletLike.js

@@ -0,0 +1 @@
+export {};

package/dist/abstractions/WalletRuntimeError.d.ts

@@ -0,0 +1,9 @@
+declare const WalletRuntimeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "WalletRuntimeError";
+} & Readonly<A>;
+export declare class WalletRuntimeError extends WalletRuntimeError_base<{
+    message: string;
+    cause?: unknown;
+}> {
+}
+export {};

package/dist/abstractions/WalletRuntimeError.js

@@ -0,0 +1,15 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 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 class WalletRuntimeError extends Data.TaggedError('WalletRuntimeError') {
+}

package/dist/abstractions/index.d.ts

@@ -0,0 +1,6 @@
+export * as Variant from './Variant.js';
+export * as VariantBuilder from './VariantBuilder.js';
+export * as WalletLike from './WalletLike.js';
+export * from './WalletRuntimeError.js';
+export * as StateChange from './StateChange.js';
+export * as VersionChangeType from './VersionChangeType.js';

package/dist/abstractions/index.js

@@ -0,0 +1,18 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 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.
+export * as Variant from './Variant.js';
+export * as VariantBuilder from './VariantBuilder.js';
+export * as WalletLike from './WalletLike.js';
+export * from './WalletRuntimeError.js';
+export * as StateChange from './StateChange.js';
+export * as VersionChangeType from './VersionChangeType.js';

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './WalletBuilder.js';
+export * as Runtime from './Runtime.js';

package/dist/index.js

@@ -0,0 +1,14 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 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.
+export * from './WalletBuilder.js';
+export * as Runtime from './Runtime.js';

package/dist/testing/utils.d.ts

@@ -0,0 +1,16 @@
+import { ProtocolState } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { Chunk } from 'effect';
+import { Observable, OperatorFunction } from 'rxjs';
+/**
+ * Utility function that takes state values from an RxJS observable until it completes or errors.
+ *
+ * @param observable The RxJS observable from which state values should be read.
+ * @param onErrCallback An optional callback to invoke if an error is encountered reading a state value.
+ * @returns A `Promise` that resolves with an array of state values that were received before encountering
+ * any error.
+ *
+ * @internal
+ */
+export declare const toProtocolStateArray: <T>(observable: Observable<ProtocolState.ProtocolState<T>>, onErrCallback?: (err: unknown) => void) => Promise<ProtocolState.ProtocolState<T>[]>;
+export declare const reduceToChunk: <T>() => OperatorFunction<T, Chunk.Chunk<T>>;
+export declare const isRange: (values: Chunk.Chunk<number>) => boolean;

package/dist/testing/utils.js

@@ -0,0 +1,33 @@
+import { Chunk } from 'effect';
+import { reduce } from 'rxjs';
+/**
+ * Utility function that takes state values from an RxJS observable until it completes or errors.
+ *
+ * @param observable The RxJS observable from which state values should be read.
+ * @param onErrCallback An optional callback to invoke if an error is encountered reading a state value.
+ * @returns A `Promise` that resolves with an array of state values that were received before encountering
+ * any error.
+ *
+ * @internal
+ */
+export const toProtocolStateArray = (observable, onErrCallback) => new Promise((resolve) => {
+    const receivedStates = [];
+    observable.subscribe({
+        next(value) {
+            receivedStates.push(value);
+        },
+        complete() {
+            resolve(receivedStates);
+        },
+        error(err) {
+            onErrCallback?.call(undefined, err);
+            resolve(receivedStates);
+        },
+    });
+});
+export const reduceToChunk = () => reduce((chunk, value) => Chunk.append(chunk, value), Chunk.empty());
+export const isRange = (values) => {
+    const firstDropped = Chunk.drop(values, 1);
+    const lastDropped = Chunk.dropRight(values, 1);
+    return Chunk.zip(lastDropped, firstDropped).pipe(Chunk.every(([l, r]) => r == l + 1));
+};

package/dist/testing/variants.d.ts

@@ -0,0 +1,58 @@
+import { Variant, VariantBuilder, VersionChangeType, WalletRuntimeError } from '../abstractions/index.js';
+import { Effect, Scope } from 'effect';
+export type RangeConfig = {
+    min: number;
+    max: number;
+};
+export declare const Numeric: "NumericRange";
+export declare class NumericRange implements Variant.Variant<typeof Numeric, number, null, Variant.RunningVariant<typeof Numeric, number>> {
+    #private;
+    __polyTag__: typeof Numeric;
+    protected configuration: RangeConfig;
+    protected yieldCount: number;
+    protected throwError: boolean;
+    constructor(configuration: RangeConfig, yieldCount: number, throwError: boolean);
+    get currentState(): number;
+    start(context: Variant.VariantContext<number>): Effect.Effect<Variant.RunningVariant<typeof Numeric, number>>;
+    migrateState(): Effect.Effect<number>;
+}
+export declare class NumericRangeBuilder implements VariantBuilder.VariantBuilder<NumericRange, RangeConfig> {
+    private readonly yieldCount;
+    private readonly throwError;
+    constructor(yieldCount?: number, throwError?: boolean);
+    build(configuration: RangeConfig): NumericRange;
+}
+export type RangeMultiplierConfig = RangeConfig & {
+    multiplier: number;
+};
+export declare const NumericMultiplier = "NumericMultiplier";
+export declare class NumericRangeMultiplier implements Variant.Variant<typeof NumericMultiplier, number, number, Variant.RunningVariant<typeof NumericMultiplier, number>> {
+    #private;
+    __polyTag__: typeof NumericMultiplier;
+    protected configuration: RangeMultiplierConfig;
+    constructor(configuration: RangeMultiplierConfig);
+    get currentState(): number;
+    start(context: Variant.VariantContext<number>): Effect.Effect<Variant.RunningVariant<typeof NumericMultiplier, number>>;
+    migrateState(state: number): Effect.Effect<number>;
+}
+export declare class NumericRangeMultiplierBuilder implements VariantBuilder.VariantBuilder<NumericRangeMultiplier, RangeMultiplierConfig> {
+    build(configuration: RangeMultiplierConfig): NumericRangeMultiplier;
+}
+export type InterceptingRunningVariant<TTag extends string | symbol, TState> = Variant.RunningVariant<TTag, TState> & {
+    emitProtocolVersionChange: (change: VersionChangeType.VersionChangeType) => Effect.Effect<void>;
+};
+export declare class InterceptingVariant<TTag extends string | symbol, TState> implements Variant.Variant<TTag, TState, TState, InterceptingRunningVariant<TTag, TState>> {
+    __polyTag__: TTag;
+    constructor(tag: TTag);
+    migrateState(previousState: TState): Effect.Effect<TState>;
+    start(context: Variant.VariantContext<TState>): Effect.Effect<InterceptingRunningVariant<TTag, TState>, WalletRuntimeError, Scope.Scope>;
+}
+/**
+ * Builder of an intercepting variant
+ * It allows removing the possibility of race conditions by requiring an explicit gesture to migrate to a next/specific protocol version
+ */
+export declare class InterceptingVariantBuilder<TTag extends string | symbol, TState> implements VariantBuilder.VariantBuilder<InterceptingVariant<TTag, TState>, object> {
+    tag: TTag;
+    constructor(tag: TTag);
+    build(): InterceptingVariant<TTag, TState>;
+}

package/dist/testing/variants.js

@@ -0,0 +1,149 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 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 { StateChange, VersionChangeType, WalletRuntimeError } from '../abstractions/index.js';
+import { Effect, Option, PubSub, Stream } from 'effect';
+export const Numeric = 'NumericRange';
+export class NumericRange {
+    __polyTag__ = Numeric;
+    #state = 0;
+    configuration;
+    yieldCount;
+    throwError;
+    constructor(configuration, yieldCount, throwError) {
+        this.throwError = throwError;
+        this.yieldCount = yieldCount;
+        this.configuration = configuration;
+    }
+    get currentState() {
+        return this.#state;
+    }
+    start(context) {
+        const max = this.configuration.max ?? 10;
+        return context.stateRef.get.pipe(Effect.flatMap((state) => {
+            return Effect.sync(() => {
+                this.#state = state;
+            });
+        }), Effect.map(() => ({
+            __polyTag__: Numeric,
+            state: Stream.fromAsyncIterable(
+            // eslint-disable-next-line @typescript-eslint/require-await
+            (async function* (self) {
+                for (let value = self.#state; value <= max; value++) {
+                    self.#state = value;
+                    yield StateChange.State({ state: value });
+                    if (--self.yieldCount === 0) {
+                        if (self.throwError) {
+                            throw new Error('NumericRange: forced break');
+                        }
+                        yield StateChange.VersionChange({ change: VersionChangeType.Next() });
+                    }
+                }
+            })(this), (e) => new WalletRuntimeError({ message: 'NumericRange error', cause: e })),
+        })));
+    }
+    migrateState() {
+        return Effect.succeed(0);
+    }
+}
+export class NumericRangeBuilder {
+    yieldCount;
+    throwError;
+    constructor(yieldCount = 10, throwError = false) {
+        this.throwError = throwError;
+        this.yieldCount = yieldCount;
+    }
+    build(configuration) {
+        return new NumericRange(configuration, this.yieldCount, this.throwError);
+    }
+}
+export const NumericMultiplier = 'NumericMultiplier';
+export class NumericRangeMultiplier {
+    __polyTag__ = NumericMultiplier;
+    #state = 0;
+    configuration;
+    constructor(configuration) {
+        this.configuration = configuration;
+    }
+    get currentState() {
+        return this.#state;
+    }
+    start(context) {
+        return context.stateRef.get.pipe(Effect.flatMap((state) => {
+            return Effect.sync(() => {
+                this.#state = state;
+            });
+        }), Effect.map(() => {
+            const max = this.configuration.max ?? 10;
+            return {
+                __polyTag__: NumericMultiplier,
+                state: Stream.fromIterable((function* (self) {
+                    for (let value = self.#state; value <= max; value++) {
+                        self.#state = value;
+                        yield StateChange.State({ state: value * self.configuration.multiplier });
+                    }
+                    return Option.none();
+                })(this)),
+            };
+        }));
+    }
+    migrateState(state) {
+        return Effect.succeed(state + 1);
+    }
+}
+export class NumericRangeMultiplierBuilder {
+    build(configuration) {
+        return new NumericRangeMultiplier(configuration);
+    }
+}
+export class InterceptingVariant {
+    __polyTag__;
+    constructor(tag) {
+        this.__polyTag__ = tag;
+    }
+    migrateState(previousState) {
+        return Effect.succeed(previousState);
+    }
+    start(context) {
+        const tag = this.__polyTag__;
+        return Effect.gen(this, function* () {
+            const pubsub = yield* PubSub.bounded({
+                capacity: 1,
+                replay: 1,
+            });
+            const state = yield* context.stateRef.get;
+            yield* PubSub.publish(pubsub, StateChange.State({ state }));
+            return {
+                __polyTag__: tag,
+                state: Stream.fromPubSub(pubsub, {
+                    shutdown: true,
+                }),
+                emitProtocolVersionChange: (change) => {
+                    return PubSub.publish(pubsub, StateChange.VersionChange({ change }));
+                },
+            };
+        });
+    }
+}
+/**
+ * Builder of an intercepting variant
+ * It allows removing the possibility of race conditions by requiring an explicit gesture to migrate to a next/specific protocol version
+ */
+export class InterceptingVariantBuilder {
+    tag;
+    constructor(tag) {
+        this.tag = tag;
+    }
+    build() {
+        return new InterceptingVariant(this.tag);
+    }
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@midnight-ntwrk/wallet-sdk-runtime",
+  "description": "Runtime for the wallet variants",
+  "version": "1.0.0-beta.10",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "author": "Midnight Foundation",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com/"
+  },
+  "files": [
+    "dist/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/midnight-ntwrk/artifacts.git"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./abstractions": {
+      "types": "./dist/abstractions/index.d.ts",
+      "import": "./dist/abstractions/index.js"
+    }
+  },
+  "dependencies": {
+    "@midnight-ntwrk/wallet-sdk-abstractions": "1.0.0-beta.10",
+    "@midnight-ntwrk/wallet-sdk-utilities": "1.0.0-beta.9",
+    "effect": "^3.17.3",
+    "rxjs": "^7.5"
+  },
+  "scripts": {
+    "typecheck": "tsc -b ./tsconfig.json --noEmit",
+    "test": "vitest run",
+    "lint": "eslint --max-warnings 0",
+    "format": "prettier --write \"**/*.{ts,js,json,yaml,yml,md}\"",
+    "format:check": "prettier --check \"**/*.{ts,js,json,yaml,yml,md}\"",
+    "dist": "tsc -b ./tsconfig.build.json",
+    "dist:publish": "tsc -b ./tsconfig.publish.json",
+    "clean": "rimraf --glob dist 'tsconfig.*.tsbuildinfo' && date +%s > .clean-timestamp",
+    "publint": "publint --strict"
+  },
+  "devDependencies": {
+    "eslint": "^9.32.0",
+    "fast-check": "^4.2.0",
+    "prettier": "^3.7.0",
+    "publint": "~0.3.14",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  }
+}