From 75f8b81d58a985669ce7302fe235ad68eddc0d47 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BF=97=E5=AE=87?= Date: Mon, 29 May 2023 21:54:53 +0800 Subject: [PATCH] Update documentation * Add `warn(missing_docs)` for `bdk_wallet` and `bdk_chain`. * Add missing documentation. * Remove `LocalChain::heights` method. * Remove old TODOs. --- crates/bdk/src/lib.rs | 2 ++ crates/bdk/src/wallet/mod.rs | 15 ++++++++++----- crates/chain/src/chain_data.rs | 21 ++++++++++++++++++--- crates/chain/src/indexed_tx_graph.rs | 4 ++++ crates/chain/src/lib.rs | 5 +++++ crates/chain/src/local_chain.rs | 16 +++++++++++----- crates/chain/src/tx_graph.rs | 4 ++++ crates/electrum/src/electrum_ext.rs | 1 - 8 files changed, 54 insertions(+), 14 deletions(-) diff --git a/crates/bdk/src/lib.rs b/crates/bdk/src/lib.rs index 19aa5540..ecd3fb23 100644 --- a/crates/bdk/src/lib.rs +++ b/crates/bdk/src/lib.rs @@ -1,5 +1,7 @@ #![doc = include_str!("../README.md")] #![no_std] +#![warn(missing_docs)] + #[cfg(feature = "std")] #[macro_use] extern crate std; diff --git a/crates/bdk/src/wallet/mod.rs b/crates/bdk/src/wallet/mod.rs index 4bee9be8..3f58921a 100644 --- a/crates/bdk/src/wallet/mod.rs +++ b/crates/bdk/src/wallet/mod.rs @@ -21,12 +21,12 @@ use alloc::{ }; pub use bdk_chain::keychain::Balance; use bdk_chain::{ - indexed_tx_graph::{IndexedAdditions, IndexedTxGraph}, + indexed_tx_graph::IndexedAdditions, keychain::{KeychainTxOutIndex, LocalChangeSet, LocalUpdate}, local_chain::{self, LocalChain, UpdateNotConnectedError}, tx_graph::{CanonicalTx, TxGraph}, - Append, BlockId, ChainPosition, ConfirmationTime, ConfirmationTimeAnchor, FullTxOut, Persist, - PersistBackend, + Append, BlockId, ChainPosition, ConfirmationTime, ConfirmationTimeAnchor, FullTxOut, + IndexedTxGraph, Persist, PersistBackend, }; use bitcoin::consensus::encode::serialize; use bitcoin::secp256k1::Secp256k1; @@ -88,7 +88,7 @@ pub struct Wallet { change_signers: Arc, chain: LocalChain, indexed_graph: IndexedTxGraph>, - persist: Persist, // [TODO] Use a different `ChangeSet` + persist: Persist, network: Network, secp: SecpCtx, } @@ -96,7 +96,7 @@ pub struct Wallet { /// The update to a [`Wallet`] used in [`Wallet::apply_update`]. This is usually returned from blockchain data sources. pub type Update = LocalUpdate; -// /// The changeset produced internally by applying an update. +/// The changeset produced internally by [`Wallet`] when mutated. pub type ChangeSet = LocalChangeSet; /// The address index selection strategy to use to derived an address from the wallet's external @@ -184,10 +184,15 @@ where } } +/// An error that may occur when inserting a transaction into [`Wallet`]. #[derive(Debug)] pub enum InsertTxError { + /// The error variant that occurs when the caller attempts to insert a transaction with a + /// confirmation height that is greater than the internal chain tip. ConfirmationHeightCannotBeGreaterThanTip { + /// The internal chain's tip height. tip_height: Option, + /// The introduced transaction's confirmation height. tx_height: u32, }, } diff --git a/crates/chain/src/chain_data.rs b/crates/chain/src/chain_data.rs index 6decfd07..bd174c2e 100644 --- a/crates/chain/src/chain_data.rs +++ b/crates/chain/src/chain_data.rs @@ -21,6 +21,7 @@ impl ChainPosition { } impl ChainPosition<&A> { + /// Maps a [`ChainPosition<&A>`] into a [`ChainPosition`] by cloning the contents. pub fn cloned(self) -> ChainPosition { match self { ChainPosition::Confirmed(a) => ChainPosition::Confirmed(a.clone()), @@ -30,6 +31,7 @@ impl ChainPosition<&A> { } impl ChainPosition { + /// Determines the upper bound of the confirmation height. pub fn confirmation_height_upper_bound(&self) -> Option { match self { ChainPosition::Confirmed(a) => Some(a.confirmation_height_upper_bound()), @@ -46,15 +48,27 @@ impl ChainPosition { serde(crate = "serde_crate") )] pub enum ConfirmationTime { - Confirmed { height: u32, time: u64 }, - Unconfirmed { last_seen: u64 }, + /// The confirmed variant. + Confirmed { + /// Confirmation height. + height: u32, + /// Confirmation time in unix seconds. + time: u64, + }, + /// The unconfirmed variant. + Unconfirmed { + /// The last-seen timestamp in unix seconds. + last_seen: u64, + }, } impl ConfirmationTime { + /// Construct an unconfirmed variant using the given `last_seen` time in unix seconds. pub fn unconfirmed(last_seen: u64) -> Self { Self::Unconfirmed { last_seen } } + /// Returns whether [`ConfirmationTime`] is the confirmed variant. pub fn is_confirmed(&self) -> bool { matches!(self, Self::Confirmed { .. }) } @@ -154,8 +168,9 @@ impl Anchor for ConfirmationHeightAnchor { pub struct ConfirmationTimeAnchor { /// The anchor block. pub anchor_block: BlockId, - + /// The confirmation height of the chain data being anchored. pub confirmation_height: u32, + /// The confirmation time of the chain data being anchored. pub confirmation_time: u64, } diff --git a/crates/chain/src/indexed_tx_graph.rs b/crates/chain/src/indexed_tx_graph.rs index 000c1a6e..730b0434 100644 --- a/crates/chain/src/indexed_tx_graph.rs +++ b/crates/chain/src/indexed_tx_graph.rs @@ -1,3 +1,7 @@ +//! Contains the [`IndexedTxGraph`] structure and associated types. +//! +//! This is essentially a [`TxGraph`] combined with an indexer. + use alloc::vec::Vec; use bitcoin::{OutPoint, Transaction, TxOut}; diff --git a/crates/chain/src/lib.rs b/crates/chain/src/lib.rs index dc5261e2..ed167ebf 100644 --- a/crates/chain/src/lib.rs +++ b/crates/chain/src/lib.rs @@ -17,18 +17,23 @@ //! cache or how you fetch it. //! //! [Bitcoin Dev Kit]: https://bitcoindevkit.org/ + #![no_std] +#![warn(missing_docs)] + pub use bitcoin; mod spk_txout_index; pub use spk_txout_index::*; mod chain_data; pub use chain_data::*; pub mod indexed_tx_graph; +pub use indexed_tx_graph::IndexedTxGraph; pub mod keychain; pub mod local_chain; mod tx_data_traits; pub mod tx_graph; pub use tx_data_traits::*; +pub use tx_graph::TxGraph; mod chain_oracle; pub use chain_oracle::*; mod persist; diff --git a/crates/chain/src/local_chain.rs b/crates/chain/src/local_chain.rs index 7623b294..fe97e3f2 100644 --- a/crates/chain/src/local_chain.rs +++ b/crates/chain/src/local_chain.rs @@ -1,6 +1,8 @@ +//! The [`LocalChain`] is a local implementation of [`ChainOracle`]. + use core::convert::Infallible; -use alloc::collections::{BTreeMap, BTreeSet}; +use alloc::collections::BTreeMap; use bitcoin::BlockHash; use crate::{BlockId, ChainOracle}; @@ -59,6 +61,7 @@ impl From> for LocalChain { } impl LocalChain { + /// Contruct a [`LocalChain`] from a list of [`BlockId`]s. pub fn from_blocks(blocks: B) -> Self where B: IntoIterator, @@ -73,6 +76,7 @@ impl LocalChain { &self.blocks } + /// Get the chain tip. pub fn tip(&self) -> Option { self.blocks .iter() @@ -158,6 +162,9 @@ impl LocalChain { Ok(changeset) } + /// Derives a [`ChangeSet`] that assumes that there are no preceding changesets. + /// + /// The changeset returned will record additions of all blocks included in [`Self`]. pub fn initial_changeset(&self) -> ChangeSet { self.blocks .iter() @@ -165,10 +172,6 @@ impl LocalChain { .collect() } - pub fn heights(&self) -> BTreeSet { - self.blocks.keys().cloned().collect() - } - /// Insert a block of [`BlockId`] into the [`LocalChain`]. /// /// # Error @@ -225,8 +228,11 @@ impl std::error::Error for UpdateNotConnectedError {} /// Represents a failure when trying to insert a checkpoint into [`LocalChain`]. #[derive(Clone, Debug, PartialEq)] pub struct InsertBlockNotMatchingError { + /// The checkpoints' height. pub height: u32, + /// Original checkpoint's block hash. pub original_hash: BlockHash, + /// Update checkpoint's block hash. pub update_hash: BlockHash, } diff --git a/crates/chain/src/tx_graph.rs b/crates/chain/src/tx_graph.rs index a9475b00..bc72cc50 100644 --- a/crates/chain/src/tx_graph.rs +++ b/crates/chain/src/tx_graph.rs @@ -983,9 +983,13 @@ impl TxGraph { )] #[must_use] pub struct Additions { + /// Added transactions. pub txs: BTreeSet, + /// Added txouts. pub txouts: BTreeMap, + /// Added anchors. pub anchors: BTreeSet<(A, Txid)>, + /// Added last-seen unix timestamps of transactions. pub last_seen: BTreeMap, } diff --git a/crates/electrum/src/electrum_ext.rs b/crates/electrum/src/electrum_ext.rs index 908fdddc..1ec44d85 100644 --- a/crates/electrum/src/electrum_ext.rs +++ b/crates/electrum/src/electrum_ext.rs @@ -236,7 +236,6 @@ impl ElectrumExt for Client { populate_with_txids(self, anchor_block, &mut update, &mut txids.iter().cloned())?; - // [TODO] cache transactions to reduce bandwidth let _txs = populate_with_outpoints( self, anchor_block,