From: Steve Myers <steve@notmandatory.org>
Date: Wed, 14 Aug 2024 15:17:36 +0000 (-0500)
Subject: Merge bitcoindevkit/bdk#1478: Allow opting out of getting `LocalChain` updates with... 
X-Git-Tag: v1.0.0-beta.2~10
X-Git-Url: http://internal-gitweb-vhost/script/%22https:/struct.EncoderStringWriter.html?a=commitdiff_plain;h=cc84872bdd5dc640dc5946998cf42192d6abb0f6;p=bdk

Merge bitcoindevkit/bdk#1478: Allow opting out of getting `LocalChain` updates with `FullScanRequest`/`SyncRequest` structures

6d77e2e2c3e7c8d49c50bd6b41e7dbc3ddd1d275 refactor(chain)!: Rename `spks_with_labels` to `spks_with_indices` (志宇)
584b10aff153e72777209f540c7bd970b4b4de04 docs(esplora): README example, uncomment async import (志宇)
3eb5dd192669f08fe3d936de2138cc61182fd055 fix(chain): correct `Iterator::size_hint` impl (志宇)
96023c0ff2b47953a2e3d465886421d79d0848f9 docs(chain): improve `SyncRequestBuilder::spks_with_labels` docs (志宇)
0234f706ab39d4f68b6cfcf9d3ff5a49d47ae2d7 docs(esplora): Fix typo (志宇)
38f86fe780d698e81108677edd75b0f88176c12f fix: no premature collect (志宇)
44e2a797e65a501dbd9d803456cb203fe561ee7f feat!: rework `FullScanRequest` and `SyncRequest` (志宇)
16c1c2cf012c3a2d197aa845218df3d1aebad435 docs(esplora): Simplify crate docs (志宇)
c93e6fd3e6289f2c7bc12012eae7231d03cb04cb feat(esplora): always fetch prevouts (志宇)
cad35336269fb2f4279cba39ab077ea5b99b1e59 feat(esplora): make ext traits more flexible (志宇)

Pull request description:

  Closes #1528

  ### Description

  Some users use `bdk_esplora` to update `bdk_chain` structures *without* a `LocalChain`. ~~This PR introduces "low-level" methods to `EsploraExt` and `EsploraAsyncExt` which populates a `TxGraph` update with associated data.~~

  We change `FullScanRequest`/`SyncRequest` to take in the `chain_tip` parameter as an option. Spk-based chain sources (`bdk_electrum` and `bdk_esplora`) will not fetch a chain-update if `chain_tip` is `None`, allowing callers to opt-out of receiving updates for `LocalChain`.

  We change `FullScanRequest`/`SyncRequest` to have better ergonomics when inspecting the progress of syncing (refer to #1528).

  We change `FullScanRequest`/`SyncRequest` to be constructed with a builder pattern. This is a better API since we separate request-construction and request-consumption.

  Additionally, much of the `bdk_esplora` logic has been made more efficient (less calls to Esplora) by utilizing the `/tx/:txid` endpoint (`get_tx_info` method). This method returns the tx and tx_status in one call. The logic for fetching updates for outpoints has been reworked to support parallelism.

  Documentation has also been updated.

  ### Notes to reviewers

  This PR has evolved somewhat. Initially, we were adding more methods on `EsploraExt`/`EsploraAsyncExt` to make syncing/scanning more modular. However, it turns out we can just make the `chain_tip` parameter of the request structures optional. Since we are changing the request structures, we might as well go further and improve the ergonomics of the whole structures (refer to #1528). This is where we are at with this PR.

  Unfortunately, the changes are now breaking. I think this is an okay tradeoff for the API improvements (before we get to stable).

  ### Changelog notice

  * Change request structures in `bdk_chain::spk_client` to be constructed via a builder pattern, make providing a `chain_tip` optional, and have better ergonomics for inspecting progress while syncing.
  * Change `bdk_esplora` to be more efficient by reducing the number of calls via the `/tx/:txid` endpoint. The logic for fetching outpoint updates has been reworked to support parallelism.
  * Change `bdk_esplora` to always add prev-txouts to the `TxGraph` update.

  ### Checklists

  #### All Submissions:

  * [x] I've signed all my commits
  * [x] I followed the [contribution guidelines](https://github.com/bitcoindevkit/bdk/blob/master/CONTRIBUTING.md)
  * [x] I ran `cargo fmt` and `cargo clippy` before committing

  #### New Features:

  * [ ] I've added tests for the new feature
  * [x] I've added docs for the new feature

ACKs for top commit:
  ValuedMammal:
    ACK 6d77e2e2c3e7c8d49c50bd6b41e7dbc3ddd1d275
  notmandatory:
    ACK 6d77e2e2c3e7c8d49c50bd6b41e7dbc3ddd1d275

Tree-SHA512: 806cb159a8801f4e33846d18e6053b65d105e452b0f3f9d639b0c3f2e48fb665e632898bf42977901526834587223b0d7ec7ba1f73bb796b5fd8fe91e6f287f7
---

cc84872bdd5dc640dc5946998cf42192d6abb0f6