@midnightntwrk/wallet-sdk-testkit 0.2.0

package/dist/scenarios/token-transfer.js

@@ -0,0 +1,212 @@
+// 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.
+//
+// Token-transfer healthcheck scenario. Only the `@healthcheck`-tagged test lives here — it is the
+// one downstream monitoring (sentinel) consumes and so must be single-sourced. The remaining
+// token-transfer tests (self-transaction, swap, error cases, dev TODOs) stay in the upstream
+// e2e-tests suite; they share the two-wallet setup via the exported `useTokenTransferWallets`.
+import { describe, test, expect, beforeEach, afterEach } from 'vitest';
+import { firstValueFrom } from 'rxjs';
+import { inspect } from 'node:util';
+import * as ledger from '@midnight-ntwrk/ledger-v8';
+import { provideWallet, saveState } from '../wallet.js';
+import { tNightAmount } from '../primitives.js';
+import { getShieldedAddress, getUnshieldedAddress } from '../addresses.js';
+import { waitForTxInHistory } from '../state-waiters.js';
+import { expectReceiverShieldedTxHistory, expectReceiverUnshieldedTxHistory, expectSenderShieldedTxHistory, expectSenderUnshieldedTxHistory, } from '../tx-history-asserts.js';
+import { logger } from '../logger.js';
+/**
+ * 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 function useTokenTransferWallets({ getEnv, fundedSeed, secondSeed, syncCacheDir, syncTimeout = 60 * 60 * 1000, timeout = 600_000, }) {
+    const shieldedTokenRaw = ledger.shieldedToken().raw;
+    let sender;
+    let receiver;
+    let wallet;
+    let wallet2;
+    let networkId;
+    let filenameWallet;
+    let filenameWallet2;
+    beforeEach(async () => {
+        const env = getEnv();
+        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 });
+        logger.info('Two wallets started');
+        const [state1, state2] = await Promise.all([
+            wallet.wallet.waitForSyncedState(),
+            wallet2.wallet.waitForSyncedState(),
+        ]);
+        const balance1 = state1.shielded.balances[shieldedTokenRaw] ?? 0n;
+        const balance2 = state2.shielded.balances[shieldedTokenRaw] ?? 0n;
+        logger.info(`Wallet 1 shielded balance: ${balance1}, Wallet 2 shielded balance: ${balance2}`);
+        if (balance1 >= balance2) {
+            logger.info('Wallet 1 (SEED) has more funds — using as sender');
+            sender = wallet;
+            receiver = wallet2;
+        }
+        else {
+            logger.info('Wallet 2 (SEED2) has more funds — using as sender');
+            sender = wallet2;
+            receiver = wallet;
+        }
+    }, syncTimeout);
+    afterEach(async () => {
+        if (syncCacheDir) {
+            await saveState(wallet.wallet, syncCacheDir, filenameWallet);
+            await saveState(wallet2.wallet, syncCacheDir, filenameWallet2);
+        }
+        await sender.wallet.stop();
+        await receiver.wallet.stop();
+        logger.info('Wallets stopped');
+    }, timeout);
+    const requireWallet = (w, label) => {
+        if (!w)
+            throw new Error(`${label} accessed before beforeEach completed`);
+        return w;
+    };
+    return {
+        getSender: () => requireWallet(sender, 'sender'),
+        getReceiver: () => requireWallet(receiver, 'receiver'),
+        getNetworkId: () => networkId,
+    };
+}
+/**
+ * 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 function registerTokenTransferHealthchecks(deps) {
+    describe('Token transfer', () => {
+        const { getSender, getReceiver, getNetworkId } = useTokenTransferWallets(deps);
+        const shieldedTokenRaw = ledger.shieldedToken().raw;
+        const unshieldedTokenRaw = ledger.unshieldedToken().raw;
+        const outputValue = tNightAmount(10n);
+        const syncTimeout = deps.syncTimeout ?? 60 * 60 * 1000;
+        test('Is working for valid transfer @healthcheck', async () => {
+            const sender = getSender();
+            const receiver = getReceiver();
+            const networkId = getNetworkId();
+            await Promise.all([sender.wallet.waitForSyncedState(), receiver.wallet.waitForSyncedState()]);
+            const senderInitialState = await firstValueFrom(sender.wallet.state());
+            const initialShieldedBalance = senderInitialState.shielded.balances[shieldedTokenRaw];
+            const initialUnshieldedBalance = senderInitialState.unshielded.balances[unshieldedTokenRaw] ?? 0n;
+            const initialDustBalance = senderInitialState.dust.balance(new Date());
+            logger.info(`Wallet 1: ${initialShieldedBalance} shielded tokens`);
+            logger.info(`Wallet 1: ${initialUnshieldedBalance} unshielded tokens`);
+            logger.info(`Wallet 1 available dust: ${initialDustBalance}`);
+            logger.info(`Wallet 1 shielded address: ${getShieldedAddress(networkId, senderInitialState.shielded.address)}`);
+            logger.info(`Wallet 1 available shielded coins: ${senderInitialState.shielded.availableCoins.length}`);
+            logger.info(inspect(senderInitialState.shielded.availableCoins, { depth: null }));
+            logger.info(`Wallet 1 available unshielded coins: ${senderInitialState.unshielded.availableCoins.length}`);
+            logger.info(inspect(senderInitialState.unshielded.availableCoins, { depth: null }));
+            logger.info(`Wallet 1 unshielded address: ${getUnshieldedAddress(networkId, senderInitialState.unshielded.address)}`);
+            const initialReceiverState = await firstValueFrom(receiver.wallet.state());
+            const initialReceiverShieldedBalance = initialReceiverState.shielded.balances[shieldedTokenRaw] ?? 0n;
+            const initialReceiverUnshieldedBalance = initialReceiverState.unshielded.balances[unshieldedTokenRaw] ?? 0n;
+            logger.info(`Wallet 2: ${initialReceiverShieldedBalance} shielded tokens`);
+            logger.info(`Wallet 2: ${initialReceiverUnshieldedBalance} unshielded tokens`);
+            logger.info(`Wallet 2 unshielded address: ${getUnshieldedAddress(networkId, initialReceiverState.unshielded.address)}`);
+            logger.info(`Wallet 2 shielded address: ${getShieldedAddress(networkId, initialReceiverState.shielded.address)}`);
+            const senderInitialTxHistory = await sender.wallet.getAllFromTxHistory();
+            const receiverInitialTxHistory = await receiver.wallet.getAllFromTxHistory();
+            const outputsToCreate = [
+                {
+                    type: 'shielded',
+                    outputs: [
+                        {
+                            type: shieldedTokenRaw,
+                            amount: outputValue,
+                            receiverAddress: initialReceiverState.shielded.address,
+                        },
+                    ],
+                },
+                {
+                    type: 'unshielded',
+                    outputs: [
+                        {
+                            type: unshieldedTokenRaw,
+                            amount: outputValue,
+                            receiverAddress: initialReceiverState.unshielded.address,
+                        },
+                    ],
+                },
+            ];
+            const txRecipe = await sender.wallet.transferTransaction(outputsToCreate, {
+                shieldedSecretKeys: sender.shieldedSecretKeys,
+                dustSecretKey: sender.dustSecretKey,
+            }, {
+                ttl: new Date(Date.now() + 30 * 60 * 1000),
+            });
+            logger.info('Signing tx...');
+            logger.info(txRecipe);
+            const signedTxRecipe = await sender.wallet.signRecipe(txRecipe, (payload) => sender.unshieldedKeystore.signData(payload));
+            logger.info('Transaction to prove...');
+            logger.info(signedTxRecipe);
+            const finalizedTx = await sender.wallet.finalizeRecipe(signedTxRecipe);
+            logger.info('Submitting transaction...');
+            logger.info(finalizedTx.toString());
+            const txId = await sender.wallet.submitTransaction(finalizedTx);
+            const txHash = finalizedTx.transactionHash();
+            logger.info('txProcessing');
+            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);
+            const senderFinalState = await sender.wallet.waitForSyncedState();
+            const senderFinalShieldedBalance = senderFinalState.shielded.balances[shieldedTokenRaw];
+            const senderFinalUnshieldedBalance = senderFinalState.unshielded.balances[unshieldedTokenRaw];
+            const senderFinalDustBalance = senderFinalState.dust.balance(new Date(3 * 1000));
+            logger.info(`Wallet 1 final available dust: ${senderFinalDustBalance}`);
+            logger.info(`Wallet 1 final available shielded coins: ${senderFinalShieldedBalance}`);
+            logger.info(`Wallet 1 final available unshielded coins: ${senderFinalUnshieldedBalance}`);
+            // assert balance after tx history is fixed
+            expect(senderFinalShieldedBalance).toBe(initialShieldedBalance - outputValue);
+            expect(senderFinalUnshieldedBalance).toBe(initialUnshieldedBalance - outputValue);
+            expect(senderFinalShieldedBalance).toBeLessThan(initialShieldedBalance);
+            expect(senderFinalUnshieldedBalance).toBeLessThan(initialUnshieldedBalance);
+            expect(senderFinalState.shielded.availableCoins.length).toBeLessThanOrEqual(senderInitialState.shielded.availableCoins.length);
+            expect(senderFinalState.dust.pendingCoins.length).toBe(0);
+            expect(senderFinalState.shielded.pendingCoins.length).toBe(0);
+            expect(senderFinalState.shielded.totalCoins.length).toBeLessThanOrEqual(senderInitialState.shielded.totalCoins.length);
+            expect(senderFinalState.unshielded.pendingCoins.length).toBe(0);
+            expect(senderFinalState.unshielded.availableCoins.length).toBeLessThanOrEqual(senderInitialState.unshielded.availableCoins.length);
+            expect(senderFinalState.unshielded.totalCoins.length).toBeLessThanOrEqual(senderInitialState.unshielded.totalCoins.length);
+            // Verify sender unshielded transaction history grew and contains the specific transaction
+            const senderFinalTxHistory = await sender.wallet.getAllFromTxHistory();
+            expect(senderFinalTxHistory.length).toBeGreaterThanOrEqual(senderInitialTxHistory.length + 1);
+            expectSenderShieldedTxHistory(senderTxEntry);
+            expectSenderUnshieldedTxHistory(senderTxEntry);
+            const receiverFinalState = await receiver.wallet.waitForSyncedState();
+            const receiverFinalShieldedBalance = receiverFinalState.shielded.balances[shieldedTokenRaw] ?? 0n;
+            const receiverFinalUnshieldedBalance = receiverFinalState.unshielded.balances[unshieldedTokenRaw] ?? 0n;
+            logger.info(`Wallet 2 final available shielded coins: ${receiverFinalShieldedBalance}`);
+            logger.info(`Wallet 2 final available unshielded coins: ${receiverFinalUnshieldedBalance}`);
+            expect(receiverFinalShieldedBalance).toBe(initialReceiverShieldedBalance + outputValue);
+            expect(receiverFinalUnshieldedBalance).toBe(initialReceiverUnshieldedBalance + outputValue);
+            expect(receiverFinalState.shielded.pendingCoins.length).toBe(0);
+            expect(receiverFinalState.shielded.availableCoins.length).toBeGreaterThanOrEqual(initialReceiverState.shielded.availableCoins.length + 1);
+            expect(receiverFinalState.shielded.totalCoins.length).toBeGreaterThanOrEqual(initialReceiverState.shielded.totalCoins.length + 1);
+            // Verify receiver unshielded transaction history grew and contains the specific transaction
+            const receiverFinalTxHistory = await receiver.wallet.getAllFromTxHistory();
+            expect(receiverFinalTxHistory.length).toBeGreaterThanOrEqual(receiverInitialTxHistory.length + 1);
+            const receiverTxEntry = await waitForTxInHistory(txHash, receiver.wallet, (entry) => entry.shielded !== undefined && entry.unshielded !== undefined);
+            expectReceiverShieldedTxHistory(receiverTxEntry, outputValue);
+            expectReceiverUnshieldedTxHistory(receiverTxEntry, outputValue);
+        }, syncTimeout);
+    });
+}

package/dist/seeds.d.ts

@@ -0,0 +1,3 @@
+export declare const getShieldedSeed: (seed: string) => Uint8Array;
+export declare const getUnshieldedSeed: (seed: string) => Uint8Array<ArrayBufferLike>;
+export declare const getDustSeed: (seed: string) => Uint8Array<ArrayBufferLike>;

package/dist/seeds.js

@@ -0,0 +1,27 @@
+// 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 { HDWallet, Roles } from '@midnightntwrk/wallet-sdk-hd';
+const deriveKey = (seed, role) => {
+    const seedBuffer = Buffer.from(seed, 'hex');
+    const hdWalletResult = HDWallet.fromSeed(seedBuffer);
+    const { hdWallet } = hdWalletResult;
+    const derivationResult = hdWallet.selectAccount(0).selectRole(role).deriveKeyAt(0);
+    if (derivationResult.type === 'keyOutOfBounds') {
+        throw new Error('Key derivation out of bounds');
+    }
+    hdWallet.clear();
+    return derivationResult.key;
+};
+export const getShieldedSeed = (seed) => Buffer.from(deriveKey(seed, Roles.Zswap));
+export const getUnshieldedSeed = (seed) => deriveKey(seed, Roles.NightExternal);
+export const getDustSeed = (seed) => deriveKey(seed, Roles.Dust);

package/dist/state-waiters.d.ts

@@ -0,0 +1,69 @@
+import type * as ledger from '@midnight-ntwrk/ledger-v8';
+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;
+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>;
+export declare const waitForDustBalance: (wallet: WalletFacade, threshold?: bigint) => Promise<import("@midnightntwrk/wallet-sdk-facade").FacadeState>;
+export declare const waitForFinalizedShieldedBalance: (wallet: ShieldedWalletAPI) => Promise<import("@midnightntwrk/wallet-sdk-shielded").ShieldedWalletState<string, ledger.FinalizedTransaction>>;
+export declare const waitForUnshieldedCoinUpdate: (wallet: WalletFacade, initialNumAvailableCoins: number) => Promise<import("@midnightntwrk/wallet-sdk-facade").FacadeState>;
+export declare const waitForStateAfterDustRegistration: (wallet: WalletFacade, finalizedTx: ledger.FinalizedTransaction) => Promise<import("@midnightntwrk/wallet-sdk-facade").FacadeState>;
+export declare const waitForRegisteredTokens: (wallet: WalletFacade) => Promise<import("@midnightntwrk/wallet-sdk-facade").FacadeState>;
+export declare const waitForTxInHistory: (txHash: string, wallet: WalletFacade, ready?: (entry: WalletEntry) => boolean) => Promise<{
+    readonly hash: string;
+    readonly protocolVersion: number;
+    readonly status: "SUCCESS" | "FAILURE" | "PARTIAL_SUCCESS";
+    readonly identifiers?: readonly string[] | undefined;
+    readonly timestamp?: Date | undefined;
+    readonly fees?: bigint | null | undefined;
+    readonly shielded?: {
+        readonly receivedCoins: readonly {
+            readonly type: string;
+            readonly nonce: string;
+            readonly value: bigint;
+            readonly mtIndex: bigint;
+        }[];
+        readonly spentCoins: readonly {
+            readonly type: string;
+            readonly nonce: string;
+            readonly value: bigint;
+            readonly mtIndex: bigint;
+        }[];
+    } | undefined;
+    readonly unshielded?: {
+        readonly id: number;
+        readonly createdUtxos: readonly {
+            readonly value: bigint;
+            readonly owner: string;
+            readonly tokenType: string;
+            readonly intentHash: string;
+            readonly outputIndex: number;
+        }[];
+        readonly spentUtxos: readonly {
+            readonly value: bigint;
+            readonly owner: string;
+            readonly tokenType: string;
+            readonly intentHash: string;
+            readonly outputIndex: number;
+        }[];
+    } | undefined;
+    readonly dust?: {
+        readonly spentUtxos: readonly {
+            readonly nonce: bigint;
+            readonly mtIndex: bigint;
+            readonly initialValue: bigint;
+            readonly seq: number;
+            readonly backingNight: string;
+        }[];
+        readonly receivedUtxos: readonly {
+            readonly nonce: bigint;
+            readonly mtIndex: bigint;
+            readonly initialValue: bigint;
+            readonly seq: number;
+            readonly backingNight: string;
+        }[];
+    } | undefined;
+}>;

package/dist/state-waiters.js

@@ -0,0 +1,100 @@
+// 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.
+/* eslint-disable @typescript-eslint/explicit-module-boundary-types */
+import * as rx from 'rxjs';
+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;
+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`);
+}), rx.filter((state) => state.state.progress.isStrictlyComplete())));
+export const waitForFacadePending = (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...`);
+    const unshieldedPending = state.unshielded.pendingCoins.length;
+    logger.info(`Unshielded wallet pending coins: ${unshieldedPending}, waiting for pending coins...`);
+}), rx.filter((state) => state.shielded.pendingCoins.length > 0 || state.unshielded.pendingCoins.length > 0)));
+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 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...`);
+}), 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}...`);
+}), rx.debounceTime(10_000), rx.filter((s) => s.isSynced), rx.filter((s) => s.unshielded.availableCoins.length > initialNumAvailableCoins)));
+export const waitForStateAfterDustRegistration = (wallet, finalizedTx) => rx.firstValueFrom(wallet.state().pipe(rx.mergeMap(async (state) => {
+    const txInHistory = await wallet.queryTxHistoryByHash(finalizedTx.transactionHash());
+    return {
+        state,
+        txFound: txInHistory !== undefined,
+    };
+}), rx.filter(({ state, txFound }) => txFound && state.isSynced && state.dust.availableCoins.length > 0), rx.map(({ state }) => state)));
+export const waitForRegisteredTokens = (wallet) => rx.firstValueFrom(wallet.state().pipe(rx.tap((s) => {
+    const registeredTokens = s.unshielded.availableCoins.filter((coin) => coin.meta.registeredForDustGeneration === true);
+    logger.info(`registered tokens: ${registeredTokens.length}`);
+}), rx.filter((s) => s.unshielded.availableCoins.filter((coin) => coin.meta.registeredForDustGeneration === true).length > 0)));
+export const waitForTxInHistory = async (txHash, wallet, ready) => {
+    const isReady = ready ?? (() => true);
+    const describeSections = (e) => ['shielded', 'unshielded', 'dust'].filter((k) => e[k] !== undefined).join(',');
+    let pollsSinceDump = 0;
+    const txEntry = await rx.firstValueFrom(rx.merge(wallet.state().pipe(rx.filter((state) => state.isSynced)), rx.interval(500)).pipe(rx.mergeMap(async () => {
+        const entry = await wallet.queryTxHistoryByHash(txHash);
+        if (entry !== undefined && entry.status !== 'SUCCESS') {
+            logger.info(`Waiting for tx ${txHash} in history: found, status=${entry.status}, sections=[${describeSections(entry)}] — non-SUCCESS, aborting wait`);
+            return entry;
+        }
+        const notReady = entry === undefined || !isReady(entry);
+        const needsDump = notReady && pollsSinceDump >= 20;
+        if (entry === undefined) {
+            logger.info(`Waiting for tx ${txHash} in history: not found yet`);
+        }
+        else {
+            logger.info(`Waiting for tx ${txHash} in history: found, status=${entry.status}, ready=${isReady(entry)}`);
+        }
+        if (needsDump) {
+            const all = await wallet.getAllFromTxHistory();
+            const summary = all.map((e) => ({
+                hash: e.hash,
+                status: e.status,
+                sections: describeSections(e),
+                identifiers: e.identifiers ?? [],
+            }));
+            logger.info(`Storage snapshot (${all.length} entries): ${JSON.stringify(summary, null, 2)}`);
+            pollsSinceDump = 0;
+        }
+        else {
+            pollsSinceDump = notReady ? pollsSinceDump + 1 : 0;
+        }
+        return entry;
+    }), rx.filter((entry) => entry !== undefined && (entry.status !== 'SUCCESS' || isReady(entry)))));
+    expect(txEntry).toBeDefined();
+    expect(txEntry.hash).toBe(txHash);
+    expect(txEntry.status).toBe('SUCCESS');
+    return txEntry;
+};

