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 d82afe1a2dcb0f7bf2837dbe9bd39b6bfceac188..62e396f7ebff422a6720a704b7fe0a15a2664294 100644 (file)
--- 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 2b382895268f699fa4a7a43391926b4b31ceab36..50cdbc43839bc5f7a131e6baa1e1840cadf64589 100644 (file)
--- 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 225b574ea446488719c85188b8481c0d10b6e647..5faac68b7707189314a513679b6427b2787ca4c3 100644 (file)
--- 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,