Class Discovery

Constructs a Discovery instance. Discovery is used to discover funds in a Bitcoin network using descriptors.

Asynchronously fetches one or more descriptor expressions, retrieving all the historical txs associated with the outputs represented by the expressions.

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).

Asynchronously discovers standard accounts (pkh, sh(wpkh), wpkh) associated with a master node. It uses a given gap limit for discovery.

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.

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.

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.

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.

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.

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.

Retrieves the hexadecimal representation of a transaction (TxHex) from the discoveryData given the transaction ID (TxId) or a Unspent Transaction Output (Utxo)

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.

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.

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.

Pushes a transaction to the network and updates the internal state.

This function first broadcasts the transaction using the configured explorer. It then attempts to update the internal discoveryData by calling addTransaction.

If addTransaction reports that one or more inputs of the pushed transaction were already considered spent by other transactions in the library's records (e.g., in an RBF scenario or a double-spend attempt already known to the library), push will automatically attempt to synchronize the state. It does this by calling fetch on all unique descriptors associated with the conflicting input(s). This helps ensure the library's state reflects the most current information from the blockchain/mempool regarding these conflicts.

The gapLimit parameter is used both when addTransaction is called and during any subsequent automatic fetch operation triggered by conflicts. It helps discover new outputs (e.g., change addresses) that might become active due to the transaction.

Note: The success of broadcasting the transaction via explorer.push(txHex) depends on the network and node policies. Even if broadcast is successful, the transaction might not be immediately visible in the mempool or might be replaced. A warning is logged if the transaction is not found in the mempool shortly after being pushed. The final state in the library will reflect the outcome of the internal addTransaction call and any automatic synchronization that occurred.

Given a transaction it updates the internal discoveryData state to include it.

This function is useful when a transaction affecting one of the descriptors has been pushed to the blockchain by a third party. It allows updating the internal representation without performing a more expensive fetch operation.

If the transaction was recently pushed to the blockchain, set txData.irreversible = false and txData.blockHeight = 0.

The transaction is represented by txData, where txData = { blockHeight: number; irreversible: boolean; txHex: TxHex; }.

It includes its hexadecimal representation txHex, its blockHeight (zero if it's in the mempool), and whether it is irreversible or not. irreversible is set by the Explorer, using the configuration parameter irrevConfThresh (defaults to IRREV_CONF_THRESH = 3). It can be obtained by calling explorer.fetchTxHistory(), for example. Set it to false when it's been just pushed (which will be the typical use of this function).

The gapLimit parameter is essential for managing descriptor discovery. When addint a transaction, there is a possibility the transaction is adding new funds as change (for example). 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.

This function updates the internal discoveryData state to include the provided transaction, but only if it doesn't attempt to spend outputs already considered spent by the library.

It first checks all inputs of the transaction. If any input corresponds to a txo (a previously known output) that is not a current utxo (i.e., it's already considered spent by another transaction in the library's records), this function will not modify the library state. Instead, it will return an object detailing all such conflicting inputs. This allows the caller (e.g., the push method) to handle these conflicts, for instance, by re-fetching the state of all affected descriptors.

If no such input conflicts are found, the transaction is processed: its details are added to the txMap, and relevant txIds are associated with the OutputData of both its inputs (if owned) and outputs (if owned).

For other types of errors (e.g., invalid input data), it may still throw.

Refer to the push method's documentation for how it utilizes this return status for automatic state synchronization.

Retrieves the Explorer instance.

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.