Line data    Source code

       1             : // Copyright (c) 2026 The Dash Core developers
       2             : // Distributed under the MIT software license, see the accompanying
       3             : // file COPYING or http://www.opensource.org/licenses/mit-license.php.
       4             : 
       5             : #ifndef BITCOIN_INDEX_ADDRESSINDEX_H
       6             : #define BITCOIN_INDEX_ADDRESSINDEX_H
       7             : 
       8             : #include <index/addressindex_types.h>
       9             : #include <index/base.h>
      10             : 
      11             : #include <memory>
      12             : #include <vector>
      13             : 
      14             : static constexpr bool DEFAULT_ADDRESSINDEX{false};
      15             : 
      16             : /**
      17             :  * AddressIndex is an async index that maintains two separate databases:
      18             :  * 1. Address transaction history (all transactions touching an address)
      19             :  * 2. Address unspent outputs (UTXO set filtered by address)
      20             :  *
      21             :  * Uses undo data to access historical UTXO information, requiring undo files
      22             :  * to be available (incompatible with pruned nodes).
      23             :  */
      24             : class AddressIndex final : public BaseIndex
      25             : {
      26             : protected:
      27             :     class DB;
      28             : 
      29             : private:
      30             :     const std::unique_ptr<DB> m_db;
      31             : 
      32             : protected:
      33             :     class DB : public BaseIndex::DB
      34             :     {
      35             :     public:
      36             :         explicit DB(size_t n_cache_size, bool f_memory = false, bool f_wipe = false);
      37             : 
      38             :         /// Write a batch of address index entries
      39             :         bool WriteBatch(const std::vector<CAddressIndexEntry>& address_entries,
      40             :                         const std::vector<CAddressUnspentIndexEntry>& unspent_entries);
      41             : 
      42             :         /// Read address transaction history
      43             :         bool ReadAddressIndex(const uint160& address_hash, const AddressType type,
      44             :                               std::vector<CAddressIndexEntry>& entries, const int32_t start = 0, const int32_t end = 0);
      45             : 
      46             :         /// Read address unspent outputs
      47             :         bool ReadAddressUnspentIndex(const uint160& address_hash, const AddressType type,
      48             :                                      std::vector<CAddressUnspentIndexEntry>& entries, const bool height_sort = false);
      49             : 
      50             :         /// Erase address transaction history entries
      51             :         bool EraseAddressIndex(const std::vector<CAddressIndexEntry>& entries);
      52             : 
      53             :         /// Update address unspent index (handles both adds and deletes)
      54             :         bool UpdateAddressUnspentIndex(const std::vector<CAddressUnspentIndexEntry>& entries);
      55             : 
      56             :         /// Atomically erase address history entries and update unspent outputs during rewind.
      57             :         bool RewindBatch(const std::vector<CAddressIndexEntry>& address_entries,
      58             :                          const std::vector<CAddressUnspentIndexEntry>& unspent_entries);
      59             :     };
      60             : 
      61             :     /// Override to return false - we need undo data
      62        1634 :     bool AllowPrune() const override { return false; }
      63             : 
      64             :     /// Write block data to the index databases
      65             :     bool WriteBlock(const CBlock& block, const CBlockIndex* pindex) override;
      66             : 
      67             :     /// Custom rewind to handle both transaction history and unspent index
      68             :     bool Rewind(const CBlockIndex* current_tip, const CBlockIndex* new_tip) override;
      69             : 
      70             :     BaseIndex::DB& GetDB() const override;
      71             : 
      72         150 :     const char* GetName() const override { return "addressindex"; }
      73             : 
      74             : public:
      75             :     /// Constructs the index, which becomes available to be queried
      76             :     explicit AddressIndex(size_t n_cache_size, bool f_memory = false, bool f_wipe = false);
      77             : 
      78             :     /// Destructor
      79             :     virtual ~AddressIndex() override;
      80             : 
      81             :     /// Query address transaction history
      82             :     bool GetAddressIndex(const uint160& address_hash, const AddressType type, std::vector<CAddressIndexEntry>& entries,
      83             :                          const int32_t start = 0, const int32_t end = 0) const;
      84             : 
      85             :     /// Query address unspent outputs
      86             :     bool GetAddressUnspentIndex(const uint160& address_hash, const AddressType type,
      87             :                                 std::vector<CAddressUnspentIndexEntry>& entries, const bool height_sort = false) const;
      88             : };
      89             : 
      90             : /// Global AddressIndex instance
      91             : extern std::unique_ptr<AddressIndex> g_addressindex;
      92             : 
      93             : #endif // BITCOIN_INDEX_ADDRESSINDEX_H