From 2b3733bf112a51479ff714292c79553ffd42b759 Mon Sep 17 00:00:00 2001
From: evoskuil <eric@voskuil.org>
Date: Mon, 20 Apr 2026 23:36:44 -0400
Subject: [PATCH] Documentation comments on unspent and history.

---
 include/bitcoin/database/types/history.hpp | 16 ++++++++++++++++
 include/bitcoin/database/types/unspent.hpp | 13 +++++++++++++
 2 files changed, 29 insertions(+)

diff --git a/include/bitcoin/database/types/history.hpp b/include/bitcoin/database/types/history.hpp
index f2db8f30..b34ba023 100644
--- a/include/bitcoin/database/types/history.hpp
+++ b/include/bitcoin/database/types/history.hpp
@@ -27,21 +27,37 @@ namespace database {
 
 struct BCD_API history
 {
+    /// unrooted_height maps to -1 in the Electrum json-rpc.
     static constexpr size_t rooted_height = zero;
     static constexpr size_t unrooted_height = max_size_t;
     static constexpr size_t unconfirmed_position = max_size_t;
     static constexpr uint64_t missing_prevout = max_uint64;
 
+    /// Filter out invalid history elements (txs) and sort.
     static void filter_sort_and_dedup(std::vector<history>& history) NOEXCEPT;
 
+    /// The tx is valid (not defaulted).
     bool valid() const NOEXCEPT;
+
+    /// The unconfirmed tx is rooted in chain (all prevouts confirmed).
     bool rooted() const NOEXCEPT;
+
+    /// The tx is confirmed in a block.
     bool confirmed() const NOEXCEPT;
+
+    /// Comparison operator based on Electrum history status sort.
     bool operator<(const history& other) const NOEXCEPT;
+
+    /// Equivalence: !LT && !GT (note that fee is never considered).
     bool operator==(const history& other) const NOEXCEPT;
 
+    /// Tx hash and block height, or rooted/unrooted_height if unconfirmed.
     checkpoint tx{};
+
+    /// Tx fee, or history::missing_prevout for missing, confirmed, or -fee.
     uint64_t fee{};
+
+    /// Tx's position in confirmed block, or history::unconfirmed_position.
     size_t position{};
 };
 
diff --git a/include/bitcoin/database/types/unspent.hpp b/include/bitcoin/database/types/unspent.hpp
index bcca66bc..0e35707f 100644
--- a/include/bitcoin/database/types/unspent.hpp
+++ b/include/bitcoin/database/types/unspent.hpp
@@ -30,15 +30,28 @@ struct BCD_API unspent
     static constexpr size_t unused_height = zero;
     static constexpr size_t unconfirmed_position = max_size_t;
 
+    /// Filter out invalid unspent output elements and sort.
     static void filter_sort_and_dedup(std::vector<unspent>& unspent) NOEXCEPT;
 
+    /// The outpoint is valid (not defaulted).
     bool valid() const NOEXCEPT;
+
+    /// The tx is confirmed in a block.
     bool confirmed() const NOEXCEPT;
+
+    /// Comparison operator based on Electrum unspent status sort.
     bool operator<(const unspent& other) const NOEXCEPT;
+
+    /// Equivalence: !LT && !GT (note that fee is never considered).
     bool operator==(const unspent& other) const NOEXCEPT;
 
+    /// Tx hash and index of output within the tx.
     outpoint out{};
+
+    /// Tx's block height if confirmed, or unspent::unused_height.
     size_t height{};
+
+    /// Tx's position in confirmed block, or unspent::unconfirmed_position.
     size_t position{};
 };