Constructs a Discovery instance. Discovery is used to discover funds in a Bitcoin network using descriptors.
Cache size limit for descriptor expressions. The cache is used to speed up data queries by avoiding unnecessary recomputations. However, it is essential to manage the memory usage of the application. If the cache size is unbounded, it could lead to excessive memory usage and degrade the application's performance, especially when dealing with a large number of descriptor expressions. On the other hand, a very small cache size may lead to more frequent cache evictions, causing the library to return a different reference for the same data when the same method is called multiple times, even if the underlying data has not changed. This is contrary to the immutability principles that the library is built upon. Ultimately, this limit acts as a trade-off between memory usage, computational efficiency, and immutability. Set to 0 for unbounded caches.
1000
Cache size limit for outputs per descriptor, related to the number of outputs
in ranged descriptor expressions. Similar to the descriptorsCacheSize,
this cache is used to speed up data queries and avoid recomputations.
As each descriptor can have multiple indices (if ranged), the number of outputs can grow rapidly,
leading to increased memory usage. Setting a limit helps keep memory usage in check,
while also maintaining the benefits of immutability and computational efficiency.
Set to 0 for unbounded caches.
10000
Private #deriversExtracts and returns descriptor expressions that are associated with at least one utilized scriptPubKey from the discovery information. The function is optimized to maintain and return the same array object for each unique networkId if the resulting expressions did not change. This helps to avoid unnecessary data processing and memory usage.
The network identifier.
Descriptor expressions.
Descriptor expressions.
Private #discoveryPrivate #ensurePrivate Ensures that a scriptPubKey is unique and has not already been set by a different descriptor. This prevents accounting for duplicate unspent transaction outputs (utxos) and balances when different descriptors could represent the same scriptPubKey (e.g., xpub vs wif).
If the scriptPubKey is not unique.
Private #fetchAsynchronously discovers an output, given a descriptor expression and index. It first retrieves the output, computes its scriptHash, and fetches the transaction history associated with this scriptHash from the explorer. It then updates the internal discoveryData accordingly.
This function has side-effects as it modifies the internal discoveryData state of the Discovery class instance. This state keeps track of transaction info and descriptors relevant to the discovery process.
This method is useful for updating the state based on new transactions and output.
This method does not retrieve the txHex associated with the Output. An additional #fetchTxs must be performed.
The descriptor expression associated with the scriptPubKey to discover.
Optional index?: numberThe descriptor index associated with the scriptPubKey to discover (if ranged).
A promise that resolves to a boolean indicating whether any transactions were found for the provided scriptPubKey.
Private #fetchAsynchronously fetches one or more descriptor expressions, retrieving all the historical txs associated with the outputs represented by the expressions.
Optional descriptor?: stringDescriptor expression representing one or potentially multiple outputs
if ranged.
Use either descriptor or descriptors, but not both simultaneously.
Optional index?: numberAn optional index associated with a ranged descriptor. Not applicable
when using the descriptors array, even if its elements are ranged.
Optional descriptors?: string[]Array of descriptor expressions. Use either descriptors or descriptor,
but not both simultaneously.
Optional gapThe gap limit for the fetch operation when retrieving ranged descriptors.
20
Optional onOptional callback function triggered once a descriptor's output has been identified as previously used in a transaction. It provides a way to react or perform side effects based on this finding.
The original descriptor or array of descriptors that have been determined to have a used output.
Optional onOptional callback function invoked at the beginning of checking a descriptor to determine its usage status. This can be used to signal the start of a descriptor's check, potentially for logging or UI updates.
The descriptor or array of descriptors being checked.
Optional next?: (() => Promise<void>)Optional function triggered immediately after detecting that a descriptor's output
has been used previously. By invoking this function, it's possible to initiate
parallel discovery processes. The primary discover method will only resolve
once both its main discovery process and any supplementary processes initiated
by next have completed. Essentially, it ensures that all discovery,
both primary and secondary, finishes before moving on.
Resolves when the fetch operation completes. If used expressions are found, waits for the discovery of associated transactions.
Retrieves the fetching status and the timestamp of the last fetch for a descriptor.
Use this function to check if the data for a specific descriptor, or an index within a ranged descriptor, is currently being fetched or has been fetched.
This function also helps to avoid errors when attempting to derive data from descriptors with incomplete data,
ensuring that subsequent calls to data derivation methods such as getUtxos or
getBalance only occur once the necessary data has been successfully retrieved (and does not return undefined).
Descriptor expression representing one or potentially multiple outputs if ranged.
Optional index?: numberAn optional index associated with a ranged descriptor.
An object with the fetching status (fetching) and the last
fetch time (timeFetched), or undefined if never fetched.
Private #ensureMakes sure that data was retrieved before trying to derive from it
Optional descriptor?: stringDescriptor expression representing one or potentially multiple outputs
if ranged.
Use either descriptor or descriptors, but not both simultaneously.
Optional index?: numberAn optional index associated with a ranged descriptor. Not applicable
when using the descriptors array, even if its elements are ranged.
Optional descriptors?: string[]Array of descriptor expressions. Use either descriptors or descriptor,
but not both simultaneously.
Asynchronously discovers standard accounts (pkh, sh(wpkh), wpkh) associated with a master node. It uses a given gap limit for discovery.
The master node to discover accounts from.
Optional gapThe gap limit for address discovery
20
Optional onOptional callback function triggered when an account
(associated with the master node) has been identified as having past
transactions. It's called with the external descriptor
of the account (keyPath = /0/*) that is active.
The external descriptor of the account that has been determined to have prior transaction activity.
Optional onOptional callback function invoked just as the system starts to evaluate the transaction activity of an account (associated with the master node). Useful for signaling the initiation of the discovery process for a particular account, often for UI updates or logging purposes.
The external descriptor of the account that is currently being evaluated for transaction activity.
Resolves when all the standrd accounts from the master node have been discovered.
Retrieves the array of descriptors with used outputs. The result is cached based on the size specified in the constructor. As long as this cache size is not exceeded, this function will maintain the same object reference if the returned array hasn't changed. This characteristic can be particularly beneficial in React and similar projects, where re-rendering occurs based on reference changes.
Returns an array of descriptor expressions. These are derived from the discovery information.
Retrieves all the accounts with used outputs:
those descriptors with keyPaths ending in {/0/*, /1/*}. An account is identified
by its external descriptor keyPath = /0/*. The result is cached based on
the size specified in the constructor. As long as this cache size is not
exceeded, this function will maintain the same object reference if the returned array remains unchanged.
This characteristic can be especially beneficial in
React or similar projects, where re-rendering occurs based on reference changes.
An array of accounts, each represented as its external descriptor expression.
Retrieves descriptor expressions associated with a specific account. The result is cached based on the size specified in the constructor. As long as this cache size is not exceeded, this function will maintain the same object reference. This characteristic can be especially beneficial in React or similar projects, where re-rendering occurs based on reference changes.
The account associated with the descriptors.
An array of descriptor expressions associated with the specified account.
Retrieves unspent transaction outputs (UTXOs) and balance associated with one or more descriptor expressions and transaction status.
This method is useful for accessing the available funds for specific descriptor expressions in the wallet, considering the transaction status (confirmed, unconfirmed, or both).
The return value is computed based on the current state of discoveryData. The method uses memoization to maintain the same object reference for the returned result, given the same input parameters, as long as the corresponding UTXOs in discoveryData haven't changed. This can be useful in environments such as React where preserving object identity can prevent unnecessary re-renders.
An object containing the UTXOs associated with the scriptPubKeys and the total balance of these UTXOs.
Convenience function which internally invokes the
getUtxosAndBalance(options).balance method.
Convenience function which internally invokes the
getUtxosAndBalance(options).utxos method.
Retrieves the next available index for a given descriptor.
The method retrieves the currently highest index used, and returns the next available index by incrementing it by 1.
The ranged descriptor expression for which to retrieve the next available index.
Optional txA scriptPubKey will be considered as used when its transaction status is txStatus extracting UTXOs and balance.
TxStatus.ALL
The next available index.
Retrieves the transaction history for one or more descriptor expressions.
This method is useful for accessing transaction records associated with one or more descriptor expressions and transaction status.
The return value is computed based on the current state of discoveryData. The method uses memoization to maintain the same object reference for the returned result, given the same input parameters, as long as the corresponding transaction records in discoveryData haven't changed.
This can be useful in environments such as React where preserving object identity can prevent unnecessary re-renders.
An array containing transaction info associated with the descriptor expressions.
Retrieves the hexadecimal representation of a transaction (TxHex) from the discoveryData given the transaction ID (TxId) or a Unspent Transaction Output (Utxo)
Optional txThe transaction ID.
Optional utxo?: stringThe UTXO.
The hexadecimal representation of the transaction.
Will throw an error if the transaction ID is invalid or if the TxHex is not found.
Retrieves the transaction data as a bitcoinjs-lib Transaction object given the transaction ID (TxId) or a Unspent Transaction Output (Utxo). The transaction data is obtained by first getting the transaction hexadecimal representation using getTxHex() method.
Use this method for quick access to the Transaction object, which avoids the need to parse the transaction hexadecimal representation (txHex). The data will have already been computed and cached for efficiency within the Discovery class.
Optional txThe transaction ID.
Optional utxo?: stringThe UTXO.
The transaction data as a Transaction object.
A class to discover funds in a Bitcoin network using descriptors. The
DiscoveryFactoryfunction internally creates and returns an instance of this class. The returned class is specialized for the providedExplorer, which is responsible for fetching blockchain data like transaction details.