@midnight-ntwrk/wallet-sdk-facade 4.0.1 → 4.1.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-facade`](https://www.npmjs.com/package/@midnightntwrk/wallet-sdk-facade).
+
+---
+
 # @midnight-ntwrk/wallet-sdk-facade
 
 > **Note:** It is recommended to use the [`@midnight-ntwrk/wallet-sdk`](../wallet-sdk/README.md) barrel package, which

package/dist/index.d.ts

@@ -6,6 +6,7 @@ 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 { Clock } from '@midnight-ntwrk/wallet-sdk-utilities';
 import { Schema } from 'effect';
 import { TransactionHistoryStorage } from '@midnight-ntwrk/wallet-sdk-abstractions';
 import { type Observable } from 'rxjs';
@@ -137,14 +138,16 @@ export declare class FacadeState {
     constructor(shielded: ShieldedWalletState, unshielded: UnshieldedWalletState, dust: DustWalletState, pending: PendingTransactions.PendingTransactions<ledger.FinalizedTransaction>);
 }
 /**
- * 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).
+ * Clock abstraction for obtaining the current time. By default, the facade uses the system clock
+ * ({@link Clock.systemClock}); for testing with a simulator, inject a custom clock (e.g. one backed by the simulator's
+ * time).
+ *
+ * Re-exported from `@midnight-ntwrk/wallet-sdk-utilities` as a namespace so the type is `Clock.Clock` and the default is
+ * `Clock.systemClock`. Forwarding the same symbol — rather than re-declaring its members individually — keeps the
+ * umbrella `wallet-sdk` package's star-exports unambiguous and lets lower-level packages (e.g. dust-wallet) share it
+ * without a circular dependency.
  */
-export type Clock = {
-    readonly now: () => Date;
-};
-/** Default clock using real system time. */
-export declare const systemClock: Clock;
+export { Clock };
 /**
  * The Terms and Conditions returned by the indexer, containing a URL for display and a SHA-256 hash for content
  * verification.
@@ -177,7 +180,7 @@ 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>;
+    clock?: (config: TConfig) => MaybePromise<Clock.Clock>;
     submissionService?: (config: TConfig) => MaybePromise<SubmissionService<ledger.FinalizedTransaction>>;
     pendingTransactionsService?: (config: TConfig) => MaybePromise<PendingTransactionsService<ledger.FinalizedTransaction>>;
     provingService?: (config: TConfig) => MaybePromise<ProvingService<UnboundTransaction>>;
@@ -225,7 +228,7 @@ export declare class WalletFacade {
      * - `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
+     * - `clock` - needs to implement {@link Clock.Clock} for getting current time, default uses system clock
      */
     static init<TConfig extends DefaultConfiguration>(initParams: InitParams<TConfig>): Promise<WalletFacade>;
     readonly shielded: ShieldedWalletAPI;
@@ -234,7 +237,7 @@ export declare class WalletFacade {
     readonly submissionService: SubmissionService<ledger.FinalizedTransaction>;
     readonly pendingTransactionsService: PendingTransactionsService<ledger.FinalizedTransaction>;
     readonly provingService: ProvingService<UnboundTransaction>;
-    readonly clock: Clock;
+    readonly clock: 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
@@ -307,6 +310,19 @@ export declare class WalletFacade {
         payFees?: boolean;
     }): Promise<UnprovenTransactionRecipe>;
     registerNightUtxosForDustGeneration(nightUtxos: readonly UtxoWithMeta[], nightVerifyingKey: ledger.SignatureVerifyingKey, signDustRegistration: (payload: Uint8Array) => ledger.Signature, dustReceiverAddress?: DustAddress): Promise<UnprovenTransactionRecipe>;
