@midnightntwrk/wallet-sdk-testkit 0.2.0

package/README.md

@@ -0,0 +1,68 @@
+# @midnightntwrk/wallet-sdk-testkit
+
+Reusable wallet-SDK test harness, extracted from `packages/e2e-tests`. Provides environment provisioning, wallet
+bootstrapping, sync waiters, and tx-history assertions as a published package so downstream consumers (e.g. monitoring /
+healthcheck suites) can write their own test scenarios against the same harness instead of vendoring copies of these
+files.
+
+## What's here
+
+| Area                 | Exports                                                                                                       |
+| -------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Environment          | `createRemoteEnvironment`, `NETWORK_PRESETS`, `makeEnvironment`, `WalletTestEnvironment`, `ResolvedEndpoints` |
+| Environment (Docker) | `createTestContainersEnvironment` — from `@midnightntwrk/wallet-sdk-testkit/testcontainers`                   |
+| Wallet               | `provideWallet`, `initWalletWithSeed`, `saveState`, `WalletInit`                                              |
+| Seeds                | `getShieldedSeed`, `getUnshieldedSeed`, `getDustSeed`                                                         |
+| Sync waiters         | `waitForSyncUnshielded`, `waitForDustBalance`, `waitForTxInHistory`, …                                        |
+| Assertions           | `expectSenderShieldedTxHistory`, `expectReceiverUnshieldedTxHistory`, …                                       |
+| Addresses            | `validateNetworkInAddress`, `getShieldedAddress`, `getUnshieldedAddress`                                      |
+| Vitest glue          | `useWalletTestEnvironment`, `installRetryLogging`                                                             |
+| Logging              | `logger`, `setLogger`, `getLogger`                                                                            |
+
+## Key change from `e2e-tests`
+
+The old `TestContainersFixture` resolved endpoints from `process.env` (`NETWORK`, `PROOF_SERVER_URL`, `SYNC_CACHE`) and
+mapped container ports. That coupling is gone: a `WalletTestEnvironment` now carries fully-resolved `endpoints`,
+produced either by `createTestContainersEnvironment` (Docker) or `createRemoteEnvironment` (no Docker, point at an
+already-running network). Downstream consumers no longer need to patch this file to inject a proof-server URL.
+
+## Usage — remote network, no Docker
+
+```ts
+import { afterAll } from 'vitest';
+import {
+  createRemoteEnvironment,
+  useWalletTestEnvironment,
+  provideWallet,
+  waitForDustBalance,
+} from '@midnightntwrk/wallet-sdk-testkit';
+
+const getEnv = useWalletTestEnvironment(() =>
+  createRemoteEnvironment({
+    network: 'devnet',
+    proverUrl: process.env.PROOF_SERVER_URL!, // a running proof server you control
+  }),
+);
+
+test('wallet reaches a dust balance', async () => {
+  const env = getEnv();
+  const { wallet } = await provideWallet(env, { seed: MY_SEED });
+  afterAll(() => wallet.stop());
+  await waitForDustBalance(wallet);
+});
+```
+
+## Usage — local stack via testcontainers
+
+```ts
+import { useWalletTestEnvironment } from '@midnightntwrk/wallet-sdk-testkit';
+import { createTestContainersEnvironment } from '@midnightntwrk/wallet-sdk-testkit/testcontainers';
+
+const getEnv = useWalletTestEnvironment(() => createTestContainersEnvironment({ network: 'undeployed' }));
+```
+
+## Peer dependencies
+
+- `vitest` — required (assertions and the environment hooks use it).
+- `testcontainers` and `@midnightntwrk/wallet-sdk-utilities` — optional; only needed for the `/testcontainers` entry
+  point.

package/dist/addresses.d.ts

