chore(chain): document insert_descriptor invariants better

diff --git a/crates/chain/src/keychain/txout_index.rs b/crates/chain/src/keychain/txout_index.rs
index 65dae93944c4b393994a497788342b0388c04b2d..d47aa843f15dfd4a603489aa9d48eae7b8df47f6 100644 (file)
--- a/crates/chain/src/keychain/txout_index.rs
+++ b/crates/chain/src/keychain/txout_index.rs
@@ -27,7 +27,11 @@ pub const DEFAULT_LOOKAHEAD: u32 = 25;
 ///
 /// There is a strict 1-to-1 relationship between descriptors and keychains. Each keychain has one
 /// and only one descriptor and each descriptor has one and only one keychain. The
-/// [`insert_descriptor`] method will return an error if you try and violate this invariant.
+/// [`insert_descriptor`] method will return an error if you try and violate this invariant. This
+/// rule is a proxy for a stronger rule: no two descriptors should produce the same script pubkey.
+/// Having two descriptors produce the same script pubkey should cause whichever keychain derives the
+/// script pubkey first to be the effective owner of it but you should not rely on this behaviour.
+/// ⚠ It is up you, the developer, not to violate this invariant.
 ///
 /// # Revealed script pubkeys
 ///