9737955023

Committed 01 Jul 2024 04:01AM UTC coverage: 83.182% (+0.2%) from 83.029%

Build # 9737955023

Build Type

Pull #1478

github

Committed by

web-flow

Commit Message

Merge d05135804 into 22368ab7b

Pull Request Pull Request #1478: Make `bdk_esplora` more modular

Run Details

358 of 422 new or added lines in 2 files covered. (84.83%)

213 existing lines in 7 files now uncovered.

11148 of 13402 relevant lines covered (83.18%)

16721.16 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

91.67

/crates/esplora/src/lib.rs

#![doc = include_str!("../README.md")]

//! # Primary Methods
//!
//! The two primary methods are [`EsploraExt::sync`] and [`EsploraExt::full_scan`].
//!
//! [`EsploraExt::sync`] is used to sync against a subset of wallet data. For example, transaction
//! histories of revealed and unused script from the external (public) keychain and/or statuses of
//! wallet-owned UTXOs and spending transactions from them. The policy of what to sync against can
//! be customized.
//!
//! [`EsploraExt::full_scan`] is designed to be used when importing or restoring a keychain where
//! the range of possibly used scripts is not known. In this case it is necessary to scan all
//! keychain scripts until a number (the `stop_gap`) of unused scripts is discovered.
//!
//! For a sync or full scan, the user receives relevant blockchain data and output updates for
//! [`bdk_chain`] .
//!
//! # Low-Level Methods
//!
//! [`EsploraExt::sync`] and [`EsploraExt::full_scan`] returns updates which are *complete* and can
//! be used directly to determine confirmation statuses of each transaction. This is because a
//! [`LocalChain`] update is contained in the returned update structures. However, sometimes the
//! caller wishes to use a custom [`ChainOracle`] implementation (something other than
//! [`LocalChain`]). The following methods ONLY populates an update [`TxGraph`]:
//!
//! * [`EsploraExt::populate_using_keychain_spks`]
//! * [`EsploraExt::populate_using_spks`]
//! * [`EsploraExt::populate_using_txids`]
//! * [`EsploraExt::populate_using_outpoints`]
//!
//! # Stop Gap
//!
//! Methods [`EsploraExt::full_scan`] and [`EsploraExt::populate_using_keychain_spks`] takes in a
//! `stop_gap` input which is defined as the maximum number of consecutive unused script pubkeys to
//! scan transactions for before stopping.
//!
//! For example, with a `stop_gap` of 3, `full_scan` will keep scanning until it encounters 3
//! consecutive script pubkeys with no associated transactions.
//!
//! This follows the same approach as other Bitcoin-related software,
//! such as [Electrum](https://electrum.readthedocs.io/en/latest/faq.html#what-is-the-gap-limit),
//! [BTCPay Server](https://docs.btcpayserver.org/FAQ/Wallet/#the-gap-limit-problem),
//! and [Sparrow](https://www.sparrowwallet.com/docs/faq.html#ive-restored-my-wallet-but-some-of-my-funds-are-missing).
//!
//! A `stop_gap` of 0 will be treated as a `stop_gap` of 1.
//!
//! # Async
//!
//! Just like how [`EsploraExt`] extends the functionality of an
//! [`esplora_client::BlockingClient`], [`EsploraExt`] is the async version which extends
//! [`esplora_client::AsyncClient`].
//!
//! [`TxGraph`]: bdk_chain::tx_graph::TxGraph
//! [`LocalChain`]: bdk_chain::local_chain::LocalChain
//! [`ChainOracle`]: bdk_chain::ChainOracle
//! [`example_esplora`]: https://github.com/bitcoindevkit/bdk/tree/master/example-crates/example_esplora

use bdk_chain::{BlockId, ConfirmationTimeHeightAnchor};
use esplora_client::TxStatus;

pub use esplora_client;

#[cfg(feature = "blocking")]
mod blocking_ext;
#[cfg(feature = "blocking")]
pub use blocking_ext::*;

#[cfg(feature = "async")]
mod async_ext;
#[cfg(feature = "async")]
pub use async_ext::*;

fn anchor_from_status(status: &TxStatus) -> Option<ConfirmationTimeHeightAnchor> {
    if let TxStatus {
        block_height: Some(height),
        block_hash: Some(hash),
        block_time: Some(time),
        ..
    } = status.clone()
    {
        Some(ConfirmationTimeHeightAnchor {
            anchor_block: BlockId { height, hash },
            confirmation_height: height,
            confirmation_time: time,
        })
    } else {
        None
    }
}

