@midnightntwrk/wallet-sdk-testkit 1.0.0-beta.3 → 1.0.0-beta.4

package/README.md

@@ -11,7 +11,8 @@ files.
 | -------------------- | ------------------------------------------------------------------------------------------------------------- |
 | Environment          | `createRemoteEnvironment`, `NETWORK_PRESETS`, `makeEnvironment`, `WalletTestEnvironment`, `ResolvedEndpoints` |
 | Environment (Docker) | `createTestContainersEnvironment` — from `@midnightntwrk/wallet-sdk-testkit/testcontainers`                   |
-| Wallet               | `provideWallet`, `initWalletWithSeed`, `saveState`, `WalletInit`                                              |
+| Wallet               | `provideWallet`, `initWalletWithSeed`, `saveState`, `shouldPersistState`, `WalletInit`                        |
+| Dust sync model      | `dustWalletFromEnv`, `dustWalletFor`, `DustSyncModel`, `projectionsDustSyncOptions`, … — see below            |
 | Seeds                | `getShieldedSeed`, `getUnshieldedSeed`, `getDustSeed`                                                         |
 | Sync waiters         | `waitForSyncUnshielded`, `waitForDustBalance`, `waitForTxInHistory`, …                                        |
 | Assertions           | `expectSenderShieldedTxHistory`, `expectReceiverUnshieldedTxHistory`, …                                       |
