mirror of
https://github.com/dashpay/dash.git
synced 2024-12-28 13:32:47 +01:00
4bf93d833e
6576a8765f67716aa6b87a2f0296fbac5956bec0 doc: Improve versionbits.h documentation (Antoine Riard)
Pull request description:
While reviewing burying of BIP 9 deployments, seen that versionbits.h wasn't that much documented. This is an attempt to improve it. It can be useful, given after burying this code isn't going to be used anymore and isn't straightforward at first sight.
ACKs for top commit:
jnewbery:
ACK 6576a8765f67716aa6b87a2f0296fbac5956bec0
ajtowns:
ACK 6576a8765f67716aa6b87a2f0296fbac5956bec0
fanquake:
ACK 6576a8765f67716aa6b87a2f0296fbac5956bec0
Tree-SHA512: 906463e0b22b988f89d77f798bf94d294f70467d29975088b87384764fb5d0dd1350be67562cc264656f61f1eada2cba20f99c0d797d1d7f90203c269e34c714
88 lines
4.7 KiB
C++
88 lines
4.7 KiB
C++
// Copyright (c) 2016 The Bitcoin Core developers
|
|
// Distributed under the MIT software license, see the accompanying
|
|
// file COPYING or http://www.opensource.org/licenses/mit-license.php.
|
|
|
|
#ifndef BITCOIN_VERSIONBITS_H
|
|
#define BITCOIN_VERSIONBITS_H
|
|
|
|
#include <chain.h>
|
|
#include <map>
|
|
|
|
/** What block version to use for new blocks (pre versionbits) */
|
|
static const int32_t VERSIONBITS_LAST_OLD_BLOCK_VERSION = 4;
|
|
/** What bits to set in version for versionbits blocks */
|
|
static const int32_t VERSIONBITS_TOP_BITS = 0x20000000UL;
|
|
/** What bitmask determines whether versionbits is in use */
|
|
static const int32_t VERSIONBITS_TOP_MASK = 0xE0000000UL;
|
|
/** Total bits available for versionbits */
|
|
static const int32_t VERSIONBITS_NUM_BITS = 29;
|
|
|
|
/** BIP 9 defines a finite-state-machine to deploy a softfork in multiple stages.
|
|
* State transitions happen during retarget period if conditions are met
|
|
* In case of reorg, transitions can go backward. Without transition, state is
|
|
* inherited between periods. All blocks of a period share the same state.
|
|
*/
|
|
enum class ThresholdState {
|
|
DEFINED, // First state that each softfork starts out as. The genesis block is by definition in this state for each deployment.
|
|
STARTED, // For blocks past the starttime.
|
|
LOCKED_IN, // For one retarget period after the first retarget period with STARTED blocks of which at least threshold have the associated bit set in nVersion.
|
|
ACTIVE, // For all blocks after the LOCKED_IN retarget period (final state)
|
|
FAILED, // For all blocks once the first retarget period after the timeout time is hit, if LOCKED_IN wasn't already reached (final state)
|
|
};
|
|
|
|
// A map that gives the state for blocks whose height is a multiple of Period().
|
|
// The map is indexed by the block's parent, however, so all keys in the map
|
|
// will either be nullptr or a block with (height + 1) % Period() == 0.
|
|
typedef std::map<const CBlockIndex*, ThresholdState> ThresholdConditionCache;
|
|
|
|
/** Display status of an in-progress BIP9 softfork */
|
|
struct BIP9Stats {
|
|
/** Length of blocks of the BIP9 signalling period */
|
|
int period;
|
|
/** Number of blocks with the version bit set required to activate the softfork */
|
|
int threshold;
|
|
/** Number of blocks elapsed since the beginning of the current period */
|
|
int elapsed;
|
|
/** Number of blocks with the version bit set since the beginning of the current period */
|
|
int count;
|
|
/** False if there are not enough blocks left in this period to pass activation threshold */
|
|
bool possible;
|
|
};
|
|
|
|
/**
|
|
* Abstract class that implements BIP9-style threshold logic, and caches results.
|
|
*/
|
|
class AbstractThresholdConditionChecker {
|
|
protected:
|
|
virtual bool Condition(const CBlockIndex* pindex, const Consensus::Params& params) const =0;
|
|
virtual int64_t BeginTime(const Consensus::Params& params) const =0;
|
|
virtual int64_t EndTime(const Consensus::Params& params) const =0;
|
|
virtual int Period(const Consensus::Params& params) const =0;
|
|
virtual int Threshold(const Consensus::Params& params, int nAttempt) const =0;
|
|
|
|
public:
|
|
/** Returns the numerical statistics of an in-progress BIP9 softfork in the current period */
|
|
BIP9Stats GetStateStatisticsFor(const CBlockIndex* pindex, const Consensus::Params& params, ThresholdConditionCache& cache) const;
|
|
/** Returns the state for pindex A based on parent pindexPrev B. Applies any state transition if conditions are present.
|
|
* Caches state from first block of period. */
|
|
ThresholdState GetStateFor(const CBlockIndex* pindexPrev, const Consensus::Params& params, ThresholdConditionCache& cache) const;
|
|
/** Returns the height since when the ThresholdState has started for pindex A based on parent pindexPrev B, all blocks of a period share the same */
|
|
int GetStateSinceHeightFor(const CBlockIndex* pindexPrev, const Consensus::Params& params, ThresholdConditionCache& cache) const;
|
|
};
|
|
|
|
/** BIP 9 allows multiple softforks to be deployed in parallel. We cache per-period state for every one of them
|
|
* keyed by the bit position used to signal support. */
|
|
struct VersionBitsCache
|
|
{
|
|
ThresholdConditionCache caches[Consensus::MAX_VERSION_BITS_DEPLOYMENTS];
|
|
|
|
void Clear();
|
|
};
|
|
|
|
ThresholdState VersionBitsState(const CBlockIndex* pindexPrev, const Consensus::Params& params, Consensus::DeploymentPos pos, VersionBitsCache& cache);
|
|
BIP9Stats VersionBitsStatistics(const CBlockIndex* pindexPrev, const Consensus::Params& params, Consensus::DeploymentPos pos, VersionBitsCache& cache);
|
|
int VersionBitsStateSinceHeight(const CBlockIndex* pindexPrev, const Consensus::Params& params, Consensus::DeploymentPos pos, VersionBitsCache& cache);
|
|
uint32_t VersionBitsMask(const Consensus::Params& params, Consensus::DeploymentPos pos);
|
|
|
|
#endif // BITCOIN_VERSIONBITS_H
|