// Copyright (c) 2014-2025 The Dash Core developers // Distributed under the MIT/X11 software license, see the accompanying // file COPYING or http://www.opensource.org/licenses/mit-license.php. #ifndef BITCOIN_GOVERNANCE_GOVERNANCE_H #define BITCOIN_GOVERNANCE_GOVERNANCE_H #include #include #include #include // IWYU pragma: export #include #include #include #include #include #include #include #include #include #include #include class CBloomFilter; class CBlockIndex; class CDataStream; class CDeterministicMNList; class CDeterministicMNManager; class ChainstateManager; template class CFlatDB; class CGovernanceException; class CGovernanceObject; class CInv; class CMasternodeMetaMan; class CMasternodeSync; class CService; struct RPCResult; class UniValue; namespace governance { class CollateralSource; class SuperblockManager; struct OrphanVote { CGovernanceVote vote; NodeSeconds expiration; OrphanVote() = default; OrphanVote(const CGovernanceVote& vote, NodeSeconds expiration) : vote(vote), expiration(expiration) {} SERIALIZE_METHODS(OrphanVote, obj) { // Preserve the historical integer Unix-seconds representation on disk. READWRITE(obj.vote, Using>(obj.expiration)); } }; inline bool operator<(const OrphanVote& lhs, const OrphanVote& rhs) { // Equal signed fields may arrive authenticated by different voting/operator keys. if (lhs.vote == rhs.vote) return lhs.vote.GetSignatureSize() < rhs.vote.GetSignatureSize(); return lhs.vote < rhs.vote; } // Orphan votes are not scarce: one masternode key can sign any number of votes naming parents that // do not exist. Each masternode is therefore limited to its own share of the cache, and the cache as // a whole holds about 40 MB at most (roughly 800 bytes per entry). Filling it takes the keys of 500 // masternodes, because only recently signed votes are held. static constexpr size_t MAX_ORPHAN_VOTES{50'000}; static constexpr size_t MAX_ORPHAN_VOTES_PER_MN{100}; // A vote stays valid for as long as its masternode's key does, so anyone can replay a masternode's // old votes for objects we no longer have. Only recent votes are held as orphans, or such replays // would use up the masternode's share of the orphan cache. static constexpr std::chrono::seconds MAX_ORPHAN_VOTE_AGE{std::chrono::hours{1}}; /** Votes waiting for their parent object, keyed by parent hash, with the oldest evicted once the * cache is full and each masternode limited to a share of it. */ class OrphanVoteCache { public: explicit OrphanVoteCache(size_t max_total, size_t max_per_mn); /** Returns whether the vote is held, either newly or because it already was. A new vote is * dropped if its masternode already holds max_per_mn orphan votes. */ [[nodiscard]] bool Insert(const uint256& parent_hash, const OrphanVote& orphan_vote); void Erase(const uint256& parent_hash, const OrphanVote& orphan_vote); void EraseExpired(NodeSeconds now); void GetAll(const uint256& parent_hash, std::vector& orphan_votes); void Clear(); template void Serialize(Stream& s) const { s << m_cache; } template void Unserialize(Stream& s) { // Read entry by entry rather than adopt the stored cache: a file from an earlier version can // hold a million entries. They are stored newest first, so keep the newest that fit the // bounds, skipping those ProcessVote() would not hold, then insert them oldest first. using Stored = CacheMultiMap; Stored::size_type stored_capacity; s >> stored_capacity; Clear(); const auto now{Now()}; std::vector kept; std::map kept_per_mn; for (uint64_t remaining{ReadCompactSize(s)}; remaining > 0; --remaining) { Stored::item_t item; s >> item; if (item.value.expiration < now || item.value.vote.Time() < now - MAX_ORPHAN_VOTE_AGE) continue; if (kept.size() >= m_cache.GetMaxSize()) continue; if (size_t& count{kept_per_mn[item.value.vote.GetMasternodeOutpoint()]}; count < m_max_per_mn) { ++count; kept.push_back(std::move(item)); } } for (auto it = kept.rbegin(); it != kept.rend(); ++it) { (void)Insert(it->key, it->value); } } private: const size_t m_max_per_mn; CacheMultiMap m_cache; std::map m_count_per_mn; }; } // namespace governance static constexpr int RATE_BUFFER_SIZE = 5; static constexpr bool DEFAULT_GOVERNANCE_ENABLE{true}; class CRateCheckBuffer { private: std::vector vecTimestamps; int nDataStart{0}; int nDataEnd{0}; bool fBufferEmpty{true}; public: CRateCheckBuffer() : vecTimestamps(RATE_BUFFER_SIZE) { } void AddTimestamp(int64_t nTimestamp) { if ((nDataEnd == nDataStart) && !fBufferEmpty) { // Buffer full, discard 1st element nDataStart = (nDataStart + 1) % RATE_BUFFER_SIZE; } vecTimestamps[nDataEnd] = nTimestamp; nDataEnd = (nDataEnd + 1) % RATE_BUFFER_SIZE; fBufferEmpty = false; } int64_t GetMinTimestamp() const { int nIndex = nDataStart; int64_t nMin = std::numeric_limits::max(); if (fBufferEmpty) { return nMin; } do { if (vecTimestamps[nIndex] < nMin) { nMin = vecTimestamps[nIndex]; } nIndex = (nIndex + 1) % RATE_BUFFER_SIZE; } while (nIndex != nDataEnd); return nMin; } int64_t GetMaxTimestamp() const { int nIndex = nDataStart; int64_t nMax = 0; if (fBufferEmpty) { return nMax; } do { if (vecTimestamps[nIndex] > nMax) { nMax = vecTimestamps[nIndex]; } nIndex = (nIndex + 1) % RATE_BUFFER_SIZE; } while (nIndex != nDataEnd); return nMax; } int GetCount() const { if (fBufferEmpty) { return 0; } if (nDataEnd > nDataStart) { return nDataEnd - nDataStart; } return RATE_BUFFER_SIZE - nDataStart + nDataEnd; } double GetRate() const { int nCount = GetCount(); if (nCount < RATE_BUFFER_SIZE) { return 0.0; } int64_t nMin = GetMinTimestamp(); int64_t nMax = GetMaxTimestamp(); if (nMin == nMax) { // multiple objects with the same timestamp => infinite rate return 1.0e10; } return static_cast(nCount) / static_cast(nMax - nMin); } SERIALIZE_METHODS(CRateCheckBuffer, obj) { READWRITE(obj.vecTimestamps, obj.nDataStart, obj.nDataEnd, obj.fBufferEmpty); } }; class GovernanceStore { protected: struct last_object_rec { explicit last_object_rec(bool fStatusOKIn = true) : triggerBuffer(), fStatusOK(fStatusOKIn) { } SERIALIZE_METHODS(last_object_rec, obj) { READWRITE(obj.triggerBuffer, obj.fStatusOK); } CRateCheckBuffer triggerBuffer; bool fStatusOK; }; using txout_m_t = std::map; protected: static constexpr int MAX_CACHE_SIZE = 1000000; static const std::string SERIALIZATION_VERSION_STRING; protected: // critical section to protect the inner data structures mutable Mutex cs_store; // keep track of the scanning errors std::map> mapObjects GUARDED_BY(cs_store); // mapErasedGovernanceObjects contains key-value pairs, where // key - governance object's hash // value - expiration time for deleted objects std::map mapErasedGovernanceObjects GUARDED_BY(cs_store); governance::OrphanVoteCache m_orphan_votes GUARDED_BY(cs_store); txout_m_t mapLastMasternodeObject GUARDED_BY(cs_store); // used to check for changed voting keys std::shared_ptr lastMNListForVotingKeys GUARDED_BY(cs_store); public: GovernanceStore(); ~GovernanceStore() = default; template void Serialize(Stream &s) const EXCLUSIVE_LOCKS_REQUIRED(!cs_store) { LOCK(cs_store); s << SERIALIZATION_VERSION_STRING << mapErasedGovernanceObjects << m_orphan_votes << mapObjects << mapLastMasternodeObject << *lastMNListForVotingKeys; } template void Unserialize(Stream &s) EXCLUSIVE_LOCKS_REQUIRED(!cs_store) { Clear(); LOCK(cs_store); std::string strVersion; s >> strVersion; if (strVersion != SERIALIZATION_VERSION_STRING) { return; } s >> mapErasedGovernanceObjects >> m_orphan_votes >> mapObjects >> mapLastMasternodeObject >> *lastMNListForVotingKeys; } void Clear() EXCLUSIVE_LOCKS_REQUIRED(!cs_store); std::string ToString() const EXCLUSIVE_LOCKS_REQUIRED(!cs_store); }; // // Governance Manager : Contains all proposals for the budget // class CGovernanceManager : public GovernanceStore { private: using db_type = CFlatDB; using object_ref_cm_t = CacheMap>; private: const std::unique_ptr m_db; bool is_loaded{false}; CMasternodeMetaMan& m_mn_metaman; const ChainstateManager& m_chainman; governance::SuperblockManager& m_superblocks; CDeterministicMNManager& m_dmnman; CMasternodeSync& m_mn_sync; //! Null on a node that can't look up proposal collateral const governance::CollateralSource* const m_collateral; int64_t nTimeLastDiff{0}; // keep track of current block height std::atomic nCachedBlockHeight{0}; object_ref_cm_t cmapVoteToObject; std::map> mapPostponedObjects; std::set setAdditionalRelayObjects; bool fRateChecksEnabled{true}; mutable Mutex cs_relay; std::vector m_relay_invs GUARDED_BY(cs_relay); public: CGovernanceManager() = delete; CGovernanceManager(const CGovernanceManager&) = delete; CGovernanceManager& operator=(const CGovernanceManager&) = delete; explicit CGovernanceManager(const fs::path& data_dir, CMasternodeMetaMan& mn_metaman, const ChainstateManager& chainman, governance::SuperblockManager& superblocks, CDeterministicMNManager& dmnman, CMasternodeSync& mn_sync, const governance::CollateralSource* collateral); ~CGovernanceManager(); // Basic initialization and querying bool IsValid() const { return is_loaded; } const governance::CollateralSource* GetCollateralSource() const { return m_collateral; } //! Whether proposal collateral can't be checked yet because the collateral source is still catching up bool IsCollateralSourceBehind() const; bool LoadCache(bool load_cache) EXCLUSIVE_LOCKS_REQUIRED(!cs_store); [[nodiscard]] static RPCResult GetJsonHelp(const std::string& key, bool optional); std::string ToString() const EXCLUSIVE_LOCKS_REQUIRED(!cs_store); [[nodiscard]] UniValue ToJson() const EXCLUSIVE_LOCKS_REQUIRED(!cs_store); void Clear() EXCLUSIVE_LOCKS_REQUIRED(!cs_store); // Getters/Setters int GetCachedBlockHeight() const { return nCachedBlockHeight; } int64_t GetLastDiffTime() const { return nTimeLastDiff; } std::vector GetCurrentVotes(const uint256& nParentHash, const COutPoint& mnCollateralOutpointFilter) const EXCLUSIVE_LOCKS_REQUIRED(!cs_store); void GetAllNewerThan(std::vector& objs, int64_t nMoreThanTime, bool include_postponed = false) const EXCLUSIVE_LOCKS_REQUIRED(!cs_store); void UpdateLastDiffTime(int64_t nTimeIn) { nTimeLastDiff = nTimeIn; } // Networking /** * This is called by AlreadyHave in net_processing.cpp as part of the inventory * retrieval process. Returns true if we want to retrieve the object, otherwise * false. (Note logic is inverted in AlreadyHave). */ bool ConfirmInventoryRequest(const CInv& inv) EXCLUSIVE_LOCKS_REQUIRED(!cs_store); bool ProcessVoteAndRelay(const CGovernanceVote& vote, CGovernanceException& exception) EXCLUSIVE_LOCKS_REQUIRED(!cs_store, !cs_relay); void RelayObject(const CGovernanceObject& obj) EXCLUSIVE_LOCKS_REQUIRED(!cs_relay); void RelayVote(const CGovernanceVote& vote) EXCLUSIVE_LOCKS_REQUIRED(!cs_relay); // Notification interface trigger void UpdatedBlockTip(const CBlockIndex* pindex) EXCLUSIVE_LOCKS_REQUIRED(!cs_store, !cs_relay); // Signer interface bool MasternodeRateCheck(const CGovernanceObject& govobj, bool fUpdateFailStatus = false) EXCLUSIVE_LOCKS_REQUIRED(!cs_store); std::shared_ptr FindGovernanceObjectByDataHash(const uint256& nDataHash) EXCLUSIVE_LOCKS_REQUIRED(!cs_store); std::vector> GetApprovedProposals(const CDeterministicMNList& tip_mn_list) EXCLUSIVE_LOCKS_REQUIRED(!cs_store); void AddGovernanceObject(CGovernanceObject& govobj, const std::string& peer_str) EXCLUSIVE_LOCKS_REQUIRED(!cs_store, !cs_relay); /** Test-only helper: inserts an object into the syncable object store without * running collateral or chain validation. */ void AddGovernanceObjectForTesting(const CGovernanceObject& govobj) EXCLUSIVE_LOCKS_REQUIRED(!cs_store); // Thread-safe accessors bool HaveObjectForHash(const uint256& nHash) const EXCLUSIVE_LOCKS_REQUIRED(!cs_store); bool HaveObjectForFetch(const uint256& nHash) const EXCLUSIVE_LOCKS_REQUIRED(!cs_store); bool HaveSyncableObjectForHash(const uint256& nHash) const EXCLUSIVE_LOCKS_REQUIRED(!cs_store); bool HaveVoteForHash(const uint256& nHash) const EXCLUSIVE_LOCKS_REQUIRED(!cs_store); bool SerializeObjectForHash(const uint256& nHash, CDataStream& ss) const EXCLUSIVE_LOCKS_REQUIRED(!cs_store); bool SerializeVoteForHash(const uint256& nHash, CDataStream& ss) const EXCLUSIVE_LOCKS_REQUIRED(!cs_store); std::shared_ptr FindGovernanceObject(const uint256& nHash) EXCLUSIVE_LOCKS_REQUIRED(!cs_store); int GetVoteCount() const EXCLUSIVE_LOCKS_REQUIRED(!cs_store); void AddPostponedObject(const CGovernanceObject& govobj) EXCLUSIVE_LOCKS_REQUIRED(!cs_store); std::shared_ptr FindConstGovernanceObject(const uint256& nHash) const EXCLUSIVE_LOCKS_REQUIRED(!cs_store); // Used by NetGovernance std::vector FetchRelayInventory() EXCLUSIVE_LOCKS_REQUIRED(!cs_relay); void CheckAndRemove() EXCLUSIVE_LOCKS_REQUIRED(!cs_store); std::pair, std::vector> FetchGovernanceObjectVotes( size_t peers_per_hash_max, int64_t now, std::map>& map_asked_recently) const EXCLUSIVE_LOCKS_REQUIRED(!cs_store); /** Build bloom filter of existing votes for a governance object (for sync requests) */ [[nodiscard]] CBloomFilter GetVoteBloomFilter(const uint256& nHash) const EXCLUSIVE_LOCKS_REQUIRED(!cs_store); /** Returns inventory items for all syncable (non-deleted, non-expired) governance objects */ [[nodiscard]] std::vector GetSyncableObjectInvs() const EXCLUSIVE_LOCKS_REQUIRED(!cs_store); /** Returns inventory items for syncable votes on a specific object, filtered by bloom filter */ [[nodiscard]] std::vector GetSyncableVoteInvs(const uint256& nProp, const CBloomFilter& filter) const EXCLUSIVE_LOCKS_REQUIRED(!cs_store); bool ProcessObject(const std::string& peer_str, const uint256& hash, CGovernanceObject& govobj) EXCLUSIVE_LOCKS_REQUIRED(::cs_main, !cs_store, !cs_relay); CDeterministicMNManager& GetMNManager(); /** Process a governance vote. Returns true on success. * If the vote is for an unknown object (orphan) and is held until that object arrives, * hashToRequest is set to the object hash. */ bool ProcessVote(const CGovernanceVote& vote, CGovernanceException& exception, uint256& hashToRequest) EXCLUSIVE_LOCKS_REQUIRED(!cs_store); private: // Internal counterparts to "Thread-safe accessors" void AddPostponedObjectInternal(const CGovernanceObject& govobj) EXCLUSIVE_LOCKS_REQUIRED(cs_store); std::shared_ptr FindGovernanceObjectInternal(const uint256& nHash) EXCLUSIVE_LOCKS_REQUIRED(cs_store); std::shared_ptr FindConstGovernanceObjectInternal(const uint256& nHash) const EXCLUSIVE_LOCKS_REQUIRED(cs_store); // Internal counterpart to "Signer interface" void AddGovernanceObjectInternal(CGovernanceObject& govobj, const std::string& peer_str) EXCLUSIVE_LOCKS_REQUIRED(::cs_main, cs_store, !cs_relay); // ... void MasternodeRateUpdate(const CGovernanceObject& govobj) EXCLUSIVE_LOCKS_REQUIRED(cs_store); /** Queue a deferred re-announcement for a trigger that is too new to propagate * reliably yet. Only call this for triggers we are keeping. */ void ScheduleTriggerRelay(const CGovernanceObject& govobj) EXCLUSIVE_LOCKS_REQUIRED(cs_store); bool MasternodeRateCheck(const CGovernanceObject& govobj, bool fUpdateFailStatus, bool fForce, bool& fRateCheckBypassed) EXCLUSIVE_LOCKS_REQUIRED(cs_store); void CheckPostponedObjects() EXCLUSIVE_LOCKS_REQUIRED(::cs_main, cs_store, !cs_relay); void InitOnLoad() EXCLUSIVE_LOCKS_REQUIRED(!cs_store); void CheckOrphanVotes(const std::shared_ptr& govobj) EXCLUSIVE_LOCKS_REQUIRED(cs_store, !cs_relay); void RebuildIndexes() EXCLUSIVE_LOCKS_REQUIRED(cs_store); void RemoveInvalidVotes() EXCLUSIVE_LOCKS_REQUIRED(cs_store); }; #endif // BITCOIN_GOVERNANCE_GOVERNANCE_H