frost/bdk
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve txout filter/listing method docs for TxGraph

Browse Source 
Rename the `S` trait bound to `OI` (outpoint index) to emphasize it's
not only for spk indexing.
This commit is contained in:
志宇 2023-05-11 12:43:49 +08:00
parent fb75aa94a9
commit ed89de752c
No known key found for this signature in database
GPG Key ID: F6345C9837C2BDE8
1 changed files with 29 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
crates/chain/src/tx_graph.rs
View File

@ -766,8 +766,9 @@ impl<A: Anchor> TxGraph<A> {
/// Get a filtered list of outputs from the given `outpoints` that are in `chain` with /// Get a filtered list of outputs from the given `outpoints` that are in `chain` with
/// `chain_tip`. /// `chain_tip`.
/// ///
/// `outpoints` is a list of outpoints we are interested in, coupled with the associated txout's /// `outpoints` is a list of outpoints we are interested in, coupled with an outpoint identifier
/// script pubkey index (`S`). /// (`OI`) for convenience. If `OI` is not necessary, the caller can use `()`, or
/// [`Iterator::enumerate`] over a list of [`OutPoint`]s.
/// ///
/// Floating outputs are ignored. /// Floating outputs are ignored.
/// ///
@ -780,16 +781,16 @@ impl<A: Anchor> TxGraph<A> {
/// instead. /// instead.
/// ///
/// [`filter_chain_txouts`]: Self::filter_chain_txouts /// [`filter_chain_txouts`]: Self::filter_chain_txouts
pub fn try_filter_chain_txouts<'a, C: ChainOracle + 'a, S: Clone + 'a>( pub fn try_filter_chain_txouts<'a, C: ChainOracle + 'a, OI: Clone + 'a>(
&'a self, &'a self,
chain: &'a C, chain: &'a C,
chain_tip: BlockId, chain_tip: BlockId,
outpoints: impl IntoIterator<Item = (S, OutPoint)> + 'a, outpoints: impl IntoIterator<Item = (OI, OutPoint)> + 'a,
) -> impl Iterator<Item = Result<(S, FullTxOut<ObservedAs<A>>), C::Error>> + 'a { ) -> impl Iterator<Item = Result<(OI, FullTxOut<ObservedAs<A>>), C::Error>> + 'a {
outpoints outpoints
.into_iter() .into_iter()
.map( .map(
move |(spk_i, op)| -> Result<Option<(S, FullTxOut<_>)>, C::Error> { move |(spk_i, op)| -> Result<Option<(OI, FullTxOut<_>)>, C::Error> {
let tx_node = match self.get_tx_node(op.txid) { let tx_node = match self.get_tx_node(op.txid) {
Some(n) => n, Some(n) => n,
None => return Ok(None), None => return Ok(None),
@ -831,12 +832,12 @@ impl<A: Anchor> TxGraph<A> {
/// This is the infallible version of [`try_filter_chain_txouts`]. /// This is the infallible version of [`try_filter_chain_txouts`].
/// ///
/// [`try_filter_chain_txouts`]: Self::try_filter_chain_txouts /// [`try_filter_chain_txouts`]: Self::try_filter_chain_txouts
pub fn filter_chain_txouts<'a, C: ChainOracle<Error = Infallible> + 'a, S: Clone + 'a>( pub fn filter_chain_txouts<'a, C: ChainOracle<Error = Infallible> + 'a, OI: Clone + 'a>(
&'a self, &'a self,
chain: &'a C, chain: &'a C,
chain_tip: BlockId, chain_tip: BlockId,
outpoints: impl IntoIterator<Item = (S, OutPoint)> + 'a, outpoints: impl IntoIterator<Item = (OI, OutPoint)> + 'a,
) -> impl Iterator<Item = (S, FullTxOut<ObservedAs<A>>)> + 'a { ) -> impl Iterator<Item = (OI, FullTxOut<ObservedAs<A>>)> + 'a {
self.try_filter_chain_txouts(chain, chain_tip, outpoints) self.try_filter_chain_txouts(chain, chain_tip, outpoints)
.map(|r| r.expect("oracle is infallible")) .map(|r| r.expect("oracle is infallible"))
} }
@ -844,8 +845,9 @@ impl<A: Anchor> TxGraph<A> {
/// Get a filtered list of unspent outputs (UTXOs) from the given `outpoints` that are in /// Get a filtered list of unspent outputs (UTXOs) from the given `outpoints` that are in
/// `chain` with `chain_tip`. /// `chain` with `chain_tip`.
/// ///
/// `outpoints` is a list of outpoints we are interested in, coupled with the associated txout's /// `outpoints` is a list of outpoints we are interested in, coupled with an outpoint identifier
/// script pubkey index (`S`). /// (`OI`) for convenience. If `OI` is not necessary, the caller can use `()`, or
/// [`Iterator::enumerate`] over a list of [`OutPoint`]s.
/// ///
/// Floating outputs are ignored. /// Floating outputs are ignored.
/// ///
@ -858,12 +860,12 @@ impl<A: Anchor> TxGraph<A> {
/// instead. /// instead.
/// ///
/// [`filter_chain_unspents`]: Self::filter_chain_unspents /// [`filter_chain_unspents`]: Self::filter_chain_unspents
pub fn try_filter_chain_unspents<'a, C: ChainOracle + 'a, S: Clone + 'a>( pub fn try_filter_chain_unspents<'a, C: ChainOracle + 'a, OI: Clone + 'a>(
&'a self, &'a self,
chain: &'a C, chain: &'a C,
chain_tip: BlockId, chain_tip: BlockId,
outpoints: impl IntoIterator<Item = (S, OutPoint)> + 'a, outpoints: impl IntoIterator<Item = (OI, OutPoint)> + 'a,
) -> impl Iterator<Item = Result<(S, FullTxOut<ObservedAs<A>>), C::Error>> + 'a { ) -> impl Iterator<Item = Result<(OI, FullTxOut<ObservedAs<A>>), C::Error>> + 'a {
self.try_filter_chain_txouts(chain, chain_tip, outpoints) self.try_filter_chain_txouts(chain, chain_tip, outpoints)
.filter(|r| match r { .filter(|r| match r {
// keep unspents, drop spents // keep unspents, drop spents
@ -879,12 +881,12 @@ impl<A: Anchor> TxGraph<A> {
/// This is the infallible version of [`try_filter_chain_unspents`]. /// This is the infallible version of [`try_filter_chain_unspents`].
/// ///
/// [`try_filter_chain_unspents`]: Self::try_filter_chain_unspents /// [`try_filter_chain_unspents`]: Self::try_filter_chain_unspents
pub fn filter_chain_unspents<'a, C: ChainOracle<Error = Infallible> + 'a, S: Clone + 'a>( pub fn filter_chain_unspents<'a, C: ChainOracle<Error = Infallible> + 'a, OI: Clone + 'a>(
&'a self, &'a self,
chain: &'a C, chain: &'a C,
chain_tip: BlockId, chain_tip: BlockId,
txouts: impl IntoIterator<Item = (S, OutPoint)> + 'a, txouts: impl IntoIterator<Item = (OI, OutPoint)> + 'a,
) -> impl Iterator<Item = (S, FullTxOut<ObservedAs<A>>)> + 'a { ) -> impl Iterator<Item = (OI, FullTxOut<ObservedAs<A>>)> + 'a {
self.try_filter_chain_unspents(chain, chain_tip, txouts) self.try_filter_chain_unspents(chain, chain_tip, txouts)
.map(|r| r.expect("oracle is infallible")) .map(|r| r.expect("oracle is infallible"))
} }
@ -893,16 +895,20 @@ impl<A: Anchor> TxGraph<A> {
/// ///
/// The output of `trust_predicate` should return `true` for scripts that we trust. /// The output of `trust_predicate` should return `true` for scripts that we trust.
/// ///
/// `outpoints` is a list of outpoints we are interested in, coupled with an outpoint identifier
/// (`OI`) for convenience. If `OI` is not necessary, the caller can use `()`, or
/// [`Iterator::enumerate`] over a list of [`OutPoint`]s.
///
/// If the provided [`ChainOracle`] implementation (`chain`) is infallible, [`balance`] can be /// If the provided [`ChainOracle`] implementation (`chain`) is infallible, [`balance`] can be
/// used instead. /// used instead.
/// ///
/// [`balance`]: Self::balance /// [`balance`]: Self::balance
pub fn try_balance<C: ChainOracle, S: Clone>( pub fn try_balance<C: ChainOracle, OI: Clone>(
&self, &self,
chain: &C, chain: &C,
chain_tip: BlockId, chain_tip: BlockId,
outpoints: impl IntoIterator<Item = (S, OutPoint)>, outpoints: impl IntoIterator<Item = (OI, OutPoint)>,
mut trust_predicate: impl FnMut(&S, &Script) -> bool, mut trust_predicate: impl FnMut(&OI, &Script) -> bool,
) -> Result<Balance, C::Error> { ) -> Result<Balance, C::Error> {
let mut immature = 0; let mut immature = 0;
let mut trusted_pending = 0; let mut trusted_pending = 0;
@ -943,12 +949,12 @@ impl<A: Anchor> TxGraph<A> {
/// This is the infallible version of [`try_balance`]. /// This is the infallible version of [`try_balance`].
/// ///
/// [`try_balance`]: Self::try_balance /// [`try_balance`]: Self::try_balance
pub fn balance<C: ChainOracle<Error = Infallible>, S: Clone>( pub fn balance<C: ChainOracle<Error = Infallible>, OI: Clone>(
&self, &self,
chain: &C, chain: &C,
chain_tip: BlockId, chain_tip: BlockId,
outpoints: impl IntoIterator<Item = (S, OutPoint)>, outpoints: impl IntoIterator<Item = (OI, OutPoint)>,
trust_predicate: impl FnMut(&S, &Script) -> bool, trust_predicate: impl FnMut(&OI, &Script) -> bool,
) -> Balance { ) -> Balance {
self.try_balance(chain, chain_tip, outpoints, trust_predicate) self.try_balance(chain, chain_tip, outpoints, trust_predicate)
.expect("oracle is infallible") .expect("oracle is infallible")