Merge pull request #1 from bitcoinerlab/outputs

V1: Enhance Discovery API Usability and Documentation

Author: landabaso

README.md

@@ -4,7 +4,7 @@ The @bitcoinerlab/discovery library, written in TypeScript, provides a method fo
 
 ## Features
 
-- **Descriptor-Based Data Retrieval:** Retrieves UTXOs, transaction history, and balances for various sources: ranged descriptors, accounts (comprising internal & external descriptors), and addresses (a descriptor specialized for a specific index).
+- **Descriptor-Based Data Retrieval:** Retrieves transaction history for various sources, including: ranged descriptors, accounts (comprising internal & external descriptors), and addresses (a descriptor specialized for a specific index).
 
 - **Transaction Status Filter:** Offers the ability to filter results by `TxStatus`: `ALL` (including transactions in the mempool), `CONFIRMED` (assuming one confirmation) and `IRREVERSIBLE` (for transactions with more than a user-defined number of confirmations).
 
@@ -42,8 +42,7 @@ To get started, follow the steps below:
      host: 'electrum.blockstream.info',
      port: 60002,
      protocol: 'ssl', // 'ssl' and 'tcp' allowed
-     network: networks.testnet // Specify the server's network; defaults to 'mainnet' if not specified
-
+     network: networks.testnet // Specify the server's network; defaults to networks.bitcoin (mainnet)
    });
    ```
 
@@ -52,62 +51,112 @@ To get started, follow the steps below:
     Please refer to the [Explorer documentation](https://github.com/bitcoinerlab/explorer) for more details.
 
 3. **Create the Discovery Class**:
-   After creating the explorer client instance, you can create the `Discovery` class, which you will use to query the Blockchain. The `Discovery` class is created using the `DiscoveryFactory` function, passing the previously created explorer instance.
+   After creating the explorer client instance, you can create the `Discovery` class, which you will use to query the Blockchain. The `Discovery` class is created using the [`DiscoveryFactory` function](https://bitcoinerlab.com/modules/discovery/api/functions/DiscoveryFactory.html), passing the previously created explorer instance.
 
    ```typescript
    import { DiscoveryFactory } from '@bitcoinerlab/discovery';
-   const { Discovery } = DiscoveryFactory(explorer); // where 'explorer' corresponds to
-                                                     // 'esploraExplorer' or 'electrumExplorer' above
+   const { Discovery } = DiscoveryFactory(explorer, network);
+   // where 'explorer' corresponds to 'esploraExplorer' or 'electrumExplorer' above
    await explorer.connect();
    const discovery = new Discovery();
+   // Perform discovery operations...
    await explorer.close();
    ```
 
-   The `Discovery` constructor accepts an optional object with two properties that are crucial for managing the application's memory usage:
+   The [`Discovery` constructor](https://bitcoinerlab.com/modules/discovery/api/classes/_Internal_.Discovery.html#constructor), `new Discovery({ descriptorsCacheSize, outputsPerDescriptorCacheSize })`, accepts an optional object with two properties that are crucial for managing the application's memory usage:
 
-   - `expressionsCacheSize`: This property represents the cache size limit for descriptor expressions. The cache, implemented using memoizers, serves a dual purpose: it speeds up data queries by avoiding unnecessary recomputations, and it helps maintain immutability. Reaching the limit of the cache size may lead to a loss of immutability and the returned reference may change. This is not a critical issue, as the data is still correct, but it may trigger extra renders in the UI. The default value is 1000, and you can set it to 0 for unbounded caches.
-   - `indicesPerExpressionCacheSize`: This property represents the cache size limit for indices per expression, related to the number of addresses in ranged descriptor expressions. Similar to the `expressionsCacheSize`, reaching the limit of this cache size may lead to the same immutability challenges. The default value is 10000, and you can set it to 0 for unbounded caches.
+   - `descriptorsCacheSize`: This property represents the cache size limit for descriptor expressions. The cache, implemented using memoizers, serves a dual purpose: it speeds up data derivation by avoiding unnecessary recomputations, and it helps maintain immutability. Reaching the limit of the cache size may lead to a loss of immutability and the returned reference may change. This is not a critical issue, as the returned data is still correct, but it may trigger extra renders in the UI. The default value is `1000`, and you can set it to `0` for unbounded caches.
+   - `outputsPerDescriptorCacheSize`: This property represents the cache size limit for indices per expression, related to the number of addresses in ranged descriptor expressions. Similar to the `descriptorsCacheSize`, reaching the limit of this cache size may lead to the same immutability challenges. The default value is `10000`, and you can set it to `0` for unbounded caches.
 
-   It is important to note that the default values for `expressionsCacheSize` and `indicesPerExpressionCacheSize` should be sufficient for most projects. However, if you expect to work with a large number of descriptor expressions or addresses, you may need to adjust these values accordingly. Conversely, for projects that require minimal resources, you may consider reducing these values to conserve memory.
+   It's noteworthy that the default settings for `descriptorsCacheSize` and `outputsPerDescriptorCacheSize` are adequate for most use cases. Yet, for projects handling a large volume of descriptor expressions or addresses, increasing these limits may be necessary. On the flip side, if conserving memory is a priority, particularly for projects with minimal resource needs, consider lowering these values.
 
    **Note**: The `connect` method must be run before starting any data queries to the blockchain, and the `close` method should be run after you have completed all necessary queries and no longer need to query the blockchain.
 
+
 4. **Using the Discovery Methods**
-   
-   Once you've instantiated the `Discovery` class, you can leverage its methods to interact with blockchain data.
 
-   For instance, if you want to fetch all the addresses from a ranged descriptor expression, execute:
+   Once you've instantiated the `Discovery` class, you have access to [a variety of methods](https://bitcoinerlab.com/modules/discovery/api/classes/_Internal_.Discovery.html#fetch) to fetch and derive blockchain data from *Bitcoin Output Descriptors*.
 
+   Descriptor expressions are a simple language used to describe collections of Bitcoin output scripts. They enable the `Discovery` class to fetch detailed blockchain information about specific outputs. For more comprehensive insights into descriptor expressions, refer to the [BitcoinerLab descriptors module](https://bitcoinerlab.com/modules/descriptors).
+   
+   To initiate (or update) the data retrieval process for addresses associated with a descriptor, whether ranged or fixed, execute [`fetch`](https://bitcoinerlab.com/modules/discovery/api/classes/_Internal_.Discovery.html#fetch):
+
    ```typescript
