8968819480

Committed 06 May 2024 12:09PM CUT coverage: 82.273%. Remained the same

Build # 8968819480

Build Type

push

github

Committed by

evanlinjin

Commit Message

Merge bitcoindevkit/bdk#1427: docs(esplora): fixed `full_scan` and `sync` documentation

<a class=hub.com/bitcoindevkit/bdk/commit/<a class="double-link" href="https://git"><a class=hub.com/bitcoindevkit/bdk/commit/f6dc6890c37752e80c86c68ae3ca3cc4fac6245e">f6dc6890c docs(esplora): fixed `full_scan` and `sync` documentation (Wei Chen)

Pull request description:

  <!-- You can erase any parts of this template not applicable to your Pull Request. -->

  ### Description

  Fixed documentation for `full_scan` and `sync` in `bdk_esplora`.

  ### Changelog notice

  <!-- Notice the release manager should include in the release tag message changelog -->
  <!-- See https://keepachangelog.com/en/1.0.0/ for examples -->
  * Updated documentation for `full_scan` and `sync` in `bdk_esplora`.

  ### 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

ACKs for top commit:
  evanlinjin:
    ACK f6dc6890c37752e80c86c68ae3ca3cc4fac6245e
  storopoli:
    ACK f6dc6890c37752e80c86c68ae3ca3cc4fac6245e

Tree-SHA512: 900fb1a280a72ee1e13c5c70a136b93f332

Run Details

10396 of 12636 relevant lines covered (82.27%)

17655.35 hits per line

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

58.82

/crates/chain/src/tx_data_traits.rs

use crate::collections::BTreeMap;
use crate::collections::BTreeSet;
use crate::BlockId;
use alloc::vec::Vec;

/// Trait that "anchors" blockchain data to a specific block of height and hash.
///
/// If transaction A is anchored in block B, and block B is in the best chain, we can
/// assume that transaction A is also confirmed in the best chain. This does not necessarily mean
/// that transaction A is confirmed in block B. It could also mean transaction A is confirmed in a
/// parent block of B.
///
/// Every [`Anchor`] implementation must contain a [`BlockId`] parameter, and must implement
/// [`Ord`]. When implementing [`Ord`], the anchors' [`BlockId`]s should take precedence
/// over other elements inside the [`Anchor`]s for comparison purposes, i.e., you should first
/// compare the anchors' [`BlockId`]s and then care about the rest.
///
/// The example shows different types of anchors:
/// ```
/// # use bdk_chain::local_chain::LocalChain;
/// # use bdk_chain::tx_graph::TxGraph;
/// # use bdk_chain::BlockId;
/// # use bdk_chain::ConfirmationHeightAnchor;
/// # use bdk_chain::ConfirmationTimeHeightAnchor;
/// # use bdk_chain::example_utils::*;
/// # use bitcoin::hashes::Hash;
/// // Initialize the local chain with two blocks.
/// let chain = LocalChain::from_blocks(
///     [
///         (1, Hash::hash("first".as_bytes())),
///         (2, Hash::hash("second".as_bytes())),
///     ]
///     .into_iter()
///     .collect(),
/// );
///
/// // Transaction to be inserted into `TxGraph`s with different anchor types.
/// let tx = tx_from_hex(RAW_TX_1);
///
/// // Insert `tx` into a `TxGraph` that uses `BlockId` as the anchor type.
/// // When a transaction is anchored with `BlockId`, the anchor block and the confirmation block of
/// // the transaction is the same block.
/// let mut graph_a = TxGraph::<BlockId>::default();
/// let _ = graph_a.insert_tx(tx.clone());
/// graph_a.insert_anchor(
///     tx.txid(),
///     BlockId {
///         height: 1,
///         hash: Hash::hash("first".as_bytes()),
///     },
/// );
///
/// // Insert `tx` into a `TxGraph` that uses `ConfirmationHeightAnchor` as the anchor type.
/// // This anchor records the anchor block and the confirmation height of the transaction.
/// // When a transaction is anchored with `ConfirmationHeightAnchor`, the anchor block and
/// // confirmation block can be different. However, the confirmation block cannot be higher than
/// // the anchor block and both blocks must be in the same chain for the anchor to be valid.
/// let mut graph_b = TxGraph::<ConfirmationHeightAnchor>::default();
/// let _ = graph_b.insert_tx(tx.clone());
/// graph_b.insert_anchor(
///     tx.txid(),
///     ConfirmationHeightAnchor {
///         anchor_block: BlockId {
///             height: 2,
///             hash: Hash::hash("second".as_bytes()),
///         },
///         confirmation_height: 1,
///     },
/// );
///
/// // Insert `tx` into a `TxGraph` that uses `ConfirmationTimeHeightAnchor` as the anchor type.
/// // This anchor records the anchor block, the confirmation height and time of the transaction.
/// // When a transaction is anchored with `ConfirmationTimeHeightAnchor`, the anchor block and
/// // confirmation block can be different. However, the confirmation block cannot be higher than
/// // the anchor block and both blocks must be in the same chain for the anchor to be valid.
/// let mut graph_c = TxGraph::<ConfirmationTimeHeightAnchor>::default();
/// let _ = graph_c.insert_tx(tx.clone());
/// graph_c.insert_anchor(
///     tx.txid(),
///     ConfirmationTimeHeightAnchor {
///         anchor_block: BlockId {
///             height: 2,
///             hash: Hash::hash("third".as_bytes()),
///         },
///         confirmation_height: 1,
///         confirmation_time: 123,
///     },
/// );
/// ```
pub trait Anchor: core::fmt::Debug + Clone + Eq + PartialOrd + Ord + core::hash::Hash {
    /// Returns the [`BlockId`] that the associated blockchain data is "anchored" in.
    fn anchor_block(&self) -> BlockId;

