diff --git a/docs/README.md b/docs/README.md index 3409fe5f..12127d03 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1046,141 +1046,53 @@ docker-compose up ## OpReturn -OP_RETURN is a [script opcode](https://wiki.bitcoinsv.io/index.php/OP_RETURN) that allows adding extra information to transactions beyond standard inputs and outputs. This can be useful for applications that want to include: +The `op-return` prop is used to pass additional metadata in the form of a structured string. The content can be seen in the message returned in the callbacks (`onSuccess` and `onTransaction`) as a parameter. This string can be: -* Different transaction categories related e.g. to gameplay events; +- A normal string, such as a simple message or phrase. +- Stringified JSON. +- An array of values separated by a `|`. +- A key-value formatted string, where keys and values are separated by `=` and multiple values for a key are separated by `|`. -* Invoice numbers; +### Examples: -* Nonces to differentiate payments of the same amount; - -* Other data. - -### General OpReturn structure - -Hex-encoded bytes representing: - - - -### General Syntax Rules: - -The data is composed by the following hex-encoded components: - -1. **OP_RETURN opcode**: `6a`. - -2. Pushdata indicating the size (in bytes) of the protocol identifier. Always 4 (`04` in hex) in the case of the PayButton protocol. - -3. **Protocol identifier**: `50415900` for PayButton (ASCII `PAY` + `0x00`). - -4. **Version**: A byte allowing future updates (currently `00`). - -5. Pushdata indicating the size (in bytes) of data payload identifier. - -6. **Data Payload**: Custom information in UTF-8 format. The maximum size is 213 bytes (UTF-8 encoded) if there is no **payment ID** (nonce). If a **payment ID** is present, the limit is 205 bytes, as the **payment ID** occupies 8 bytes. Can be empty. - -7. Pushdata indicating the size (in bytes) of nonce identifier. - -8. **Nonce**: Eight random bytes to differentiate payments (can be empty). - -If the **data payload** or **nonce** is empty, the pushdata for each will be `00`. - - - -### How to send data using the OP_RETURN opcode in PayButton - -To send data using the OP_RETURN opcode in PayButton, you can use the `op-return` prop. The content of the `op-return` prop will be encoded and will correspond to the **data payload**, mentioned above. Additionally, you may use the **payment ID** as a nonce. To disable sending the **payment ID**, use the `disable-payment-id` prop — PayButton will automatically encode the message according to the rules specified bellow. - - -### PayButton OpReturn encoding examples: - - -#### 1. OpReturn message with 12 bytes of data and no nonce - - - 6a0450415900000c0102030405060708090a0b0c00 - - - -Breaking this down: - - - -- `6a` → OP_RETURN opcode - -- `04` → Pushdata indicating the size of the protocol identifier - -- `50415900` → PayButton identifier (ASCII `PAY` + `0x00`) - -- `00` → Version 0 - -- `0c` → Pushdata indicating the size of data payload identifier - -- `0102030405060708090a0b0c` → Data payload - -- `00` → Pushdata for payment ID (nonce), indicating there will be none - - - -#### 2. OpReturn message with 12 bytes of data and an 8-byte nonce - - 6a0450415900000c0102030405060708090a0b0c080102030405060708 - - - -- `6a` → OP_RETURN opcode - -- `04` → Pushdata indicating the size of the protocol identifier - -- `50415900` → PayButton identifier (ASCII `PAY` + `0x00`) - -- `00` → Version 0 - -- `0c` → Pushdata indicating the size of data payload identifier - -- `0102030405060708090a0b0c` → Data payload - -- `08` → Pushdata indicating that this transaction has an 8-byte payment ID - -- `0102030405060708` → Payment ID - - - -#### 3. OpReturn message with no data but an 8-byte payment ID (nonce) - - 6a04504159000000080102030405060708 - - -- `6a` → OP_RETURN opcode - -- `04` → Pushdata indicating the size of the protocol identifier - -- `50415900` → PayButton identifier (ASCII `PAY` + `0x00`) - -- `00` → Version 0 - -- `00` → No data payload - -- `08` → Pushdata indicating that this transaction has an 8-byte payment ID - -- `0102030405060708` → Payment ID - -#### 4. Transaction with no data and no payment ID - - 6a0450415900000000 - -- `6a` → OP_RETURN opcode - -- `04` → Pushdata indicating the size of the protocol identifier - -- `50415900` → PayButton identifier (ASCII `PAY` + `0x00`) +#### Simple String +```html +op-return="hello world" +``` +- A plain string with no parsing behavior. -- `00` → Version 0 +#### Key-Value Formatted String +```html +op-return="classOf=2013 bullYears=2013|2017|2021" +``` +- This format will be parsed into an object: +```json +{ + "classOf": 2013, + "bullYears": [2013, 2017, 2021] +} +``` -- `00` → Pushdata for data payload, indicating there will be none +#### JSON String +```html +op-return="{'foo': 'bar'}" +``` +- This format will be parsed into an object: +```json +{ + "foo": "bar" +} +``` -- `00` → Pushdata for payment ID, indicating there will be none +#### Pipe-Separated Values +```html +op-return="item1|item2|item3" +``` +- This format will be parsed into an array: +```json +["item1", "item2", "item3"] +``` - ## Donate diff --git a/docs/op-return-specs.md b/docs/op-return-specs.md new file mode 100644 index 00000000..c6250b57 --- /dev/null +++ b/docs/op-return-specs.md @@ -0,0 +1,137 @@ +## OpReturn + +OP_RETURN is a [script opcode](https://wiki.bitcoinsv.io/index.php/OP_RETURN) that allows adding extra information to transactions beyond standard inputs and outputs. This can be useful for applications that want to include: + +* Different transaction categories related e.g. to gameplay events; + +* Invoice numbers; + +* Nonces to differentiate payments of the same amount; + +* Other data. + +### General OpReturn structure + +Hex-encoded bytes representing: + + + +### General Syntax Rules: + +The data is composed by the following hex-encoded components: + +1. **OP_RETURN opcode**: `6a`. + +2. Pushdata indicating the size (in bytes) of the protocol identifier. Always 4 (`04` in hex) in the case of the PayButton protocol. + +3. **Protocol identifier**: `50415900` for PayButton (ASCII `PAY` + `0x00`). + +4. **Version**: A byte allowing future updates (currently `00`). + +5. Pushdata indicating the size (in bytes) of data payload identifier. + +6. **Data Payload**: Custom information in UTF-8 format. The maximum size is 213 bytes (UTF-8 encoded) if there is no **payment ID** (nonce). If a **payment ID** is present, the limit is 205 bytes, as the **payment ID** occupies 8 bytes. Can be empty. + +7. Pushdata indicating the size (in bytes) of nonce identifier. + +8. **Nonce**: Eight random bytes to differentiate payments (can be empty). + +If the **data payload** or **nonce** is empty, the pushdata for each will be `00`. + + + +### How to send data using the OP_RETURN opcode in PayButton + +To send data using the OP_RETURN opcode in PayButton, you can use the `op-return` prop. The content of the `op-return` prop will be encoded and will correspond to the **data payload**, mentioned above. Additionally, you may use the **payment ID** as a nonce. To disable sending the **payment ID**, use the `disable-payment-id` prop — PayButton will automatically encode the message according to the rules specified bellow. + + +### PayButton OpReturn encoding examples: + + +#### 1. OpReturn message with 12 bytes of data and no nonce + + + 6a0450415900000c0102030405060708090a0b0c00 + + + +Breaking this down: + + + +- `6a` → OP_RETURN opcode + +- `04` → Pushdata indicating the size of the protocol identifier + +- `50415900` → PayButton identifier (ASCII `PAY` + `0x00`) + +- `00` → Version 0 + +- `0c` → Pushdata indicating the size of data payload identifier + +- `0102030405060708090a0b0c` → Data payload + +- `00` → Pushdata for payment ID (nonce), indicating there will be none + + + +#### 2. OpReturn message with 12 bytes of data and an 8-byte nonce + + 6a0450415900000c0102030405060708090a0b0c080102030405060708 + + + +- `6a` → OP_RETURN opcode + +- `04` → Pushdata indicating the size of the protocol identifier + +- `50415900` → PayButton identifier (ASCII `PAY` + `0x00`) + +- `00` → Version 0 + +- `0c` → Pushdata indicating the size of data payload identifier + +- `0102030405060708090a0b0c` → Data payload + +- `08` → Pushdata indicating that this transaction has an 8-byte payment ID + +- `0102030405060708` → Payment ID + + + +#### 3. OpReturn message with no data but an 8-byte payment ID (nonce) + + 6a04504159000000080102030405060708 + + +- `6a` → OP_RETURN opcode + +- `04` → Pushdata indicating the size of the protocol identifier + +- `50415900` → PayButton identifier (ASCII `PAY` + `0x00`) + +- `00` → Version 0 + +- `00` → No data payload + +- `08` → Pushdata indicating that this transaction has an 8-byte payment ID + +- `0102030405060708` → Payment ID + +#### 4. Transaction with no data and no payment ID + + 6a0450415900000000 + +- `6a` → OP_RETURN opcode + +- `04` → Pushdata indicating the size of the protocol identifier + +- `50415900` → PayButton identifier (ASCII `PAY` + `0x00`) + +- `00` → Version 0 + +- `00` → Pushdata for data payload, indicating there will be none + +- `00` → Pushdata for payment ID, indicating there will be none + + \ No newline at end of file diff --git a/docs/zh-cn/op-return-specs.md b/docs/zh-cn/op-return-specs.md new file mode 100644 index 00000000..8aba50b8 --- /dev/null +++ b/docs/zh-cn/op-return-specs.md @@ -0,0 +1,128 @@ +## OpReturn + +OP_RETURN 是一[script opcode](https://wiki.bitcoinsv.io/index.php/OP_RETURN),允许在交易中添加额外信息,超出标准的输入和输出范围。这对于希望包含以下内容的应用程序来说可能很有用: + +与事件相关的不同交易类型(例如,游戏); + +发票号码; + +用于区分相同金额支付的随机数(Nonce); + +其他数据。 +### 一般 OpReturn 结构 + + <协议标识符的 pushdata><协议标识符><版本><数据负载的 pushdata><数据负载><随机数的 pushdata><随机数> + +### 通用语法规则: + +数据由以下十六进制编码的组件组成: + + +1. **OP_RETURN opcode**: `6a`. + +2.Pushdata 指示协议标识符的大小(以字节为单位)。在 PayButton 协议的情况下,始终为 4(十六进制为 `04`)。 + +3. **协议标识符**: `50415900` 对于 PayButton (ASCII `PAY` + `0x00`). + +4. **版本**: 一个字节,允许未来更新(当前为 `00`)。 + +5. Pushdata 指示数据有效负载标识符的大小(以字节为单位)。 + +6. **数据有效负载**: 自定义信息采用 UTF-8 编码格式。若无 payment ID(nonce),最大大小为 213 字节(UTF-8 编码)。若包含 payment ID,则限制为 205 字节,因为 payment ID 占用 8 字节。(可为空)。 + +7. Pushdata 指示 nonce 标识符的大小(以字节为单位)。 + +8. **随机数**: 八个随机字节用于区分支付(可以为空)。 + +如果 **数据有效负载** 或 **随机数** 为空,则每个对应的 pushdata 将为 `00`。 + + +### 如何在 PayButton 中使用 OP_RETURN 操作码发送数据 + +要在 PayButton 中使用 OP_RETURN 操作码发送数据,您可以使用 `op-return` 属性。op-return 属性的内容将被编码,并对应于上述提到的 **数据有效负载**。 此外,您可以将 **支付 ID** 用作随机数(nonce)。要禁用发送 **支付 ID**,请使用 `disable-payment-id` 属性 — PayButton 将根据下面指定的规则自动编码消息。 + + +### PayButton OP_RETURN 编码示例: + +#### 1. 没有随机数且数据为 12 字节的 OP_RETURN 消息: + + + 6a0450415900000c0102030405060708090a0b0c00 + + +- `6a` → OP_RETURN opcode + +- `04` → Pushdata 指示协议标识符的大小 + +- `50415900` → 协议标识符 (ASCII `PAY` + `0x00`) + +- `00` → 版本 0 + +- `0c` → Pushdata 指示数据有效负载标识符的大小 + +- `0102030405060708090a0b0c` → 数据有效负载 + +- `00` → **支付 ID**(随机数)的 Pushdata,表示将没有随机数 + + + +#### 2. 具有 12 字节数据和 8 字节随机数(nonce)的 OP_RETURN 消息 + + 6a0450415900000c0102030405060708090a0b0c080102030405060708 + + + +- `6a` → OP_RETURN opcode + +- `04` → Pushdata 指示协议标识符的大小 + +- `50415900` → 协议标识符 (ASCII `PAY` + `0x00`) + +- `00` → 版本 0 + +- `0c` → Pushdata 指示数据有效负载标识符的大小 + +- `0102030405060708090a0b0c` → 数据有效负载 + +- `08` → Pushdata 指示此交易具有 8 字节的 payment ID + +- `0102030405060708` → 支付 ID + + + +#### 3. 没有数据但有 8 字节支付 ID(随机数)的 OP_RETURN 消息 + + 6a04504159000000080102030405060708 + + +- `6a` → OP_RETURN opcode + +- `04` → Pushdata 指示协议标识符的大小 + +- `50415900` → 协议标识符 (ASCII `PAY` + `0x00`) + +- `00` → 版本 0 + +- `00` → 没有数据有效负载 + +- `08` → Pushdata 指示此交易具有 8 字节的 payment ID。 + +- `0102030405060708` → 支付 ID + +#### 4. 没有数据和没有支付 ID 的交易 + + 6a0450415900000000 + +- `6a` → OP_RETURN opcode + +- `04` → Pushdata 指示协议标识符的大小 + +- `50415900` → 协议标识符 (ASCII `PAY` + `0x00`) + +- `00` → 版本 0 + +- `00` → Pushdata for data payload, indicating there will be none + +- `00` → 支付 ID 的 Pushdata,表示将没有支付 ID + + diff --git a/docs/zh-tw/op-return-specs.md b/docs/zh-tw/op-return-specs.md new file mode 100644 index 00000000..e69de29b