package/dist/testcontainers.d.ts

@@ -0,0 +1,18 @@
+import { type MidnightNetwork, type WalletTestEnvironment } from './types.js';
+/** Configuration for {@link createTestContainersEnvironment}. */
+export interface TestContainersEnvironmentConfig {
+    network: MidnightNetwork;
+    /** Environment variables forwarded into the compose environment. Default: `['APP_INFRA_SECRET']`. */
+    passEnv?: readonly string[];
+    /** Startup timeout for the remote-network proof-server, in ms. Default: 100000. */
+    startupTimeoutMs?: number;
+}
+/**
+ * Spins up the local docker-compose stack and returns a {@link WalletTestEnvironment}.
+ *
+ * - `undeployed`: full local stack (proof-server + node + indexer), endpoints resolved from mapped ports.
+ * - Remote networks: a local proof-server only, combined with the public indexer/node preset. This is the case the
+ *   downstream `PROOF_SERVER_URL` patch used to bypass; downstream consumers should instead use
+ *   `createRemoteEnvironment` with an explicit `proverUrl` and skip Docker entirely.
+ */
+export declare const createTestContainersEnvironment: (config: TestContainersEnvironmentConfig) => Promise<WalletTestEnvironment>;

package/dist/testcontainers.js

@@ -0,0 +1,87 @@
+// 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.
+//
+// Docker-backed environment provisioning. Kept behind the `@midnightntwrk/wallet-sdk-testkit/
+// testcontainers` entry point so consumers that only target remote networks never load
+// `testcontainers` or `@midnightntwrk/wallet-sdk-utilities` (both declared as optional peers).
+import { randomUUID } from 'node:crypto';
+import { DockerComposeEnvironment, Wait } from 'testcontainers';
+import { NetworkId } from '@midnightntwrk/wallet-sdk-abstractions';
+import { buildTestEnvironmentVariables, getComposeDirectory } from '@midnightntwrk/wallet-sdk-utilities/testing';
+import { NETWORK_PRESETS, makeEnvironment } from './environment.js';
+import { sleep } from './network.js';
+import { logger } from './logger.js';
+const PROOF_SERVER_PORT = 6300;
+const NODE_PORT_RPC = 9944;
+const INDEXER_PORT = 8088;
+const mappedPort = (env, container, port) => env.getContainer(container).getMappedPort(port);
+const resolveUndeployedEndpoints = (env, uid) => {
+    const indexerPort = mappedPort(env, `indexer_${uid}`, INDEXER_PORT);
+    return {
+        networkId: NetworkId.NetworkId.Undeployed,
+        proverUrl: `http://localhost:${mappedPort(env, `proof-server_${uid}`, PROOF_SERVER_PORT)}`,
+        indexerHttpUrl: `http://localhost:${indexerPort}/api/v3/graphql`,
+        indexerWsUrl: `ws://localhost:${indexerPort}/api/v4/graphql/ws`,
+        nodeUrl: `ws://localhost:${mappedPort(env, `node_${uid}`, NODE_PORT_RPC)}`,
+    };
+};
+/**
+ * Spins up the local docker-compose stack and returns a {@link WalletTestEnvironment}.
+ *
+ * - `undeployed`: full local stack (proof-server + node + indexer), endpoints resolved from mapped ports.
+ * - Remote networks: a local proof-server only, combined with the public indexer/node preset. This is the case the
+ *   downstream `PROOF_SERVER_URL` patch used to bypass; downstream consumers should instead use
+ *   `createRemoteEnvironment` with an explicit `proverUrl` and skip Docker entirely.
+ */
+export const createTestContainersEnvironment = async (config) => {
+    const { network } = config;
+    const passEnv = config.passEnv ?? ['APP_INFRA_SECRET'];
+    const uid = randomUUID();
+    logger.info(`Spinning up ${network} test environment...`);
+    if (network === 'undeployed') {
+        const environmentVars = buildTestEnvironmentVariables(passEnv, { additionalVars: { TESTCONTAINERS_UID: uid } });
+        const composeEnvironment = await new DockerComposeEnvironment(getComposeDirectory(), 'docker-compose-dynamic.yml')
+            .withWaitStrategy(`proof-server_${uid}`, Wait.forListeningPorts())
+            .withWaitStrategy(`node_${uid}`, Wait.forListeningPorts())
+            .withWaitStrategy(`indexer_${uid}`, Wait.forListeningPorts())
+            .withEnvironment(environmentVars)
+            .up();
+        // wait for another block to be produced
+        await sleep(6);
+        logger.info('Test environment started');
+        return makeEnvironment('undeployed', resolveUndeployedEndpoints(composeEnvironment, uid), {
+            down: async () => {
+                await composeEnvironment.down({ timeout: 10_000, removeVolumes: true });
+            },
+        });
+    }
+    const environmentVars = buildTestEnvironmentVariables(passEnv, {
+        additionalVars: { TESTCONTAINERS_UID: uid, NETWORK_ID: network },
+    });
+    const composeEnvironment = await new DockerComposeEnvironment(getComposeDirectory(), 'docker-compose-remote-dynamic.yml')
+        .withWaitStrategy(`proof-server_${uid}`, Wait.forLogMessage('Actix runtime found; starting in Actix runtime'))
+        .withEnvironment(environmentVars)
+        .withStartupTimeout(config.startupTimeoutMs ?? 100_000)
+        .up();
+    logger.info('Test environment started');
+    const preset = NETWORK_PRESETS[network];
+    const endpoints = {
+        ...preset,
+        proverUrl: `http://localhost:${mappedPort(composeEnvironment, `proof-server_${uid}`, PROOF_SERVER_PORT)}`,
+    };
+    return makeEnvironment(network, endpoints, {
+        down: async () => {
+            await composeEnvironment.down({ timeout: 10_000, removeVolumes: true });
+        },
+    });
+};

