@ocap/client 1.25.4 → 1.25.5

package/docs/api-reference.zh-TW.md

@@ -0,0 +1,23 @@
+# API 參考
+
+歡迎來到 OCAP Client API 參考。本節提供所有可用類別、方法和資料類型的全面且可搜尋的參考。無論您是在尋找 GraphQL 方法的細節、交易輔助工具的參數，還是回應物件的結構，您都可以在這裡找到所需的詳細資訊。
+
+探索以下部分，深入了解客戶端的功能：
+
+<x-cards data-columns="2">
+  <x-card data-title="輔助方法" data-icon="lucide:function-square" data-href="/api-reference/client-methods">
+    核心客戶端輔助方法的詳細文件，例如 `getType`、`decodeTx` 和 `fromUnitToToken`。
+  </x-card>
+  <x-card data-title="查詢與變更方法" data-icon="lucide:database-zap" data-href="/api-reference/query-mutation-methods">
+    所有可用的 GraphQL 查詢和變更方法的完整列表，用於讀取和寫入鏈上資料。
+  </x-card>
+  <x-card data-title="高階 API" data-icon="lucide:zap" data-href="/api-reference/transaction-helpers">
+    高階函數的參考，可簡化如轉移代幣和管理資產等常見工作流程。
+  </x-card>
+  <x-card data-title="低階 API" data-icon="lucide:cpu" data-href="/api-reference/low-level-api">
+    學習如何手動建構、簽署和發送交易，以完全控制交易的生命週期。
+  </x-card>
+  <x-card data-title="資料類型" data-icon="lucide:box" data-href="/api-reference/data-types">
+    定義整個客戶端 API 中使用的所有自訂資料結構、輸入參數和回應物件。
+  </x-card>
+</x-cards>

package/docs/api-reference.zh.md

@@ -1,21 +1,21 @@
 # API 参考
 
-欢迎使用 OCAP 客户端 API 参考。本节为所有可用的类、方法和数据类型提供了全面且可搜索的参考文档。无论您是在寻找 GraphQL 方法的具体细节、交易辅助工具的参数，还是响应对象的结构，都可以在这里找到所需的详细信息。
+欢迎来到 OCAP Client API 参考。本节为所有可用的类、方法和数据类型提供了全面且可搜索的参考。无论您是想了解 GraphQL 方法的细节、交易辅助工具的参数，还是响应对象的结构，都可以在这里找到所需的详细信息。
 
-浏览以下部分，深入了解客户端的功能：
+探索以下部分，深入了解客户端的功能：
 
 <x-cards data-columns="2">
   <x-card data-title="辅助方法" data-icon="lucide:function-square" data-href="/api-reference/client-methods">
-    核心客户端辅助方法的详细文档，例如 `getType`、`decodeTx` 和 `fromUnitToToken`。
+    核心客户端辅助方法（如 `getType`、`decodeTx` 和 `fromUnitToToken`）的详细文档。
   </x-card>
   <x-card data-title="查询与变更方法" data-icon="lucide:database-zap" data-href="/api-reference/query-mutation-methods">
-    所有可用的 GraphQL 查询和变更方法的完整列表，用于在链上进行读写操作。
+    所有可用的 GraphQL 查询和变更方法的完整列表，用于读取和写入链上数据。
   </x-card>
   <x-card data-title="高阶 API" data-icon="lucide:zap" data-href="/api-reference/transaction-helpers">
-    用于简化常见工作流（如转移通证和管理资产）的高阶函数参考。
+    用于简化代币转账和资产管理等常见工作流程的高阶函数参考。
   </x-card>
   <x-card data-title="低阶 API" data-icon="lucide:cpu" data-href="/api-reference/low-level-api">
-    了解如何手动构建、签名和发送交易，以完全控制交易生命周期。
+    了解如何手动构建、签署和发送交易，以完全控制交易生命周期。
   </x-card>
   <x-card data-title="数据类型" data-icon="lucide:box" data-href="/api-reference/data-types">
     定义了整个客户端 API 中使用的所有自定义数据结构、输入参数和响应对象。

package/docs/core-concepts-client-architecture.ja.md

