8968819480

Committed 06 May 2024 12:09PM UTC 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

13.73

/crates/bdk/src/wallet/error.rs

// Bitcoin Dev Kit
// Written in 2020 by Alekos Filini <alekos.filini@gmail.com>
//
// Copyright (c) 2020-2021 Bitcoin Dev Kit Developers
//
// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
// or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
// You may not use this file except in accordance with one or both of these
// licenses.

//! Errors that can be thrown by the [`Wallet`](crate::wallet::Wallet)

use crate::descriptor::policy::PolicyError;
use crate::descriptor::DescriptorError;
use crate::wallet::coin_selection;
use crate::{descriptor, KeychainKind};
use alloc::string::String;
use bitcoin::{absolute, psbt, OutPoint, Sequence, Txid};
use core::fmt;

/// Errors returned by miniscript when updating inconsistent PSBTs
#[derive(Debug, Clone)]
pub enum MiniscriptPsbtError {
    /// Descriptor key conversion error
    Conversion(miniscript::descriptor::ConversionError),
    /// Return error type for PsbtExt::update_input_with_descriptor
    UtxoUpdate(miniscript::psbt::UtxoUpdateError),
    /// Return error type for PsbtExt::update_output_with_descriptor
    OutputUpdate(miniscript::psbt::OutputUpdateError),
}

impl fmt::Display for MiniscriptPsbtError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Conversion(err) => write!(f, "Conversion error: {}", err),
            Self::UtxoUpdate(err) => write!(f, "UTXO update error: {}", err),
            Self::OutputUpdate(err) => write!(f, "Output update error: {}", err),
        }
    }
}

#[cfg(feature = "std")]
impl std::error::Error for MiniscriptPsbtError {}

#[derive(Debug)]
/// Error returned from [`TxBuilder::finish`]
///
/// [`TxBuilder::finish`]: crate::wallet::tx_builder::TxBuilder::finish
pub enum CreateTxError {
    /// There was a problem with the descriptors passed in
    Descriptor(DescriptorError),
    /// We were unable to load wallet data from or write wallet data to the persistence backend
    Persist(anyhow::Error),
    /// There was a problem while extracting and manipulating policies
    Policy(PolicyError),
    /// Spending policy is not compatible with this [`KeychainKind`]
    SpendingPolicyRequired(KeychainKind),
    /// Requested invalid transaction version '0'
    Version0,
    /// Requested transaction version `1`, but at least `2` is needed to use OP_CSV
    Version1Csv,
    /// Requested `LockTime` is less than is required to spend from this script
    LockTime {
        /// Requested `LockTime`
        requested: absolute::LockTime,
        /// Required `LockTime`
        required: absolute::LockTime,
    },
    /// Cannot enable RBF with a `Sequence` >= 0xFFFFFFFE
    RbfSequence,
    /// Cannot enable RBF with `Sequence` given a required OP_CSV
    RbfSequenceCsv {
        /// Given RBF `Sequence`
        rbf: Sequence,
        /// Required OP_CSV `Sequence`
        csv: Sequence,
    },
    /// When bumping a tx the absolute fee requested is lower than replaced tx absolute fee
    FeeTooLow {
        /// Required fee absolute value (satoshi)
        required: u64,
    },
    /// When bumping a tx the fee rate requested is lower than required
    FeeRateTooLow {
        /// Required fee rate
        required: bitcoin::FeeRate,
    },
    /// `manually_selected_only` option is selected but no utxo has been passed
    NoUtxosSelected,
    /// Output created is under the dust limit, 546 satoshis
    OutputBelowDustLimit(usize),
    /// The `change_policy` was set but the wallet does not have a change_descriptor
    ChangePolicyDescriptor,
    /// There was an error with coin selection
    CoinSelection(coin_selection::Error),
    /// Wallet's UTXO set is not enough to cover recipient's requested plus fee
    InsufficientFunds {
        /// Sats needed for some transaction
        needed: u64,
        /// Sats available for spending
        available: u64,
    },
    /// Cannot build a tx without recipients
    NoRecipients,
    /// Partially signed bitcoin transaction error
    Psbt(psbt::Error),
    /// In order to use the [`TxBuilder::add_global_xpubs`] option every extended
    /// key in the descriptor must either be a master key itself (having depth = 0) or have an
    /// explicit origin provided
    ///
    /// [`TxBuilder::add_global_xpubs`]: crate::wallet::tx_builder::TxBuilder::add_global_xpubs
    MissingKeyOrigin(String),
    /// Happens when trying to spend an UTXO that is not in the internal database
    UnknownUtxo,
    /// Missing non_witness_utxo on foreign utxo for given `OutPoint`
    MissingNonWitnessUtxo(OutPoint),
    /// Miniscript PSBT error
    MiniscriptPsbt(MiniscriptPsbtError),
}

