diff options
Diffstat (limited to 'bip-0135.mediawiki')
| -rw-r--r-- | bip-0135.mediawiki | 409 |
1 files changed, 409 insertions, 0 deletions
diff --git a/bip-0135.mediawiki b/bip-0135.mediawiki new file mode 100644 index 0000000..cb6f9a0 --- /dev/null +++ b/bip-0135.mediawiki @@ -0,0 +1,409 @@ +<pre> + BIP: 135 + Title: Generalized version bits voting + Author: Sancho Panza <sanch0panza@protonmail.com> + Comments-Summary: No comments yet. + Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0135 + https://bitco.in/forum/threads/bip9-generalized-version-bits-voting-bip-genvbvoting.1968/ + Status: Draft + Type: Informational + Created: 2017-03-29 + License: CC0-1.0 + GNU-All-Permissive + Post-History: https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2017-April/013969.html + Replaces: 9 +</pre> + + +==Abstract== + +BIP9 introduced a mechanism for using the version bits to signal support for +backwards-compatible changes (soft-forks) using a tally over the previous 2016 +blocks computed at re-targeting intervals. It provided for a fixed threshold and +non-configurable lock-in interval applicable to all deployments on a chain. + +This document describes a generalized signaling scheme which allows each +signaling bit to have its own configurable threshold, window size (number of +blocks over which it is tallied) and a configurable lock-in period. + +It extends the semantics of the signaling bits to cover arbitrary consensus +changes, referred to under the general term 'forks'. The same range +of version bits is used for signaling. + +The states of the BIP9 state machine and its original parameters (name, bit, +starttime, timeout) are retained. Some state transition conditions are +extended by additional parameters ('threshold', 'windowsize', 'minlockedblocks', +'minlockedtime') to provide for fine-tuning of threshold and grace period. + + +==Motivation== + +The Bitcoin protocol requires a flexible scheme for finding consensus on +protocol changes, to ensure that it can adapt to the needs of the market and +remain competitive as an electronic payment system. + +While BIP9 has served the community well for previous deployments, there are +some shortcomings in its approach: + +* it specifically applies only to backward-compatible changes + +* its fixed 95% threshold is not flexible enough to allow for a 'spectrum of contentiousness' to be represented + +* small minorities can veto proposed changes, which can lead to undesirable stagnation + +A generalized revision of the BIP9 specification can address these issues +and satisfy the needs of the market for both soft and hard fork changes +as well as more flexible activation thresholds and upgrade (grace) periods. + +The proposal should allow more freedom of choice in activation strategies +while remaining backward compatible with respect to existing BIP9-based +deployments. + + +==Terms and conventions== + +The version bits used by this proposal for signaling deployment of forks are +referred to as 'signaling bits' or shortened to 'bits' where unambiguous. + +All times in this specification are in seconds since the epoch [1]. +Durations / time offsets are in seconds. + +The term 'MTP' refers to the 'median time past' which is calculated as the +median nTime of a block and its 10 predecessors. It is treated as a monotonic +clock defined by a chain, and evaluated on the ancestor of a block, i.e. + +MTP := '''GetMedianTimePast(block.parent)''' + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", +"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this +document are to be interpreted as described in RFC 2119. + + +==Specification== + + +===Backward compatibility=== + +This specification SHALL enable strict backward compatibility with existing +BIP9-based deployments through suitable parameter configuration. Any part of +the specification preventing full backward compatibility SHALL be considered +as erroneous and amended. + +As before, a set of configuration parameters SHALL exist for the version bits +for each chain supported by an implementation. This permits each bit to be +configured independently for each chain (mainnet, testnet, etc.) + + +===Signaling bits=== + + +The signaling bits SHALL comprise the 29 least significant bits of the +nVersion block header field. nVersion is a 32-bit field which is treated as +a little-endian integer. + +Signaling bits SHALL be assigned numbers from 0..28 ranging from the least +significant (bit 0) to the most significant (bit 28) in the range. + +The top 3 bits of nVersion MUST be set to 001 , yielding a range of possible +nVersion values between [0x20000000...0x3FFFFFFF], inclusive. + +If a block's nVersion does not have its top 3 bits set to 001, all its signaling +bits MUST be treated as if they are 0 (see also: 'Tallying' section below). + + +===Deployment states=== + +With each block and fork, we associate a deployment state. +The possible states are: + +# '''DEFINED''' is the first state that each fork starts out as. The genesis block for any chain SHALL by definition be in this state for each deployment. +# '''STARTED''' for blocks past the starttime. +# '''LOCKED_IN''' after STARTED, if at least threshold out of windowsize blocks have the associated bit set in nVersion, measured at next height that is evenly divisible by the windowsize. +# '''ACTIVE''' for all blocks after the grace period conditions have been met. +# '''FAILED''' if past the timeout time and LOCKED_IN was not reached. + +In accordance with BIP9, a block's state SHALL never depend on its own nVersion; +only on that of its ancestors. + + +===Fork deployment parameters=== + +Each fork deployment is specified by the following per-chain parameters: + +# The '''name''' specifies a very brief description of the 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 fork deployment. It is chosen from the set {0,1,2,...,28}. +# The '''starttime''' specifies a minimum median time past (MTP) of a block at which the bit gains its meaning. +# The '''timeout''' specifies a time at which the deployment is considered failed. If the MTP of a block >= timeout and the fork has not yet locked in (including this block's bit state), the deployment is considered failed on all descendants of the block. +# The '''windowsize''' specifies the number of past blocks (including the block under consideration) to be taken into account for locking in a fork. +# The '''threshold''' specifies a number of blocks, in the range of 1..windowsize, which must signal for a fork in order to lock it in. The support is measured when the chain height is evenly divisible by the windowsize. If the windowsize is set to 2016 (as in BIP9) this coincides with the 2016-block re-targeting intervals. +# The '''minlockedblocks''' specifies a minimum number of blocks which a fork must remain in locked-in state before it can become active. Both minlockedblocks and minlockedtime (see below) must be satisfied before a fork can become active. +# The '''minlockedtime''' specifies a minimum grace time, an earliest time after lock-in at which the fork can become active. If the MTP of a block >= (minlockedtime + median time of the block that locked in the fork), then the fork becomes activated. Both minlockedtime and minlockedblocks (see above) must be satisfied before a fork can become active. + + +===Tallying=== + +If a block's nVersion does not have its top 3 bits set to 001, all its signaling +bits MUST be treated as if they are '0'. + +A signaling bit value of '1' SHALL indicate support of a fork and SHALL count +towards its tally on a chain. + +A signaling bit value of '0' SHALL indicate absence of support of a fork and +SHALL NOT count towards its tally on a chain. + +The signaling bits SHALL be tallied whenever the head of the active chain +changes (including after reorganizations). + + +===State transitions=== + +The following diagram illustrates the generalized state machine: + +<img src="bip-0135/bip-0135-states-small.png" align="middle"></img> +<br> + +'''NOTES:''' + +The genesis block of any chain SHALL have the state DEFINED for each deployment. + +A given deployment SHALL remain in the DEFINED state until it either passes the +starttime (and becomes STARTED) or the timeout time (and becomes FAILED). + +Once a deployment has STARTED, the signal for that deployment SHALL be tallied +over the the past windowsize blocks whenever a new block is received on that +chain. + +A transition from the STARTED state to the LOCKED_IN state SHALL only occur +when all of these are true: + +* the height of the received block is an integer multiple of the window size +* the MTP is below the timeout time +* at least threshold out of windowsize blocks have signaled support + +A similar height synchronization precondition SHALL exist for the transition from +LOCKED_IN to ACTIVE. +These synchronization conditions are expressed by the "mod(height, windowsize) = 0" +clauses in the diagram, and have been been added so that backward compatibility +with BIP9's use of the 2016-block re-targeting periods can be configured for +existing deployments (see above 'Optional full backward compatibility' section). + +A transition from LOCKED_IN to ACTIVE state SHALL only occur if the height +synchronization criterion is met and two configurable 'grace period' conditions +are fulfilled: + +# current height MUST be at least minlockedblocks above LOCKED_IN height +# MTP must exceed LOCKED_IN time by at least minlockedtime seconds + +NOTE: If minlockedtime and minlockedblocks are both set to 0, then the fork will +proceed directly to ACTIVE state once the chain height reaches a multiple of the +windowsize. + +The ACTIVE and FAILED states are terminal; a deployment stays in these states +once they are reached. + +Deployment states are maintained along block chain branches. +They need re-computation when a reorganization happens. + + +===New consensus rules=== + +New consensus rules deployed by a fork SHALL be enforced for each block that has +ACTIVE state. + + +===Optional operator notifications=== + +An implementation SHOULD notify the operator when a deployment transitions +to STARTED, LOCKED_IN, ACTIVE or FAILED states. + +It is RECOMMENDED that an implementation provide finer-grained notifications +to the operator which allow him/her to track the measured support level for +defined deployments. + +An implementation SHOULD warn the operator if the configured (emitted) nVersion +has been overridden to contain bits set to '1' in contravention of the above +non-signaling recommendations for DEFINED forks. + +It is RECOMMENDED that an implementation warn the operator if no signal has +been received for a given deployment during a full windowsize period after the +deployment has STARTED. This could indicate that something may be wrong with +the operator's configuration that is causing them not to receive the signal +correctly. + +For undefined signals, it is RECOMMENDED that implementation track these and +alert their operators with supportive upgrade notifications, e.g. + +* "warning: signaling started on unknown feature on version bit X" +* "warning: signaling on unknown feature reached X% (over last N blocks)" +* "info: signaling ceased on unknown feature (over last M blocks)" + +Since parameters of these deployments are unknown, it is RECOMMENDED that +implementations allow the user to configure the emission of such notifications +(e.g. suitable N and M parameters in the messages above, e.g. a best-guess +window of 100 blocks). + + +===getblocktemplate changes=== + +The getblocktemplate features introduced in BIP9 remain in effect unmodified. + + +==Rationale== + +The timeout into FAILED state allows eventual reuse of bits if a fork was not +successfully activated. + +A fallow period at the conclusion of a fork attempt allows some detection of +buggy clients, and allows time for warnings and software upgrades for +successful forks. The duration of a fallow period is not specified by this +proposal, although a conventional fallow period of 3 months is RECOMMENDED. + +Due to the constraints set by BIP 34, BIP 66 and BIP 65, there are only +0x7FFFFFFB possible nVersion values available. This limits to at most 30 +independent deployments. +By restricting the top 3 bits to 001 we we are left with 29 out of those for +the purposes of this proposal, and support two future upgrades for different +mechanisms (top bits 010 and 011). + + +==Guidelines== + + +===Parameter selection guidelines=== + +The following guidelines are suggested for selecting the parameters for a fork: + +# '''name''' SHOULD be selected such that no two forks, concurrent or otherwise, ever use the same name. +# '''bit''' SHOULD be selected such that no two concurrent forks use the same bit. Implementors should make an effort to consult resources such as [2] to establish whether the bit they wish to use can reasonably be assumed to be unclaimed by a concurrent fork, and to announce their use ('claim') of a bit for a fork purpose on various project mailing lists, to reduce chance of collisions. +# '''starttime''' SHOULD be set to some date in the future, approximately one month after a software release date which includes the fork signaling. This allows for some release delays, while preventing triggers as a result of parties running pre-release software. +# '''timeout''' is RECOMMENDED to be 1 year (31536000 seconds) after starttime. +# '''windowsize''' SHOULD be set large enough to allow reception of an adequately precise signal. A good high-resolution value would be 2016 blocks as used in BIP9. It is NOT RECOMMENDED to use a windowsize less than 100 blocks. +# '''threshold''' SHOULD be set as high as possible to ensure a smooth activation based on the estimated support and the nature of the proposed changes. It is strongly RECOMMENDED that threshold >= windowsize / 2 (rounded up) to ensure that a proposal is only activated by majority support. +# '''minlockedblocks''' is RECOMMENDED to be set >= windowsize, to ensure that a full window passes in LOCKED_IN state. Lower values will be ineffective as the transition from LOCKED_IN to ACTIVE is guarded by a synchronization based on the window size. +# '''minlockedtime''' SHOULD only be set > 0 if a minimum LOCKED_IN time period needs be strictly enforced. It is permissible to set minlockedblocks to 0 and only specify minlockedtime, however the synchronization condition means the grace period can only expire once the time has passed AND the chain height is a multiple of the windowsize. + +NOTE: If minlockedtime and minlockedblocks are both set to 0, then the fork will +proceed to ACTIVE state when the chain height reaches a multiple of the windowsize. + +A later deployment using the same bit is possible as long as the starttime is +after the previous fork's timeout or activation, but it is discouraged until +necessary, and even then recommended to have a pause in between to detect +buggy software. + + +===Signaling guidelines=== + +An implementation SHOULD signal '0' on a bit if one of the following holds true: + +* the deployment parameters are not DEFINED (not configured or explicitly undefined) +* the deployment is DEFINED and has not yet reached the STARTED state +* the deployment has succeeded (it has become ACTIVE) +* the deployment has FAILED + +An implementation SHOULD enable the operator to choose (override) whether to +signal '0' or '1' on a bit, once its deployment has at least reached the STARTED +state. + +An implementation SHOULD warn the operator if the configured (emitted) nVersion +has been overridden to contain bits set to '1' in contravention of the above +non-signaling recommendations. + +A supporting miner SHOULD signal '1' on a bit for which the deployment +is LOCKED_IN state so that uptake is visible. However, this has no effect on +consensus rules. +Once LOCKED_IN, a deployment proceeds to ACTIVE solely based on the configured +grace period parameters (see 'Fork deployment parameters' above). + +A miner SHOULD signal '0' on a bit if they wish to suspend signaling of support +for a fork that is DEFINED in their software. + +It is NOT RECOMMENDED to signal '1' for bits where the meaning is undefined +(i.e. bits which are unclaimed by proposals). + + +===Settings for BIP9 compatibility=== + +This section lists parameter values which can be used to effect compatibility +with the existing BIP9 versionbits state machine. + +The following table describes mainnet compatibility options (95%, 2016 blocks): + +{| class="wikitable" +!colspan=3 | +|- +! Parameter !! BIP9 value !! BIP135 value +|- +| name || some_name || some_name +|- +| bit || b || b +|- +| starttime || T_start || T_start +|- +| timeout || T_timeout || T_timeout +|- +| windowsize || n/a || 2016 +|- +| threshold || n/a || 1916 +|- +| minlockedblocks || n/a || 2016 +|- +| minlockedtime || n/a || 0 +|} + +The following table describes testnet compatibility options (75%, 2016 blocks): + +{| class="wikitable" +!colspan=3 | +|- +! Parameter !! BIP9 value !! BIP135 value +|- +| name || some_name || some_name +|- +| bit || b || b +|- +| starttime || T_start || T_start +|- +| timeout || T_timeout || T_timeout +|- +| windowsize || n/a || 2016 +|- +| threshold || n/a || 1512 +|- +| minlockedblocks || n/a || 2016 +|- +| minlockedtime || n/a || 0 +|} + + +==Deployment== + +As this BIP is not itself consensus-relevant (Information like BIP9), it can +be rolled out without the use of a BIP9 fork bit. + +Backward compatibility through judicious fork configuration parameters should +ensure that it does not interfere with existing known deployments. + +By way of design it does not interfere with unknown (undefined) deployments. + + +==Reference implementation== + +A working reference implementation, including tests, can be found in this Pull Request: + +https://github.com/BitcoinUnlimited/BitcoinUnlimited/pull/458 + +Existing unit tests and regression tests have been left active to demonstrate +backward compatibility of the default settings with BIP9. + + +==References== + +[1] http://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap04.html#tag_21_04_16 + +[2] [[https://github.com/bitcoin/bips/blob/master/bip-0009/assignments.mediawiki|List of existing BIP9 deployment proposals]] + + +==Copyright== + +This BIP is dual-licensed under the Creative Commons CC0 1.0 Universal and +GNU All-Permissive licenses. |