doc(chain): add section for non-recommended K to descriptor assignments
This commit is contained in:
parent
de53d72191
commit
86711d4f46
@ -160,19 +160,34 @@ const DEFAULT_LOOKAHEAD: u32 = 25;
|
|||||||
/// let new_spk_for_user = txout_index.reveal_next_spk(&MyKeychain::MyAppUser{ user_id: 42 });
|
/// let new_spk_for_user = txout_index.reveal_next_spk(&MyKeychain::MyAppUser{ user_id: 42 });
|
||||||
/// ```
|
/// ```
|
||||||
///
|
///
|
||||||
/// # Re-assigning descriptors
|
/// # Non-recommend keychain to descriptor assignments
|
||||||
///
|
///
|
||||||
/// Under the hood, the [`KeychainTxOutIndex`] uses a [`SpkTxOutIndex`] that keeps track of spks,
|
/// A keychain (`K`) is used to identify a descriptor. However, the following keychain to descriptor
|
||||||
/// indexed by descriptors. Users then assign or unassign keychains to those descriptors. It's
|
/// arrangements result in behavior that is harder to reason about and is not recommended.
|
||||||
/// important to note that descriptors, once added, never get removed from the [`SpkTxOutIndex`];
|
|
||||||
/// this is useful in case a user unassigns a keychain from a descriptor and after some time
|
|
||||||
/// assigns it again.
|
|
||||||
///
|
///
|
||||||
/// Additionally, although a keychain can only be assigned to one descriptor, different keychains
|
/// ## Multiple keychains identifying the same descriptor
|
||||||
/// can be assigned to the same descriptor. When a method returns spks/outpoints that is associated
|
///
|
||||||
/// with a descriptor, it may be associated with multiple keychain variants. The keychain variant
|
/// Although a single keychain variant can only identify a single descriptor, multiple keychain
|
||||||
/// with the higher rank will be returned. Rank is determined by the [`Ord`] implementation of the
|
/// variants can identify the same descriptor.
|
||||||
/// keychain type. Earlier keychain variants have higher rank.
|
///
|
||||||
|
/// If multiple keychains identify the same descriptor:
|
||||||
|
/// 1. Methods that take in a keychain (such as [`reveal_next_spk`]) will work normally when any
|
||||||
|
/// keychain (that identifies that descriptor) is passed in.
|
||||||
|
/// 2. Methods that return data which associates with a descriptor (such as [`outpoints`],
|
||||||
|
/// [`txouts`], [`unused_spks`], etc.) the method will return the highest-ranked keychain variant
|
||||||
|
/// that identifies the descriptor. Rank is determined by the [`Ord`] implementation of the keychain
|
||||||
|
/// type.
|
||||||
|
///
|
||||||
|
/// This arrangement is not recommended since some methods will return a single keychain variant
|
||||||
|
/// even though multiple keychain variants identify the same descriptor.
|
||||||
|
///
|
||||||
|
/// ## Reassigning the descriptor of a single keychain
|
||||||
|
///
|
||||||
|
/// Descriptors added to [`KeychainTxOutIndex`] are never removed. However, a keychain that
|
||||||
|
/// identifies a descriptor can be reassigned to identify a different descriptor. This may result in
|
||||||
|
/// a situation where a descriptor has no associated keychain(s), and relevant [`TxOut`]s,
|
||||||
|
/// [`OutPoint`]s and [`Script`]s (of that descriptor) will not be return by [`KeychainTxOutIndex`].
|
||||||
|
/// Therefore, reassigning the descriptor of a single keychain is not recommended.
|
||||||
///
|
///
|
||||||
/// [`Ord`]: core::cmp::Ord
|
/// [`Ord`]: core::cmp::Ord
|
||||||
/// [`SpkTxOutIndex`]: crate::spk_txout_index::SpkTxOutIndex
|
/// [`SpkTxOutIndex`]: crate::spk_txout_index::SpkTxOutIndex
|
||||||
@ -186,6 +201,9 @@ const DEFAULT_LOOKAHEAD: u32 = 25;
|
|||||||
/// [`new`]: KeychainTxOutIndex::new
|
/// [`new`]: KeychainTxOutIndex::new
|
||||||
/// [`unbounded_spk_iter`]: KeychainTxOutIndex::unbounded_spk_iter
|
/// [`unbounded_spk_iter`]: KeychainTxOutIndex::unbounded_spk_iter
|
||||||
/// [`all_unbounded_spk_iters`]: KeychainTxOutIndex::all_unbounded_spk_iters
|
/// [`all_unbounded_spk_iters`]: KeychainTxOutIndex::all_unbounded_spk_iters
|
||||||
|
/// [`outpoints`]: KeychainTxOutIndex::outpoints
|
||||||
|
/// [`txouts`]: KeychainTxOutIndex::txouts
|
||||||
|
/// [`unused_spks`]: KeychainTxOutIndex::unused_spks
|
||||||
#[derive(Clone, Debug)]
|
#[derive(Clone, Debug)]
|
||||||
pub struct KeychainTxOutIndex<K> {
|
pub struct KeychainTxOutIndex<K> {
|
||||||
inner: SpkTxOutIndex<(DescriptorId, u32)>,
|
inner: SpkTxOutIndex<(DescriptorId, u32)>,
|
||||||
|
Loading…
x
Reference in New Issue
Block a user