@@ -0,0 +1,12 @@
+import { type NetworkId } from '@midnightntwrk/wallet-sdk-abstractions';
+import { ShieldedAddress, UnshieldedAddress } from '@midnightntwrk/wallet-sdk-address-format';
+import { type MidnightNetwork } from './types.js';
+/**
+ * Asserts the bech32m network prefix of `address` matches `expectedNetwork`.
+ *
+ * Replaces the old `TestContainersFixture.network` static read — the expected network is now an explicit argument
+ * (typically `env.network`).
+ */
+export declare function validateNetworkInAddress(address: string, expectedNetwork: MidnightNetwork): void;
+export declare function getShieldedAddress(networkId: NetworkId.NetworkId, walletAddress: ShieldedAddress): string;
+export declare function getUnshieldedAddress(networkId: NetworkId.NetworkId, walletAddress: UnshieldedAddress): string;

package/dist/addresses.js

@@ -0,0 +1,30 @@
+// 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 { expect } from 'vitest';
+import { MidnightBech32m, ShieldedAddress, UnshieldedAddress } from '@midnightntwrk/wallet-sdk-address-format';
+/**
+ * Asserts the bech32m network prefix of `address` matches `expectedNetwork`.
+ *
+ * Replaces the old `TestContainersFixture.network` static read — the expected network is now an explicit argument
+ * (typically `env.network`).
+ */
+export function validateNetworkInAddress(address, expectedNetwork) {
+    const parsed = MidnightBech32m.parse(address);
+    expect(parsed.network).toBe(expectedNetwork);
+}
+export function getShieldedAddress(networkId, walletAddress) {
+    return ShieldedAddress.codec.encode(networkId, walletAddress).asString();
+}
+export function getUnshieldedAddress(networkId, walletAddress) {
+    return UnshieldedAddress.codec.encode(networkId, walletAddress).asString();
+}

package/dist/core.d.ts

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './logger.js';
+export * from './environment.js';
+export * from './network.js';
+export * from './seeds.js';
+export * from './primitives.js';
+export * from './wallet.js';

package/dist/core.js

@@ -0,0 +1,24 @@
+// 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.
+//
+// Vitest-free harness: types, environment provisioning, wallet bootstrapping, seeds, network
+// helpers, and logging. Import from `@midnightntwrk/wallet-sdk-testkit/core` in non-test contexts
+// (e.g. standalone diagnostic scripts) to avoid transitively loading `vitest`, which the root
+// entry's assertion / sync-waiter / suite-glue helpers require.
+export * from './types.js';
+export * from './logger.js';
+export * from './environment.js';
+export * from './network.js';
+export * from './seeds.js';
+export * from './primitives.js';
+export * from './wallet.js';

package/dist/environment.d.ts

@@ -0,0 +1,37 @@
+import { type MidnightNetwork, type RemoteNetwork, type ResolvedEndpoints, type WalletTestEnvironment } from './types.js';
+/** Public service endpoints for each remote network, minus the (caller-supplied) prover URL. */
+export type RemoteNetworkPreset = Omit<ResolvedEndpoints, 'proverUrl'>;
+/**
+ * Endpoint presets lifted verbatim from the old `TestContainersFixture` getters. The proof server is intentionally
+ * absent — there is no public prover, so every remote environment must be told where to find one.
+ */
+export declare const NETWORK_PRESETS: Record<RemoteNetwork, RemoteNetworkPreset>;
+/**
+ * Builds a {@link WalletTestEnvironment} from already-resolved endpoints. Shared by the remote factory below and the
+ * testcontainers factory (which resolves endpoints from mapped ports first). The two `get*Config` builders are
+ * byte-for-byte the behaviour of the old fixture, except the URLs come from `endpoints` instead of `process.env` /
+ * container introspection.
+ */
+export declare const makeEnvironment: (network: MidnightNetwork, endpoints: ResolvedEndpoints, options?: {
+    down?: () => Promise<void>;
+}) => WalletTestEnvironment;
+/** Configuration for {@link createRemoteEnvironment}. */
+export interface RemoteEnvironmentConfig {
+    /** Which remote network's endpoint preset to start from. */
+    network: RemoteNetwork;
+    /** Proof-server base URL. Required — there is no public prover. */
+    proverUrl: string;
+    /**
+     * Optional endpoint overrides. Use this to point at an internal indexer/node (e.g. a monitoring deployment that
+     * proxies the public ones) without abandoning the preset for the rest.
+     */
+    endpoints?: Partial<Omit<ResolvedEndpoints, 'proverUrl'>>;
+}
+/**
+ * Creates a no-Docker environment pointed at an already-running network.
+ *
+ * This is the path downstream consumers (e.g. sentinel monitoring) use: supply a prover URL and a network preset, get
+ * back the same `WalletTestEnvironment` the local testcontainers stack produces — with no testcontainers dependency
+ * loaded and no `process.env` patching required.
+ */
+export declare const createRemoteEnvironment: (config: RemoteEnvironmentConfig) => WalletTestEnvironment;

