From 45845e236d306f650ad448df8088d6b62755a102 Mon Sep 17 00:00:00 2001 From: Alejo Acosta Date: Thu, 14 Nov 2024 14:29:49 -0300 Subject: [PATCH] add JSDoc to qi hdwallet methods --- src/transaction/abstract-coinselector.ts | 22 +++++++++++++++++++-- src/transaction/coinselector-fewest.ts | 17 ++++------------ src/wallet/qi-hdwallet.ts | 25 ++++++++++++++++++++++-- 3 files changed, 47 insertions(+), 17 deletions(-) diff --git a/src/transaction/abstract-coinselector.ts b/src/transaction/abstract-coinselector.ts index 9c94bcf1..f65e568e 100644 --- a/src/transaction/abstract-coinselector.ts +++ b/src/transaction/abstract-coinselector.ts @@ -37,6 +37,13 @@ export type SelectedCoinsResult = { * @category Transaction * @abstract */ +export interface CoinSelectionConfig { + target?: bigint; + fee?: bigint; + includeLocked?: boolean; + // Any future parameters can be added here +} + export abstract class AbstractCoinSelector { public availableUTXOs: UTXO[]; public totalInputValue: bigint = BigInt(0); @@ -65,10 +72,10 @@ export abstract class AbstractCoinSelector { * and change outputs. * * @abstract - * @param {SpendTarget} target - The target address and value to spend. + * @param {CoinSelectionConfig} config - The configuration for coin selection. * @returns {SelectedCoinsResult} The selected UTXOs and outputs. */ - abstract performSelection(target: bigint, fee: bigint): SelectedCoinsResult; + abstract performSelection(config: CoinSelectionConfig): SelectedCoinsResult; /** * Validates the provided UTXO instance. In order to be valid for coin selection, the UTXO must have a valid address @@ -95,4 +102,15 @@ export abstract class AbstractCoinSelector { throw new Error('UTXO index is required'); } } + + /** + * Validates the available UTXOs. + * + * @throws Will throw an error if there are no available UTXOs. + */ + protected validateUTXOs() { + if (this.availableUTXOs.length === 0) { + throw new Error('No UTXOs available'); + } + } } diff --git a/src/transaction/coinselector-fewest.ts b/src/transaction/coinselector-fewest.ts index cfa45932..21c12747 100644 --- a/src/transaction/coinselector-fewest.ts +++ b/src/transaction/coinselector-fewest.ts @@ -1,5 +1,5 @@ // import { bigIntAbs } from '../utils/maths.js'; -import { AbstractCoinSelector, SelectedCoinsResult } from './abstract-coinselector.js'; +import { AbstractCoinSelector, CoinSelectionConfig, SelectedCoinsResult } from './abstract-coinselector.js'; import { UTXO, denominate, denominations } from './utxo.js'; /** @@ -21,7 +21,9 @@ export class FewestCoinSelector extends AbstractCoinSelector { * @param {bigint} fee - The fee amount to include in the selection. * @returns {SelectedCoinsResult} The selected UTXOs and outputs. */ - performSelection(target: bigint, fee: bigint = BigInt(0)): SelectedCoinsResult { + performSelection(config: CoinSelectionConfig): SelectedCoinsResult { + const { target = BigInt(0), fee = BigInt(0) } = config; + if (target <= BigInt(0)) { throw new Error('Target amount must be greater than 0'); } @@ -353,15 +355,4 @@ export class FewestCoinSelector extends AbstractCoinSelector { return diff > BigInt(0) ? 1 : diff < BigInt(0) ? -1 : 0; }); } - - /** - * Validates the available UTXOs. - * - * @throws Will throw an error if there are no available UTXOs. - */ - private validateUTXOs() { - if (this.availableUTXOs.length === 0) { - throw new Error('No UTXOs available'); - } - } } diff --git a/src/wallet/qi-hdwallet.ts b/src/wallet/qi-hdwallet.ts index d244f591..1776348b 100644 --- a/src/wallet/qi-hdwallet.ts +++ b/src/wallet/qi-hdwallet.ts @@ -631,7 +631,7 @@ export class QiHDWallet extends AbstractHDWallet { const fewestCoinSelector = new FewestCoinSelector(unlockedUTXOs); const spendTarget: bigint = amount; - let selection = fewestCoinSelector.performSelection(spendTarget); + let selection = fewestCoinSelector.performSelection({ target: spendTarget }); // 3. Generate as many unused addresses as required to populate the spend outputs const sendAddresses = await getDestinationAddresses(selection.spendOutputs.length); @@ -702,7 +702,7 @@ export class QiHDWallet extends AbstractHDWallet { finalFee = await this.provider.estimateFeeForQi(feeEstimationTx); // Get new selection with updated fee 2x - selection = fewestCoinSelector.performSelection(spendTarget, finalFee * 3n); + selection = fewestCoinSelector.performSelection({ target: spendTarget, fee: finalFee * 3n }); // Determine if new addresses are needed for the change outputs const changeAddressesNeeded = selection.changeOutputs.length - changeAddresses.length; @@ -862,6 +862,17 @@ export class QiHDWallet extends AbstractHDWallet { return this.prepareAndSendTransaction(amount, originZone, getDestinationAddresses); } + /** + * Prepares a transaction with the specified parameters. + * + * @private + * @param {SelectedCoinsResult} selection - The selected coins result. + * @param {string[]} inputPubKeys - The public keys of the inputs. + * @param {string[]} sendAddresses - The addresses to send to. + * @param {string[]} changeAddresses - The addresses to change to. + * @param {number} chainId - The chain ID. + * @returns {Promise} A promise that resolves to the prepared transaction. + */ private async prepareTransaction( selection: SelectedCoinsResult, inputPubKeys: string[], @@ -895,6 +906,16 @@ export class QiHDWallet extends AbstractHDWallet { return tx; } + /** + * Prepares a fee estimation transaction with the specified parameters. + * + * @private + * @param {SelectedCoinsResult} selection - The selected coins result. + * @param {string[]} inputPubKeys - The public keys of the inputs. + * @param {string[]} sendAddresses - The addresses to send to. + * @param {string[]} changeAddresses - The addresses to change to. + * @returns {QiPerformActionTransaction} The prepared transaction. + */ private prepareFeeEstimationTransaction( selection: SelectedCoinsResult, inputPubKeys: string[],