Version: 2020-01-09
Authors: nChain Ltd
- Introduction
- Definitions
- Upgrade Activation Mechanism
- UTXO Height Rule Determination
- Changes to the Bitcoin Specification
- Block Consensus Rules
- Block Size Consensus Rule
- Number of CheckSig Operations per MB of Block Space
- Transaction Consensus Rules
- Maximum Transaction Size
- Maximum Number of CheckSig Operations per Transaction
- nLockTime & nSequence
- Script Language Rules
- Data Types
- Formal Grammar for Bitcoin Script
- Validity of Script Consensus Rule
- PUSHDATA Only in Unlocking Script Consensus Rule
- Disabled Operations Consensus Rule
- Script Element Size Consensus Rule
- Stack Size Consensus Rule
- Script Size Consensus Rule
- Numeric Value Size Consensus Rule
- Number of Public Keys per Multisig Consensus Rule
- Number of Non-Push Operations Per Script Consensus Rule
- Stack Memory Usage Consensus Rule
- Sunset P2SH
- OP_RETURN Functionality
- Sunset OP_CHECKLOCKTIMEVERIFY & OP_CHECKSEQUENCEVERIFY
- Block Consensus Rules
- Standard Local Policies
- Standard Local Transaction Policies
- Maximum Acceptable Transaction Size Policy
- Transaction Evaluation Timeout
- Standard Local Script Language Policies
- Numeric Value Length
- Stack Memory Usage Policy
- Standard Local P2P Network Policies
- Propagation of non-Standard Transactions
- Standard Local Transaction Policies
- Notes
This is the specification of the Genesis Upgrade. It defines the upgrade activation mechanism, the changes to the Bitcoin Specification and the Consensus Rules, as well as the Standard Local Policies that are recommended for client implementations.
This document is a specification. It is not a guide and it does not describe implementation specifics or emergent behaviour of the system.
The Bitcoin Rules are the precise rules which define Bitcoin. These include rules such as: the sum of the value of the inputs of a transaction must be greater than or equal to the sum of the values of the outputs, and the block subsidy schedule. These are the foundational rules of Bitcoin, irrespective of implementation.
The Consensus Rules are additional rules that have been reached by general agreement and are necessary to implement the Bitcoin Specification in software. They are needed because software has limitations and agreements are needed in order to facilitate integration of the software. Some Consensus Rules are configurable in the software, some are not. An example of a non-configurable Consensus Rule is that the version of a transaction must fit in a signed 32-bit integer. An example of a configurable Consensus Rule, after Genesis activation, is the maximum accepted block size.
Local Policies are additional controls that are implemented in software and may place additional restrictions on the transactions and blocks that the software will propagate to other systems and, for transactions, confirm in blocks. Policies are “local”, they apply to the instance of software that is running, they do not apply to the validation of blocks, or the transactions within a block. A block accepted from another miner may contain transactions that do not conform to local policy.
Standard Policies are common local policies that are used by client software. They are defined as a Standard to facilitate common application across independent software implementations but it is important to note that it is not required that software implement or adhere to these policies.
Throughout this specification the following words are used with specific meanings:
- valid - a transaction or block is valid if it follows the Bitcoin and Consensus rules.
- invalid - a transaction or block is invalid if it does not follow either the Bitcoin or Consensus rules.
- rejected - a transaction or block may be rejected by an implementation due to a Policy. The implementation may not have determined whether the transaction or block was valid or invalid.
Throughout this specification the metric system is used. One KB is one kilobyte which is 1,000 bytes.
The Genesis Upgrade will activate at the block heights defined in the table below.
| Mainnet | 620,538 |
| Testnet | 1,344,302 |
| Scaling Test Network | 14,896 |
| Regtest | 10,000 |
The upgraded Bitcoin Rules, Consensus Rules, and Policies become active in the block that is mined at this height.
The Genesis Upgrade introduces the “UTXO Height” mechanism for determining the Bitcoin Rules, Consensus Rules, and Policies that are to be applied to a transaction. The purpose of this mechanism is to maintain compatibility for UTXO’s that were created under the previous version of the Bitcoin Rules and Consensus Rules.
Every output of a transaction is evaluated under the rules that are in effect for the block in which the transaction is being confirmed. If a transaction is confirmed in a block that has a height which is greater or equal to the Genesis activation height, then the outputs of that transaction must comply with the Genesis Upgrade. If a transaction is confirmed in a block that has a height which is less than the Genesis activation height, then the outputs of that transaction must comply with the rules prior to the Genesis Upgrade.
Every input of a transaction is evaluated under either the rules prior to the Genesis Upgrade, or the Genesis Upgrade rules, depending on whether the UTXO that is being spent by the input was, or will be, confirmed prior to the Genesis activation height or after the Genesis activation height. If the transaction which contains the UTXO that is being spent was, or will be, confirmed in a block before the Genesis activation height then the input script and the output script for the UTXO being spent by that input are evaluated according to rules prior to the Genesis Upgrade. If the transaction which contains the UTXO that is being spent was, or will be, confirmed in a block with a height greater than or equal to the Genesis activation height, then the input script and the output script for the UTXO being spent by that input are evaluated according to the Genesis Upgrade.
Other characteristics of the transaction, such as the maximum number of sigops, are evaluated according to the rules that are in effect for the block in which the transaction is being confirmed.
It is worth noting that, after Genesis activation, a single transaction may spend inputs from before Genesis activation and after Genesis activation, in which case each input is evaluated under the rules that are applicable to that input based upon the block height that the transaction referenced by that input was confirmed.
These consensus rules apply to blocks that are produced after Genesis activation.
The size of a block is the size in bytes of the serialized form of the block, including the block header and all of the transactions confirmed by the block1.
The consensus rule that restricts the maximum size of a block to a specific number of bytes has been converted into a configurable consensus rule. The default value of the maximum acceptable size of a block is unlimited.
Miners are expected to reach consensus on this value and configure it manually.
The consensus rule that limits the number of checksig operations per megabyte of block space has been removed.
These consensus rules apply to transactions that are confirmed in blocks after Genesis activation.
The size of a transaction is the size in bytes of the serialized form of the transaction2.
The maximum size of a transaction is 1GB (1,000,000,000 bytes). This limitation is expected to be lifted in the future.
The consensus rule that limits the number of checksig operations per transaction has been removed.
After Genesis activation, the functionality of the nLockTime field of a transaction and the nSequence fields of transaction inputs revert to their original purpose. The rules defined here only apply to transactions that are confirmed after Genesis activation.
The nSequence fields of every transaction input and the nLockTime field of the transaction collectively determine the “finality” of a transaction. If a transaction is “non-final” then it can not be valid but it can become “final” at a later time. If a transaction is “final” then it can be valid.
- If the value of nSequence of a transaction input is 0xFFFFFFFF then that input is a “final input”.
- If the value of nSequence of a transaction input is not 0xFFFFFFFF then that input is a “non-final input”.
- If all of the inputs of a transaction are “final inputs” then the transaction is “final”, irrespective of the value of the nLockTime field.
- If one or more of the inputs of a transaction are “non-final inputs” then:
- If the value of the transactions nLockTime field is less than 500,000,000 then the field represents a block height.
- If the height of the block in which the transaction is being confirmed is greater or equal to the value of this field, then the transaction is “final”.
- Otherwise the transaction is “non-final”
- If the value of the transactions nLockTime field is greater or equal to 500,000,000 then the field represents a UNIX epoch timestamp.
- If the MTP of the last 11 blocks is greater or equal to the value of this field, then the transaction is “final”.
- Otherwise, the transaction is “non-final”.
- If the value of the transactions nLockTime field is less than 500,000,000 then the field represents a block height.
A “final” transaction may be confirmed in a block following the “first-seen” rule.
A new transaction must replace a prior “non-final” transaction if it has the same inputs in the same order and every sequence number for every input in the new transaction is not less than the sequence number for the corresponding input in the prior transaction and the sequence number of at least one input in the new transaction is greater than the sequence number for the corresponding input in the prior transaction.
If a new transaction is detected which does not fulfill all of these requirements then it must be rejected.
If a new transaction is detected which has inputs that conflict with the inputs of a “non-final” transaction, but which are not identical to the inputs of the “non-final” transaction, then the “non-final” transaction is the “first seen” transaction and takes priority over the new transaction.
Bitcoin Script is the programming language that is used to lock and unlock transaction outputs. This section contains changes to the Script Language Rules.
The rules defined here apply to locking and unlocking scripts for transactions outputs that are created after the Genesis activation. The previous rules apply to transaction outputs created prior to Genesis activation.
All data items in Bitcoin Script are a byte sequence. Some operations interpret their parameters as numeric or boolean values and require the item to fulfill the requirements of those types. Some operations produce items on the stack which are valid numeric or boolean values.
A byte sequence has a length and a value. The length of the byte sequence must be an integer greater or equal to zero and less than or equal to 2^32-1 (UINT32_MAX).
The byte sequence of length zero is called the “null value”.
Any data item can be interpreted as a boolean value. If the data item consists entirely of bytes with value zero, or the data item is the null value, then the boolean value of the item is false. Otherwise, the boolean value of the item is true.
A data item can be interpreted as a numeric value. The numeric value is encoded in a byte sequence using little-endian notation. The byte sequence of length zero (the null value) is the standard representation for the numeric value zero. There is a Consensus Rule on the maximum size of a numeric value that is defined below.
A formal grammar has been defined for Bitcoin Script. This section of the document defines that grammar but it does not describe how this definition is applied. The application of the grammar definition is described in further parts of this document.
This grammar is fully described by the following BNF grammar:
<script> ::= <unlocking-script> <locking-script>
<unlocking-script> ::= <constants> | <empty>
<locking-script> ::= <script-block> ["OP_RETURN" <non-script-data>]
<script-block> ::= <function> [<script-block>] |
<push-data> [<script-block>] |
<branch> [<script-block>] |
"OP_RETURN" [<script-block>] |
<empty>
<branch> ::= <op-if> <script-block> ["OP_ELSE" <script-block>]
"OP_ENDIF"
<op-if> ::= "OP_IF" | "OP_NOTIF"
<constants> ::= <constant> [<constants>]
<constant> ::= "OP_PUSHDATA1" <count-1> "bytes" |
"OP_PUSHDATA2" <count-2> "bytes" |
"OP_PUSHDATA4" <count-4> "bytes" |
<op-push-xx> "bytes" | <op-false> |
<op-true> | "OP_2" | "OP_3" | "OP_4" |
"OP_5" | "OP_6" | "OP_7" | "OP_8" | "OP_9" |
"OP_10" | "OP_11" | "OP_12" | "OP_13" |
"OP_14" | "OP_15" | "OP_16"
<count-1> ::= a one byte unsigned integer (0-255)
<count-2> ::= a two byte unsigned integer (0-65535, little-endian encoded)
<count-4> ::= a four byte unsigned integer (0-4294967295, little-endian encoded)
<op-push-xx> ::= hex codes 0x01 to 0x4b
<op-false> ::= "OP_0" | "OP_FALSE"
<op-true> ::= "OP_1" | "OP_TRUE"
<function> ::= "OP_NOP" | "OP_VERIFY" |
"OP_TOALTSTACK" | "OP_FROMALTSTACK" | "OF_IFDUP" |
"OP_DEPTH" | "OP_DROP" | "OP_DUP" | "OP_NIP" | "OP_OVER" |
"OP_PICK" | "OP_ROLL" | "OP_ROT" | "OP_SWAP" | "OP_TUCK" |
"OP_2DROP" | "OP_2DUP" | "OP_3DUP" | "OP_2OVER" |
"OP_2ROT" | "OP_2SWAP" | "OP_SIZE" | "OP_EQUAL" |
"OP_EQUALVERIFY" | "OP_1ADD" | "OP_1SUB" | "OP_NEGATE" |
"OP_ABS" | "OP_NOT" | "OP_0NOTEQUAL" | "OP_ADD" |
"OP_SUB" | "OP_BOOLAND" | "OP_BOOLOR" | "OP_NUMEQUAL" |
"OP_NUMEQUALVERIFY" | "OP_NUMNOTEQUAL" | "OP_LESSTHAN" |
"OP_GREATERTHAN" | "OP_LESSTHANOREQUAL" |
"OP_GREATERTHANOREQUAL" | "OP_MIN" | "OP_MAX" |
"OP_WITHIN" | "OP_RIPEMD160" | "OP_SHA1" | "OP_SHA256" |
"OP_HASH160" | "OP_HASH256" | "OP_CODESEPARATOR" |
"OP_CHECKSIG" | "OP_CHECKSIGVERIFY" | "OP_CHECKMULTISIG" |
"OP_CHECKMULTISIGVERIFY" | "OP_CAT" | "OP_SPLIT" |
"OP_AND" | "OP_OR" | "OP_XOR" | "OP_DIV" | "OP_MOD" |
"OP_NUM2BIN" | "OP_BIN2NUM" | "OP_NOP1" | "OP_NOP2" |
"OP_NOP3" | "OP_NOP4" | "OP_NOP5" | "OP_NOP6" |
"OP_NOP7" | "OP_NOP8" | "OP_NOP9" | "OP_NOP10" |
"OP_MUL" | "OP_LSHIFT" | "OP_RSHIFT" | "OP_INVERT" |
"OP_2MUL" | "OP_2DIV" | "OP_VERIF" | "OP_VERNOTIF"
<non-script-data> ::= any sequence of bytes
It’s worth highlighting the following features of this formal grammar:
- The complete script consists of two sections, the unlocking script and the locking script. The locking script is included in the transaction output that is being spent, the unlocking script is included in the transaction input that is spending the output.
- The unlocking script can only contain constants. This requirement is part of Validity of Script Consensus Rule, defined later.
- A branching operator (OP_IF or OP_NOTIF) must have a matching OP_ENDIF.
- An OP_ELSE can only be included between a branching operator and OP_ENDIF pair. There can only be at most one OP_ELSE between a branching operator and an OP_ENDIF.
- OP_RETURN may appear at any location in a valid script. The functionality of OP_RETURN has been restored and is defined later in the section OP_RETURN Functionality. Grammatically, any bytes after an OP_RETURN that is not in a branch block are not evaluated and there are no grammatical requirements for those bytes.
- Note that disabled operations are included in this grammar. A disabled operation is grammatically correct but will produce a failure if executed.
The locking and unlocking scripts for every input of a transaction must be grammatically valid, as defined by the formal grammar above.
Note that this includes the requirement that unlocking scripts only contain PUSHDATA operations.
Also note that the scripts must be grammatically valid when they are spent. It is not required that the output scripts of a transaction are grammatically valid although it is highly recommended that client software implement this restriction as a policy.
After Genesis activation, the unlocking scripts used in transaction inputs may only contain PUSHDATA operations, as defined by the formal grammar above.
In contrast to all the other updates in this section, this consensus rule is activated for all inputs of transactions that are, or will be, confirmed in a block after Genesis activation, regardless of the height of the UTXO being spent.
This rule is a subset of the Validity of Script Consensus Rule defined above but is included separately because the activation conditions are different.
The following operations are disabled: OP_2MUL, OP_2DIV, OP_VERIF, OP_VERNOTIF.
Although these operations are grammatically correct and can appear in valid Script, their execution will cause script failure and therefore transaction invalidity. If they are present in un-executed script, the script execution may succeed.
It is very strongly recommended that these operations not be used at all until they are activated.
The consensus rule that limits the maximum size of a script element has been removed.
The functionality previously provided by this consensus rule is now covered by the Stack Memory Usage Consensus Rule.
The consensus rule that limits the combined number of elements that can be placed on the stack, and the altstack, has been removed.
The functionality previously provided by this consensus rule is now covered by the Stack Memory Usage Consensus Rule.
The consensus rule that limits the maximum size of a script has been removed.
The functionality previously provided by this consensus rule is now covered by the Maximum Transaction Size Consensus Rule and the Stack Memory Usage Consensus Rule.
For a byte sequence to validly represent a numeric value, the length of the byte sequence must be less than or equal to 750,000 bytes. A byte sequence that is larger than this is a valid byte sequence but is not a valid numeric value.
Note that while some operations require parameters to be valid numeric values, they may produce byte sequences which are not valid numeric values (for example, OP_MUL may produce a byte sequence which is too large to validly represent a numeric value).
The consensus rule that limits the number of public keys per multisig has been changed to be 2^31-1 (INT32_MAX).
The consensus rule that limits the number of non-push operations per script has been removed.
The functionality previously provided by this consensus rule is now covered by the Stack Memory Usage Consensus Rule while other capabilities manage the cost of execution.
The stack memory usage consensus rule limits the amount of memory that can be used on the stacks. This rule is evaluated against the sum of the memory used by the stack and the memory used by the altstack.
If the execution of the unlocking and locking script for an input uses more stack memory than defined in this rule, then the transaction is invalid.
The memory usage of a stack is calculated using a specific formula, so that it can be coordinated across software implementations. The formula for calculating the memory usage of a stack is:
usage = sum of (for each element: 32 + size in bytes of element)
where "size in bytes of element" is the size in bytes of the element when serialized in the Bitcoin Serialization Format.
This is a configurable consensus rule, with a default value that is formally unlimited but will in practice depend on the capabilities of the system that is evaluating the script.
Miners are expected to reach consensus on this value and configure it manually.
Pay to script hash (P2SH) is a capability that was added to Bitcoin in 2012 by BIP13. It assigns a special meaning to a specific output script template. If the specific script template is present in the script of an output that is being spent by an input then it is treated in a different way, rather than being executed normally.
The p2sh script template is identified as OP_HASH160 <20 bytes data> OP_EQUAL, or in hex a914 <20 bytes data> 87,
where the 20 bytes of data will vary depending on the redeem script being used.
The P2SH capability is being removed by the Genesis Upgrade and the presence of a p2sh script template in an output will invalidate a transaction.
The functionality of the OP_RETURN operation is being restored. OP_RETURN will cause termination of the script and the validity of the script is determined by the value of the top item on the stack.
OP_CHECKLOCKTIMEVERIFY and OP_CHECKSEQUENCEVERIFY are operations that were introduced by BIP0065 and BIP0112.
These operations revert to NOP’s, which have no effect.
However, most implementations have a local policy which rejects scripts that contain “upgradeable NOPs”, including these, and will reject transactions containing these operations.
Policies are settings that are configured by software operators. These settings are generally required by software implementations. It is expected that as implementations of the software mature that these settings will be adjusted.
Policies control which transactions the software will propagate across the P2P network or include in a block. However, policies are not Bitcoin Rules or Consensus Rules and are not used to determine the validity of blocks or the transactions confirmed by a block.
Four new standard policies have been defined as part of the Genesis Upgrade and one prior policy has been changed. These policies are listed below. It must be noted that this is not an exhaustive list of all standard policies, many of the policies that were standard before the Genesis Upgrade have been retained.
The maximum acceptable transaction size is a standard policy that configures the largest transactions that the software will propagate across the P2P network or include in a block.
The value of this configuration item must be less than or equal to the value of the Maximum Transaction Size Consensus Rule or it will have no effect
The default value for this policy setting is 10MB (10,000,000 bytes).
The transaction evaluation timeout is a standard policy that defines the maximum amount of time that the software will allow for the evaluation of a transaction before terminating the evaluation and rejecting the transaction. This setting is always defined with a time unit and the default value is 1 second.
This policy applies to transactions that are received by the software and its processes for determining whether the transaction should be propagated across the P2P network or included in a block. The policy does not apply to the evaluation of transactions in a confirmed block.
Note that:
- if the evaluation of a transaction is terminated due to exceeding the timeout limit then the software has not determined whether the transaction is valid or invalid, it has merely decided not to make that determination;
- the time taken to evaluate a transaction by a particular system will vary based on the software used, the resources available, and other dynamic factors such as the load on the system. It is not an exact measurement.
Script Language Policies apply to the execution of script.
It must be noted that there are existing policies regarding the representation of numeric values in byte sequences, in particular the minimal encoding policy. These policies have not been changed as part of the Genesis Upgrade and are not documented here.
The length of numeric value policy defines the maximum length of a byte sequence to be considered a valid numeric value. The default value for this policy is 250,000 bytes.
Transactions which contain script that consume numeric values that are larger than this policy setting will be rejected; they will not be propagated across the P2P network or included in a block.
The stack memory usage policy limits the amount of memory that can be used on the stacks. This policy is evaluated against the sum of the memory used by the stack and the memory used by the altstack.
If the execution of the unlocking and locking script for an input uses more stack memory than defined in this policy, then the transaction is rejected.
The memory usage of a stack is calculated using the same formula described in the Stack Memory Usage Consensus Rule (above).
The default value for this policy is 100MB (100,000,000 bytes). The value of this policy must be less than or equal to the value of the Stack Memory Usage Consensus Rule.
The local policy on the Propagation of non-standard transactions controls whether the software will propagate non-standard transactions to other peers on the P2P network.
Before Genesis Activation, the default setting for this policy is that non-standard transactions will not be propagated across the P2P Network.
After Genesis Activation, the default setting for this policy is that non-standard transactions will be propagated across the P2P Network.
Note that even though non-standard transactions will be propagated across the P2P Network after Genesis activation, other policies such as the Maximum Acceptable Transaction Size Policy remain in effect.