package/dist/environment.js

@@ -0,0 +1,101 @@
+// 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 { InMemoryTransactionHistoryStorage, NetworkId } from '@midnightntwrk/wallet-sdk-abstractions';
+import { WalletEntrySchema, mergeWalletEntries } from '@midnightntwrk/wallet-sdk-facade';
+/**
+ * Endpoint presets lifted verbatim from the old `TestContainersFixture` getters. The proof server is intentionally
+ * absent — there is no public prover, so every remote environment must be told where to find one.
+ */
+export const NETWORK_PRESETS = {
+    devnet: {
+        networkId: NetworkId.NetworkId.DevNet,
+        indexerHttpUrl: 'https://indexer.devnet.midnight.network/api/v4/graphql',
+        indexerWsUrl: 'wss://indexer.devnet.midnight.network/api/v4/graphql/ws',
+        nodeUrl: 'wss://rpc.devnet.midnight.network',
+    },
+    qanet: {
+        networkId: NetworkId.NetworkId.QaNet,
+        indexerHttpUrl: 'https://indexer.qanet.midnight.network/api/v4/graphql',
+        // NB: qanet ws is served from the `indexer-blue` host — preserved from upstream.
+        indexerWsUrl: 'wss://indexer-blue.qanet.midnight.network/api/v4/graphql/ws',
+        nodeUrl: 'wss://rpc.qanet.midnight.network',
+    },
+    preview: {
+        networkId: NetworkId.NetworkId.Preview,
+        indexerHttpUrl: 'https://indexer.preview.midnight.network/api/v4/graphql',
+        indexerWsUrl: 'wss://indexer.preview.midnight.network/api/v4/graphql/ws',
+        nodeUrl: 'wss://rpc.preview.midnight.network',
+    },
+    preprod: {
+        networkId: NetworkId.NetworkId.PreProd,
+        indexerHttpUrl: 'https://indexer.preprod.midnight.network/api/v4/graphql',
+        indexerWsUrl: 'wss://indexer.preprod.midnight.network/api/v4/graphql/ws',
+        nodeUrl: 'wss://rpc.preprod.midnight.network',
+    },
+};
+/**
+ * Builds a {@link WalletTestEnvironment} from already-resolved endpoints. Shared by the remote factory below and the
+ * testcontainers factory (which resolves endpoints from mapped ports first). The two `get*Config` builders are
+ * byte-for-byte the behaviour of the old fixture, except the URLs come from `endpoints` instead of `process.env` /
+ * container introspection.
+ */
+export const makeEnvironment = (network, endpoints, options = {}) => ({
+    network,
+    endpoints,
+    getWalletConfig() {
+        return {
+            indexerClientConnection: {
+                indexerHttpUrl: endpoints.indexerHttpUrl,
+                indexerWsUrl: endpoints.indexerWsUrl,
+            },
+            provingServerUrl: new URL(endpoints.proverUrl),
+            relayURL: new URL(endpoints.nodeUrl),
+            networkId: endpoints.networkId,
+            txHistoryStorage: new InMemoryTransactionHistoryStorage(WalletEntrySchema, mergeWalletEntries),
+        };
+    },
+    getDustWalletConfig() {
+        return {
+            networkId: endpoints.networkId,
+            costParameters: {
+                feeBlocksMargin: 5,
+            },
+            txHistoryStorage: new InMemoryTransactionHistoryStorage(WalletEntrySchema, mergeWalletEntries),
+            indexerClientConnection: {
+                indexerHttpUrl: endpoints.indexerHttpUrl,
+            },
+        };
+    },
+    down: options.down ?? (async () => { }),
+});
+/**
+ * Creates a no-Docker environment pointed at an already-running network.
+ *
+ * This is the path downstream consumers (e.g. sentinel monitoring) use: supply a prover URL and a network preset, get
+ * back the same `WalletTestEnvironment` the local testcontainers stack produces — with no testcontainers dependency
+ * loaded and no `process.env` patching required.
+ */
+export const createRemoteEnvironment = (config) => {
+    if (!config.proverUrl) {
+        throw new Error('createRemoteEnvironment: `proverUrl` is required (there is no public proof server).');
+    }
+    const preset = NETWORK_PRESETS[config.network];
+    const endpoints = {
+        networkId: config.endpoints?.networkId ?? preset.networkId,
+        proverUrl: config.proverUrl,
+        indexerHttpUrl: config.endpoints?.indexerHttpUrl ?? preset.indexerHttpUrl,
+        indexerWsUrl: config.endpoints?.indexerWsUrl ?? preset.indexerWsUrl,
+        nodeUrl: config.endpoints?.nodeUrl ?? preset.nodeUrl,
+    };
+    return makeEnvironment(config.network, endpoints);
+};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './core.js';
+export * from './addresses.js';
+export * from './state-waiters.js';
+export * from './tx-history-asserts.js';
+export * from './vitest.js';