    /// Get the upper bound of the chain data's confirmation height.
    ///
    /// The default definition gives a pessimistic answer. This can be overridden by the `Anchor`
    /// implementation for a more accurate value.
    fn confirmation_height_upper_bound(&self) -> u32 {
        self.anchor_block().height
    }
}

impl<'a, A: Anchor> Anchor for &'a A {
    fn anchor_block(&self) -> BlockId {
        <A as Anchor>::anchor_block(self)
    }
}

/// An [`Anchor`] that can be constructed from a given block, block height and transaction position
/// within the block.
pub trait AnchorFromBlockPosition: Anchor {
    /// Construct the anchor from a given `block`, block height and `tx_pos` within the block.
    fn from_block_position(block: &bitcoin::Block, block_id: BlockId, tx_pos: usize) -> Self;
}

/// Trait that makes an object appendable.
pub trait Append {
    /// Append another object of the same type onto `self`.
    fn append(&mut self, other: Self);

    /// Returns whether the structure is considered empty.
    fn is_empty(&self) -> bool;
}

impl<K: Ord, V> Append for BTreeMap<K, V> {
    fn append(&mut self, other: Self) {
        // We use `extend` instead of `BTreeMap::append` due to performance issues with `append`.
        // Refer to https://github.com/rust-lang/rust/issues/34666#issuecomment-675658420
        BTreeMap::extend(self, other)
    }

    fn is_empty(&self) -> bool {
        BTreeMap::is_empty(self)
    }
}

impl<T: Ord> Append for BTreeSet<T> {
    fn append(&mut self, other: Self) {
        // We use `extend` instead of `BTreeMap::append` due to performance issues with `append`.
        // Refer to https://github.com/rust-lang/rust/issues/34666#issuecomment-675658420
        BTreeSet::extend(self, other)
    }

    fn is_empty(&self) -> bool {
        BTreeSet::is_empty(self)
    }
}

impl<T> Append for Vec<T> {
    fn append(&mut self, mut other: Self) {
        Vec::append(self, &mut other)
    }

    fn is_empty(&self) -> bool {
        Vec::is_empty(self)
    }
}

macro_rules! impl_append_for_tuple {
    ($($a:ident $b:tt)*) => {
        impl<$($a),*> Append for ($($a,)*) where $($a: Append),* {

            fn append(&mut self, _other: Self) {
                $(Append::append(&mut self.$b, _other.$b) );*
            }

            fn is_empty(&self) -> bool {
                $(Append::is_empty(&self.$b) && )* true
            }
        }
    }
}

impl_append_for_tuple!();
impl_append_for_tuple!(T0 0);
impl_append_for_tuple!(T0 0 T1 1);
impl_append_for_tuple!(T0 0 T1 1 T2 2);
impl_append_for_tuple!(T0 0 T1 1 T2 2 T3 3);
impl_append_for_tuple!(T0 0 T1 1 T2 2 T3 3 T4 4);
impl_append_for_tuple!(T0 0 T1 1 T2 2 T3 3 T4 4 T5 5);
impl_append_for_tuple!(T0 0 T1 1 T2 2 T3 3 T4 4 T5 5 T6 6);
impl_append_for_tuple!(T0 0 T1 1 T2 2 T3 3 T4 4 T5 5 T6 6 T7 7);
impl_append_for_tuple!(T0 0 T1 1 T2 2 T3 3 T4 4 T5 5 T6 6 T7 7 T8 8);
impl_append_for_tuple!(T0 0 T1 1 T2 2 T3 3 T4 4 T5 5 T6 6 T7 7 T8 8 T9 9);
impl_append_for_tuple!(T0 0 T1 1 T2 2 T3 3 T4 4 T5 5 T6 6 T7 7 T8 8 T9 9 T10 10);

