@midnight-ntwrk/wallet-sdk-dust-wallet 4.1.0 → 4.2.0

package/README.md

@@ -1,3 +1,10 @@
+> [!IMPORTANT]
+> **This package has moved.** The `@midnight-ntwrk` scope is published only
+> during the migration window and will stop receiving updates. Please migrate to
+> [`@midnightntwrk/wallet-sdk-dust-wallet`](https://www.npmjs.com/package/@midnightntwrk/wallet-sdk-dust-wallet).
+
+---
+
 # @midnight-ntwrk/wallet-sdk-dust-wallet
 
 Manages dust (transaction fees) on the Midnight network.

package/dist/DustWallet.d.ts

@@ -2,6 +2,7 @@ import { type DustParameters, type DustPublicKey, DustSecretKey, type FinalizedT
 import { type ProtocolState, ProtocolVersion, type SyncProgress } from '@midnight-ntwrk/wallet-sdk-abstractions';
 import { type DustAddress } from '@midnight-ntwrk/wallet-sdk-address-format';
 import { type Variant, type VariantBuilder, type WalletLike } from '@midnight-ntwrk/wallet-sdk-runtime/abstractions';
+import { type Clock } from '@midnight-ntwrk/wallet-sdk-utilities';
 import * as rx from 'rxjs';
 import { type Balance, type CoinsAndBalancesCapability, type UtxoWithFullDustDetails } from './v1/CoinsAndBalances.js';
 import { CoreWallet } from './v1/CoreWallet.js';
@@ -57,6 +58,29 @@ export type DustWalletAPI<TStartAux = DustSecretKey, TSerialized = string> = {
     balanceTransactions(secretKey: DustSecretKey, transactions: ReadonlyArray<AnyTransaction>, ttl: Date, currentTime?: Date): Promise<UnprovenTransaction>;
     serializeState(): Promise<TSerialized>;
     waitForSyncedState(allowedGap?: bigint): Promise<DustWalletState<TSerialized>>;
+    /**
+     * Resolves when the dust projected to be generated by the single highest-generation unregistered Night UTxO reaches
+     * `requiredAmount`. The projection is re-evaluated every second so the wait advances even when the dust state stream
+     * is quiet. Tracks the same quantity used as `allow_fee_payment` for the registration (the maximum across the UTxOs,
+     * not their sum, since `splitNightUtxos` puts only one UTxO in the guaranteed slot), so pairing with
+     * `WalletFacade.estimateRegistration` to pick `requiredAmount` guarantees the subsequent
+     * `registerNightUtxosForDustGeneration` will pass its fee-coverage guard.
+     *
+     * @param nightUtxos - UTxOs to project generation for; same set passed to `registerNightUtxosForDustGeneration`.
+     *   Already-registered UTxOs are ignored. Must be non-empty.
+     * @param requiredAmount - Threshold to wait for, as a Dust amount. Resolves immediately if `<= 0n`.
+     * @param clock - Source of current time, read on every tick. Required, and a {@link Clock.Clock} rather than a
+     *   snapshot `Date` like the other methods' `currentTime`: the projection only advances because the time is re-read
+     *   each tick, and callers must inject their own clock so simulator-driven tests respect simulator time.
+     * @param opts.timeoutMs - Deadline, in ms from subscription, for `requiredAmount` to be reached; rejects if it is
+     *   not. Default `300_000`.
+     * @returns A promise that resolves once the projected dust reaches `requiredAmount`.
+     * @throws Error if `nightUtxos` is empty.
+     * @throws TimeoutError if `requiredAmount` is not reached within `opts.timeoutMs`.
+     */
+    waitForGeneratedDust(nightUtxos: ReadonlyArray<UtxoWithMeta>, requiredAmount: bigint, clock: Clock.Clock, opts?: {
+        timeoutMs?: number;
+    }): Promise<void>;
     revertTransaction(transaction: AnyTransaction): Promise<void>;
     getAddress(): Promise<DustAddress>;
     stop(): Promise<void>;

package/dist/DustWallet.js

@@ -158,6 +158,30 @@ export function CustomDustWallet(configuration, builder) {
         waitForSyncedState(allowedGap = 0n) {
             return rx.firstValueFrom(this.state.pipe(rx.filter((state) => state.state.progress.isCompleteWithin(allowedGap))));
         }
+        async waitForGeneratedDust(nightUtxos, requiredAmount, clock, opts) {
+            if (nightUtxos.length === 0) {
+                throw Error('At least one Night UTXO is required.');
+            }
+            if (requiredAmount <= 0n) {
+                return;
+            }
+            const timeoutMs = opts?.timeoutMs ?? 300_000;
+            // Combine the dust state stream with a 1 s tick — the dust state only emits when sync
+            // updates apply, but the generation projection depends on a current-time reading, which
+            // advances continuously. Without a periodic tick the filter would never re-run between
+            // state emissions on a quiet wallet, and the wait would hang.
+            await rx.firstValueFrom(rx.combineLatest([this.state, rx.timer(0, 1000)]).pipe(rx.filter(([dustState]) => {
+                // The registration's allow_fee_payment is capped at the single highest-generation
+                // unregistered Night UTxO (splitNightUtxos puts only 1 UTxO in the guaranteed slot),
+                // so the wait must track that same quantity — summing across UTxOs would resolve
+                // optimistically and the registration would still fail the fee check.
+                const maxGeneratedNow = dustState
+                    .estimateDustGeneration(nightUtxos, clock.now())
+                    .filter((u) => !u.utxo.registeredForDustGeneration)
+                    .reduce((max, u) => (u.dust.generatedNow > max ? u.dust.generatedNow : max), 0n);
+                return maxGeneratedNow >= requiredAmount;
+            }), rx.timeout({ first: timeoutMs })));
+        }
         serializeState() {
             return rx.firstValueFrom(this.state).then((state) => state.serialize());
         }

package/dist/v1/RunningV1Variant.js

@@ -71,7 +71,14 @@ export class RunningV1Variant {
                 message: 'Error while applying sync update',
                 cause: err,
             }),
-        })).pipe(Effect.flatMap(({ changes, protocolVersion }) => pipe(Effect.forEach(changes, (change) => pipe(this.#v1Context.transactionHistoryService.getTransactionDetails(change.source), Effect.flatMap((metadata) => this.#v1Context.transactionHistoryService.put(change, metadata, protocolVersion)), Effect.catchAllCause((cause) => Console.error('Error processing tx history metadata', cause))), { discard: true, concurrency: 'unbounded' }), Effect.forkScoped)), Effect.provideService(Scope.Scope, this.#scope))), Stream.tapError((error) => Console.error(error)), Stream.retry(pipe(Schedule.exponential(Duration.seconds(1), 2), Schedule.map((delay) => {
+        })).pipe(Effect.flatMap(({ changes, protocolVersion }) => 
+        // Skip the tx-history fork entirely when there are no changes.
+        // Forking unconditionally allocates a fiber per apply call (one
+        // for every batch the sync emits, even the all-progress ones),
+        // which adds up fast during catch-up.
+        changes.length === 0
+            ? Effect.void
+            : pipe(Effect.forEach(changes, (change) => pipe(this.#v1Context.transactionHistoryService.getTransactionDetails(change.source), Effect.flatMap((metadata) => this.#v1Context.transactionHistoryService.put(change, metadata, protocolVersion)), Effect.catchAllCause((cause) => Console.error('Error processing tx history metadata', cause))), { discard: true, concurrency: 'unbounded' }), Effect.forkScoped)), Effect.provideService(Scope.Scope, this.#scope))), Stream.tapError((error) => Console.error(error)), Stream.retry(pipe(Schedule.exponential(Duration.seconds(1), 2), Schedule.map((delay) => {
             const maxDelay = Duration.minutes(2);
             const jitter = Duration.millis(Math.floor(Math.random() * 1000));
             const delayWithJitter = Duration.toMillis(delay) + Duration.toMillis(jitter);

package/dist/v1/Sync.d.ts

@@ -26,6 +26,10 @@ export type IndexerClientConnection = {
     indexerHttpUrl: string;
     indexerWsUrl?: string;
     keepAlive?: number;
+    /** Cap on the in-flight event queue between the WebSocket push and the apply loop. Default: 10000. */
+    bufferSize?: number;
+    /** In-flight count at which the disposed WS subscription is reopened. Default: 100. */
+    resumeThreshold?: number;
 };
 export type BatchUpdatesConfig = {
     /**

package/dist/v1/Sync.js

@@ -33,19 +33,13 @@ const LedgerEventSchema = Schema.declare((input) => input instanceof LedgerEvent
     identifier: 'ledger.Event',
 });
 const LedgerEventFromUInt8Array = Schema.asSchema(Schema.transformOrFail(Uint8ArraySchema, LedgerEventSchema, {
-    encode: (e) => {
-        return Effect.try({
-            try: () => e.serialize(),
-            catch: (err) => {
-                return new ParseResult.Unexpected(err, 'Could not serialize Ledger Event');
-            },
-        });
-    },
+    encode: (e) => Effect.try({
+        try: () => e.serialize(),
+        catch: (err) => new ParseResult.Unexpected(err, 'Could not serialize Ledger Event'),
+    }),
     decode: (bytes) => Effect.try({
         try: () => LedgerEvent.deserialize(bytes),
-        catch: (err) => {
-            return new ParseResult.Unexpected(err, 'Could not deserialize Ledger Event');
-        },
+        catch: (err) => new ParseResult.Unexpected(err, 'Could not deserialize Ledger Event'),
     }),
 }));
 const HexedEvent = pipe(Schema.Uint8ArrayFromHex, Schema.compose(LedgerEventFromUInt8Array));
@@ -110,8 +104,32 @@ export const makeIndexerSyncService = (config) => {
         },
         subscribeWallet(state) {
             const { appliedIndex } = state.progress;
-            return pipe(DustLedgerEvents.run({
-                id: Number(appliedIndex),
+            const bufferSize = config.indexerClientConnection.bufferSize ?? 10000;
+            const resumeThreshold = config.indexerClientConnection.resumeThreshold ?? 100;
+            // The boundary is load-bearing, not waste: this subscription emits only events (no tip/progress
+            // sentinel), and `isConnected`/the tip (`maxId`) are set only when an event is received. So the
+            // cursor must stay `<= appliedIndex` — never `appliedIndex + 1`. Requesting one event later would
+            // deliver nothing to a wallet already at the tip, so `applyUpdate` would never run and sync would
+            // hang.
+            //
+            // A fresh wallet has `appliedIndex === 0n` (the "nothing applied yet" sentinel), so `resumeFrom`
+            // is `-1n` and the `variables` mapping below opens the subscription with no `id` — the indexer
+            // streams from the very start. A restored wallet has `appliedIndex >= 1`, so `resumeFrom` is
+            // `appliedIndex - 1` and the inclusive cursor re-delivers the boundary event.
+            const resumeFrom = appliedIndex - 1n;
+            return pipe(
+            // Backpressure caps the in-flight queue between the WS push and the
+            // apply loop. Without it the JS heap grows linearly with catch-up
+            // depth, since `Stream.asyncPush({ bufferSize: 'unbounded' })`
+            // buffers every event the indexer pushes regardless of apply rate.
+            DustLedgerEvents.runWithBackpressure({
+                bufferSize,
+                resumeThreshold,
+                from: resumeFrom,
+                // `resumeFrom < 0n` means a fresh wallet: send no `id` so the indexer streams from the very
+                // start, rather than relying on `id: 0` sorting below the first real event id.
+                variables: (cursor) => ({ id: cursor < 0n ? null : Number(cursor) }),
+                key: (r) => BigInt(r.dustLedgerEvents.id),
             }), Stream.mapEffect((subscription) => pipe(Schema.decodeUnknownEither(SyncEventsUpdateSchema)(subscription.dustLedgerEvents), Either.mapLeft((err) => new SyncWalletError(err)), EitherOps.toEffect)), Stream.mapError((error) => new SyncWalletError(error)));
         },
     };
@@ -124,21 +142,14 @@ export const makeDefaultSyncCapability = () => {
             if (updates.length === 0) {
                 return [state, { changes: [], protocolVersion: Number(state.protocolVersion) }];
             }
-            const lastUpdate = updates.at(-1);
-            const nextIndex = BigInt(lastUpdate.id);
-            const highestRelevantWalletIndex = BigInt(lastUpdate.maxId);
-            // in case the nextIndex is less than or equal to the current appliedIndex
-            // just update highestRelevantWalletIndex
-            if (nextIndex <= state.progress.appliedIndex) {
-                return [
-                    CoreWallet.updateProgress(state, { highestRelevantWalletIndex, isConnected: true }),
-                    { changes: [], protocolVersion: Number(state.protocolVersion) },
-                ];
-            }
-            const events = updates.map((u) => u.raw).filter((event) => event !== null);
-            const [newState, changes] = CoreWallet.applyEventsWithChanges(state, secretKey, events, wrappedUpdate.timestamp);
+            const appliedIndex = state.progress.appliedIndex;
+            const freshUpdates = updates.filter((u) => BigInt(u.id) > appliedIndex);
+            const highestRelevantWalletIndex = BigInt(updates.at(-1).maxId);
+            const [newState, changes] = freshUpdates.length === 0
+                ? [state, []]
+                : CoreWallet.applyEventsWithChanges(state, secretKey, freshUpdates.map((u) => u.raw), wrappedUpdate.timestamp);
             const updatedState = CoreWallet.updateProgress(newState, {
-                appliedIndex: nextIndex,
+                appliedIndex: freshUpdates.length === 0 ? appliedIndex : BigInt(freshUpdates.at(-1).id),
                 highestRelevantWalletIndex,
                 isConnected: true,
             });

package/dist/v1/index.d.ts

@@ -9,3 +9,4 @@ export * from './V1Builder.js';
 export * from './types/index.js';
 export * as CoinsAndBalances from './CoinsAndBalances.js';
 export * as TransactionHistory from './TransactionHistory.js';
+export * as WalletError from './WalletError.js';

package/dist/v1/index.js

@@ -21,3 +21,4 @@ export * from './V1Builder.js';
 export * from './types/index.js';
 export * as CoinsAndBalances from './CoinsAndBalances.js';
 export * as TransactionHistory from './TransactionHistory.js';
+export * as WalletError from './WalletError.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midnight-ntwrk/wallet-sdk-dust-wallet",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -8,14 +8,16 @@
   "author": "Midnight Foundation",
   "license": "Apache-2.0",
   "publishConfig": {
-    "registry": "https://npm.pkg.github.com/"
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
   },
   "files": [
     "dist/"
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/midnight-ntwrk/artifacts.git"
+    "url": "git+https://github.com/midnightntwrk/midnight-wallet.git",
+    "directory": "packages/dust-wallet"
   },
   "exports": {
     ".": {
@@ -32,8 +34,8 @@
     "@midnight-ntwrk/wallet-sdk-abstractions": "^2.1.0",
     "@midnight-ntwrk/wallet-sdk-address-format": "^3.1.2",
     "@midnight-ntwrk/wallet-sdk-capabilities": "^3.3.1",
-    "@midnight-ntwrk/wallet-sdk-indexer-client": "^1.2.2",
-    "@midnight-ntwrk/wallet-sdk-runtime": "^1.0.4",
+    "@midnight-ntwrk/wallet-sdk-indexer-client": "^1.2.3",
+    "@midnight-ntwrk/wallet-sdk-runtime": "^1.0.5",
     "@midnight-ntwrk/wallet-sdk-utilities": "^1.2.0",
     "effect": "^3.19.19",
     "rxjs": "^7.8.2"
@@ -50,6 +52,6 @@
     "publint": "publint --strict"
   },
   "devDependencies": {
-    "@midnight-ntwrk/wallet-sdk-hd": "^3.0.2"
+    "@midnight-ntwrk/wallet-sdk-hd": "^3.0.3"
   }
 }