@midnight-ntwrk/wallet-sdk-facade 5.0.0-rc.0 → 5.0.0-rc.1

package/dist/index.d.ts

@@ -7,13 +7,18 @@ import { type DefaultShieldedConfiguration, type ShieldedWalletAPI, type Shielde
 import type { DefaultUnshieldedConfiguration, SignSegment, 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 { type DateTime, Option, Schema } from 'effect';
+import { DateTime, Option, Schema } from 'effect';
 import { type AnyTx, type FinalizedTx, ProtocolVersion, TransactionHistoryStorage, type UnboundTx, type UnprovenTx, WalletTransaction } from '@midnight-ntwrk/wallet-sdk-abstractions';
 import * as ledgerV8 from '@midnight-ntwrk/ledger-v8';
 import { type WalletSeeds } from '@midnight-ntwrk/wallet-sdk-hd';
 import { type Observable } from 'rxjs';
 import { type DefaultPendingTransactionsServiceConfiguration, PendingTransactions, type PendingTransactionsService } from '@midnight-ntwrk/wallet-sdk-capabilities';
 import { type AnyLedgerParameters, type AnyVersionValidatableTransaction, type BlockData, type BlockDataFetcher, type ValidateTxOptions, ValidationFetchError, type VersionedValidationService, WellFormedError, type WellFormedStrictnessFlags } from '@midnight-ntwrk/wallet-sdk-capabilities/validation';
+/**
+ * The traits pending transactions are read with, exported so a test that restores a stored pending-transaction payload
+ * reads it exactly as the wallet does. Building a second trait for that would be testing the copy, not the wallet.
+ */
+export { finalizedTransactionTraits } from './transaction.js';
 import { type DustAddress, type ShieldedAddress, type UnshieldedAddress } from '@midnight-ntwrk/wallet-sdk-address-format';
 /**
  * Full entry schema for transaction history. The common entry data and wallet-specific sections (`shielded`,
@@ -32,11 +37,11 @@ export declare const WalletEntrySchema: Schema.Struct<Readonly<{
         submittedAt: typeof Schema.Date;
     }>, Schema.Struct<{
         status: Schema.Literal<["finalized"]>;
-        finalizedBlock: Schema.Struct<{
+        finalizedBlock: Schema.optional<Schema.Struct<{
             hash: typeof Schema.String;
             height: typeof Schema.Number;
             timestamp: typeof Schema.Date;
-        }>;
+        }>>;
     }>, Schema.Struct<{
         status: Schema.Literal<["rejected"]>;
         rejectedAt: typeof Schema.Date;
@@ -786,6 +791,35 @@ export declare class WalletFacade {
         ttl: Date;
         payFees?: boolean;
     }): Promise<UnprovenTransactionRecipe>;
+    /**
+     * Builds and signs a transaction registering `nightUtxos` to generate dust for `dustReceiverAddress`.
+     *
+     * @remarks
+     *   A first-time registration pays its own fee out of the dust its Night has generated so far. When that falls short,
+     *   the Night UTxOs booked for the transaction are released before the call rejects, so it can be retried as is.
+     * @example
+     *   ```ts
+     *   const register = () => wallet.registerNightUtxosForDustGeneration(nightUtxos, verifyingKey, signData);
+     *   const recipe = await register().catch(async (error: unknown) => {
+     *     // An unreachable fee will not be covered by waiting, so only a reachable one is waited out.
+     *     if (!isInsufficientDustForFeeError(error) || error.estimate._tag !== 'Reachable') throw error;
+     *     const timeoutMs = Number(error.estimate.seconds) * 1000 + 60_000;
+     *     await wallet.waitForGeneratedDust(nightUtxos, error.fee, { timeoutMs });
+     *     return register();
+     *   });
+     *   ```;
+     *
+     * @param nightUtxos - The Night UTxOs to register. Must be non-empty.
+     * @param nightVerifyingKey - The verifying key that owns them.
+     * @param signDustRegistration - Signs the registration and the unshielded offers.
+     * @param dustReceiverAddress - Where the generated dust goes. Defaults to this wallet's own dust address.
+     * @returns The unproven registration transaction, signed.
+     * @throws Error if `nightUtxos` is empty.
+     * @throws InsufficientDustForFeeError (`_tag` `'Wallet.InsufficientDustForFee'`, recognised by
+     *   `isInsufficientDustForFeeError` from `@midnight-ntwrk/wallet-sdk`) when the generated dust does not yet cover the
+     *   fee. It carries `claimableFeePayment`, `fee`, `shortfall` and an `estimate` of when it will; when it is
+     *   reachable, wait with {@link waitForGeneratedDust} for at least that long and retry.
+     */
     registerNightUtxosForDustGeneration(nightUtxos: readonly UtxoWithMeta[], nightVerifyingKey: ledgerV9.SignatureVerifyingKey, signDustRegistration: SignSegment, dustReceiverAddress?: DustAddress): Promise<UnprovenTransactionRecipe>;
     /**
      * Waits until the dust projected to be generated by the given Night UTxOs reaches `requiredAmount`, re-checking every

package/dist/index.js

@@ -15,18 +15,25 @@ import { makeDefaultSubmissionService, } from '@midnight-ntwrk/wallet-sdk-capabi
 import { makeDefaultVersionedProvingService, } from '@midnight-ntwrk/wallet-sdk-capabilities/proving';
 import { ShieldedSectionSchema, mergeShieldedSections, } from '@midnight-ntwrk/wallet-sdk-shielded';
 import { UnshieldedSectionSchema, mergeUnshieldedSections, } from '@midnight-ntwrk/wallet-sdk-unshielded-wallet';
+import { TransactionOps as V1UnshieldedTransactionOps } from '@midnight-ntwrk/wallet-sdk-unshielded-wallet/v1';
+import { TransactionOps as V2UnshieldedTransactionOps } from '@midnight-ntwrk/wallet-sdk-unshielded-wallet/v2';
 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, Either, Option, pipe, Schema } from 'effect';
+import { Array as Arr, DateTime, Either, Option, pipe, Schema } from 'effect';
 import { ProtocolVersion, TransactionHistoryStorage, WalletTransaction, WireFormatError, } from '@midnight-ntwrk/wallet-sdk-abstractions';
 import * as ledgerV8 from '@midnight-ntwrk/ledger-v8';
 import * as Signatures from '@midnight-ntwrk/wallet-sdk-capabilities/signatures';
-import { BehaviorSubject, combineLatest, concatMap, distinctUntilChanged, firstValueFrom, map, tap, } from 'rxjs';
+import { BehaviorSubject, combineLatest, concatMap, distinctUntilChanged, filter, firstValueFrom, map, take, tap, } from 'rxjs';
 import { PendingTransactions, PendingTransactionsServiceImpl, } from '@midnight-ntwrk/wallet-sdk-capabilities';
 import { makeDefaultBlockDataFetcher, makeDefaultVersionedValidationService, ValidationFetchError, WellFormedError, } from '@midnight-ntwrk/wallet-sdk-capabilities/validation';
 import { finalizedTransactionTraits, txHistoryHash } from './transaction.js';
+/**
+ * The traits pending transactions are read with, exported so a test that restores a stored pending-transaction payload
+ * reads it exactly as the wallet does. Building a second trait for that would be testing the copy, not the wallet.
+ */
+export { finalizedTransactionTraits } from './transaction.js';
 /**
  * Why the wallet gave up on a transaction, for the history entry.
  *
@@ -292,6 +299,8 @@ export class FacadeState {
     }
 }
 const DEFAULT_TTL_MS = 60 * 60 * 1000; // 1 hour
+/** How a coin is named wherever it is referred to without being carried: in a reservation, and in a release by id. */
+const coinIdsOf = (utxos) => utxos.map((utxo) => `${utxo.intentHash}#${utxo.outputNo}`);
 /**
  * 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
@@ -447,6 +456,8 @@ export class WalletFacade {
     #txHistoryStorage;
     clock;
     #pendingSubscription;
+    #expiredReservationSubscription;
+    #restoredBookingSubscription;
     #protocolVersionSubscription;
     /**
      * The protocol version the wallets have all reached, as last observed.
@@ -483,6 +494,38 @@ export class WalletFacade {
             }
         }))
             .subscribe();
+        // A reservation past its TTL stands for a transaction the ledger will not accept, so the record has done its job
+        // and is dropped. It does not release the coins: the wallet books each one with the same TTL and sweeps them
+        // itself, so one mechanism owns release.
+        //
+        // Releasing from here as well would be a second sweep on a different clock, and a coin the wallet has already
+        // freed can be booked again for another transaction before this one fires. The ids a reservation holds say
+        // nothing about which booking currently holds them, so that release would free the wrong one.
+        this.#expiredReservationSubscription = this.pendingTransactionsService
+            .state()
+            .pipe(concatMap((pending) => PendingTransactions.allExpiredReservations(pending)), concatMap((reservation) => this.pendingTransactionsService.clearReservation(reservation.identifiers)))
+            .subscribe();
+        // Coins a previous process left booked would otherwise sit until their transactions' TTLs, which can be an hour.
+        // Once sync reaches the tip, every transaction this address is party to has been applied, so a coin still booked
+        // was never spent — unless a reservation or a transaction being tracked says the spend is still out there. Both
+        // halves matter: registering a transaction drops the reservation standing in for it, so from submission onwards
+        // the tracked transaction is the only thing saying its coins are spoken for.
+        //
+        // This only sees what the services were given. A pending-transactions service restored from storage covers the
+        // spends a previous process submitted; one started empty covers none of them, and a restored booking whose
+        // transaction is still in the mempool is released here.
+        this.#restoredBookingSubscription = this.unshielded.state
+            .pipe(filter((unshielded) => unshielded.state.progress.isStrictlyComplete()), 
+        // Only bookings restored at startup are candidates, and this releases all of them at once, so the first time
+        // sync reaches the tip is the only time there is anything to do. Acting once also keeps the reaction from
+        // feeding itself: releasing publishes new state, which would otherwise satisfy this same condition again.
+        take(1), concatMap(async () => {
+            const { publicKey } = (await firstValueFrom(this.unshielded.state)).state;
+            const pending = await firstValueFrom(this.pendingTransactionsService.state());
+            const stillSpokenFor = PendingTransactions.coveredUnshieldedIds(pending, (tx) => this.#ownInputIds(tx, publicKey.publicKey));
+            await this.unshielded.releaseRestoredPending(stillSpokenFor);
+        }))
+            .subscribe();
         // Deliberately built from the wallets' own states rather than from `state()`: `state()` includes the pending set,
         // and orphaning writes to it, so feeding that back here would be a cycle.
         this.#protocolVersionSubscription = combineLatest([this.shielded.state, this.unshielded.state, this.dust.state])
@@ -593,6 +636,107 @@ export class WalletFacade {
             }),
         }).pipe(Either.map((transaction) => WalletTransaction.adopt(stage, transaction, protocolVersion))), (error) => error);
     }
+    /**
+     * Reads the transaction a handle carries, with the ledger version the handle itself names.
+     *
+     * @remarks
+     *   The counterpart of {@link accept}, which reads at the version the facade is acting at and refuses the rest. This one
+     *   asks nothing of the facade's position: the handle was stamped by whichever ledger version built it, and that
+     *   version is the one that can read its bytes. It is how a transaction tracked across a crossing can still name its
+     *   coins afterwards.
+     * @param handle The handle to read.
+     * @returns The carried transaction.
+     */
+    #carried(handle) {
+        return Either.getOrThrowWith(WalletTransaction.unwrapWithin(handle, this.epochOf(handle.protocolVersion)), (error) => error);
+    }
+    /**
+     * The ids of this wallet's own coins that `handle` spends, read with the ledger version that built it.
+     *
+     * @remarks
+     *   The identity is this wallet's in ledger-v9's shape; a transaction built below the boundary is read with ledger-v8,
+     *   whose verifying key is the bare bytes of the one scheme it has, so the key is narrowed to match. Only a schnorr
+     *   identity ever has a ledger-v8 transaction to read, because the wallet refuses to start that variant with any
+     *   other, so the narrowing cannot fail here and a failure is reported as the defect it would be.
+     * @param handle The transaction to read.
+     * @param publicKey This wallet's verifying key, in the shape of whichever variant is running: ledger-v8's bare hex
+     *   below the boundary, ledger-v9's tagged record from it.
+     * @returns Every coin of this wallet's the transaction spends, each `intentHash#outputNo`.
+     */
+    #ownInputIds(handle, publicKey) {
+        // Lifted once so both branches start from ledger-v9's shape; ledger-v8's key is the bare string, so the check is exact.
+        const verifyingKey = typeof publicKey === 'string' ? Signatures.liftSignatureVerifyingKey(publicKey) : publicKey;
+        const ownInputs = handle.protocolVersion < this.#forkVersion
+            ? V1UnshieldedTransactionOps.extractOwnInputs(this.#carried(handle), Either.getOrThrowWith(Signatures.lowerSignatureVerifyingKey(verifyingKey), (error) => error))
+            : V2UnshieldedTransactionOps.extractOwnInputs(this.#carried(handle), verifyingKey);
+        return coinIdsOf(ownInputs);
+    }
+    /**
+     * Records that a just-balanced transaction has unshielded coins reserved.
+     *
+     * Balancing books those coins, but nothing tracks the transaction until it is submitted, so a caller that abandons it
+     * in between leaves the coins spoken for with no record saying so. The reservation is that record, and it is matched
+     * to the transaction that eventually arrives by identifier, which proving and binding leave unchanged.
+     *
+     * Takes the transaction the unshielded wallet produced rather than the merged one: its inputs are exactly the coins
+     * booked here, and its identifiers are a subset of whatever the merged transaction ends up carrying.
+     */
+    async #reserve(unshieldedTx, ttl) {
+        if (!unshieldedTx) {
+            return;
+        }
+        const { publicKey } = (await firstValueFrom(this.unshielded.state)).state;
+        await this.#reserveIds(unshieldedTx, this.#ownInputIds(unshieldedTx, publicKey.publicKey), ttl);
+    }
+    /** Records `bookedIds` against `unshieldedTx`, or nothing at all when the transaction booked no coins. */
+    async #reserveIds(unshieldedTx, bookedIds, ttl) {
+        if (bookedIds.length === 0) {
+            return;
+        }
+        const identity = this.#carried(unshieldedTx);
+        await this.pendingTransactionsService.addReservation({
+            identifiers: identity.identifiers(),
+            intentHashes: [...(identity.intents?.entries() ?? [])].map(([segment, intent]) => intent.intentHash(segment)),
+            inputs: { unshielded: bookedIds },
+            ttl,
+            createdAt: DateTime.unsafeFromDate(this.clock.now()),
+            expired: false,
+        });
+    }
+    /**
+     * Balances a transaction in place and records only the coins the wallet itself booked doing so.
+     *
+     * In-place balancing hands back the caller's own transaction with the wallet's inputs added, so the result names
+     * coins from two sources: the ones coin selection just took, and any the caller had already put there. Only the first
+     * are this wallet's booking, and they are exactly the inputs of this wallet's that the balanced transaction carries
+     * and the caller's did not.
+     *
+     * Read off the two transactions, not off the wallet's published state: the wallet publishes its state on its own
+     * fiber, so a read taken as soon as the balancing call returns can still show the coins as available, and the booking
+     * would go unrecorded.
+     */
+    async #balanceInPlaceAndReserve(tx, balance, ttl) {
+        const { publicKey } = (await firstValueFrom(this.unshielded.state)).state;
+        const inputsBefore = new Set(this.#ownInputIds(tx, publicKey.publicKey));
+        const balanced = await balance();
+        if (balanced === undefined) {
+            return balanced;
+        }
+        const newlyBooked = this.#ownInputIds(balanced, publicKey.publicKey).filter((id) => !inputsBefore.has(id));
+        await this.#reserveIds(balanced, newlyBooked, ttl);
+        return balanced;
+    }
+    /**
+     * Undoes a booking taken while balancing, together with the record that stood for it.
+     *
+     * The two always go together. A record left behind outlives the coins it named, and until its TTL passes it tells
+     * anything that reads it that a spend is still out there — holding coins at the next reconciliation that nothing is
+     * actually holding.
+     */
+    async #revertUnshieldedBooking(tx) {
+        await this.unshielded.revertTransaction(tx);
+        await this.pendingTransactionsService.clearReservation([...this.#carried(tx).identifiers()]);
+    }
     defaultTtl() {
         return new Date(this.clock.now().getTime() + DEFAULT_TTL_MS);
     }
@@ -666,11 +810,12 @@ export class WalletFacade {
         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 }) => ({
+        const nightUtxosWithMeta = nightUtxos.map(({ utxo, meta }) => ({
             ...utxo,
             ctime: meta.ctime,
             registeredForDustGeneration: meta.registeredForDustGeneration,
-        })), isRegistration);
+        }));
+        const split = await this.dust.splitNightUtxosForDustRegistration(now, nightUtxosWithMeta, isRegistration);
         const toUnshieldedUtxoWithMeta = (u) => ({
             utxo: {
                 value: u.utxo.value,
@@ -690,6 +835,7 @@ export class WalletFacade {
         // 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);
+        await this.#reserve(txWithOffers, 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;
@@ -697,7 +843,7 @@ export class WalletFacade {
             txWithDustActions = await this.dust.attachDustRegistration(txWithOffers, now, nightVerifyingKey, dustReceiverAddress, split.feePayment);
         }
         catch (error) {
-            await this.unshielded.revertTransaction(txWithOffers);
+            await this.#revertUnshieldedBooking(txWithOffers);
             throw error;
         }
         // Step 4 (first-time registration only) — Fail fast if the dust generated so far by the
@@ -713,10 +859,12 @@ export class WalletFacade {
         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.`);
+            try {
+                await this.dust.ensureFeeCoverage(now, nightUtxosWithMeta, split.feePayment, fee);
+            }
+            catch (error) {
+                await this.#revertUnshieldedBooking(txWithOffers);
+                throw error;
             }
         }
         // Step 5 — Sign via the standard signRecipe pathway, which now stamps both the unshielded
@@ -729,7 +877,7 @@ export class WalletFacade {
             return signedRecipe.transaction;
         }
         catch (error) {
-            await this.unshielded.revertTransaction(txWithOffers);
+            await this.#revertUnshieldedBooking(txWithOffers);
             throw error;
         }
     }
@@ -796,6 +944,7 @@ export class WalletFacade {
         const unshieldedBalancingTx = shouldBalanceUnshielded
             ? await this.unshielded.balanceFinalizedTransaction(tx)
             : undefined;
+        await this.#reserve(unshieldedBalancingTx, ttl);
         const shieldedBalancingTx = shouldBalanceShielded ? await this.shielded.balanceTransaction(tx) : undefined;
         // Step 2: Merge unshielded and shielded balancing
         const mergedBalancingTx = this.mergeUnprovenTransactions(shieldedBalancingTx, unshieldedBalancingTx);
@@ -836,7 +985,7 @@ export class WalletFacade {
         const shieldedBalancingTx = shouldBalanceShielded ? await this.shielded.balanceTransaction(tx) : undefined;
         // For unbound transactions, unshielded balancing happens in place not with a balancing transaction
         const balancedUnshieldedTx = shouldBalanceUnshielded
-            ? await this.unshielded.balanceUnboundTransaction(tx)
+            ? await this.#balanceInPlaceAndReserve(tx, () => this.unshielded.balanceUnboundTransaction(tx), ttl)
             : undefined;
         // Step 2: Unbound unshielded tx are balanced in place, use it as base tx if present
         const baseTx = balancedUnshieldedTx ?? tx;
@@ -878,7 +1027,7 @@ export class WalletFacade {
         const shieldedBalancingTx = shouldBalanceShielded ? await this.shielded.balanceTransaction(tx) : undefined;
         // For unproven transactions, unshielded balancing happens in place
         const balancedUnshieldedTx = shouldBalanceUnshielded
-            ? await this.unshielded.balanceUnprovenTransaction(tx)
+            ? await this.#balanceInPlaceAndReserve(tx, () => this.unshielded.balanceUnprovenTransaction(tx), ttl)
             : undefined;
         // Step 2: Use the balanced unshielded tx if present, otherwise use the original tx
         const baseTx = balancedUnshieldedTx ?? tx;
@@ -1009,7 +1158,7 @@ export class WalletFacade {
         catch (error) {
             await Promise.allSettled([
                 this.shielded.revertTransaction(tx),
-                this.unshielded.revertTransaction(tx),
+                this.#revertUnshieldedBooking(tx),
                 this.dust.revertTransaction(tx),
             ]);
             throw error;
@@ -1035,6 +1184,7 @@ export class WalletFacade {
         }
         const shieldedTx = shieldedOutputs.length > 0 ? await this.shielded.transferTransaction(shieldedOutputs) : undefined;
         const unshieldedTx = unshieldedOutputs.length > 0 ? await this.unshielded.transferTransaction(unshieldedOutputs, ttl) : undefined;
+        await this.#reserve(unshieldedTx, ttl);
         const mergedTxs = this.mergeUnprovenTransactions(shieldedTx, unshieldedTx);
         // Add fee payment
         const dustResult = payFees ? await this.dust.balanceTransactions([mergedTxs], ttl) : undefined;
@@ -1110,6 +1260,7 @@ export class WalletFacade {
         const unshieldedTx = hasUnshieldedPart
             ? await this.unshielded.initSwap(unshieldedInputs ?? {}, unshieldedOutputs, ttl)
             : undefined;
+        await this.#reserve(unshieldedTx, ttl);
         const combinedTx = this.mergeUnprovenTransactions(shieldedTx, unshieldedTx);
         if (!combinedTx) {
             throw Error('Unexpected transaction state.');
@@ -1124,6 +1275,35 @@ export class WalletFacade {
             ...(dustResult ? { blockData: dustResult.blockData } : {}),
         };
     }
+    /**
+     * Builds and signs a transaction registering `nightUtxos` to generate dust for `dustReceiverAddress`.
+     *
+     * @remarks
+     *   A first-time registration pays its own fee out of the dust its Night has generated so far. When that falls short,
+     *   the Night UTxOs booked for the transaction are released before the call rejects, so it can be retried as is.
+     * @example
+     *   ```ts
+     *   const register = () => wallet.registerNightUtxosForDustGeneration(nightUtxos, verifyingKey, signData);
+     *   const recipe = await register().catch(async (error: unknown) => {
+     *     // An unreachable fee will not be covered by waiting, so only a reachable one is waited out.
+     *     if (!isInsufficientDustForFeeError(error) || error.estimate._tag !== 'Reachable') throw error;
+     *     const timeoutMs = Number(error.estimate.seconds) * 1000 + 60_000;
+     *     await wallet.waitForGeneratedDust(nightUtxos, error.fee, { timeoutMs });
+     *     return register();
+     *   });
+     *   ```;
+     *
+     * @param nightUtxos - The Night UTxOs to register. Must be non-empty.
+     * @param nightVerifyingKey - The verifying key that owns them.
+     * @param signDustRegistration - Signs the registration and the unshielded offers.
+     * @param dustReceiverAddress - Where the generated dust goes. Defaults to this wallet's own dust address.
+     * @returns The unproven registration transaction, signed.
+     * @throws Error if `nightUtxos` is empty.
+     * @throws InsufficientDustForFeeError (`_tag` `'Wallet.InsufficientDustForFee'`, recognised by
+     *   `isInsufficientDustForFeeError` from `@midnight-ntwrk/wallet-sdk`) when the generated dust does not yet cover the
+     *   fee. It carries `claimableFeePayment`, `fee`, `shortfall` and an `estimate` of when it will; when it is
+     *   reachable, wait with {@link waitForGeneratedDust} for at least that long and retry.
+     */
     async registerNightUtxosForDustGeneration(nightUtxos, nightVerifyingKey, signDustRegistration, dustReceiverAddress) {
         if (nightUtxos.length === 0) {
             throw Error('At least one Night UTXO is required.');
@@ -1271,6 +1451,8 @@ export class WalletFacade {
             this.pendingTransactionsService.stop(),
             Promise.resolve(this.#pendingSubscription?.unsubscribe()),
             Promise.resolve(this.#protocolVersionSubscription?.unsubscribe()),
+            Promise.resolve(this.#expiredReservationSubscription?.unsubscribe()),
+            Promise.resolve(this.#restoredBookingSubscription?.unsubscribe()),
         ]);
     }
     async queryTxHistoryByHash(hash) {

package/dist/transaction.d.ts

@@ -1,5 +1,7 @@
 import { type PendingTransactions } from '@midnight-ntwrk/wallet-sdk-capabilities';
 import { ProtocolVersion, type FinalizedTx } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import * as ledgerV8 from '@midnight-ntwrk/ledger-v8';
+import * as ledgerV9 from '@midnightntwrk/ledger-v9';
 /**
  * The key under which a transaction's history entry is stored.
  *
@@ -20,6 +22,16 @@ export declare const txHistoryHash: (tx: {
     transactionHash: () => unknown;
     serialize: () => Uint8Array;
 }) => string;
+export declare const v9FinalizedTransactionTrait: PendingTransactions.TransactionTrait<ledgerV9.FinalizedTransaction>;
+/**
+ * The ledger-v8's reading of a pending transaction.
+ *
+ * @remarks
+ *   Structurally the same as ledger-v9's — identifiers, a TTL, bytes — against a different ledger version's classes. It
+ *   is the classes that make this a separate trait: `instanceof` distinguishes them, each deserializer refuses the
+ *   other's bytes, and a grace period is read off that version's own initial parameters.
+ */
+export declare const v8FinalizedTransactionTrait: PendingTransactions.TransactionTrait<ledgerV8.FinalizedTransaction>;
 /**
  * The traits pending transactions are read with, split at the protocol version this chain forks at.
  *

package/dist/transaction.js

@@ -40,7 +40,29 @@ export const txHistoryHash = (tx) => {
         return Buffer.from(tx.serialize()).toString('hex');
     }
 };
-const v9FinalizedTransactionTrait = {
+/**
+ * The one TTL rule, closed over the ledger whose grace period it reads: a transaction has expired once the earliest of
+ * its intent TTLs has passed, or, when it spends dust, carries shielded offers, or carries no intent at all, once the
+ * dust grace period after its creation has. The grace period is the wallet's own backstop rather than a ledger rule; it
+ * is what lets a rewards or bridge claim, which has no intents and no offers and which the indexer never reports a
+ * status for, leave the pending set at all.
+ */
+const hasTTLExpiredUnder = (dustGracePeriodSeconds) => (tx, creationTime, now) => {
+    const intentTTLs = pipe(tx.intents?.values().toArray() ?? [], Arr.map((i) => i.ttl), Arr.filterMap(DateTime.make));
+    const hasDustPayments = pipe(tx.intents?.values().toArray() ?? [], Arr.flatMap((i) => i.dustActions?.spends ?? []), Arr.isNonEmptyArray);
+    const hasShieldedOffers = tx.guaranteedOffer != null || (tx.fallibleOffer?.size ?? 0) > 0;
+    const hasNoDeadlineOfItsOwn = Arr.isEmptyReadonlyArray(intentTTLs);
+    const maybeShieldedTTL = hasDustPayments || hasShieldedOffers || hasNoDeadlineOfItsOwn
+        ? pipe(creationTime, DateTime.addDuration(Duration.seconds(Number(dustGracePeriodSeconds()))), Arr.of)
+        : Arr.empty();
+    return pipe(intentTTLs, Arr.appendAll(maybeShieldedTTL), (arr) => Arr.isNonEmptyReadonlyArray(arr)
+        ? Option.some(Arr.min(arr, Order.mapInput(Order.Date, DateTime.toDate)))
+        : Option.none(), Option.match({
+        onNone: () => false,
+        onSome: (finalTTL) => DateTime.distance(finalTTL, now) > 0,
+    }));
+};
+export const v9FinalizedTransactionTrait = {
     areAllTxIdsIncluded(tx, txIds) {
         const txIdsSet = HashSet.fromIterable(tx.identifiers());
         const expectedIdSet = HashSet.fromIterable(txIds);
@@ -52,21 +74,7 @@ const v9FinalizedTransactionTrait = {
     firstId(tx) {
         return tx.identifiers()[0];
     },
-    hasTTLExpired(tx, creationTime, now) {
-        const defaultShieldedGracePeriod = ledgerV9.LedgerParameters.initialParameters().dust.dustGracePeriodSeconds;
-        const intentTTLs = pipe(tx.intents?.values().toArray() ?? [], Arr.map((i) => i.ttl), Arr.filterMap(DateTime.make));
-        const hasDustPayments = pipe(tx.intents?.values().toArray() ?? [], Arr.flatMap((i) => i.dustActions?.spends ?? []), Arr.isNonEmptyArray);
-        const hasShieldedOffers = tx.guaranteedOffer != null || (tx.fallibleOffer?.size ?? 0) == 0;
-        const maybeShieldedTTL = hasDustPayments || hasShieldedOffers
-            ? pipe(creationTime, DateTime.addDuration(Duration.seconds(Number(defaultShieldedGracePeriod))), Arr.of)
-            : Arr.empty();
-        return pipe(intentTTLs, Arr.appendAll(maybeShieldedTTL), (arr) => Arr.isNonEmptyReadonlyArray(arr)
-            ? Option.some(Arr.min(arr, Order.mapInput(Order.Date, DateTime.toDate)))
-            : Option.none(), Option.match({
-            onNone: () => false,
-            onSome: (finalTTL) => DateTime.distance(finalTTL, now) > 0,
-        }));
-    },
+    hasTTLExpired: hasTTLExpiredUnder(() => ledgerV9.LedgerParameters.initialParameters().dust.dustGracePeriodSeconds),
     ids(tx) {
         return tx.identifiers();
     },
@@ -92,7 +100,7 @@ const v9FinalizedTransactionTrait = {
  *   is the classes that make this a separate trait: `instanceof` distinguishes them, each deserializer refuses the
  *   other's bytes, and a grace period is read off that version's own initial parameters.
  */
-const v8FinalizedTransactionTrait = {
+export const v8FinalizedTransactionTrait = {
     areAllTxIdsIncluded(tx, txIds) {
         return HashSet.isSubset(HashSet.fromIterable(tx.identifiers()), HashSet.fromIterable(txIds));
     },
@@ -102,21 +110,7 @@ const v8FinalizedTransactionTrait = {
     firstId(tx) {
         return tx.identifiers()[0];
     },
-    hasTTLExpired(tx, creationTime, now) {
-        const defaultShieldedGracePeriod = ledgerV8.LedgerParameters.initialParameters().dust.dustGracePeriodSeconds;
-        const intentTTLs = pipe(tx.intents?.values().toArray() ?? [], Arr.map((i) => i.ttl), Arr.filterMap(DateTime.make));
-        const hasDustPayments = pipe(tx.intents?.values().toArray() ?? [], Arr.flatMap((i) => i.dustActions?.spends ?? []), Arr.isNonEmptyArray);
-        const hasShieldedOffers = tx.guaranteedOffer != null || (tx.fallibleOffer?.size ?? 0) == 0;
-        const maybeShieldedTTL = hasDustPayments || hasShieldedOffers
-            ? pipe(creationTime, DateTime.addDuration(Duration.seconds(Number(defaultShieldedGracePeriod))), Arr.of)
-            : Arr.empty();
-        return pipe(intentTTLs, Arr.appendAll(maybeShieldedTTL), (arr) => Arr.isNonEmptyReadonlyArray(arr)
-            ? Option.some(Arr.min(arr, Order.mapInput(Order.Date, DateTime.toDate)))
-            : Option.none(), Option.match({
-            onNone: () => false,
-            onSome: (finalTTL) => DateTime.distance(finalTTL, now) > 0,
-        }));
-    },
+    hasTTLExpired: hasTTLExpiredUnder(() => ledgerV8.LedgerParameters.initialParameters().dust.dustGracePeriodSeconds),
     ids(tx) {
         return tx.identifiers();
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midnight-ntwrk/wallet-sdk-facade",
-  "version": "5.0.0-rc.0",
+  "version": "5.0.0-rc.1",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -27,13 +27,13 @@
   },
   "dependencies": {
     "@midnightntwrk/ledger-v9": "1.0.0-rc.5",
-    "@midnight-ntwrk/wallet-sdk-abstractions": "3.0.0-rc.0",
+    "@midnight-ntwrk/wallet-sdk-abstractions": "3.0.0-rc.1",
     "@midnight-ntwrk/wallet-sdk-address-format": "4.0.0-rc.0",
-    "@midnight-ntwrk/wallet-sdk-capabilities": "4.0.0-rc.0",
-    "@midnight-ntwrk/wallet-sdk-dust-wallet": "5.0.0-rc.0",
-    "@midnight-ntwrk/wallet-sdk-indexer-client": "2.0.0-rc.0",
-    "@midnight-ntwrk/wallet-sdk-shielded": "4.0.0-rc.0",
-    "@midnight-ntwrk/wallet-sdk-unshielded-wallet": "4.0.0-rc.0",
+    "@midnight-ntwrk/wallet-sdk-capabilities": "4.0.0-rc.1",
+    "@midnight-ntwrk/wallet-sdk-dust-wallet": "5.0.0-rc.1",
+    "@midnight-ntwrk/wallet-sdk-indexer-client": "2.0.0-rc.1",
+    "@midnight-ntwrk/wallet-sdk-shielded": "4.0.0-rc.1",
+    "@midnight-ntwrk/wallet-sdk-unshielded-wallet": "4.0.0-rc.1",
     "effect": "^3.19.19",
     "rxjs": "^7.8.2"
   },