@midnight-ntwrk/wallet-sdk-facade 3.0.0-rc.0 → 4.0.0

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

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: {
@@ -98,6 +170,8 @@ export type DefaultConfiguration = DefaultUnshieldedConfiguration & DefaultShiel
 type MaybePromise<T> = T | Promise<T>;
 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,18 +187,17 @@ 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>;
     static init<TConfig extends DefaultConfiguration>(initParams: InitParams<TConfig>): Promise<WalletFacade>;
@@ -134,6 +207,7 @@ export declare class WalletFacade {
     readonly submissionService: SubmissionService<ledger.FinalizedTransaction>;
     readonly pendingTransactionsService: PendingTransactionsService<ledger.FinalizedTransaction>;
     readonly provingService: ProvingService<UnboundTransaction>;
+    readonly clock: Clock;
     private constructor();
     private defaultTtl;
     private mergeUnprovenTransactions;
@@ -183,8 +257,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 +279,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, {}, {
@@ -129,7 +158,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 +167,25 @@ export class WalletFacade {
     submissionService;
     pendingTransactionsService;
     provingService;
+    #txHistoryStorage;
+    clock;
     #pendingSubscription;
-    constructor(shieldedWallet, unshieldedWallet, dustWallet, submissionService, pendingTransactionsService, provingService) {
+    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)
@@ -397,11 +431,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,
@@ -500,4 +536,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-rc.0",
+  "version": "4.0.0",
   "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-rc.0",
-    "@midnight-ntwrk/wallet-sdk-capabilities": "^3.2.0-rc.0",
-    "@midnight-ntwrk/wallet-sdk-dust-wallet": "^3.0.0-rc.0",
-    "@midnight-ntwrk/wallet-sdk-indexer-client": "^1.2.0-rc.0",
-    "@midnight-ntwrk/wallet-sdk-shielded": "^2.1.0-rc.0",
-    "@midnight-ntwrk/wallet-sdk-unshielded-wallet": "^2.1.0-rc.0",
+    "@midnight-ntwrk/ledger-v8": "^8.0.3",
+    "@midnight-ntwrk/wallet-sdk-address-format": "^3.1.1",
+    "@midnight-ntwrk/wallet-sdk-capabilities": "^3.3.0",
+    "@midnight-ntwrk/wallet-sdk-dust-wallet": "^4.0.0",
+    "@midnight-ntwrk/wallet-sdk-indexer-client": "^1.2.1",
+    "@midnight-ntwrk/wallet-sdk-shielded": "^3.0.0",
+    "@midnight-ntwrk/wallet-sdk-unshielded-wallet": "^3.0.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-rc.0"
+    "@midnight-ntwrk/wallet-sdk-abstractions": "^2.1.0",
+    "@midnight-ntwrk/wallet-sdk-hd": "^3.0.2",
+    "@midnight-ntwrk/wallet-sdk-utilities": "1.1.1"
   },
   "scripts": {
     "typecheck": "tsc -b ./tsconfig.json --noEmit --force",