Constructs a Discovery instance. Discovery is used to discover funds in a Bitcoin network using descriptors.
Optional descriptorsCache 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
Optional outputsCache 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
Optional imported?: { Optional parameter used to initialize the Discovery instance with
previously exported data with
export(). This allows for the
continuation of a previous discovery process. The imported object
should contain discoveryData and a version string. The
discoveryData is deeply cloned upon import to ensure that the
internal state of the Discovery instance is isolated from
external changes. The version is used to verify that the imported
data model is compatible with the current version of the Discovery
class.
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.
Compares two transactions based on their blockHeight and input dependencies. Can be used as callback in Array.sort function to sort from old to new.
The first transaction data to compare.
The second transaction data to compare.
txWithOrderA and txWithOrderB should contain the blockHeight (use 0 if
in the mempool) and either tx (Transaction type) or txHex (the
hexadecimal representation of the transaction)
< 0 if txWithOrderA is older than txWithOrderB, > 01 if txWithOrderA is newer than txWithOrderB, and 0 if undecided.
Private #discoveryPrivate #getPrivate Finds the descriptor (and index) that corresponds to the scriptPubKey passed as argument.
Network to check.
The scriptPubKey to check for uniqueness.
Optional gapWhen the descriptor is ranged, it will keep searching for the scriptPubKey to non-set indices above the last one set until reaching the gapLimit. If you only need to get one of the existing already-fetched descriptors, leave gapLimit to zero.
Private #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. In addition it also retrieves spent transaction outputs (STXOS) which correspond to previous UTXOs that have been spent.
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.
It also returns previous UTXOs that had been
eventually spent as stxos: ArraytxoMap. txoMap maps all the txos (unspent or spent
outputs) with their corresponding indexedDescriptor: IndexedDescriptor
(see IndexedDescriptor)
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 accesses transaction records associated with descriptor expressions and transaction status.
When withAttributions is false, it returns an array of historical transactions
(Array<TxData>). See TxData.
To determine if each transaction corresponds to a sent/received transaction, set
withAttributions to true.
When withAttributions is true, this function returns an array of
TxAttribution elements.
TxAttribution identifies the owner of the previous output for each input and
the owner of the output for each transaction.
This is useful in wallet applications to specify whether inputs are from owned outputs (e.g., change from a previous transaction) or from third parties. It also specifies if outputs are destined to third parties or are internal change. This helps wallet apps show transaction history with "Sent" or "Received" labels, considering only transactions with third parties.
See TxAttribution for a complete list of items returned per transaction.
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.
Criteria for selecting transaction outputs, including descriptor expressions, transaction status, and whether to include attributions.
Whether to include attributions in the returned data.
An array containing transaction information 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) or the hexadecimal representation of the transaction (it will then use memoization). The transaction data is obtained by first getting the transaction hexadecimal representation using getTxHex() method (unless the txHex was passed).
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 txThe transaction txHex.
Optional utxo?: stringThe UTXO.
The transaction data as a Transaction object.
Compares two transactions based on their blockHeight and input dependencies. Can be used as callback in Array.sort function to sort from old to new.
The first transaction data to compare.
The second transaction data to compare.
txWithOrderA and txWithOrderB should contain the blockHeight (use 0 if
in the mempool) and either tx (Transaction type) or txHex (the
hexadecimal representation of the transaction)
< 0 if txWithOrderA is older than txWithOrderB, > 0 if txWithOrderA is newer than txWithOrderB, and 0 if undecided.
Given an unspent tx output, this function retrieves its descriptor (if still unspent).
Alternatively, pass a txo (any transaction output, which may have been
spent already or not) and this function will also retrieve its descriptor.
txo can be in any of these formats: ${txId}:${vout} or
using its extended form: ${txId}:${vout}:${recipientTxId}:${recipientVin}
Returns the descriptor (and index if ranged) or undefined if not found.
Optional utxo?: stringThe UTXO.
Optional txo?: stringPushes a transaction to the network and updates the internal state
accordingly. This function ensures that the transaction is pushed,
verifies its presence in the mempool, and updates the internal
discoveryData to include the new transaction.
The gapLimit parameter is essential for managing descriptor discovery.
When pushing a transaction, there is a possibility of receiving new funds
as change. If the range for that index does not exist yet, the gapLimit
helps to update the descriptor corresponding to a new UTXO for new
indices within the gap limit.
The hexadecimal representation of the transaction to push.
Optional gapThe gap limit for descriptor discovery. Defaults to 20.
Exports the current state of the Discovery instance.
This method is used to serialize the state of the Discovery instance so
that it can be saved and potentially re-imported later using the
imported parameter in the constructor.
The exported data includes a version string and a deep clone of the internal discovery data. The deep cloning process ensures that the exported data is a snapshot of the internal state, isolated from future changes to the Discovery instance. This isolation maintains the integrity and immutability of the exported data.
The inclusion of a version string in the exported data allows for compatibility checks when re-importing the data. This check ensures that the data model of the imported data is compatible with the current version of the Discovery class.
The exported data is guaranteed to be serializable, allowing it to be safely stored or transmitted. It can be serialized using JSON.stringify or other serialization methods, such as structured serialization (https://html.spec.whatwg.org/multipage/structured-data.html#structuredserializeinternal). This feature ensures that the data can be serialized and deserialized without loss of integrity, facilitating data persistence and transfer across different sessions or environments.
An object containing the version string and the serialized discovery data.
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.