1	#![doc = include_str!("../README.md")]
2
3	//! # Primary Methods
4	//!
5	//! The two primary methods are [`EsploraExt::sync`] and [`EsploraExt::full_scan`].
6	//!
7	//! [`EsploraExt::sync`] is used to sync against a subset of wallet data. For example, transaction
8	//! histories of revealed and unused script from the external (public) keychain and/or statuses of
9	//! wallet-owned UTXOs and spending transactions from them. The policy of what to sync against can
10	//! be customized.
11	//!
12	//! [`EsploraExt::full_scan`] is designed to be used when importing or restoring a keychain where
13	//! the range of possibly used scripts is not known. In this case it is necessary to scan all
14	//! keychain scripts until a number (the `stop_gap`) of unused scripts is discovered.
15	//!
16	//! For a sync or full scan, the user receives relevant blockchain data and output updates for
17	//! [`bdk_chain`] .
18	//!
19	//! # Low-Level Methods
20	//!
21	//! [`EsploraExt::sync`] and [`EsploraExt::full_scan`] returns updates which are complete and can
22	//! be used directly to determine confirmation statuses of each transaction. This is because a
23	//! [`LocalChain`] update is contained in the returned update structures. However, sometimes the
24	//! caller wishes to use a custom [`ChainOracle`] implementation (something other than
25	//! [`LocalChain`]). The following methods ONLY populates an update [`TxGraph`]:
26	//!
27	//! * [`EsploraExt::populate_using_keychain_spks`]
28	//! * [`EsploraExt::populate_using_spks`]
29	//! * [`EsploraExt::populate_using_txids`]
30	//! * [`EsploraExt::populate_using_outpoints`]
31	//!
32	//! # Stop Gap
33	//!
34	//! Methods [`EsploraExt::full_scan`] and [`EsploraExt::populate_using_keychain_spks`] takes in a
35	//! `stop_gap` input which is defined as the maximum number of consecutive unused script pubkeys to
36	//! scan transactions for before stopping.
37	//!
38	//! For example, with a `stop_gap` of 3, `full_scan` will keep scanning until it encounters 3
39	//! consecutive script pubkeys with no associated transactions.
40	//!
41	//! This follows the same approach as other Bitcoin-related software,
42	//! such as [Electrum](https://electrum.readthedocs.io/en/latest/faq.html#what-is-the-gap-limit),
43	//! [BTCPay Server](https://docs.btcpayserver.org/FAQ/Wallet/#the-gap-limit-problem),
44	//! and [Sparrow](https://www.sparrowwallet.com/docs/faq.html#ive-restored-my-wallet-but-some-of-my-funds-are-missing).
45	//!
46	//! A `stop_gap` of 0 will be treated as a `stop_gap` of 1.
47	//!
48	//! # Async
49	//!
50	//! Just like how [`EsploraExt`] extends the functionality of an
51	//! [`esplora_client::BlockingClient`], [`EsploraExt`] is the async version which extends
52	//! [`esplora_client::AsyncClient`].
53	//!
54	//! [`TxGraph`]: bdk_chain::tx_graph::TxGraph
55	//! [`LocalChain`]: bdk_chain::local_chain::LocalChain
56	//! [`ChainOracle`]: bdk_chain::ChainOracle
57	//! [`example_esplora`]: https://github.com/bitcoindevkit/bdk/tree/master/example-crates/example_esplora
58
59	use bdk_chain::{BlockId, ConfirmationTimeHeightAnchor};
60	use esplora_client::TxStatus;
61
62	pub use esplora_client;
63
64	#[cfg(feature = "blocking")]
65	mod blocking_ext;
66	#[cfg(feature = "blocking")]
67	pub use blocking_ext::*;
68
69	#[cfg(feature = "async")]
70	mod async_ext;
71	#[cfg(feature = "async")]
72	pub use async_ext::*;
73
74	fn anchor_from_status(status: &TxStatus) -> Option<ConfirmationTimeHeightAnchor> {	24✔
75	if let TxStatus {
76	block_height: Some(height),	24✔
77	block_hash: Some(hash),	24✔
78	block_time: Some(time),	24✔
79	..
80	} = status.clone()	24✔
81	{
82	Some(ConfirmationTimeHeightAnchor {	24✔
83	anchor_block: BlockId { height, hash },	24✔
84	confirmation_height: height,	24✔
85	confirmation_time: time,	24✔
86	})	24✔
87	} else {
UNCOV 88	None	×
89	}
90	}	24✔

bitcoindevkit / bdk / 9737955023

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous