Skip to content

Commit 40790d0

Browse files
evanlinjinevanlinjin
committed
docs(chain): Tighten CanonicalView documentation
1 parent f444a8d commit 40790d0

1 file changed

Lines changed: 6 additions & 123 deletions

File tree

‎crates/chain/src/canonical_view.rs‎

Lines changed: 6 additions & 123 deletions
Original file line numberDiff line numberDiff line change
@@ -81,31 +81,9 @@ impl<A: Anchor> CanonicalView<A> {
8181
/// This constructor analyzes the given [`TxGraph`] and creates a canonical view of all
8282
/// transactions, resolving conflicts and ordering them according to their chain position.
8383
///
84-
/// # Arguments
85-
///
86-
/// * `tx_graph` - The transaction graph containing all known transactions
87-
/// * `chain` - A chain oracle for determining block inclusion
88-
/// * `chain_tip` - The current chain tip to use for canonicalization
89-
/// * `params` - Parameters controlling the canonicalization process
90-
///
9184
/// # Returns
9285
///
9386
/// Returns `Ok(CanonicalView)` on success, or an error if the chain oracle fails.
94-
///
95-
/// # Example
96-
///
97-
/// ```
98-
/// # use bdk_chain::{CanonicalView, TxGraph, CanonicalizationParams, local_chain::LocalChain};
99-
/// # use bdk_core::BlockId;
100-
/// # use bitcoin::hashes::Hash;
101-
/// # let tx_graph = TxGraph::<BlockId>::default();
102-
/// # let chain = LocalChain::from_blocks([(0, bitcoin::BlockHash::all_zeros())].into_iter().collect()).unwrap();
103-
/// let chain_tip = chain.tip().block_id();
104-
/// let params = CanonicalizationParams::default();
105-
///
106-
/// let view = CanonicalView::new(&tx_graph, &chain, chain_tip, params)?;
107-
/// # Ok::<_, Box<dyn std::error::Error>>(())
108-
/// ```
10987
pub fn new<'g, C>(
11088
tx_graph: &'g TxGraph<A>,
11189
chain: &'g C,
@@ -213,21 +191,6 @@ impl<A: Anchor> CanonicalView<A> {
213191
///
214192
/// Returns `Some(CanonicalViewTx)` if the transaction exists in the canonical view,
215193
/// or `None` if the transaction doesn't exist or was excluded due to conflicts.
216-
///
217-
/// # Example
218-
///
219-
/// ```
220-
/// # use bdk_chain::{CanonicalView, TxGraph, local_chain::LocalChain};
221-
/// # use bdk_core::BlockId;
222-
/// # use bitcoin::hashes::Hash;
223-
/// # let tx_graph = TxGraph::<BlockId>::default();
224-
/// # let chain = LocalChain::from_blocks([(0, bitcoin::BlockHash::all_zeros())].into_iter().collect()).unwrap();
225-
/// # let view = CanonicalView::new(&tx_graph, &chain, chain.tip().block_id(), Default::default()).unwrap();
226-
/// # let txid = bitcoin::Txid::all_zeros();
227-
/// if let Some(canonical_tx) = view.tx(txid) {
228-
/// println!("Found tx {} at position {:?}", canonical_tx.txid, canonical_tx.pos);
229-
/// }
230-
/// ```
231194
pub fn tx(&self, txid: Txid) -> Option<CanonicalTx<A>> {
232195
self.txs
233196
.get(&txid)
@@ -244,25 +207,6 @@ impl<A: Anchor> CanonicalView<A> {
244207
/// - The transaction doesn't exist in the canonical view
245208
/// - The output index is out of bounds
246209
/// - The transaction was excluded due to conflicts
247-
///
248-
/// # Example
249-
///
250-
/// ```
251-
/// # use bdk_chain::{CanonicalView, TxGraph, local_chain::LocalChain};
252-
/// # use bdk_core::BlockId;
253-
/// # use bitcoin::{OutPoint, hashes::Hash};
254-
/// # let tx_graph = TxGraph::<BlockId>::default();
255-
/// # let chain = LocalChain::from_blocks([(0, bitcoin::BlockHash::all_zeros())].into_iter().collect()).unwrap();
256-
/// # let view = CanonicalView::new(&tx_graph, &chain, chain.tip().block_id(), Default::default()).unwrap();
257-
/// # let outpoint = OutPoint::default();
258-
/// if let Some(txout) = view.txout(outpoint) {
259-
/// if txout.spent_by.is_some() {
260-
/// println!("Output is spent");
261-
/// } else {
262-
/// println!("Output is unspent with value: {}", txout.txout.value);
263-
/// }
264-
/// }
265-
/// ```
266210
pub fn txout(&self, op: OutPoint) -> Option<FullTxOut<A>> {
267211
let (tx, pos) = self.txs.get(&op.txid)?;
268212
let vout: usize = op.vout.try_into().ok()?;
@@ -315,12 +259,8 @@ impl<A: Anchor> CanonicalView<A> {
315259
/// of `(identifier, full_txout)` pairs for outpoints that exist in the canonical view.
316260
/// Non-existent outpoints are silently filtered out.
317261
///
318-
/// The identifier type `O` can be any cloneable type and is passed through unchanged.
319-
/// This is useful for tracking which outpoints correspond to which addresses or keys.
320-
///
321-
/// # Arguments
322-
///
323-
/// * `outpoints` - An iterator of `(identifier, outpoint)` pairs to look up
262+
/// The identifier type `O` is useful for tracking which outpoints correspond to which addresses
263+
/// or keys.
324264
///
325265
/// # Example
326266
///
@@ -333,7 +273,7 @@ impl<A: Anchor> CanonicalView<A> {
333273
/// # let view = CanonicalView::new(&tx_graph, &chain, chain.tip().block_id(), Default::default()).unwrap();
334274
/// # let indexer = KeychainTxOutIndex::<&str>::default();
335275
/// // Get all outputs from an indexer
336-
/// for (keychain, txout) in view.filter_outpoints(indexer.outpoints().into_iter().map(|(k, op)| (k.clone(), *op))) {
276+
/// for (keychain, txout) in view.filter_outpoints(indexer.outpoints().clone()) {
337277
/// println!("{}: {} sats", keychain.0, txout.txout.value);
338278
/// }
339279
/// ```
@@ -351,10 +291,6 @@ impl<A: Anchor> CanonicalView<A> {
351291
/// Similar to [`filter_outpoints`](Self::filter_outpoints), but only returns outputs that
352292
/// have not been spent. This is useful for finding available UTXOs for spending.
353293
///
354-
/// # Arguments
355-
///
356-
/// * `outpoints` - An iterator of `(identifier, outpoint)` pairs to look up
357-
///
358294
/// # Example
359295
///
360296
/// ```
@@ -366,7 +302,7 @@ impl<A: Anchor> CanonicalView<A> {
366302
/// # let view = CanonicalView::new(&tx_graph, &chain, chain.tip().block_id(), Default::default()).unwrap();
367303
/// # let indexer = KeychainTxOutIndex::<&str>::default();
368304
/// // Get unspent outputs (UTXOs) from an indexer
369-
/// for (keychain, utxo) in view.filter_unspent_outpoints(indexer.outpoints().into_iter().map(|(k, op)| (k.clone(), *op))) {
305+
/// for (keychain, utxo) in view.filter_unspent_outpoints(indexer.outpoints().clone()) {
370306
/// println!("{} UTXO: {} sats", keychain.0, utxo.txout.value);
371307
/// }
372308
/// ```
@@ -395,25 +331,12 @@ impl<A: Anchor> CanonicalView<A> {
395331
///
396332
/// # Minimum Confirmations
397333
///
398-
/// The `min_confirmations` parameter controls when outputs are considered confirmed:
399-
///
400-
/// - `0` or `1`: Standard behavior - require at least 1 confirmation
401-
/// - `6`: Conservative - require 6 confirmations (often used for high-value transactions)
402-
/// - `100+`: May be used for coinbase outputs which require 100 confirmations
334+
/// The `min_confirmations` parameter controls when outputs are considered confirmed. A
335+
/// `min_confirmations` value of `0` is equivalent to `1` (require at least 1 confirmation).
403336
///
404337
/// Outputs with fewer than `min_confirmations` are categorized as pending (trusted or
405338
/// untrusted based on the trust predicate).
406339
///
407-
/// # Balance Categories
408-
///
409-
/// The returned [`Balance`] contains four categories:
410-
///
411-
/// - `confirmed`: Outputs with ≥ `min_confirmations` and spendable
412-
/// - `trusted_pending`: Unconfirmed or insufficiently confirmed outputs from trusted scripts
413-
/// - `untrusted_pending`: Unconfirmed or insufficiently confirmed outputs from untrusted
414-
/// scripts
415-
/// - `immature`: Coinbase outputs that haven't reached maturity (100 confirmations)
416-
///
417340
/// # Example
418341
///
419342
/// ```
@@ -430,13 +353,6 @@ impl<A: Anchor> CanonicalView<A> {
430353
/// |_keychain, _script| true, // Trust all outputs
431354
/// 6, // Require 6 confirmations
432355
/// );
433-
///
434-
/// // Or calculate balance trusting no outputs
435-
/// let untrusted_balance = view.balance(
436-
/// indexer.outpoints().into_iter().map(|(k, op)| (k.clone(), *op)),
437-
/// |_keychain, _script| false, // Trust no outputs
438-
/// 1,
439-
/// );
440356
/// ```
441357
pub fn balance<'v, O: Clone + 'v>(
442358
&'v self,
@@ -498,39 +414,6 @@ impl<A: Anchor> CanonicalView<A> {
498414
/// commonly used with
499415
/// [`SyncRequestBuilder::expected_spk_txids`](bdk_core::spk_client::SyncRequestBuilder::expected_spk_txids)
500416
/// to inform sync operations about known transactions.
501-
///
502-
/// # Arguments
503-
///
504-
/// * `indexer` - A script pubkey indexer (e.g., `KeychainTxOutIndex`) that tracks which scripts
505-
/// are relevant
506-
/// * `spk_index_range` - A range bound to constrain which script indices to include. Use `..`
507-
/// for all indices.
508-
///
509-
/// # Returns
510-
///
511-
/// An iterator of `(script_pubkey, txid)` pairs for all canonical transactions that involve
512-
/// the specified scripts.
513-
///
514-
/// # Example
515-
///
516-
/// ```
517-
/// # use bdk_chain::{CanonicalView, TxGraph, local_chain::LocalChain, spk_txout::SpkTxOutIndex};
518-
/// # use bdk_core::BlockId;
519-
/// # use bitcoin::hashes::Hash;
520-
/// # let tx_graph = TxGraph::<BlockId>::default();
521-
/// # let chain = LocalChain::from_blocks([(0, bitcoin::BlockHash::all_zeros())].into_iter().collect()).unwrap();
522-
/// # let view = CanonicalView::new(&tx_graph, &chain, chain.tip().block_id(), Default::default()).unwrap();
523-
/// # let indexer = SpkTxOutIndex::<u32>::default();
524-
/// // List all expected transactions for script indices 0-100
525-
/// for (script, txid) in view.list_expected_spk_txids(&indexer, 0..100) {
526-
/// println!("Script {:?} appears in transaction {}", script, txid);
527-
/// }
528-
///
529-
/// // List all expected transactions (no range constraint)
530-
/// for (script, txid) in view.list_expected_spk_txids(&indexer, ..) {
531-
/// println!("Found transaction {} for script", txid);
532-
/// }
533-
/// ```
534417
pub fn list_expected_spk_txids<'v, I>(
535418
&'v self,
536419
indexer: &'v impl AsRef<SpkTxOutIndex<I>>,

0 commit comments

Comments
 (0)