diff --git a/AGENTS.md b/AGENTS.md index bb860dab5c83..28a6f7dd291e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -236,8 +236,11 @@ Be extra careful around: - governance object and superblock payment logic; - EvoDB, credit-pool, asset-lock, and Platform integration code; - network-message serialization, checksums, and partial-send paths; -- BLS scheme transitions across connect, disconnect, undo, and activation - boundaries; +- BLS schemes: an unnamed scheme is basic; legacy is selected by a payload's + version (encoding) or by the block being validated (signature verification). + Uniqueness checks also probe both encodings, and RPC or log code may print or + parse a key or signature in either one. See "BLS schemes" in + `doc/developer-notes.md`; - future DKG/quorum prediction, which must evaluate quorum availability at the relevant future work/cycle base instead of only the current tip; - time, mocktime, scheduler, and interrupt/shutdown behavior. diff --git a/doc/developer-notes.md b/doc/developer-notes.md index 291b17a4bdc6..aebc5eeeb690 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -18,6 +18,7 @@ Developer Notes - [DEBUG_LOCKORDER](#debug_lockorder) - [DEBUG_LOCKCONTENTION](#debug_lockcontention) - [Assertions and Checks](#assertions-and-checks) + - [BLS schemes](#bls-schemes) - [Valgrind suppressions file](#valgrind-suppressions-file) - [Compiling for test coverage](#compiling-for-test-coverage) - [Performance profiling with perf](#performance-profiling-with-perf) @@ -502,6 +503,43 @@ assert; use `Assume` for our *own* bookkeeping while still handling the violated case; and reserve `assert` for the narrow spot where continuing would corrupt EvoDB, the block index, or the wallet. +### BLS schemes + +BLS public keys and signatures have two encodings and two signature schemes: the +legacy one used before v19, and the basic one used since. Which one applies is a +property of the data or of the block, never of the node: + +- A call that names no scheme is basic. That is the right choice for everything + that is not historical: P2P messages, DKG, signing, ChainLocks, InstantSend, + governance, and any new payload or message. +- The encoding of a key or signature inside a versioned structure follows that + structure's version. Use the helper of its owner (`ProTxVersion::GetBLSScheme()`, + `CFinalCommitment::GetBLSScheme()`, `OperatorKeyScheme()`) rather than comparing + versions inline. +- The scheme an operator signature in a provider transaction, or a signature of + a mined quorum commitment, is *verified* under follows the block, not the + version of the payload carrying it: `BLSSchemeAfter(pindexPrev, params)`, which + provider transaction checks receive as `SpecialTxRules::bls_scheme`. A + legacy-encoded payload mined after v19 is verified under basic. +- Signatures a quorum recovers (ChainLocks, InstantSend locks, EHF signals, asset + unlocks) are always verified under basic, in a block or out of one. +- Production code cannot sign under the legacy scheme. Tests that need a legacy + signature for historical validation use `SignBLS()` from `test/util/bls.h`. +- An operator key (`CBLSLazyPublicKey`) has no encoding of its own, so + serializing, hashing or printing one always names the scheme, taken from the + payload or masternode state that owns it. +- Two other kinds of code name legacy explicitly: operator-key uniqueness + checks, which probe both encodings, and RPC or log code that prints or parses + a key or signature in either encoding. + +`test/lint/lint-bls-scheme.py` rejects a line outside `src/bls`, the tests and +the benchmarks that names `BLSScheme::Legacy`, unless the line carries +`// NOLINT(bls-legacy-scheme)` or the line before it carries +`// NOLINTNEXTLINE(bls-legacy-scheme)`. A marker left on a line that no longer +names it is rejected as well. The marked lines are version and block selection, +those uniqueness probes, legacy-diff migration, and the RPC or log code that +prints or parses either encoding. + ### Valgrind suppressions file Valgrind is a programming tool for memory debugging, memory leak detection, and diff --git a/src/active/dkgsession.cpp b/src/active/dkgsession.cpp index 1fdad45fd7d5..8338114a68d1 100644 --- a/src/active/dkgsession.cpp +++ b/src/active/dkgsession.cpp @@ -31,8 +31,7 @@ ActiveDKGSession::ActiveDKGSession(CBLSWorker& bls_worker, CDeterministicMNManag CDKGSession(bls_worker, dmnman, dkgdbgman, qdkgsman, qsnapman, chainman, base_block_index, llmq_params), m_mn_metaman{mn_metaman}, m_mn_activeman{mn_activeman}, - m_sporkman{sporkman}, - m_use_legacy_bls{!DeploymentActiveAfter(m_quorum_base_block_index, Params().GetConsensus(), Consensus::DEPLOYMENT_V19)} + m_sporkman{sporkman} { } @@ -125,7 +124,7 @@ std::optional ActiveDKGSession::SendContributions() logger.Batch("encrypted contributions. time=%d", t1.count()); - qc.sig = m_mn_activeman.Sign(qc.GetSignHash(), m_use_legacy_bls); + qc.sig = m_mn_activeman.Sign(qc.GetSignHash()); logger.Flush(); @@ -157,7 +156,6 @@ void ActiveDKGSession::VerifyPendingContributions() std::vector memberIndexes; std::vector vvecs; std::vector skContributions; - bool anyLegacyVvec{false}; for (const auto& idx : pendingContributionVerifications) { const auto& m = members[idx]; @@ -166,7 +164,6 @@ void ActiveDKGSession::VerifyPendingContributions() } memberIndexes.emplace_back(idx); vvecs.emplace_back(receivedVvecs[idx]); - anyLegacyVvec |= receivedVvecsLegacyScheme[idx]; skContributions.emplace_back(receivedSkContributions[idx]); // Write here to definitely store one contribution for each member no matter if // our share is valid or not, could be that others are still correct @@ -184,9 +181,8 @@ void ActiveDKGSession::VerifyPendingContributions() return; } - // Weighted aggregation needs points that passed subgroup checks, which legacy-scheme deserialization skips auto result = blsWorker.VerifyContributionShares(myId, vvecs, skContributions, /*parallel=*/true, - /*aggregated=*/!anyLegacyVvec); + /*aggregated=*/true); if (result.size() != memberIndexes.size()) { logger.Batch("VerifyContributionShares returned result of size %d but size %d was expected, something is wrong", result.size(), memberIndexes.size()); return; @@ -348,7 +344,7 @@ std::optional ActiveDKGSession::SendComplaint() logger.Batch("sending complaint. badCount=%d, complaintCount=%d", badCount, complaintCount); - qc.sig = m_mn_activeman.Sign(qc.GetSignHash(), m_use_legacy_bls); + qc.sig = m_mn_activeman.Sign(qc.GetSignHash()); logger.Flush(); @@ -438,7 +434,7 @@ std::optional ActiveDKGSession::SendJustification(const Uint2 return std::nullopt; } - qj.sig = m_mn_activeman.Sign(qj.GetSignHash(), m_use_legacy_bls); + qj.sig = m_mn_activeman.Sign(qj.GetSignHash()); logger.Flush(); @@ -595,23 +591,24 @@ std::optional ActiveDKGSession::SendCommitment() (*qc.quorumVvecHash.begin())++; } - uint256 commitmentHash = BuildCommitmentHash(qc.llmqType, qc.quorumHash, qc.validMembers, qc.quorumPublicKey, qc.quorumVvecHash); + uint256 commitmentHash = BuildCommitmentHash(qc.llmqType, qc.quorumHash, qc.validMembers, qc.quorumPublicKey, + qc.quorumVvecHash, BLSScheme::Basic); if (lieType == 2) { (*commitmentHash.begin())++; } - qc.sig = m_mn_activeman.Sign(commitmentHash, m_use_legacy_bls); - qc.quorumSig = skShare.Sign(commitmentHash, m_use_legacy_bls); + qc.sig = m_mn_activeman.Sign(commitmentHash); + qc.quorumSig = skShare.Sign(commitmentHash); if (lieType == 3) { - auto buf = qc.sig.ToBytes(m_use_legacy_bls); + auto buf = qc.sig.ToBytes(); buf[5]++; - qc.sig.SetBytes(buf, m_use_legacy_bls); + qc.sig.SetBytes(buf); } else if (lieType == 4) { - auto buf = qc.quorumSig.ToBytes(m_use_legacy_bls); + auto buf = qc.quorumSig.ToBytes(); buf[5]++; - qc.quorumSig.SetBytes(buf, m_use_legacy_bls); + qc.quorumSig.SetBytes(buf); } t3.stop(); @@ -686,7 +683,8 @@ std::vector ActiveDKGSession::FinalizeCommitments() fqc.nVersion = CFinalCommitment::GetVersion(isQuorumRotationEnabled, DeploymentActiveAfter(m_quorum_base_block_index, m_chainman.GetConsensus(), Consensus::DEPLOYMENT_V19)); fqc.quorumIndex = isQuorumRotationEnabled ? quorumIndex : 0; - uint256 commitmentHash = BuildCommitmentHash(fqc.llmqType, fqc.quorumHash, fqc.validMembers, fqc.quorumPublicKey, fqc.quorumVvecHash); + uint256 commitmentHash = BuildCommitmentHash(fqc.llmqType, fqc.quorumHash, fqc.validMembers, + fqc.quorumPublicKey, fqc.quorumVvecHash, BLSScheme::Basic); std::vector aggSigs; std::vector aggPks; @@ -722,7 +720,7 @@ std::vector ActiveDKGSession::FinalizeCommitments() t2.stop(); cxxtimer::Timer t3(true); - if (!fqc.Verify({m_dmnman, m_qsnapman, m_chainman, m_quorum_base_block_index}, true)) { + if (!fqc.Verify({m_dmnman, m_qsnapman, m_chainman, m_quorum_base_block_index}, BLSScheme::Basic)) { logger.Batch("failed to verify final commitment"); continue; } @@ -773,16 +771,16 @@ CFinalCommitment ActiveDKGSession::FinalizeSingleCommitment() fqc.quorumIndex = 0; uint256 commitmentHash = BuildCommitmentHash(fqc.llmqType, fqc.quorumHash, fqc.validMembers, fqc.quorumPublicKey, - fqc.quorumVvecHash); - fqc.quorumSig = sk1.Sign(commitmentHash, m_use_legacy_bls); + fqc.quorumVvecHash, BLSScheme::Basic); + fqc.quorumSig = sk1.Sign(commitmentHash); - fqc.membersSig = m_mn_activeman.Sign(commitmentHash, m_use_legacy_bls); + fqc.membersSig = m_mn_activeman.Sign(commitmentHash); if (workaround_qpublic_key) { fqc.quorumSig = fqc.membersSig; } - if (!fqc.Verify({m_dmnman, m_qsnapman, m_chainman, m_quorum_base_block_index}, true)) { + if (!fqc.Verify({m_dmnman, m_qsnapman, m_chainman, m_quorum_base_block_index}, BLSScheme::Basic)) { logger.Batch("failed to verify final commitment"); assert(false); } diff --git a/src/active/dkgsession.h b/src/active/dkgsession.h index 6ea2f71a510d..e7db33a7ce92 100644 --- a/src/active/dkgsession.h +++ b/src/active/dkgsession.h @@ -20,7 +20,6 @@ class ActiveDKGSession final : public llmq::CDKGSession CMasternodeMetaMan& m_mn_metaman; const CActiveMasternodeManager& m_mn_activeman; const CSporkManager& m_sporkman; - const bool m_use_legacy_bls{false}; public: ActiveDKGSession() = delete; diff --git a/src/active/dkgsessionhandler.cpp b/src/active/dkgsessionhandler.cpp index 1d540275efda..d1db8227cb8f 100644 --- a/src/active/dkgsessionhandler.cpp +++ b/src/active/dkgsessionhandler.cpp @@ -87,6 +87,11 @@ bool ActiveDKGSessionHandler::InitNewQuorum(gsl::not_null pQ if (!DeploymentDIP0003Enforced(pQuorumBaseBlockIndex->nHeight, Params().GetConsensus())) { return false; } + if (!DeploymentActiveAfter(pQuorumBaseBlockIndex, Params().GetConsensus(), Consensus::DEPLOYMENT_V19)) { + LogPrint(BCLog::LLMQ_DKG, "%s -- no DKG for quorum base %d: v19 is not active\n", __func__, + pQuorumBaseBlockIndex->nHeight); + return false; + } auto next_session = std::make_shared(m_bls_worker, m_dmnman, m_dkgdbgman, m_qdkgsman, m_mn_metaman, m_qsnapman, m_mn_activeman, m_chainman, diff --git a/src/active/masternode.cpp b/src/active/masternode.cpp index 20561768e686..1953615d0316 100644 --- a/src/active/masternode.cpp +++ b/src/active/masternode.cpp @@ -59,8 +59,8 @@ CActiveMasternodeManager::CActiveMasternodeManager(CConnman& connman, CDetermini { assert(sk.IsValid()); /* We can assume pk is valid if sk is valid */ LogPrintf("MASTERNODE:\n blsPubKeyOperator legacy: %s\n blsPubKeyOperator basic: %s\n", - m_operator_pk.ToString(/*specificLegacyScheme=*/true), - m_operator_pk.ToString(/*specificLegacyScheme=*/false)); + // NOLINTNEXTLINE(bls-legacy-scheme) + m_operator_pk.ToString(BLSScheme::Legacy), m_operator_pk.ToString(BLSScheme::Basic)); } CActiveMasternodeManager::~CActiveMasternodeManager() = default; @@ -288,21 +288,21 @@ template bool CActiveMasternodeManager::Decrypt(const CBLSIESEncryptedObject& obj, size_t idx, CBLSSecretKey& ret_obj, int version) const; -[[nodiscard]] CBLSSignature CActiveMasternodeManager::Sign(const uint256& hash, const bool is_legacy) const +[[nodiscard]] CBLSSignature CActiveMasternodeManager::Sign(const uint256& hash) const { AssertLockNotHeld(cs); - return WITH_READ_LOCK(cs, return m_operator_sk.Sign(hash, is_legacy)); + return WITH_READ_LOCK(cs, return m_operator_sk.Sign(hash)); } [[nodiscard]] std::vector CActiveMasternodeManager::SignBasic(const uint256& hash) const { AssertLockNotHeld(cs); - auto sig = Sign(hash, /*is_legacy=*/false); + auto sig = Sign(hash); assert(sig.IsValid()); - return sig.ToByteVector(/*specificLegacyScheme=*/false); + return sig.ToByteVector(); } -// We need to pass a copy as opposed to a const ref because CBLSPublicKeyVersionWrapper +// We need to pass a copy as opposed to a const ref because BLSEncoded // does not accept a const ref in its construction args [[nodiscard]] CBLSPublicKey CActiveMasternodeManager::GetPubKey() const { diff --git a/src/active/masternode.h b/src/active/masternode.h index e189fba0ea02..de0c68bea6e1 100644 --- a/src/active/masternode.h +++ b/src/active/masternode.h @@ -61,7 +61,7 @@ class CActiveMasternodeManager template