diff options
Diffstat (limited to 'bip-0008.mediawiki')
| -rw-r--r-- | bip-0008.mediawiki | 68 |
1 files changed, 41 insertions, 27 deletions
diff --git a/bip-0008.mediawiki b/bip-0008.mediawiki index 6fa8cea..7030a20 100644 --- a/bip-0008.mediawiki +++ b/bip-0008.mediawiki @@ -37,8 +37,8 @@ Each soft fork deployment is specified by the following per-chain parameters (fu # The '''name''' specifies a very brief description of the soft fork, reasonable for use as an identifier. For deployments described in a single BIP, it is recommended to use the name "bipN" where N is the appropriate BIP number. # The '''bit''' determines which bit in the nVersion field of the block is to be used to signal the soft fork lock-in and activation. It is chosen from the set {0,1,2,...,28}. # The '''startheight''' specifies the height of the first block at which the bit gains its meaning. -# The '''timeoutheight''' specifies a block height at which the miner signalling ends. Once this height has been reached, if the soft fork has not yet locked in (excluding this block's bit state), the deployment is either considered failed on all descendants of the block (but see the exception during '''FAILING''' state), or, if '''lockinontimeout'' is true, transitions to the '''LOCKED_IN''' state. -# The '''lockinontimeout''' boolean if set to true, will transition state to '''LOCKED_IN''' at timeoutheight if not already '''LOCKED_IN''' or '''ACTIVE'''. +# The '''timeoutheight''' specifies a block height at which the miner signalling ends. Once this height has been reached, if the soft fork has not yet locked in (excluding this block's bit state), the deployment is considered failed on all descendants of the block. +# The '''lockinontimeout''' boolean if set to true, blocks are required to signal in the final period, ensuring the soft fork has locked in by timeoutheight. ===Selection guidelines=== @@ -53,16 +53,18 @@ The following guidelines are suggested for selecting these parameters for a soft A later deployment using the same bit is possible as long as the startheight is after the previous one's timeoutheight or activation, but it is discouraged until necessary, and even then recommended to have a pause in between to detect buggy software. +'''startheight''' and '''timeoutheight''' must be an exact multiple of 2016 (ie, at a retarget boundary), and '''timeoutheight''' must be at least 4096 blocks (2 retarget intervals) after '''startheight'''. + ===States=== With each block and soft fork, we associate a deployment state. The possible states are: # '''DEFINED''' is the first state that each soft fork starts out as. The genesis block is by definition in this state for each deployment. # '''STARTED''' for blocks at or beyond the startheight. -# '''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, or for one retarget period after the timeout when '''lockinontimeout''' is true. +# '''MUST_SIGNAL''' for one retarget period prior to the timeout, if LOCKED_IN was not reached and '''lockinontimeout''' is true. +# '''LOCKED_IN''' for one retarget period after the first retarget period with STARTED (or MUST_SIGNAL) blocks of which at least threshold have the associated bit set in nVersion. # '''ACTIVE''' for all blocks after the LOCKED_IN retarget period. -# '''FAILING''' for one retarget period after the timeout, if LOCKED_IN was not reached and '''lockinontimeout''' is false. -# '''FAILED''' for all blocks after the FAILING retarget period. +# '''FAILED''' for all blocks after the timeoutheight if LOCKED_IN is not reached. ===Bit flags=== @@ -77,19 +79,18 @@ for the purposes of this proposal, and support two future upgrades for different When a block nVersion does not have top bits 001, it is treated as if all bits are 0 for the purposes of deployments. -Miners must continue setting the bit in LOCKED_IN phase so uptake is visible and acknowledged. -Blocks without the applicable bit set are invalid during this period. -For flexibility, this rule does NOT require the top 3 bits to be set any particular way. - ===New consensus rules=== The new consensus rules for each soft fork are enforced for each block that has ACTIVE state. +During the MUST_SIGNAL and LOCKED_IN phases, blocks that fail to signal are invalid. +For flexibility, during the LOCKED_IN phase only, this rule does NOT require the top 3 bits to be set any particular way. + ===State transitions=== <img src="bip-0008/states.png" align="middle"></img> -During the STARTED state if the '''lockinontimeout''' is set to true, the state will transition to LOCKED_IN when '''timeoutheight''' is reached. +Note that when '''lockinontimeout''' is true, the LOCKED_IN state will be reached no later than at a height of '''timeoutheight''', and ACTIVE will be reached no later than at a height of '''timeoutheight + 2016'''. The genesis block has state DEFINED for each deployment, by definition. @@ -121,7 +122,8 @@ We remain in the initial state until we reach the start block height. After a period in the STARTED state, we tally the bits set, and transition to LOCKED_IN if a sufficient number of blocks in the past period set the deployment bit in their version numbers. The threshold is ≥1916 blocks (95% of 2016), or ≥1512 for testnet (75% of 2016). -If the threshold hasn't been met, and we reach the timeout, then we either transition to LOCKED_IN state anyway (if lockinontimeout is true), or we transition to FAILING. +If the threshold hasn't been met, lockinontimeout is true, and we are at the last period before the timeout, then we transition to MUST_SIGNAL. +If the threshold hasn't been met and we reach the timeout, we transition directly to FAILED. Note that a block's state never depends on its own nVersion; only on that of its ancestors. @@ -131,28 +133,22 @@ Note that a block's state never depends on its own nVersion; only on that of its for (i = 0; i < 2016; i++) { walk = walk.parent; if (walk.nVersion & 0xE0000000 == 0x20000000 && (walk.nVersion >> bit) & 1 == 1) { - count++; + ++count; } } if (count >= threshold) { return LOCKED_IN; + } else if (lockinontimeout && block.height + 2016 >= timeoutheight) { + return MUST_SIGNAL; } else if (block.height >= timeoutheight) { - return (lockinontimeout == true) ? LOCKED_IN : FAILING; + return FAILED; } return STARTED; -If the deployment is not LOCKED_IN by the timeout (or '''lockinontimeout'''), it has a single retarget period during which it may still become active, only by unanimous signalling in every block. -This state exists such that if '''lockinontimeout''' is set to true later, it remains compatible with the original deployment. +If we have finished a period of MUST_SIGNAL, we transition directly to LOCKED_IN. - case FAILING: - walk = block; - for (i = 0; i < 2016; i++) { - walk = walk.parent; - if (walk.nVersion & 0xE0000000 == 0x20000000 && ((walk.nVersion >> bit) & 1) != 1) { - return FAILED; - } - } - return ACTIVE; + case MUST_SIGNAL: + return LOCKED_IN; After a retarget period of LOCKED_IN, we automatically transition to ACTIVE. @@ -178,6 +174,25 @@ current retarget period (i.e. up to and including its ancestor with height block it is possible to implement the mechanism above efficiently and safely by caching the resulting state of every multiple-of-2016 block, indexed by its parent. +===Mandatory signalling=== + +Blocks received while in the MUST_SIGNAL and LOCKED_IN phases must be checked to ensure that they signal. For example: + + if (GetStateForBlock(block) == MUST_SIGNAL) { + if ((block.nVersion & 0xE0000000) != 0x20000000 || ((block.nVersion >> bit) & 1) != 1) { + return state.Invalid(BlockValidationResult::RECENT_CONSENSUS_CHANGE, "bad-version-bip8-must-signal"); + } + } + if (GetStateForBlock(block) == LOCKED_IN) { + if (((block.nVersion >> bit) & 1) != 1) { + return state.Invalid(BlockValidationResult::RECENT_CONSENSUS_CHANGE, "bad-version-bip8-locked-in"); + } + } + +Implementations should be careful not to ban peers that send blocks that are invalid due to not signalling (or blocks that build on those blocks), as that would allow an incompatible chain that is only briefly longer than the compliant chain to cause a split of the p2p network. If that occurred, nodes that have not set ''lockinontimeout'' may not see new blocks in the compliant chain, and thus not reorg to it at the point when it has more work, and would thus not be following the valid chain with the most work. + +Implementations with ''lockinontimeout'' set to true may potentially follow a lower work chain than nodes with ''lockinontimeout'' set to false for an extended period. In order for this not to result in a net split nodes with ''lockinontimeout'' set to true, those nodes may need to preferentially connect to each other. Deployments proposing that implementations set ''lockinontimeout'' to true should either use parameters that do not risk there being a higher work alternative chain, or specify a mechanism for implementations that support the deployment to preferentially peer with each other. + ===Warning mechanism=== To support upgrade warnings, an extra "unknown upgrade" is tracked, using the "implicit bit" mask = (block.nVersion & ~expectedVersion) != 0. Mask will be non-zero whenever an unexpected bit is set in nVersion. Whenever LOCKED_IN for the unknown upgrade is detected, the software should warn loudly about the upcoming soft fork. It should warn even more loudly after the next retarget period (when the unknown upgrade is in the ACTIVE state). @@ -211,7 +226,7 @@ The template Object is also extended: The "version" key of the template is retained, and used to indicate the server's preference of deployments. If versionbits is being used, "version" MUST be within the versionbits range of [0x20000000...0x3FFFFFFF]. Miners MAY clear or set bits in the block version WITHOUT any special "mutable" key, provided they are listed among the template's "vbavailable" and (when clearing is desired) NOT included as a bit in "vbrequired". -Servers MUST set bits in "vbrequired" for deployments in LOCKED_IN state, to ensure blocks produced are valid. +Servers MUST set bits in "vbrequired" for deployments in MUST_SIGNAL and LOCKED_IN states, to ensure blocks produced are valid. Softfork deployment names listed in "rules" or as keys in "vbavailable" may be prefixed by a '!' character. Without this prefix, GBT clients may assume the rule will not impact usage of the template as-is; typical examples of this would be when previously valid transactions cease to be valid, such as BIPs 16, 65, 66, 68, 112, and 113. @@ -225,9 +240,8 @@ https://github.com/bitcoin/bitcoin/compare/master...luke-jr:bip8 ==Contrasted with BIP 9== -* The '''lockinontimeout''' flag is added. BIP 9 would only transition to the FAILED state when timeout was reached. +* The '''lockinontimeout''' flag is added, providing a way to guarantee transition to LOCKED_IN. * Block heights are used for the deployment monotonic clock, rather than median-time-past. -* The last-ditch effort during a new FAILING state is added to allow '''lockinontimeout''' to be safely set after the initial deployment. ==Backwards compatibility== |