@@ -61,6 +62,53 @@ import { createTestContainersEnvironment } from '@midnightntwrk/wallet-sdk-testk
 const getEnv = useWalletTestEnvironment(() => createTestContainersEnvironment({ network: 'undeployed' }));
 ```
 
+## Choosing the Dust sync model
+
+Dust can sync from the indexer's event stream or from its projections (the "event-less" fast sync). `DUST_SYNC` selects
+which, for a whole run:
+
+```bash
+DUST_SYNC=projections yarn test-remote -- -t @healthcheck
+```
+
+Unset, `provideWallet` and `initWalletWithSeed` build the event-based sync; the dust and token-transfer healthcheck
+scenarios fall back to projections instead, so the network being monitored is exercised against the model the wallet
+ships to users. `DUST_SYNC` overrides both, so a run can never end up half on one model and half on the other. An
+unrecognized value is rejected rather than defaulted, so a typo cannot report a run as covering a model it did not
+exercise.
+
+A test that needs a specific model regardless of the environment pins it in code, which does override `DUST_SYNC`:
+
+```ts
+provideWallet(env, { ...projectionsDustSyncOptions, seed, syncCacheDir, filename });
+```
+
+Use `manualProjectionsDustSyncOptions` instead when the test drives each sync pass itself with `facade.doSync()`; the
+plain `projectionsDustSyncOptions` leaves background synchronization on, so the usual state waiters work unchanged.
+
+Pin a model only when the test genuinely requires it. A pinned wallet stops following `DUST_SYNC`, so a lane switched by
+environment will leave it behind — which reports coverage the run did not have.
+
+### Building a Dust wallet directly
+
+A test that constructs its own Dust wallet rather than going through the helpers must build it from the same source, or
+it will silently disagree with the rest of the run:
+
+```ts
+const Dust = dustWalletFromEnv()({ ...walletConfig, ...env.getDustWalletConfig() });
+```
+
+This matters most for serialize/restore tests. The two models disagree about the meaning of the single progress value a
+Dust snapshot carries — an event cursor to one, a composite of tree indices and nullifier count to the other — so state
+written by one model and restored into the other resumes from a position that is not a cursor at all, and the wallet
+never reports synced. Hard-coding `DustWallet(...)` as the restore target while the run uses projections does exactly
+that.
+
+Snapshots on disk are protected from this automatically: they are stored per model, so switching models finds no
+snapshot and rebuilds from scratch rather than resuming wrongly, with no cache to clear by hand. That protection does
+not extend to state serialized and restored in memory within a test — hence the rule above. The shielded and unshielded
+snapshots are model-independent and shared.
+
 ## Peer dependencies
 
 - `vitest` — required (assertions and the environment hooks use it).

package/dist/core.d.ts

@@ -5,3 +5,4 @@ export * from './network.js';
 export * from './seeds.js';
 export * from './primitives.js';
 export * from './wallet.js';
+export * from './dust-sync.js';

package/dist/core.js

@@ -22,3 +22,4 @@ export * from './network.js';
 export * from './seeds.js';
 export * from './primitives.js';
 export * from './wallet.js';
+export * from './dust-sync.js';

package/dist/dust-sync.d.ts

@@ -0,0 +1,126 @@
+import { type DustParameters } from '@midnightntwrk/ledger-v9';
+import { type DefaultDustConfiguration, type DustWalletAPI } from '@midnightntwrk/wallet-sdk-dust-wallet';
+/**
+ * The factory shape {@link provideWallet} and the scenarios accept for the dust sub-wallet.
+ *
+ * Structural rather than `DustWalletClass`, so a single-variant composition is acceptable too — but note that
+ * {@link eventLessDustWallet}, the projections factory this exists for, is **not** one: it is the shipped two-variant
+ * wallet with the V2 variant's sync service swapped, which is what lets it build transactions as well as sync. On a
+ * chain running ledger-v9 from its first block the V1 variant never applies, so it reaches the projections sync
+ * immediately. A start resolving asynchronously is accepted because such a wallet may ask the chain where it is before
+ * it picks a variant.
+ */
+export type DustWalletFactory = (config: DefaultDustConfiguration) => {
+    startWithSeed(seed: Uint8Array, dustParameters?: DustParameters): DustWalletAPI | Promise<DustWalletAPI>;
+    /** Also required, because `provideWallet` restores a snapshot into whatever composition it was given. */
+    restore(serializedState: string): DustWalletAPI;
+};
+/**
+ * A dust sub-wallet that syncs from indexer projections instead of the event stream.
+ *
+ * The shipped `DustWallet` with exactly one substitution — the V2 variant's sync service. The V1 variant keeps the
+ * event stream, because the projections sync is a ledger-v9 capability: it rests on `DustLocalState` members no
+ * ledger-v8 has. On a chain that runs ledger-v9 from its first block the V1 variant never applies, so a wallet built
+ * this way reaches the projections sync immediately.
+ *
+ * The projections sync synchronizes in finite passes rather than over a live subscription, but background
+ * synchronization re-runs those passes on an interval, so this factory can be used on its own and the usual state
+ * waiters behave as they do for the event-based sync. Pair it with `manualSync` — see
+ * {@link manualProjectionsDustSyncOptions} — only when a caller wants to decide when each pass happens.
+ *
+ * **Both variants are registered, so a wallet built this way transacts.** A single-variant composition would answer for
+ * the whole protocol timeline and therefore report the minimum supported version; because a facade acts at the lowest
+ * version its three sub-wallets report, such a sub-wallet holds the facade below the ledger-v9 boundary and the facade
+ * then refuses the shielded wallet's ledger-v9 transaction, the two sides of a boundary being unmergeable. Registering
+ * both variants leaves the version to the chain, which is what lets the healthcheck scenarios pay fees and transfer
+ * while syncing their Dust from projections.
+ */
+export declare const eventLessDustWallet: DustWalletFactory;
+/**
+ * The event-stream dust sub-wallet, with the long-lived subscription.
+ *
+ * A dust snapshot stores one progress value, `appliedIndex`, and the two sync models mean different things by it: this
+ * service treats it as a ledger-event cursor to resume its subscription from, while the projections service writes a
+ * composite of tree indices and nullifier count. Restoring a projections-written snapshot here would therefore resume
+ * the subscription from a position that is not an event id at all, and because the cursor is trusted rather than
+ * validated, the effect would be silently skipped events rather than an error.
+ *
+ * Callers do not have to guard against that: dust snapshots are stored per sync model (see {@link dustSnapshotPath}), so
+ * switching a wallet's model finds no snapshot and rebuilds from scratch instead of resuming from a cursor that is not
+ * one.
+ */
+export declare const eventBasedDustWallet: DustWalletFactory;
+/** Which of the two dust sync implementations a wallet is built with. */
+export type DustSyncModel = 'events' | 'projections';
+/**
+ * How a dust snapshot on disk is labelled with the sync model that wrote it.
+ *
+ * `custom` covers a caller-supplied factory whose model cannot be identified. Giving it its own namespace is the safe
+ * default: an unidentified factory then shares a snapshot with neither known model rather than with the wrong one.
+ */
+export type DustSnapshotModel = DustSyncModel | 'custom';
+/** The dust sub-wallet factory for a sync model. */
+export declare const dustWalletFor: (model: DustSyncModel) => DustWalletFactory;
+/** The sync model a factory implements, or `custom` if it is neither of the two built-in ones. */
+export declare const dustSyncModelOf: (factory: DustWalletFactory) => DustSnapshotModel;
+/** Environment variable selecting the dust sync model for a whole test run. */
+export declare const DUST_SYNC_ENV_VAR = "DUST_SYNC";
+/**
+ * Reads a dust sync model from its environment-variable spelling, falling back to `fallback` when unset or empty.
+ *
+ * An unrecognized value is rejected rather than defaulted. A silent fallback would mean a typo in `DUST_SYNC` reports a
+ * run as covering one sync model while it actually covered the other, which is worse than not running at all.
+ *
+ * @throws Error if `raw` is neither empty nor a known model
+ */
+export declare const parseDustSyncModel: (raw: string | undefined, fallback?: DustSyncModel) => DustSyncModel;
+/** The dust sync model selected by `DUST_SYNC`, or `fallback` when it is unset. */
+export declare const dustSyncModelFromEnv: (env?: Record<string, string | undefined>, fallback?: DustSyncModel) => DustSyncModel;
+/**
+ * The dust sub-wallet factory selected by `DUST_SYNC`, or the one for `fallback` when it is unset.
+ *
+ * This is the default an explicit `dustWallet` option overrides, so a whole lane can be switched between the two sync
+ * models by configuration while individual tests that need a specific model keep pinning it in code.
+ *
+ * `fallback` lets a caller choose which model applies when nothing is configured **without** taking the choice away
+ * from `DUST_SYNC`. Passing an explicit `dustWallet` instead would pin the model outright and make the variable
+ * ineffective for that wallet — which silently splits a lane, since some of its tests would switch and others would
+ * not.
+ */
+export declare const dustWalletFromEnv: (env?: Record<string, string | undefined>, fallback?: DustSyncModel) => DustWalletFactory;
+/**
+ * Where the dust sub-wallet's snapshot lives, namespaced by the sync model that wrote it.
+ *
+ * The two models disagree on the meaning of the one progress value a snapshot carries, so a snapshot must never be
+ * restored into the other model — see {@link eventBasedDustWallet}. Keeping them in separate files makes a model switch
+ * degrade to a from-scratch build rather than to a wrong resume position, with no cache-clearing step to remember.
+ *
+ * The shielded and unshielded snapshots are model-independent and are not namespaced.
+ */
+export declare const dustSnapshotPath: (syncCacheDir: string, filename: string, model: DustSnapshotModel) => string;
+/**
+ * The projections dust sync, synchronizing in the background like the event-based sync does.
+ *
+ * This is the plain drop-in: spread it into the wallet options and the usual state waiters work unchanged, because
+ * background synchronization re-runs the projections passes on an interval.
+ *
+ * Use {@link manualProjectionsDustSyncOptions} instead when a test needs to decide when each pass happens.
+ */
+export declare const projectionsDustSyncOptions: {
+    readonly dustWallet: DustWalletFactory;
+};
+/**
+ * The projections dust sync with background synchronization switched off, so the caller decides when each pass runs.
+ *
+ * Use this when a test needs passes to happen at known points — asserting on the state a specific pass produced, for
+ * instance. A caller that spreads this in must drive `facade.doSync(seeds)` itself, after start and again after
+ * anything that changes dust state; waiting on `waitForSyncedState()` alone will block, because with `manualSync`
+ * nothing advances the dust wallet until `doSync` runs.
+ *
+ * For a test that just wants the wallet to keep up on its own, spread {@link projectionsDustSyncOptions} instead and let
+ * background synchronization run the passes.
+ */
+export declare const manualProjectionsDustSyncOptions: {
+    readonly dustWallet: DustWalletFactory;
+    readonly manualSync: true;
+};

package/dist/dust-sync.js

@@ -0,0 +1,140 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// You may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import { LedgerParameters } from '@midnightntwrk/ledger-v9';
+import { makeIndexerChainVersionProbe } from '@midnightntwrk/wallet-sdk-capabilities/chainVersion';
+import { asV8DustParameters, CustomForkingDustWallet, DustWallet, makeEventLessSyncCapability, makeEventLessSyncService, } from '@midnightntwrk/wallet-sdk-dust-wallet';
+import { V1Builder } from '@midnightntwrk/wallet-sdk-dust-wallet/v1';
+import { Migration, V2Builder } from '@midnightntwrk/wallet-sdk-dust-wallet/v2';
+/**
+ * A dust sub-wallet that syncs from indexer projections instead of the event stream.
+ *
+ * The shipped `DustWallet` with exactly one substitution — the V2 variant's sync service. The V1 variant keeps the
+ * event stream, because the projections sync is a ledger-v9 capability: it rests on `DustLocalState` members no
+ * ledger-v8 has. On a chain that runs ledger-v9 from its first block the V1 variant never applies, so a wallet built
+ * this way reaches the projections sync immediately.
+ *
+ * The projections sync synchronizes in finite passes rather than over a live subscription, but background
+ * synchronization re-runs those passes on an interval, so this factory can be used on its own and the usual state
+ * waiters behave as they do for the event-based sync. Pair it with `manualSync` — see
+ * {@link manualProjectionsDustSyncOptions} — only when a caller wants to decide when each pass happens.
+ *
+ * **Both variants are registered, so a wallet built this way transacts.** A single-variant composition would answer for
+ * the whole protocol timeline and therefore report the minimum supported version; because a facade acts at the lowest
+ * version its three sub-wallets report, such a sub-wallet holds the facade below the ledger-v9 boundary and the facade
+ * then refuses the shielded wallet's ledger-v9 transaction, the two sides of a boundary being unmergeable. Registering
+ * both variants leaves the version to the chain, which is what lets the healthcheck scenarios pay fees and transfer
+ * while syncing their Dust from projections.
+ */
+export const eventLessDustWallet = (config) => {
+    const dustParameters = config.dustParameters ?? LedgerParameters.initialParameters().dust;
+    return CustomForkingDustWallet({ ...config, chainVersionProbe: config.chainVersionProbe ?? makeIndexerChainVersionProbe(config) }, {
+        builder: new V1Builder().withDefaults(),
+        // The one field that cannot be shared: `dustParameters` is a WASM object of whichever ledger module produced it,
+        // so the V1 variant is handed the ledger-v8 rebuild of the same rates rather than the object itself.
+        configuration: { ...config, dustParameters: asV8DustParameters(dustParameters) },
+    }, {
+        builder: new V2Builder()
+            .withDefaults()
+            .withSync(makeEventLessSyncService, makeEventLessSyncCapability)
+            // Restated because `withSync` drops it: the seed-to-key derivation a start from a seed needs.
+            .withStartAuxDefaults()
+            .withMigration(() => Migration.makeCrossLedgerMigration({ dustParameters })),
+        configuration: config,
+    });
+};
+/**
+ * The event-stream dust sub-wallet, with the long-lived subscription.
+ *
+ * A dust snapshot stores one progress value, `appliedIndex`, and the two sync models mean different things by it: this
+ * service treats it as a ledger-event cursor to resume its subscription from, while the projections service writes a
+ * composite of tree indices and nullifier count. Restoring a projections-written snapshot here would therefore resume
+ * the subscription from a position that is not an event id at all, and because the cursor is trusted rather than
+ * validated, the effect would be silently skipped events rather than an error.
+ *
+ * Callers do not have to guard against that: dust snapshots are stored per sync model (see {@link dustSnapshotPath}), so
+ * switching a wallet's model finds no snapshot and rebuilds from scratch instead of resuming from a cursor that is not
+ * one.
+ */
+export const eventBasedDustWallet = DustWallet;
+/** The dust sub-wallet factory for a sync model. */
+export const dustWalletFor = (model) => model === 'projections' ? eventLessDustWallet : eventBasedDustWallet;
+/** The sync model a factory implements, or `custom` if it is neither of the two built-in ones. */
+export const dustSyncModelOf = (factory) => factory === eventLessDustWallet ? 'projections' : factory === eventBasedDustWallet ? 'events' : 'custom';
+/** Environment variable selecting the dust sync model for a whole test run. */
+export const DUST_SYNC_ENV_VAR = 'DUST_SYNC';
+/**
+ * Reads a dust sync model from its environment-variable spelling, falling back to `fallback` when unset or empty.
+ *
+ * An unrecognized value is rejected rather than defaulted. A silent fallback would mean a typo in `DUST_SYNC` reports a
+ * run as covering one sync model while it actually covered the other, which is worse than not running at all.
+ *
+ * @throws Error if `raw` is neither empty nor a known model
+ */
+export const parseDustSyncModel = (raw, fallback = 'events') => {
+    const value = raw?.trim();
+    if (value === undefined || value === '')
+        return fallback;
+    if (value === 'events' || value === 'projections')
+        return value;
+    throw new Error(`${DUST_SYNC_ENV_VAR} must be 'events' or 'projections', got '${raw}'`);
+};
+/** The dust sync model selected by `DUST_SYNC`, or `fallback` when it is unset. */
+export const dustSyncModelFromEnv = (env = process.env, fallback = 'events') => parseDustSyncModel(env[DUST_SYNC_ENV_VAR], fallback);
+/**
+ * The dust sub-wallet factory selected by `DUST_SYNC`, or the one for `fallback` when it is unset.
+ *
+ * This is the default an explicit `dustWallet` option overrides, so a whole lane can be switched between the two sync
+ * models by configuration while individual tests that need a specific model keep pinning it in code.
+ *
+ * `fallback` lets a caller choose which model applies when nothing is configured **without** taking the choice away
+ * from `DUST_SYNC`. Passing an explicit `dustWallet` instead would pin the model outright and make the variable
+ * ineffective for that wallet — which silently splits a lane, since some of its tests would switch and others would
+ * not.
+ */
+export const dustWalletFromEnv = (env = process.env, fallback = 'events') => dustWalletFor(dustSyncModelFromEnv(env, fallback));
+/**
+ * Where the dust sub-wallet's snapshot lives, namespaced by the sync model that wrote it.
+ *
+ * The two models disagree on the meaning of the one progress value a snapshot carries, so a snapshot must never be
+ * restored into the other model — see {@link eventBasedDustWallet}. Keeping them in separate files makes a model switch
+ * degrade to a from-scratch build rather than to a wrong resume position, with no cache-clearing step to remember.
+ *
+ * The shielded and unshielded snapshots are model-independent and are not namespaced.
+ */
+export const dustSnapshotPath = (syncCacheDir, filename, model) => `${syncCacheDir}/dust-${model}-${filename}`;
+/**
+ * The projections dust sync, synchronizing in the background like the event-based sync does.
+ *
+ * This is the plain drop-in: spread it into the wallet options and the usual state waiters work unchanged, because
+ * background synchronization re-runs the projections passes on an interval.
+ *
+ * Use {@link manualProjectionsDustSyncOptions} instead when a test needs to decide when each pass happens.
+ */
+export const projectionsDustSyncOptions = {
+    dustWallet: eventLessDustWallet,
+};
+/**
+ * The projections dust sync with background synchronization switched off, so the caller decides when each pass runs.
+ *
+ * Use this when a test needs passes to happen at known points — asserting on the state a specific pass produced, for
+ * instance. A caller that spreads this in must drive `facade.doSync(seeds)` itself, after start and again after
+ * anything that changes dust state; waiting on `waitForSyncedState()` alone will block, because with `manualSync`
+ * nothing advances the dust wallet until `doSync` runs.
+ *
+ * For a test that just wants the wallet to keep up on its own, spread {@link projectionsDustSyncOptions} instead and let
+ * background synchronization run the passes.
+ */
+export const manualProjectionsDustSyncOptions = {
+    dustWallet: eventLessDustWallet,
+    manualSync: true,
+};

package/dist/logger.js

@@ -30,7 +30,7 @@ export const getLogger = () => current;
 // whatever `setLogger` installed, without every helper having to call `getLogger()`.
 export const logger = new Proxy({}, {
     get(_target, property) {
-        const value = current[property];
+        const value = Reflect.get(current, property);
         return typeof value === 'function' ? value.bind(current) : value;
     },
 });

package/dist/scenarios/dust.d.ts

@@ -1,4 +1,5 @@
 import { type WalletTestEnvironment } from '../types.js';
+import { type ProvideWalletOptions } from '../wallet.js';
 /** Dependencies the dust scenarios need from the consumer. */
 export interface DustScenarioDeps {
     /** Accessor for the active environment (typically the return of `useWalletTestEnvironment`). */
@@ -7,8 +8,19 @@ export interface DustScenarioDeps {
     seed: string;
     /** Optional dir to persist/restore wallet state across runs. (Was the `SYNC_CACHE` env var.) */
     syncCacheDir?: string | undefined;
-    /** Per-test timeout in ms. Defaults to the upstream value of 1 hour. */
+    /** Per-test timeout in ms. Defaults to 15 minutes; a longer bound only spends lane time on a wedged wallet. */
     timeout?: number | undefined;
+    /**
+     * Selects the dust sync model. Defaults to the projections sync with background synchronization, so the network being
+     * monitored is exercised against the sync model the wallet ships to users.
+     *
+     * Left unset, the model still follows `DUST_SYNC` when that is configured, so a whole lane can be switched by
+     * environment; projections is only the fallback for when nothing is. Pass `{ dustWallet: eventBasedDustWallet }` to
+     * pin the event-stream sync regardless of the environment — dust snapshots are namespaced per sync model, so there is
+     * no cache to clear when switching. Avoid adding `manualSync` here: these scenarios wait on the state stream rather
+     * than driving passes themselves, so they need background synchronization to be running.
+     */
+    walletOptions?: Pick<ProvideWalletOptions, 'dustWallet' | 'manualSync'> | undefined;
 }
 /** Registers the dust register/deregister healthchecks under a `describe('Dust tests')` block. */
-export declare function registerDustHealthchecks({ getEnv, seed, syncCacheDir, timeout }: DustScenarioDeps): void;
+export declare function registerDustHealthchecks({ getEnv, seed, syncCacheDir, timeout, walletOptions, }: DustScenarioDeps): void;

package/dist/scenarios/dust.js

@@ -19,10 +19,10 @@ import { describe, test, expect, beforeEach, afterEach } from 'vitest';
 import { inspect } from 'node:util';
 import * as rx from 'rxjs';
 import * as ledger from '@midnightntwrk/ledger-v9';
-import { provideWallet, saveState } from '../wallet.js';
+import { provideWallet, saveState, shouldPersistState, withProjectionsDefault, } from '../wallet.js';
 import { logger } from '../logger.js';
 /** Registers the dust register/deregister healthchecks under a `describe('Dust tests')` block. */
-export function registerDustHealthchecks({ getEnv, seed, syncCacheDir, timeout = 3_600_000 }) {
+export function registerDustHealthchecks({ getEnv, seed, syncCacheDir, timeout = 900_000, walletOptions, }) {
     describe('Dust tests', () => {
         const unshieldedTokenRaw = ledger.unshieldedToken().raw;
         let wallet;
@@ -30,11 +30,17 @@ export function registerDustHealthchecks({ getEnv, seed, syncCacheDir, timeout =
         beforeEach(async () => {
             const env = getEnv();
             filenameWallet = `${seed.substring(0, 7)}-${env.network}.state`;
-            wallet = await provideWallet(env, { seed, syncCacheDir, filename: filenameWallet });
+            wallet = await provideWallet(env, {
+                ...withProjectionsDefault(walletOptions),
+                seed,
+                syncCacheDir,
+                filename: filenameWallet,
+            });
         });
-        afterEach(async () => {
-            if (syncCacheDir) {
-                await saveState(wallet.wallet, syncCacheDir, filenameWallet);
+        afterEach(async (context) => {
+            // Only a passing test leaves its wallets in a resumable position; see `shouldPersistState`.
+            if (syncCacheDir && shouldPersistState(context)) {
+                await saveState(wallet, syncCacheDir, filenameWallet);
             }
             await wallet.wallet.stop();
             logger.info('Wallet stopped');

package/dist/scenarios/token-transfer.d.ts

@@ -1,6 +1,6 @@
 import { type NetworkId } from '@midnightntwrk/wallet-sdk-abstractions';
 import { type WalletTestEnvironment } from '../types.js';
-import { type WalletInit } from '../wallet.js';
+import { type ProvideWalletOptions, type WalletInit } from '../wallet.js';
 /** Dependencies the token-transfer setup + scenarios need from the consumer. */
 export interface TokenTransferScenarioDeps {
     /** Accessor for the active environment (typically the return of `useWalletTestEnvironment`). */
@@ -11,10 +11,24 @@ export interface TokenTransferScenarioDeps {
     secondSeed: string;
     /** Optional dir to persist/restore wallet state across runs. (Was the `SYNC_CACHE` env var.) */
     syncCacheDir?: string | undefined;
-    /** Timeout for the sync-heavy `beforeEach` and the healthcheck test in ms. Defaults to 1 hour. */
+    /**
+     * Timeout for the sync-heavy `beforeEach` and the healthcheck test in ms. Defaults to 15 minutes — a longer bound
+     * does not rescue a wedged wallet, it only spends lane time before reporting.
+     */
     syncTimeout?: number | undefined;
     /** Timeout for the `afterEach` teardown in ms. Defaults to 10 minutes. */
     timeout?: number | undefined;
+    /**
+     * Selects the dust sync model for both wallets. Defaults to the projections sync with background synchronization, so
+     * these transfers' fees are paid out of a projections-synced dust wallet.
+     *
+     * Left unset, the model still follows `DUST_SYNC` when that is configured, so a whole lane can be switched by
+     * environment; projections is only the fallback for when nothing is. Pass `{ dustWallet: eventBasedDustWallet }` to
+     * pin the event-stream sync regardless of the environment — dust snapshots are namespaced per sync model, so there is
+     * no cache to clear when switching. Avoid adding `manualSync` here: these scenarios wait on the state stream rather
+     * than driving passes themselves, so they need background synchronization to be running.
+     */
+    walletOptions?: Pick<ProvideWalletOptions, 'dustWallet' | 'manualSync'> | undefined;
 }
 /** Accessors returned by {@link useTokenTransferWallets}, valid inside `test`/`it` bodies. */
 export interface TokenTransferWallets {
@@ -29,7 +43,7 @@ export interface TokenTransferWallets {
  * Call once inside a `describe`. Both the healthcheck scenario below and the upstream-only token-transfer tests reuse
  * this so the sender/receiver selection lives in one place.
  */
-export declare function useTokenTransferWallets({ getEnv, fundedSeed, secondSeed, syncCacheDir, syncTimeout, timeout, }: TokenTransferScenarioDeps): TokenTransferWallets;
+export declare function useTokenTransferWallets({ getEnv, fundedSeed, secondSeed, syncCacheDir, syncTimeout, timeout, walletOptions, }: TokenTransferScenarioDeps): TokenTransferWallets;
 /**
  * Registers the single `@healthcheck`-tagged token-transfer test under a `describe('Token transfer')` block. This is
  * the only token-transfer test shipped in the testkit; downstream monitoring selects it with `vitest run -t

