@midnight-ntwrk/wallet-sdk-dust-wallet 4.0.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,11 +2,13 @@ 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';
 import { type KeysCapability } from './v1/Keys.js';
 import { type SerializationCapability } from './v1/Serialization.js';
+import { type NightUtxoSplitForDustRegistration } from './v1/Transacting.js';
 import { type DustFullInfo, type UtxoWithMeta } from './v1/types/Dust.js';
 import { type AnyTransaction } from './v1/types/ledger.js';
 import { type BaseV1Configuration, type DefaultV1Configuration, type V1Variant } from './v1/V1Builder.js';
@@ -41,12 +43,44 @@ export type DustWalletAPI<TStartAux = DustSecretKey, TSerialized = string> = {
     readonly state: rx.Observable<DustWalletState<TSerialized>>;
     start(secretKey: TStartAux): Promise<void>;
     createDustGenerationTransaction(currentTime: Date | undefined, ttl: Date, nightUtxos: Array<UtxoWithMeta>, nightVerifyingKey: SignatureVerifyingKey, dustReceiverAddress: DustAddress | undefined): Promise<UnprovenTransaction>;
+    splitNightUtxosForDustRegistration(currentTime: Date, nightUtxos: ReadonlyArray<UtxoWithMeta>, isRegistration: boolean): Promise<NightUtxoSplitForDustRegistration>;
+    attachDustRegistration(transaction: UnprovenTransaction, currentTime: Date, nightVerifyingKey: SignatureVerifyingKey, dustReceiverAddress: DustAddress | undefined, feePayment: bigint): Promise<UnprovenTransaction>;
     addDustGenerationSignature(transaction: UnprovenTransaction, signature: Signature): Promise<UnprovenTransaction>;
+    /**
+     * Attaches a signature to the DustRegistration in segment 1's `dustActions` only. Unlike
+     * {@link addDustGenerationSignature}, this does NOT touch the unshielded offers — those should be signed separately
+     * via the unshielded-wallet signing path. Use this when the caller orchestrates signing across both packages (e.g.
+     * the facade's `signRecipe`).
+     */
+    addDustRegistrationSignature(transaction: UnprovenTransaction, signature: Signature): Promise<UnprovenTransaction>;
     calculateFee(transactions: ReadonlyArray<AnyTransaction>): Promise<bigint>;
     estimateFee(secretKey: DustSecretKey, transactions: ReadonlyArray<AnyTransaction>, ttl?: Date, currentTime?: Date): Promise<bigint>;
     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

@@ -98,6 +98,20 @@ export function CustomDustWallet(configuration, builder) {
             })
                 .pipe(Effect.runPromise);
         }
