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

package/README.md

@@ -24,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

@@ -168,6 +168,12 @@ 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()`). */
@@ -200,6 +206,27 @@ export declare class WalletFacade {
      *   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;
@@ -208,6 +235,12 @@ export declare class WalletFacade {
     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;

package/dist/index.js

@@ -145,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)
@@ -170,6 +191,12 @@ export class WalletFacade {
     #txHistoryStorage;
     clock;
     #pendingSubscription;
+    /**
+     * 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;
@@ -194,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([
@@ -349,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 {
@@ -368,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);
     }
@@ -446,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midnight-ntwrk/wallet-sdk-facade",
-  "version": "4.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.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",
+    "@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.1.0",
     "@midnight-ntwrk/wallet-sdk-hd": "^3.0.2",
-    "@midnight-ntwrk/wallet-sdk-utilities": "1.1.1"
+    "@midnight-ntwrk/wallet-sdk-utilities": "^1.2.0"
   },
   "scripts": {
     "typecheck": "tsc -b ./tsconfig.json --noEmit --force",