package/dist/scenarios/token-transfer.js

@@ -21,10 +21,10 @@ import { firstValueFrom } from 'rxjs';
 import { inspect } from 'node:util';
 import * as ledger from '@midnightntwrk/ledger-v9';
 import { ProtocolVersion, WalletTransaction } from '@midnightntwrk/wallet-sdk-abstractions';
-import { provideWallet, saveState } from '../wallet.js';
+import { provideWallet, saveState, shouldPersistState, withProjectionsDefault, } from '../wallet.js';
 import { tNightAmount } from '../primitives.js';
 import { getShieldedAddress, getUnshieldedAddress } from '../addresses.js';
-import { waitForTxInHistory } from '../state-waiters.js';
+import { waitForFacadePendingClear, waitForTxInHistory } from '../state-waiters.js';
 import { expectReceiverShieldedTxHistory, expectReceiverUnshieldedTxHistory, expectSenderShieldedTxHistory, expectSenderUnshieldedTxHistory, } from '../tx-history-asserts.js';
 import { logger } from '../logger.js';
 /**
@@ -32,7 +32,7 @@ import { logger } from '../logger.js';
  * Call once inside a `describe`. Both the healthcheck scenario below and the upstream-only token-transfer tests reuse
  * this so the sender/receiver selection lives in one place.
  */