-   await discovery.discover({ expressions, network, gapLimit: 3 });
-   const { utxos, balance } = discovery.getUtxos({ expressions, network });
+   await discovery.fetch({ descriptor });
    ```
+   This method retrieves all associated outputs for a given descriptor. If the descriptor is ranged, you can also specify an index to target a specific output within that range. When dealing with multiple descriptors, use the `descriptors` parameter with an array of strings. See the [`fetch` API documentation](https://bitcoinerlab.com/modules/discovery/api/classes/_Internal_.Discovery.html#fetch) for detailed usage.
 
-   In this context, the term `expressions` can be a single string or an array of strings. These expressions represent [descriptor expressions](https://bitcoinerlab.com/modules/descriptors). If an expression is ranged, it will retrieve all the related `scriptPubKeys`. Subsequently, you can obtain the UTXOs and balance for that particular expression using the subsequent line.
-
-   Other beneficial methods include:
+   **Note**: To ensure accurate data computations, fetch descriptor data (using the query above) before employing methods like `getUtxos`, `getBalance`, or others described below. An error will alert you when attempting to derive data from descriptors that have not been previously fetched. This ensures you do not compute data based on incomplete information. If you are unsure whether a descriptor has been previously fetched or need to ensure that the data is up-to-date, use [`whenFetched`](https://bitcoinerlab.com/modules/discovery/api/classes/_Internal_.Discovery.html#whenFetched):
+   
+   ```typescript
+   const fetchStatus = discovery.whenFetched({ descriptor });
+   if (fetchStatus === undefined) {
+     // The descriptor has not been fetched.
+   } else {
+     const secondsSinceFetched = (Date.now() - fetchStatus.timeFetched * 1000) / 1000;
+     if (secondsSinceFetched > SOME_TIME_THRESHOLD) {
+       // The descriptor data is outdated and may need to be fetched again.
+     }
+   }
+   ```
+    
+   If fetch status is verified or known, proceed directly to the data derivation methods:
 
-   - **Getting the Next Index**: 
-     If you're dealing with ranged descriptor expressions and want to determine the next available (unused) index, use:
+   - **Deriving UTXOs**:
+     Use [`getUtxos`](https://bitcoinerlab.com/modules/discovery/api/classes/_Internal_.Discovery.html#getUtxos) to derive all unspent transaction outputs (UTXOs) from the fetched data:
      ```typescript
-     const index = discovery.getNextIndex({ expression, network });
+     const { utxos } = discovery.getUtxos({ descriptor });
      ```
-
-   - **Fetching ScriptPubKeys by UTXO**:
-     This method is essential post-discovery. For a given UTXO, it yields all possible `scriptPubKeys` and related data that can consume the specified UTXO. It's worth noting that this method returns an array since multiple valid descriptor expressions might refer to the same output.
+   
+   - **Calculating Balance**:
+     Use [`getBalance`](https://bitcoinerlab.com/modules/discovery/api/classes/_Internal_.Discovery.html#getBalance) to calculate the total balance from the fetched data:
      ```typescript