impl fmt::Display for CreateTxError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Descriptor(e) => e.fmt(f),
            Self::Persist(e) => {
                write!(
                    f,
                    "failed to load wallet data from or write wallet data to persistence backend: {}",
                    e
                )
            }
            Self::Policy(e) => e.fmt(f),
            CreateTxError::SpendingPolicyRequired(keychain_kind) => {
                write!(f, "Spending policy required: {:?}", keychain_kind)
            }
            CreateTxError::Version0 => {
                write!(f, "Invalid version `0`")
            }
            CreateTxError::Version1Csv => {
                write!(
                    f,
                    "TxBuilder requested version `1`, but at least `2` is needed to use OP_CSV"
                )
            }
            CreateTxError::LockTime {
                requested,
                required,
            } => {
                write!(f, "TxBuilder requested timelock of `{:?}`, but at least `{:?}` is required to spend from this script", required, requested)
            }
            CreateTxError::RbfSequence => {
                write!(f, "Cannot enable RBF with a nSequence >= 0xFFFFFFFE")
            }
            CreateTxError::RbfSequenceCsv { rbf, csv } => {
                write!(
                    f,
                    "Cannot enable RBF with nSequence `{:?}` given a required OP_CSV of `{:?}`",
                    rbf, csv
                )
            }
            CreateTxError::FeeTooLow { required } => {
                write!(f, "Fee to low: required {} sat", required)
            }
            CreateTxError::FeeRateTooLow { required } => {
                write!(
                    f,
                    // Note: alternate fmt as sat/vb (ceil) available in bitcoin-0.31
                    //"Fee rate too low: required {required:#}"
                    "Fee rate too low: required {} sat/vb",
                    crate::floating_rate!(required)
                )
            }
            CreateTxError::NoUtxosSelected => {
                write!(f, "No UTXO selected")
            }
            CreateTxError::OutputBelowDustLimit(limit) => {
                write!(f, "Output below the dust limit: {}", limit)
            }
            CreateTxError::ChangePolicyDescriptor => {
                write!(
                    f,
                    "The `change_policy` can be set only if the wallet has a change_descriptor"
                )
            }
            CreateTxError::CoinSelection(e) => e.fmt(f),
            CreateTxError::InsufficientFunds { needed, available } => {
                write!(
                    f,
                    "Insufficient funds: {} sat available of {} sat needed",
                    available, needed
                )
            }
            CreateTxError::NoRecipients => {
                write!(f, "Cannot build tx without recipients")
            }
            CreateTxError::Psbt(e) => e.fmt(f),
            CreateTxError::MissingKeyOrigin(err) => {
                write!(f, "Missing key origin: {}", err)
            }
            CreateTxError::UnknownUtxo => {
                write!(f, "UTXO not found in the internal database")
            }
            CreateTxError::MissingNonWitnessUtxo(outpoint) => {
                write!(f, "Missing non_witness_utxo on foreign utxo {}", outpoint)
            }
            CreateTxError::MiniscriptPsbt(err) => {
                write!(f, "Miniscript PSBT error: {}", err)
            }
        }
    }
}

impl From<descriptor::error::Error> for CreateTxError {
    fn from(err: descriptor::error::Error) -> Self {
        CreateTxError::Descriptor(err)
    }
}

impl From<PolicyError> for CreateTxError {
    fn from(err: PolicyError) -> Self {
        CreateTxError::Policy(err)
    }
}

impl From<MiniscriptPsbtError> for CreateTxError {
    fn from(err: MiniscriptPsbtError) -> Self {
        CreateTxError::MiniscriptPsbt(err)
    }
}

impl From<psbt::Error> for CreateTxError {
    fn from(err: psbt::Error) -> Self {
        CreateTxError::Psbt(err)
    }
}

impl From<coin_selection::Error> for CreateTxError {
    fn from(err: coin_selection::Error) -> Self {
        CreateTxError::CoinSelection(err)
    }
}

#[cfg(feature = "std")]
impl std::error::Error for CreateTxError {}