@@ -0,0 +1,102 @@
+# クライアントアーキテクチャ
+
+OCAP クライアントは、さまざまな JavaScript 環境や特定のユースケースに対応できるよう、モジュラーアーキテクチャで設計されています。画一的なライブラリではなく、Node.js バックエンドやバンドルサイズが重視されるウェブアプリケーションなど、特定のコンテキストに最適化された複数のクライアント実装を提供します。このアプローチにより、ニーズに最も効率的なクライアントを選択でき、必要に応じてパフォーマンスの向上とフットプリントの削減が実現します。
+
+すべてのクライアントのバリエーションは、共通の基盤である `GraphQLClientBase` 上に構築されており、ブロックチェーンの GraphQL API と対話するためのコア機能を提供します。
+
+### 継承図
+
+次の図は、さまざまなクライアント実装間の関係を示しています。
+
+```d2
+direction: down
+
+GraphQLClientBase: {
+  label: "GraphQLClientBase\n(コア機能)"
+  shape: rectangle
+}
+
+GraphQLClient: {
+  label: "GraphQLClient\n(フルクライアント + ヘルパー)"
+  shape: rectangle
+}
+
+GraphqlClientLite: {
+  label: "GraphqlClientLite\n(ブラウザ向けに最適化)"
+  shape: rectangle
+}
+
+NativeGraphqlClient: {
+  label: "NativeGraphqlClient\n(Node.js向けに最適化)"
+  shape: rectangle
+}
+
+GraphQLClientBase -> GraphQLClient: "Extends"
+GraphQLClientBase -> GraphqlClientLite: "Extends"
+GraphQLClient -> NativeGraphqlClient: "Extends"
+```
+
+## クライアント実装
+
+ここでは、利用可能な各クライアントと、その想定されるユースケースについて説明します。
+
+### `GraphQLClientBase` (コア)
+
+これは、他のすべてのクライアントが拡張する、基盤となる軽量なクライアントです。ブロックチェーンと通信するための基本的な機能を提供します。
+
+- GraphQL のクエリとミューテーションの送信。
+- リアルタイムのイベントサブスクリプションのための WebSocket 接続の確立。
+- スポンサー付きトランザクションのためのガス支払いヘッダーの処理。
+- 環境に依存しませんが、サブスクリプションを使用する場合は、WebSocket と EventEmitter に互換性のある実装を提供する必要があります。
+
+このクライアントは、基本的な読み取り専用機能のみが必要で、依存関係を最小限に抑えたい場合に最適です。
+
+### `GraphQLClient` (フルクライアント)
+
+これは標準的な汎用クライアントであり、最も頻繁に使用されるものです。`GraphQLClientBase` を拡張し、一般的なオンチェーン操作を簡素化する豊富な高レベルヘルパーメソッド群を追加します。これらのヘルパーは、アセットの作成、トークンの転送、ステークの管理などのタスクをカバーし、生の GraphQL ミューテーションの複雑さを抽象化します。
+
+デフォルトでは、インスタンス化の際にコンテキストを自動的に初期化するため、すぐに使用できます。
+
+### `NativeGraphqlClient` (Node.js向け)
+
+このクライアントは Node.js ランタイムに特化して最適化されています。フル機能の `GraphQLClient` を拡張し、イベント処理に Node.js のネイティブ `events` モジュールを使用するように設定します。これにより、サーバー上で実行されるあらゆるバックエンドアプリケーション、コマンドラインツール、またはスクリプトにとって、最もパフォーマンスが高く信頼性の高い選択肢となります。
+
+### `GraphqlClientLite` (ブラウザ向け)
+
+フロントエンドのウェブアプリケーション向けに設計された `GraphqlClientLite` は `GraphQLClientBase` を拡張し、バンドルサイズが最小になるように最適化されています。Node.js 固有の依存関係を `wolfy87-eventemitter` のようなブラウザ互換の代替ライブラリに置き換えています。パフォーマンスと読み込み時間が重要なウェブアプリケーションを構築している場合、このクライアントは、フル機能のヘルパーメソッド群による余分な負荷なしで、OCAP のコア機能を提供します。
+
+## どのクライアントを使用すべきか？
+
+どのクライアントを選択すればよいか判断しやすいように、各シナリオで推奨されるクライアントの概要を以下に示します。
+
+| 環境 | ユースケース | 推奨クライアント | インポートパス |
+| :---------- | :------------------------------------------- | :----------------------- | :---------------------- |
+| Node.js | バックエンドサービス、スクリプト、CLI ツール | `NativeGraphqlClient` | `@ocap/client/node` |
+| ブラウザ | 一般的なウェブアプリケーション (例: React, Vue) | `GraphQLClient` | `@ocap/client` |
+| ブラウザ | バンドルサイズが重視されるアプリケーション | `GraphqlClientLite` | `@ocap/client/lite` |
+| すべて | 読み取り専用、最小限の機能が必要 | `GraphQLClientBase` | `@ocap/client/base` |
+
+### インポート例
+
+以下に、コード内で各クライアントをインポートする方法を示します。
+
+```javascript Node.js クライアント icon=logos:nodejs-icon
+const NativeGraphqlClient = require('@ocap/client/node');
+const client = new NativeGraphqlClient('https://beta.abtnetwork.io/api');
+```
+
+```javascript フルブラウザクライアント icon=logos:javascript
+const GraphQLClient = require('@ocap/client');
+const client = new GraphQLClient('https://beta.abtnetwork.io/api');
+```
+
+```javascript Lite ブラウザクライアント icon=logos:javascript
+const GraphqlClientLite = require('@ocap/client/lite');
+const client = new GraphqlClientLite('https://beta.abtnetwork.io/api');
+```
+
+## まとめ
+
+さまざまなクライアント実装を理解することで、アプリケーションの環境と要件に最も適した、情報に基づいた選択ができます。適切なクライアントを選択することで、パフォーマンス、バンドルサイズ、使いやすさを最適化できます。
+
+これでクライアントアーキテクチャを理解できたので、次はトランザクションがどのように構築され、処理されるかをさらに深く掘り下げてみましょう。[トランザクションライフサイクル](./core-concepts-transaction-lifecycle.md) ガイドで詳しく学んでください。

