From: hassan <144530465+h55n@users.noreply.github.com>
Date: Thu, 8 Oct 2026 07:31:37 +0000 (+0530)
Subject: docs(esplora): explain prevout trust assumptions
X-Git-Url: http://internal-gitweb-vhost/-script/src/example_cli/database/struct.DerivedDescriptorKey.html?a=commitdiff_plain;h=e634a5ab935a3afe9a0a683f79d54989508a16ef;p=bdk

docs(esplora): explain prevout trust assumptions

Refs #2343

Signed-off-by: Hassan Rehman <144530465+h55n@users.noreply.github.com>
---

diff --git a/crates/esplora/README.md b/crates/esplora/README.md
index d82afe1a..62e396f7 100644
--- a/crates/esplora/README.md
+++ b/crates/esplora/README.md
@@ -6,6 +6,19 @@ BDK Esplora extends [`esplora-client`] (with extension traits: [`EsploraExt`] an
 The extension traits are primarily intended to satisfy [`SyncRequest`]s with [`sync`] and
 [`FullScanRequest`]s with [`full_scan`].
 
+## Trust assumptions
+
+The Esplora server is trusted: it can hide transactions or misreport confirmations.
+
+Esplora also reports each input's previous output (value and script). `sync` and `full_scan`
+insert these into `TxUpdate::txouts` as floating txouts without fetching the parent
+transactions to verify them.
+
+If a parent transaction is not in your `TxGraph`, fee and sent/received calculations
+rely on these unverified values. This includes inputs owned by other parties, such as
+in payjoin or coinjoin transactions. Use a trusted Esplora server, or fetch and verify
+the parent transactions before relying on these figures.
+
 ## Usage
 
 For blocking-only:
diff --git a/crates/esplora/src/async_ext.rs b/crates/esplora/src/async_ext.rs
index 2b382895..50cdbc43 100644
--- a/crates/esplora/src/async_ext.rs
+++ b/crates/esplora/src/async_ext.rs
@@ -29,6 +29,9 @@ pub trait EsploraAsyncExt {
     /// `stop_gap` script pubkeys with no associated transactions. `parallel_requests` specifies
     /// the maximum number of HTTP requests to make in parallel.
     ///
+    /// 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,
@@ -43,6 +46,9 @@ pub trait EsploraAsyncExt {
     /// [`SyncRequest`]). `parallel_requests` specifies the maximum number of HTTP requests to make
     /// in parallel.
     ///
+    /// 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 --git a/crates/esplora/src/blocking_ext.rs b/crates/esplora/src/blocking_ext.rs
index 225b574e..5faac68b 100644
--- a/crates/esplora/src/blocking_ext.rs
+++ b/crates/esplora/src/blocking_ext.rs
@@ -26,6 +26,9 @@ pub trait EsploraExt {
     /// `stop_gap` script pubkeys with no associated transactions. `parallel_requests` specifies
     /// the maximum number of HTTP requests to make in parallel.
     ///
+    /// 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,
@@ -40,6 +43,9 @@ pub trait EsploraExt {
     /// [`SyncRequest`]). `parallel_requests` specifies the maximum number of HTTP requests to make
     /// in parallel.
     ///
+    /// 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,