package/dist/index.js

@@ -0,0 +1,26 @@
+// 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.
+//
+// Full entry point. Re-exports the vitest-free core (environment, wallet, seeds, network, logging)
+// plus the vitest-coupled helpers (assertions, sync waiters, address validation, suite glue).
+// Importing this pulls in `vitest`; non-test consumers should import from
+// `@midnightntwrk/wallet-sdk-testkit/core` instead.
+//
+// The Docker-backed environment lives at `@midnightntwrk/wallet-sdk-testkit/testcontainers` so it
+// (and the `testcontainers` peer dependency) is only loaded when actually needed.
+export * from './core.js';
+// vitest-coupled (each imports from 'vitest' at module load):
+export * from './addresses.js';
+export * from './state-waiters.js';
+export * from './tx-history-asserts.js';
+export * from './vitest.js';

package/dist/logger.d.ts

@@ -0,0 +1,6 @@
+import { type Logger } from 'pino';
+/** Replace the logger used by all testkit helpers. Pass any pino-compatible logger. */
+export declare const setLogger: (next: Logger) => void;
+/** Returns the currently-active logger instance. */
+export declare const getLogger: () => Logger;
+export declare const logger: Logger;

package/dist/logger.js

@@ -0,0 +1,36 @@
+// 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 pinoPretty from 'pino-pretty';
+import pino from 'pino';
+// Unlike the original e2e-tests logger, a published package must not write log files to a
+// path relative to its own source. The default here is a plain pretty stdout logger; consumers
+// that want file output (or structured JSON, or their own pino instance) call `setLogger`.
+const createDefaultLogger = () => {
+    const pretty = pinoPretty({ colorize: true, sync: true });
+    return pino({ level: process.env['WALLET_TESTKIT_LOG_LEVEL'] ?? 'info', depthLimit: 20 }, pretty);
+};
+let current = createDefaultLogger();
+/** Replace the logger used by all testkit helpers. Pass any pino-compatible logger. */
+export const setLogger = (next) => {
+    current = next;
+};
+/** Returns the currently-active logger instance. */
+export const getLogger = () => current;
+// A stable proxy so existing call sites (`logger.info(...)`) keep working *and* pick up
+// whatever `setLogger` installed, without every helper having to call `getLogger()`.
+export const logger = new Proxy({}, {
+    get(_target, property) {
+        const value = current[property];
+        return typeof value === 'function' ? value.bind(current) : value;
+    },
+});

