feat: add address/spent/timestamp index + RPCs (Bitpay insight / PIVX)

Add the standard address-index feature so the daemon exposes the RPCs
getaddressbalance, getaddressutxos, getaddresstxids, getaddressdeltas,
getaddressmempool and getspentinfo, gated on -addressindex / -spentindex /
-timestampindex (network-agnostic: works on mainnet, testnet and regtest).

- addressindex.h / spentindex.h: key/value types (CAddressIndexKey,
  CAddressUnspentKey/Value, CSpentIndexKey/Value, CTimestampIndexKey, iterator
  keys, mempool delta types). Heights serialized big-endian for LevelDB key
  ordering.
- serialize.h: ser_writedata*/ser_readdata* stream byte helpers (incl. *be).
- txdb.[h|cpp]: DB prefixes (d/u/p/s/z) + Write/Erase/Read address index,
  Update/Read address-unspent, Update/Read spent index, Write/Read timestamp
  index. Read loops check the type byte before deserializing the key so a
  prefix scan that runs into a shorter-keyed family does not over-read.
- main.[h|cpp]: globals fAddressIndex/fSpentIndex/fTimestampIndex; build index
  entries from each tx's vins (spends) and vouts (receives) in ConnectBlock and
  revert them symmetrically in DisconnectBlock (correct on reorg); GetAddressIndex
  / GetAddressUnspent / GetSpentIndex / GetTimestampIndex helpers; persist flags
  via the block tree db and require -reindex when they change; feed the mempool
  index from AcceptToMemoryPool.
- txmempool.[h|cpp]: addressDeltaMap + addAddressIndex/getAddressIndex/
  removeAddressIndex and the mempool spent index so getaddressmempool/getspentinfo
  see unconfirmed entries.
- base58.[h|cpp]: CBitcoinAddress::GetIndexKey to turn an address into (hash,type).
- rpcaddressindex.cpp + rpcserver.[h|cpp] table + rpcclient.cpp conversion table:
  the six RPCs, matching PIVX return shapes.
- init.cpp: read the flags before block index load, add -reindex-required checks
  and help text.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: NateIsern

src/Makefile.am

@@ -75,10 +75,12 @@ endif
 # faircoin core #
 BITCOIN_CORE_H = \
   activemasternode.h \
+  addressindex.h \
   addrman.h \
   alert.h \
   allocators.h \
   amount.h \
+  spentindex.h \
   base58.h \
   bip38.h \
   bloom.h \
@@ -197,6 +199,7 @@ libbitcoin_server_a_SOURCES = \
   noui.cpp \
   pow.cpp \
   rest.cpp \
+  rpcaddressindex.cpp \
   rpcblockchain.cpp \
   rpcmasternode.cpp \
   rpcmasternode-budget.cpp \

src/addressindex.h