package/docs/core-concepts-client-architecture.zh-TW.md

@@ -0,0 +1,102 @@
+# 客戶端架構
+
+OCAP 客戶端採用模組化架構設計，以滿足不同的 JavaScript 環境和特定使用情境。它並非提供一個一體適用的函式庫，而是提供多種客戶端實作，每種實作都針對特定情境進行了優化，例如 Node.js 後端或對程式碼包大小敏感的 Web 應用程式。這種方法讓您可以根據需求選擇最高效的客戶端，從而在必要時確保更佳的效能和更小的體積。
+
+所有客戶端變體都建立在一個共同的基礎 `GraphQLClientBase` 之上，它提供了與區塊鏈的 GraphQL API 互動的核心功能。
+
+### 繼承關係圖
+
+下圖說明了不同客戶端實作之間的關係：
+
+```d2
+direction: down
+
+GraphQLClientBase: {
+  label: "GraphQLClientBase\n(核心功能)"
+  shape: rectangle
+}
+
+GraphQLClient: {
+  label: "GraphQLClient\n(完整客戶端 + 輔助工具)"
+  shape: rectangle
+}
+
+GraphqlClientLite: {
+  label: "GraphqlClientLite\n(瀏覽器優化)"
+  shape: rectangle
+}
+
+NativeGraphqlClient: {
+  label: "NativeGraphqlClient\n(Node.js 優化)"
+  shape: rectangle
+}
+
+GraphQLClientBase -> GraphQLClient: "擴展"
+GraphQLClientBase -> GraphqlClientLite: "擴展"
+GraphQLClient -> NativeGraphqlClient: "擴展"
+```
+
+## 客戶端實作
+
+以下是每種可用客戶端及其預期使用情境的詳細說明。
+
+### `GraphQLClientBase` (核心)
+
+這是所有其他客戶端擴展的基礎、輕量級客戶端。它提供了與區塊鏈通訊的基本功能：
+
+- 發送 GraphQL 查詢和變更。
+- 建立 WebSocket 連線以進行即時事件訂閱。
+- 處理贊助交易的 gas 支付標頭。
+- 它與環境無關，但如果您使用訂閱功能，則需要為 WebSocket 和 EventEmitter 提供相容的實作。
+
+如果您只需要基本的唯讀功能並希望最小化依賴性，這個客戶端是理想的選擇。
+
+### `GraphQLClient` (完整客戶端)
+
+這是標準的、通用的客戶端，也是您最可能經常使用的客戶端。它擴展了 `GraphQLClientBase`，並增加了一套豐富的高階輔助方法，以簡化常見的鏈上操作。這些輔助工具涵蓋了創建資產、轉移代幣和管理質押等任務，將原始 GraphQL 變更的複雜性抽象化。
+
+預設情況下，它在實例化時也會自動初始化其上下文，使其可以立即使用。
+
+### `NativeGraphqlClient` (適用於 Node.js)
+
+這個客戶端專為 Node.js 執行環境進行了優化。它擴展了完整的 `GraphQLClient`，並將其配置為使用 Node.js 的原生 `events` 模組進行事件處理。這使其成為任何後端應用程式、命令列工具或在伺服器上執行的腳本中最具效能和最可靠的選擇。
+
+### `GraphqlClientLite` (適用於瀏覽器)
+
+`GraphqlClientLite` 專為前端 Web 應用程式設計，擴展了 `GraphQLClientBase`，並針對最小化程式碼包大小進行了優化。它將 Node.js 特有的依賴性換成了與瀏覽器相容的替代品，例如 `wolfy87-eventemitter`。如果您正在建構一個對效能和載入時間至關重要的 Web 應用程式，這個客戶端提供了 OCAP 的核心功能，而沒有完整輔助方法套件的額外負擔。
+
+## 我應該使用哪個客戶端？
+
+為了幫助您決定，以下是針對每種情境推薦的客戶端摘要：
+
+| 環境 | 使用情境 | 推薦的客戶端 | 導入路徑 |
+| :---------- | :------------------------------------------- | :----------------------- | :---------------------- |
+| Node.js | 後端服務、腳本、CLI 工具 | `NativeGraphqlClient` | `@ocap/client/node` |
+| 瀏覽器 | 一般 Web 應用程式（例如 React、Vue） | `GraphQLClient` | `@ocap/client` |
+| 瀏覽器 | 對程式碼包大小敏感的應用程式 | `GraphqlClientLite` | `@ocap/client/lite` |
+| 任何環境 | 唯讀，需要最少功能 | `GraphQLClientBase` | `@ocap/client/base` |
+
+### 導入範例
+
+以下是在您的程式碼中導入每個客戶端的方式：
+
+```javascript Node.js Client icon=logos:nodejs-icon
+const NativeGraphqlClient = require('@ocap/client/node');
+const client = new NativeGraphqlClient('https://beta.abtnetwork.io/api');
+```
+
+```javascript Full Browser Client icon=logos:javascript
+const GraphQLClient = require('@ocap/client');
+const client = new GraphQLClient('https://beta.abtnetwork.io/api');
+```
+
+```javascript Lite Browser Client icon=logos:javascript
+const GraphqlClientLite = require('@ocap/client/lite');
+const client = new GraphqlClientLite('https://beta.abtnetwork.io/api');
+```
+
+## 總結
+
+了解不同的客戶端實作可以讓您做出最適合您應用程式環境和需求的明智選擇。透過選擇適當的客戶端，您可以優化效能、程式碼包大小和易用性。
+
+現在您已經了解了客戶端架構，可以更深入地了解交易是如何建構和處理的。在 [交易生命週期](./core-concepts-transaction-lifecycle.md) 指南中了解更多資訊。

