@midnightntwrk/wallet-sdk-testkit 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,41 @@
+import { type NetworkId } from '@midnightntwrk/wallet-sdk-abstractions';
+import { type DefaultV1Configuration } from '@midnightntwrk/wallet-sdk-shielded/v1';
+import { type DefaultV1Configuration as DefaultDustV1Configuration } from '@midnightntwrk/wallet-sdk-dust-wallet/v1';
+import { type DefaultProvingConfiguration } from '@midnightntwrk/wallet-sdk-capabilities/proving';
+import { type DefaultSubmissionConfiguration } from '@midnightntwrk/wallet-sdk-capabilities/submission';
+/** Networks a wallet test environment can target. */
+export type MidnightNetwork = 'undeployed' | 'qanet' | 'devnet' | 'preview' | 'preprod';
+/** A remote (already-running) network — anything other than the local testcontainers stack. */
+export type RemoteNetwork = Exclude<MidnightNetwork, 'undeployed'>;
+/**
+ * The fully-resolved set of service endpoints a wallet needs. This is the single source of truth that replaces the
+ * env-var + container-port resolution previously baked into `TestContainersFixture`. Callers either let an environment
+ * factory resolve these or supply them directly.
+ */
+export interface ResolvedEndpoints {
+    readonly networkId: NetworkId.NetworkId;
+    /** Proof-server base URL, e.g. `http://localhost:6300`. No public default exists. */
+    readonly proverUrl: string;
+    readonly indexerHttpUrl: string;
+    readonly indexerWsUrl: string;
+    /** Node RPC (relay) URL, e.g. `wss://rpc.devnet.midnight.network`. */
+    readonly nodeUrl: string;
+}
+/** Shielded + submission + proving configuration consumed by `ShieldedWallet`/`WalletFacade`. */
+export type WalletConfiguration = DefaultV1Configuration & DefaultSubmissionConfiguration & DefaultProvingConfiguration;
+/** Dust wallet configuration consumed by `DustWallet`. */
+export type DustWalletConfiguration = DefaultDustV1Configuration;
+/**
+ * A provisioned wallet test environment. Produced by {@link createRemoteEnvironment} (no Docker) or
+ * `createTestContainersEnvironment` (from the `/testcontainers` entry point). Replaces the old `TestContainersFixture`
+ * class — the wallet-config builders are identical, but the endpoints are injected rather than read from `process.env`
+ * / mapped container ports.
+ */
+export interface WalletTestEnvironment {
+    readonly network: MidnightNetwork;
+    readonly endpoints: ResolvedEndpoints;
+    getWalletConfig(): WalletConfiguration;
+    getDustWalletConfig(): DustWalletConfiguration;
+    /** Tears down any resources (containers) the environment owns. No-op for remote environments. */
+    down(): Promise<void>;
+}

package/dist/types.js

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

package/dist/vitest.d.ts

@@ -0,0 +1,15 @@
+import { type WalletTestEnvironment } from './types.js';
+/**
+ * Registers `beforeAll`/`afterAll` hooks that build a {@link WalletTestEnvironment} from `factory` and tear it down
+ * after the suite. Returns an accessor for use inside tests.
+ *
+ * Replaces the old `useTestContainersFixture()`, but the environment is now whatever the factory returns — e.g.
+ * `createRemoteEnvironment({ network: 'devnet', proverUrl })` (no Docker) or `createTestContainersEnvironment({
+ * network: 'undeployed' })` (from the `/testcontainers` entry).
+ */
+export declare const useWalletTestEnvironment: (factory: () => Promise<WalletTestEnvironment> | WalletTestEnvironment) => (() => WalletTestEnvironment);
+/**
+ * Installs a `beforeEach` hook that logs detailed failure information on each failed attempt of a retried test. Mirrors
+ * the old `setup-retry-logging.ts` setup file; call once per suite (or wire it into a vitest `setupFiles` entry).
+ */
+export declare const installRetryLogging: () => void;

package/dist/vitest.js