package/dist/network.d.ts

@@ -0,0 +1,6 @@
+export declare const sleep: (secs: number) => Promise<void>;
+/**
+ * Waits for the blockchain to produce at least one new block by polling the indexer for the current block height.
+ * Resolves as soon as the height increases from its initial value.
+ */
+export declare const waitForBlockAdvancement: (indexerHttpUrl: string, timeoutMs?: number) => Promise<void>;

package/dist/network.js

@@ -0,0 +1,43 @@
+// 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 { BlockHash } from '@midnightntwrk/wallet-sdk-indexer-client';
+import { QueryRunner } from '@midnightntwrk/wallet-sdk-indexer-client/effect';
+import { logger } from './logger.js';
+export const sleep = (secs) => {
+    return new Promise((resolve) => setTimeout(resolve, secs * 1000));
+};
+const fetchBlockHeight = async (indexerHttpUrl) => {
+    const result = await QueryRunner.runPromise(BlockHash, { offset: null }, { url: indexerHttpUrl });
+    if (!result.block)
+        throw new Error('No block returned from indexer');
+    return result.block.height;
+};
+/**
+ * Waits for the blockchain to produce at least one new block by polling the indexer for the current block height.
+ * Resolves as soon as the height increases from its initial value.
+ */
+export const waitForBlockAdvancement = async (indexerHttpUrl, timeoutMs = 60_000) => {
+    const initialHeight = await fetchBlockHeight(indexerHttpUrl);
+    logger.info(`Waiting for block advancement beyond height ${initialHeight}...`);
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        await sleep(2);
+        const currentHeight = await fetchBlockHeight(indexerHttpUrl);
+        logger.info(`Current block height: ${currentHeight} (waiting for > ${initialHeight})`);
+        if (currentHeight > initialHeight) {
+            logger.info('Block advancement detected');
+            return;
+        }
+    }
+    throw new Error(`Timed out waiting for block advancement beyond height ${initialHeight} after ${timeoutMs}ms`);
+};

package/dist/primitives.d.ts

@@ -0,0 +1,2 @@
+export declare const tNightAmount: (amount: bigint) => bigint;
+export declare const isArrayUnique: (arr: unknown[]) => boolean;

package/dist/primitives.js

@@ -0,0 +1,14 @@
+// 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.
+export const tNightAmount = (amount) => amount * 10n ** 6n;
+export const isArrayUnique = (arr) => Array.isArray(arr) && new Set(arr).size === arr.length;

package/dist/scenarios/dust.d.ts

@@ -0,0 +1,14 @@
+import { type WalletTestEnvironment } from '../types.js';
+/** Dependencies the dust scenarios need from the consumer. */
+export interface DustScenarioDeps {
+    /** Accessor for the active environment (typically the return of `useWalletTestEnvironment`). */
+    getEnv: () => WalletTestEnvironment;
+    /** Hex seed of a funded wallet holding registerable Night UTXOs. (Was the `SEED` env var.) */
+    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. */
+    timeout?: number | undefined;
+}
+/** Registers the dust register/deregister healthchecks under a `describe('Dust tests')` block. */
+export declare function registerDustHealthchecks({ getEnv, seed, syncCacheDir, timeout }: DustScenarioDeps): void;

package/dist/scenarios/dust.js

