From b8e3318dd101c84b005aa426affeb3a191b92cf6 Mon Sep 17 00:00:00 2001 From: pasta Date: Fri, 6 Nov 2026 01:31:29 -0600 Subject: [PATCH] feat(interfaces): look up a Platform quorum at its signed Core height getPlatformQuorums exported every retained Platform quorum key (1440 on mainnet) with no notion of when each quorum could sign. A verifier that accepts any of them accepts state signed by a quorum that was never in the signing set at the state's Core height, and an empty or short list reads the same as "this quorum does not exist", which would ban an honest endpoint on a node that is merely behind. It has no production caller. getPlatformQuorum(llmq_type, quorum_hash, core_chain_locked_height) replaces it and answers FOUND (with the 48-byte basic-scheme key), INVALID or UNAVAILABLE: - FOUND: the quorum is in the window at that height, the newest commitments mined at or below it: signingActiveQuorumCount + 2 for a non-rotating type, and 3 * signingActiveQuorumCount for a rotating type. Each is a quorum's signing-active period plus two DKG intervals of slack. The height must also be within that many DKG intervals of the best ChainLock (clamped to the tip, or the tip if none is known), so an old quorum cannot get old state accepted as current. - INVALID: not the Platform type; a height above INT32_MAX; or a quorum hash that is no block of the active chain below that height, when the block at that height is covered by the best ChainLock whose block this node knows. No quorum with such a hash was mined by then. - UNAVAILABLE: everything else: missing node services, a height above the tip, a stale height, a quorum that is not in the window but was or may have been mined by that height, or a missing commitment record. A quorum outside the window is UNAVAILABLE, not INVALID, when its base block is on the active chain below the height. Platform verifies a block against its last committed validator set, and Tenderdash installs a new set only when it commits, so after a Core-height jump the first Platform block carrying the new height is signed by the outgoing quorum however far it has fallen behind the window. A stale height is UNAVAILABLE as well: if Platform halts for longer than the window while Core keeps ChainLocking, every honest endpoint serves state with a stale height. INVALID relies on this node's active chain. Above a ChainLock that chain may be a competing branch, and a ChainLock's height alone does not rule that out: a CLSIG can name a block this node does not know or a branch it has not activated yet. A quorum found in the window is answered regardless of ChainLock coverage. The window is read with the GetMinedCommitments*UntilBlock walkers that quorum scanning already uses. The staleness bound and window size are the pure llmq::PlatformQuorumMinSignedHeight and llmq::PlatformEligibleQuorumCount. Co-Authored-By: Claude Opus 5.5 Co-Authored-By: Claude Fable 5.2 --- src/interfaces/node.h | 24 ++-- src/llmq/params.h | 30 ++++ src/node/interfaces.cpp | 88 +++++++----- src/test/interfaces_tests.cpp | 241 +++++++++++++++++++++++++-------- src/test/llmq_params_tests.cpp | 38 ++++++ 5 files changed, 327 insertions(+), 94 deletions(-) diff --git a/src/interfaces/node.h b/src/interfaces/node.h index 559746221f13..2768c91dfa45 100644 --- a/src/interfaces/node.h +++ b/src/interfaces/node.h @@ -273,16 +273,22 @@ class LLMQ int32_t m_expiry_height{0}; }; virtual std::vector getQuorumStats() = 0; - struct PlatformQuorum { - uint256 m_quorum_hash{}; - std::vector m_pubkey{}; //!< serialized BLS public key (basic scheme) - int32_t m_height{0}; + enum class PlatformQuorumStatus { FOUND, INVALID, UNAVAILABLE }; + struct PlatformQuorumResult { + PlatformQuorumStatus status{PlatformQuorumStatus::UNAVAILABLE}; + std::vector public_key; //!< 48-byte basic-scheme key for FOUND; empty otherwise }; - //! Locally retained quorums of the given LLMQ type with their public - //! keys. Used by the GUI Platform client to verify Platform state-root - //! quorum signatures against locally synced quorum data. This includes - //! retained signing quorums that are no longer in the active signing set. - virtual std::vector getPlatformQuorums(uint8_t llmq_type) = 0; + //! Whether `quorum_hash` (Core internal byte order) could sign Platform state whose signed metadata + //! carries `core_chain_locked_height`, judged from this node's active chain. FOUND means it is among + //! the quorums eligible at that height. INVALID means the local chain proves it could not: the + //! hash is no block of the active chain below that height, so no quorum with it was mined by then, + //! which counts only if the active chain's block at that height is, or is an ancestor of, the block + //! of the best ChainLock whose block this node knows. UNAVAILABLE means this node proves neither and + //! says nothing against whoever served the state: the height is above the tip or too far below the + //! best ChainLock to verify, or the quorum is an older one, which may still sign the one Platform + //! block that first carries a height after a jump. + virtual PlatformQuorumResult getPlatformQuorum(uint8_t llmq_type, const uint256& quorum_hash, + uint32_t core_chain_locked_height) = 0; //! Serialized InstantSend lock for the given txid, or empty if the //! transaction has no islock (used to build asset lock proofs). virtual std::vector getInstantSendLock(const uint256& txid) = 0; diff --git a/src/llmq/params.h b/src/llmq/params.h index 2c975d828cb8..b9701e7f46f7 100644 --- a/src/llmq/params.h +++ b/src/llmq/params.h @@ -5,6 +5,7 @@ #ifndef BITCOIN_LLMQ_PARAMS_H #define BITCOIN_LLMQ_PARAMS_H +#include #include #include #include @@ -512,6 +513,35 @@ static constexpr std::array available_llmqs = { } // namespace Consensus +namespace llmq { +//! DKG intervals beyond its signing-active period during which a Platform quorum is still accepted +//! as the signer of Platform state. +static constexpr int PLATFORM_QUORUM_SLACK{2}; + +//! DKG intervals during which a Platform quorum may sign Platform state. A quorum of a non-rotating +//! type is signing-active for signingActiveQuorumCount intervals, one of a rotating type for one. +[[nodiscard]] constexpr int PlatformEligibleIntervals(const Consensus::LLMQParams& params) +{ + return (params.useRotation ? 1 : params.signingActiveQuorumCount) + PLATFORM_QUORUM_SLACK; +} + +//! How many of the newest mined Platform quorums may sign Platform state. A non-rotating type mines +//! one quorum per DKG interval, a rotating type one per quorum index. +[[nodiscard]] constexpr int PlatformEligibleQuorumCount(const Consensus::LLMQParams& params) +{ + return PlatformEligibleIntervals(params) * (params.useRotation ? params.signingActiveQuorumCount : 1); +} + +//! Lowest Core chain-locked height that Platform state may carry for this node to verify its +//! quorum signature, given the node's ChainLock height. Bounding by the ChainLock rather than the +//! tip keeps state signed before a ChainLock stall verifiable while the tip keeps moving. +[[nodiscard]] constexpr int PlatformQuorumMinSignedHeight(const Consensus::LLMQParams& params, int cl_height) +{ + const int64_t window{int64_t{PlatformEligibleIntervals(params)} * params.dkgInterval}; + return static_cast(std::max(0, int64_t{cl_height} - window)); +} +} // namespace llmq + // This must be outside of all namespaces. We must also duplicate the forward declaration of is_serializable_enum to // avoid inclusion of serialize.h here. template struct is_serializable_enum; diff --git a/src/node/interfaces.cpp b/src/node/interfaces.cpp index c0878655a70a..b4c8618242de 100644 --- a/src/node/interfaces.cpp +++ b/src/node/interfaces.cpp @@ -36,6 +36,7 @@ #include #include #include +#include #include #include #include @@ -86,6 +87,7 @@ #include #include +#include #include #include #include @@ -684,44 +686,68 @@ class LLMQImpl : public LLMQ } return stats; } - std::vector getPlatformQuorums(uint8_t llmq_type) override + PlatformQuorumResult getPlatformQuorum(uint8_t llmq_type, const uint256& quorum_hash, + uint32_t core_chain_locked_height) override { - std::vector ret; + PlatformQuorumResult invalid{PlatformQuorumStatus::INVALID, {}}; + const auto type{static_cast(llmq_type)}; + const auto llmq_params{Params().GetLLMQ(type)}; + if (type != Params().GetConsensus().llmqTypePlatform || !llmq_params.has_value()) { + return invalid; + } + if (core_chain_locked_height > static_cast(std::numeric_limits::max())) { + return invalid; + } + const int signed_height{static_cast(core_chain_locked_height)}; if (!context().llmq_ctx || !context().llmq_ctx->quorum_block_processor || !context().chainman) { - return ret; + return {}; } - const auto* pindex{WITH_LOCK(::cs_main, return context().chainman->ActiveChain().Tip())}; - if (!pindex) { - return ret; + // Only a ChainLock whose block is known can lock part of the active chain; the best height may + // belong to a block this node has not seen. + const CBlockIndex* chainlocked_block{nullptr}; + int32_t best_cl_height{-1}; + if (const auto& chainlocks{context().chainlocks}) { + chainlocked_block = chainlocks->GetBestChainlockWithPindex().second; + best_cl_height = chainlocks->GetBestChainLockHeight(); } - const auto type{static_cast(llmq_type)}; - const auto llmq_params{Params().GetLLMQ(type)}; - if (!llmq_params.has_value()) { - return ret; + + LOCK(::cs_main); + const CChain& active{context().chainman->ActiveChain()}; + const CBlockIndex* tip{active.Tip()}; + if (!tip || signed_height > tip->nHeight) { + return {}; } - // Drive proofs may be signed by an older Platform quorum while they - // are still consensus-valid and retained locally. Export the full - // retained-key window, not only the current signing-active set. - const auto quorum_count{static_cast(std::max(llmq_params->signingActiveQuorumCount, - llmq_params->keepOldKeys))}; - // Read mined final commitments directly: they already carry the quorum - // hash and public key, so there is no need to materialize full CQuorum - // objects (member lists, vvec/contribution reads, quorum cache inserts) - // via ScanQuorums. Newest-first, matching ScanQuorums' ordering. + // A ChainLock can arrive before its block, and without one the tip is the best bound known. + // A stale height proves nothing against the quorum, so it is not INVALID. + const int cl_height{best_cl_height >= 0 ? std::min(best_cl_height, tip->nHeight) : tip->nHeight}; + if (signed_height < llmq::PlatformQuorumMinSignedHeight(*llmq_params, cl_height)) { + return {}; + } + const auto& qbp{*context().llmq_ctx->quorum_block_processor}; - const auto quorum_base_block_indexes{llmq_params->useRotation - ? qbp.GetMinedCommitmentsIndexedUntilBlock(type, pindex, quorum_count) - : qbp.GetMinedCommitmentsUntilBlock(type, pindex, quorum_count)}; - for (const auto* pQuorumBaseBlockIndex : quorum_base_block_indexes) { - const auto qc{qbp.GetMinedCommitment(type, pQuorumBaseBlockIndex->GetBlockHash()).first}; - if (!qc.quorumPublicKey.IsValid()) continue; - ret.emplace_back(PlatformQuorum{ - .m_quorum_hash = qc.quorumHash, - .m_pubkey = qc.quorumPublicKey.ToByteVector(/*specificLegacyScheme=*/false), - .m_height = pQuorumBaseBlockIndex->nHeight, - }); + const CBlockIndex* signed_block{active[signed_height]}; + const auto window{static_cast(llmq::PlatformEligibleQuorumCount(*llmq_params))}; + const auto bases{llmq_params->useRotation ? qbp.GetMinedCommitmentsIndexedUntilBlock(type, signed_block, window) + : qbp.GetMinedCommitmentsUntilBlock(type, signed_block, window)}; + if (std::ranges::none_of(bases, [&](const CBlockIndex* base) { return base->GetBlockHash() == quorum_hash; })) { + // Platform verifies a block against its last committed validator set, so the block that + // first carries a height may be signed by a quorum no longer in the window at that height. + // A quorum mined at or below the height has its base block on the active chain below it; + // any other hash could never have signed. + const CBlockIndex* base{context().chainman->m_blockman.LookupBlockIndex(quorum_hash)}; + const bool never_mined{!base || base->nHeight >= signed_height || !active.Contains(base)}; + // That is final only on the part of the active chain a ChainLock locks; beyond it the + // active chain may be a competing branch. Unlike Chainlocks::HasChainLock, this keeps the + // lock while spork 19 is off. + const bool chainlocked{chainlocked_block && chainlocked_block->GetAncestor(signed_height) == signed_block}; + return never_mined && chainlocked ? invalid : PlatformQuorumResult{}; } - return ret; + + const auto qc{qbp.GetMinedCommitment(type, quorum_hash).first}; + if (!qc.quorumPublicKey.IsValid()) { + return {}; + } + return {PlatformQuorumStatus::FOUND, qc.quorumPublicKey.ToByteVector(/*specificLegacyScheme=*/false)}; } std::vector getInstantSendLock(const uint256& txid) override { diff --git a/src/test/interfaces_tests.cpp b/src/test/interfaces_tests.cpp index 2bdca0b6f459..e424955a94df 100644 --- a/src/test/interfaces_tests.cpp +++ b/src/test/interfaces_tests.cpp @@ -3,6 +3,7 @@ // file COPYING or http://www.opensource.org/licenses/mit-license.php. #include +#include #include #include #include @@ -13,20 +14,24 @@ #include #include #include +#include #include