+    /**
+     * Waits until the dust projected to be generated by the given Night UTxOs reaches `requiredAmount`, re-checking every
+     * second. Pair with {@link estimateRegistration} to pick `requiredAmount`, then call before
+     * {@link registerNightUtxosForDustGeneration} so the registration covers its own fee.
+     *
+     * @param nightUtxos - Night UTxOs to project generation for; the same set passed to the registration.
+     * @param requiredAmount - Dust threshold to wait for. Resolves immediately if `<= 0n`.
+     * @param opts.timeoutMs - Deadline, in ms, for the threshold to be reached. Rejects otherwise. Default `300_000`.
+     * @throws If `nightUtxos` is empty, or if `requiredAmount` is not reached within `opts.timeoutMs`.
+     */
+    waitForGeneratedDust(nightUtxos: readonly UtxoWithMeta[], requiredAmount: bigint, opts?: {
+        timeoutMs?: number;
+    }): Promise<void>;
     deregisterFromDustGeneration(nightUtxos: UtxoWithMeta[], nightVerifyingKey: ledger.SignatureVerifyingKey, signDustRegistration: (payload: Uint8Array) => ledger.Signature): Promise<UnprovenTransactionRecipe>;
     revert(txOrRecipe: AnyTransaction | BalancingRecipe): Promise<void>;
     revertTransaction(tx: AnyTransaction): Promise<void>;
@@ -315,4 +331,3 @@ export declare class WalletFacade {
     queryTxHistoryByHash(hash: TransactionHistoryStorage.TransactionHash): Promise<WalletEntry | undefined>;
     getAllFromTxHistory(): Promise<WalletEntry[]>;
 }
-export {};

package/dist/index.js

@@ -16,6 +16,7 @@ import { makeDefaultProvingService, } from '@midnight-ntwrk/wallet-sdk-capabilit
 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 { Clock } from '@midnight-ntwrk/wallet-sdk-utilities';
 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, Schema } from 'effect';
@@ -98,8 +99,17 @@ export class FacadeState {
     }
 }
 const DEFAULT_TTL_MS = 60 * 60 * 1000; // 1 hour