@@ -0,0 +1,62 @@
+// 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 { afterAll, beforeAll, beforeEach, onTestFailed } from 'vitest';
+import { logger } from './logger.js';
+/**
+ * Registers `beforeAll`/`afterAll` hooks that build a {@link WalletTestEnvironment} from `factory` and tear it down
+ * after the suite. Returns an accessor for use inside tests.
+ *
+ * Replaces the old `useTestContainersFixture()`, but the environment is now whatever the factory returns — e.g.
+ * `createRemoteEnvironment({ network: 'devnet', proverUrl })` (no Docker) or `createTestContainersEnvironment({
+ * network: 'undeployed' })` (from the `/testcontainers` entry).
+ */
+export const useWalletTestEnvironment = (factory) => {
+    let environment;
+    beforeAll(async () => {
+        environment = await factory();
+        logger.info(`Wallet test environment ready (network=${environment.network})`);
+    }, 120_000);
+    afterAll(async () => {
+        logger.info('Tearing down wallet test environment...');
+        await environment?.down();
+        logger.info('Wallet test environment torn down');
+    }, 60_000);
+    return () => {
+        if (!environment) {
+            throw new Error('Wallet test environment accessed before beforeAll completed');
+        }
+        return environment;
+    };
+};
+/**
+ * Installs a `beforeEach` hook that logs detailed failure information on each failed attempt of a retried test. Mirrors
+ * the old `setup-retry-logging.ts` setup file; call once per suite (or wire it into a vitest `setupFiles` entry).
+ */
+export const installRetryLogging = () => {
+    beforeEach(() => {
+        onTestFailed(({ task: failedTask }) => {
+            const attempt = (failedTask.result?.retryCount ?? 0) + 1;
+            const retry = failedTask.retry;
+            const maxRetries = typeof retry === 'number' ? retry : (retry?.count ?? 0);
+            if (maxRetries > 0) {
+                logger.error(`Test "${failedTask.name}" failed on attempt ${attempt}/${maxRetries + 1}:`);
+                for (const error of failedTask.result?.errors ?? []) {
+                    logger.error(error.message);
+                    if (error.stack) {
+                        logger.error(error.stack);
+                    }
+                }
+            }
+        });
+    });
+};

package/dist/wallet.d.ts

@@ -0,0 +1,34 @@
+import * as ledger from '@midnight-ntwrk/ledger-v8';
+import { WalletFacade } from '@midnightntwrk/wallet-sdk-facade';
+import { type UnshieldedKeystore } from '@midnightntwrk/wallet-sdk-unshielded-wallet';
+import { type WalletTestEnvironment } from './types.js';
+export type WalletInit = {
+    wallet: WalletFacade;
+    shieldedSecretKeys: ledger.ZswapSecretKeys;
+    dustSecretKey: ledger.DustSecretKey;
+    unshieldedKeystore: UnshieldedKeystore;
+};
+/** Options for {@link provideWallet}. */
+export interface ProvideWalletOptions {
+    /** Hex seed used to derive the three sub-wallet keys. */
+    seed: string;
+    /**
+     * Directory used to persist/restore serialized wallet state across runs. When omitted, the wallet is always built
+     * from scratch and nothing is read or written (replaces the old `SYNC_CACHE` env var, which `exit(1)`-ed when unset).
+     * Explicitly allows `undefined` for pass-through under `exactOptionalPropertyTypes`.
+     */
+    syncCacheDir?: string | undefined;
+    /** Filename suffix for the three serialized state files. Required when `syncCacheDir` is set. */
+    filename?: string | undefined;
+}
+/**
+ * Builds a fully-started {@link WalletFacade} (shielded + unshielded + dust) for the given seed.
+ *
+ * If `syncCacheDir`/`filename` are provided, attempts to restore serialized state from disk and verify it syncs;
+ * 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>;
+/** Builds and starts a fresh {@link WalletFacade} from `seed`, with no disk persistence. */
+export declare const initWalletWithSeed: (env: WalletTestEnvironment, seed: string) => Promise<WalletInit>;

package/dist/wallet.js

