[spec] 2019-05-15 Specification Draft

Add draft specifications for the 2019-05-15 protocol upgrade.

This commit also includes the nChain specification for reenabling
the following opcodes:
  * OP_MUL
  * OP_INVERT
  * OP_LSHIFT
  * OP_RSHIFT

spec/20190515-may-upgrade.md

@@ -0,0 +1,72 @@
+---
+layout: specification
+title: 2019-MAY-15 Network Upgrade Specification
+date: 2018-10-16
+activation: 1557921600
+version: 0.1 DRAFT SUBJECT TO CHANGE
+---
+
+## Summary
+
+When the median time past [1] of the most recent 11 blocks (MTP-11) is greater than or equal to UNIX timestamp 1557921600, Bitcoin Cash will execute an upgrade of the network consensus rules according to this specification. Starting from the next block these consensus rules changes will take effect:
+
+* Enable the following opcodes
+  * OP_MUL
+  * OP_INVERT
+  * OP_LSHIFT
+  * OP_RSHIFT
+* Enable Schnorr signatures
+* Enforce minimal pushdata
+* Enforce NULLDUMMY (BIP0147)
+* Replace transaction size >100 byte requirement with transaction size not equal 64 bytes.
+
+The following are not consensus changes, but are recommended changes for Bitcoin Cash implementations:
+
+* Automatic replay protection for future upgrade
+
+## OpCodes
+
+The following opcodes will be re-enabled per [20190515-reenabled-opcodes.md](2019-may-opcodes.md):
+
+* OP_MUL
+* OP_INVERT
+* OP_LSHIFT
+* OP_RSHIFT
+
+## Schnorr Signatures
+
+Support schnorr signatures per [schnorr-signatures.md](schnorr-signatures.md):
+
+## Enforce minimal pushdata
+
+As per existing standardness checks, enforce that all pushed data is a minimal representation at the script layer.
+
+## Enforce NULLDUMMY (BIP0147)
+
+As per BIP0147, enforce that the dummy element in OP_CHECKMULSIG(VERIFY) is a null
+stack element.  This will go into effect at the consensus layer.
+
+## Allow transactions <100 bytes, except 64 bytes specifically
+
+Replace transaction size >100 byte requirement with transaction size not equal 64 bytes.
+
+This rule prevents a hash griding attack, where SPV wallets can confuse a 64 byte transaction for a merkle node.
+The amount of entropy in each 32-byte sections of the transaction is insufficient to prevent a preimage attack. 
+In this case, a valid transaction could be found with a hash equal
+to the first, or last, 32 bytes of a 64-byte transaction.
+
+## Automatic Replay Protection
+
+When the median time past [2] of the most recent 11 blocks (MTP-11) is less than UNIX timestamp 1573819200 (Nov 2019 upgrade) Bitcoin Cash full nodes MUST enforce the following rule:
+
+ * `forkid` [1] to be equal to 0.
+
+When the median time past [1] of the most recent 11 blocks (MTP-11) is greater than or equal to UNIX timestamp 1573819200 (Nov 2019 upgrade) Bitcoin Cash full nodes implementing the May 2019 consensus rules SHOULD enforce the following change:
+
+ * Update `forkid` [1] to be equal to 0xFF0002.  ForkIDs beginning with 0xFF will be reserved for future protocol upgrades.
+
+This particular consensus rule MUST NOT be implemented by Bitcoin Cash wallet software. Wallets that follow the upgrade should not have to change anything.
+
+## References
+
+[1] The `forkId` is defined as per the [replay protected sighash](replay-protected-sighash.md) specification.

spec/20190515-reenabled-opcodes.md