1	use crate::collections::BTreeMap;
2	use crate::collections::BTreeSet;
3	use crate::BlockId;
4	use alloc::vec::Vec;
5
6	/// Trait that "anchors" blockchain data to a specific block of height and hash.
7	///
8	/// If transaction A is anchored in block B, and block B is in the best chain, we can
9	/// assume that transaction A is also confirmed in the best chain. This does not necessarily mean
10	/// that transaction A is confirmed in block B. It could also mean transaction A is confirmed in a
11	/// parent block of B.
12	///
13	/// Every [`Anchor`] implementation must contain a [`BlockId`] parameter, and must implement
14	/// [`Ord`]. When implementing [`Ord`], the anchors' [`BlockId`]s should take precedence
15	/// over other elements inside the [`Anchor`]s for comparison purposes, i.e., you should first
16	/// compare the anchors' [`BlockId`]s and then care about the rest.
17	///
18	/// The example shows different types of anchors:
19	/// ```
20	/// # use bdk_chain::local_chain::LocalChain;
21	/// # use bdk_chain::tx_graph::TxGraph;
22	/// # use bdk_chain::BlockId;
23	/// # use bdk_chain::ConfirmationHeightAnchor;
24	/// # use bdk_chain::ConfirmationTimeHeightAnchor;
25	/// # use bdk_chain::example_utils::*;
26	/// # use bitcoin::hashes::Hash;
27	/// // Initialize the local chain with two blocks.
28	/// let chain = LocalChain::from_blocks(
29	/// [
30	/// (1, Hash::hash("first".as_bytes())),
31	/// (2, Hash::hash("second".as_bytes())),
32	/// ]
33	/// .into_iter()
34	/// .collect(),
35	/// );
36	///
37	/// // Transaction to be inserted into `TxGraph`s with different anchor types.
38	/// let tx = tx_from_hex(RAW_TX_1);
39	///
40	/// // Insert `tx` into a `TxGraph` that uses `BlockId` as the anchor type.
41	/// // When a transaction is anchored with `BlockId`, the anchor block and the confirmation block of
42	/// // the transaction is the same block.
43	/// let mut graph_a = TxGraph::<BlockId>::default();
44	/// let _ = graph_a.insert_tx(tx.clone());
45	/// graph_a.insert_anchor(
46	/// tx.txid(),
47	/// BlockId {
48	/// height: 1,
49	/// hash: Hash::hash("first".as_bytes()),
50	/// },
51	/// );
52	///
53	/// // Insert `tx` into a `TxGraph` that uses `ConfirmationHeightAnchor` as the anchor type.
54	/// // This anchor records the anchor block and the confirmation height of the transaction.
55	/// // When a transaction is anchored with `ConfirmationHeightAnchor`, the anchor block and
56	/// // confirmation block can be different. However, the confirmation block cannot be higher than
57	/// // the anchor block and both blocks must be in the same chain for the anchor to be valid.
58	/// let mut graph_b = TxGraph::<ConfirmationHeightAnchor>::default();
59	/// let _ = graph_b.insert_tx(tx.clone());
60	/// graph_b.insert_anchor(
61	/// tx.txid(),
62	/// ConfirmationHeightAnchor {
63	/// anchor_block: BlockId {
64	/// height: 2,
65	/// hash: Hash::hash("second".as_bytes()),
66	/// },
67	/// confirmation_height: 1,
68	/// },
69	/// );
70	///
71	/// // Insert `tx` into a `TxGraph` that uses `ConfirmationTimeHeightAnchor` as the anchor type.
72	/// // This anchor records the anchor block, the confirmation height and time of the transaction.
73	/// // When a transaction is anchored with `ConfirmationTimeHeightAnchor`, the anchor block and
74	/// // confirmation block can be different. However, the confirmation block cannot be higher than
75	/// // the anchor block and both blocks must be in the same chain for the anchor to be valid.
76	/// let mut graph_c = TxGraph::<ConfirmationTimeHeightAnchor>::default();
77	/// let _ = graph_c.insert_tx(tx.clone());
78	/// graph_c.insert_anchor(
79	/// tx.txid(),
80	/// ConfirmationTimeHeightAnchor {
81	/// anchor_block: BlockId {
82	/// height: 2,
83	/// hash: Hash::hash("third".as_bytes()),
84	/// },
85	/// confirmation_height: 1,
86	/// confirmation_time: 123,
87	/// },
88	/// );
89	/// ```
90	pub trait Anchor: core::fmt::Debug + Clone + Eq + PartialOrd + Ord + core::hash::Hash {
91	/// Returns the [`BlockId`] that the associated blockchain data is "anchored" in.
92	fn anchor_block(&self) -> BlockId;
93
94	/// Get the upper bound of the chain data's confirmation height.
95	///
96	/// The default definition gives a pessimistic answer. This can be overridden by the `Anchor`
97	/// implementation for a more accurate value.
98	fn confirmation_height_upper_bound(&self) -> u32 {	71✔
99	self.anchor_block().height	71✔
100	}	71✔
101	}
102
103	impl<'a, A: Anchor> Anchor for &'a A {
104	fn anchor_block(&self) -> BlockId {	×
105	<A as Anchor>::anchor_block(self)	×
106	}	×
107	}
108
109	/// An [`Anchor`] that can be constructed from a given block, block height and transaction position
110	/// within the block.
111	pub trait AnchorFromBlockPosition: Anchor {
112	/// Construct the anchor from a given `block`, block height and `tx_pos` within the block.
113	fn from_block_position(block: &bitcoin::Block, block_id: BlockId, tx_pos: usize) -> Self;
114	}
115
116	/// Trait that makes an object appendable.
117	pub trait Append {
118	/// Append another object of the same type onto `self`.
119	fn append(&mut self, other: Self);
120
121	/// Returns whether the structure is considered empty.
122	fn is_empty(&self) -> bool;
123	}
124
125	impl<K: Ord, V> Append for BTreeMap<K, V> {
126	fn append(&mut self, other: Self) {	12,489✔
127	// We use `extend` instead of `BTreeMap::append` due to performance issues with `append`.	12,489✔
128	// Refer to https://github.com/rust-lang/rust/issues/34666#issuecomment-675658420	12,489✔
129	BTreeMap::extend(self, other)	12,489✔
130	}	12,489✔
131
132	fn is_empty(&self) -> bool {	×
133	BTreeMap::is_empty(self)	×
134	}	×
135	}
136
137	impl<T: Ord> Append for BTreeSet<T> {
138	fn append(&mut self, other: Self) {	450✔
139	// We use `extend` instead of `BTreeMap::append` due to performance issues with `append`.	450✔
140	// Refer to https://github.com/rust-lang/rust/issues/34666#issuecomment-675658420	450✔
141	BTreeSet::extend(self, other)	450✔
142	}	450✔
143
144	fn is_empty(&self) -> bool {	437✔
145	BTreeSet::is_empty(self)	437✔
146	}	437✔
147	}
148
149	impl<T> Append for Vec<T> {
150	fn append(&mut self, mut other: Self) {	×
151	Vec::append(self, &mut other)	×
152	}	×
153
154	fn is_empty(&self) -> bool {	×
155	Vec::is_empty(self)	×
156	}	×
157	}
158
159	macro_rules! impl_append_for_tuple {
160	($($a:ident $b:tt)*) => {
161	impl<$($a),> Append for ($($a,)) where $($a: Append),* {
162
163	fn append(&mut self, _other: Self) {	6,468✔
164	$(Append::append(&mut self.$b, _other.$b) );*	6,468✔
165	}	6,468✔
166
167	fn is_empty(&self) -> bool {	×
168	$(Append::is_empty(&self.$b) && )* true	×
169	}	2,142✔
170	}
171	}
172	}
173
174	impl_append_for_tuple!();
175	impl_append_for_tuple!(T0 0);
176	impl_append_for_tuple!(T0 0 T1 1);
177	impl_append_for_tuple!(T0 0 T1 1 T2 2);
178	impl_append_for_tuple!(T0 0 T1 1 T2 2 T3 3);
179	impl_append_for_tuple!(T0 0 T1 1 T2 2 T3 3 T4 4);
180	impl_append_for_tuple!(T0 0 T1 1 T2 2 T3 3 T4 4 T5 5);
181	impl_append_for_tuple!(T0 0 T1 1 T2 2 T3 3 T4 4 T5 5 T6 6);
182	impl_append_for_tuple!(T0 0 T1 1 T2 2 T3 3 T4 4 T5 5 T6 6 T7 7);
183	impl_append_for_tuple!(T0 0 T1 1 T2 2 T3 3 T4 4 T5 5 T6 6 T7 7 T8 8);
184	impl_append_for_tuple!(T0 0 T1 1 T2 2 T3 3 T4 4 T5 5 T6 6 T7 7 T8 8 T9 9);
185	impl_append_for_tuple!(T0 0 T1 1 T2 2 T3 3 T4 4 T5 5 T6 6 T7 7 T8 8 T9 9 T10 10);

bitcoindevkit / bdk / 8968819480

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