diff --git a/docs/README.md b/docs/README.md index 549146e4..3409fe5f 100644 --- a/docs/README.md +++ b/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: + + + +### 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. diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 07fede99..ffb60490 100644 --- a/docs/_sidebar.md +++ b/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) \ No newline at end of file diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md index da62938a..42e77e1e 100644 --- a/docs/zh-cn/README.md +++ b/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 结构 + + <协议标识符的 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的开发。 diff --git a/docs/zh-cn/_sidebar.md b/docs/zh-cn/_sidebar.md index 457f7ff5..cee79266 100644 --- a/docs/zh-cn/_sidebar.md +++ b/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=捐助) \ No newline at end of file diff --git a/docs/zh-tw/README.md b/docs/zh-tw/README.md index c45348e8..34a2be1d 100644 --- a/docs/zh-tw/README.md +++ b/docs/zh-tw/README.md @@ -1039,6 +1039,134 @@ docker-compose up +## 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 指示隨機數標識符的大小(以位元組為單位)。 + +8. **隨機數**: 八個隨機位元組,用於區分支付(可以為空)。 + +如果 **數據有效載荷** 或 **隨機數** 為空,則每個的 Pushdata 為 00 + + + +### 如何使用 OP_RETURN opcode 在 PayButton 中發送數據 + +要在 PayButton 中使用 OP_RETURN opcode 發送數據,您可以使用 op-return 屬性。 op-return 屬性的內容將被編碼,並將對應於上述提到的 **數據有效載荷**。 此外,您可以使用 payment ID 作為隨機數。 要禁用發送 payment ID,請使用 disable-payment-id 屬性—PayButton 將根據下面指定的規則自動編碼消息。 + + +### PayButton OpReturn 編碼範例: + + +#### 1. 帶有 12 位元組數據且無隨機數的 OpReturn 消息 + + + 6a0450415900000c0102030405060708090a0b0c00 + + +- `6a` → OP_RETURN opcode + +- `04` → Pushdata 指示協議標識符的大小 + +- `50415900` → PayButton 標識符 (ASCII `PAY` + `0x00`) + +- `00` → 版本 0 + +- `0c` → Pushdata 指示數據有效載荷標識符的大小 + +- `0102030405060708090a0b0c` → 數據有效載荷 + +- `00` → 支付 ID(隨機數)的 Pushdata,指示將不會有隨機數 + + + +#### 2. OpReturn message with 12 bytes of data and an 8-byte nonce + + 6a0450415900000c0102030405060708090a0b0c080102030405060708 + + + +- `6a` → OP_RETURN opcode + +- `04` → Pushdata 指示協議標識符的大小 + +- `50415900` → PayButton 標識符 (ASCII `PAY` + `0x00`) + +- `00` → 版本 0 + +- `0c` → Pushdata 指示數據有效載荷標識符的大小 + +- `0102030405060708090a0b0c` → 數據有效載荷 + +- `08` → Pushdata 指示此交易具有 8 位元組的 payment ID + +- `0102030405060708` → 付款ID + + +#### 3. OpReturn message with no data but an 8-byte payment ID (nonce) + + 6a04504159000000080102030405060708 + + +- `6a` → OP_RETURN opcode + +- `04` → Pushdata 指示協議標識符的大小 + +- `50415900` → PayButton 標識符 (ASCII `PAY` + `0x00`) + +- `00` → 版本 0 + +- `00` → 無數據有效載荷 + +- `08` → Pushdata 指示此交易具有 8 位元組的 payment ID + +- `0102030405060708` → 付款ID + +#### 4. Transaction with no data and no payment ID + + 6a0450415900000000 + +- `6a` → OP_RETURN opcode + +- `04` → Pushdata 指示協議標識符的大小 + +- `50415900` → PayButton 標識符 (ASCII `PAY` + `0x00`) + +- `00` → 版本 0 + +- `00` → 無數據有效載荷 + +- `00` → 支付 ID(隨機數)的 Pushdata,指示將不會有隨機數 + + ## 捐款 > 所有收到的PayButton捐款都直接用於資助PayButton的開發。 diff --git a/docs/zh-tw/_sidebar.md b/docs/zh-tw/_sidebar.md index b70ec635..a0e62748 100644 --- a/docs/zh-tw/_sidebar.md +++ b/docs/zh-tw/_sidebar.md @@ -34,4 +34,5 @@ - [設置開發環境](/zh-tw/?id=設置開發環境) - [用 Storybook 測試 UI 組件](/zh-tw/?id=用-Storybook-測試-UI-組件) - [啟動文檔網站](/zh-tw/?id=啟動文檔網站) + - [OpReturn](/zh-tw/?id=OpReturn) - [捐款](/zh-tw/?id=捐款) \ No newline at end of file