#[derive(Debug)]
/// Error returned from [`Wallet::build_fee_bump`]
///
/// [`Wallet::build_fee_bump`]: super::Wallet::build_fee_bump
pub enum BuildFeeBumpError {
    /// Happens when trying to spend an UTXO that is not in the internal database
    UnknownUtxo(OutPoint),
    /// Thrown when a tx is not found in the internal database
    TransactionNotFound(Txid),
    /// Happens when trying to bump a transaction that is already confirmed
    TransactionConfirmed(Txid),
    /// Trying to replace a tx that has a sequence >= `0xFFFFFFFE`
    IrreplaceableTransaction(Txid),
    /// Node doesn't have data to estimate a fee rate
    FeeRateUnavailable,
}

impl fmt::Display for BuildFeeBumpError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::UnknownUtxo(outpoint) => write!(
                f,
                "UTXO not found in the internal database with txid: {}, vout: {}",
                outpoint.txid, outpoint.vout
            ),
            Self::TransactionNotFound(txid) => {
                write!(
                    f,
                    "Transaction not found in the internal database with txid: {}",
                    txid
                )
            }
            Self::TransactionConfirmed(txid) => {
                write!(f, "Transaction already confirmed with txid: {}", txid)
            }
            Self::IrreplaceableTransaction(txid) => {
                write!(f, "Transaction can't be replaced with txid: {}", txid)
            }
            Self::FeeRateUnavailable => write!(f, "Fee rate unavailable"),
        }
    }
}

#[cfg(feature = "std")]
impl std::error::Error for BuildFeeBumpError {}

