diff --git a/src/validation.h b/src/validation.h --- a/src/validation.h +++ b/src/validation.h @@ -265,7 +265,7 @@ * for non-network block sources and whitelisted peers. * @param[out] fNewBlock A boolean which is set to indicate if the block was * first received via this call - * @return True if state.IsValid() + * @return true if the block is accepted as a valid block */ bool ProcessNewBlock(const Config &config, const std::shared_ptr pblock, @@ -325,7 +325,15 @@ bool GetTransaction(const Config &config, const uint256 &hash, CTransactionRef &tx, uint256 &hashBlock, bool fAllowSlow = false); -/** Find the best known block, and make it the tip of the block chain */ +/** + * Find the best known block, and make it the active tip of the block chain. + * If it fails, the tip is not updated. + * + * pblock is either nullptr or a pointer to a block that is already loaded + * in memory (to avoid loading it from disk again). + * + * Returns true if a new chain tip was set. + */ bool ActivateBestChain( const Config &config, CValidationState &state, std::shared_ptr pblock = std::shared_ptr()); @@ -539,7 +547,12 @@ /** Functions for validating blocks and updating the block tree */ -/** Context-independent validity checks */ +/** + * Context-independent validity checks. + * + * Returns true if the provided block is valid (has valid header, + * transactions are valid, block is a valid size, etc.) + */ bool CheckBlock(const Config &Config, const CBlock &block, CValidationState &state, bool fCheckPOW = true, bool fCheckMerkleRoot = true); @@ -598,7 +611,14 @@ CBlockIndex *FindForkInGlobalIndex(const CChain &chain, const CBlockLocator &locator); -/** Mark a block as precious and reorganize. */ +/** + * Treats a block as if it were received before others with the same work, + * making it the active chain tip if applicable. Successive calls to + * PreciousBlock() will override the effects of earlier calls. The effects of + * calls to PreciousBlock() are not retained across restarts. + * + * Returns true if the provided block index successfully became the chain tip. + */ bool PreciousBlock(const Config &config, CValidationState &state, CBlockIndex *pindex); diff --git a/src/validation.cpp b/src/validation.cpp --- a/src/validation.cpp +++ b/src/validation.cpp @@ -2389,7 +2389,9 @@ FlushStateToDisk(chainparams, state, FLUSH_STATE_NONE); } -/** Update chainActive and related internal data structures. */ +/** + * Update chainActive and related internal data structures when adding a new block to the chain tip. + */ static void UpdateTip(const Config &config, CBlockIndex *pindexNew) { const Consensus::Params &consensusParams = config.GetChainParams().GetConsensus(); @@ -2901,11 +2903,6 @@ } } -/** - * Make the best chain active, in multiple steps. The result is either failure - * or an activated best chain. pblock is either nullptr or a pointer to a block - * that is already loaded (to avoid loading it again from disk). - */ bool ActivateBestChain(const Config &config, CValidationState &state, std::shared_ptr pblock) { // Note that while we're often called here from ProcessNewBlock, this is @@ -3618,6 +3615,11 @@ return true; } +/** + * If the provided block header is valid, add it to the block index. + * + * Returns true if the block is succesfully added to the block index. + */ static bool AcceptBlockHeader(const Config &config, const CBlockHeader &block, CValidationState &state, CBlockIndex **ppindex) { AssertLockHeld(cs_main); @@ -3793,9 +3795,9 @@ block.GetHash().ToString()); } - // Header is valid/has work, merkle tree and segwit merkle tree are - // good...RELAY NOW (but if it does not build on our best tip, let the - // SendMessages loop relay it) + // Header is valid/has work and the merkle tree is good. + // Relay now, but if it does not build on our best tip, let the + // SendMessages loop relay it. if (!IsInitialBlockDownload() && chainActive.Tip() == pindex->pprev) { GetMainSignals().NewPoWValidBlock(pindex, pblock); }