From 1a3c36d8f88fe240497ead681ed0fd9e810bf618 Mon Sep 17 00:00:00 2001 From: {o} Studio Date: Thu, 12 Dec 2019 21:42:49 +0100 Subject: [PATCH] Template as a bitfield --- readme.md | 83 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 44 insertions(+), 39 deletions(-) diff --git a/readme.md b/readme.md index 65671b0..75f5bc2 100644 --- a/readme.md +++ b/readme.md @@ -1,6 +1,6 @@ # OP_PUSHSTATE Draft Specification -OP_PUSHSTATE is a new opcode for the BCH virtual machine which provides direct access to elements of the virtual machine’s state during evaluation. A `template` describes the list and order of state elements according to the [State Item Identifiers](#state-item-identifiers) table. On evaluation, the value of the requested elements are concatenated and pushed to the stack. +OP_PUSHSTATE is a new opcode for the BCH virtual machine which provides direct access to elements of the virtual machine’s state during evaluation. A `template` represents the state elements bitfield according to the [State Item Identifiers](#state-item-identifiers) table. On evaluation, the value of the requested elements are concatenated and pushed to the stack. ## Deployment @@ -14,7 +14,7 @@ OP_PUSHSTATE allows scripts to request state information directly from the virtu ## Opcode Description ``` -Pop the top item from the stack as a state concatenation template. If each byte of the template is recognized, push the identified state value to the stack, otherwise, error. +Pop the top item from the stack as a state concatenation template. If each bit of the template is recognized, push the identified state value to the stack, otherwise, error. ``` ## Codepoint @@ -25,7 +25,7 @@ The next undefined codepoint (`0xbc`/`188`) is defined as `OP_PUSHSTATE`. When the virtual machine encounters an `OP_PUSHSTATE`, the top item is popped from the stack as the `template`. -Each byte in the `template` is confirmed to be defined in the [State Item Identifiers](#state-item-identifiers) table. If not, error. +The `template` is confirmed to be a minimally encoded 1 or 2 bytes long array. If not, error. The value of each identified state item is concatenated together in the order specified by the `template`. If the length of this concatenation exceeds the maximum push length (currently 520 bytes), error. @@ -33,29 +33,38 @@ The concatenated result is pushed to the stack. ## State Item Identifiers -OP_PUSHSTATE `template` bytes are mapped to specific state information as follows: - -| Name | Number | Hex | Description | -| --------------------------------- | ------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------- | -| Version | `1` | `0x01` | The transaction's version number. | -| Transaction Outpoints | `2` | `0x02` | The signing serialization of all transaction outpoints. | -| Transaction Outpoints Hash | `3` | `0x03` | The double-sha256 hash (`OP_HASH256`) of `Transaction Outpoints`. | -| Transaction Sequence Numbers | `4` | `0x04` | The signing serialization of all transaction sequence numbers. | -| Transaction Sequence Numbers Hash | `5` | `0x05` | The double-sha256 hash (`OP_HASH256`) of `Transaction Sequence Numbers`. | -| Outpoint Transaction Hash | `6` | `0x06` | The transaction hash/ID of the outpoint being spent by the current input. | -| Outpoint Index | `7` | `0x07` | The index of the outpoint being spent by the current input. | -| Covered Bytecode Length | `8` | `0x08` | The length of the covered bytecode encoded as a Bitcoin VarInt. | -| Covered Bytecode | `9` | `0x09` | The bytecode segment covered by the signature (A.K.A. `scriptCode`) | -| Output Value | `10` | `0x0a` | The output value of the outpoint being spent by the current input. | -| Sequence Number | `11` | `0x0b` | The sequence number of the outpoint being spent by the current input. | -| Corresponding Output | `12` | `0x0c` | The signing serialization of the transaction output with the same index as the current input. If none, an empty stack item (`0x`). | -| Corresponding Output Hash | `13` | `0x0d` | The double-sha256 hash (`OP_HASH256`) of `Corresponding Output`. | -| Transaction Outputs | `14` | `0x0e` | The signing serialization of all transaction outputs. | -| Transaction Outputs Hash | `15` | `0x0f` | The double-sha256 hash (`OP_HASH256`) of `Transaction Outputs`. | -| Locktime | `16` | `0x10` | The transaction's locktime. | - - -Note, all state item identifiers can be interpreted as valid Script Numbers. This ensures maximum future protocol compatibility and implementation flexibility. Identifiers begin at `1` to reserve both empty stack items (`0x`) and zero values (`0x00`/`0x80`) for use in future extensions. +OP_PUSHSTATE `template` bits are mapped to specific state information as follows: + +| Name | Bit | Hex (BE) | Hex (LE) | Description | +| --------------------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| Version | `1` | `0x01` | `0x01` | The transaction's version number. | +| Transaction Outpoints | `2` | `0x02` | `0x02` | The signing serialization of all transaction outpoints. | +| Transaction Outpoints Hash | `3` | `0x04` | `0x04` | The double-sha256 hash (`OP_HASH256`) of `Transaction Outpoints`. | +| Transaction Sequence Numbers | `4` | `0x08` | `0x08` | The signing serialization of all transaction sequence numbers. | +| Transaction Sequence Numbers Hash | `5` | `0x10` | `0x10` | The double-sha256 hash (`OP_HASH256`) of `Transaction Sequence Numbers`. | +| Outpoint Transaction Hash | `6` | `0x20` | `0x20` | The transaction hash/ID of the outpoint being spent by the current input. | +| Outpoint Index | `7` | `0x40` | `0x40` | The index of the outpoint being spent by the current input. | +| Covered Bytecode Length | `8` | `0x80` | `0x80` | The length of the covered bytecode encoded as a Bitcoin VarInt. | +| Covered Bytecode | `9` | `0x0100` | `0x0001` | The bytecode segment covered by the signature (A.K.A. `scriptCode`) | +| Output Value | `10` | `0x0200` | `0x0002` | The output value of the outpoint being spent by the current input. | +| Sequence Number | `11` | `0x0400` | `0x0004` | The sequence number of the outpoint being spent by the current input. | +| Corresponding Output | `12` | `0x0800` | `0x0008` | The signing serialization of the transaction output with the same index as the current input. If none, an empty stack item (`0x`). | +| Corresponding Output Hash | `13` | `0x1000` | `0x0010` | The double-sha256 hash (`OP_HASH256`) of `Corresponding Output`. | +| Transaction Outputs | `14` | `0x2000` | `0x0020` | The signing serialization of all transaction outputs. | +| Transaction Outputs Hash | `15` | `0x4000` | `0x0040` | The double-sha256 hash (`OP_HASH256`) of `Transaction Outputs`. | +| Locktime | `16` | `0x8000` | `0x0080` | The transaction's locktime. | +## Calculating and pushing template + +The `template` is a sum (binary `OR`) of state element bit values. At least one bit must be set. + +Once the `template` parameter is determined, it needs to be encoded to bytes, and then minimally pushed the same way as `checkbits` in `OP_CHECKMULTISIG`. While the encoding to bytes is straight forward, it is worth emphasizing that certain length-1 byte vectors must be pushed using special opcodes. + +* For `template <= 8`, a length-1 byte array is to be pushed. + * The byte arrays `{0x01}` through `{0x10}` must be pushed using OP_1 through OP_16, respectively. + * The byte array `{0x81}` must be pushed using OP_1NEGATE. + * Other cases will be pushed using no special opcode, i.e., using `0x01