package/docs/core-concepts-client-architecture.zh.md

@@ -1,12 +1,12 @@
 # 客户端架构
 
-OCAP Client 采用模块化架构设计，以适应不同的 JavaScript 环境和特定用例。它并非一个万能的库，而是提供了多种客户端实现，每种实现都针对特定上下文进行了优化，例如 Node.js 后端或对包大小敏感的 Web 应用程序。这种方法使您可以根据需要选择最高效的客户端，从而在必要时确保更好的性能和更小的体积。
+OCAP 客户端采用模块化架构设计，以适应不同的 JavaScript 环境和特定用例。它不提供一个通用的库，而是提供了多个客户端实现，每个实现都针对特定上下文进行了优化，例如 Node.js 后端或对包大小敏感的 Web 应用。这种方法允许您根据需要选择最高效的客户端，从而在必要时确保更好的性能和更小的体积。
 
-所有客户端变体都构建在一个共同的基础 `GraphQLClientBase` 之上，它提供了与区块链的 GraphQL API 交互的核心功能。
+所有客户端变体都构建在一个通用的基础 `GraphQLClientBase` 之上，该基础提供了与区块链的 GraphQL API 交互的核心功能。
 
 ### 继承关系图
 
-下图说明了不同客户端实现之间的关系：
+下图展示了不同客户端实现之间的关系：
 
 ```d2
 direction: down
@@ -46,57 +46,57 @@ GraphQLClient -> NativeGraphqlClient: "扩展"
 
 - 发送 GraphQL 查询和变更。
 - 建立 WebSocket 连接以进行实时事件订阅。
-- 处理赞助交易的 Gas 支付头。
-- 它与环境无关，但如果您使用订阅，则需要为 WebSocket 和 EventEmitter 提供兼容的实现。
+- 处理赞助交易的 gas 支付头。
+- 它是环境无关的，但如果您使用订阅功能，则需要为 WebSocket 和 EventEmitter 提供兼容的实现。
 
 如果您只需要基本的只读功能并希望最小化依赖项，那么这个客户端是理想的选择。
 
 ### `GraphQLClient` (完整客户端)
 
-这是标准的通用客户端，也是您可能最常使用的客户端。它扩展了 `GraphQLClientBase`，并添加了一套丰富的高级辅助方法，以简化常见的链上操作。这些辅助方法涵盖了创建资产、转移通证和管理质押等任务，抽象了原始 GraphQL 变更的复杂性。
+这是标准的通用客户端，也是您最可能经常使用的客户端。它扩展了 `GraphQLClientBase` 并添加了一套丰富的高级辅助方法，以简化常见的链上操作。这些辅助方法涵盖了创建资产、转移通证和管理质押等任务，抽象了原始 GraphQL 变更的复杂性。
 
 默认情况下，它在实例化时也会自动初始化其上下文，使其可以立即使用。
 
-### `NativeGraphqlClient` (用于 Node.js)
+### `NativeGraphqlClient` (适用于 Node.js)
 
-该客户端专门为 Node.js 运行时进行了优化。它扩展了完整的 `GraphQLClient`，并将其配置为使用 Node.js 的原生 `events` 模块进行事件处理。这使其成为任何在服务器上运行的后端应用程序、命令行工具或脚本的性能最高、最可靠的选择。
+该客户端专门为 Node.js 运行时进行了优化。它扩展了完整的 `GraphQLClient`，并将其配置为使用 Node.js 的原生 `events` 模块进行事件处理。这使其成为任何后端应用、命令行工具或在服务器上运行的脚本的最高性能和最可靠的选择。
 
-### `GraphqlClientLite` (用于浏览器)
+### `GraphqlClientLite` (适用于浏览器)
 
-`GraphqlClientLite` 专为前端 Web 应用程序设计，它扩展了 `GraphQLClientBase`，并针对最小化包大小进行了优化。它将 Node.js 特定的依赖项替换为浏览器兼容的替代品，例如 `wolfy87-eventemitter`。如果您正在构建一个对性能和加载时间至关重要的 Web 应用程序，该客户端可以在不增加完整辅助方法套件额外负担的情况下提供核心的 OCAP 功能。
+专为前端 Web 应用设计的 `GraphqlClientLite` 扩展了 `GraphQLClientBase`，并针对最小化包大小进行了优化。它将 Node.js 特定的依赖项替换为浏览器兼容的替代方案，如 `wolfy87-eventemitter`。如果您正在构建一个对性能和加载时间至关重要的 Web 应用，此客户端可在不增加完整辅助方法套件额外负担的情况下，提供 OCAP 的核心功能。
 
 ## 我应该使用哪个客户端？
 
 为了帮助您决定，以下是针对每种场景推荐的客户端摘要：
 
-| 环境 | 使用场景 | 推荐客户端 | 导入路径 |
+| 环境 | 用例 | 推荐客户端 | 导入路径 |
 | :---------- | :------------------------------------------- | :----------------------- | :---------------------- |
-| Node.js     | 后端服务、脚本、CLI 工具 | `NativeGraphqlClient`    | `@ocap/client/node`     |
-| 浏览器 | 通用 Web 应用程序（例如 React、Vue） | `GraphQLClient`          | `@ocap/client`          |
-| 浏览器 | 对包大小敏感的应用程序 | `GraphqlClientLite`      | `@ocap/client/lite`     |
-| 任何 | 只读，需要最少的功能 | `GraphQLClientBase`      | `@ocap/client/base`     |
+| Node.js | 后端服务、脚本、CLI 工具 | `NativeGraphqlClient` | `@ocap/client/node` |
+| 浏览器 | 通用 Web 应用（例如 React、Vue） | `GraphQLClient` | `@ocap/client` |
+| 浏览器 | 对包大小敏感的应用 | `GraphqlClientLite` | `@ocap/client/lite` |
+| 任何 | 只读，需要最少的功能 | `GraphQLClientBase` | `@ocap/client/base` |
 
 ### 导入示例
 
-以下是在代码中导入每个客户端的方法：
+以下是在代码中导入每个客户端的方式：
 
-```javascript Node.js Client icon=logos:nodejs-icon
+```javascript Node.js 客户端 icon=logos:nodejs-icon
 const NativeGraphqlClient = require('@ocap/client/node');
 const client = new NativeGraphqlClient('https://beta.abtnetwork.io/api');
 ```
 