-export function useTokenTransferWallets({ getEnv, fundedSeed, secondSeed, syncCacheDir, syncTimeout = 60 * 60 * 1000, timeout = 600_000, }) {
+export function useTokenTransferWallets({ getEnv, fundedSeed, secondSeed, syncCacheDir, syncTimeout = 15 * 60 * 1000, timeout = 600_000, walletOptions, }) {
     const shieldedTokenRaw = ledger.shieldedToken().raw;
     let sender;
     let receiver;
@@ -46,8 +46,18 @@ export function useTokenTransferWallets({ getEnv, fundedSeed, secondSeed, syncCa
         networkId = env.endpoints.networkId;
         filenameWallet = `${fundedSeed.substring(0, 7)}-${env.network}.state`;
         filenameWallet2 = `${secondSeed.substring(0, 7)}-${env.network}.state`;
-        wallet = await provideWallet(env, { seed: fundedSeed, syncCacheDir, filename: filenameWallet });
-        wallet2 = await provideWallet(env, { seed: secondSeed, syncCacheDir, filename: filenameWallet2 });
+        wallet = await provideWallet(env, {
+            ...withProjectionsDefault(walletOptions),
+            seed: fundedSeed,
+            syncCacheDir,
+            filename: filenameWallet,
+        });
+        wallet2 = await provideWallet(env, {
+            ...withProjectionsDefault(walletOptions),
+            seed: secondSeed,
+            syncCacheDir,
+            filename: filenameWallet2,
+        });
         logger.info('Two wallets started');
         const [state1, state2] = await Promise.all([
             wallet.wallet.waitForSyncedState(),
@@ -67,10 +77,11 @@ export function useTokenTransferWallets({ getEnv, fundedSeed, secondSeed, syncCa
             receiver = wallet;
         }
     }, syncTimeout);
-    afterEach(async () => {
-        if (syncCacheDir) {
-            await saveState(wallet.wallet, syncCacheDir, filenameWallet);
-            await saveState(wallet2.wallet, syncCacheDir, filenameWallet2);
+    afterEach(async (context) => {
+        // Only a passing test leaves its wallets in a resumable position; see `shouldPersistState`.
+        if (syncCacheDir && shouldPersistState(context)) {
+            await saveState(wallet, syncCacheDir, filenameWallet);
+            await saveState(wallet2, syncCacheDir, filenameWallet2);
         }
         await sender.wallet.stop();
         await receiver.wallet.stop();
@@ -99,7 +110,7 @@ export function registerTokenTransferHealthchecks(deps) {
         const shieldedTokenRaw = ledger.shieldedToken().raw;
         const unshieldedTokenRaw = ledger.unshieldedToken().raw;
         const outputValue = tNightAmount(10n);
-        const syncTimeout = deps.syncTimeout ?? 60 * 60 * 1000;
+        const syncTimeout = deps.syncTimeout ?? 15 * 60 * 1000;
         test('Is working for valid transfer @healthcheck', async () => {
             const sender = getSender();
             const receiver = getReceiver();
@@ -169,6 +180,7 @@ export function registerTokenTransferHealthchecks(deps) {
             logger.info('Transaction id: ' + txId);
             logger.info('waiting for tx in history');
             const senderTxEntry = await waitForTxInHistory(txHash, sender.wallet, (e) => e.shielded !== undefined && e.unshielded !== undefined);
+            await waitForFacadePendingClear(sender.wallet);
             const senderFinalState = await sender.wallet.waitForSyncedState();
             const senderFinalShieldedBalance = senderFinalState.shielded.balances[shieldedTokenRaw];
             const senderFinalUnshieldedBalance = senderFinalState.unshielded.balances[unshieldedTokenRaw];
@@ -193,6 +205,7 @@ export function registerTokenTransferHealthchecks(deps) {
             expect(senderFinalTxHistory.length).toBeGreaterThanOrEqual(senderInitialTxHistory.length + 1);
             expectSenderShieldedTxHistory(senderTxEntry);
             expectSenderUnshieldedTxHistory(senderTxEntry);
+            await waitForFacadePendingClear(receiver.wallet);
             const receiverFinalState = await receiver.wallet.waitForSyncedState();
             const receiverFinalShieldedBalance = receiverFinalState.shielded.balances[shieldedTokenRaw] ?? 0n;
             const receiverFinalUnshieldedBalance = receiverFinalState.unshielded.balances[unshieldedTokenRaw] ?? 0n;

package/dist/state-waiters.d.ts

@@ -1,9 +1,35 @@
+import * as rx from 'rxjs';
 import type * as ledger from '@midnightntwrk/ledger-v9';
 import { type ShieldedWalletAPI } from '@midnightntwrk/wallet-sdk-shielded';
 import { type UnshieldedWallet } from '@midnightntwrk/wallet-sdk-unshielded-wallet';
 import { type WalletFacade, type WalletEntry } from '@midnightntwrk/wallet-sdk-facade';
 /** Default dust-balance threshold to wait for: 7 * 10^14. */
 export declare const DEFAULT_DUST_BALANCE_THRESHOLD: bigint;
+/**
+ * Resolves with the wallet's current state once `predicate` has held continuously for `settleMs`.
+ *
+ * A settle window is needed because conditions like `pendingCoins.length === 0` are also the _resting_ state before a
+ * transaction is submitted: a waiter that resolved on the first matching emission would hand back the stale
+ * pre-transaction state.
+ *
+ * The window has to be applied to the predicate rather than to the source. Debouncing the source waits for the wallet
+ * to stop emitting altogether, which never happens while a sub-wallet syncs in the background — a Dust wallet syncing
+ * from projections emits about every 5 seconds indefinitely — so the predicate is never evaluated and the wait runs to
+ * the test timeout while logging that its condition is already satisfied.
+ *
+ * `distinctUntilChanged` is load-bearing: without it, `switchMap` would cancel and restart the timer on every emission
+ * and the timer would never elapse, reproducing the same starvation.
+ *
+ * The value is carried through the pipeline rather than re-read from `source` once the window elapses, because `source`
+ * must only be subscribed once. The facade's `state()` replays its current value on subscribe, but a sub-wallet's
+ * `state` does not: a second subscription there receives nothing until the next change, so on an already-settled wallet
+ * it would never produce a value and the wait would hang. `shareReplay` is what reconciles that with returning the
+ * _latest_ matching value rather than the one from the moment the condition began to hold: it multicasts a single
+ * upstream subscription, so the window and the value read at the end of it come from the same one. Returning the
+ * opening value would defeat the point of the window — `pendingCoins.length === 0` is equally true either side of a
+ * balance arriving, so the waiter would hand back the stale pre-transaction state it exists to avoid.
+ */
+export declare const waitForStableState: <T>(source: rx.Observable<T>, predicate: (value: T) => boolean, description: string, settleMs?: number, timeoutMs?: number) => Promise<T>;
 export declare const waitForSyncUnshielded: (wallet: UnshieldedWallet) => Promise<import("@midnightntwrk/wallet-sdk-unshielded-wallet").UnshieldedWalletState<string>>;
 export declare const waitForFacadePending: (wallet: WalletFacade) => Promise<import("@midnightntwrk/wallet-sdk-facade").FacadeState>;
 export declare const waitForFacadePendingClear: (wallet: WalletFacade) => Promise<import("@midnightntwrk/wallet-sdk-facade").FacadeState>;

package/dist/state-waiters.js

@@ -16,6 +16,45 @@ import { expect } from 'vitest';
 import { logger } from './logger.js';
 /** Default dust-balance threshold to wait for: 7 * 10^14. */
 export const DEFAULT_DUST_BALANCE_THRESHOLD = 7n * 10n ** 14n;
+/** How long a condition must hold before a settling waiter accepts it. */
+const DEFAULT_SETTLE_MS = 10_000;
+/** How long a settling waiter waits for its condition before failing rather than running to the test timeout. */
+const DEFAULT_SETTLE_TIMEOUT_MS = 180_000;
+/**
+ * Resolves with the wallet's current state once `predicate` has held continuously for `settleMs`.
+ *
+ * A settle window is needed because conditions like `pendingCoins.length === 0` are also the _resting_ state before a
+ * transaction is submitted: a waiter that resolved on the first matching emission would hand back the stale
+ * pre-transaction state.
+ *
+ * The window has to be applied to the predicate rather than to the source. Debouncing the source waits for the wallet
+ * to stop emitting altogether, which never happens while a sub-wallet syncs in the background — a Dust wallet syncing
+ * from projections emits about every 5 seconds indefinitely — so the predicate is never evaluated and the wait runs to
+ * the test timeout while logging that its condition is already satisfied.
+ *
+ * `distinctUntilChanged` is load-bearing: without it, `switchMap` would cancel and restart the timer on every emission
+ * and the timer would never elapse, reproducing the same starvation.
+ *
+ * The value is carried through the pipeline rather than re-read from `source` once the window elapses, because `source`
+ * must only be subscribed once. The facade's `state()` replays its current value on subscribe, but a sub-wallet's
+ * `state` does not: a second subscription there receives nothing until the next change, so on an already-settled wallet
+ * it would never produce a value and the wait would hang. `shareReplay` is what reconciles that with returning the
+ * _latest_ matching value rather than the one from the moment the condition began to hold: it multicasts a single
+ * upstream subscription, so the window and the value read at the end of it come from the same one. Returning the
+ * opening value would defeat the point of the window — `pendingCoins.length === 0` is equally true either side of a
+ * balance arriving, so the waiter would hand back the stale pre-transaction state it exists to avoid.
+ */
+export const waitForStableState = (source, predicate, description, settleMs = DEFAULT_SETTLE_MS, timeoutMs = DEFAULT_SETTLE_TIMEOUT_MS) => {
+    const observed = source.pipe(rx.map((value) => ({ value, holds: predicate(value) })), rx.shareReplay({ bufferSize: 1, refCount: true }));
+    return rx.firstValueFrom(observed.pipe(rx.distinctUntilChanged((a, b) => a.holds === b.holds), rx.switchMap(({ holds }) => (holds ? rx.timer(settleMs) : rx.NEVER)), 
+    // The window has elapsed, so take the newest value rather than the one that opened it. That value still satisfies
+    // the predicate: a value that did not would have been a `holds` transition, and `switchMap` would have cancelled
+    // this timer before it could fire.
+    rx.withLatestFrom(observed), rx.map(([, latest]) => latest.value), rx.take(1), rx.timeout({
+        first: timeoutMs,
+        with: () => rx.throwError(() => new Error(`${description}: condition never held continuously for ${settleMs}ms within ${timeoutMs}ms. It may have been met repeatedly and simply never stayed met for that long — a wallet still syncing keeps breaking the window.`)),
+    })));
+};
 export const waitForSyncUnshielded = (wallet) => rx.firstValueFrom(wallet.state.pipe(rx.throttleTime(5_000), rx.tap((state) => {
     const applyGap = state.state.progress.highestTransactionId - state.state.progress.appliedId;
     logger.info(`Wallet behind by ${applyGap} indices`);
@@ -32,32 +71,21 @@ rx.timeout({
     first: 120_000,
     with: () => rx.throwError(() => new Error('waitForFacadePending: no pending coins observed within 120s — the pending window was likely missed (tx confirmed before it was observed) or the transaction was never submitted.')),
 })));
-export const waitForFacadePendingClear = (wallet) => rx.firstValueFrom(wallet.state().pipe(rx.tap((state) => {
-    const shieldedPending = state.shielded.pendingCoins.length;
-    logger.info(`Shielded wallet pending coins: ${shieldedPending}, waiting for pending coins to clear...`);
-    const unshieldedPending = state.unshielded.pendingCoins.length;
-    logger.info(`Unshielded wallet pending coins: ${unshieldedPending}, waiting for pending coins to clear...`);
-    const dustPending = state.dust.pendingCoins.length;
-    logger.info(`Dust wallet pending coins: ${dustPending}, waiting for pending coins to clear...`);
-}), rx.debounceTime(10_000), rx.filter((state) => state.shielded.pendingCoins.length == 0 &&
-    state.unshielded.pendingCoins.length == 0 &&
-    state.dust.pendingCoins.length == 0)));
+export const waitForFacadePendingClear = (wallet) => waitForStableState(wallet.state().pipe(rx.tap((state) => {
+    logger.info(`Pending coins — shielded: ${state.shielded.pendingCoins.length}, unshielded: ${state.unshielded.pendingCoins.length}, dust: ${state.dust.pendingCoins.length}; waiting for all to clear...`);
+})), (state) => state.shielded.pendingCoins.length === 0 &&
+    state.unshielded.pendingCoins.length === 0 &&
+    state.dust.pendingCoins.length === 0, 'waitForFacadePendingClear');
 export const waitForDustBalance = (wallet, threshold = DEFAULT_DUST_BALANCE_THRESHOLD) => rx.firstValueFrom(wallet.state().pipe(rx.tap((state) => {
     const dustBalance = state.dust.balance(new Date());
     logger.info(`Dust balance: ${dustBalance}, waiting for dust balance > ${threshold}...`);
 }), rx.filter((state) => state.dust.balance(new Date()) > threshold)));
-export const waitForFinalizedShieldedBalance = (wallet) => rx.firstValueFrom(wallet.state.pipe(rx.tap((state) => {
-    const pending = state.pendingCoins.length;
-    logger.info(`Wallet pending coins: ${pending}, waiting for pending coins cleared...`);
-}), 
-// `pendingCoins.length === 0` is also the resting condition, so without a settle window `firstValueFrom` resolves
-// on the pre-transaction emission. Debounce until the state stops changing so we capture the settled post-tx
-// state rather than the stale one.
-rx.debounceTime(10_000), rx.filter((state) => state.pendingCoins.length === 0)));
-export const waitForUnshieldedCoinUpdate = (wallet, initialNumAvailableCoins) => rx.firstValueFrom(wallet.state().pipe(rx.tap((state) => {
-    const currentNumAvailableCoins = state.unshielded.availableCoins.length;
-    logger.info(`Unshielded available coins: ${currentNumAvailableCoins}, waiting for more than ${initialNumAvailableCoins}...synced = ${state.isSynced}`);
-}), rx.debounceTime(10_000), rx.filter((s) => s.isSynced), rx.filter((s) => s.unshielded.availableCoins.length > initialNumAvailableCoins)));
+export const waitForFinalizedShieldedBalance = (wallet) => waitForStableState(wallet.state.pipe(rx.tap((state) => {
+    logger.info(`Wallet pending coins: ${state.pendingCoins.length}, waiting for pending coins cleared...`);
+})), (state) => state.pendingCoins.length === 0, 'waitForFinalizedShieldedBalance');
+export const waitForUnshieldedCoinUpdate = (wallet, initialNumAvailableCoins) => waitForStableState(wallet.state().pipe(rx.tap((state) => {
+    logger.info(`Unshielded available coins: ${state.unshielded.availableCoins.length}, waiting for more than ${initialNumAvailableCoins}...synced = ${state.isSynced}`);
+})), (state) => state.isSynced && state.unshielded.availableCoins.length > initialNumAvailableCoins, 'waitForUnshieldedCoinUpdate');
 export const waitForStateAfterDustRegistration = (wallet, finalizedTx) => rx.firstValueFrom(wallet.state().pipe(rx.mergeMap(async (state) => {
     const txInHistory = await wallet.queryTxHistoryByHash(finalizedTx.transactionHash());
     return {

package/dist/wallet.d.ts

@@ -3,6 +3,7 @@ import * as ledger from '@midnightntwrk/ledger-v9';
 import { WalletFacade } from '@midnightntwrk/wallet-sdk-facade';
 import { type UnshieldedKeystore } from '@midnightntwrk/wallet-sdk-unshielded-wallet';
 import { type WalletTestEnvironment } from './types.js';
+import { type DustSnapshotModel, type DustWalletFactory } from './dust-sync.js';
 export type WalletInit = {
     wallet: WalletFacade;
     shieldedSecretKeys: ledger.ZswapSecretKeys;
@@ -10,6 +11,12 @@ export type WalletInit = {
     /** The three per-wallet seeds, which is what the facade is started and stepped with. */
     seeds: WalletSeeds;
     unshieldedKeystore: UnshieldedKeystore;
+    /**
+     * The dust sync model this wallet was actually built with, whether it came from an explicit option or from the
+     * environment. {@link saveState} reads it so a snapshot is always written to the namespace of the model that produced
+     * it.
+     */
+    dustSyncModel: DustSnapshotModel;
 };
 /** Options for {@link provideWallet}. */
 export interface ProvideWalletOptions {
@@ -23,7 +30,36 @@ export interface ProvideWalletOptions {
     syncCacheDir?: string | undefined;
     /** Filename suffix for the three serialized state files. Required when `syncCacheDir` is set. */
     filename?: string | undefined;
+    /**
+     * Replaces the dust sub-wallet factory. Defaults to whatever `DUST_SYNC` selects (the event-based `DustWallet` when
+     * unset) — see `dustWalletFromEnv` — so a lane can be switched between sync models by configuration while a test that
+     * needs a specific model pins it here. Applies to both the restored and the built-from-scratch paths, so a cold cache
+     * cannot silently fall back to a different sync model.
+     */
+    dustWallet?: DustWalletFactory | undefined;
+    /**
+     * Starts the facade without background syncing, leaving the caller to drive `facade.doSync()`. Defaults to `false`
+     * (background sync), which is what every existing scenario relies on.
+     */
+    manualSync?: boolean | undefined;
 }
+/**
+ * Scenario wallet options with the projections default filled in **per field** rather than wholesale.
+ *
+ * A whole-parameter default is lost the moment a caller passes any `walletOptions` at all: `{ manualSync: true }`
+ * leaves `dustWallet` undefined, {@link provideWallet} falls back to the `events` model, and a scenario silently stops
+ * monitoring the sync model it exists to monitor. Filling the field in only when the caller supplied one keeps
+ * `DUST_SYNC` in charge of the model and the caller's own choices intact.
+ *
+ * An explicit `dustWallet: undefined` counts as not supplying one, so it is filled in too. The field is declared `|
+ * undefined` precisely so an optional factory can be forwarded under `exactOptionalPropertyTypes`, which means a caller
+ * forwarding an absent one type-checks; taking that as a choice of the `events` model would drop the scenario onto the
+ * sync it exists to stop monitoring, without the caller having named a model at all.
+ *
+ * @param walletOptions What the caller passed, if anything.
+ * @returns The options to hand {@link provideWallet}.
+ */
+export declare const withProjectionsDefault: (walletOptions: Pick<ProvideWalletOptions, "dustWallet" | "manualSync"> | undefined) => Pick<ProvideWalletOptions, "dustWallet" | "manualSync">;
 /**
  * Builds a fully-started {@link WalletFacade} (shielded + unshielded + dust) for the given seed.
  *
@@ -31,7 +67,31 @@ export interface ProvideWalletOptions {
  * otherwise (or on any restore failure) builds from scratch via {@link initWalletWithSeed}.
  */
 export declare const provideWallet: (env: WalletTestEnvironment, options: ProvideWalletOptions) => Promise<WalletInit>;
-/** Serializes all three sub-wallet states into `syncCacheDir`, keyed by `filename`. */
-export declare const saveState: (wallet: WalletFacade, syncCacheDir: string, filename: string) => Promise<void>;
+/**
+ * Whether the test that has just finished is safe to persist wallet state from.
+ *
+ * State written by a failed or timed-out test is worse than no state at all: the next run restores it, resumes from
+ * whatever partial position the failure left behind, and fails in turn — so one transient failure becomes permanent and
+ * every later run inherits it. Only a test that passed is known to have left its wallets in a position the chain can be
+ * resumed from.
+ *
+ * Pass the `afterEach` context: `afterEach((ctx) => { if (shouldPersistState(ctx)) await saveState(...) })`.
+ */
+export declare const shouldPersistState: (context: {
+    readonly task: {
+        readonly result?: {
+            readonly state?: string;
+        };
+    };
+}) => boolean;
+/**
+ * Serializes all three sub-wallet states into `syncCacheDir`, keyed by `filename`.
+ *
+ * Takes the whole {@link WalletInit} rather than the facade alone so the dust snapshot is always written to the
+ * namespace of the sync model that produced it — a model and a facade passed separately could disagree.
+ */
+export declare const saveState: (walletInit: Pick<WalletInit, "wallet" | "dustSyncModel">, syncCacheDir: string, filename: string) => Promise<void>;
+/** Options for {@link initWalletWithSeed}, a subset of {@link ProvideWalletOptions}. */
+export type InitWalletOptions = Pick<ProvideWalletOptions, 'dustWallet' | 'manualSync'>;
 /** Builds and starts a fresh {@link WalletFacade} from `seed`, with no disk persistence. */
-export declare const initWalletWithSeed: (env: WalletTestEnvironment, seed: string) => Promise<WalletInit>;
+export declare const initWalletWithSeed: (env: WalletTestEnvironment, seed: string, options?: InitWalletOptions) => Promise<WalletInit>;

package/dist/wallet.js

@@ -18,9 +18,9 @@ import { InMemoryTransactionHistoryStorage, } from '@midnightntwrk/wallet-sdk-ab
 import { ShieldedWallet } from '@midnightntwrk/wallet-sdk-shielded';
 import { WalletFacade, WalletEntrySchema, mergeWalletEntries } from '@midnightntwrk/wallet-sdk-facade';
 import { createKeystore, PublicKey, UnshieldedWallet, } from '@midnightntwrk/wallet-sdk-unshielded-wallet';
-import { DustWallet } from '@midnightntwrk/wallet-sdk-dust-wallet';
 import { logger } from './logger.js';
 import { getDustSeed, getShieldedSeed, getUnshieldedSeed } from './seeds.js';
+import { dustSnapshotPath, dustSyncModelOf, dustWalletFromEnv, } from './dust-sync.js';
 const waitForSyncProgress = async (wallet) => await rx.firstValueFrom(wallet.state().pipe(rx.throttleTime(5000), rx.tap((state) => {
     const applyGap = state.unshielded.progress.highestTransactionId - state.unshielded.progress.appliedId;
     logger.info(`Wallet facade behind by ${applyGap}`);
@@ -65,11 +65,11 @@ const restoreUnshieldedWallet = async (path, seed, env, readIfExists, txHistoryS
     }
     return undefined;
 };
-const restoreDustWallet = async (path, walletConfig, readIfExists) => {
+const restoreDustWallet = async (path, walletConfig, readIfExists, dustWallet) => {
     try {
         const serialized = await readIfExists(path);
         if (serialized) {
-            const DustInstance = DustWallet({
+            const DustInstance = dustWallet({
                 ...walletConfig,
                 costParameters: walletConfig?.costParameters ?? {
                     feeBlocksMargin: 5,
@@ -86,6 +86,26 @@ const restoreDustWallet = async (path, walletConfig, readIfExists) => {
     }
     return undefined;
 };
+/**
+ * Scenario wallet options with the projections default filled in **per field** rather than wholesale.
+ *
+ * A whole-parameter default is lost the moment a caller passes any `walletOptions` at all: `{ manualSync: true }`
+ * leaves `dustWallet` undefined, {@link provideWallet} falls back to the `events` model, and a scenario silently stops
+ * monitoring the sync model it exists to monitor. Filling the field in only when the caller supplied one keeps
+ * `DUST_SYNC` in charge of the model and the caller's own choices intact.
+ *
+ * An explicit `dustWallet: undefined` counts as not supplying one, so it is filled in too. The field is declared `|
+ * undefined` precisely so an optional factory can be forwarded under `exactOptionalPropertyTypes`, which means a caller
+ * forwarding an absent one type-checks; taking that as a choice of the `events` model would drop the scenario onto the
+ * sync it exists to stop monitoring, without the caller having named a model at all.
+ *
+ * @param walletOptions What the caller passed, if anything.
+ * @returns The options to hand {@link provideWallet}.
+ */
+export const withProjectionsDefault = (walletOptions) => ({
+    ...walletOptions,
+    dustWallet: walletOptions?.dustWallet ?? dustWalletFromEnv(process.env, 'projections'),
+});
 /**
  * Builds a fully-started {@link WalletFacade} (shielded + unshielded + dust) for the given seed.
  *
@@ -93,10 +113,15 @@ const restoreDustWallet = async (path, walletConfig, readIfExists) => {
  * otherwise (or on any restore failure) builds from scratch via {@link initWalletWithSeed}.
  */
 export const provideWallet = async (env, options) => {
-    const { seed, syncCacheDir, filename } = options;
+    const { seed, syncCacheDir, filename, manualSync } = options;
+    // Resolved once, here, so the restore path, the snapshot namespace and every from-scratch fallback below all agree on
+    // which sync model was asked for.
+    const dustWallet = options.dustWallet ?? dustWalletFromEnv();
+    const dustSyncModel = dustSyncModelOf(dustWallet);
+    const fromScratch = { dustWallet, manualSync };
     if (!syncCacheDir || !filename) {
         logger.info('No sync cache configured; building wallet facade from scratch');
-        return initWalletWithSeed(env, seed);
+        return initWalletWithSeed(env, seed, fromScratch);
     }
     // Single shared tx-history storage so all three sub-wallets and the facade read/write
     // the same instance; otherwise shielded/unshielded writes go to a storage the facade
@@ -127,11 +152,11 @@ export const provideWallet = async (env, options) => {
     const [restoredShielded, restoredUnshielded, restoredDust] = await Promise.all([
         restoreShieldedWallet(`${syncCacheDir}/shielded-${filename}`, Wallet, readIfExists),
         restoreUnshieldedWallet(`${syncCacheDir}/unshielded-${filename}`, seed, env, readIfExists, txHistoryStorage),
-        restoreDustWallet(`${syncCacheDir}/dust-${filename}`, { ...walletConfig, ...dustWalletConfig }, readIfExists),
+        restoreDustWallet(dustSnapshotPath(syncCacheDir, filename, dustSyncModel), { ...walletConfig, ...dustWalletConfig }, readIfExists, dustWallet),
     ]);
     if (!restoredShielded || !restoredUnshielded || !restoredDust) {
         logger.info('Building wallet facade from scratch');
-        return initWalletWithSeed(env, seed);
+        return initWalletWithSeed(env, seed, fromScratch);
     }
     else {
         const restoredWallet = await WalletFacade.init({
@@ -143,7 +168,7 @@ export const provideWallet = async (env, options) => {
             unshielded: () => restoredUnshielded,
             dust: () => restoredDust,
         });
-        await restoredWallet.start(seeds);
+        await restoredWallet.start(seeds, { manualSync: manualSync ?? false });
         // check if wallet is syncing correctly
         await waitForSyncProgress(restoredWallet);
         const restoredWalletState = await rx.firstValueFrom(restoredWallet.state());
@@ -152,33 +177,49 @@ export const provideWallet = async (env, options) => {
         if ((applyGap ?? 0) < 0) {
             logger.warn('Unable to sync restored wallet. Building wallet facade from scratch');
             await restoredWallet.stop();
-            return initWalletWithSeed(env, seed);
+            return initWalletWithSeed(env, seed, fromScratch);
         }
         else {
             logger.info('Successfully restored wallet facade.');
-            return { wallet: restoredWallet, shieldedSecretKeys, dustSecretKey, seeds, unshieldedKeystore };
+            return { wallet: restoredWallet, shieldedSecretKeys, dustSecretKey, seeds, unshieldedKeystore, dustSyncModel };
         }
     }
 };
-/** Serializes all three sub-wallet states into `syncCacheDir`, keyed by `filename`. */
-export const saveState = async (wallet, syncCacheDir, filename) => {
+/**
+ * Whether the test that has just finished is safe to persist wallet state from.
+ *
+ * State written by a failed or timed-out test is worse than no state at all: the next run restores it, resumes from
+ * whatever partial position the failure left behind, and fails in turn — so one transient failure becomes permanent and
+ * every later run inherits it. Only a test that passed is known to have left its wallets in a position the chain can be
+ * resumed from.
+ *
+ * Pass the `afterEach` context: `afterEach((ctx) => { if (shouldPersistState(ctx)) await saveState(...) })`.
+ */
+export const shouldPersistState = (context) => context.task.result?.state === 'pass';
+/**
+ * Serializes all three sub-wallet states into `syncCacheDir`, keyed by `filename`.
+ *
+ * Takes the whole {@link WalletInit} rather than the facade alone so the dust snapshot is always written to the
+ * namespace of the sync model that produced it — a model and a facade passed separately could disagree.
+ */
+export const saveState = async (walletInit, syncCacheDir, filename) => {
     logger.info(`Saving state in ${syncCacheDir}/${filename}`);
     try {
         await fsAsync.mkdir(syncCacheDir, { recursive: true });
         // Serialize all three states
         const [shieldedSerializedState, unshieldedSerializedState, dustSerializedState] = await Promise.all([
-            wallet.shielded.serializeState(),
-            wallet.unshielded.serializeState(),
-            wallet.dust.serializeState(),
+            walletInit.wallet.shielded.serializeState(),
+            walletInit.wallet.unshielded.serializeState(),
+            walletInit.wallet.dust.serializeState(),
         ]);
         const files = [
-            { suffix: 'shielded-', data: shieldedSerializedState },
-            { suffix: 'unshielded-', data: unshieldedSerializedState },
-            { suffix: 'dust-', data: dustSerializedState },
+            { path: `${syncCacheDir}/shielded-${filename}`, data: shieldedSerializedState },
+            { path: `${syncCacheDir}/unshielded-${filename}`, data: unshieldedSerializedState },
+            { path: dustSnapshotPath(syncCacheDir, filename, walletInit.dustSyncModel), data: dustSerializedState },
         ];
-        const results = await Promise.allSettled(files.map((f) => fsAsync.writeFile(`${syncCacheDir}/${f.suffix}${filename}`, f.data, 'utf-8')));
+        const results = await Promise.allSettled(files.map((f) => fsAsync.writeFile(f.path, f.data, 'utf-8')));
         for (const [i, res] of results.entries()) {
-            const pathWritten = `${syncCacheDir}/${files[i].suffix}${filename}`;
+            const pathWritten = files[i].path;
             if (res.status === 'fulfilled') {
                 logger.info(`State written to file ${pathWritten}`);
             }
@@ -200,7 +241,8 @@ export const saveState = async (wallet, syncCacheDir, filename) => {
     }
 };
 /** Builds and starts a fresh {@link WalletFacade} from `seed`, with no disk persistence. */
-export const initWalletWithSeed = async (env, seed) => {
+export const initWalletWithSeed = async (env, seed, options = {}) => {
+    const dustWalletClass = options.dustWallet ?? dustWalletFromEnv();
     const walletConfig = env.getWalletConfig();
     const seeds = {
         shielded: getShieldedSeed(seed),
@@ -218,8 +260,15 @@ export const initWalletWithSeed = async (env, seed) => {
         },
         shielded: (config) => ShieldedWallet(config).startWithSeed(getShieldedSeed(seed)),
         unshielded: (config) => UnshieldedWallet(config).startWithPublicKey(PublicKey.fromKeyStore(unshieldedKeystore)),
-        dust: (config) => DustWallet(config).startWithSeed(getDustSeed(seed)),
+        dust: (config) => dustWalletClass(config).startWithSeed(getDustSeed(seed)),
     });
-    await facade.start(seeds);
-    return { wallet: facade, shieldedSecretKeys, dustSecretKey, seeds, unshieldedKeystore };
+    await facade.start(seeds, { manualSync: options.manualSync ?? false });
+    return {
+        wallet: facade,
+        shieldedSecretKeys,
+        dustSecretKey,
+        seeds,
+        unshieldedKeystore,
+        dustSyncModel: dustSyncModelOf(dustWalletClass),
+    };
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@midnightntwrk/wallet-sdk-testkit",
   "description": "Reusable wallet-SDK test harness: environment provisioning, wallet bootstrapping, sync waiters and tx-history assertions",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.4",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -39,16 +39,16 @@
     }
   },
   "dependencies": {
-    "@midnightntwrk/ledger-v9": "1.0.0-rc.4",
-    "@midnightntwrk/wallet-sdk-abstractions": "3.0.0-beta.1",
-    "@midnightntwrk/wallet-sdk-address-format": "4.0.0-beta.3",
-    "@midnightntwrk/wallet-sdk-capabilities": "4.0.0-beta.3",
-    "@midnightntwrk/wallet-sdk-dust-wallet": "5.0.0-beta.3",
-    "@midnightntwrk/wallet-sdk-facade": "5.0.0-beta.3",
-    "@midnightntwrk/wallet-sdk-hd": "3.1.0-beta.2",
+    "@midnightntwrk/ledger-v9": "1.0.0-rc.5",
+    "@midnightntwrk/wallet-sdk-abstractions": "3.0.0-beta.2",
+    "@midnightntwrk/wallet-sdk-address-format": "4.0.0-beta.4",
+    "@midnightntwrk/wallet-sdk-capabilities": "4.0.0-beta.4",
+    "@midnightntwrk/wallet-sdk-dust-wallet": "5.0.0-beta.4",
+    "@midnightntwrk/wallet-sdk-facade": "5.0.0-beta.4",
+    "@midnightntwrk/wallet-sdk-hd": "3.1.0-beta.3",
     "@midnightntwrk/wallet-sdk-indexer-client": "2.0.0-beta.2",
-    "@midnightntwrk/wallet-sdk-shielded": "4.0.0-beta.3",
-    "@midnightntwrk/wallet-sdk-unshielded-wallet": "4.0.0-beta.3",
+    "@midnightntwrk/wallet-sdk-shielded": "4.0.0-beta.4",
+    "@midnightntwrk/wallet-sdk-unshielded-wallet": "4.0.0-beta.4",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
     "rxjs": "^7.8.2"
@@ -71,10 +71,13 @@
     "rimraf": "6.1.3",
     "testcontainers": "11.14.0",
     "typescript": "5.9.3",
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
   },
   "scripts": {
     "typecheck": "tsc -b ./tsconfig.json --noEmit --force",
+    "test": "vitest run",
+    "test:unit": "vitest run --project unit --passWithNoTests",
+    "test:integration": "vitest run --project integration --passWithNoTests",
     "lint": "eslint --max-warnings 0",
     "format": "prettier --write \"**/*.{ts,js,json,yaml,yml,md}\"",
     "format:check": "prettier --check \"**/*.{ts,js,json,yaml,yml,md}\"",