From: merge-script <hello@evanlinjin.me>
Date: Mon, 19 Oct 2026 11:55:18 +0000 (+1100)
Subject: Merge bitcoindevkit/bdk#2350: docs(esplora): explain prevout trust assumptions
X-Git-Url: http://internal-gitweb-vhost/-client-interface/%22https:/bdk/database/struct.Update.html?a=commitdiff_plain;h=HEAD;p=bdk

Merge bitcoindevkit/bdk#2350: docs(esplora): explain prevout trust assumptions

e634a5ab935a3afe9a0a683f79d54989508a16ef docs(esplora): explain prevout trust assumptions (hassan)

Pull request description:

  ### Description

  Refs #2343

  Esplora `sync` and `full_scan` insert server-reported previous outputs into `TxUpdate::txouts` without fetching the parent transactions to verify them. If a parent isn't in the `TxGraph`, fee and sent/received figures rely on these unverified values.

  This adds a "Trust assumptions" section to the `bdk_esplora` README saying so, and links `sync`/`full_scan` (blocking and async) to it. Docs only; no behaviour change.

  ### Changelog notice

  #### Added

  - `bdk_esplora`: document that the previous outputs `sync` and `full_scan` add to `TxUpdate::txouts` are server-reported and unverified (new "Trust assumptions" section in the crate docs). #2350

  ### Checklists

  #### All Submissions:

  * [x] I followed the contribution guidelines

ACKs for top commit:
  evanlinjin:
    ACK e634a5ab935a3afe9a0a683f79d54989508a16ef

Tree-SHA512: d96822f29a0ef012fa1acc272ca91c1fa6979c0182809be45edd45b5c85213e11f3732275411b5d62c6bb9f16f252b1ad535df2a93247262116ac55a39a01c80
---

6860bf7c1cd9f79764f85a8fafc29f236043a4f9
diff --cc crates/esplora/src/async_ext.rs
index 5dd4f031,50cdbc43..f08e8d2e
--- a/crates/esplora/src/async_ext.rs
+++ b/crates/esplora/src/async_ext.rs
@@@ -27,9 -27,11 +27,12 @@@ pub trait EsploraAsyncExt 
      /// `request` provides the data required to perform a script-pubkey-based full scan
      /// (see [`FullScanRequest`]). The full scan for each keychain (`K`) stops after a gap of
      /// `stop_gap` script pubkeys with no associated transactions. `parallel_requests` specifies
 -    /// the maximum number of HTTP requests to make in parallel.
 +    /// the maximum number of HTTP requests to make in parallel. A `parallel_requests` of 0 is
 +    /// treated as 1.
      ///
+     /// Previous outputs in `tx_update.txouts` are server-reported and unverified; see
+     /// [trust assumptions](crate#trust-assumptions).
+     ///
      /// Refer to [crate-level docs](crate) for more.
      async fn full_scan<K: Ord + Clone + Send, R: Into<FullScanRequest<K>> + Send>(
          &self,
@@@ -42,8 -44,11 +45,11 @@@
      ///
      /// `request` provides the data required to perform a script-pubkey-based sync (see
      /// [`SyncRequest`]). `parallel_requests` specifies the maximum number of HTTP requests to make
 -    /// in parallel.
 +    /// in parallel. A `parallel_requests` of 0 is treated as 1.
      ///
+     /// Previous outputs in `tx_update.txouts` are server-reported and unverified; see
+     /// [trust assumptions](crate#trust-assumptions).
+     ///
      /// Refer to [crate-level docs](crate) for more.
      async fn sync<I: Send, R: Into<SyncRequest<I>> + Send>(
          &self,
diff --cc crates/esplora/src/blocking_ext.rs
index 779c6729,5faac68b..0062585c
--- a/crates/esplora/src/blocking_ext.rs
+++ b/crates/esplora/src/blocking_ext.rs
@@@ -24,9 -24,11 +24,12 @@@ pub trait EsploraExt 
      /// `request` provides the data required to perform a script-pubkey-based full scan
      /// (see [`FullScanRequest`]). The full scan for each keychain (`K`) stops after a gap of
      /// `stop_gap` script pubkeys with no associated transactions. `parallel_requests` specifies
 -    /// the maximum number of HTTP requests to make in parallel.
 +    /// the maximum number of HTTP requests to make in parallel. A `parallel_requests` of 0 is
 +    /// treated as 1.
      ///
+     /// Previous outputs in `tx_update.txouts` are server-reported and unverified; see
+     /// [trust assumptions](crate#trust-assumptions).
+     ///
      /// Refer to [crate-level docs](crate) for more.
      fn full_scan<K: Ord + Clone, R: Into<FullScanRequest<K>>>(
          &self,
@@@ -39,8 -41,11 +42,11 @@@
      ///
      /// `request` provides the data required to perform a script-pubkey-based sync (see
      /// [`SyncRequest`]). `parallel_requests` specifies the maximum number of HTTP requests to make
 -    /// in parallel.
 +    /// in parallel. A `parallel_requests` of 0 is treated as 1.
      ///
+     /// Previous outputs in `tx_update.txouts` are server-reported and unverified; see
+     /// [trust assumptions](crate#trust-assumptions).
+     ///
      /// Refer to [crate-level docs](crate) for more.
      fn sync<I: 'static, R: Into<SyncRequest<I>>>(
          &self,