-```javascript Full Browser Client icon=logos:javascript
+```javascript 完整浏览器客户端 icon=logos:javascript
 const GraphQLClient = require('@ocap/client');
 const client = new GraphQLClient('https://beta.abtnetwork.io/api');
 ```
 
-```javascript Lite Browser Client icon=logos:javascript
+```javascript 轻量浏览器客户端 icon=logos:javascript
 const GraphqlClientLite = require('@ocap/client/lite');
 const client = new GraphqlClientLite('https://beta.abtnetwork.io/api');
 ```
 
 ## 总结
 
-了解不同的客户端实现可以让您根据应用程序的环境和需求做出明智的选择。通过选择合适的客户端，您可以优化性能、包大小和易用性。
+了解不同的客户端实现可以让您做出最适合您应用环境和需求的明智选择。通过选择合适的客户端，您可以优化性能、包大小和易用性。
 
-既然您已经了解了客户端架构，您可以更深入地研究交易是如何构建和处理的。在 [交易生命周期](./core-concepts-transaction-lifecycle.md) 指南中了解更多信息。
+现在您已经了解了客户端架构，可以更深入地研究交易是如何构建和处理的。请在[交易生命周期](./core-concepts-transaction-lifecycle.md)指南中了解更多信息。

package/docs/core-concepts-event-subscriptions.ja.md