1	// Bitcoin Dev Kit
2	// Written in 2020 by Alekos Filini <alekos.filini@gmail.com>
3	//
4	// Copyright (c) 2020-2021 Bitcoin Dev Kit Developers
5	//
6	// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
7	// or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
8	// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
9	// You may not use this file except in accordance with one or both of these
10	// licenses.
11
12	//! Errors that can be thrown by the [`Wallet`](crate::wallet::Wallet)
13
14	use crate::descriptor::policy::PolicyError;
15	use crate::descriptor::DescriptorError;
16	use crate::wallet::coin_selection;
17	use crate::{descriptor, KeychainKind};
18	use alloc::string::String;
19	use bitcoin::{absolute, psbt, OutPoint, Sequence, Txid};
20	use core::fmt;
21
22	/// Errors returned by miniscript when updating inconsistent PSBTs
23	#[derive(Debug, Clone)]
24	pub enum MiniscriptPsbtError {
25	/// Descriptor key conversion error
26	Conversion(miniscript::descriptor::ConversionError),
27	/// Return error type for PsbtExt::update_input_with_descriptor
28	UtxoUpdate(miniscript::psbt::UtxoUpdateError),
29	/// Return error type for PsbtExt::update_output_with_descriptor
30	OutputUpdate(miniscript::psbt::OutputUpdateError),
31	}
32
33	impl fmt::Display for MiniscriptPsbtError {
34	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {	×
35	match self {	×
36	Self::Conversion(err) => write!(f, "Conversion error: {}", err),	×
37	Self::UtxoUpdate(err) => write!(f, "UTXO update error: {}", err),	×
38	Self::OutputUpdate(err) => write!(f, "Output update error: {}", err),	×
39	}
40	}	×
41	}
42
43	#[cfg(feature = "std")]
44	impl std::error::Error for MiniscriptPsbtError {}
45
46	#[derive(Debug)]
47	/// Error returned from [`TxBuilder::finish`]
48	///
49	/// [`TxBuilder::finish`]: crate::wallet::tx_builder::TxBuilder::finish
50	pub enum CreateTxError {
51	/// There was a problem with the descriptors passed in
52	Descriptor(DescriptorError),
53	/// We were unable to load wallet data from or write wallet data to the persistence backend
54	Persist(anyhow::Error),
55	/// There was a problem while extracting and manipulating policies
56	Policy(PolicyError),
57	/// Spending policy is not compatible with this [`KeychainKind`]
58	SpendingPolicyRequired(KeychainKind),
59	/// Requested invalid transaction version '0'
60	Version0,
61	/// Requested transaction version `1`, but at least `2` is needed to use OP_CSV
62	Version1Csv,
63	/// Requested `LockTime` is less than is required to spend from this script
64	LockTime {
65	/// Requested `LockTime`
66	requested: absolute::LockTime,
67	/// Required `LockTime`
68	required: absolute::LockTime,
69	},
70	/// Cannot enable RBF with a `Sequence` >= 0xFFFFFFFE
71	RbfSequence,
72	/// Cannot enable RBF with `Sequence` given a required OP_CSV
73	RbfSequenceCsv {
74	/// Given RBF `Sequence`
75	rbf: Sequence,
76	/// Required OP_CSV `Sequence`
77	csv: Sequence,
78	},
79	/// When bumping a tx the absolute fee requested is lower than replaced tx absolute fee
80	FeeTooLow {
81	/// Required fee absolute value (satoshi)
82	required: u64,
83	},
84	/// When bumping a tx the fee rate requested is lower than required
85	FeeRateTooLow {
86	/// Required fee rate
87	required: bitcoin::FeeRate,
88	},
89	/// `manually_selected_only` option is selected but no utxo has been passed
90	NoUtxosSelected,
91	/// Output created is under the dust limit, 546 satoshis
92	OutputBelowDustLimit(usize),
93	/// The `change_policy` was set but the wallet does not have a change_descriptor
94	ChangePolicyDescriptor,
95	/// There was an error with coin selection
96	CoinSelection(coin_selection::Error),
97	/// Wallet's UTXO set is not enough to cover recipient's requested plus fee
98	InsufficientFunds {
99	/// Sats needed for some transaction
100	needed: u64,
101	/// Sats available for spending
102	available: u64,
103	},
104	/// Cannot build a tx without recipients
105	NoRecipients,
106	/// Partially signed bitcoin transaction error
107	Psbt(psbt::Error),
108	/// In order to use the [`TxBuilder::add_global_xpubs`] option every extended
109	/// key in the descriptor must either be a master key itself (having depth = 0) or have an
110	/// explicit origin provided
111	///
112	/// [`TxBuilder::add_global_xpubs`]: crate::wallet::tx_builder::TxBuilder::add_global_xpubs
113	MissingKeyOrigin(String),
114	/// Happens when trying to spend an UTXO that is not in the internal database
115	UnknownUtxo,
116	/// Missing non_witness_utxo on foreign utxo for given `OutPoint`
117	MissingNonWitnessUtxo(OutPoint),
118	/// Miniscript PSBT error
119	MiniscriptPsbt(MiniscriptPsbtError),
120	}
121
122	impl fmt::Display for CreateTxError {
123	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {	8✔
124	match self {	8✔
125	Self::Descriptor(e) => e.fmt(f),	×
126	Self::Persist(e) => {	×
127	write!(	×
128	f,	×
129	"failed to load wallet data from or write wallet data to persistence backend: {}",	×
130	e	×
131	)	×
132	}
133	Self::Policy(e) => e.fmt(f),	×
134	CreateTxError::SpendingPolicyRequired(keychain_kind) => {	×
135	write!(f, "Spending policy required: {:?}", keychain_kind)	×
136	}
137	CreateTxError::Version0 => {
138	write!(f, "Invalid version `0`")	×
139	}
140	CreateTxError::Version1Csv => {
141	write!(	×
142	f,	×
143	"TxBuilder requested version `1`, but at least `2` is needed to use OP_CSV"	×
144	)	×
145	}
146	CreateTxError::LockTime {
147	requested,	×
148	required,	×
149	} => {	×
150	write!(f, "TxBuilder requested timelock of `{:?}`, but at least `{:?}` is required to spend from this script", required, requested)	×
151	}
152	CreateTxError::RbfSequence => {
153	write!(f, "Cannot enable RBF with a nSequence >= 0xFFFFFFFE")	×
154	}
155	CreateTxError::RbfSequenceCsv { rbf, csv } => {	×
156	write!(	×
157	f,	×
158	"Cannot enable RBF with nSequence `{:?}` given a required OP_CSV of `{:?}`",	×
159	rbf, csv	×
160	)	×
161	}
162	CreateTxError::FeeTooLow { required } => {	×
163	write!(f, "Fee to low: required {} sat", required)	×
164	}
165	CreateTxError::FeeRateTooLow { required } => {	8✔
166	write!(	8✔
167	f,	8✔
168	// Note: alternate fmt as sat/vb (ceil) available in bitcoin-0.31	8✔
169	//"Fee rate too low: required {required:#}"	8✔
170	"Fee rate too low: required {} sat/vb",	8✔
171	crate::floating_rate!(required)	8✔
172	)	8✔
173	}
174	CreateTxError::NoUtxosSelected => {
175	write!(f, "No UTXO selected")	×
176	}
177	CreateTxError::OutputBelowDustLimit(limit) => {	×
178	write!(f, "Output below the dust limit: {}", limit)	×
179	}
180	CreateTxError::ChangePolicyDescriptor => {
181	write!(	×
182	f,	×
183	"The `change_policy` can be set only if the wallet has a change_descriptor"	×
184	)	×
185	}
186	CreateTxError::CoinSelection(e) => e.fmt(f),	×
187	CreateTxError::InsufficientFunds { needed, available } => {	×
188	write!(	×
189	f,	×
190	"Insufficient funds: {} sat available of {} sat needed",	×
191	available, needed	×
192	)	×
193	}
194	CreateTxError::NoRecipients => {
195	write!(f, "Cannot build tx without recipients")	×
196	}
197	CreateTxError::Psbt(e) => e.fmt(f),	×
198	CreateTxError::MissingKeyOrigin(err) => {	×
199	write!(f, "Missing key origin: {}", err)	×
200	}
201	CreateTxError::UnknownUtxo => {
202	write!(f, "UTXO not found in the internal database")	×
203	}
204	CreateTxError::MissingNonWitnessUtxo(outpoint) => {	×
205	write!(f, "Missing non_witness_utxo on foreign utxo {}", outpoint)	×
206	}
207	CreateTxError::MiniscriptPsbt(err) => {	×
208	write!(f, "Miniscript PSBT error: {}", err)	×
209	}
210	}
211	}	8✔
212	}
213
214	impl From<descriptor::error::Error> for CreateTxError {
215	fn from(err: descriptor::error::Error) -> Self {	×
216	CreateTxError::Descriptor(err)	×
217	}	×
218	}
219
220	impl From<PolicyError> for CreateTxError {
221	fn from(err: PolicyError) -> Self {	×
222	CreateTxError::Policy(err)	×
223	}	×
224	}
225
226	impl From<MiniscriptPsbtError> for CreateTxError {
227	fn from(err: MiniscriptPsbtError) -> Self {	×
228	CreateTxError::MiniscriptPsbt(err)	×
229	}	×
230	}
231
232	impl From<psbt::Error> for CreateTxError {
233	fn from(err: psbt::Error) -> Self {	×
234	CreateTxError::Psbt(err)	×
235	}	×
236	}
237
238	impl From<coin_selection::Error> for CreateTxError {
239	fn from(err: coin_selection::Error) -> Self {	48✔
240	CreateTxError::CoinSelection(err)	48✔
241	}	48✔
242	}
243
244	#[cfg(feature = "std")]
245	impl std::error::Error for CreateTxError {}
246
247	#[derive(Debug)]
248	/// Error returned from [`Wallet::build_fee_bump`]
249	///
250	/// [`Wallet::build_fee_bump`]: super::Wallet::build_fee_bump
251	pub enum BuildFeeBumpError {
252	/// Happens when trying to spend an UTXO that is not in the internal database
253	UnknownUtxo(OutPoint),
254	/// Thrown when a tx is not found in the internal database
255	TransactionNotFound(Txid),
256	/// Happens when trying to bump a transaction that is already confirmed
257	TransactionConfirmed(Txid),
258	/// Trying to replace a tx that has a sequence >= `0xFFFFFFFE`
259	IrreplaceableTransaction(Txid),
260	/// Node doesn't have data to estimate a fee rate
261	FeeRateUnavailable,
262	}
263
264	impl fmt::Display for BuildFeeBumpError {
265	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {	×
266	match self {	×
267	Self::UnknownUtxo(outpoint) => write!(	×
268	f,	×
269	"UTXO not found in the internal database with txid: {}, vout: {}",	×
270	outpoint.txid, outpoint.vout	×
271	),	×
272	Self::TransactionNotFound(txid) => {	×
273	write!(	×
274	f,	×
275	"Transaction not found in the internal database with txid: {}",	×
276	txid	×
277	)	×
278	}
279	Self::TransactionConfirmed(txid) => {	×
280	write!(f, "Transaction already confirmed with txid: {}", txid)	×
281	}
282	Self::IrreplaceableTransaction(txid) => {	×
283	write!(f, "Transaction can't be replaced with txid: {}", txid)	×
284	}
285	Self::FeeRateUnavailable => write!(f, "Fee rate unavailable"),	×
286	}
287	}	×
288	}
289
290	#[cfg(feature = "std")]
291	impl std::error::Error for BuildFeeBumpError {}

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