package/dist/tx-history-asserts.d.ts

@@ -0,0 +1,25 @@
+import { type WalletEntry } from '@midnightntwrk/wallet-sdk-facade';
+export declare function expectValidShieldedCoinFields(coin: NonNullable<WalletEntry['shielded']>['receivedCoins'][number]): void;
+export declare function expectValidShieldedTxHistoryEntry(entry: WalletEntry): void;
+export declare function expectValidUnshieldedTxHistoryEntry(entry: WalletEntry): void;
+/** Asserts a sender's shielded tx history entry has valid spentCoins. */
+export declare function expectSenderShieldedTxHistory(entry: WalletEntry): void;
+/**
+ * Asserts a receiver's shielded tx history entry has valid receivedCoins, and that a coin matching the expected value
+ * exists with valid fields.
+ */
+export declare function expectReceiverShieldedTxHistory(entry: WalletEntry, expectedValue: bigint): void;
+/** Asserts a sender's unshielded tx history entry has valid spentUtxos. */
+export declare function expectSenderUnshieldedTxHistory(entry: WalletEntry): void;
+/**
+ * Asserts a receiver's unshielded tx history entry has valid createdUtxos, and that a UTXO matching the expected value
+ * exists with valid fields.
+ */
+export declare function expectReceiverUnshieldedTxHistory(entry: WalletEntry, expectedValue: bigint): void;
+/**
+ * Asserts that tx history entries from a storage contain at least one entry with the specified section ('shielded' or
+ * 'unshielded').
+ */
+export declare function expectTxHistoryHasSection(storage: {
+    getAll(): Promise<readonly Record<string, unknown>[]>;
+}, section: 'shielded' | 'unshielded'): Promise<readonly Record<string, unknown>[]>;