@@ -0,0 +1,123 @@
+# イベントサブスクリプション
+
+OCAP Clientは、アプリケーションがオンチェーンのアクティビティをリアルタイムでリッスンできる、強力なイベントサブスクリプションシステムを提供します。この機能はWebSocket上に構築されており、ブロックチェーンノードへの永続的な接続を提供することで、更新をチェックするための継続的なポーリングを不要にします。
+
+特定のイベントトピックをサブスクライブすることで、新しいトランザクションの作成、アセットの転送、トークンの交換など、幅広いオンチェーンイベントの即時通知を受け取ることができます。これは、ブロックチェーンの状態変化にリアルタイムで反応する、レスポンシブでインタラクティブなアプリケーションを構築するために不可欠です。これらのイベントが何によってトリガーされるかをより深く理解するには、[トランザクションライフサイクル](./core-concepts-transaction-lifecycle.md)を参照することをお勧めします。
+
+## 仕組み
+
+内部的には、イベントを初めてサブスクライブすると、OCAP Clientはブロックチェーンノードの指定されたエンドポイントへのWebSocket接続を自動的に確立します。この接続は維持され、イベントが発生するとすぐにノードがクライアントに直接イベントデータをプッシュできるようになります。
+
+クライアントがWebSocket接続のライフサイクルを管理します。初期接続の処理、接続をアクティブに保つためのハートビートメッセージの送信、接続が切断された場合の再接続試行などを行います。これにより、最小限の設定で安定した信頼性の高いイベントストリームが保証されます。
+
+## イベントのサブスクライブ
+
+イベントのリッスンを開始するには、`subscribe`メソッドを使用します。イベントを識別する文字列であるイベントトピックと、そのイベントが受信されるたびに実行されるコールバック関数を提供します。
+
+```javascript OCAP Client icon=logos:javascript
+const client = new GraphQLClient('https://beta.abtnetwork.io/api/v2/gql');
+
+const handleNewTransaction = (eventData) => {
+  console.log('A new transaction was created on-chain:', eventData);
+};
+
+// 'tx.create'トピックをサブスクライブする
+client.subscribe('tx.create', handleNewTransaction);
+```
+
+### メソッドシグネチャ
+
+**`subscribe(topic, callback)`**
+
+<x-field-group>
+  <x-field data-name="topic" data-type="string" data-required="true" data-desc="サブスクライブするイベントトピックの名前。例：'tx.create'。"></x-field>
+  <x-field data-name="callback" data-type="Function" data-required="true" data-desc="イベントが受信されたときに実行される関数。イベントデータは最初の引数として渡されます。"></x-field>
+</x-field-group>
+
+### 一般的なイベントトピック
+
+イベントトピックは通常、`tx.<transaction_type>`のパターンに従います。以下に一般的な例をいくつか示します：
+
+| Topic | Description |
+|---|---|
+| `tx.create` | 新しいトランザクションが正常に処理され、ブロックに追加されたときに発行されます。 |
+| `tx.transfer_v2` | `transferV2`トランザクションが発生したときに特に発行されます。 |
+| `tx.exchange_v2` | `exchangeV2`（アトミックスワップ）トランザクションが完了したときに発行されます。 |
+| `tx.create_asset` | 新しいアセット（NFT）が作成されたときに発行されます。 |
+
+## イベントのサブスクライブ解除
+
+サブスクリプションが不要になった場合は、クリーンアップすることをお勧めします。特に、コンポーネントがマウントおよびアンマウントされるシングルページアプリケーションでは重要です。これにより、メモリリークや不要な処理を防ぐことができます。サブスクリプションは`unsubscribe`メソッドを使用して削除できます。
+
+```javascript OCAP Client icon=logos:javascript
+// 特定のリスナーを削除するには、同じコールバック関数の参照を渡します
+client.unsubscribe('tx.create', handleNewTransaction);
+
+// 特定のトピックのすべてのリスナーを削除するには
+client.unsubscribe('tx.create');
+```
+
+### メソッドシグネチャ
+
+**`unsubscribe(topic, [callback])`**
+
+<x-field-group>
+  <x-field data-name="topic" data-type="string" data-required="true" data-desc="サブスクライブを解除するイベントトピックの名前。"></x-field>
+  <x-field data-name="callback" data-type="Function" data-required="false" data-desc="任意。削除する特定のコールバック関数。省略した場合、指定されたトピックのすべてのリスナーが削除されます。"></x-field>
+</x-field-group>
+
+## 完全な例
+
+以下は、イベントのサブスクライブ、トリガー、そしてサブスクライブ解除をデモンストレーションする完全な例です。
+
+```javascript Event Subscription Lifecycle icon=logos:javascript
+import GraphQLClient from '@ocap/client';
+import { fromRandom } from '@ocap/wallet';
+
+const main = async () => {
+  const client = new GraphQLClient('https://beta.abtnetwork.io/api/v2/gql');
+  const events = { txCreate: 0, txTransfer: 0 };
+
+  // 1. イベントをサブスクライブ
+  client.subscribe('tx.create', () => (events.txCreate += 1));
+  client.subscribe('tx.transfer_v2', () => (events.txTransfer += 1));
+
+  console.log('Subscribed to tx.create and tx.transfer_v2 events...');
+
+  // 短時間待機するためのヘルパー
+  const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+  await sleep(100); // サブスクリプションが登録されるまで少し待つ
+
+  // 2. イベントをトリガーするアクションを実行
+  // 注：これには資金のあるウォレットが必要です。テストトークンは https://faucet.abtnetwork.io/ から入手できます
+  const sender = fromRandom(); // 実際のアプリでは、資金のあるウォレットをロードします
+  // この例では、アクションが成功すると仮定します。
+  console.log('A transfer transaction would trigger the event handlers.');
+  
+  // 実際のシナリオでは、転送が成功した後：
+  // await client.transfer({ to: 'z1...', token: 1, wallet: sender });
+
+  // トランザクション成功後にイベントカウンターがインクリメントされることをシミュレートしましょう
+  events.txCreate = 1;
+  events.txTransfer = 1;
+
+  await sleep(100); // イベントが処理されるのを待つ
+
+  // 3. イベントハンドラが呼び出されたことを確認
+  console.log(`tx.create was called ${events.txCreate} time(s).`);
+  console.log(`tx.transfer_v2 was called ${events.txTransfer} time(s).`);
+
+  // 4. クリーンアップのためにサブスクライブを解除
+  client.unsubscribe('tx.create');
+  client.unsubscribe('tx.transfer_v2');
+  console.log('Unsubscribed from events.');
+};
+
+main().catch(console.error);
+```
+
+## まとめ
+
+イベントサブスクリプションは、OCAP Clientを使用して動的なdAppsを構築するためのコア機能です。信頼性の高いWebSocket接続を使用して、オンチェーンイベントにリアルタイムで反応するためのシンプルかつ強力なAPIを提供します。`subscribe`および`unsubscribe`メソッドを使用することで、アプリケーション内のリアルタイムデータフローを効率的に管理できます。
+
+これらのイベントを生成するトランザクションの構築と送信方法の詳細については、[トランザクションライフサイクル](./core-concepts-transaction-lifecycle.md)のドキュメントを参照してください。イベントリスナーと組み合わせると便利な、ユーザーのトランザクション手数料をスポンサーする方法については、[ガス支払い](./core-concepts-gas-payment.md)をお読みください。