+        async splitNightUtxosForDustRegistration(currentTime, nightUtxos, isRegistration) {
+            return this.runtime
+                .dispatch({
+                [V1Tag]: (v1) => v1.splitNightUtxosForDustRegistration(currentTime, nightUtxos, isRegistration),
+            })
+                .pipe(Effect.runPromise);
+        }
+        async attachDustRegistration(transaction, currentTime, nightVerifyingKey, dustReceiverAddress, feePayment) {
+            return this.runtime
+                .dispatch({
+                [V1Tag]: (v1) => v1.attachDustRegistration(transaction, currentTime, nightVerifyingKey, dustReceiverAddress, feePayment),
+            })
+                .pipe(Effect.runPromise);
+        }
         addDustGenerationSignature(transaction, signature) {
             return this.runtime
                 .dispatch({
@@ -105,6 +119,13 @@ export function CustomDustWallet(configuration, builder) {
             })
                 .pipe(Effect.runPromise);
         }
+        addDustRegistrationSignature(transaction, signature) {
+            return this.runtime
+                .dispatch({
+                [V1Tag]: (v1) => v1.addDustRegistrationSignature(transaction, signature),
+            })
+                .pipe(Effect.runPromise);
+        }
         calculateFee(transactions) {
             return this.runtime
                 .dispatch({
@@ -137,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/CoinsAndBalances.d.ts

@@ -1,3 +1,4 @@
+import { type CoinRecipe } from '@midnight-ntwrk/wallet-sdk-capabilities';
 import { type CoreWallet } from './CoreWallet.js';
 import { type KeysCapability } from './Keys.js';
 import { type DustGenerationDetails, type DustGenerationInfo, type Dust, type DustFullInfo, type UtxoWithMeta } from './types/Dust.js';
@@ -14,8 +15,8 @@ export type UtxoWithFullDustDetails = Readonly<{
     utxo: UtxoWithMeta;
     dust: DustGenerationDetails;
 }>;
-export type CoinSelection<TInput> = (coins: readonly CoinWithValue<TInput>[]) => CoinWithValue<TInput> | undefined;
-export declare const chooseCoin: <TInput>(coins: readonly CoinWithValue<TInput>[]) => CoinWithValue<TInput> | undefined;
+export type CoinSelection = <TCoin extends CoinRecipe>(coins: readonly TCoin[]) => TCoin | undefined;
+export declare const chooseCoin: CoinSelection;
 export type CoinsAndBalancesCapability<TState> = {
     getWalletBalance(state: TState, time: Date): Balance;
     getAvailableCoins(state: TState, time?: Date): readonly DustFullInfo[];

package/dist/v1/CoinsAndBalances.js

@@ -13,7 +13,10 @@
 import * as ledger from '@midnight-ntwrk/ledger-v8';
 import { DateOps } from '@midnight-ntwrk/wallet-sdk-utilities';
 import { pipe, Array as Arr, Order } from 'effect';
-export const chooseCoin = (coins) => coins.toSorted((a, b) => Number(a.value - b.value)).at(0);
+export const chooseCoin = (coins) => coins
+    .filter((coin) => coin.value > 0n)
+    .toSorted((a, b) => Number(a.value - b.value))
+    .at(0);
 const FAKE_NONCE = '0'.repeat(64);
 export const makeDefaultCoinsAndBalancesCapability = (_config, getContext) => {
     const getWalletBalance = (state, time) => {

package/dist/v1/RunningV1Variant.d.ts

@@ -3,12 +3,12 @@ import { type TransactionHistoryService } from './TransactionHistory.js';
 import { type DustSecretKey, type Signature, type SignatureVerifyingKey, type FinalizedTransaction, type UnprovenTransaction } from '@midnight-ntwrk/ledger-v8';
 import { type WalletError } from './WalletError.js';
 import { type WalletRuntimeError, type Variant, StateChange } from '@midnight-ntwrk/wallet-sdk-runtime/abstractions';
-import { type Dust, type UtxoWithMeta } from './types/Dust.js';
+import { type UtxoWithMeta } from './types/Dust.js';
 import { type KeysCapability } from './Keys.js';
 import { type ChangesResult, type SyncCapability, type SyncService } from './Sync.js';
 import { type SimulatorState } from '@midnight-ntwrk/wallet-sdk-capabilities/simulation';
 import { type CoinsAndBalancesCapability, type CoinSelection } from './CoinsAndBalances.js';
-import { type TransactingCapability } from './Transacting.js';
+import { type NightUtxoSplitForDustRegistration, type TransactingCapability } from './Transacting.js';
 import { type CoreWallet } from './CoreWallet.js';
 import { type SerializationCapability } from './Serialization.js';
 import { type AnyTransaction } from './types/ledger.js';
@@ -21,7 +21,7 @@ export declare namespace RunningV1Variant {
         transactingCapability: TransactingCapability<DustSecretKey, CoreWallet, TTransaction>;
         coinsAndBalancesCapability: CoinsAndBalancesCapability<CoreWallet>;
         keysCapability: KeysCapability<CoreWallet>;
-        coinSelection: CoinSelection<Dust>;
+        coinSelection: CoinSelection;
         transactionHistoryService: TransactionHistoryService;
     };
     type AnyContext = Context<any, any, any, any>;
@@ -36,7 +36,10 @@ export declare class RunningV1Variant<TSerialized, TSyncUpdate, TTransaction, TS
     startSyncInBackground(startAux: TStartAux): Effect.Effect<void>;
     startSync(startAux: TStartAux): Stream.Stream<void, WalletError, Scope.Scope>;
     createDustGenerationTransaction(currentTime: Date | undefined, ttl: Date, nightUtxos: ReadonlyArray<UtxoWithMeta>, nightVerifyingKey: SignatureVerifyingKey, dustReceiverAddress: DustAddress | undefined): Effect.Effect<UnprovenTransaction, WalletError>;
+    splitNightUtxosForDustRegistration(currentTime: Date, nightUtxos: ReadonlyArray<UtxoWithMeta>, isRegistration: boolean): Effect.Effect<NightUtxoSplitForDustRegistration, WalletError>;
+    attachDustRegistration(transaction: UnprovenTransaction, currentTime: Date, nightVerifyingKey: SignatureVerifyingKey, dustReceiverAddress: DustAddress | undefined, feePayment: bigint): Effect.Effect<UnprovenTransaction, WalletError>;
     addDustGenerationSignature(transaction: UnprovenTransaction, signature: Signature): Effect.Effect<UnprovenTransaction, WalletError>;
+    addDustRegistrationSignature(transaction: UnprovenTransaction, signature: Signature): Effect.Effect<UnprovenTransaction, WalletError>;
     calculateFee(transactions: ReadonlyArray<AnyTransaction>): Effect.Effect<bigint, WalletError>;
     estimateFee(secretKey: DustSecretKey, transactions: ReadonlyArray<AnyTransaction>, ttl: Date, currentTime?: Date): Effect.Effect<bigint, WalletError>;
     balanceTransactions(secretKey: DustSecretKey, transactions: ReadonlyArray<AnyTransaction>, ttl: Date, currentTime?: Date): Effect.Effect<UnprovenTransaction, WalletError>;

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);
@@ -82,19 +89,41 @@ export class RunningV1Variant {
         if (nightUtxos.some((utxo) => utxo.type !== nativeToken().raw)) {
             return Effect.fail(new OtherWalletError({ message: 'Token of a non-Night type received' }));
         }
-        return Effect.Do.pipe(Effect.bind('currentState', () => SubscriptionRef.get(this.#context.stateRef)), Effect.bind('blockData', () => this.#v1Context.syncService.blockData()), Effect.let('currentTime', ({ blockData }) => currentTime ?? blockData.timestamp), Effect.let('utxosWithDustValue', ({ currentState, currentTime }) => {
-            return this.#v1Context.coinsAndBalancesCapability.estimateDustGeneration(currentState, nightUtxos, currentTime);
-        }), Effect.flatMap(({ utxosWithDustValue, currentTime }) => {
-            return this.#v1Context.transactingCapability
-                .createDustGenerationTransaction(currentTime, ttl, utxosWithDustValue, nightVerifyingKey, dustReceiverAddress)
+        return Effect.gen(this, function* () {
+            const currentState = yield* SubscriptionRef.get(this.#context.stateRef);
+            const blockData = yield* this.#v1Context.syncService.blockData();
+            const resolvedTime = currentTime ?? blockData.timestamp;
+            const utxosWithDustValue = this.#v1Context.coinsAndBalancesCapability.estimateDustGeneration(currentState, nightUtxos, resolvedTime);
+            return yield* this.#v1Context.transactingCapability
+                .createDustGenerationTransaction(resolvedTime, ttl, utxosWithDustValue, nightVerifyingKey, dustReceiverAddress)
                 .pipe(EitherOps.toEffect);
-        }));
+        });
+    }
+    splitNightUtxosForDustRegistration(currentTime, nightUtxos, isRegistration) {
+        if (nightUtxos.some((utxo) => utxo.type !== nativeToken().raw)) {
+            return Effect.fail(new OtherWalletError({ message: 'Token of a non-Night type received' }));
+        }
+        return Effect.gen(this, function* () {
+            const currentState = yield* SubscriptionRef.get(this.#context.stateRef);
+            const utxosWithDustValue = this.#v1Context.coinsAndBalancesCapability.estimateDustGeneration(currentState, nightUtxos, currentTime);
+            return this.#v1Context.transactingCapability.splitNightUtxosForDustRegistration(utxosWithDustValue, isRegistration);
+        });
+    }
+    attachDustRegistration(transaction, currentTime, nightVerifyingKey, dustReceiverAddress, feePayment) {
+        return this.#v1Context.transactingCapability
+            .attachDustRegistration(transaction, currentTime, nightVerifyingKey, dustReceiverAddress, feePayment)
+            .pipe(EitherOps.toEffect);
     }
     addDustGenerationSignature(transaction, signature) {
         return this.#v1Context.transactingCapability
             .addDustGenerationSignature(transaction, signature)
             .pipe(EitherOps.toEffect);
     }
+    addDustRegistrationSignature(transaction, signature) {
+        return this.#v1Context.transactingCapability
+            .addDustRegistrationSignature(transaction, signature)
+            .pipe(EitherOps.toEffect);
+    }
     calculateFee(transactions) {
         return pipe(this.#v1Context.syncService.blockData(), Effect.map((blockData) => pipe(transactions, Arr.map((transaction) => this.#v1Context.transactingCapability.calculateFee(transaction, blockData.ledgerParameters)), ArrayOps.sumBigInt)));
     }

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/Transacting.d.ts

@@ -6,11 +6,45 @@ import { CoreWallet } from './CoreWallet.js';
 import { type AnyTransaction, type Dust, type NetworkId, type TotalCostParameters } from './types/index.js';
 import { type CoinsAndBalancesCapability, type CoinSelection, type CoinWithValue, type UtxoWithFullDustDetails } from './CoinsAndBalances.js';
 import { type KeysCapability } from './Keys.js';
+/**
+ * Result of splitting Night UTxOs into the guaranteed/fallible sections of a Dust registration or deregistration
+ * intent, together with the fee-payment allowance the registration may claim from dust generated by the guaranteed
+ * UTxO.
+ *
+ * For deregistration, `feePayment` is always `0n`.
+ */
+export type NightUtxoSplitForDustRegistration = {
+    readonly guaranteedUtxos: ReadonlyArray<UtxoWithFullDustDetails>;
+    readonly fallibleUtxos: ReadonlyArray<UtxoWithFullDustDetails>;
+    readonly feePayment: bigint;
+};
 export interface TransactingCapability<TSecrets, TState, _TTransaction> {
     readonly networkId: NetworkId;
     readonly costParams: TotalCostParameters;
     createDustGenerationTransaction(currentTime: Date, ttl: Date, nightUtxos: ReadonlyArray<UtxoWithFullDustDetails>, nightVerifyingKey: SignatureVerifyingKey, dustReceiverAddress: DustAddress | undefined): Either.Either<UnprovenTransaction, WalletError>;
+    /**
+     * Decides which Night UTxOs belong in the guaranteed vs fallible section of a dust registration/deregistration
+     * transaction, and computes the fee-payment allowance the registration may claim from dust generated by the
+     * guaranteed UTxO.
+     *
+     * For deregistration (`isRegistration === false`) the fee-payment allowance is always `0n`.
+     */
+    splitNightUtxosForDustRegistration(utxosWithDustValue: ReadonlyArray<UtxoWithFullDustDetails>, isRegistration: boolean): NightUtxoSplitForDustRegistration;
+    /**
+     * Attaches a Dust registration / deregistration action onto the intent (at segment 1) of an unproven transaction
+     * whose offers have already been built (typically by the unshielded wallet's `rotateUtxos`). The Night UTxOs are
+     * assumed to already appear in the intent's guaranteed/fallible offers and to already be booked in the unshielded
+     * wallet state.
+     */
+    attachDustRegistration(transaction: UnprovenTransaction, currentTime: Date, nightVerifyingKey: SignatureVerifyingKey, dustReceiverAddress: DustAddress | undefined, feePayment: bigint): Either.Either<UnprovenTransaction, WalletError>;
     addDustGenerationSignature(transaction: UnprovenTransaction, signature: Signature): Either.Either<UnprovenTransaction, WalletError>;
+    /**
+     * Attaches a signature to the DustRegistration in segment 1's `dustActions` only. Unlike
+     * {@link addDustGenerationSignature}, this does NOT touch the unshielded offers — those are expected to be signed via
+     * the unshielded-wallet signing path. Use this when the caller orchestrates signing across both packages (e.g. the
+     * facade's `signRecipe`).
+     */
+    addDustRegistrationSignature(transaction: UnprovenTransaction, signature: Signature): Either.Either<UnprovenTransaction, WalletError>;
     calculateFee(transaction: AnyTransaction, ledgerParams: LedgerParameters): bigint;
     estimateFee(secretKey: TSecrets, state: TState, transactions: ReadonlyArray<AnyTransaction>, ttl: Date, currentTime: Date, ledgerParams: LedgerParameters): Either.Either<bigint, WalletError>;
     balanceTransactions(secretKey: TSecrets, state: TState, transactions: ReadonlyArray<AnyTransaction>, ttl: Date, currentTime: Date, ledgerParams: LedgerParameters): Either.Either<[UnprovenTransaction, TState], WalletError>;
@@ -21,7 +55,7 @@ export type DefaultTransactingConfiguration = {
     costParameters: TotalCostParameters;
 };
 export type DefaultTransactingContext = {
-    coinSelection: CoinSelection<Dust>;
+    coinSelection: CoinSelection;
     coinsAndBalancesCapability: CoinsAndBalancesCapability<CoreWallet>;
     keysCapability: KeysCapability<CoreWallet>;
 };
@@ -41,11 +75,14 @@ export declare const findAvailableSegmentId: (transaction: AnyTransaction) => Op
 export declare class TransactingCapabilityImplementation<TTransaction extends AnyTransaction> implements TransactingCapability<DustSecretKey, CoreWallet, TTransaction> {
     readonly networkId: string;
     readonly costParams: TotalCostParameters;
-    readonly getCoinSelection: () => CoinSelection<Dust>;
+    readonly getCoinSelection: () => CoinSelection;
     readonly getCoins: () => CoinsAndBalancesCapability<CoreWallet>;
     readonly getKeys: () => KeysCapability<CoreWallet>;
-    constructor(networkId: NetworkId, costParams: TotalCostParameters, getCoinSelection: () => CoinSelection<Dust>, getCoins: () => CoinsAndBalancesCapability<CoreWallet>, getKeys: () => KeysCapability<CoreWallet>);
+    constructor(networkId: NetworkId, costParams: TotalCostParameters, getCoinSelection: () => CoinSelection, getCoins: () => CoinsAndBalancesCapability<CoreWallet>, getKeys: () => KeysCapability<CoreWallet>);
     createDustGenerationTransaction(currentTime: Date, ttl: Date, nightUtxos: ReadonlyArray<UtxoWithFullDustDetails>, nightVerifyingKey: SignatureVerifyingKey, dustReceiverAddress: DustAddress | undefined): Either.Either<UnprovenTransaction, WalletError>;
+    splitNightUtxosForDustRegistration(utxosWithDustValue: ReadonlyArray<UtxoWithFullDustDetails>, isRegistration: boolean): NightUtxoSplitForDustRegistration;
+    attachDustRegistration(transaction: UnprovenTransaction, currentTime: Date, nightVerifyingKey: SignatureVerifyingKey, dustReceiverAddress: DustAddress | undefined, feePayment: bigint): Either.Either<UnprovenTransaction, WalletError>;
+    addDustRegistrationSignature(transaction: UnprovenTransaction, signatureData: Signature): Either.Either<UnprovenTransaction, WalletError>;
     addDustGenerationSignature(transaction: UnprovenTransaction, signatureData: Signature): Either.Either<UnprovenTransaction, WalletError>;
     calculateFee(transaction: AnyTransaction, ledgerParams: LedgerParameters): bigint;
     dryRunFee(recipeInputs: ReadonlyArray<CoinWithValue<Dust>>, transactions: ReadonlyArray<FinalizedTransaction | UnprovenTransaction>, secretKey: DustSecretKey, state: CoreWallet, ttl: Date, currentTime: Date, ledgerParams: LedgerParameters): bigint;

package/dist/v1/Transacting.js

@@ -108,6 +108,72 @@ export class TransactingCapabilityImplementation {
             });
         });
     }
+    splitNightUtxosForDustRegistration(utxosWithDustValue, isRegistration) {
+        const splitResult = this.getCoins().splitNightUtxos(utxosWithDustValue);
+        // Deregistration must not claim dust as fee payment (matches the historical
+        // `dustReceiverAddress === undefined` branch of createDustGenerationTransaction).
+        const feePayment = isRegistration
+            ? pipe(splitResult.guaranteed, IterableOps.filter((coin) => !coin.utxo.registeredForDustGeneration), IterableOps.map((coin) => coin.dust.generatedNow), BigIntOps.sumAll)
+            : 0n;
+        return {
+            guaranteedUtxos: splitResult.guaranteed,
+            fallibleUtxos: splitResult.fallible,
+            feePayment,
+        };
+    }
+    attachDustRegistration(transaction, currentTime, nightVerifyingKey, dustReceiverAddress, feePayment) {
+        return Either.gen(this, function* () {
+            const intent = transaction.intents?.get(1);
+            if (!intent) {
+                return yield* Either.left(new TransactingError({
+                    message: 'No intent found at segment 1; expected an intent built by rotateUtxos',
+                }));
+            }
+            if (intent.dustActions !== undefined && intent.dustActions.registrations.length > 0) {
+                return yield* Either.left(new TransactingError({ message: 'Intent at segment 1 already has a dust registration attached' }));
+            }
+            return yield* LedgerOps.ledgerTry(() => {
+                const receiver = dustReceiverAddress ? dustReceiverAddress.data : undefined;
+                const dustRegistration = new DustRegistration(SignatureMarker.signature, nightVerifyingKey, receiver, feePayment);
+                const dustActions = new DustActions(SignatureMarker.signature, ProofMarker.preProof, currentTime, [], [dustRegistration]);
+                // Intents fetched from `transaction.intents.get(...)` behave like value copies — assigning
+                // to a field doesn't propagate back. Match the addDustGenerationSignature pattern: copy the
+                // intent via serialize/deserialize, mutate the copy, then set it back into a fresh
+                // transaction's intents map.
+                const newIntent = Intent.deserialize(SignatureMarker.signature, ProofMarker.preProof, BindingMarker.preBinding, intent.serialize());
+                newIntent.dustActions = dustActions;
+                const newTransaction = Transaction.deserialize(SignatureMarker.signature, ProofMarker.preProof, BindingMarker.preBinding, transaction.serialize());
+                newTransaction.intents = newTransaction.intents.set(1, newIntent);
+                return newTransaction;
+            });
+        });
+    }
+    addDustRegistrationSignature(transaction, signatureData) {
+        return Either.gen(this, function* () {
+            const intent = transaction.intents?.get(1);
+            if (!intent) {
+                return yield* Either.left(new TransactingError({ message: 'No intent found in the transaction intents with segment = 1' }));
+            }
+            const { dustActions } = intent;
+            if (!dustActions) {
+                return yield* Either.left(new TransactingError({ message: 'No dustActions found in intent' }));
+            }
+            const [registration, ...restRegistrations] = dustActions.registrations;
+            if (!registration) {
+                return yield* Either.left(new TransactingError({ message: 'No registrations found in dustActions' }));
+            }
+            return yield* LedgerOps.ledgerTry(() => {
+                const signature = new SignatureEnabled(signatureData);
+                const registrationWithSignature = new DustRegistration(signature.instance, registration.nightKey, registration.dustAddress, registration.allowFeePayment, signature);
+                const newDustActions = new DustActions(signature.instance, ProofMarker.preProof, dustActions.ctime, dustActions.spends, [registrationWithSignature, ...restRegistrations]);
+                const newIntent = Intent.deserialize(signature.instance, ProofMarker.preProof, BindingMarker.preBinding, intent.serialize());
+                newIntent.dustActions = newDustActions;
+                const newTransaction = Transaction.deserialize(signature.instance, ProofMarker.preProof, BindingMarker.preBinding, transaction.serialize());
+                newTransaction.intents = newTransaction.intents.set(1, newIntent);
+                return newTransaction;
+            });
+        });
+    }
     addDustGenerationSignature(transaction, signatureData) {
         return Either.gen(this, function* () {
             const intent = transaction.intents?.get(1);
@@ -167,9 +233,7 @@ export class TransactingCapabilityImplementation {
         const [first, ...rest] = transactions.map((tx) => tx.eraseProofs());
         const mergedExisting = first ? rest.reduce((acc, tx) => acc.merge(tx), first) : undefined;
         const segmentId = mergedExisting ? Option.getOrElse(findAvailableSegmentId(mergedExisting), () => 1) : 1;
-        // @TODO in ledger 8.1.0 will be able to set the segment id when constructing the tx
-        const balancingTx = Transaction.fromParts(network, undefined, undefined, undefined);
-        balancingTx.intents = new Map([[segmentId, intent]]);
+        const balancingTx = Transaction.fromParts(network).addIntent({ tag: 'specific', value: segmentId }, intent);
         const erasedBalancing = balancingTx.eraseProofs();
         const mergedTx = mergedExisting ? mergedExisting.merge(erasedBalancing) : erasedBalancing;
         return this.calculateFee(mergedTx, ledgerParams);
@@ -197,14 +261,15 @@ export class TransactingCapabilityImplementation {
                         })),
                         initialImbalances: CapImbalances.fromEntry('dust', currentFee),
                         feeTokenType: 'dust',
+                        coinSelection: this.getCoinSelection(),
                         transactionCostModel: {
                             inputFeeOverhead: 0n,
                             outputFeeOverhead: 0n,
                         },
                         createOutput: (coin) => coin,
-                        isCoinEqual: (a, b) => a.type === b.type && a.value === b.value,
+                        isCoinEqual: (a, b) => a.token.nonce === b.token.nonce,
                     });
-                    const recipeInputs = recipe.inputs.map((input) => ({ token: input.token, value: input.value }));
+                    const recipeInputs = recipe.inputs.map(({ token, value }) => ({ token, value }));
                     const newFee = this.dryRunFee(recipeInputs, transactions, secretKey, state, ttl, currentTime, ledgerParams);
                     const recipeAmountCoverage = recipeInputs.reduce((sum, input) => sum + input.value, 0n);
                     return { currentFee: newFee, recipeInputs, converged: newFee <= recipeAmountCoverage };
@@ -243,8 +308,7 @@ export class TransactingCapabilityImplementation {
                 const [first, ...rest] = transactions.map((tx) => tx.eraseProofs());
                 const mergedExisting = first ? rest.reduce((acc, tx) => acc.merge(tx), first) : undefined;
                 const segmentId = mergedExisting ? Option.getOrElse(findAvailableSegmentId(mergedExisting), () => 1) : 1;
-                const feeTransaction = Transaction.fromParts(networkId, undefined, undefined, undefined);
-                feeTransaction.intents = new Map([[segmentId, intent]]);
+                const feeTransaction = Transaction.fromParts(networkId).addIntent({ tag: 'specific', value: segmentId }, intent);
                 return [feeTransaction, updatedState];
             });
         }));

package/dist/v1/V1Builder.d.ts

@@ -10,7 +10,6 @@ import { type KeysCapability } from './Keys.js';
 import { type CoinsAndBalancesCapability, type CoinSelection, type DefaultCoinsAndBalancesContext } from './CoinsAndBalances.js';
 import { type DefaultTransactingConfiguration, type DefaultTransactingContext, type TransactingCapability } from './Transacting.js';
 import { type NetworkId } from './types/ledger.js';
-import { type Dust } from './types/Dust.js';
 import { type SerializationCapability } from './Serialization.js';
 import { type TotalCostParameters } from './types/transaction.js';
 export type BaseV1Configuration = {
@@ -43,7 +42,7 @@ export declare class V1Builder<TConfig extends BaseV1Configuration = BaseV1Confi
     withSerialization<TSerializationConfig, TSerializationContext extends Partial<RunningV1Variant.AnyContext>, TSerialized>(serializationCapability: (configuration: TSerializationConfig, getContext: () => TSerializationContext) => SerializationCapability<CoreWallet, null, TSerialized>): V1Builder<TConfig & TSerializationConfig, TContext & TSerializationContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
     withTransactingDefaults(this: V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, FinalizedTransaction, TStartAux>): V1Builder<TConfig & DefaultTransactingConfiguration, TContext & DefaultTransactingContext, TSerialized, TSyncUpdate, FinalizedTransaction, TStartAux>;
     withTransacting<TTransactingConfig, TTransactingContext extends Partial<RunningV1Variant.AnyContext>>(transactingCapability: (config: TTransactingConfig, getContext: () => TTransactingContext) => TransactingCapability<DustSecretKey, CoreWallet, TTransaction>): V1Builder<TConfig & TTransactingConfig, TContext & TTransactingContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
-    withCoinSelection<TCoinSelectionConfig, TCoinSelectionContext extends Partial<RunningV1Variant.AnyContext>>(coinSelection: (config: TCoinSelectionConfig, getContext: () => TCoinSelectionContext) => CoinSelection<Dust>): V1Builder<TConfig & TCoinSelectionConfig, TContext & TCoinSelectionContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
+    withCoinSelection<TCoinSelectionConfig, TCoinSelectionContext extends Partial<RunningV1Variant.AnyContext>>(coinSelection: (config: TCoinSelectionConfig, getContext: () => TCoinSelectionContext) => CoinSelection): V1Builder<TConfig & TCoinSelectionConfig, TContext & TCoinSelectionContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
     withCoinSelectionDefaults(): V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
     withCoinsAndBalancesDefaults(): V1Builder<TConfig, TContext & DefaultCoinsAndBalancesContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
     withCoinsAndBalances<TBalancesConfig, TBalancesContext extends Partial<RunningV1Variant.AnyContext>>(coinsAndBalancesCapability: (configuration: TBalancesConfig, getContext: () => TBalancesContext) => CoinsAndBalancesCapability<CoreWallet>): V1Builder<TConfig & TBalancesConfig, TContext & TBalancesContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
@@ -66,7 +65,7 @@ declare namespace V1Builder {
         readonly serializationCapability: (configuration: TConfig, getContext: () => TContext) => SerializationCapability<CoreWallet, null, TSerialized>;
     };
     type HasCoinSelection<TConfig, TContext> = {
-        readonly coinSelection: (configuration: TConfig, getContext: () => TContext) => CoinSelection<Dust>;
+        readonly coinSelection: (configuration: TConfig, getContext: () => TContext) => CoinSelection;
     };
     type HasCoinsAndBalances<TConfig, TContext> = {
         readonly coinsAndBalancesCapability: (configuration: TConfig, getContext: () => TContext) => CoinsAndBalancesCapability<CoreWallet>;

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.0.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": {
     ".": {
@@ -28,13 +30,13 @@
     }
   },
   "dependencies": {
-    "@midnight-ntwrk/ledger-v8": "^8.0.3",
-    "@midnight-ntwrk/wallet-sdk-abstractions": "2.1.0",
-    "@midnight-ntwrk/wallet-sdk-address-format": "3.1.1",
-    "@midnight-ntwrk/wallet-sdk-capabilities": "3.3.0",
-    "@midnight-ntwrk/wallet-sdk-indexer-client": "1.2.1",
-    "@midnight-ntwrk/wallet-sdk-runtime": "1.0.3",
-    "@midnight-ntwrk/wallet-sdk-utilities": "1.1.1",
+    "@midnight-ntwrk/ledger-v8": "^8.1.0",
+    "@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.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"
   }
 }