-     discovery.getScriptPubKeysByUtxo({ utxo, network });
-     // This yields: Array<{ expression, index, vout, txHex }>
+     const { balance } = discovery.getBalance({ descriptor });
      ```
-     This function is particularly useful when crafting a transaction capable of expending the UTXO, especially when paired with the @bitcoinerlab/descriptors library.
-
-   - **Reviewing Transaction History**:
-     To inspect all transactions associated with a specific descriptor expression (or an array of them), use:
+   
+   Other methods to derive or calculate data include:
+   
+   - **Determining the Next Index**: 
+     For ranged descriptor expressions, determine the next unused index:
+     ```typescript
+     const index = discovery.getNextIndex({ descriptor });
+     ```
+     See the [`getNextIndex` API documentation](https://bitcoinerlab.com/modules/discovery/api/classes/_Internal_.Discovery.html#getNextIndex) for detailed usage.
+   
+   - **Identifying Descriptors by UTXO**:
+     Find the descriptor that corresponds to a specific UTXO using [`getDescriptor`](https://bitcoinerlab.com/modules/discovery/api/classes/_Internal_.Discovery.html#getDescriptor):
+     ```typescript
+     const descriptorData = discovery.getDescriptor({ utxo });
+     // Returns: { descriptor, index? }, with 'index' provided for ranged descriptors.
+     ```
+     This is particularly useful for transaction preparation when you need to instantiate a `new Output({ descriptor })` using the descriptor associated with the UTXO, as facilitated by the [@bitcoinerlab/descriptors](https://bitcoinerlab.com/modules/descriptors) library.
+   
+   - **Accessing Transaction History**:
+     Access all transactions associated with a specific descriptor expression (or an array of them):
+     ```typescript
+     const history = discovery.getHistory({ descriptors });
+     ```
+     Refer to the [`getHistory` API](https://bitcoinerlab.com/modules/discovery/api/classes/_Internal_.Discovery.html#getHistory) for the details.
+   
+   - **Fetching Standard Accounts**:
+     The [`fetchStandardAccounts`](https://bitcoinerlab.com/modules/discovery/api/classes/_Internal_.Discovery.html#fetchStandardAccounts) method is a helper that automates the common task of retrieving or updating standard accounts (pkh, sh(wpkh), wpkh) associated with a master node. This method saves developers time and eliminates repetitive coding tasks.
+   
+     Efficiently retrieve wallet accounts with:
      ```typescript
-     const history = discovery.getHistory({ expressions, network });
+     await discovery.fetchStandardAccounts({
+       masterNode,
+       gapLimit: 20, // The default gap limit
+       onAccountUsed: (account) => {
+         // Optional: Trigger app updates when an account with transactions is found.
+       },
+       onAccountChecking: (account) => {
+         // Optional: Implement app-specific logic when the check for an account begins.
+       }
+     });
      ```
+     Implement the `onAccountUsed` and `onAccountChecking` callbacks as needed for your app's functionality, such as UI updates or logging.
 
-   For a comprehensive rundown of all available methods and their descriptions, please consult [the API documentation](https://bitcoinerlab.com/modules/discovery/api/classes/_Internal_.Discovery.html).
+   The methods listed above are only a part of all the `Discovery` class's functionality. For a complete overview of all available methods and their usage, refer to [the API documentation](https://bitcoinerlab.com/modules/discovery/api/classes/_Internal_.Discovery.html).
 
 ## API Documentation
 

package-lock.json

@@ -2,7 +2,7 @@
   "name": "@bitcoinerlab/discovery",
   "description": "A TypeScript library for retrieving Bitcoin funds from ranged descriptors, leveraging @bitcoinerlab/explorer for standardized access to multiple blockchain explorers.",
   "homepage": "https://github.com/bitcoinerlab/discovery",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "author": "Jose-Luis Landabaso",
   "license": "MIT",
   "prettier": "@bitcoinerlab/configs/prettierConfig.json",
@@ -43,7 +43,7 @@
     "dist"
   ],
   "dependencies": {
-    "@bitcoinerlab/descriptors": "^1.0.2",
+    "@bitcoinerlab/descriptors": "^2.0.1",
     "@bitcoinerlab/explorer": "^0.1.0",
     "@bitcoinerlab/secp256k1": "^1.0.5",
     "@types/memoizee": "^0.4.8",