package/dist/tx-history-asserts.js

@@ -0,0 +1,92 @@
+// 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.
+/* eslint-disable @typescript-eslint/explicit-module-boundary-types */
+import { expect } from 'vitest';
+function expectValidUnshieldedUtxoFields(utxo) {
+    expect(typeof utxo.value).toBe('bigint');
+    expect(typeof utxo.owner).toBe('string');
+    expect(typeof utxo.tokenType).toBe('string');
+    expect(typeof utxo.intentHash).toBe('string');
+    expect(typeof utxo.outputIndex).toBe('number');
+}
+export function expectValidShieldedCoinFields(coin) {
+    expect(typeof coin.type).toBe('string');
+    expect(coin.type.length).toBeGreaterThan(0);
+    expect(typeof coin.nonce).toBe('string');
+    expect(coin.nonce.length).toBeGreaterThan(0);
+    expect(typeof coin.value).toBe('bigint');
+    expect(typeof coin.mtIndex).toBe('bigint');
+}
+export function expectValidShieldedTxHistoryEntry(entry) {
+    expect(entry.shielded).toBeDefined();
+    expect(Array.isArray(entry.shielded.receivedCoins)).toBe(true);
+    expect(Array.isArray(entry.shielded.spentCoins)).toBe(true);
+    for (const coin of [...entry.shielded.receivedCoins, ...entry.shielded.spentCoins]) {
+        expectValidShieldedCoinFields(coin);
+    }
+}
+export function expectValidUnshieldedTxHistoryEntry(entry) {
+    expect(entry.unshielded).toBeDefined();
+    expect(Array.isArray(entry.unshielded.createdUtxos)).toBe(true);
+    expect(Array.isArray(entry.unshielded.spentUtxos)).toBe(true);
+    for (const utxo of [...entry.unshielded.createdUtxos, ...entry.unshielded.spentUtxos]) {
+        expectValidUnshieldedUtxoFields(utxo);
+    }
+}
+/** Asserts a sender's shielded tx history entry has valid spentCoins. */
+export function expectSenderShieldedTxHistory(entry) {
+    expect(entry.shielded).toBeDefined();
+    expect(entry.shielded.spentCoins.length).toBeGreaterThan(0);
+    expectValidShieldedTxHistoryEntry(entry);
+}
+/**
+ * Asserts a receiver's shielded tx history entry has valid receivedCoins, and that a coin matching the expected value
+ * exists with valid fields.
+ */
+export function expectReceiverShieldedTxHistory(entry, expectedValue) {
+    expect(entry.shielded).toBeDefined();
+    expect(entry.shielded.receivedCoins.length).toBeGreaterThan(0);
+    const receivedCoin = entry.shielded.receivedCoins.find((c) => c.value === expectedValue);
+    expect(receivedCoin).toBeDefined();
+    expectValidShieldedCoinFields(receivedCoin);
+    expectValidShieldedTxHistoryEntry(entry);
+}
+/** Asserts a sender's unshielded tx history entry has valid spentUtxos. */
+export function expectSenderUnshieldedTxHistory(entry) {
+    expect(entry.unshielded).toBeDefined();
+    expect(entry.unshielded.spentUtxos.length).toBeGreaterThan(0);
+    expectValidUnshieldedTxHistoryEntry(entry);
+}
+/**
+ * Asserts a receiver's unshielded tx history entry has valid createdUtxos, and that a UTXO matching the expected value
+ * exists with valid fields.
+ */
+export function expectReceiverUnshieldedTxHistory(entry, expectedValue) {
+    expect(entry.unshielded).toBeDefined();
+    expect(entry.unshielded.createdUtxos.length).toBeGreaterThan(0);
+    const receivedUtxo = entry.unshielded.createdUtxos.find((u) => u.value === expectedValue);
+    expect(receivedUtxo).toBeDefined();
+    expectValidUnshieldedUtxoFields(receivedUtxo);
+    expectValidUnshieldedTxHistoryEntry(entry);
+}
+/**
+ * Asserts that tx history entries from a storage contain at least one entry with the specified section ('shielded' or
+ * 'unshielded').
+ */
+export async function expectTxHistoryHasSection(storage, section) {
+    const entries = await storage.getAll();
+    expect(entries.length).toBeGreaterThan(0);
+    const matching = entries.filter((e) => e[section] !== undefined);
+    expect(matching.length).toBeGreaterThan(0);
+    return entries;
+}