@midnight-ntwrk/wallet-sdk-dust-wallet 5.0.0-beta.3 → 5.0.0-beta.4

package/dist/v1/RunningV1Variant.d.ts

@@ -1,4 +1,4 @@
-import { Effect, Stream, Scope } from 'effect';
+import { Effect, Stream, Scope, Duration, Schedule } from 'effect';
 import { type TransactionHistoryService } from './TransactionHistory.js';
 import { type DustSecretKey, type Signature, type SignatureVerifyingKey, type FinalizedTransaction, type UnprovenTransaction } from '@midnight-ntwrk/ledger-v8';
 import { type WalletError } from './WalletError.js';
@@ -27,6 +27,14 @@ export declare namespace RunningV1Variant {
     type AnyContext = Context<any, any, any, any>;
 }
 export declare const V1Tag: unique symbol;
+/**
+ * How a failing synchronization pass is retried.
+ *
+ * @remarks
+ *   Exported so the delays it actually produces can be asserted. A schedule reads as though its combinators apply to the
+ *   delay, and for some of them they do not — which is worth pinning in a test rather than trusting by eye.
+ */
+export declare const syncRetrySchedule: Schedule.Schedule<[Duration.Duration, number], unknown, never>;
 export type DefaultRunningV1 = RunningV1Variant<string, V8.SimulatorState, FinalizedTransaction, DustSecretKey>;
 export declare class RunningV1Variant<TSerialized, TSyncUpdate, TTransaction, TStartAux> implements Variant.RunningVariant<typeof V1Tag, CoreWallet> {
     #private;

package/dist/v1/RunningV1Variant.js

@@ -15,6 +15,7 @@ import { ProtocolVersion, Token } from '@midnight-ntwrk/wallet-sdk-abstractions'
 import { OtherWalletError } from './WalletError.js';
 import { ArrayOps, EitherOps } from '@midnight-ntwrk/wallet-sdk-utilities';
 import { StateChange, VersionChangeType, } from '@midnight-ntwrk/wallet-sdk-runtime/abstractions';
+import { BackgroundRepeat } from './Sync.js';
 const progress = (state) => {
     const appliedIndex = state.progress?.appliedIndex ?? 0n;
     const highestRelevantWalletIndex = state.progress?.highestRelevantWalletIndex ?? 0n;
@@ -48,6 +49,21 @@ const protocolVersionChange = (previous, current, isInitial, activationRange) =>
         : [];
 };
 export const V1Tag = Symbol('V1');
+/**
+ * How a failing synchronization pass is retried.
+ *
+ * @remarks
+ *   Exported so the delays it actually produces can be asserted. A schedule reads as though its combinators apply to the
+ *   delay, and for some of them they do not — which is worth pinning in a test rather than trusting by eye.
+ */
+export const syncRetrySchedule = pipe(Schedule.exponential(Duration.seconds(1), 2), Schedule.jittered, 
+// `union` retries as soon as either side would, so pairing the backoff with a fixed two-minute schedule takes the
+// shorter of the two — which is the backoff until it grows past two minutes, and two minutes from then on. Written
+// this way rather than as a `Schedule.map` over the delay: `map` rewrites a schedule's *output*, which it takes
+// **after** the delay has already been read from it, so mapping an exponential leaves the timing untouched. The
+// earlier form did exactly that, and backed off unboundedly — past an hour by the twelfth attempt — while reading
+// as though it were capped.
+Schedule.union(Schedule.spaced(Duration.minutes(2))));
 export class RunningV1Variant {
     __polyTag__ = V1Tag;
     #scope;
@@ -59,11 +75,26 @@ export class RunningV1Variant {
     #txHistoryPermits = Effect.makeSemaphore(8).pipe(Effect.runSync);
     state;
     #syncLock;
+    /**
+     * Whether a background synchronization worker is already running.
+     *
+     * @remarks
+     *   Distinct from {@link #syncLock}, which is released at the end of every pass and so says nothing about the worker
+     *   that runs them. Held for the worker's whole lifetime — polling delays and retries included — and released as it
+     *   exits, so a wallet started again while it is already synchronizing keeps the worker it has instead of gaining a
+     *   second one that polls alongside it until the wallet stops.
+     *
+     *   The guard asks only whether a worker is running, not what it was started with, so a second start is ignored even
+     *   when it carries different key material. Starting a running wallet on a second key is not a supported way to
+     *   change keys: stop it first. Two workers would be no better — they would apply two keys' updates to one state.
+     */
+    #backgroundWorkerLock;
     constructor(scope, context, v1Context) {
         this.#scope = scope;
         this.#context = context;
         this.#v1Context = v1Context;
         this.#syncLock = Effect.runSync(Ref.make(false));
+        this.#backgroundWorkerLock = Effect.runSync(Ref.make(false));
         this.state = Stream.fromEffect(context.stateRef.get).pipe(Stream.flatMap((initialState) => context.stateRef.changes.pipe(
         // The accumulator carries the "have we seen anything yet" flag alongside the previous state: the first
         // observation is the only one that can be a restored state nobody has inspected against this variant's
@@ -78,12 +109,29 @@ export class RunningV1Variant {
         }));
     }
     startSyncInBackground(startAux) {
-        return this.startSync(startAux).pipe(Stream.retry(pipe(Schedule.exponential(Duration.seconds(1), 2), Schedule.map((delay) => {
-            const maxDelay = Duration.minutes(2);
-            const jitter = Duration.millis(Math.floor(Math.random() * 1000));
-            const delayWithJitter = Duration.toMillis(delay) + Duration.toMillis(jitter);
-            return Duration.millis(Math.min(delayWithJitter, Duration.toMillis(maxDelay)));
-        }))), Stream.runScoped(Sink.drain), Effect.forkScoped, Effect.provideService(Scope.Scope, this.#scope));
+        // One pass, in a scope of its own. `Stream.runScoped` acquires into whichever scope it is handed, and the source's
+        // client layers take `Scope` as an input requirement rather than discharging one of their own — so a pass drained
+        // straight into the variant scope leaves its clients open there until the wallet stops, one more set per repeat.
+        // Scoping here closes them as the pass ends, on success, failure or interruption alike, and before any retry delay.
+        // The tx-history fan-out `startSync` forks is deliberately unaffected: it is pinned to the variant scope
+        // explicitly, and none of its work needs a client this scope holds.
+        const pass = this.startSync(startAux).pipe(Stream.runScoped(Sink.drain), Effect.scoped);
+        // Retrying the drained pass rather than the stream keeps the scope inside the retry: a failed attempt gives its
+        // resources back before the backoff, instead of holding them for the length of it.
+        const attempt = pass.pipe(Effect.retry(syncRetrySchedule));
+        // A service that synchronizes in finite passes would otherwise leave the wallet frozen at whatever its first pass
+        // saw. Repeating re-runs `startSync`, which re-reads the wallet state, so each pass resumes from what the previous
+        // one applied. The retry above cannot serve this purpose: it re-runs a pass on failure, not on completion.
+        // Repeating outside it keeps a transient failure to the pass it happened in, rather than restarting the cycle.
+        const worker = BackgroundRepeat.$match(this.#v1Context.syncService.backgroundRepeat, {
+            Once: () => attempt,
+            WithDelay: ({ delay }) => Effect.repeat(attempt, Schedule.spaced(delay)).pipe(Effect.asVoid),
+        });
+        // Taken before the worker is forked and given back as it exits, so the guard covers the gaps between passes that
+        // the sync lock cannot. A second start finds it held and leaves the running worker alone.
+        return Ref.modify(this.#backgroundWorkerLock, (isRunning) => [!isRunning, true]).pipe(Effect.flatMap((acquired) => acquired
+            ? worker.pipe(Effect.ensuring(Ref.set(this.#backgroundWorkerLock, false)), Effect.forkScoped, Effect.asVoid)
+            : Effect.void), Effect.provideService(Scope.Scope, this.#scope));
     }
     /**
      * Runs one sync pass to completion, rather than forking it into the background.

package/dist/v1/Sync.d.ts

@@ -1,4 +1,4 @@
-import { Effect, Layer, Schema, type Scope, Stream, Option } from 'effect';
+import { Data, Effect, Layer, Schema, type Scope, Stream, Duration, Option } from 'effect';
 import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
 import { LedgerParametersCodec } from '@midnight-ntwrk/wallet-sdk-capabilities/codecs';
 import { type DustSecretKey, type DustStateChanges, Event as LedgerEvent, LedgerParameters } from '@midnight-ntwrk/ledger-v8';
@@ -7,9 +7,96 @@ import { type WalletError } from './WalletError.js';
 import { V8 } from '@midnight-ntwrk/wallet-sdk-capabilities/simulation';
 import { CoreWallet } from './CoreWallet.js';
 import { type NetworkId } from './types/ledger.js';
+/**
+ * How often background synchronization runs a sync service's `updates`.
+ *
+ * @remarks
+ *   Every service states this, because the answer cannot be inferred from the service: it follows from whether `updates`
+ *   is finite, which only the service knows. A service whose `updates` is a long-lived subscription is
+ *   {@link BackgroundRepeat.Once} — that single pass never ends, so there is nothing to repeat. A service that
+ *   synchronizes in finite passes is {@link BackgroundRepeat.WithDelay}, or a wallet synchronizing in the background
+ *   would converge once and then never observe anything again. The variant's background retry does not cover the
+ *   latter: it re-runs a pass on failure, not on completion.
+ *
+ *   Every service this variant has is {@link BackgroundRepeat.Once}: the finite-pass projections sync is a ledger-v9
+ *   capability that no published ledger-v8 can support. The type is declared in both twins so that their background
+ *   synchronization reads one contract, and so that a ledger-v8 service which one day synchronizes in finite passes has
+ *   the vocabulary to say so.
+ */
+export type BackgroundRepeat = Data.TaggedEnum<{
+    /** Run `updates` once and leave it running. For a service whose `updates` never completes. */
+    Once: {};
+    /** Re-run `updates` this long after each pass completes. For a service that synchronizes in finite passes. */
+    WithDelay: {
+        readonly delay: Duration.DurationInput;
+    };
+}>;
+/**
+ * Constructors and matchers for {@link BackgroundRepeat}.
+ *
+ * @example
+ *   ```ts
+ *   const service: SyncService<CoreWallet, DustSecretKey, WalletSyncUpdate> = {
+ *     backgroundRepeat: BackgroundRepeat.Once(),
+ *     updates: (state, secretKey) => subscribe(state, secretKey),
+ *     blockData: () => latestBlock(),
+ *   };
+ *   ```;
+ */
+export declare const BackgroundRepeat: {
+    readonly Once: Data.Case.Constructor<{
+        readonly _tag: "Once";
+    }, "_tag">;
+    readonly WithDelay: Data.Case.Constructor<{
+        readonly _tag: "WithDelay";
+        readonly delay: Duration.DurationInput;
+    }, "_tag">;
+    readonly $is: <Tag extends "Once" | "WithDelay">(tag: Tag) => (u: unknown) => u is Extract<{
+        readonly _tag: "Once";
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "WithDelay";
+        readonly delay: Duration.DurationInput;
+    }, {
+        readonly _tag: Tag;
+    }>;
+    readonly $match: {
+        <const Cases extends {
+            readonly Once: (args: {
+                readonly _tag: "Once";
+            }) => any;
+            readonly WithDelay: (args: {
+                readonly _tag: "WithDelay";
+                readonly delay: Duration.DurationInput;
+            }) => any;
+        }>(cases: Cases & { [K in Exclude<keyof Cases, "Once" | "WithDelay">]: never; }): (value: {
+            readonly _tag: "Once";
+        } | {
+            readonly _tag: "WithDelay";
+            readonly delay: Duration.DurationInput;
+        }) => import("effect/Unify").Unify<ReturnType<Cases["Once" | "WithDelay"]>>;
+        <const Cases extends {
+            readonly Once: (args: {
+                readonly _tag: "Once";
+            }) => any;
+            readonly WithDelay: (args: {
+                readonly _tag: "WithDelay";
+                readonly delay: Duration.DurationInput;
+            }) => any;
+        }>(value: {
+            readonly _tag: "Once";
+        } | {
+            readonly _tag: "WithDelay";
+            readonly delay: Duration.DurationInput;
+        }, cases: Cases & { [K in Exclude<keyof Cases, "Once" | "WithDelay">]: never; }): import("effect/Unify").Unify<ReturnType<Cases["Once" | "WithDelay"]>>;
+    };
+};
 export interface SyncService<TState, TStartAux, TUpdate> {
     updates: (state: TState, auxData: TStartAux) => Stream.Stream<TUpdate, WalletError, Scope.Scope>;
     blockData: () => Effect.Effect<BlockData, WalletError>;
+    /** How often background synchronization re-runs {@link SyncService.updates}. See {@link BackgroundRepeat}. */
+    readonly backgroundRepeat: BackgroundRepeat;
 }
 export interface BlockData {
     hash: string;

package/dist/v1/Sync.js

@@ -10,7 +10,7 @@
 // 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, Layer, ParseResult, pipe, Schema, Stream, Duration, Chunk, Schedule, Option, identity, } from 'effect';
+import { Array as Arr, Data, Effect, Either, Layer, ParseResult, pipe, Schema, Stream, Duration, Chunk, Schedule, Option, identity, } from 'effect';
 import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
 import { LedgerParametersCodec } from '@midnight-ntwrk/wallet-sdk-capabilities/codecs';
 import { Event as LedgerEvent, LedgerParameters, } from '@midnight-ntwrk/ledger-v8';
@@ -18,10 +18,23 @@ import { BlockHash, DustLedgerEventTip, DustLedgerEvents } from '@midnight-ntwrk
 import { WsSubscriptionClient, HttpQueryClient, ConnectionHelper, } from '@midnight-ntwrk/wallet-sdk-indexer-client/effect';
 import { EitherOps } from '@midnight-ntwrk/wallet-sdk-utilities';
 import { WsURL } from '@midnight-ntwrk/wallet-sdk-utilities/networking';
-import { OtherWalletError, SyncWalletError } from './WalletError.js';
+import { OtherWalletError, OutOfOrderSyncUpdateError, SyncWalletError } from './WalletError.js';
 import { V8 } from '@midnight-ntwrk/wallet-sdk-capabilities/simulation';
 import { CoreWallet } from './CoreWallet.js';
 import { Uint8ArraySchema } from './Serialization.js';
+/**
+ * Constructors and matchers for {@link BackgroundRepeat}.
+ *
+ * @example
+ *   ```ts
+ *   const service: SyncService<CoreWallet, DustSecretKey, WalletSyncUpdate> = {
+ *     backgroundRepeat: BackgroundRepeat.Once(),
+ *     updates: (state, secretKey) => subscribe(state, secretKey),
+ *     blockData: () => latestBlock(),
+ *   };
+ *   ```;
+ */
+export const BackgroundRepeat = Data.taggedEnum();
 /**
  * The ledger parameters codecs this variant reads blocks with, unless it is told otherwise.
  *
@@ -244,6 +257,8 @@ const versionWatch = (config, resumeFrom, knownVersion) => {
 export const makeDefaultSyncService = (config) => {
     const indexerSyncService = makeIndexerSyncService(config);
     return {
+        // A long-lived indexer subscription: the one pass never ends, so there is nothing to repeat.
+        backgroundRepeat: BackgroundRepeat.Once(),
         updates: (state, secretKey) => {
             const batchSize = config.batchUpdates?.size ?? 10;
             const batchTimeout = Duration.millis(config.batchUpdates?.timeout ?? 1);
@@ -358,6 +373,26 @@ const applyVersionSignal = (state, update) => [
         : annotateVersion(state, Option.some(ProtocolVersion.ProtocolVersion(BigInt(update.version)))),
     noChanges(state),
 ];
+/**
+ * Checks that freshly delivered events arrive in strictly ascending id order.
+ *
+ * @remarks
+ *   Order is all that can be checked, never contiguity: dust events share one id sequence with zswap and contract events
+ *   in the indexer, so gaps in a dust stream are normal. A skipped commitment-inserting event is caught by the ledger's
+ *   own insertion check instead. An empty batch is trivially ordered.
+ * @param fresh The events left after the cursor filter, in source order.
+ * @param appliedIndex The highest event id already applied; the first fresh id must exceed it.
+ * @returns The batch unchanged, or the first id that fails to exceed its predecessor as an
+ *   {@link OutOfOrderSyncUpdateError}.
+ */
+const expectAscending = (fresh, appliedIndex) => pipe(Arr.zipWith(fresh, Arr.prepend(Arr.map(fresh, (item) => BigInt(item.id)), appliedIndex), (item, previous) => ({ item, previous })), Arr.findFirst(({ item, previous }) => BigInt(item.id) <= previous), Option.match({
+    onNone: () => Either.right(fresh),
+    onSome: ({ item, previous }) => Either.left(new OutOfOrderSyncUpdateError({
+        message: `Dust event ${item.id} delivered at or below its predecessor ${previous}; batch refused, applied index stays at ${appliedIndex}`,
+        expected: previous,
+        received: BigInt(item.id),
+    })),
+}));
 export const makeDefaultSyncCapability = () => {
     return {
         applyUpdate(state, wrappedUpdate, activeRange) {
@@ -374,7 +409,14 @@ export const makeDefaultSyncCapability = () => {
             // The tip is a property of the source, not of what this variant chose to apply, so it is read from the batch
             // tail even when the tail belongs to the next protocol version.
             const highestRelevantWalletIndex = BigInt(updates.at(-1).maxId);
-            const { applied, observedVersion } = splitAtVersionBoundary(freshUpdates, (update) => update.protocolVersion, activeRange);
+            // Refuse the whole batch: applying the sound prefix would move the cursor and hide the fault behind
+            // `isConnected: true`. State and cursor stay untouched, so the retry re-fetches the same range; a transient
+            // reorder heals, a persistent one fails visibly.
+            //
+            // `SyncCapability.applyUpdate` has no typed error channel, so throwing preserves its public tuple-returning API;
+            // `RunningV1Variant` catches this at the capability boundary. See #572 for the planned `Either`-based API.
+            const orderedUpdates = Either.getOrThrowWith(expectAscending(freshUpdates, appliedIndex), identity);
+            const { applied, observedVersion } = splitAtVersionBoundary(orderedUpdates, (update) => update.protocolVersion, activeRange);
             // Read here and nowhere earlier: `applied` is exactly the slice this variant owns, so nothing outside its
             // activation range — nor anything below its cursor — is ever handed to this ledger version's deserializer.
             const [newState, changes] = applied.length === 0
@@ -402,6 +444,8 @@ export const makeDefaultSyncCapability = () => {
 };
 export const makeSimulatorSyncService = (config) => {
     return {
+        // A live feed of simulator states: the one pass never ends, so there is nothing to repeat.
+        backgroundRepeat: BackgroundRepeat.Once(),
         updates: (_state, secretKey) => {
             // Get the initial state immediately to ensure we process the genesis block.
             // Then subscribe to state$ for subsequent changes, but deduplicate by block number

package/dist/v1/WalletError.d.ts

@@ -39,5 +39,30 @@ export declare class TransactionHistoryError extends TransactionHistoryError_bas
     cause?: unknown;
 }> {
 }
-export type WalletError = OtherWalletError | SyncWalletError | TransactingError | InsufficientFundsError | TransactionHistoryError | LedgerOps.LedgerError;
+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 dust 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: dust events share one id sequence with zswap 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 type WalletError = OtherWalletError | SyncWalletError | TransactingError | InsufficientFundsError | TransactionHistoryError | OutOfOrderSyncUpdateError | LedgerOps.LedgerError;
 export {};

package/dist/v1/WalletError.js

@@ -21,3 +21,19 @@ export class InsufficientFundsError extends Data.TaggedError('Wallet.Insufficien
 }
 export class TransactionHistoryError extends Data.TaggedError('Wallet.TransactionHistory') {
 }
+/**
+ * A batch of dust 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: dust events share one id sequence with zswap 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/v2/RunningV2Variant.d.ts

@@ -1,4 +1,4 @@
-import { Effect, Stream, Scope } from 'effect';
+import { Effect, Stream, Scope, Duration, Schedule } from 'effect';
 import { type TransactionHistoryService } from './TransactionHistory.js';
 import { type DustSecretKey, type Signature, type SignatureVerifyingKey, type FinalizedTransaction, type UnprovenTransaction } from '@midnightntwrk/ledger-v9';
 import { type WalletError } from './WalletError.js';
@@ -28,6 +28,14 @@ export declare namespace RunningV2Variant {
     type AnyContext = Context<any, any, any, any>;
 }
 export declare const V2Tag: unique symbol;
+/**
+ * How a failing synchronization pass is retried.
+ *
+ * @remarks
+ *   Exported so the delays it actually produces can be asserted. A schedule reads as though its combinators apply to the
+ *   delay, and for some of them they do not — which is worth pinning in a test rather than trusting by eye.
+ */
+export declare const syncRetrySchedule: Schedule.Schedule<[Duration.Duration, number], unknown, never>;
 export type DefaultRunningV2 = RunningV2Variant<string, SimulatorState, FinalizedTransaction, DustSecretKey>;
 export declare class RunningV2Variant<TSerialized, TSyncUpdate, TTransaction, TStartAux> implements Variant.RunningVariant<typeof V2Tag, CoreWallet> {
     #private;

package/dist/v2/RunningV2Variant.js

@@ -15,6 +15,7 @@ import { ProtocolVersion, Token } from '@midnight-ntwrk/wallet-sdk-abstractions'
 import { OtherWalletError } from './WalletError.js';
 import { ArrayOps, EitherOps } from '@midnight-ntwrk/wallet-sdk-utilities';
 import { StateChange, VersionChangeType, } from '@midnight-ntwrk/wallet-sdk-runtime/abstractions';
+import { BackgroundRepeat } from './Sync.js';
 const progress = (state) => {
     const appliedIndex = state.progress?.appliedIndex ?? 0n;
     const highestRelevantWalletIndex = state.progress?.highestRelevantWalletIndex ?? 0n;
@@ -48,6 +49,21 @@ const protocolVersionChange = (previous, current, isInitial, activationRange) =>
         : [];
 };
 export const V2Tag = Symbol('V2');
+/**
+ * How a failing synchronization pass is retried.
+ *
+ * @remarks
+ *   Exported so the delays it actually produces can be asserted. A schedule reads as though its combinators apply to the
+ *   delay, and for some of them they do not — which is worth pinning in a test rather than trusting by eye.
+ */
+export const syncRetrySchedule = pipe(Schedule.exponential(Duration.seconds(1), 2), Schedule.jittered, 
+// `union` retries as soon as either side would, so pairing the backoff with a fixed two-minute schedule takes the
+// shorter of the two — which is the backoff until it grows past two minutes, and two minutes from then on. Written
+// this way rather than as a `Schedule.map` over the delay: `map` rewrites a schedule's *output*, which it takes
+// **after** the delay has already been read from it, so mapping an exponential leaves the timing untouched. The
+// earlier form did exactly that, and backed off unboundedly — past an hour by the twelfth attempt — while reading
+// as though it were capped.
+Schedule.union(Schedule.spaced(Duration.minutes(2))));
 export class RunningV2Variant {
     __polyTag__ = V2Tag;
     #scope;
@@ -59,11 +75,26 @@ export class RunningV2Variant {
     #txHistoryPermits = Effect.makeSemaphore(8).pipe(Effect.runSync);
     state;
     #syncLock;
+    /**
+     * Whether a background synchronization worker is already running.
+     *
+     * @remarks
+     *   Distinct from {@link #syncLock}, which is released at the end of every pass and so says nothing about the worker
+     *   that runs them. Held for the worker's whole lifetime — polling delays and retries included — and released as it
+     *   exits, so a wallet started again while it is already synchronizing keeps the worker it has instead of gaining a
+     *   second one that polls alongside it until the wallet stops.
+     *
+     *   The guard asks only whether a worker is running, not what it was started with, so a second start is ignored even
+     *   when it carries different key material. Starting a running wallet on a second key is not a supported way to
+     *   change keys: stop it first. Two workers would be no better — they would apply two keys' updates to one state.
+     */
+    #backgroundWorkerLock;
     constructor(scope, context, v2Context) {
         this.#scope = scope;
         this.#context = context;
         this.#v2Context = v2Context;
         this.#syncLock = Effect.runSync(Ref.make(false));
+        this.#backgroundWorkerLock = Effect.runSync(Ref.make(false));
         this.state = Stream.fromEffect(context.stateRef.get).pipe(Stream.flatMap((initialState) => context.stateRef.changes.pipe(
         // The accumulator carries the "have we seen anything yet" flag alongside the previous state: the first
         // observation is the only one that can be a restored state nobody has inspected against this variant's
@@ -78,12 +109,29 @@ export class RunningV2Variant {
         }));
     }
     startSyncInBackground(startAux) {
-        return this.startSync(startAux).pipe(Stream.retry(pipe(Schedule.exponential(Duration.seconds(1), 2), Schedule.map((delay) => {
-            const maxDelay = Duration.minutes(2);
-            const jitter = Duration.millis(Math.floor(Math.random() * 1000));
-            const delayWithJitter = Duration.toMillis(delay) + Duration.toMillis(jitter);
-            return Duration.millis(Math.min(delayWithJitter, Duration.toMillis(maxDelay)));
-        }))), Stream.runScoped(Sink.drain), Effect.forkScoped, Effect.provideService(Scope.Scope, this.#scope));
+        // One pass, in a scope of its own. `Stream.runScoped` acquires into whichever scope it is handed, and the source's
+        // client layers take `Scope` as an input requirement rather than discharging one of their own — so a pass drained
+        // straight into the variant scope leaves its clients open there until the wallet stops, one more set per repeat.
+        // Scoping here closes them as the pass ends, on success, failure or interruption alike, and before any retry delay.
+        // The tx-history fan-out `startSync` forks is deliberately unaffected: it is pinned to the variant scope
+        // explicitly, and none of its work needs a client this scope holds.
+        const pass = this.startSync(startAux).pipe(Stream.runScoped(Sink.drain), Effect.scoped);
+        // Retrying the drained pass rather than the stream keeps the scope inside the retry: a failed attempt gives its
+        // resources back before the backoff, instead of holding them for the length of it.
+        const attempt = pass.pipe(Effect.retry(syncRetrySchedule));
+        // A service that synchronizes in finite passes would otherwise leave the wallet frozen at whatever its first pass
+        // saw. Repeating re-runs `startSync`, which re-reads the wallet state, so each pass resumes from what the previous
+        // one applied. The retry above cannot serve this purpose: it re-runs a pass on failure, not on completion.
+        // Repeating outside it keeps a transient failure to the pass it happened in, rather than restarting the cycle.
+        const worker = BackgroundRepeat.$match(this.#v2Context.syncService.backgroundRepeat, {
+            Once: () => attempt,
+            WithDelay: ({ delay }) => Effect.repeat(attempt, Schedule.spaced(delay)).pipe(Effect.asVoid),
+        });
+        // Taken before the worker is forked and given back as it exits, so the guard covers the gaps between passes that
+        // the sync lock cannot. A second start finds it held and leaves the running worker alone.
+        return Ref.modify(this.#backgroundWorkerLock, (isRunning) => [!isRunning, true]).pipe(Effect.flatMap((acquired) => acquired
+            ? worker.pipe(Effect.ensuring(Ref.set(this.#backgroundWorkerLock, false)), Effect.forkScoped, Effect.asVoid)
+            : Effect.void), Effect.provideService(Scope.Scope, this.#scope));
     }
     sync(startAux) {
         return this.startSync(startAux).pipe(Stream.runScoped(Sink.drain), Effect.scoped);

package/dist/v2/Sync.d.ts

@@ -1,4 +1,4 @@
-import { Array as Arr, Effect, Layer, Option, type Scope, Stream } from 'effect';
+import { Array as Arr, Data, Effect, Layer, Option, type Scope, Stream, Duration } from 'effect';
 import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
 import { type LedgerParametersCodec } from '@midnight-ntwrk/wallet-sdk-capabilities/codecs';
 import { type DustNullifier, type DustSecretKey, DustStateChanges, type DustLocalState, type LedgerParameters } from '@midnightntwrk/ledger-v9';
@@ -9,9 +9,91 @@ import { CoreWallet } from './CoreWallet.js';
 import { type NetworkId } from './types/ledger.js';
 import { type CollapsedMerkleTree, type DustGenerationsSubscription, type DustNullifierTransactionsSubscription, type DustProjectionsUpdate, type DustSpendProcessedEvent, type DustUtxoUpdate, DustUtxoMap, type WalletSyncSubscription, WalletSyncUpdate, type BlockData, type DustGenerationDtimUpdate, type NullifierRegularTransaction } from './SyncSchema.js';
 import { type Dust } from './types/index.js';
+/**
+ * How often background synchronization runs a sync service's `updates`.
+ *
+ * @remarks
+ *   Every service states this, because the answer cannot be inferred from the service: it follows from whether `updates`
+ *   is finite, which only the service knows. A service whose `updates` is a long-lived subscription is
+ *   {@link BackgroundRepeat.Once} — that single pass never ends, so there is nothing to repeat. A service that
+ *   synchronizes in finite passes is {@link BackgroundRepeat.WithDelay}, or a wallet synchronizing in the background
+ *   would converge once and then never observe anything again. The variant's background retry does not cover the
+ *   latter: it re-runs a pass on failure, not on completion.
+ */
+export type BackgroundRepeat = Data.TaggedEnum<{
+    /** Run `updates` once and leave it running. For a service whose `updates` never completes. */
+    Once: {};
+    /** Re-run `updates` this long after each pass completes. For a service that synchronizes in finite passes. */
+    WithDelay: {
+        readonly delay: Duration.DurationInput;
+    };
+}>;
+/**
+ * Constructors and matchers for {@link BackgroundRepeat}.
+ *
+ * @example
+ *   ```ts
+ *   const service: SyncService<CoreWallet, DustSecretKey, WalletSyncUpdate> = {
+ *     backgroundRepeat: BackgroundRepeat.Once(),
+ *     updates: (state, secretKey) => subscribe(state, secretKey),
+ *     blockData: () => latestBlock(),
+ *   };
+ *   ```;
+ */
+export declare const BackgroundRepeat: {
+    readonly Once: Data.Case.Constructor<{
+        readonly _tag: "Once";
+    }, "_tag">;
+    readonly WithDelay: Data.Case.Constructor<{
+        readonly _tag: "WithDelay";
+        readonly delay: Duration.DurationInput;
+    }, "_tag">;
+    readonly $is: <Tag extends "Once" | "WithDelay">(tag: Tag) => (u: unknown) => u is Extract<{
+        readonly _tag: "Once";
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "WithDelay";
+        readonly delay: Duration.DurationInput;
+    }, {
+        readonly _tag: Tag;
+    }>;
+    readonly $match: {
+        <const Cases extends {
+            readonly Once: (args: {
+                readonly _tag: "Once";
+            }) => any;
+            readonly WithDelay: (args: {
+                readonly _tag: "WithDelay";
+                readonly delay: Duration.DurationInput;
+            }) => any;
+        }>(cases: Cases & { [K in Exclude<keyof Cases, "Once" | "WithDelay">]: never; }): (value: {
+            readonly _tag: "Once";
+        } | {
+            readonly _tag: "WithDelay";
+            readonly delay: Duration.DurationInput;
+        }) => import("effect/Unify").Unify<ReturnType<Cases["Once" | "WithDelay"]>>;
+        <const Cases extends {
+            readonly Once: (args: {
+                readonly _tag: "Once";
+            }) => any;
+            readonly WithDelay: (args: {
+                readonly _tag: "WithDelay";
+                readonly delay: Duration.DurationInput;
+            }) => any;
+        }>(value: {
+            readonly _tag: "Once";
+        } | {
+            readonly _tag: "WithDelay";
+            readonly delay: Duration.DurationInput;
+        }, cases: Cases & { [K in Exclude<keyof Cases, "Once" | "WithDelay">]: never; }): import("effect/Unify").Unify<ReturnType<Cases["Once" | "WithDelay"]>>;
+    };
+};
 export interface SyncService<TState, TStartAux, TUpdate> {
     updates: (state: TState, auxData: TStartAux) => Stream.Stream<TUpdate, WalletError, Scope.Scope>;
     blockData: (height?: number) => Effect.Effect<BlockData, WalletError>;
+    /** How often background synchronization re-runs {@link SyncService.updates}. See {@link BackgroundRepeat}. */
+    readonly backgroundRepeat: BackgroundRepeat;
 }
 export type ChangesResult = {
     readonly changes: DustStateChanges[];
@@ -121,6 +203,19 @@ export type DefaultSyncConfiguration = {
     versionWatch?: VersionWatchConfig;
     /** The ledger parameters codecs blocks are read with; defaults to {@link defaultLedgerParametersCodecs}. */
     ledgerParametersCodecs?: LedgerParametersCodec.LedgerParametersCodecs<LedgerParameters>;
+    /**
+     * Delay in milliseconds between background synchronization passes, for a sync service that synchronizes in finite
+     * passes rather than over a live subscription — currently only the projections service. Ignored by the event-based
+     * service, whose subscription never completes.
+     *
+     * Lower values keep the wallet closer to the chain tip at the cost of more idle queries; a pass with nothing to do
+     * costs one block query, because the generation subscription and the commitment load both short-circuit on an
+     * unchanged tip. Passes never overlap regardless of this value: a pass that cannot take the sync lock yields to the
+     * one already running and waits for the next interval.
+     *
+     * @default 5000
+     */
+    backgroundSyncInterval?: number;
 };
 export type SimulatorSyncConfiguration = {
     simulator: Simulator;
@@ -136,6 +231,23 @@ export declare const SecretKeysResource: {
 };
 export declare const makeDefaultSyncService: (config: DefaultSyncConfiguration) => SyncService<CoreWallet, DustSecretKey, WalletSyncUpdate>;
 export declare const nullifierPhaseProgress: (mtIndicesSum: bigint, totalNullifiers: number, freshCount: number, maxCommitmentEndIndex: number) => number;
+/**
+ * The applied index a mid-phase nullifier report carries, on the same basis as every other report in the pass.
+ *
+ * @remarks
+ *   The nullifier term is the larger of two true statements about the same work. {@link nullifierPhaseProgress} measures
+ *   this phase from zero, while the report that opened the phase already credited the nullifiers the wallet arrived
+ *   holding; early in the phase the credit is the further along of the two, and reporting the measurement alone would
+ *   take progress backwards.
+ * @param basis The two terms this phase does not advance: commitment work, and nullifier work already credited.
+ * @param generationWork The generation term, which is complete by the time this phase runs.
+ * @param phaseProgress What {@link nullifierPhaseProgress} has measured so far.
+ * @returns The applied index to report.
+ */
+export declare const nullifierPhaseAppliedIndex: (basis: {
+    readonly commitmentWork: number;
+    readonly creditedNullifierWork: number;
+}, generationWork: number, phaseProgress: number) => number;
 export declare const doEventlessSync: (state: CoreWallet, secretKey: DustSecretKey, anonymityLevel: number, indexerSyncService: IndexerSyncService, ledgerParametersCodecs?: LedgerParametersCodec.LedgerParametersCodecs<LedgerParameters>) => Stream.Stream<DustProjectionsUpdate, WalletError, Scope.Scope | QueryClient | SubscriptionClient>;
 export declare const makeEventLessSyncService: (config: DefaultSyncConfiguration) => SyncService<CoreWallet, DustSecretKey, DustProjectionsUpdate>;
 export type IndexerSyncService = {

package/dist/v2/Sync.js

@@ -10,7 +10,7 @@
 // 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 { Array as Arr, Effect, Either, HashMap, HashSet, Layer, Option, pipe, Schema, Stream, Duration, Chunk, Schedule, identity, } from 'effect';
+import { Array as Arr, Data, Effect, Either, HashMap, HashSet, Layer, Option, pipe, Schema, Stream, Duration, Chunk, Schedule, identity, } from 'effect';
 import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
 import { dustNullifier, successorDustUtxo, DustStateChanges, } from '@midnightntwrk/ledger-v9';
 import { DustAddress } from '@midnight-ntwrk/wallet-sdk-address-format';
@@ -18,11 +18,24 @@ import { DustGenerationEvents, BlockHash, DustLedgerEventTip, DustLedgerEvents,
 import { WsSubscriptionClient, HttpQueryClient, ConnectionHelper, } from '@midnight-ntwrk/wallet-sdk-indexer-client/effect';
 import { EitherOps } from '@midnight-ntwrk/wallet-sdk-utilities';
 import { WsURL } from '@midnight-ntwrk/wallet-sdk-utilities/networking';
-import { OtherWalletError, SyncWalletError } from './WalletError.js';
+import { OtherWalletError, OutOfOrderSyncUpdateError, SyncWalletError } from './WalletError.js';
 import { getLastBlock } from '@midnight-ntwrk/wallet-sdk-capabilities/simulation';
 import { CoreWallet } from './CoreWallet.js';
 import { CollapsedMerkleTreeSchema, DustGenerationsSubscriptionSchema, DustGenerationsSyncUpdate, DustNullifierTransactionSubscriptionSchema, DustUtxoMap, SyncEventsUpdateSchema, VersionSignalSyncUpdate, WalletSyncUpdate, defaultLedgerParametersCodecs, makeBlockDataSchema, ProgressUpdate, StateUpdate, isProgressUpdate, readEvent, readNullifierBlockParameters, tryReadEvent, } from './SyncSchema.js';
 import { bigintToLeHex, calculatePrefixLength, gapRanges, hashMapGroupBy, leBigintToHex, uniqueArray, } from './Utils.js';
+/**
+ * Constructors and matchers for {@link BackgroundRepeat}.
+ *
+ * @example
+ *   ```ts
+ *   const service: SyncService<CoreWallet, DustSecretKey, WalletSyncUpdate> = {
+ *     backgroundRepeat: BackgroundRepeat.Once(),
+ *     updates: (state, secretKey) => subscribe(state, secretKey),
+ *     blockData: () => latestBlock(),
+ *   };
+ *   ```;
+ */
+export const BackgroundRepeat = Data.taggedEnum();
 /**
  * Splits a batch of version-tagged items at the end of a variant's activation range.
  *
@@ -155,6 +168,8 @@ export const SecretKeysResource = {
 export const makeDefaultSyncService = (config) => {
     const indexerSyncService = makeIndexerSyncService(config);
     return {
+        // A long-lived indexer subscription: the one pass never ends, so there is nothing to repeat.
+        backgroundRepeat: BackgroundRepeat.Once(),
         updates: (state, secretKey) => {
             const batchSize = config.batchUpdates?.size ?? 10;
             const batchTimeout = Duration.millis(config.batchUpdates?.timeout ?? 1);
@@ -205,7 +220,26 @@ const NULLIFIER_LENGTH = NULLIFIER_BYTE_LENGTH * 2;
 // counts as a full scan of the commitment space; a still-live chain counts up to the merkle index of its freshest
 // successor. Bounded by totalNullifiers * maxCommitmentEndIndex (the phase ceiling).
 export const nullifierPhaseProgress = (mtIndicesSum, totalNullifiers, freshCount, maxCommitmentEndIndex) => Math.min(Number(mtIndicesSum) + (totalNullifiers - freshCount) * maxCommitmentEndIndex, totalNullifiers * maxCommitmentEndIndex);
-const resolveNullifierSpends = (initialNullifiers, initialNewUtxos, pendingDust, dustState, secretKey, latestBlock, dustGenerationUpdates, indexerSyncService, anonymityLevel, ledgerParametersCodecs, emit) => {
+/**
+ * The applied index a mid-phase nullifier report carries, on the same basis as every other report in the pass.
+ *
+ * @remarks
+ *   The nullifier term is the larger of two true statements about the same work. {@link nullifierPhaseProgress} measures
+ *   this phase from zero, while the report that opened the phase already credited the nullifiers the wallet arrived
+ *   holding; early in the phase the credit is the further along of the two, and reporting the measurement alone would
+ *   take progress backwards.
+ * @param basis The two terms this phase does not advance: commitment work, and nullifier work already credited.
+ * @param generationWork The generation term, which is complete by the time this phase runs.
+ * @param phaseProgress What {@link nullifierPhaseProgress} has measured so far.
+ * @returns The applied index to report.
+ */
+export const nullifierPhaseAppliedIndex = (basis, generationWork, phaseProgress) => generationWork + basis.commitmentWork + Math.max(basis.creditedNullifierWork, phaseProgress);
+const resolveNullifierSpends = (initialNullifiers, initialNewUtxos, pendingDust, dustState, secretKey, latestBlock, dustGenerationUpdates, indexerSyncService, anonymityLevel, ledgerParametersCodecs, 
+/**
+ * The two terms of the pass's progress basis this phase does not itself advance, so that the progress it reports is a
+ * sum on the same basis as every other report rather than a figure of its own.
+ */
+progressBasis, emit) => {
     const maxCommitmentEndIndex = latestBlock.dustCommitmentEndIndex - 1;
     const initialSpentUtxos = HashMap.empty();
     return pipe(Stream.unfoldEffect([initialNullifiers, initialNewUtxos, initialSpentUtxos], ([nullifiersToCheck, newUtxos, spentUtxos]) => {
@@ -222,8 +256,13 @@ const resolveNullifierSpends = (initialNullifiers, initialNewUtxos, pendingDust,
                 const mtIndicesSum = freshUtxos.reduce((partialSum, a) => partialSum + a.qdo.mtIndex, 0n);
                 const generationEndIndex = latestBlock.dustGenerationEndIndex - 1;
                 const progress = nullifierPhaseProgress(mtIndicesSum, initialNullifiers.length, freshUtxos.length, maxCommitmentEndIndex);
-                // NOTE: since this process goes after the generation updates, we need to add the generationEndIndex to the progress
-                yield* Effect.promise(() => emit.single(ProgressUpdate({ appliedIndex: progress + generationEndIndex })));
+                // This phase runs after the generation updates, so its term sits on top of a completed generation tree and
+                // the commitment work the wallet already had. `nullifierPhaseProgress` counts this phase from zero, so on
+                // an early iteration it can still be behind the credit report 2 gave for nullifiers the wallet arrived
+                // holding; the larger of the two is the one that is true.
+                yield* Effect.promise(() => emit.single(ProgressUpdate({
+                    appliedIndex: nullifierPhaseAppliedIndex(progressBasis, generationEndIndex, progress),
+                })));
             }
             const { nextUtxos, nextSpentUtxos } = accumulateUtxoUpdates(dustUtxoUpdates, newUtxos, spentUtxos);
             const nextNullifiersToCheck = dustUtxoUpdates.filter((u) => !u.isSpent).map((u) => u.dustNullifier);
@@ -242,10 +281,15 @@ export const doEventlessSync = (state, secretKey, anonymityLevel, indexerSyncSer
         const lastSyncedCommitmentIndex = state.state.commitmentTreeFirstFree - 1n;
         const lastSyncedGenerationIndex = state.state.generatingTreeFirstFree - 1n;
         const lastSyncedBlockHeight = state.progress.highestIndex;
-        const highestInitialIndex = maxGeneratingTreeIndex + maxCommitmentTreeIndex + state.state.nullifiers.size * maxCommitmentTreeIndex;
-        const initialAppliedIndex = Number(lastSyncedGenerationIndex) +
-            Number(lastSyncedCommitmentIndex) +
-            state.state.nullifiers.size * Number(maxCommitmentTreeIndex);
+        // Every report this pass makes is a sum of the same three terms — generation work, commitment work, nullifier
+        // work — against a total on that same basis. A report that leaves one of them out does not read as "less far
+        // along"; it reads as progress going *backwards*, because the terms it drops were already counted. That
+        // matters beyond cosmetics: `isSynced` is exact equality between the applied and relevant indexes, so a
+        // settled wallet whose pass undercounts flips to "not synced" and back on every background repeat.
+        const commitmentWork = Number(lastSyncedCommitmentIndex);
+        const creditedNullifierWork = state.state.nullifiers.size * maxCommitmentTreeIndex;
+        const highestInitialIndex = maxGeneratingTreeIndex + maxCommitmentTreeIndex + creditedNullifierWork;
+        const initialAppliedIndex = Number(lastSyncedGenerationIndex) + commitmentWork + creditedNullifierWork;
         // What this pass resumed from, in one line. A projections pass is a single snapshot fetch, so when it comes back
         // with less than expected the only question worth asking is where it started — and the three cursors that decide
         // that are otherwise invisible to anything outside this function, including to a wallet that arrived here by
@@ -261,12 +305,20 @@ export const doEventlessSync = (state, secretKey, anonymityLevel, indexerSyncSer
             .map((n) => n.dustNullifier)
             .concat([...state.state.nullifiers.keys(), ...state.pendingDust.map((d) => d.nullifier)]);
         const highestRelevantIndex = maxGeneratingTreeIndex + maxCommitmentTreeIndex + allNullifiers.length * maxCommitmentTreeIndex;
-        // increase the highestRelevantIndex as our nullifier list got expanded by new generations
-        // appliedIndex now reflects the completed generation tree sync
-        yield* Effect.promise(() => emit.single(ProgressUpdate({ highestRelevantIndex, appliedIndex: maxGeneratingTreeIndex })));
+        // The generation tree is now synced to the chain's end index, so its term becomes the full
+        // `maxGeneratingTreeIndex`. The commitment and nullifier terms are carried across untouched — this phase did
+        // not undo them. `highestRelevantIndex` rises here because new generations added nullifiers to check.
+        yield* Effect.promise(() => emit.single(ProgressUpdate({
+            highestRelevantIndex,
+            appliedIndex: maxGeneratingTreeIndex + commitmentWork + creditedNullifierWork,
+        })));
         const newUtxos = DustUtxoMap.create(dustGenerationUpdates.newGenerations);
-        const { nextUtxos: finalUtxos, nextSpentUtxos: finalSpentUtxos } = yield* resolveNullifierSpends(allNullifiers, newUtxos, CoreWallet.pendingDustToMap(state.pendingDust), state.state, secretKey, latestBlock, dustGenerationUpdates, indexerSyncService, anonymityLevel, ledgerParametersCodecs, emit);
-        yield* Effect.promise(() => emit.single(ProgressUpdate({ appliedIndex: maxGeneratingTreeIndex + allNullifiers.length * maxCommitmentTreeIndex })));
+        const { nextUtxos: finalUtxos, nextSpentUtxos: finalSpentUtxos } = yield* resolveNullifierSpends(allNullifiers, newUtxos, CoreWallet.pendingDustToMap(state.pendingDust), state.state, secretKey, latestBlock, dustGenerationUpdates, indexerSyncService, anonymityLevel, ledgerParametersCodecs, { commitmentWork, creditedNullifierWork }, emit);
+        // Every nullifier has been resolved, so the nullifier term reaches its full width. The commitment phase has
+        // not run yet, so its term is still what the wallet arrived holding.
+        yield* Effect.promise(() => emit.single(ProgressUpdate({
+            appliedIndex: maxGeneratingTreeIndex + commitmentWork + allNullifiers.length * maxCommitmentTreeIndex,
+        })));
         // lastSyncedCommitmentIndex out of maxCommitmentTreeIndex
         const collapsedCommitments = yield* loadCollapsedCommitments(Number(lastSyncedCommitmentIndex), maxCommitmentTreeIndex, finalUtxos, indexerSyncService);
         yield* Effect.promise(() => emit.single(StateUpdate({
@@ -279,13 +331,21 @@ export const doEventlessSync = (state, secretKey, anonymityLevel, indexerSyncSer
         // NOTE: appliedIndex = highestRelevantIndex means we're fully synced
         yield* Effect.promise(() => emit.single(ProgressUpdate({ appliedIndex: highestRelevantIndex })));
         yield* Effect.promise(() => emit.end());
-    }));
+    }), 
+    // The whole pass runs inside this register effect, and Effect only starts draining the stream once that effect
+    // returns — so every update a pass emits has to sit in the buffer simultaneously. The default buffer is bounded
+    // (16), which caps the sync at a handful of Dust spends: the emission that overflows it suspends waiting for
+    // capacity no consumer is running to free, and the pass deadlocks silently rather than failing. A pass emits one
+    // update per resolved spend, so the ceiling is reached by any wallet with a modest spend history.
+    'unbounded');
 };
 export const makeEventLessSyncService = (config) => {
     const defaultSyncService = makeDefaultSyncService(config);
     const indexerSyncService = makeIndexerSyncService(config);
     const anonymityLevel = config.anonymityLevel ?? 7;
     return {
+        // Each pass ends its own stream, so background synchronization has to be told to run another one.
+        backgroundRepeat: BackgroundRepeat.WithDelay({ delay: Duration.millis(config.backgroundSyncInterval ?? 5_000) }),
         updates: (state, secretKey) => pipe(doEventlessSync(state, secretKey, anonymityLevel, indexerSyncService, config.ledgerParametersCodecs ?? defaultLedgerParametersCodecs), Stream.provideSomeLayer(Layer.merge(indexerSyncService.connectionLayer(), indexerSyncService.queryClient()))),
         blockData: defaultSyncService.blockData,
     };
@@ -401,6 +461,26 @@ const applyVersionSignal = (state, update) => [
         : annotateVersion(state, Option.some(ProtocolVersion.ProtocolVersion(BigInt(update.version)))),
     noChanges(state),
 ];
+/**
+ * Checks that freshly delivered events arrive in strictly ascending id order.
+ *
+ * @remarks
+ *   Order is all that can be checked, never contiguity: dust events share one id sequence with zswap and contract events
+ *   in the indexer, so gaps in a dust stream are normal. A skipped commitment-inserting event is caught by the ledger's
+ *   own insertion check instead. An empty batch is trivially ordered.
+ * @param fresh The events left after the cursor filter, in source order.
+ * @param appliedIndex The highest event id already applied; the first fresh id must exceed it.
+ * @returns The batch unchanged, or the first id that fails to exceed its predecessor as an
+ *   {@link OutOfOrderSyncUpdateError}.
+ */
+const expectAscending = (fresh, appliedIndex) => pipe(Arr.zipWith(fresh, Arr.prepend(Arr.map(fresh, (item) => BigInt(item.id)), appliedIndex), (item, previous) => ({ item, previous })), Arr.findFirst(({ item, previous }) => BigInt(item.id) <= previous), Option.match({
+    onNone: () => Either.right(fresh),
+    onSome: ({ item, previous }) => Either.left(new OutOfOrderSyncUpdateError({
+        message: `Dust event ${item.id} delivered at or below its predecessor ${previous}; batch refused, applied index stays at ${appliedIndex}`,
+        expected: previous,
+        received: BigInt(item.id),
+    })),
+}));
 export const makeDefaultSyncCapability = () => {
     return {
         applyUpdate(state, wrappedUpdate, activeRange) {
@@ -417,7 +497,14 @@ export const makeDefaultSyncCapability = () => {
             // The tip is a property of the source, not of what this variant chose to apply, so it is read from the batch
             // tail even when the tail belongs to the next protocol version.
             const highestRelevantWalletIndex = BigInt(updates.at(-1).maxId);
-            const { applied, observedVersion } = splitAtVersionBoundary(freshUpdates, (update) => update.protocolVersion, activeRange);
+            // Refuse the whole batch: applying the sound prefix would move the cursor and hide the fault behind
+            // `isConnected: true`. State and cursor stay untouched, so the retry re-fetches the same range; a transient
+            // reorder heals, a persistent one fails visibly.
+            //
+            // `SyncCapability.applyUpdate` has no typed error channel, so throwing preserves its public tuple-returning API;
+            // `RunningV2Variant` catches this at the capability boundary. See #572 for the planned `Either`-based API.
+            const orderedUpdates = Either.getOrThrowWith(expectAscending(freshUpdates, appliedIndex), identity);
+            const { applied, observedVersion } = splitAtVersionBoundary(orderedUpdates, (update) => update.protocolVersion, activeRange);
             // Read here and nowhere earlier: `applied` is exactly the slice this variant owns, so nothing outside its
             // activation range — nor anything below its cursor — is ever handed to this ledger version's deserializer.
             const [newState, changes] = applied.length === 0
@@ -569,6 +656,8 @@ export const matchedDustSpends = (nullifierTransactions) => pipe(nullifierTransa
 export const createDustUtxoUpdates = (dustState, spends, secretKey, knownUtxos, pendingDust, generationDtimeUpdates, ledgerParametersCodecs = defaultLedgerParametersCodecs) => pipe(spends, Arr.map(({ transaction, dustSpend }) => createUtxoUpdatesFromSpend(dustState, secretKey, knownUtxos, pendingDust, generationDtimeUpdates, transaction, dustSpend, ledgerParametersCodecs)), Effect.all, Effect.map(Arr.getSomes), Effect.map(Arr.flatten));
 export const makeSimulatorSyncService = (config) => {
     return {
+        // A live feed of simulator states: the one pass never ends, so there is nothing to repeat.
+        backgroundRepeat: BackgroundRepeat.Once(),
         updates: (_state, secretKey) => {
             // Get the initial state immediately to ensure we process the genesis block.
             // Then subscribe to state$ for subsequent changes, but deduplicate by block number

package/dist/v2/WalletError.d.ts

@@ -39,5 +39,30 @@ export declare class TransactionHistoryError extends TransactionHistoryError_bas
     cause?: unknown;
 }> {
 }
-export type WalletError = OtherWalletError | SyncWalletError | TransactingError | InsufficientFundsError | TransactionHistoryError | LedgerOps.LedgerError;
+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 dust 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: dust events share one id sequence with zswap 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 type WalletError = OtherWalletError | SyncWalletError | TransactingError | InsufficientFundsError | TransactionHistoryError | OutOfOrderSyncUpdateError | LedgerOps.LedgerError;
 export {};

package/dist/v2/WalletError.js

@@ -21,3 +21,19 @@ export class InsufficientFundsError extends Data.TaggedError('Wallet.Insufficien
 }
 export class TransactionHistoryError extends Data.TaggedError('Wallet.TransactionHistory') {
 }
+/**
+ * A batch of dust 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: dust events share one id sequence with zswap 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midnight-ntwrk/wallet-sdk-dust-wallet",
-  "version": "5.0.0-beta.3",
+  "version": "5.0.0-beta.4",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -35,12 +35,12 @@
   },
   "dependencies": {
     "@midnight-ntwrk/ledger-v8": "^8.1.0",
-    "@midnightntwrk/ledger-v9": "1.0.0-rc.4",
-    "@midnight-ntwrk/wallet-sdk-abstractions": "3.0.0-beta.1",
-    "@midnight-ntwrk/wallet-sdk-address-format": "4.0.0-beta.3",
-    "@midnight-ntwrk/wallet-sdk-capabilities": "4.0.0-beta.3",
+    "@midnightntwrk/ledger-v9": "1.0.0-rc.5",
+    "@midnight-ntwrk/wallet-sdk-abstractions": "3.0.0-beta.2",
+    "@midnight-ntwrk/wallet-sdk-address-format": "4.0.0-beta.4",
+    "@midnight-ntwrk/wallet-sdk-capabilities": "4.0.0-beta.4",
     "@midnight-ntwrk/wallet-sdk-indexer-client": "2.0.0-beta.2",
-    "@midnight-ntwrk/wallet-sdk-runtime": "1.1.0-beta.1",
+    "@midnight-ntwrk/wallet-sdk-runtime": "1.1.0-beta.2",
     "@midnight-ntwrk/wallet-sdk-utilities": "1.2.2-beta.0",
     "effect": "^3.19.19",
     "rxjs": "^7.8.2"
@@ -59,6 +59,6 @@
     "publint": "publint --strict"
   },
   "devDependencies": {
-    "@midnight-ntwrk/wallet-sdk-hd": "^3.1.0-beta.2"
+    "@midnight-ntwrk/wallet-sdk-hd": "^3.1.0-beta.3"
   }
 }