@midnight-ntwrk/wallet-sdk-facade 3.0.0 → 4.0.1

package/README.md

@@ -1,5 +1,8 @@
 # @midnight-ntwrk/wallet-sdk-facade
 
+> **Note:** It is recommended to use the [`@midnight-ntwrk/wallet-sdk`](../wallet-sdk/README.md) barrel package, which
+> re-exports this and all other wallet SDK packages through a single dependency.
+
 Unified facade for the Midnight Wallet SDK that combines all wallet types into a single API.
 
 ## Installation
@@ -21,6 +24,11 @@ The Wallet Facade provides a high-level unified interface that aggregates the fu
 
 ## Usage
 
+More detailed and complete examples can be found at [docs snippets](../docs-snippets/src/snippets) (always up-to-date
+with the recent changes) or at the
+[SDK documentation site](https://docs.midnight.network/sdks/official/wallet-developer-guide) (aligned with the recent
+release)
+
 ### Initializing the Facade
 
 ```typescript

package/dist/index.d.ts

@@ -6,9 +6,72 @@ import { type AnyTransaction, type CoinsAndBalances as DustCoinsAndBalances } fr
 import { type DefaultShieldedConfiguration, type ShieldedWalletAPI, type ShieldedWalletState } from '@midnight-ntwrk/wallet-sdk-shielded';
 import type { DefaultUnshieldedConfiguration, UnshieldedWalletAPI } from '@midnight-ntwrk/wallet-sdk-unshielded-wallet';
 import { type UnshieldedWalletState } from '@midnight-ntwrk/wallet-sdk-unshielded-wallet';
+import { Schema } from 'effect';
+import { TransactionHistoryStorage } from '@midnight-ntwrk/wallet-sdk-abstractions';
 import { type Observable } from 'rxjs';
-import { DefaultPendingTransactionsServiceConfiguration, PendingTransactions, PendingTransactionsService } from '@midnight-ntwrk/wallet-sdk-capabilities';
-import { DustAddress, ShieldedAddress, UnshieldedAddress } from '@midnight-ntwrk/wallet-sdk-address-format';
+import { type DefaultPendingTransactionsServiceConfiguration, PendingTransactions, type PendingTransactionsService } from '@midnight-ntwrk/wallet-sdk-capabilities';
+import { type DustAddress, type ShieldedAddress, type UnshieldedAddress } from '@midnight-ntwrk/wallet-sdk-address-format';
+/**
+ * Full entry schema for transaction history — common fields + all wallet sections. Pass this to
+ * `InMemoryTransactionHistoryStorage` to enable serialize/restore.
+ */
+export declare const WalletEntrySchema: Schema.Struct<{
+    shielded: Schema.optional<Schema.Struct<{
+        receivedCoins: Schema.Array$<Schema.Struct<{
+            type: typeof Schema.String;
+            nonce: typeof Schema.String;
+            value: typeof Schema.BigInt;
+            mtIndex: typeof Schema.BigInt;
+        }>>;
+        spentCoins: Schema.Array$<Schema.Struct<{
+            type: typeof Schema.String;
+            nonce: typeof Schema.String;
+            value: typeof Schema.BigInt;
+            mtIndex: typeof Schema.BigInt;
+        }>>;
+    }>>;
+    unshielded: Schema.optional<Schema.Struct<{
+        id: typeof Schema.Number;
+        createdUtxos: Schema.Array$<Schema.Struct<{
+            value: Schema.Schema<bigint, string, never>;
+            owner: typeof Schema.String;
+            tokenType: typeof Schema.String;
+            intentHash: typeof Schema.String;
+            outputIndex: typeof Schema.Number;
+        }>>;
+        spentUtxos: Schema.Array$<Schema.Struct<{
+            value: Schema.Schema<bigint, string, never>;
+            owner: typeof Schema.String;
+            tokenType: typeof Schema.String;
+            intentHash: typeof Schema.String;
+            outputIndex: typeof Schema.Number;
+        }>>;
+    }>>;
+    dust: Schema.optional<Schema.Struct<{
+        receivedUtxos: Schema.Array$<Schema.Struct<{
+            initialValue: typeof Schema.BigInt;
+            nonce: typeof Schema.BigInt;
+            seq: typeof Schema.Number;
+            backingNight: typeof Schema.String;
+            mtIndex: typeof Schema.BigInt;
+        }>>;
+        spentUtxos: Schema.Array$<Schema.Struct<{
+            initialValue: typeof Schema.BigInt;
+            nonce: typeof Schema.BigInt;
+            seq: typeof Schema.Number;
+            backingNight: typeof Schema.String;
+            mtIndex: typeof Schema.BigInt;
+        }>>;
+    }>>;
+    hash: typeof Schema.String;
+    protocolVersion: typeof Schema.Number;
+    status: Schema.Literal<["SUCCESS", "FAILURE", "PARTIAL_SUCCESS"]>;
+    identifiers: Schema.optional<Schema.Array$<typeof Schema.String>>;
+    timestamp: Schema.optional<typeof Schema.Date>;
+    fees: Schema.optional<Schema.NullOr<typeof Schema.BigInt>>;
+}>;
+export type WalletEntry = Schema.Schema.Type<typeof WalletEntrySchema>;
+export declare const mergeWalletEntries: (existing: WalletEntry, incoming: WalletEntry) => WalletEntry;
 type TokenKind = 'dust' | 'shielded' | 'unshielded';
 type TokenKindsToBalance = 'all' | TokenKind[];
 declare const TokenKindsToBalance: {
@@ -74,8 +137,17 @@ export declare class FacadeState {
     constructor(shielded: ShieldedWalletState, unshielded: UnshieldedWalletState, dust: DustWalletState, pending: PendingTransactions.PendingTransactions<ledger.FinalizedTransaction>);
 }
 /**
- * The Terms and Conditions returned by the indexer, containing a URL for display
- * and a SHA-256 hash for content verification.
+ * A clock abstraction for obtaining the current time. By default, the facade uses the system clock. For testing with a
+ * simulator, inject a custom clock (e.g., one backed by the simulator's time).
+ */
+export type Clock = {
+    readonly now: () => Date;
+};
+/** Default clock using real system time. */
+export declare const systemClock: Clock;
+/**
+ * The Terms and Conditions returned by the indexer, containing a URL for display and a SHA-256 hash for content
+ * verification.
  */
 export type TermsAndConditions = {
     /** The hex-encoded SHA-256 hash of the Terms and Conditions document. */
@@ -84,9 +156,9 @@ export type TermsAndConditions = {
     url: string;
 };
 /**
- * Minimal configuration required for {@link WalletFacade.fetchTermsAndConditions}.
- * Accepts the shared `indexerClientConnection` sub-object found on all wallet configurations,
- * so callers can pass the full wallet configuration directly without any adaptation.
+ * Minimal configuration required for {@link WalletFacade.fetchTermsAndConditions}. Accepts the shared
+ * `indexerClientConnection` sub-object found on all wallet configurations, so callers can pass the full wallet
+ * configuration directly without any adaptation.
  */
 export type FetchTermsAndConditionsConfiguration = {
     indexerClientConnection: {
@@ -96,8 +168,16 @@ export type FetchTermsAndConditionsConfiguration = {
 };
 export type DefaultConfiguration = DefaultUnshieldedConfiguration & DefaultShieldedConfiguration & DefaultDustConfiguration & DefaultSubmissionConfiguration & DefaultPendingTransactionsServiceConfiguration & Partial<DefaultProvingConfiguration>;
 type MaybePromise<T> = T | Promise<T>;
+/**
+ * Parameters object for {@link WalletFacade.init}. It features configuration and bunch of initializers for the wallets
+ * and services, all of them are in a form of a function that takes the configuration and returns proper implementation,
+ * either synchronously or wrapped in a Promise. Services are optional to provide ({@link WalletFacade.init} will provide
+ * default implementations), but all 3 wallets: shielded, unshielded and Dust one need to be present
+ */
 export type InitParams<TConfig extends DefaultConfiguration> = {
     configuration: TConfig;
+    /** Optional factory for the clock abstraction. Defaults to system clock (`() => new Date()`). */
+    clock?: (config: TConfig) => MaybePromise<Clock>;
     submissionService?: (config: TConfig) => MaybePromise<SubmissionService<ledger.FinalizedTransaction>>;
     pendingTransactionsService?: (config: TConfig) => MaybePromise<PendingTransactionsService<ledger.FinalizedTransaction>>;
     provingService?: (config: TConfig) => MaybePromise<ProvingService<UnboundTransaction>>;
@@ -113,20 +193,40 @@ export declare class WalletFacade {
     /**
      * Fetches the current Terms and Conditions from the network indexer.
      *
-     * This is a static, pre-initialization utility — no wallet instance is required.
-     * Wallet builders should call this before or independently of wallet initialization
-     * to display the current T&C to end users and obtain the hash for content verification.
+     * This is a static, pre-initialization utility — no wallet instance is required. Wallet builders should call this
+     * before or independently of wallet initialization to display the current T&C to end users and obtain the hash for
+     * content verification.
      *
-     * The returned `hash` is the hex-encoded SHA-256 hash of the document at `url`.
-     * Wallet builders are responsible for fetching and rendering the document content
-     * via `url` in whatever manner suits their application.
+     * The returned `hash` is the hex-encoded SHA-256 hash of the document at `url`. Wallet builders are responsible for
+     * fetching and rendering the document content via `url` in whatever manner suits their application.
      *
-     * @param configuration - An object with an `indexerClientConnection.indexerHttpUrl`.
-     *   Any wallet configuration that satisfies {@link FetchTermsAndConditionsConfiguration} can be passed directly.
-     * @returns A promise resolving to the current {@link TermsAndConditions}, or rejecting if
-     *   no Terms and Conditions have been set on the network yet.
+     * @param configuration - An object with an `indexerClientConnection.indexerHttpUrl`. Any wallet configuration that
+     *   satisfies {@link FetchTermsAndConditionsConfiguration} can be passed directly.
+     * @returns A promise resolving to the current {@link TermsAndConditions}, or rejecting if no Terms and Conditions have
+     *   been set on the network yet.
      */
     static fetchTermsAndConditions(configuration: FetchTermsAndConditionsConfiguration): Promise<TermsAndConditions>;
+    /**
+     * Default initialization for {@link WalletFacade}. It is a static method, which takes an object holding configuration
+     * and initialization of necessary components. Specifically - it requires following fields:
+     *
+     * - `configuration` - holding a configuration, which needs to extend {@link DefaultConfiguration} - this way allows to
+     *   convey use-case-specific settings in the same way, as the SDK works by default
+     * - `shielded` - a function taking the configuration and returning shielded wallet (or a promise with such)
+     *   implementing {@link ShieldedWalletAPI}
+     * - `unshielded` - a function taking the configuration and returning unshielded wallet (or a promise with such)
+     *   implementing {@link UnshieldedWalletAPI}
+     * - `dust` - a function taking the configuration and returning Dust wallet (or a promise with such) implementing
+     *   {@link DustWalletAPI} There are some optional services/abstractions to provide, too. If not provided - default
+     *   implementations will be used, each of them is initialized by a function taking the configuration and returning
+     *   proper implementation (wrapped in a {@link Promise} or not).
+     * - `submissionService` - needs to implement {@link SubmissionService} for a {@link ledger.FinalizedTransaction} to
+     *   submit transactions to the network, default uses Node RPC connection
+     * - `pendingTransactionsService` - needs to implement {@link PendingTransactionsService} for a
+     *   {@link ledger.FinalizedTransaction} to keep track of pending transactions, default uses in-memory implementation
+     * - `provingService` - needs to implement {@link ProvingService} to prove it, default uses proving server
+     * - `clock` - needs to implement {@link Clock} for getting current time, default uses system clock
+     */
     static init<TConfig extends DefaultConfiguration>(initParams: InitParams<TConfig>): Promise<WalletFacade>;
     readonly shielded: ShieldedWalletAPI;
     readonly unshielded: UnshieldedWalletAPI;
@@ -134,6 +234,13 @@ export declare class WalletFacade {
     readonly submissionService: SubmissionService<ledger.FinalizedTransaction>;
     readonly pendingTransactionsService: PendingTransactionsService<ledger.FinalizedTransaction>;
     readonly provingService: ProvingService<UnboundTransaction>;
+    readonly clock: Clock;
+    /**
+     * Constructor is private on purpose - much of initialization of the facade is potentially asynchronous, and adding
+     * new parameters is a breaking change to the users Use {@link WalletFacade.init} instead
+     *
+     * @private
+     */
     private constructor();
     private defaultTtl;
     private mergeUnprovenTransactions;
@@ -183,8 +290,10 @@ export declare class WalletFacade {
     }): Promise<UnprovenTransactionRecipe>;
     /**
      * Provides estimate of the fee of issuing registration transaction with provided UTxOs
+     *
      * @param nightUtxos - Night UTxOs to use for the registration
-     * @returns And object informing about fee at the moment, as well as estimation of dust generation of the UTxO(s), that would be used for paying the fee. These include data that allows to compute when the fee could be paid
+     * @returns And object informing about fee at the moment, as well as estimation of dust generation of the UTxO(s),
+     *   that would be used for paying the fee. These include data that allows to compute when the fee could be paid
      */
     estimateRegistration(nightUtxos: readonly UtxoWithMeta[]): Promise<{
         fee: bigint;
@@ -203,5 +312,7 @@ export declare class WalletFacade {
     revertTransaction(tx: AnyTransaction): Promise<void>;
     start(shieldedSecretKeys: ledger.ZswapSecretKeys, dustSecretKey: ledger.DustSecretKey): Promise<void>;
     stop(): Promise<void>;
+    queryTxHistoryByHash(hash: TransactionHistoryStorage.TransactionHash): Promise<WalletEntry | undefined>;
+    getAllFromTxHistory(): Promise<WalletEntry[]>;
 }
 export {};

package/dist/index.js

@@ -13,12 +13,40 @@
 import * as ledger from '@midnight-ntwrk/ledger-v8';
 import { makeDefaultSubmissionService, } from '@midnight-ntwrk/wallet-sdk-capabilities';
 import { makeDefaultProvingService, } from '@midnight-ntwrk/wallet-sdk-capabilities/proving';
+import { ShieldedSectionSchema, mergeShieldedSections, } from '@midnight-ntwrk/wallet-sdk-shielded';
+import { UnshieldedSectionSchema } from '@midnight-ntwrk/wallet-sdk-unshielded-wallet';
+import { DustSectionSchema, mergeDustSections } from '@midnight-ntwrk/wallet-sdk-dust-wallet';
 import { FetchTermsAndConditions as FetchTermsAndConditionsQuery } from '@midnight-ntwrk/wallet-sdk-indexer-client';
 import { QueryRunner } from '@midnight-ntwrk/wallet-sdk-indexer-client/effect';
-import { Array as Arr, pipe } from 'effect';
+import { Array as Arr, pipe, Schema } from 'effect';
+import { TransactionHistoryStorage } from '@midnight-ntwrk/wallet-sdk-abstractions';
 import { combineLatest, map, firstValueFrom, concatMap } from 'rxjs';
 import { PendingTransactions, PendingTransactionsServiceImpl, } from '@midnight-ntwrk/wallet-sdk-capabilities';
 import { finalizedTransactionTrait } from './transaction.js';
+/**
+ * Full entry schema for transaction history — common fields + all wallet sections. Pass this to
+ * `InMemoryTransactionHistoryStorage` to enable serialize/restore.
+ */
+export const WalletEntrySchema = Schema.Struct({
+    ...TransactionHistoryStorage.TransactionHistoryCommonSchema.fields,
+    shielded: Schema.optional(ShieldedSectionSchema),
+    unshielded: Schema.optional(UnshieldedSectionSchema),
+    dust: Schema.optional(DustSectionSchema),
+});
+export const mergeWalletEntries = (existing, incoming) => ({
+    ...existing,
+    ...incoming,
+    ...(existing.shielded !== undefined && incoming.shielded !== undefined
+        ? { shielded: mergeShieldedSections(existing.shielded, incoming.shielded) }
+        : {}),
+    ...(existing.unshielded !== undefined && incoming.unshielded !== undefined
+        ? { unshielded: { ...existing.unshielded, ...incoming.unshielded } }
+        : {}),
+    ...(existing.dust !== undefined && incoming.dust !== undefined
+        ? { dust: mergeDustSections(existing.dust, incoming.dust) }
+        : {}),
+});
+const isWalletEntry = Schema.is(WalletEntrySchema);
 const TokenKindsToBalance = new (class {
     allTokenKinds = ['shielded', 'unshielded', 'dust'];
     toFlags = (tokenKinds) => {
@@ -70,6 +98,8 @@ export class FacadeState {
     }
 }
 const DEFAULT_TTL_MS = 60 * 60 * 1000; // 1 hour
+/** Default clock using real system time. */
+export const systemClock = { now: () => new Date() };
 export class WalletFacade {
     static makeDefaultSubmissionService(config) {
         return makeDefaultSubmissionService(config);
@@ -93,18 +123,17 @@ export class WalletFacade {
     /**
      * Fetches the current Terms and Conditions from the network indexer.
      *
-     * This is a static, pre-initialization utility — no wallet instance is required.
-     * Wallet builders should call this before or independently of wallet initialization
-     * to display the current T&C to end users and obtain the hash for content verification.
+     * This is a static, pre-initialization utility — no wallet instance is required. Wallet builders should call this
+     * before or independently of wallet initialization to display the current T&C to end users and obtain the hash for
+     * content verification.
      *
-     * The returned `hash` is the hex-encoded SHA-256 hash of the document at `url`.
-     * Wallet builders are responsible for fetching and rendering the document content
-     * via `url` in whatever manner suits their application.
+     * The returned `hash` is the hex-encoded SHA-256 hash of the document at `url`. Wallet builders are responsible for
+     * fetching and rendering the document content via `url` in whatever manner suits their application.
      *
-     * @param configuration - An object with an `indexerClientConnection.indexerHttpUrl`.
-     *   Any wallet configuration that satisfies {@link FetchTermsAndConditionsConfiguration} can be passed directly.
-     * @returns A promise resolving to the current {@link TermsAndConditions}, or rejecting if
-     *   no Terms and Conditions have been set on the network yet.
+     * @param configuration - An object with an `indexerClientConnection.indexerHttpUrl`. Any wallet configuration that
+     *   satisfies {@link FetchTermsAndConditionsConfiguration} can be passed directly.
+     * @returns A promise resolving to the current {@link TermsAndConditions}, or rejecting if no Terms and Conditions have
+     *   been set on the network yet.
      */
     static async fetchTermsAndConditions(configuration) {
         const result = await QueryRunner.runPromise(FetchTermsAndConditionsQuery, {}, {
@@ -116,6 +145,27 @@ export class WalletFacade {
         }
         return tc;
     }
+    /**
+     * Default initialization for {@link WalletFacade}. It is a static method, which takes an object holding configuration
+     * and initialization of necessary components. Specifically - it requires following fields:
+     *
+     * - `configuration` - holding a configuration, which needs to extend {@link DefaultConfiguration} - this way allows to
+     *   convey use-case-specific settings in the same way, as the SDK works by default
+     * - `shielded` - a function taking the configuration and returning shielded wallet (or a promise with such)
+     *   implementing {@link ShieldedWalletAPI}
+     * - `unshielded` - a function taking the configuration and returning unshielded wallet (or a promise with such)
+     *   implementing {@link UnshieldedWalletAPI}
+     * - `dust` - a function taking the configuration and returning Dust wallet (or a promise with such) implementing
+     *   {@link DustWalletAPI} There are some optional services/abstractions to provide, too. If not provided - default
+     *   implementations will be used, each of them is initialized by a function taking the configuration and returning
+     *   proper implementation (wrapped in a {@link Promise} or not).
+     * - `submissionService` - needs to implement {@link SubmissionService} for a {@link ledger.FinalizedTransaction} to
+     *   submit transactions to the network, default uses Node RPC connection
+     * - `pendingTransactionsService` - needs to implement {@link PendingTransactionsService} for a
+     *   {@link ledger.FinalizedTransaction} to keep track of pending transactions, default uses in-memory implementation
+     * - `provingService` - needs to implement {@link ProvingService} to prove it, default uses proving server
+     * - `clock` - needs to implement {@link Clock} for getting current time, default uses system clock
+     */
     static async init(initParams) {
         const submissionService = await Promise.resolve(initParams.submissionService
             ? initParams.submissionService(initParams.configuration)
@@ -129,7 +179,8 @@ export class WalletFacade {
         const shielded = await Promise.resolve(initParams.shielded(initParams.configuration));
         const unshielded = await Promise.resolve(initParams.unshielded(initParams.configuration));
         const dust = await Promise.resolve(initParams.dust(initParams.configuration));
-        return new WalletFacade(shielded, unshielded, dust, submissionService, pendingTransactionsService, provingService);
+        const clock = await Promise.resolve(initParams.clock ? initParams.clock(initParams.configuration) : systemClock);
+        return new WalletFacade(shielded, unshielded, dust, submissionService, pendingTransactionsService, provingService, initParams.configuration.txHistoryStorage, clock);
     }
     shielded;
     unshielded;
@@ -137,21 +188,31 @@ export class WalletFacade {
     submissionService;
     pendingTransactionsService;
     provingService;
+    #txHistoryStorage;
+    clock;
     #pendingSubscription;
-    constructor(shieldedWallet, unshieldedWallet, dustWallet, submissionService, pendingTransactionsService, provingService) {
+    /**
+     * Constructor is private on purpose - much of initialization of the facade is potentially asynchronous, and adding
+     * new parameters is a breaking change to the users Use {@link WalletFacade.init} instead
+     *
+     * @private
+     */
+    constructor(shieldedWallet, unshieldedWallet, dustWallet, submissionService, pendingTransactionsService, provingService, txHistoryStorage, clock = systemClock) {
         this.shielded = shieldedWallet;
         this.unshielded = unshieldedWallet;
         this.dust = dustWallet;
         this.submissionService = submissionService;
         this.pendingTransactionsService = pendingTransactionsService;
         this.provingService = provingService;
+        this.#txHistoryStorage = txHistoryStorage;
+        this.clock = clock;
         this.#pendingSubscription = this.pendingTransactionsService
             .state()
             .pipe(concatMap((pending) => PendingTransactions.allFailed(pending)), concatMap((item) => this.revert(item.tx)))
             .subscribe();
     }
     defaultTtl() {
-        return new Date(Date.now() + DEFAULT_TTL_MS);
+        return new Date(this.clock.now().getTime() + DEFAULT_TTL_MS);
     }
     mergeUnprovenTransactions(a, b) {
         if (a && b)
@@ -160,18 +221,58 @@ export class WalletFacade {
     }
     async createDustActionTransaction(action, nightUtxos, nightVerifyingKey, signDustRegistration) {
         const ttl = this.defaultTtl();
-        const transaction = await this.dust.createDustGenerationTransaction(undefined, ttl, nightUtxos.map(({ utxo, meta }) => ({
+        const now = this.clock.now();
+        const isRegistration = action.type === 'registration';
+        const dustReceiverAddress = isRegistration ? action.dustReceiverAddress : undefined;
+        // Step 1 — Dust decides which Night UTxO belongs in the guaranteed slot (the one whose dust
+        // generation can pay the fee) and computes the fee-payment allowance.
+        const split = await this.dust.splitNightUtxosForDustRegistration(now, nightUtxos.map(({ utxo, meta }) => ({
             ...utxo,
             ctime: meta.ctime,
             registeredForDustGeneration: meta.registeredForDustGeneration,
-        })), nightVerifyingKey, action.type === 'registration' ? action.dustReceiverAddress : undefined);
-        const intent = transaction.intents?.get(1);
-        if (!intent) {
-            throw Error('Dust generation transaction is missing intent segment 1.');
+        })), isRegistration);
+        const toUnshieldedUtxoWithMeta = (u) => ({
+            utxo: {
+                value: u.utxo.value,
+                type: u.utxo.type,
+                owner: u.utxo.owner,
+                intentHash: u.utxo.intentHash,
+                outputNo: u.utxo.outputNo,
+            },
+            meta: {
+                ctime: u.utxo.ctime,
+                registeredForDustGeneration: u.utxo.registeredForDustGeneration,
+            },
+        });
+        const guaranteedForUnshielded = split.guaranteedUtxos.map(toUnshieldedUtxoWithMeta);
+        const fallibleForUnshielded = split.fallibleUtxos.map(toUnshieldedUtxoWithMeta);
+        // Step 2 — Unshielded books the Night UTxOs (move available -> pending) and builds the intent
+        // with the two offers. After this point, a concurrent build call that wants any of these UTxOs
+        // will fail fast.
+        const txWithOffers = await this.unshielded.rotateUtxos(guaranteedForUnshielded, fallibleForUnshielded, nightVerifyingKey, ttl);
+        // Step 3 — Dust attaches its DustActions onto the intent the unshielded wallet just built.
+        // If this fails we must unbook the UTxOs so the caller can retry.
+        let txWithDustActions;
+        try {
+            txWithDustActions = await this.dust.attachDustRegistration(txWithOffers, now, nightVerifyingKey, dustReceiverAddress, split.feePayment);
+        }
+        catch (error) {
+            await this.unshielded.revertTransaction(txWithOffers);
+            throw error;
+        }
+        // Step 4 — Sign via the standard signRecipe pathway, which now stamps both the unshielded
+        // offers and the dust registration. Signing failures also need to release the booking.
+        try {
+            const signedRecipe = await this.signRecipe({ type: 'UNPROVEN_TRANSACTION', transaction: txWithDustActions }, signDustRegistration);
+            if (signedRecipe.type !== 'UNPROVEN_TRANSACTION') {
+                throw Error('signRecipe returned unexpected recipe type for dust action transaction.');
+            }
+            return signedRecipe.transaction;
+        }
+        catch (error) {
+            await this.unshielded.revertTransaction(txWithOffers);
+            throw error;
         }
-        const signatureData = intent.signatureData(1);
-        const signature = await Promise.resolve(signDustRegistration(signatureData));
-        return await this.dust.addDustGenerationSignature(transaction, signature);
     }
     state() {
         return combineLatest([
@@ -315,15 +416,16 @@ export class WalletFacade {
         switch (recipe.type) {
             case 'FINALIZED_TRANSACTION': {
                 const signedBalancingTx = await this.signUnprovenTransaction(recipe.balancingTransaction, signSegment);
+                const withDustSig = await this.#signDustRegistrationIfPresent(signedBalancingTx, signSegment);
                 return {
                     type: 'FINALIZED_TRANSACTION',
                     originalTransaction: recipe.originalTransaction,
-                    balancingTransaction: signedBalancingTx,
+                    balancingTransaction: withDustSig,
                 };
             }
             case 'UNBOUND_TRANSACTION': {
                 const signedBalancingTx = recipe.balancingTransaction
-                    ? await this.signUnprovenTransaction(recipe.balancingTransaction, signSegment)
+                    ? await this.signUnprovenTransaction(recipe.balancingTransaction, signSegment).then((tx) => this.#signDustRegistrationIfPresent(tx, signSegment))
                     : undefined;
                 const signedBaseTx = await this.signUnboundTransaction(recipe.baseTransaction, signSegment);
                 return {
@@ -334,13 +436,23 @@ export class WalletFacade {
             }
             case 'UNPROVEN_TRANSACTION': {
                 const signedTx = await this.signUnprovenTransaction(recipe.transaction, signSegment);
+                const withDustSig = await this.#signDustRegistrationIfPresent(signedTx, signSegment);
                 return {
                     type: 'UNPROVEN_TRANSACTION',
-                    transaction: signedTx,
+                    transaction: withDustSig,
                 };
             }
         }
     }
+    async #signDustRegistrationIfPresent(tx, signSegment) {
+        const intent = tx.intents?.get(1);
+        const registrations = intent?.dustActions?.registrations ?? [];
+        if (!intent || registrations.length === 0) {
+            return tx;
+        }
+        const signature = signSegment(intent.signatureData(1));
+        return await this.dust.addDustRegistrationSignature(tx, signature);
+    }
     async signUnprovenTransaction(tx, signSegment) {
         return await this.unshielded.signUnprovenTransaction(tx, signSegment);
     }
@@ -397,11 +509,13 @@ export class WalletFacade {
     }
     /**
      * Provides estimate of the fee of issuing registration transaction with provided UTxOs
+     *
      * @param nightUtxos - Night UTxOs to use for the registration
-     * @returns And object informing about fee at the moment, as well as estimation of dust generation of the UTxO(s), that would be used for paying the fee. These include data that allows to compute when the fee could be paid
+     * @returns And object informing about fee at the moment, as well as estimation of dust generation of the UTxO(s),
+     *   that would be used for paying the fee. These include data that allows to compute when the fee could be paid
      */
     async estimateRegistration(nightUtxos) {
-        const now = new Date();
+        const now = this.clock.now();
         const dustState = await this.dust.waitForSyncedState();
         const dustGenerationEstimations = pipe(nightUtxos, Arr.map(({ utxo, meta }) => ({
             ...utxo,
@@ -410,8 +524,23 @@ export class WalletFacade {
         })), (utxosWithMeta) => dustState.estimateDustGeneration(utxosWithMeta, now), (estimatedUtxos) => dustState.capabilities.coinsAndBalances.splitNightUtxos(estimatedUtxos), (split) => split.guaranteed);
         const fakeSigningKey = ledger.sampleSigningKey();
         const fakeVerifyingKey = ledger.signatureVerifyingKey(fakeSigningKey);
-        const fakeRegistrationRecipe = await this.registerNightUtxosForDustGeneration(nightUtxos, fakeVerifyingKey, (payload) => ledger.signData(fakeSigningKey, payload), dustState.address);
-        const finalizedFakeTx = fakeRegistrationRecipe.transaction.mockProve().bind();
+        // Use the legacy dust-only construction path here so estimation does NOT book real UTxOs in the
+        // unshielded wallet state. (The race-fix path in createDustActionTransaction books on purpose;
+        // estimation is meant to be observation-only.)
+        const ttl = this.defaultTtl();
+        const fakeUnsignedTx = await this.dust.createDustGenerationTransaction(undefined, ttl, nightUtxos.map(({ utxo, meta }) => ({
+            ...utxo,
+            ctime: meta.ctime,
+            registeredForDustGeneration: meta.registeredForDustGeneration,
+        })), fakeVerifyingKey, dustState.address);
+        const intent = fakeUnsignedTx.intents?.get(1);
+        if (!intent) {
+            throw Error('Dust generation transaction is missing intent segment 1.');
+        }
+        const signatureData = intent.signatureData(1);
+        const signature = ledger.signData(fakeSigningKey, signatureData);
+        const fakeSignedTx = await this.dust.addDustGenerationSignature(fakeUnsignedTx, signature);
+        const finalizedFakeTx = fakeSignedTx.mockProve().bind();
         const fee = await this.calculateTransactionFee(finalizedFakeTx);
         return {
             fee,
@@ -500,4 +629,12 @@ export class WalletFacade {
             Promise.resolve(this.#pendingSubscription?.unsubscribe()),
         ]);
     }
+    async queryTxHistoryByHash(hash) {
+        const raw = await this.#txHistoryStorage.get(hash);
+        return raw && isWalletEntry(raw) ? raw : undefined;
+    }
+    async getAllFromTxHistory() {
+        const allEntries = await this.#txHistoryStorage.getAll();
+        return [...allEntries];
+    }
 }

package/dist/transaction.d.ts

@@ -1,3 +1,3 @@
-import { PendingTransactions } from '@midnight-ntwrk/wallet-sdk-capabilities';
+import { type PendingTransactions } from '@midnight-ntwrk/wallet-sdk-capabilities';
 import * as ledger from '@midnight-ntwrk/ledger-v8';
 export declare const finalizedTransactionTrait: PendingTransactions.TransactionTrait<ledger.FinalizedTransaction>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midnight-ntwrk/wallet-sdk-facade",
-  "version": "3.0.0",
+  "version": "4.0.1",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -24,19 +24,19 @@
     }
   },
   "dependencies": {
-    "@midnight-ntwrk/ledger-v8": "^8.0.2",
-    "@midnight-ntwrk/wallet-sdk-address-format": "^3.1.0",
-    "@midnight-ntwrk/wallet-sdk-capabilities": "^3.2.0",
-    "@midnight-ntwrk/wallet-sdk-dust-wallet": "^3.0.0",
-    "@midnight-ntwrk/wallet-sdk-indexer-client": "^1.2.0",
-    "@midnight-ntwrk/wallet-sdk-shielded": "^2.1.0",
-    "@midnight-ntwrk/wallet-sdk-unshielded-wallet": "^2.1.0",
+    "@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-dust-wallet": "^4.1.0",
+    "@midnight-ntwrk/wallet-sdk-indexer-client": "^1.2.2",
+    "@midnight-ntwrk/wallet-sdk-shielded": "^3.0.1",
+    "@midnight-ntwrk/wallet-sdk-unshielded-wallet": "^3.1.0",
     "rxjs": "^7.8.2"
   },
   "devDependencies": {
-    "@midnight-ntwrk/wallet-sdk-abstractions": "^2.0.0",
-    "@midnight-ntwrk/wallet-sdk-hd": "^3.0.1",
-    "@midnight-ntwrk/wallet-sdk-utilities": "1.1.0"
+    "@midnight-ntwrk/wallet-sdk-hd": "^3.0.2",
+    "@midnight-ntwrk/wallet-sdk-utilities": "^1.2.0"
   },
   "scripts": {
     "typecheck": "tsc -b ./tsconfig.json --noEmit --force",