@@ -0,0 +1,213 @@
+// 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 * as rx from 'rxjs';
+import { existsSync } from 'node:fs';
+import * as fsAsync from 'node:fs/promises';
+import * as ledger from '@midnight-ntwrk/ledger-v8';
+import { InMemoryTransactionHistoryStorage, } from '@midnightntwrk/wallet-sdk-abstractions';
+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';
+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}`);
+}), rx.filter((state) => state.unshielded.progress.isStrictlyComplete())));
+const restoreShieldedWallet = async (path, Wallet, readIfExists) => {
+    try {
+        const serialized = await readIfExists(path);
+        if (serialized) {
+            const wallet = Wallet.restore(serialized);
+            logger.info(`Restored shielded wallet from ${path}`);
+            return wallet;
+        }
+        logger.warn('Unable to restore shielded wallet.');
+    }
+    catch (err) {
+        logger.error(`Failed to restore shielded wallet: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return undefined;
+};
+const restoreUnshieldedWallet = async (path, seed, env, readIfExists, txHistoryStorage) => {
+    try {
+        const serialized = await readIfExists(path);
+        if (serialized) {
+            const keyStore = createKeystore(getUnshieldedSeed(seed), env.endpoints.networkId);
+            const wallet = UnshieldedWallet({
+                networkId: env.endpoints.networkId,
+                indexerClientConnection: {
+                    indexerHttpUrl: env.endpoints.indexerHttpUrl,
+                    indexerWsUrl: env.endpoints.indexerWsUrl,
+                },
+                txHistoryStorage,
+            }).startWithPublicKey(PublicKey.fromKeyStore(keyStore));
+            logger.info(`Restored unshielded wallet from ${path}`);
+            return wallet;
+        }
+        logger.warn('Unable to restore unshielded wallet.');
+    }
+    catch (err) {
+        logger.error(`Failed to restore unshielded wallet: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return undefined;
+};
+const restoreDustWallet = async (path, walletConfig, readIfExists) => {
+    try {
+        const serialized = await readIfExists(path);
+        if (serialized) {
+            const DustInstance = DustWallet({
+                ...walletConfig,
+                costParameters: walletConfig?.costParameters ?? {
+                    feeBlocksMargin: 5,
+                },
+            });
+            const wallet = DustInstance.restore(serialized);
+            logger.info(`Restored dust wallet from ${path}`);
+            return wallet;
+        }
+        logger.warn('Unable to restore dust wallet.');
+    }
+    catch (err) {
+        logger.error(`Failed to restore dust wallet: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return undefined;
+};
+/**
+ * Builds a fully-started {@link WalletFacade} (shielded + unshielded + dust) for the given seed.
+ *
+ * If `syncCacheDir`/`filename` are provided, attempts to restore serialized state from disk and verify it syncs;
+ * otherwise (or on any restore failure) builds from scratch via {@link initWalletWithSeed}.
+ */
+export const provideWallet = async (env, options) => {
+    const { seed, syncCacheDir, filename } = options;
+    if (!syncCacheDir || !filename) {
+        logger.info('No sync cache configured; building wallet facade from scratch');
+        return initWalletWithSeed(env, seed);
+    }
+    // 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
+    // never queries.
+    const txHistoryStorage = new InMemoryTransactionHistoryStorage(WalletEntrySchema, mergeWalletEntries);
+    const walletConfig = { ...env.getWalletConfig(), txHistoryStorage };
+    const dustWalletConfig = { ...env.getDustWalletConfig(), txHistoryStorage };
+    const Wallet = ShieldedWallet(walletConfig);
+    const shieldedSecretKeys = ledger.ZswapSecretKeys.fromSeed(getShieldedSeed(seed));
+    const dustSecretKey = ledger.DustSecretKey.fromSeed(getDustSeed(seed));
+    const unshieldedKeystore = createKeystore(getUnshieldedSeed(seed), env.endpoints.networkId);
+    const readIfExists = async (p) => {
+        try {
+            if (!existsSync(p))
+                return undefined;
+            return await fsAsync.readFile(p, 'utf-8');
+        }
+        catch (err) {
+            logger.error(`Failed to read ${p}: ${err instanceof Error ? err.message : String(err)}`);
+            return undefined;
+        }
+    };
+    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),
+    ]);
+    if (!restoredShielded || !restoredUnshielded || !restoredDust) {
+        logger.info('Building wallet facade from scratch');
+        return initWalletWithSeed(env, seed);
+    }
+    else {
+        const restoredWallet = await WalletFacade.init({
+            configuration: {
+                ...walletConfig,
+                ...dustWalletConfig,
+            },
+            shielded: () => restoredShielded,
+            unshielded: () => restoredUnshielded,
+            dust: () => restoredDust,
+        });
+        await restoredWallet.start(shieldedSecretKeys, dustSecretKey);
+        // check if wallet is syncing correctly
+        await waitForSyncProgress(restoredWallet);
+        const restoredWalletState = await rx.firstValueFrom(restoredWallet.state());
+        const applyGap = restoredWalletState.unshielded.progress.highestTransactionId - restoredWalletState.unshielded.progress.appliedId;
+        logger.info(`Apply gap: ${applyGap}`);
+        if ((applyGap ?? 0) < 0) {
+            logger.warn('Unable to sync restored wallet. Building wallet facade from scratch');
+            await restoredWallet.stop();
+            return initWalletWithSeed(env, seed);
+        }
+        else {
+            logger.info('Successfully restored wallet facade.');
+            return { wallet: restoredWallet, shieldedSecretKeys, dustSecretKey, unshieldedKeystore };
+        }
+    }
+};
+/** Serializes all three sub-wallet states into `syncCacheDir`, keyed by `filename`. */
+export const saveState = async (wallet, 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(),
+        ]);
+        const files = [
+            { suffix: 'shielded-', data: shieldedSerializedState },
+            { suffix: 'unshielded-', data: unshieldedSerializedState },
+            { suffix: 'dust-', data: dustSerializedState },
+        ];
+        const results = await Promise.allSettled(files.map((f) => fsAsync.writeFile(`${syncCacheDir}/${f.suffix}${filename}`, f.data, 'utf-8')));
+        for (const [i, res] of results.entries()) {
+            const pathWritten = `${syncCacheDir}/${files[i].suffix}${filename}`;
+            if (res.status === 'fulfilled') {
+                logger.info(`State written to file ${pathWritten}`);
+            }
+            else {
+                logger.error(`Failed to write ${pathWritten}: ${res.reason instanceof Error ? res.reason.message : String(res.reason)}`);
+            }
+        }
+    }
+    catch (e) {
+        if (typeof e === 'string') {
+            logger.warn(e);
+        }
+        else if (e instanceof Error) {
+            logger.warn(e.message);
+        }
+        else {
+            logger.warn('Unknown error while saving state');
+        }
+    }
+};
+/** Builds and starts a fresh {@link WalletFacade} from `seed`, with no disk persistence. */
+export const initWalletWithSeed = async (env, seed) => {
+    const walletConfig = env.getWalletConfig();
+    const shieldedSecretKeys = ledger.ZswapSecretKeys.fromSeed(getShieldedSeed(seed));
+    const dustSecretKey = ledger.DustSecretKey.fromSeed(getDustSeed(seed));
+    const unshieldedKeystore = createKeystore(getUnshieldedSeed(seed), env.endpoints.networkId);
+    const facade = await WalletFacade.init({
+        configuration: {
+            ...walletConfig,
+            ...env.getDustWalletConfig(),
+            txHistoryStorage: new InMemoryTransactionHistoryStorage(WalletEntrySchema, mergeWalletEntries),
+        },
+        shielded: (config) => ShieldedWallet(config).startWithSeed(getShieldedSeed(seed)),
+        unshielded: (config) => UnshieldedWallet(config).startWithPublicKey(PublicKey.fromKeyStore(unshieldedKeystore)),
+        dust: (config) => DustWallet(config).startWithSeed(getDustSeed(seed), ledger.LedgerParameters.initialParameters().dust),
+    });
+    await facade.start(shieldedSecretKeys, dustSecretKey);
+    return { wallet: facade, shieldedSecretKeys, dustSecretKey, unshieldedKeystore };
+};

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@midnightntwrk/wallet-sdk-testkit",
+  "description": "Reusable wallet-SDK test harness: environment provisioning, wallet bootstrapping, sync waiters and tx-history assertions",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "author": "Midnight Foundation",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com/"
+  },
+  "files": [
+    "dist/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/midnightntwrk/midnight-wallet.git",
+    "directory": "packages/wallet-sdk-testkit"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js"
+    },
+    "./testcontainers": {
+      "types": "./dist/testcontainers.d.ts",
+      "import": "./dist/testcontainers.js"
+    },
+    "./scenarios": {
+      "types": "./dist/scenarios/index.d.ts",
+      "import": "./dist/scenarios/index.js"
+    }
+  },
+  "dependencies": {
+    "@midnight-ntwrk/ledger-v8": "^8.1.0",
+    "@midnightntwrk/wallet-sdk-abstractions": "workspace:^",
+    "@midnightntwrk/wallet-sdk-address-format": "workspace:^",
+    "@midnightntwrk/wallet-sdk-capabilities": "workspace:^",
+    "@midnightntwrk/wallet-sdk-dust-wallet": "workspace:^",
+    "@midnightntwrk/wallet-sdk-facade": "workspace:^",
+    "@midnightntwrk/wallet-sdk-hd": "workspace:^",
+    "@midnightntwrk/wallet-sdk-indexer-client": "workspace:^",
+    "@midnightntwrk/wallet-sdk-shielded": "workspace:^",
+    "@midnightntwrk/wallet-sdk-unshielded-wallet": "workspace:^",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "rxjs": "^7.8.2"
+  },
+  "peerDependencies": {
+    "@midnightntwrk/wallet-sdk-utilities": "workspace:^",
+    "testcontainers": "^11.12.0",
+    "vitest": "^4.1.4"
+  },
+  "peerDependenciesMeta": {
+    "@midnightntwrk/wallet-sdk-utilities": {
+      "optional": true
+    },
+    "testcontainers": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@midnightntwrk/wallet-sdk-utilities": "workspace:^",
+    "rimraf": "^6.1.3",
+    "testcontainers": "^11.12.0",
+    "typescript": "^5.9.3",
+    "vitest": "4.1.8"
+  },
+  "scripts": {
+    "typecheck": "tsc -b ./tsconfig.json --noEmit --force",
+    "lint": "eslint --max-warnings 0",
+    "format": "prettier --write \"**/*.{ts,js,json,yaml,yml,md}\"",
+    "format:check": "prettier --check \"**/*.{ts,js,json,yaml,yml,md}\"",
+    "dist": "tsc -b ./tsconfig.build.json",
+    "dist:publish": "tsc -b ./tsconfig.publish.json",
+    "clean": "rimraf --glob dist 'tsconfig.*.tsbuildinfo'",
+    "publint": "publint --strict"
+  }
+}