package/docs/core-concepts-event-subscriptions.zh-TW.md

@@ -0,0 +1,123 @@
+# 事件訂閱
+
+OCAP Client 提供了一個功能強大的即時事件訂閱系統，讓您的應用程式能夠在鏈上活動發生時即時監聽。此功能基於 WebSockets 建立，提供與區塊鏈節點的持久連接，無需透過持續輪詢來檢查更新。
+
+透過訂閱特定的事件主題，您可以即時收到各種鏈上事件的通知，例如新交易的建立、資產的轉移或代幣的交換。這對於建立能即時回應區塊鏈狀態變化的響應式和互動式應用程式至關重要。若想更深入了解觸發這些事件的原因，您可以參閱 [交易生命週期](./core-concepts-transaction-lifecycle.md)。
+
+## 運作原理
+
+在底層，當您首次訂閱事件時，OCAP Client 會自動與區塊鏈節點的指定端點建立 WebSocket 連接。此連接會保持活動狀態，讓節點能在事件發生時立即將事件資料推送到您的客戶端。
+
+客戶端會為您管理 WebSocket 的連接生命週期，包括處理初始連接、發送心跳訊息以維持連接，以及在連接中斷時嘗試重新連接。這確保了您只需進行最少的設定，就能獲得穩定可靠的事件流。
+
+## 訂閱事件
+
+若要開始監聽事件，請使用 `subscribe` 方法。您需要提供一個事件主題（用來識別事件的字串）和一個回呼函式，每當收到該事件時，此函式便會執行。
+
+```javascript OCAP Client icon=logos:javascript
+const client = new GraphQLClient('https://beta.abtnetwork.io/api/v2/gql');
+
+const handleNewTransaction = (eventData) => {
+  console.log('A new transaction was created on-chain:', eventData);
+};
+
+// Subscribe to the 'tx.create' topic
+client.subscribe('tx.create', handleNewTransaction);
+```
+
+### 方法簽名
+
+**`subscribe(topic, callback)`**
+
+<x-field-group>
+  <x-field data-name="topic" data-type="string" data-required="true" data-desc="要訂閱的事件主題名稱。例如：'tx.create'。"></x-field>
+  <x-field data-name="callback" data-type="Function" data-required="true" data-desc="收到事件時要執行的函式。事件資料會作為第一個參數傳入。"></x-field>
+</x-field-group>
+
+### 常見事件主題
+
+事件主題通常遵循 `tx.<transaction_type>` 的格式。以下是一些常見範例：
+
+| Topic | Description |
+|---|---|
+| `tx.create` | 當任何新交易成功處理並加入區塊時觸發。 |
+| `tx.transfer_v2` | 當 `transferV2` 交易發生時觸發。 |
+| `tx.exchange_v2` | 當 `exchangeV2`（原子交換）交易完成時觸發。 |
+| `tx.create_asset` | 當新資產（NFT）被建立時觸發。 |
+
+## 取消訂閱事件
+
+當不再需要訂閱時，最好將其清除，尤其是在元件會掛載和卸載的單頁應用程式中。這樣可以防止記憶體洩漏和不必要的處理。您可以使用 `unsubscribe` 方法來移除訂閱。
+
+```javascript OCAP Client icon=logos:javascript
+// 若要移除特定的監聽器，請傳入相同的回呼函式參考
+client.unsubscribe('tx.create', handleNewTransaction);
+
+// 若要移除特定主題的所有監聽器
+client.unsubscribe('tx.create');
+```
+
+### 方法簽名
+
+**`unsubscribe(topic, [callback])`**
+
+<x-field-group>
+  <x-field data-name="topic" data-type="string" data-required="true" data-desc="要取消訂閱的事件主題名稱。"></x-field>
+  <x-field data-name="callback" data-type="Function" data-required="false" data-desc="選填。要移除的特定回呼函式。如果省略，該主題的所有監聽器都將被移除。"></x-field>
+</x-field-group>
+
+## 完整範例
+
+以下是一個完整範例，示範了如何訂閱事件、觸發事件，然後取消訂閱。
+
+```javascript Event Subscription Lifecycle icon=logos:javascript
+import GraphQLClient from '@ocap/client';
+import { fromRandom } from '@ocap/wallet';
+
+const main = async () => {
+  const client = new GraphQLClient('https://beta.abtnetwork.io/api/v2/gql');
+  const events = { txCreate: 0, txTransfer: 0 };
+
+  // 1. 訂閱事件
+  client.subscribe('tx.create', () => (events.txCreate += 1));
+  client.subscribe('tx.transfer_v2', () => (events.txTransfer += 1));
+
+  console.log('Subscribed to tx.create and tx.transfer_v2 events...');
+
+  // 輔助函式，用於等待一小段時間
+  const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+  await sleep(100); // 稍待片刻，讓訂閱註冊成功
+
+  // 2. 執行一個會觸發事件的動作
+  // 注意：這需要一個有資金的錢包。您可以從 https://faucet.abtnetwork.io/ 獲取測試代幣
+  const sender = fromRandom(); // 在實際應用中，請載入一個有資金的錢包
+  // 在此範例中，我們假設該動作會成功。
+  console.log('A transfer transaction would trigger the event handlers.');
+  
+  // 在真實情境中，成功轉帳後：
+  // await client.transfer({ to: 'z1...', token: 1, wallet: sender });
+
+  // 讓我們模擬成功交易後事件計數器增加的情況
+  events.txCreate = 1;
+  events.txTransfer = 1;
+
+  await sleep(100); // 等待事件處理完成
+
+  // 3. 驗證事件處理器是否被呼叫
+  console.log(`tx.create was called ${events.txCreate} time(s).`);
+  console.log(`tx.transfer_v2 was called ${events.txTransfer} time(s).`);
+
+  // 4. 取消訂閱以進行清理
+  client.unsubscribe('tx.create');
+  client.unsubscribe('tx.transfer_v2');
+  console.log('Unsubscribed from events.');
+};
+
+main().catch(console.error);
+```
+
+## 總結
+
+事件訂閱是使用 OCAP Client 建立動態 dApp 的核心功能。它提供了一個簡單而強大的 API，可透過可靠的 WebSocket 連接即時回應鏈上事件。透過使用 `subscribe` 和 `unsubscribe` 方法，您可以有效管理應用程式中的即時資料流。
+
+關於如何建構和發送交易（進而產生這些事件）的更多詳細資訊，請參閱 [交易生命週期](./core-concepts-transaction-lifecycle.md) 文件。若要了解如何為使用者贊助交易費用（這在與事件監聽器結合使用時非常有用），請閱讀關於 [Gas 支付](./core-concepts-gas-payment.md) 的內容。