@bsv/wallet-toolbox-client 2.4.21 → 2.5.0

package/out/index.client.d.mts

@@ -2093,6 +2093,7 @@ interface FindProvenTxReqsArgs extends FindSincePagedArgs {
 }
 interface FindProvenTxsArgs extends FindSincePagedArgs {
   partial: Partial<TableProvenTx>;
+  txids?: string[];
 }
 interface FindStaleMerkleRootsArgs {
   height: number;
@@ -2603,7 +2604,8 @@ declare class ScriptTemplateBRC29 implements ScriptTemplate {
   getKeyID(): string;
   getKeyDeriver(privKey: PrivateKey | HexString): KeyDeriverApi;
   lock(lockerPrivKey: string, unlockerPubKey: string): LockingScript;
-  unlock(unlockerPrivKey: string, lockerPubKey: string, sourceSatoshis?: number, lockingScript?: Script): ScriptTemplateUnlock;
+  unlock(unlockerPrivKey: PrivateKey | HexString, lockerPubKey: PublicKey | string, sourceSatoshis?: number, lockingScript?: Script): ScriptTemplateUnlock;
+  unlockWithDerivedPrivateKey(derivedPrivateKey: PrivateKey, sourceSatoshis?: number, lockingScript?: Script): ScriptTemplateUnlock;
   /**
    * P2PKH unlock estimateLength is a constant
    */
@@ -3166,8 +3168,9 @@ declare class EntityProvenTx extends EntityBase<TableProvenTx> {
   /**
    * @returns desirialized `MerklePath` object, value is cached.
    */
-  getMerklePath(): MerklePath;
+  getMerklePath(validateRoots?: boolean): MerklePath;
   _mp?: MerklePath;
+  _mpUnchecked?: MerklePath;
   get provenTxId(): number;
   set provenTxId(v: number);
   get created_at(): Date;
@@ -3873,6 +3876,9 @@ declare abstract class StorageReaderWriter extends StorageReader {
 }
 interface StorageReaderWriterOptions extends StorageReaderOptions {}
 //#endregion
+//#region ../src/storage/methods/availableManagedChange.d.ts
+type ManagedChangeInputCandidate = Pick<TableOutput, 'outputId' | 'transactionId' | 'satoshis' | 'txid' | 'vout'>;
+//#endregion
 //#region ../src/storage/StorageProvider.d.ts
 declare abstract class StorageProvider extends StorageReaderWriter implements WalletStorageProvider {
   isDirty: boolean;
@@ -3897,7 +3903,32 @@ declare abstract class StorageProvider extends StorageReaderWriter implements Wa
   }>;
   abstract purgeData(params: PurgeParams, trx?: TrxToken): Promise<PurgeResults>;
   abstract allocateChangeInput(userId: number, basketId: number, targetSatoshis: number, exactSatoshis: number | undefined, excludeSending: boolean, transactionId: number): Promise<TableOutput | undefined>;
+  /** Mark a planned set of change inputs spent within the caller's transaction. */
+  markChangeInputsSpent(outputIds: number[], transactionId: number, trx: TrxToken): Promise<number>;
+  /**
+   * Insert outputs that do not need their generated ids returned to the
+   * caller. Engines with a multi-row insert override this common-path helper;
+   * the fallback preserves existing storage implementations unchanged.
+   */
+  insertOutputs(outputs: TableOutput[], trx?: TrxToken): Promise<void>;
+  /** Return unreserved wallet-managed outputs eligible for automatic funding. */
+  findAvailableManagedChangeInputs(userId: number, basketId: number, excludeSending: boolean, trx?: TrxToken): Promise<TableOutput[]>;
+  /** Read only the fields needed by the in-memory funding planner. */
+  findAvailableManagedChangeInputCandidates(userId: number, basketId: number, excludeSending: boolean, trx?: TrxToken): Promise<ManagedChangeInputCandidate[]>;
+  /** Read the current status of a set of source transactions without loading raw transaction bytes. */
+  findTransactionStatusesByIds(userId: number, transactionIds: number[], trx?: TrxToken): Promise<Map<number, TransactionStatus>>;
+  /**
+   * Lock and return the selected funding rows whose source transaction and
+   * action-batch reservation state still permit allocation.
+   */
+  findFundingOutputsForUpdate(userId: number, outputIds: number[], statuses: TransactionStatus[], trx: TrxToken): Promise<Record<number, TableOutput>>;
   abstract getProvenOrRawTx(txid: string, trx?: TrxToken): Promise<ProvenOrRawTx>;
+  /**
+   * Resolve several transaction proofs in one storage operation when the
+   * backend supports it. The default preserves compatibility for custom
+   * providers; SQL and IndexedDB providers override this hot path.
+   */
+  getProvenOrRawTxs(txids: string[], trx?: TrxToken): Promise<Map<string, ProvenOrRawTx>>;
   abstract getRawTxOfKnownValidTransaction(txid?: string, offset?: number, length?: number, trx?: TrxToken): Promise<number[] | undefined>;
   abstract getLabelsForTransactionId(transactionId?: number, trx?: TrxToken): Promise<TableTxLabel[]>;
   abstract getTagsForOutputId(outputId: number, trx?: TrxToken): Promise<TableOutputTag[]>;
@@ -3921,6 +3952,8 @@ declare abstract class StorageProvider extends StorageReaderWriter implements Wa
   deleteActionBatchBlobRecords(_actionBatchId: number, _trx?: TrxToken): Promise<void>;
   getCapabilities(): Promise<StorageCapabilities>;
   protected supportsActionBatchPersistence(): boolean;
+  /** Custom providers may require physical expiry cleanup before reservations are queried. */
+  protected requiresActionBatchCleanupBeforeCreateAction(): boolean;
   beginActionBatch(auth: AuthId, args: BeginActionBatchArgs): Promise<BeginActionBatchResult>;
   extendActionBatch(auth: AuthId, args: ExtendActionBatchArgs): Promise<ExtendActionBatchResult>;
   renewActionBatch(auth: AuthId, batchId: string): Promise<RenewActionBatchResult>;
@@ -3939,7 +3972,7 @@ declare abstract class StorageProvider extends StorageReaderWriter implements Wa
   findOutputsByOutpointsForUpdate(userId: number, outpoints: Array<{
     txid: string;
     vout: number;
-  }>, trx: TrxToken): Promise<Record<string, TableOutput>>;
+  }>, trx: TrxToken, _noScript?: boolean): Promise<Record<string, TableOutput>>;
   findOrInsertOutputBasketsBulk(userId: number, names: string[], trx?: TrxToken): Promise<Record<string, TableOutputBasket>>;
   findOrInsertOutputTagsBulk(userId: number, tags: string[], trx?: TrxToken): Promise<Record<string, TableOutputTag>>;
   findOrInsertTxLabelsBulk(userId: number, labels: string[], trx?: TrxToken): Promise<Record<string, TableTxLabel>>;
@@ -4031,6 +4064,7 @@ declare abstract class StorageProvider extends StorageReaderWriter implements Wa
   private handleProvenTxBranch;
   getValidBeefForTxid(...[txid, mergeToBeef, trustSelf, knownTxids, trx, requiredLevels, chainTracker, skipInvalidProofs]: [txid: string, mergeToBeef?: Beef, trustSelf?: TrustSelf, knownTxids?: string[], trx?: TrxToken, requiredLevels?: number, chainTracker?: ChainTracker, skipInvalidProofs?: boolean]): Promise<Beef | undefined>;
   getBeefForTransaction(txid: string, options: StorageGetBeefOptions): Promise<Beef>;
+  getBeefForTransactions(txids: string[], options: StorageGetBeefOptions): Promise<Beef>;
   findMonitorEventById(id: number, trx?: TrxToken): Promise<TableMonitorEvent | undefined>;
   relinquishCertificate(auth: AuthId, args: RelinquishCertificateArgs): Promise<number>;
   relinquishOutput(auth: AuthId, args: RelinquishOutputArgs): Promise<number>;
@@ -4464,6 +4498,8 @@ interface StorageIdbSchema {
     value: TableOutput;
     indexes: {
       userId: number;
+      userId_basketId: [number, number];
+      txid_vout_userId: [string, number, number];
       transactionId: number;
       basketId: number;
       spentBy: string;
@@ -4571,6 +4607,7 @@ declare class StorageIdb extends StorageProvider implements WalletStorageProvide
   db?: IDBPDatabase<StorageIdbSchema>;
   constructor(options: StorageIdbOptions);
   protected supportsActionBatchPersistence(): boolean;
+  protected requiresActionBatchCleanupBeforeCreateAction(): boolean;
   /**
    * This method must be called at least once before any other method accesses the database,
    * and each time the schema may have updated.
@@ -4638,6 +4675,7 @@ declare class StorageIdb extends StorageProvider implements WalletStorageProvide
    */
   allocateChangeInput(userId: number, basketId: number, targetSatoshis: number, exactSatoshis: number | undefined, excludeSending: boolean, transactionId: number): Promise<TableOutput | undefined>;
   getProvenOrRawTx(txid: string, trx?: TrxToken): Promise<ProvenOrRawTx>;
+  getProvenOrRawTxs(txids: string[], trx?: TrxToken): Promise<Map<string, ProvenOrRawTx>>;
   getRawTxOfKnownValidTransaction(txid?: string, offset?: number, length?: number, trx?: TrxToken): Promise<number[] | undefined>;
   private getRawTxForSlice;
   private getRawTxFull;
@@ -4646,6 +4684,16 @@ declare class StorageIdb extends StorageProvider implements WalletStorageProvide
   listActions(auth: AuthId, vargs: Validation.ValidListActionsArgs): Promise<ListActionsResult>;
   listOutputs(auth: AuthId, vargs: Validation.ValidListOutputsArgs): Promise<ListOutputsResult>;
   countChangeInputs(userId: number, basketId: number, excludeSending: boolean): Promise<number>;
+  findTransactionStatusesByIds(userId: number, transactionIds: number[], trx?: TrxToken): Promise<Map<number, TransactionStatus>>;
+  private findOutputsByOutpointsInternal;
+  findOutputsByOutpoints(userId: number, outpoints: Array<{
+    txid: string;
+    vout: number;
+  }>, trx?: TrxToken): Promise<Record<string, TableOutput>>;
+  findOutputsByOutpointsForUpdate(userId: number, outpoints: Array<{
+    txid: string;
+    vout: number;
+  }>, trx: TrxToken, noScript?: boolean): Promise<Record<string, TableOutput>>;
   findCertificatesAuth(auth: AuthId, args: FindCertificatesArgs): Promise<TableCertificateX[]>;
   findOutputBasketsAuth(auth: AuthId, args: FindOutputBasketsArgs): Promise<TableOutputBasket[]>;
   findOutputsAuth(auth: AuthId, args: FindOutputsArgs): Promise<TableOutput[]>;
@@ -4738,6 +4786,7 @@ declare class StorageIdb extends StorageProvider implements WalletStorageProvide
   filterOutputBaskets(args: FindOutputBasketsArgs, filtered: (v: TableOutputBasket) => void): Promise<void>;
   findOutputBaskets(args: FindOutputBasketsArgs): Promise<TableOutputBasket[]>;
   private openOutputsCursor;
+  private eligibleOutputTransactionIds;
   filterOutputs(args: FindOutputsArgs, filtered: (v: TableOutput) => void, tagIds?: number[], isQueryModeAll?: boolean): Promise<void>;
   private outputMatchesTags;
   findOutputs(args: FindOutputsArgs, tagIds?: number[], isQueryModeAll?: boolean): Promise<TableOutput[]>;
@@ -8245,9 +8294,9 @@ interface WalletArgs {
    */
   makeLogger?: MakeWalletLogger;
   /**
-   * Internal Wallet Toolbox optimization policy. `auto` negotiates the optional
-   * action-batch storage capability; `legacy` always uses per-action storage.
-   * This does not change the BRC-100 wallet interface.
+   * Internal Wallet Toolbox optimization policy. `auto` (the default)
+   * negotiates the optional action-batch storage capability; `legacy` always
+   * uses per-action storage. This does not change the BRC-100 wallet interface.
    */
   actionBatchMode?: ActionBatchMode;
   /**
@@ -8838,7 +8887,7 @@ interface UMPTokenInteractor {
    *
    * @param hash The hash of the presentation key.
    * @returns The UMP token if found; otherwise, undefined.
-   * @throws Implementations should throw when absence cannot be established authoritatively.
+   * @throws Implementations should throw when no verified token or clean empty response is available.
    */
   findByPresentationKeyHash: (hash: number[]) => Promise<UMPToken | undefined>;
   /**
@@ -8847,7 +8896,7 @@ interface UMPTokenInteractor {
    *
    * @param hash The hash of the recovery key.
    * @returns The UMP token if found; otherwise, undefined.
-   * @throws Implementations should throw when absence cannot be established authoritatively.
+   * @throws Implementations should throw when no verified token or clean empty response is available.
    */
   findByRecoveryKeyHash: (hash: number[]) => Promise<UMPToken | undefined>;
   /**
@@ -8875,7 +8924,7 @@ interface UMPTokenLookupDiagnostics {
 }
 type UMPTokenLookupFailureReason = 'lookup-unavailable' | 'lookup-incomplete' | 'token-malformed' | 'token-ambiguous';
 /**
- * Raised when UMP absence cannot be established authoritatively.
+ * Raised when a UMP lookup yields neither a verified token nor a clean empty response.
  *
  * Callers must offer retry/recovery rather than treating this error as a new
  * account. Diagnostics contain counts only and never hashes, keys, or tokens.
@@ -8935,9 +8984,37 @@ declare class OverlayUMPTokenInteractor implements UMPTokenInteractor {
    */
   findByRecoveryKeyHash(hash: number[]): Promise<UMPToken | undefined>;
   private findToken;
+  /**
+   * Picks the newest rendition among distinct verified tokens, when possible.
+   *
+   * The on-chain UMP protocol expresses token updates by consumption: the
+   * transaction creating a new rendition spends the previous rendition's
+   * outpoint (there is no rendition counter field in the current format).
+   * A candidate is therefore superseded when any other candidate's ancestry
+   * (available from its BEEF) spends the candidate's outpoint.
+   *
+   * @returns The single unsuperseded candidate, or undefined when supersession
+   * cannot be established for every stale candidate (e.g. forked tokens).
+   */
+  private resolveNewestToken;
+  /**
+   * Whether `tx` spends an input whose source output (available in the BEEF)
+   * decodes as a UMP token sharing the candidate's presentation or recovery
+   * hash — on-chain proof that the candidate is an update of a same-identity
+   * predecessor rather than an independently minted token.
+   */
+  private consumesSameIdentityToken;
+  /**
+   * Accumulates every outpoint spent by `tx` and by the ancestor transactions
+   * embedded in its BEEF, so supersession is detected even when intermediate
+   * renditions are absent from the lookup answer. Iterative so arbitrarily
+   * long update chains cannot exhaust the call stack.
+   */
+  private collectSpentOutpoints;
   private emptyLookupDiagnostics;
   private toLookupDiagnostics;
   private lookupDiagnosticAttributes;
+  private captureLookupCompleted;
   private captureLookupFailure;
   /**
    * Creates or updates (replaces) a UMP token on-chain. If `oldTokenToConsume` is provided,