docs: opReturn feature

docs/README.md

@@ -1044,6 +1044,144 @@ docker-compose up
 2. Site will be avaiable on `localhost:3001`
 3. You can update the documentation by modifying the file `docs/README.md`
 
+## 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:
+
+    <OP_RETURN opcode><pushdata for protocol identifier><protocol identifier><version><pushdata for data payload><data payload><pushdata for nonce><nonce>
+
+### 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
+
+
+
 ## Donate
 
 > All PayButton donations received are used to directly fund PayButton development.

docs/_sidebar.md

@@ -35,4 +35,5 @@
     - [Setup Development](/?id=setup-development-environment)
     - [Starting Storybook](/?id=test-ui-components-with-storybook)
     - [Documentation Website](/?id=starting-documentation-website)
+    - [OpReturn](/?id=OpReturn)
   - [Donate](/?id=donate)

docs/zh-cn/README.md

@@ -1038,6 +1038,135 @@ docker-compose up
 2. 网站将在 localhost:3001 上可用。
 3. 你可以通过修改文件 docs/README.md 来更新文档
 
+## OpReturn
+
+OP_RETURN 是一[script opcode](https://wiki.bitcoinsv.io/index.php/OP_RETURN)，允许在交易中添加额外信息，超出标准的输入和输出范围。这对于希望包含以下内容的应用程序来说可能很有用：
+
+与事件相关的不同交易类型（例如，游戏）；
+
+发票号码；
+
+用于区分相同金额支付的随机数（Nonce）；
+
+其他数据。
+### 一般 OpReturn 结构
+
+    <OP_RETURN 操作码><协议标识符的 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
+
+
+
 ## 捐助
 
 > 所有收到的PayButton捐助都直接用於资助PayButton的开发。

docs/zh-cn/_sidebar.md

@@ -34,4 +34,5 @@
     - [设置开发环境](/zh-cn/?id=设置开发环境)
     - [用 Storybook 测试 UI 组件](/zh-cn/?id=用-storybook-测试-ui-组件)
     - [启动文档网站](/zh-cn/?id=启动文档网站)
+    - [OpReturn](/zh-cn/?id=OpReturn)
   - [捐助](/zh-cn/?id=捐助)