@@ -0,0 +1,91 @@
+// 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.
+//
+// Dust healthcheck scenarios. The test bodies are single-sourced here and registered by both the
+// upstream e2e-tests suite and downstream consumers (e.g. sentinel monitoring), each supplying its
+// own environment via `getEnv`. The `@healthcheck`-tagged test names are preserved so consumers can
+// select them with `vitest run -t @healthcheck`.
+import { describe, test, expect, beforeEach, afterEach } from 'vitest';
+import { inspect } from 'node:util';
+import * as rx from 'rxjs';
+import * as ledger from '@midnight-ntwrk/ledger-v8';
+import { provideWallet, saveState } 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 }) {
+    describe('Dust tests', () => {
+        const unshieldedTokenRaw = ledger.unshieldedToken().raw;
+        let wallet;
+        let filenameWallet;
+        beforeEach(async () => {
+            const env = getEnv();
+            filenameWallet = `${seed.substring(0, 7)}-${env.network}.state`;
+            wallet = await provideWallet(env, { seed, syncCacheDir, filename: filenameWallet });
+        });
+        afterEach(async () => {
+            if (syncCacheDir) {
+                await saveState(wallet.wallet, syncCacheDir, filenameWallet);
+            }
+            await wallet.wallet.stop();
+            logger.info('Wallet stopped');
+        });
+        test('Able to register Night tokens for Dust generation @healthcheck', async () => {
+            const initialState = await wallet.wallet.waitForSyncedState();
+            const initialUnshieldedBalance = initialState.unshielded.balances[unshieldedTokenRaw];
+            const initialDustBalance = initialState.dust.balance(new Date());
+            logger.info(`Wallet: ${initialUnshieldedBalance} unshielded tokens`);
+            logger.info(`wallet dust balance: ${initialDustBalance}`);
+            logger.info(`Wallet total unshielded coins: ${initialState.unshielded.availableCoins.length}`);
+            logger.info(inspect(initialState.unshielded.availableCoins, { depth: null }));
+            const unregisteredNightUtxos = initialState.unshielded.availableCoins.filter((coin) => coin.utxo.type === unshieldedTokenRaw && coin.meta.registeredForDustGeneration === false);
+            const registeredNightUtxos = initialState.unshielded.availableCoins.filter((coin) => coin.utxo.type === unshieldedTokenRaw && coin.meta.registeredForDustGeneration === true);
+            const unregisteredUtxosNumber = unregisteredNightUtxos.length;
+            expect(unregisteredUtxosNumber, 'Not enough unregistered UTXOs found').toBeGreaterThan(1);
+            logger.info(`utxo length: ${unregisteredUtxosNumber}`);
+            const firstTwoNightUtxos = unregisteredNightUtxos.slice(0, 2);
+            logger.info(`Registering UTXOs: ${inspect(firstTwoNightUtxos, { depth: null })}`);
+            const dustRegistrationRecipe = await wallet.wallet.registerNightUtxosForDustGeneration(firstTwoNightUtxos, wallet.unshieldedKeystore.getPublicKey(), (payload) => wallet.unshieldedKeystore.signData(payload));
+            const finalizedDustTx = await wallet.wallet.finalizeRecipe(dustRegistrationRecipe);
+            const dustRegistrationTxid = await wallet.wallet.submitTransaction(finalizedDustTx);
+            expect(dustRegistrationTxid).toBeDefined();
+            logger.info(`Dust registration tx id: ${dustRegistrationTxid}`);
+            const finalWalletState = await rx.firstValueFrom(wallet.wallet.state().pipe(rx.tap((s) => {
+                const registeredTokens = s.unshielded.availableCoins.filter((coin) => coin.utxo.type === unshieldedTokenRaw && coin.meta.registeredForDustGeneration === true);
+                logger.info(`registered tokens: ${registeredTokens.length}`);
+            }), rx.filter((s) => s.unshielded.availableCoins.filter((coin) => coin.utxo.type === unshieldedTokenRaw && coin.meta.registeredForDustGeneration === true).length >=
+                registeredNightUtxos.length + 2 && s.isSynced === true)));
+            const finalNightUtxos = finalWalletState.unshielded.availableCoins.filter((coin) => coin.utxo.type === unshieldedTokenRaw && coin.meta.registeredForDustGeneration === true);
+            expect(finalNightUtxos.length).toBe(registeredNightUtxos.length + 2);
+        }, timeout);
+        test('Able to deregister night tokens for dust decay @healthcheck', async () => {
+            const initialWalletState = await wallet.wallet.waitForSyncedState();
+            const initialDustBalance = initialWalletState.dust.balance(new Date());
+            logger.info(`Initial Dust Balance: ${initialDustBalance}`);
+            const registeredNightUtxos = initialWalletState.unshielded.availableCoins.filter((coin) => coin.utxo.type === unshieldedTokenRaw && coin.meta.registeredForDustGeneration === true);
+            logger.info(`Registered night UTXOs: ${inspect(registeredNightUtxos, { depth: null })}`);
+            expect(registeredNightUtxos.length, 'Not enough registered UTXOs found').toBeGreaterThan(1);
+            const firstTwoRegisteredNightUtxos = registeredNightUtxos.slice(0, 2);
+            const dustDeregistrationRecipe = await wallet.wallet.deregisterFromDustGeneration(firstTwoRegisteredNightUtxos, wallet.unshieldedKeystore.getPublicKey(), (payload) => wallet.unshieldedKeystore.signData(payload));
+            const balancedTransactionRecipe = await wallet.wallet.balanceUnprovenTransaction(dustDeregistrationRecipe.transaction, {
+                shieldedSecretKeys: wallet.shieldedSecretKeys,
+                dustSecretKey: wallet.dustSecretKey,
+            }, {
+                ttl: new Date(Date.now() + 30 * 60 * 1000),
+            });
+            const finalizedDustTx = await wallet.wallet.finalizeRecipe(balancedTransactionRecipe);
+            const dustDeregistrationTxid = await wallet.wallet.submitTransaction(finalizedDustTx);
+            expect(dustDeregistrationTxid).toBeDefined();
+            logger.info(`Dust de-registration tx id: ${dustDeregistrationTxid}`);
+        }, timeout);
+    });
+}

