Merge pull request #391 from luke-jr/vb_gbt

BIP 9: GBT updates for versionbits

1 files changed, 40 insertions, 0 deletions

diff --git a/bip-0009.mediawiki b/bip-0009.mediawiki
index 995ae85..153f6db 100644
--- a/bip-0009.mediawiki
+++ b/bip-0009.mediawiki
@@ -24,6 +24,7 @@ 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 '''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 '''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.
@@ -32,6 +33,7 @@ Each soft fork deployment is specified by the following per-chain parameters (fu
 
 The following guidelines are suggested for selecting these parameters for a soft fork:
 
+# '''name''' should be selected such that no two softforks, concurrent or otherwise, ever use the same name.
 # '''bit''' should be selected such that no two concurrent softforks use the same bit.
 # '''starttime''' should be set to some date in the future, approximately one month after a software release date including the soft fork.  This allows for some release delays, while preventing triggers as a result of parties running pre-release software.
 # '''timeout''' should be 1 year (31536000 seconds) after starttime.
@@ -51,6 +53,8 @@ With each block and soft fork, we associate a deployment state. The possible sta
 
 ===Bit flags===
 
+The nVersion block header field is to be interpreted as a 32-bit little-endian integer (as present), and bits are selected within this integer as values (1 << N) where N is the bit number.
+
 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.
 
@@ -157,6 +161,42 @@ block, indexed by its parent.
 
 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).
 
+===getblocktemplate changes===
+
+The template request Object is extended to include a new item:
+
+{| class="wikitable"
+!colspan=4| template request
+|-
+! Key !! Required !! Type !! Description
+|-
+| rules || No || Array of Strings || list of supported softfork deployments, by name
+|}
+
+The template Object is also extended:
+
+{| class="wikitable"
+!colspan=4| template
+|-
+! Key !! Required !! Type !! Description
+|-
+| rules || Yes || Array of Strings || list of softfork deployments, by name, that are active state
+|-
+| vbavailable || Yes || Object || set of pending, supported softfork deployments; each uses the softfork name as the key, and the softfork bit as its value
+|-
+| vbrequired || No || Number || bit mask of softfork deployment version bits the server requires enabled in submissions
+|}
+
+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".
+
+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.
+If a client does not understand a rule without the prefix, it may use it unmodified for mining.
+On the other hand, when this prefix is used, it indicates a more subtle change to the block structure or generation transaction; examples of this would be BIP 34 (because it modifies coinbase construction) and 141 (since it modifies the txid hashing and adds a commitment to the generation transaction).
+A client that does not understand a rule prefixed by '!' must not attempt to process the template, and must not attempt to use it for mining even unmodified.
+
 ==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.