From 8315dfd3faf8c2af74ac6185269fcebc89d41c26 Mon Sep 17 00:00:00 2001 From: Pieter Wuille Date: Tue, 1 Mar 2016 04:05:48 +0100 Subject: [PATCH] Rewrite state transition logic --- bip-0009.mediawiki | 224 +++++++++++++++++++++----------------------- bip-0009/states.png | Bin 0 -> 24827 bytes 2 files changed, 107 insertions(+), 117 deletions(-) create mode 100644 bip-0009/states.png diff --git a/bip-0009.mediawiki b/bip-0009.mediawiki index b10a91c1..856db7a9 100644 --- a/bip-0009.mediawiki +++ b/bip-0009.mediawiki @@ -24,140 +24,130 @@ In addition, BIP 34 made the integer comparison (nVersion >= 2) a consensus rule Each soft fork deployment is specified by the following per-chain parameters (further elaborated below): -# 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. -# The '''threshold''' specifies how many blocks within a single retarget period (2016 blocks) must have the bit set before we lock in the deployment. +# 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 '''threshold''' specifies how many blocks within a single retarget period (2016 blocks) must have the bit set before we lock in the deployment. The recommended value is 1916 (95%) for mainnet and 1512 (75%) for testnets. # The '''starttime''' specifies a minimum median time past of a block at which the bit gains its meaning. # The '''timeout''' specifies a time at which the deployment is considered failed. If the median time past of a block >= timeout and the soft fork has not yet locked in (including this block's bit state), the deployment is considered failed on all descendants of the block. -===Mechanism=== +No two deployments may use the same bit if they have overlapping starttime-timeout periods. -'''Bit flags''' -We are permitting several independent soft forks to be deployed in parallel. For each, a bit B is chosen from the set {0,1,2,...,28}, which is not currently in use for any other ongoing soft fork. Miners signal intent to enforce the new rules associated with the proposed soft fork by setting bit 1B in nVersion to 1 in their blocks. +The starttime should be set to some date in the future, coordinates with software release date. This is to prevent +triggers as a result of parties running pre-release software. The timeout should be set a reasonable time after the +starttime. Setting it to 3 years after the starttime would allow around 9 deployments to be initiated every year. -'''High bits''' -The highest 3 bits are set to 001, so the range of actually possible nVersion values is [0x20000000...0x3FFFFFFF], inclusive. This leaves two future upgrades for different mechanisms (top bits 010 and 011), while complying to the constraints set by BIP 34 and BIP 66. Having more than 29 available bits for parallel soft forks does not add anything anyway, as the (nVersion >= 3) requirement already makes that impossible. +====States==== -'''States''' -With every softfork proposal we associate a state BState, which begins -at ''defined'', and can be ''started'', ''locked-in'', ''activated'', -or ''failed''. Transitions are considered after each -retarget period. +With each block and soft fork, we associate a deployment state. The possible states are: -'''Soft Fork Support''' -Software which supports the change should begin by setting B in all blocks -mined until it is resolved. +# '''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 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. +# '''FAILED''' for one retarget period past the timeout time, if LOCKED_IN was not reached. +# '''ABANDONED''' for all blocks after the FAILED retarget period. - if (BState == started || BState == locked-in) { - SetBInBlock(); - } +====Bit flags==== -'''Start time''' -If a block's median time past is at least the starttime, and it is consider ''started''. +Blocks in the STARTED state get an nVersion whose bit position bit is set to 1. The top 3 bits of such blocks must be +001, so the range of actually possible nVersion values is [0x20000000...0x3FFFFFFF], inclusive. This leaves two future +upgrades for different mechanisms (top bits 010 and 011), while complying to the constraints set by BIP 34 and others. +Having more than 29 available bits for parallel soft forks does not add anything anyway, as the (nVersion >= 3) +requirement already makes that impossible. When a block nVersion does not have top bits 001, it is treated as if all +bits are 0 for the purposes of deployments in the context of this BIP. Miners should continue setting the bit in +LOCKED_IN phase, so uptake is visible - if (NextBlockHeight % 2016 == 0) { - if (BState == defined && GetMedianTimePast(nextblock) >= starttime) { - BState = started; +====New consensus rules==== + +The new consensus rules for each soft fork are enforced for each block that has ACTIVE state. + +====State transitions==== + + + +The genesis block has state DEFINED for each deployment, by definition. + + State GetStateForBlock(block) { + if (block.height == 0) { + return DEFINED; + } + +All blocks within a retarget period have the same state. This means that if +floor(block1.height / 2016) = floor(block2.height / 2016), they are guaranteed to have the same state for every +deployment. + + if ((block.height % 2016) != 0) { + return GetStateForBlock(GetParent(block)); + } + +Otherwise, the next state depends on the previous state: + + switch (GetStateForBlock(GetAncestorAtHeight(block, block.height - 2016))) { + +We remain in the initial state until either we pass the start time or the timeout. GetMedianTimePast in the code below +refers to the median nTime of the 11 blocks preceeding a given block. + + case DEFINED: + if (GetMedianTimePast(block) >= timeout) { + return FAILED; + } + if (GetMedianTimePast(block) >= starttime) { + return STARTED; + } + return DEFINED; + +When in STARTED state, we tally the bits set, and can transition to LOCKED_IN if we pass the threshold. Alternatively, +the timeout can trigger. Note that a block's state never depends on its own nVersion; only on that of its ancestors. + + case STARTED: { + int count = 0; + walk = block; + for (i = 0; i < 2016; i++) { + walk = walk.parent; + if (walk.nVersion & 0xE0000000 == 0x2000000 && (walk.nVersion >> bit) & 1 == 1) { + count++; + } + } + if (count >= threshold) { + return LOCKED_IN; + } + if (GetMedianTimePast(block) >= timeout) { + return FAILED; + } + } + +After a retarget period of LOCKED_IN or FAILED, we automatically transition to ACTIVE and ABANDONED, respectively. + + case LOCKED_IN: + return ACTIVE; + + case FAILED: + return ABANDONED; + +And ACTIVE and ABANDONED are terminal states, which a deployment stays in once they're reached. + + case ACTIVE: + return ACTIVE; + + case ABANDONED: + return ABANDONED; } } -'''Success: Lock-in Threshold''' -If bit B is set in 1916 (1512 on testnet) or -more of the 2016 blocks within a retarget period, it is considered -''locked-in''. Miners should continue setting bit B, so uptake is -visible. - - if (NextBlockHeight % 2016 == 0) { - if (BState == started && Previous2016BlocksCountB() >= threshold) { - BState = locked-in; - BActiveHeight = NextBlockHeight + 2016; - } - } - -'''Success: Activation Delay''' -The consensus rules related to ''locked-in'' soft fork will be enforced in -the second retarget period; ie. there is a one retarget period in -which the remaining 5% can upgrade. At the that activation block and -after, miners should stop setting bit B, which may be reused for a different soft fork. - - if (BState == locked-in && NextBlockHeight == BActiveHeight) { - BState = activated; - ApplyRulesForBFromNextBlock(); - /* B can be reused, immediately */ - } - -'''Failure: Timeout''' -A soft fork proposal should include a ''timeout''. This is measured -as the beginning of a calendar year as per this table (suggest -adding three to the current calendar year when drafting the soft fork proposal): - -{| -! Timeout Year -! >= Seconds -! Timeout Year -! >= Seconds -|- -|2018 -|1514764800 -|2026 -|1767225600 -|- -|2019 -|1546300800 -|2027 -|1798761600 -|- -|2020 -|1577836800 -|2028 -|1830297600 -|- -|2021 -|1609459200 -|2029 -|1861920000 -|- -|2022 -|1640995200 -|2030 -|1893456000 -|- -|2023 -|1672531200 -|2031 -|1924992000 -|- -|2024 -|1704067200 -|2032 -|1956528000 -|- -|2025 -|1735689600 -|2033 -|1988150400 -|} - -If the soft fork still not ''locked-in'' and the -GetMedianTimePast() of a block following a retarget period is at or -past this timeout, miners should cease setting this bit. - - if (NextBlockHeight % 2016 == 0) { - if (BState == started && GetMedianTimePast(nextblock) >= BFinalYear) { - BState = failed; - } - } - -After another retarget period (to allow detection of buggy miners), -the bit may be reused. - -'''Warning system''' -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 lock-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. - '''Forks''' It should be noted that the states are maintained along block chain branches, but may need recomputation when a reorganization happens. -===Support for future changes=== +'''Implementation''' +Given that the state for a specific block/deployment combination is completely determined by its ancestry before the +current retarget period (i.e. up to and including its ancestor with height block.height - 1 - (block.height % 2016)), +it is possible to implement the mechanism above efficiently by caching the resulting state of every multiple-of-2016 +block, indexed by its parent. + +====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). + +==Support for future changes== The mechanism described above is very generic, and variations are possible for future soft forks. Here are some ideas that can be taken into account. diff --git a/bip-0009/states.png b/bip-0009/states.png new file mode 100644 index 0000000000000000000000000000000000000000..7b3139efe40652d75d9a93408eb2466544823ca5 GIT binary patch literal 24827 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%0Ad6_92|6sX{(bbQ^c}2 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