diff options
| -rw-r--r-- | bip-0009.mediawiki | 40 | ||||
| -rw-r--r-- | bip-0022.mediawiki | 28 | ||||
| -rw-r--r-- | bip-0141.mediawiki | 12 | ||||
| -rw-r--r-- | bip-0145.mediawiki | 19 |
4 files changed, 73 insertions, 26 deletions
diff --git a/bip-0009.mediawiki b/bip-0009.mediawiki index 509a8a9..162b264 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. diff --git a/bip-0022.mediawiki b/bip-0022.mediawiki index 35b59be..4b33e59 100644 --- a/bip-0022.mediawiki +++ b/bip-0022.mediawiki @@ -26,9 +26,9 @@ Block template creation can be influenced by various parameters: |- ! Key !! Required !! Type !! Description |- -| capabilities || {{No}} || Array of Strings || SHOULD contain a list of the following, to indicate client-side support: [[#Optional: Long Polling|"longpoll"]], "coinbasetxn", "coinbasevalue", [[bip-0023.mediawiki#Block Proposal|"proposal"]], [[bip-0023.mediawiki#Logical Services|"serverlist"]], "workid", and any of the [[bip-0023.mediawiki#Mutations|mutations]] +| capabilities || No || Array of Strings || SHOULD contain a list of the following, to indicate client-side support: [[#Optional: Long Polling|"longpoll"]], "coinbasetxn", "coinbasevalue", [[bip-0023.mediawiki#Block Proposal|"proposal"]], [[bip-0023.mediawiki#Logical Services|"serverlist"]], "workid", and any of the [[bip-0023.mediawiki#Mutations|mutations]] |- -| mode || {{No}} || String || MUST be "template" or omitted +| mode || No || String || MUST be "template" or omitted |} getblocktemplate MUST return a JSON Object containing the following keys: @@ -37,29 +37,29 @@ getblocktemplate MUST return a JSON Object containing the following keys: |- ! Key !! Required !! Type !! Description |- -| bits || {{Yes}} || String || the compressed difficulty in hexadecimal +| bits || Yes || String || the compressed difficulty in hexadecimal |- -| curtime || {{Yes}} || Number || the current time as seen by the server (recommended for block time) - note this is not necessarily the system clock, and must fall within the mintime/maxtime rules +| curtime || Yes || Number || the current time as seen by the server (recommended for block time) - note this is not necessarily the system clock, and must fall within the mintime/maxtime rules |- -| height || {{Yes}} || Number || the height of the block we are looking for +| height || Yes || Number || the height of the block we are looking for |- -| previousblockhash || {{Yes}} || String || the hash of the previous block, in big-endian hexadecimal +| previousblockhash || Yes || String || the hash of the previous block, in big-endian hexadecimal |- -| sigoplimit || {{No}} || Number || number of sigops allowed in blocks +| sigoplimit || No || Number || number of sigops allowed in blocks |- -| sizelimit || {{No}} || Number || number of bytes allowed in blocks +| sizelimit || No || Number || number of bytes allowed in blocks |- -| transactions || {{Yes|Should}} || Array of Objects || Objects containing [[#Transactions Object Format|information for Bitcoin transactions]] (excluding coinbase) +| transactions || Should || Array of Objects || Objects containing [[#Transactions Object Format|information for Bitcoin transactions]] (excluding coinbase) |- -| version || {{Yes}} || Number || always 1 or 2 (at least for bitcoin) - clients MUST understand the implications of the version they use (eg, comply with [[bip-0034.mediawiki|BIP 0034]] for version 2) +| version || Yes || Number || always 1 or 2 (at least for bitcoin) - clients MUST understand the implications of the version they use (eg, comply with [[bip-0034.mediawiki|BIP 0034]] for version 2) |- -| coinbaseaux || {{No}} || Object || data that SHOULD be included in the coinbase's scriptSig content. Only the values (hexadecimal byte-for-byte) in this Object should be included, not the keys. This does not include the block height, which is required to be included in the scriptSig by [[bip-0034.mediawiki|BIP 0034]]. It is advisable to encode values inside "PUSH" opcodes, so as to not inadvertently expend SIGOPs (which are counted toward limits, despite not being executed). +| coinbaseaux || No || Object || data that SHOULD be included in the coinbase's scriptSig content. Only the values (hexadecimal byte-for-byte) in this Object should be included, not the keys. This does not include the block height, which is required to be included in the scriptSig by [[bip-0034.mediawiki|BIP 0034]]. It is advisable to encode values inside "PUSH" opcodes, so as to not inadvertently expend SIGOPs (which are counted toward limits, despite not being executed). |- -| coinbasetxn || {{Patch|this or ↓}} || Object || [[#Transactions Object Format|information for coinbase transaction]] +| coinbasetxn || this or ↓ || Object || [[#Transactions Object Format|information for coinbase transaction]] |- -| coinbasevalue || {{Patch|this or ↑}} || Number || total funds available for the coinbase (in Satoshis) +| coinbasevalue || this or ↑ || Number || total funds available for the coinbase (in Satoshis) |- -| workid || {{No}} || String || if provided, this value must be returned with results (see [[#Block Submission|Block Submission]]) +| workid || No || String || if provided, this value must be returned with results (see [[#Block Submission|Block Submission]]) |} ==== Transactions Object Format ==== diff --git a/bip-0141.mediawiki b/bip-0141.mediawiki index 07e6a7f..b8f686c 100644 --- a/bip-0141.mediawiki +++ b/bip-0141.mediawiki @@ -82,8 +82,8 @@ If all transactions in a block do not have witness data, the commitment is optio A <code>scriptPubKey</code> (or <code>redeemScript</code> as defined in BIP16/P2SH) that consists of a 1-byte push opcode (for 0 to 16) followed by a data push between 2 and 32 bytes gets a new special meaning. The value of the first push is called the "version byte". The following byte vector pushed is called the "witness program". There are two cases in which witness validation logic are triggered. Each case determines the location of the witness version byte and program, as well as the form of the scriptSig: -# Triggered by a <code>scriptPubKey</code> that is exactly a push of a version byte, plus a push of a witness program. The scriptSig must be exactly empty or validation fails. -# Triggered when a <code>scriptPubKey</code> is a P2SH script, and the BIP16 <code>redeemScript</code> pushed in the <code>scriptSig</code> is exactly a push of a version byte plus a push of a witness program. The <code>scriptSig</code> must be exactly a push of the BIP16 <code>redeemScript</code> or validation fails. +# Triggered by a <code>scriptPubKey</code> that is exactly a push of a version byte, plus a push of a witness program. The scriptSig must be exactly empty or validation fails. (''"native witness program"'') +# Triggered when a <code>scriptPubKey</code> is a P2SH script, and the BIP16 <code>redeemScript</code> pushed in the <code>scriptSig</code> is exactly a push of a version byte plus a push of a witness program. The <code>scriptSig</code> must be exactly a push of the BIP16 <code>redeemScript</code> or validation fails. (''"P2SH witness program"'') If the version byte is 0, and the witness program is 20 bytes: * It is interpreted as a pay-to-witness-public-key-hash (P2WPKH) program. @@ -120,9 +120,11 @@ The new rule is ''block cost'' ≤ 4,000,000. Sigops per block is currently limited to 20,000. We change this restriction as follows: -''Sigop cost'' is defined. The cost of a sigop in traditional script is 4, while the cost of a sigop in witness program is 1. +Sigops in the current pubkey script, signature script, and P2SH check script are counted at 4 times their previous value. +The sigop limit is likewise quadrupled to ≤ 80,000. -The new rule is total ''sigop cost'' ≤ 80,000. +In addition, opcodes within the witness program are counted identical to as previously within the P2SH check script. +That is, CHECKSIG in a witness program is counted as only 1 sigop, and CHECKMULTISIG in a witness program is counted as 1 to 20 sigops according to the arguments. This rule applies to both native witness program and P2SH witness program. == Examples == @@ -272,7 +274,7 @@ As a soft fork, older software will continue to operate without modification. N == Deployment == -This BIP will be deployed by "version bits" BIP9 using bit 1. +This BIP will be deployed by "version bits" BIP9 with the name "segwit" and using bit 1. For Bitcoin mainnet, the BIP9 starttime will be midnight TBD UTC (Epoch timestamp TBD) and BIP9 timeout will be midnight TBD UTC (Epoch timestamp TBD). diff --git a/bip-0145.mediawiki b/bip-0145.mediawiki index b90725e..b04c9e6 100644 --- a/bip-0145.mediawiki +++ b/bip-0145.mediawiki @@ -15,20 +15,20 @@ This BIP describes modifications to the getblocktemplate JSON-RPC call ([[bip-00 ===Block Template=== -The template Object is revised to include these keys: +The template Object is revised to include a new key: {| class="wikitable" !colspan=4| template |- ! Key !! Required !! Type !! Description |- -| costlimit || {{No}} || Number || total cost allowed in blocks -|- -| sigoplimit || {{No}} || Number || total sigop cost allowed in blocks divided by 4 -|- -| version || {{Yes}} || Number || block version; clients MUST understand the implications of the version they use (eg, comply with [[bip-0141.mediawiki|BIP 141]] for version 5) +| costlimit || No || Number || total cost allowed in blocks |} +The '!' rule prefix MUST be enabled on the "segwit" rule for templates including transactions with witness data. +In particular, note that even if the client's "rules" list lacks "segwit", server MAY support old miners by producing a witness-free template and omitting the '!' rule prefix for "segwit" in the template's "rules" list. +If the GBT server does not support producing witness-free templates after its activation, it must also use the '!' rule prefix in the "vbavailable" list prior to activation. + ====Transactions Object Format==== The Objects listed in the response's "transactions" key is revised to include these keys: @@ -45,7 +45,11 @@ The Objects listed in the response's "transactions" key is revised to include th | hash || String || reversed hash of complete transaction (with witness data included) encoded in hexadecimal |} -Transactions with witness data may only be included if the template's block version is at least 5. +Transactions with witness data may only be included if the template's "rules" list (see [[bip-0009.mediawiki#getblocktemplate_changes|BIP 9]]) includes "segwit". + +===Sigops=== + +For templates with "segwit" enabled as a rule, the "sigoplimit" and "sigops" keys must use the new values as calculated in [[bip-0141.mediawiki#Sigops|BIP 141]]. ===Block Assembly with Witness Transactions=== @@ -87,6 +91,7 @@ Why shouldn't the server simply add the commitment upfront in the "coinbasetxn", * [https://github.com/bitcoin/bitcoin/pull/7404/files Bitcoin Core] ==See Also== +* [[bip-0009.mediawiki|BIP 9: Version bits with timeout and delay]] * [[bip-0022.mediawiki|BIP 22: getblocktemplate - Fundamentals]] * [[bip-0023.mediawiki|BIP 23: getblocktemplate - Pooled Mining]] * [[bip-0141.mediawiki|BIP 141: Segregated Witness (Consensus layer)]] |