@@ -0,0 +1,331 @@
+// Copyright (c) 2009-2010 Satoshi Nakamoto
+// Copyright (c) 2009-2014 The Bitcoin developers
+// Copyright (c) 2017 The Bitcore developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+#ifndef BITCOIN_ADDRESSINDEX_H
+#define BITCOIN_ADDRESSINDEX_H
+
+#include "amount.h"
+#include "script/script.h"
+#include "serialize.h"
+#include "uint256.h"
+
+#include <utility>
+#include <vector>
+
+struct CAddressUnspentKey {
+    unsigned int type;
+    uint160 hashBytes;
+    uint256 txhash;
+    size_t index;
+
+    size_t GetSerializeSize(int nType, int nVersion) const
+    {
+        return 57;
+    }
+    template <typename Stream>
+    void Serialize(Stream& s, int nType, int nVersion) const
+    {
+        ser_writedata8(s, type);
+        hashBytes.Serialize(s, nType, nVersion);
+        txhash.Serialize(s, nType, nVersion);
+        ser_writedata32(s, index);
+    }
+    template <typename Stream>
+    void Unserialize(Stream& s, int nType, int nVersion)
+    {
+        type = ser_readdata8(s);
+        hashBytes.Unserialize(s, nType, nVersion);
+        txhash.Unserialize(s, nType, nVersion);
+        index = ser_readdata32(s);
+    }
+
+    CAddressUnspentKey(unsigned int addressType, uint160 addressHash, uint256 txid, size_t indexValue)
+    {
+        type = addressType;
+        hashBytes = addressHash;
+        txhash = txid;
+        index = indexValue;
+    }
+
+    CAddressUnspentKey()
+    {
+        SetNull();
+    }
+
+    void SetNull()
+    {
+        type = 0;
+        hashBytes.SetNull();
+        txhash.SetNull();
+        index = 0;
+    }
+};
+
+struct CAddressUnspentValue {
+    CAmount satoshis;
+    CScript script;
+    int blockHeight;
+
+    ADD_SERIALIZE_METHODS;
+
+    template <typename Stream, typename Operation>
+    inline void SerializationOp(Stream& s, Operation ser_action, int nType, int nVersion)
+    {
+        READWRITE(satoshis);
+        READWRITE(script);
+        READWRITE(blockHeight);
+    }
+
+    CAddressUnspentValue(CAmount sats, CScript scriptPubKey, int height)
+    {
+        satoshis = sats;
+        script = scriptPubKey;
+        blockHeight = height;
+    }
+
+    CAddressUnspentValue()
+    {
+        SetNull();
+    }
+
+    void SetNull()
+    {
+        satoshis = -1;
+        script.clear();
+        blockHeight = 0;
+    }
+
+    bool IsNull() const
+    {
+        return (satoshis == -1);
+    }
+};
+
+struct CAddressIndexKey {
+    unsigned int type;
+    uint160 hashBytes;
+    int blockHeight;
+    unsigned int txindex;
+    uint256 txhash;
+    size_t index;
+    bool spending;
+
+    size_t GetSerializeSize(int nType, int nVersion) const
+    {
+        return 66;
+    }
+    template <typename Stream>
+    void Serialize(Stream& s, int nType, int nVersion) const
+    {
+        ser_writedata8(s, type);
+        hashBytes.Serialize(s, nType, nVersion);
+        // Heights are stored big-endian for key sorting in LevelDB
+        ser_writedata32be(s, blockHeight);
+        ser_writedata32be(s, txindex);
+        txhash.Serialize(s, nType, nVersion);
+        ser_writedata32(s, index);
+        char f = spending;
+        ser_writedata8(s, f);
+    }
+    template <typename Stream>
+    void Unserialize(Stream& s, int nType, int nVersion)
+    {
+        type = ser_readdata8(s);
+        hashBytes.Unserialize(s, nType, nVersion);
+        blockHeight = ser_readdata32be(s);
+        txindex = ser_readdata32be(s);
+        txhash.Unserialize(s, nType, nVersion);
+        index = ser_readdata32(s);
+        char f = ser_readdata8(s);
+        spending = f;
+    }
+
+    CAddressIndexKey(unsigned int addressType, uint160 addressHash, int height, int blockindex,
+                     uint256 txid, size_t indexValue, bool isSpending)
+    {
+        type = addressType;
+        hashBytes = addressHash;
+        blockHeight = height;
+        txindex = blockindex;
+        txhash = txid;
+        index = indexValue;
+        spending = isSpending;
+    }
+
+    CAddressIndexKey()
+    {
+        SetNull();
+    }
+
+    void SetNull()
+    {
+        type = 0;
+        hashBytes.SetNull();
+        blockHeight = 0;
+        txindex = 0;
+        txhash.SetNull();
+        index = 0;
+        spending = false;
+    }
+};
+
+struct CAddressIndexIteratorKey {
+    unsigned int type;
+    uint160 hashBytes;
+
+    size_t GetSerializeSize(int nType, int nVersion) const
+    {
+        return 21;
+    }
+    template <typename Stream>
+    void Serialize(Stream& s, int nType, int nVersion) const
+    {
+        ser_writedata8(s, type);
+        hashBytes.Serialize(s, nType, nVersion);
+    }
+    template <typename Stream>
+    void Unserialize(Stream& s, int nType, int nVersion)
+    {
+        type = ser_readdata8(s);
+        hashBytes.Unserialize(s, nType, nVersion);
+    }
+
+    CAddressIndexIteratorKey(unsigned int addressType, uint160 addressHash)
+    {
+        type = addressType;
+        hashBytes = addressHash;
+    }
+
+    CAddressIndexIteratorKey()
+    {
+        SetNull();
+    }
+
+    void SetNull()
+    {
+        type = 0;
+        hashBytes.SetNull();
+    }
+};
+
+struct CAddressIndexIteratorHeightKey {
+    unsigned int type;
+    uint160 hashBytes;
+    int blockHeight;
+
+    size_t GetSerializeSize(int nType, int nVersion) const
+    {
+        return 25;
+    }
+    template <typename Stream>
+    void Serialize(Stream& s, int nType, int nVersion) const
+    {
+        ser_writedata8(s, type);
+        hashBytes.Serialize(s, nType, nVersion);
+        ser_writedata32be(s, blockHeight);
+    }
+    template <typename Stream>
+    void Unserialize(Stream& s, int nType, int nVersion)
+    {
+        type = ser_readdata8(s);
+        hashBytes.Unserialize(s, nType, nVersion);
+        blockHeight = ser_readdata32be(s);
+    }
+
+    CAddressIndexIteratorHeightKey(unsigned int addressType, uint160 addressHash, int height)
+    {
+        type = addressType;
+        hashBytes = addressHash;
+        blockHeight = height;
+    }
+
+    CAddressIndexIteratorHeightKey()
+    {
+        SetNull();
+    }
+
+    void SetNull()
+    {
+        type = 0;
+        hashBytes.SetNull();
+        blockHeight = 0;
+    }
+};
+
+struct CTimestampIndexIteratorKey {
+    unsigned int timestamp;
+
+    size_t GetSerializeSize(int nType, int nVersion) const
+    {
+        return 4;
+    }
+    template <typename Stream>
+    void Serialize(Stream& s, int nType, int nVersion) const
+    {
+        ser_writedata32be(s, timestamp);
+    }
+    template <typename Stream>
+    void Unserialize(Stream& s, int nType, int nVersion)
+    {
+        timestamp = ser_readdata32be(s);
+    }
+
+    CTimestampIndexIteratorKey(unsigned int time)
+    {
+        timestamp = time;
+    }
+
+    CTimestampIndexIteratorKey()
+    {
+        SetNull();
+    }
+
+    void SetNull()
+    {
+        timestamp = 0;
+    }
+};
+
+struct CTimestampIndexKey {
+    unsigned int timestamp;
+    uint256 blockHash;
+
+    size_t GetSerializeSize(int nType, int nVersion) const
+    {
+        return 36;
+    }
+    template <typename Stream>
+    void Serialize(Stream& s, int nType, int nVersion) const
+    {
+        ser_writedata32be(s, timestamp);
+        blockHash.Serialize(s, nType, nVersion);
+    }
+    template <typename Stream>
+    void Unserialize(Stream& s, int nType, int nVersion)
+    {
+        timestamp = ser_readdata32be(s);
+        blockHash.Unserialize(s, nType, nVersion);
+    }
+
+    CTimestampIndexKey(unsigned int time, uint256 hash)
+    {
+        timestamp = time;
+        blockHash = hash;
+    }
+
+    CTimestampIndexKey()
+    {
+        SetNull();
+    }
+
+    void SetNull()
+    {
+        timestamp = 0;
+        blockHash.SetNull();
+    }
+};
+
+#endif // BITCOIN_ADDRESSINDEX_H

src/base58.cpp

@@ -293,6 +293,23 @@ bool CBitcoinAddress::IsScript() const
     return IsValid() && vchVersion == Params().Base58Prefix(CChainParams::SCRIPT_ADDRESS);
 }
 
+bool CBitcoinAddress::GetIndexKey(uint160& hashBytes, int& type) const
+{
+    if (!IsValid()) {
+        return false;
+    } else if (vchVersion == Params().Base58Prefix(CChainParams::PUBKEY_ADDRESS)) {
+        memcpy(&hashBytes, &vchData[0], 20);
+        type = 1;
+        return true;
+    } else if (vchVersion == Params().Base58Prefix(CChainParams::SCRIPT_ADDRESS)) {
+        memcpy(&hashBytes, &vchData[0], 20);
+        type = 2;
+        return true;
+    }
+
+    return false;
+}
+
 void CBitcoinSecret::SetKey(const CKey& vchSecret)
 {
     assert(vchSecret.IsValid());

src/base58.h

@@ -122,6 +122,7 @@ class CBitcoinAddress : public CBase58Data
 
     CTxDestination Get() const;
     bool GetKeyID(CKeyID& keyID) const;
+    bool GetIndexKey(uint160& hashBytes, int& type) const;
     bool IsScript() const;
 };