@@ -0,0 +1,212 @@
+---
+layout: specification
+title: Specification for Re-enabling old Opcodes, May 2019
+date: 2018-08-03
+version: 1.0
+updated: 2018-08-13
+---
+
+# Introduction
+
+In May 2018 several disabled opcodes were reintroduced to the Bitcoin Cash scripting engine2. The scope of that change was limited in order to focus developer attention rather than attempting to reintroduce all of the disabled opcodes at once. This specification expands upon that change by reintroducing additional opcodes.
+
+This specifications describes the opcodes that are proposed to be added in the May 2019 protocol upgrade.
+
+The opcodes to be added are:
+
+| Word | OpCode | Hex | Input | Output | Description |
+| :--- | :----- | :-- | :---- | :----- | :---------- |
+| OP_MUL | 149 | 0x95 | n1 | n2 | out | Multiplies two numbers |
+| OP_RSHIFT | 153 | 0x99 | b | n | out | Right shift b by n bits |
+| OP_LSHIFT | 152 | 0x98 | b | n | out | Left shift b by n bits |
+| OP_INVERT | 131 | 0x83 | b | out | Bitwise | NOT |
+
+## Data types
+
+Script data values are byte sequences but may be interpreted as numeric values by some opcodes. Specification of the data types used by Script is beyond the scope of this document.
+
+For accuracy in this specification, byte sequence values are represented as a sequence of byte values surrounded by curly brackets, such as {0x01, 0x02, 0x03}. This sequence is three bytes long, it begins with a byte of value 1 and ends with a byte of value 3.
+
+Numeric data values are represented in this document as decimal numbers, such as 35315.
+
+In this specification, a variable representing a byte sequence is named using the symbol b. A variable representing a numeric value is named using the symbol n.
+
+## Overflow
+
+Conceptually overflow means that the result of the operation is out-of-bounds.
+
+For consistency with previous opcodes and to avoid exposing underlying implementation details, all of the opcodes defined in this document give no indication of overflow.
+
+Note that divide by zero is a separate error and reported as such.
+
+## Definitions
+Operand order: In keeping with convention, where multiple operands are specified the top most stack item is the last operand. For example:
+```
+n1 n2 OP_MUL → out
+```
+is the same as
+
+1. Push n1 onto stack
+2. Push n2 onto stack
+3. Execute OP_MUL
+
+The result is that n2 and n1 are popped from the stack and replaced by out.
+
+## Global Conditions
+
+The following conditions apply to all opcodes. These conditions must be checked by the implementation to ensure that no violations occur:
+
+1. for all b : elements on the stack, 0 <= len(b) <= MAX_SCRIPT_ELEMENT_SIZE
+2. for each opcode, the prerequisite number of operands are present on the stack when the
+opcode is executed
+
+These unit tests should be included for every opcode:
+
+1. Executing the opcode with an input element of length greater than
+MAX_SCRIPT_ELEMENT_SIZE fails.
+2. Executing the opcode with an insufficient number of operands on the stack fails.
+
+## Operand Consumption
+
+In all cases the opcode and operand stack elements are consumed by the opcode and replaced with the output.
+
+# Arithmetic Operators
+
+## OP_MUL
+
+Opcode (decimal): 149
+Opcode (hex): 0x95
+Description: Multiply two operands.
+
+```
+n1 n2 OP_MUL → out,
+where out is the product (multiplication) of n1 and n2.
+```
+
+### Examples:
+* 4 7 OP_MUL → 28
+* -4 7 OP_MUL → -28
+
+Any overflow is ignored. The result of the opcode may be a byte sequence that is too large to be interpreted as a numeric value.
+
+Impact of successful execution:
+
+* The number of elements on stack is reduced by one.
+
+### Unit Tests
+
+1. b1 b2 OP_MUL -> FAIL - where b1 is not a valid numerical value or b2 is not a valid
+numerical value, or both
+2. The following test will be repeated with various values for n1 and n2. The values of n1 and n2 must include values which have byte sequence representations of size 1 to 4 bytes inclusive. The tests will be repeated with values n1,n2 and -n1,n2 and n1,-n2 and -n1,-n2.
+  a. n1 n2 OP_MUL → n1*n2
+  b. n1 1 OP_MUL → n1
+  c. n1 0 OP_MUL → 0 3. n1 n2 OP_MUL -> b - where (n1 * n2) is too large to be represented in 4 bytes. The result b must be a byte sequence which is a representation of (n1*n2) but larger than 4 bytes.
+
+# Bitwise Operators
+
+The result produced by these opcodes is always the same size as the operand.
+The execution cost of these opcodes is proportional to the length of the operand.
+
+## OP_RSHIFT
+
+Opcode (decimal): 153
+Opcode (hex): 0x99
+Description: Right shift b by n bits.
+
+```
+b n OP_RSHIFT → out,
+where out is the byte sequence created by a right shift of the binary bit pattern b by n bits.
+```
+
+There is no limit imposed on the value of n except that n must be a valid numerical value and must be non-negative. If n is negative, the script fails.
+
+If n is greater than the number of bits in the byte sequence, the result is a zero filled byte sequence equal in length to the original byte sequence. This is consistent with the interpretation of b n OP_RSHIFT as equal to b 1 OP_RSHIFT repeated n times. This amounts to a logical, rather than arithmetic shift.
+
+Impact of successful execution:
+
+* The number of elements on stack is reduced by one.
+
+### Unit Tests
+
+These tests may be repeated with a number of values for b and n.
+
+1. b 0 OP_RSHIFT → b
+2. b n OP_RSHIFT → out with for various n > 0, including when n > len(b)
+3. b n OP_RSHIFT → fails with error with n < 0
+
+## OP_LSHIFT
+
+Opcode (decimal): 152
+Opcode (hex): 0x98
+Description: Left shift b by n bits.
+
+```
+b n OP_LSHIFT → out,
+where out is the byte sequence created by a left shift of binary bit pattern b by n bits.
+```
+
+There is no limit imposed on the value of n except that n must be a valid numerical value and must be non-negative. If n is negative, the script fails.
+
+If n is greater than the number of bits in the byte sequence, the result is a zero filled byte sequence equal in length to the original byte sequence. This is consistent with the interpretation of b n OP_LSHIFT as equal to b 1 OP_LSHIFT repeated n times.
+
+Impact of successful execution:
+
+* The number of elements on stack is reduced by one.
+
+### Unit Tests
+
+These tests must be repeated with a number of values for b and n.
+
+1. b 0 OP_LSHIFT → b
+2. b n OP_LSHIFT → out with for various n > 0, including when n > len(b)
+3. b n OP_LSHIFT → fails with error with n < 0
+
+## OP_INVERT
+
+Opcode (decimal): 131
+Opcode (hex): 0x83
+Description: Bitwise invert.
+
+```
+b OP_INVERT → out,
+where out is b bitwise inverted.
+```
+
+Impact of successful execution:
+
+* The number of elements on stack is unchanged.
+
+### Unit Tests
+
+1. {} OP_INVERT → {}
+2. b OP_INVERT → bitwise invert(x) for various b and various sizes of b. E.g. {0x80, 0x12, 0x34} → {0x7F, 0xED, 0xCB}
+
+# References
+
+[1] [https://en.bitcoin.it/wiki/Script#Opcodes](https://en.bitcoin.it/wiki/Script#Opcodes)
+
+[2] [may-2018-reenabled-opcodes.md](https://github.com/bitcoincashorg/bitcoincash.org/blob/master/spec/may-2018-reenabled-opcodes.md)
+
+# Specification Status
+
+This document is a final draft in Google Doc format. It will be made available for public comment. It will also be transcribed into Markdown format and submitted to the bitcoincashorg GitHub repository.
+This document is a specification document. It was produced following a proposal, community discussions in the “[WG] OpCodes” telegram group, and a workshop style meeting.
+The proposal document is [here](https://docs.google.com/document/d/1KaX9IUJRBXl_r7ZsjYEt67s07x22jcaTw06zFhCFYdw/edit).
+The meeting was held on 19th July 2018, the agenda is [here](https://drive.google.com/file/d/14xYdMV-7yAhWWElJ5GVMpaydQmNI9EpT/view).
+
+# Document History
+
+* 2018-08-13 - Daniel Connolly, nChain Ltd - included license
+* 2018-08-13 - Daniel Connolly, nChain Ltd - version 1.0
+* 2018-08-06 - Daniel Connolly, nChain Ltd - minor edits, grammar, typos
+* 2018-08-03 - Shaun O’Kane, nChain Ltd - initial version
+
+# License
+
+Copyright 2018 nChain Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this specification, to deal in the specification without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the specification, and to permit persons to whom the specification is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the specification.
+
+THE SPECIFICATION IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SPECIFICATION OR THE USE OR OTHER DEALINGS IN THE SPECIFICATION.