package/dist/scenarios/index.d.ts

@@ -0,0 +1,2 @@
+export * from './dust.js';
+export * from './token-transfer.js';

package/dist/scenarios/index.js

@@ -0,0 +1,19 @@
+// 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.
+//
+// Shared, single-sourced test scenarios. Each `register*` function declares its `describe/test`
+// blocks; consumers supply the environment and seeds. Lives behind the `/scenarios` entry point
+// because importing it has the side effect of registering vitest suites — only do so from a file
+// the consumer's vitest discovers as a test.
+export * from './dust.js';
+export * from './token-transfer.js';

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

@@ -0,0 +1,39 @@
+import { type NetworkId } from '@midnightntwrk/wallet-sdk-abstractions';
+import { type WalletTestEnvironment } from '../types.js';
+import { 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`). */
+    getEnv: () => WalletTestEnvironment;
+    /** Hex seed of the primary funded wallet. (Was the `SEED` env var.) */
+    fundedSeed: string;
+    /** Hex seed of the second wallet. (Was the `SEED2` env var.) */
+    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. */
+    syncTimeout?: number | undefined;
+    /** Timeout for the `afterEach` teardown in ms. Defaults to 10 minutes. */
+    timeout?: number | undefined;
+}
+/** Accessors returned by {@link useTokenTransferWallets}, valid inside `test`/`it` bodies. */
+export interface TokenTransferWallets {
+    /** The wallet holding the larger shielded balance at setup time. */
+    getSender: () => WalletInit;
+    /** The other wallet. */
+    getReceiver: () => WalletInit;
+    getNetworkId: () => NetworkId.NetworkId;
+}
+/**
+ * Registers the shared two-wallet `beforeEach`/`afterEach` used by every token-transfer test and returns accessors.
+ * 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;
+/**
+ * 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
+ *
+ * @healthcheck`.
+ */
+export declare function registerTokenTransferHealthchecks(deps: TokenTransferScenarioDeps): void;