-/** Default clock using real system time. */
-export const systemClock = { now: () => new Date() };
+/**
+ * Clock abstraction for obtaining the current time. By default, the facade uses the system clock
+ * ({@link Clock.systemClock}); for testing with a simulator, inject a custom clock (e.g. one backed by the simulator's
+ * time).
+ *
+ * Re-exported from `@midnight-ntwrk/wallet-sdk-utilities` as a namespace so the type is `Clock.Clock` and the default is
+ * `Clock.systemClock`. Forwarding the same symbol — rather than re-declaring its members individually — keeps the
+ * umbrella `wallet-sdk` package's star-exports unambiguous and lets lower-level packages (e.g. dust-wallet) share it
+ * without a circular dependency.
+ */
+export { Clock };
 export class WalletFacade {
     static makeDefaultSubmissionService(config) {
         return makeDefaultSubmissionService(config);
@@ -164,7 +174,7 @@ export class WalletFacade {
      * - `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
+     * - `clock` - needs to implement {@link Clock.Clock} for getting current time, default uses system clock
      */
     static async init(initParams) {
         const submissionService = await Promise.resolve(initParams.submissionService
@@ -179,7 +189,7 @@ 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));
-        const clock = await Promise.resolve(initParams.clock ? initParams.clock(initParams.configuration) : systemClock);
+        const clock = await Promise.resolve(initParams.clock ? initParams.clock(initParams.configuration) : Clock.systemClock);
         return new WalletFacade(shielded, unshielded, dust, submissionService, pendingTransactionsService, provingService, initParams.configuration.txHistoryStorage, clock);
     }
     shielded;
@@ -197,7 +207,7 @@ export class WalletFacade {
      *
      * @private
      */
-    constructor(shieldedWallet, unshieldedWallet, dustWallet, submissionService, pendingTransactionsService, provingService, txHistoryStorage, clock = systemClock) {
+    constructor(shieldedWallet, unshieldedWallet, dustWallet, submissionService, pendingTransactionsService, provingService, txHistoryStorage, clock = Clock.systemClock) {
         this.shielded = shieldedWallet;
         this.unshielded = unshieldedWallet;
         this.dust = dustWallet;
@@ -260,7 +270,21 @@ export class WalletFacade {
             await this.unshielded.revertTransaction(txWithOffers);
             throw error;
         }
-        // Step 4 — Sign via the standard signRecipe pathway, which now stamps both the unshielded
+        // Step 4 (first-time registration only) — Fail fast if the dust generated so far by the
+        // unregistered guaranteed UTxOs is below the registration's own fee. Submitting would fail
+        // on-chain with BalanceCheckOverspend. Skip for re-registration (all guaranteed UTxOs already
+        // registered) since `feePayment` is 0 by design and the caller is expected to balance the fee
+        // externally via `balanceUnprovenTransaction({ tokenKindsToBalance: ['dust'] })`.
+        const hasUnregisteredGuaranteed = split.guaranteedUtxos.some((u) => !u.utxo.registeredForDustGeneration);
+        if (isRegistration && hasUnregisteredGuaranteed) {
+            const fee = await this.dust.calculateFee([txWithDustActions]);
+            if (split.feePayment < fee) {
+                await this.unshielded.revertTransaction(txWithOffers);
+                throw Error(`Insufficient generated dust to cover registration fee (have ${split.feePayment}, need ${fee}). ` +
+                    `Use WalletFacade.waitForGeneratedDust(utxos, ${fee}) before retrying.`);
+            }
+        }
+        // Step 5 — 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);
@@ -590,6 +614,23 @@ export class WalletFacade {
             transaction: dustRegistrationTx,
         };
     }
+    /**
+     * Waits until the dust projected to be generated by the given Night UTxOs reaches `requiredAmount`, re-checking every
+     * second. Pair with {@link estimateRegistration} to pick `requiredAmount`, then call before
+     * {@link registerNightUtxosForDustGeneration} so the registration covers its own fee.
+     *
+     * @param nightUtxos - Night UTxOs to project generation for; the same set passed to the registration.
+     * @param requiredAmount - Dust threshold to wait for. Resolves immediately if `<= 0n`.
+     * @param opts.timeoutMs - Deadline, in ms, for the threshold to be reached. Rejects otherwise. Default `300_000`.
+     * @throws If `nightUtxos` is empty, or if `requiredAmount` is not reached within `opts.timeoutMs`.
+     */
+    async waitForGeneratedDust(nightUtxos, requiredAmount, opts) {
+        await this.dust.waitForGeneratedDust(nightUtxos.map(({ utxo, meta }) => ({
+            ...utxo,
+            ctime: meta.ctime,
+            registeredForDustGeneration: meta.registeredForDustGeneration,
+        })), requiredAmount, this.clock, opts);
+    }
     async deregisterFromDustGeneration(nightUtxos, nightVerifyingKey, signDustRegistration) {
         const dustDeregistrationTx = await this.createDustActionTransaction({ type: 'deregistration' }, nightUtxos, nightVerifyingKey, signDustRegistration);
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midnight-ntwrk/wallet-sdk-facade",
-  "version": "4.0.1",
+  "version": "4.1.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/facade"
   },
   "exports": {
     ".": {
@@ -28,14 +30,14 @@
     "@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-dust-wallet": "^4.2.0",
+    "@midnight-ntwrk/wallet-sdk-indexer-client": "^1.2.3",
+    "@midnight-ntwrk/wallet-sdk-shielded": "^3.0.2",
     "@midnight-ntwrk/wallet-sdk-unshielded-wallet": "^3.1.0",
     "rxjs": "^7.8.2"
   },
   "devDependencies": {
-    "@midnight-ntwrk/wallet-sdk-hd": "^3.0.2",
+    "@midnight-ntwrk/wallet-sdk-hd": "^3.0.3",
     "@midnight-ntwrk/wallet-sdk-utilities": "^1.2.0"
   },
   "scripts": {