From b8907db95076abe39596934d4f04a3b8ffce0160 Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Wed, 30 Mar 2016 21:58:51 +0000 Subject: [PATCH 01/10] BIP 9: Clarify nVersion interpretation and bit order --- bip-0009.mediawiki | 2 ++ 1 file changed, 2 insertions(+) diff --git a/bip-0009.mediawiki b/bip-0009.mediawiki index 995ae85a..6ea0ddd2 100644 --- a/bip-0009.mediawiki +++ b/bip-0009.mediawiki @@ -51,6 +51,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. From 4e9591d8c787f0d32b5a79862c8570300dc742d6 Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Wed, 30 Mar 2016 22:22:09 +0000 Subject: [PATCH 02/10] BIP 9: Add softfork deployment "name" --- bip-0009.mediawiki | 2 ++ 1 file changed, 2 insertions(+) diff --git a/bip-0009.mediawiki b/bip-0009.mediawiki index 6ea0ddd2..a8604fa7 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. # 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. From 4c124a8c5dad794b9c13d27990fa42651f44676f Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Wed, 30 Mar 2016 22:38:57 +0000 Subject: [PATCH 03/10] BIP 9: GBT specification --- bip-0009.mediawiki | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/bip-0009.mediawiki b/bip-0009.mediawiki index a8604fa7..98eb1907 100644 --- a/bip-0009.mediawiki +++ b/bip-0009.mediawiki @@ -161,6 +161,35 @@ 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}} || Object || set of pending, supported softfork deployments; each uses the softfork name as the key, and the softfork bit as its value +|- +| rulesrequired || {{No}} || Array of Strings || list of softfork deployments the server requires support for +|- +| rulesenforced || {{Yes}} || Array of Strings || list of softfork deployments that are active state +|} + +The "version" key of the template is retained, and used to indicate the server's preference of deployments. +Miners MAY clear or set bits in the block version WITHOUT any special "mutable" key, provided they are listed among the template's "rules" and (when clearing is desired) NOT listed in "rulesrequired". + ==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. From c7a31304e7741aa369864059ea183ae8e3b0aa33 Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Sat, 23 Apr 2016 20:12:41 +0000 Subject: [PATCH 04/10] bip-0009: Recommend name "bipN" --- bip-0009.mediawiki | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bip-0009.mediawiki b/bip-0009.mediawiki index 98eb1907..a54da681 100644 --- a/bip-0009.mediawiki +++ b/bip-0009.mediawiki @@ -24,7 +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. +# 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. From adbf64c626ca4e79bd4ff983ec37d9ffd8577148 Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Sat, 23 Apr 2016 20:20:13 +0000 Subject: [PATCH 05/10] BIP 9: Switch to rules/vbavailable/vbrequired GBT interface --- bip-0009.mediawiki | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/bip-0009.mediawiki b/bip-0009.mediawiki index a54da681..63341423 100644 --- a/bip-0009.mediawiki +++ b/bip-0009.mediawiki @@ -180,15 +180,15 @@ The template Object is also extended: |- ! Key !! Required !! Type !! Description |- -| rules || {{Yes}} || Object || set of pending, supported softfork deployments; each uses the softfork name as the key, and the softfork bit as its value +| rules || {{Yes}} || Array of Strings || list of softfork deployments, by name, that are active state |- -| rulesrequired || {{No}} || Array of Strings || list of softfork deployments the server requires support for +| vbavailable || {{Yes}} || Object || set of pending, supported softfork deployments; each uses the softfork name as the key, and the softfork bit as its value |- -| rulesenforced || {{Yes}} || Array of Strings || list of softfork deployments that are active state +| 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. -Miners MAY clear or set bits in the block version WITHOUT any special "mutable" key, provided they are listed among the template's "rules" and (when clearing is desired) NOT listed in "rulesrequired". +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". ==Support for future changes== From baacb0c64572548829db9a0609036b17e5d25a5c Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Sat, 23 Apr 2016 20:32:59 +0000 Subject: [PATCH 06/10] BIP 9: Use simple Yes/No rather than templates (which don't work on GitHub) --- bip-0009.mediawiki | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/bip-0009.mediawiki b/bip-0009.mediawiki index 63341423..fbb0fde6 100644 --- a/bip-0009.mediawiki +++ b/bip-0009.mediawiki @@ -170,7 +170,7 @@ The template request Object is extended to include a new item: |- ! Key !! Required !! Type !! Description |- -| rules || {{No}} || Array of Strings || list of supported softfork deployments, by name +| rules || No || Array of Strings || list of supported softfork deployments, by name |} The template Object is also extended: @@ -180,11 +180,11 @@ The template Object is also extended: |- ! Key !! Required !! Type !! Description |- -| rules || {{Yes}} || Array of Strings || list of softfork deployments, by name, that are active state +| 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 +| 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 +| 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. From 074909a173cc5c425f057dba12dad8bf52eb0eab Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Sat, 23 Apr 2016 21:13:02 +0000 Subject: [PATCH 07/10] BIP 9: Clarify GBT "version" --- bip-0009.mediawiki | 1 + 1 file changed, 1 insertion(+) diff --git a/bip-0009.mediawiki b/bip-0009.mediawiki index fbb0fde6..38a4396c 100644 --- a/bip-0009.mediawiki +++ b/bip-0009.mediawiki @@ -188,6 +188,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". ==Support for future changes== From d28a720f2aed00c2051b51402d4093062a8c431a Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Mon, 25 Apr 2016 00:18:39 +0000 Subject: [PATCH 08/10] BIP 9: rules/force mutation --- bip-0009.mediawiki | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/bip-0009.mediawiki b/bip-0009.mediawiki index 38a4396c..52c2add9 100644 --- a/bip-0009.mediawiki +++ b/bip-0009.mediawiki @@ -191,6 +191,19 @@ The "version" key of the template is retained, and used to indicate the server's 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". +The mutable key defined by BIP 23 is expanded to optionally include one new mutation: + +{| class="wikitable" +!colspan=4| mutations +|- +! Value !! Significance +|- +| rules/force || the miner may ignore rules it does not understand, if the template is to be used as-is (not modified by the client) +|} + +Servers should only signal this mutation when they have verified a client behaving this way will not produce invalid blocks. +This includes verifying the client's supported rules (listed in the template request) are not lacking of a rule that would change serialisation. + ==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. From 949bb13c1d1d4f5b1d1166c6ff33c924dae47dc3 Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Wed, 11 May 2016 17:45:08 +0000 Subject: [PATCH 09/10] Replace "rules/force" mutation with a "cannot be ignored" prefix to rule names --- bip-0009.mediawiki | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/bip-0009.mediawiki b/bip-0009.mediawiki index 52c2add9..45123e09 100644 --- a/bip-0009.mediawiki +++ b/bip-0009.mediawiki @@ -191,15 +191,11 @@ The "version" key of the template is retained, and used to indicate the server's 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". -The mutable key defined by BIP 23 is expanded to optionally include one new mutation: - -{| class="wikitable" -!colspan=4| mutations -|- -! Value !! Significance -|- -| rules/force || the miner may ignore rules it does not understand, if the template is to be used as-is (not modified by the client) -|} +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. Servers should only signal this mutation when they have verified a client behaving this way will not produce invalid blocks. This includes verifying the client's supported rules (listed in the template request) are not lacking of a rule that would change serialisation. From a95b8f8796533f52061d62442d8a596ba65902fc Mon Sep 17 00:00:00 2001 From: Luke Dashjr Date: Wed, 11 May 2016 21:54:09 +0000 Subject: [PATCH 10/10] bip-0009: Remove n/a paragraph --- bip-0009.mediawiki | 3 --- 1 file changed, 3 deletions(-) diff --git a/bip-0009.mediawiki b/bip-0009.mediawiki index 45123e09..153f6dbc 100644 --- a/bip-0009.mediawiki +++ b/bip-0009.mediawiki @@ -197,9 +197,6 @@ If a client does not understand a rule without the prefix, it may use it unmodif 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. -Servers should only signal this mutation when they have verified a client behaving this way will not produce invalid blocks. -This includes verifying the client's supported rules (listed in the template request) are not lacking of a rule that would change serialisation. - ==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.