@ocap/client 1.25.3 → 1.25.5

package/docs/core-concepts-transaction-lifecycle.zh-TW.md

@@ -0,0 +1,183 @@
+# 交易生命週期
+
+每個修改區塊鏈狀態的動作，例如轉移代幣或創建資產，都是透過交易來執行的。理解交易的生命週期是使用 OCAP Client 建立應用程式的基礎。此過程涉及四個主要階段：準備、編碼、簽署和發送。
+
+OCAP Client 提供了一套靈活的方法，讓您可以為了最大程度的控制而單獨執行這些步驟，或者為了方便而使用將它們組合在一起的高階輔助函式。
+
+本指南將分解每個階段，並說明單簽和多簽的工作流程。
+
+## 生命週期總覽
+
+下圖說明了一筆交易從準備到最終提交至區塊鏈的完整過程。
+
+```d2 交易生命週期圖
+direction: down
+
+Start: {
+  label: "1. 準備 Itx"
+  shape: oval
+}
+
+Encode-Tx: {
+  label: "2. 編碼交易\n(encode<Type>Tx)"
+  shape: rectangle
+}
+
+Sign-Tx: {
+  label: "3. 簽署交易"
+  shape: diamond
+}
+
+Single-Sign: {
+  label: "單一簽名\n(sign<Type>Tx)"
+  shape: rectangle
+}
+
+Multi-Sign-Flow: {
+  label: "多重簽名"
+  shape: rectangle
+  
+  Multi-Sign-1: {
+    label: "簽署者 1\n(multiSign<Type>Tx)"
+  }
+  
+  Multi-Sign-2: {
+    label: "簽署者 2\n(multiSign<Type>Tx)"
+  }
+
+  Multi-Sign-N: {
+    label: "..."
+  }
+  
+  Multi-Sign-1 -> Multi-Sign-2: "傳遞已簽署的 TX"
+  Multi-Sign-2 -> Multi-Sign-N: "傳遞已簽署的 TX"
+}
+
+Send-Tx: {
+  label: "4. 發送交易\n(send<Type>Tx)"
+  shape: rectangle
+}
+
+End: {
+  label: "交易雜湊值"
+  shape: oval
+}
+
+Start -> Encode-Tx
+Encode-Tx -> Sign-Tx
+Sign-Tx -> Single-Sign: "單一簽署者"
+Sign-Tx -> Multi-Sign-Flow: "多重簽署者"
+Single-Sign -> Send-Tx
+Multi-Sign-Flow -> Send-Tx
+Send-Tx -> End
+```
+
+## 階段 1：準備 (建立 `itx`)
+
+每筆交易都始於一個 `itx` (內部交易)。這是一個純粹的 JavaScript 物件，其中包含您想要執行的動作的具體資料。例如，一筆轉帳 `itx` 會包含收款人的地址和金額。
+
+```javascript 準備 itx icon=logos:javascript
+// 我們轉帳交易的核心資料
+const itx = {
+  to: 'z2C8j81aL2oXpA5t42s2h4g9o8p1k6m3n7b', // 收款人地址
+  value: await client.fromTokenToUnit(10),   // 要發送的金額，已轉換為鏈上的基本單位
+};
+```
+
+## 階段 2：編碼
+
+編碼會將 `itx` 和其他元資料轉換為一個標準化的二進位格式，以便進行密碼學簽署。客戶端為每種交易類型提供了一個 `encode{TxType}Tx` 方法（例如 `encodeTransferV2Tx`）。
+
+在此階段，客戶端會自動添加必要的元資料：
+
+*   **`from`**：發送者的地址，從提供的錢包中派生。
+*   **`chainId`**：目標區塊鏈的識別碼，會自動擷取。
+*   **`nonce`**：一個唯一的數字，用以防止重放攻擊，預設為當前時間戳 (`Date.now()`)。
+*   **`pk`**：發送者錢包的公鑰。
+
+編碼函式會回傳完整的交易物件和序列化資料的 `Buffer`，後者用於簽署。
+
+```javascript 編碼交易 icon=logos:javascript
+const { object: encodedTx, buffer: txBuffer } = await client.encodeTransferV2Tx({
+  tx: { itx },
+  wallet: senderWallet,
+});
+
+console.log('編碼後的 TX 物件:', encodedTx);
+console.log('待簽署的 Buffer:', txBuffer);
+```
+
+## 階段 3：簽署
+
+簽署證明了帳戶的所有權並授權該交易。單簽和多簽工作流程的過程有所不同。
+
+### 單簽工作流程
+
+這是最常見的情境，即單一使用者簽署一筆交易。`sign{TxType}Tx` 方法會接收編碼後的交易，使用者的私鑰簽署二進位緩衝區，並填入 `signature` 欄位。
+
+```javascript 使用單一簽名進行簽署 icon=logos:javascript
+const signedTx = await client.signTransferV2Tx({
+  tx: encodedTx, // 來自編碼步驟的物件
+  wallet: senderWallet,
+});
+
+console.log('簽名:', signedTx.signature);
+```
+
+### 多簽工作流程
+
+多重簽名 (multisig) 交易需要多方批准。這通常用於原子交換或共享帳戶。此過程是循序的：
+
+1.  **準備**：初始交易會與一個定義了所有必要簽署者的 `signaturesList` 一同建立。
+2.  **循序簽署**：交易會從一個簽署者傳遞到下一個。每個簽署者都使用對應的 `multiSign{TxType}Tx` 方法來添加他們的簽名。
+
+在內部，`multiSign` 方法會透過在編碼交易以供簽署前，暫時移除所有現有簽名，來確保各方簽署的是完全相同的交易摘要。
+
+以下是一個 `ExchangeTx` 的範例，其中兩方交換資產。
+
+```javascript 多重簽名範例 icon=logos:javascript
+// 步驟 1：Alice (要約方) 準備並簽署交換交易。
+const txFromAlice = await client.prepareExchange({
+  offerToken: 10,
+  demandToken: 20,
+  receiver: bobWallet.address,
+  wallet: aliceWallet,
+});
+
+// 步驟 2：交易被發送給 Bob。
+// Bob (承諾方) 添加他的簽名以完成交易。
+const txFromBob = await client.finalizeExchange({
+  tx: txFromAlice, // 由 Alice 簽署的交易
+  wallet: bobWallet,
+});
+
+console.log('Alice 的簽名:', txFromBob.signaturesList[0].signature);
+console.log('Bob 的簽名:', txFromBob.signaturesList[1].signature);
+```
+
+## 階段 4：發送
+
+一旦交易完全簽署，就可以將其發送到區塊鏈節點進行處理。`send{TxType}Tx` 方法負責處理這最後一步。
+
+為了方便起見，如果您提供一個錢包和一筆未簽署的交易，這些方法也可以隱式地執行簽署步驟。此方法會回傳一個 promise，在成功提交後，該 promise 會解析並回傳交易雜湊值。
+
+```javascript 發送已簽署的交易 icon=logos:javascript
+// 使用預先簽署的交易
+const hash = await client.sendTransferV2Tx({ tx: signedTx, wallet: senderWallet });
+
+// 或者，讓發送方法自動處理簽署
+const hash2 = await client.sendTransferV2Tx({
+  tx: { itx }, // 僅有內部交易
+  wallet: senderWallet,
+});
+
+console.log('交易已發送！雜湊值:', hash);
+```
+
+您也可以包含一個 `commit: true` 選項，使客戶端等到交易完全確認並被包含在一個區塊中後，才解析該 promise。
+
+## 總結
+
+交易生命週期提供了一個穩健且靈活的框架，用於與區塊鏈互動。透過將過程分解為不同的階段——準備、編碼、簽署和發送——OCAP Client 為開發者提供了對交易創建的精細控制，同時也為常見用例提供了簡單的高階輔助函式。
+
+有關交易手續費如何處理的更多詳情，請參閱 [Gas 費用支付](./core-concepts-gas-payment.md) 指南。要了解可用的不同客戶端類型，請參閱 [客戶端架構](./core-concepts-client-architecture.md) 文件。

package/docs/core-concepts-transaction-lifecycle.zh.md

@@ -0,0 +1,183 @@
+# 交易生命周期
+
+每一个修改区块链状态的操作，例如转移通证或创建资产，都是通过交易来执行的。理解交易的生命周期是使用 OCAP Client 构建应用的基础。此过程涉及四个主要阶段：准备、编码、签名和发送。
+
+OCAP Client 提供了一套灵活的方法，允许您为了最大程度的控制而单独执行这些步骤，或者为了方便而使用将它们组合在一起的高级辅助函数。
+
+本指南将分解每个阶段，并说明单签名和多签名工作流。
+
+## 生命周期概览
+
+下图说明了交易从准备到最终提交至区块链的完整过程。
+
+```d2 Transaction Lifecycle Diagram
+direction: down
+
+Start: {
+  label: "1. Prepare Itx"
+  shape: oval
+}
+
+Encode-Tx: {
+  label: "2. Encode Transaction\n(encode<Type>Tx)"
+  shape: rectangle
+}
+
+Sign-Tx: {
+  label: "3. Sign Transaction"
+  shape: diamond
+}
+
+Single-Sign: {
+  label: "Single Signature\n(sign<Type>Tx)"
+  shape: rectangle
+}
+
+Multi-Sign-Flow: {
+  label: "Multi-Signature"
+  shape: rectangle
+  
+  Multi-Sign-1: {
+    label: "Signer 1\n(multiSign<Type>Tx)"
+  }
+  
+  Multi-Sign-2: {
+    label: "Signer 2\n(multiSign<Type>Tx)"
+  }
+
+  Multi-Sign-N: {
+    label: "..."
+  }
+  
+  Multi-Sign-1 -> Multi-Sign-2: "Pass signed TX"
+  Multi-Sign-2 -> Multi-Sign-N: "Pass signed TX"
+}
+
+Send-Tx: {
+  label: "4. Send Transaction\n(send<Type>Tx)"
+  shape: rectangle
+}
+
+End: {
+  label: "Transaction Hash"
+  shape: oval
+}
+
+Start -> Encode-Tx
+Encode-Tx -> Sign-Tx
+Sign-Tx -> Single-Sign: "Single Signer"
+Sign-Tx -> Multi-Sign-Flow: "Multiple Signers"
+Single-Sign -> Send-Tx
+Multi-Sign-Flow -> Send-Tx
+Send-Tx -> End
+```
+
+## 阶段 1：准备（创建 `itx`）
+
+每笔交易都始于一个 `itx`（内部交易）。这是一个纯粹的 JavaScript 对象，包含了您想要执行的操作的具体数据。例如，一个转账 `itx` 会包含接收方的地址和金额。
+
+```javascript Preparing the itx icon=logos:javascript
+// 我们转账交易的核心数据
+const itx = {
+  to: 'z2C8j81aL2oXpA5t42s2h4g9o8p1k6m3n7b', // 接收方地址
+  value: await client.fromTokenToUnit(10),   // 要发送的金额，已转换为链的基本单位
+};
+```
+
+## 阶段 2：编码
+
+编码将 `itx` 和其他元数据转换为一种标准化的二进制格式，以便进行加密签名。客户端为每种交易类型提供了一个 `encode{TxType}Tx` 方法（例如，`encodeTransferV2Tx`）。
+
+在此阶段，客户端会自动添加必要的元数据：
+
+*   **`from`**：发送方地址，从提供的钱包中派生。
+*   **`chainId`**：目标区块链的标识符，自动获取。
+*   **`nonce`**：一个用于防止重放攻击的唯一数字，默认为当前时间戳（`Date.now()`）。
+*   **`pk`**：发送方钱包的公钥。
+
+编码函数会返回完整的交易对象和一个序列化数据的 `Buffer`，后者用于签名。
+
+```javascript Encoding the Transaction icon=logos:javascript
+const { object: encodedTx, buffer: txBuffer } = await client.encodeTransferV2Tx({
+  tx: { itx },
+  wallet: senderWallet,
+});
+
+console.log('编码后的交易对象：', encodedTx);
+console.log('待签名的 Buffer：', txBuffer);
+```
+
+## 阶段 3：签名
+
+签名证明了账户的所有权并授权该交易。单签名和多签名工作流的过程有所不同。
+
+### 单签名工作流
+
+这是最常见的场景，即单个用户签署一笔交易。`sign{TxType}Tx` 方法接收编码后的交易，使用用户的私钥对二进制缓冲区进行签名，并填充 `signature` 字段。
+
+```javascript Signing with a Single Signature icon=logos:javascript
+const signedTx = await client.signTransferV2Tx({
+  tx: encodedTx, // 编码步骤中得到的对象
+  wallet: senderWallet,
+});
+
+console.log('签名：', signedTx.signature);
+```
+
+### 多签名工作流
+
+多重签名（multisig）交易需要多方批准。这通常用于原子交换或共享账户。该过程是顺序的：
+
+1.  **准备**：创建初始交易时，需包含一个定义了所有必需签名者的 `signaturesList`。
+2.  **顺序签名**：交易从一个签名者传递到下一个。每个签名者使用相应的 `multiSign{TxType}Tx` 方法添加自己的签名。
+
+在内部，`multiSign` 方法通过在编码交易以进行签名之前临时剥离所有现有签名，来确保各方签署的是完全相同的交易摘要。
+
+以下是一个关于 `ExchangeTx` 的示例，其中两方交换资产。
+
+```javascript Multi-Signature Signing Example icon=logos:javascript
+// 步骤 1：Alice（报价方）准备并签署交换交易。
+const txFromAlice = await client.prepareExchange({
+  offerToken: 10,
+  demandToken: 20,
+  receiver: bobWallet.address,
+  wallet: aliceWallet,
+});
+
+// 步骤 2：将交易发送给 Bob。
+// Bob（需求方）添加他的签名以最终完成交易。
+const txFromBob = await client.finalizeExchange({
+  tx: txFromAlice, // 由 Alice 签名的交易
+  wallet: bobWallet,
+});
+
+console.log('Alice 的签名：', txFromBob.signaturesList[0].signature);
+console.log('Bob 的签名：', txFromBob.signaturesList[1].signature);
+```
+
+## 阶段 4：发送
+
+一旦交易被完全签名，就可以发送到区块链节点进行处理。`send{TxType}Tx` 方法处理这最后一步。
+
+为方便起见，如果您提供一个钱包和一个未签名的交易，这些方法也可以隐式执行签名步骤。该方法返回一个 promise，在成功提交后会解析为交易哈希。
+
+```javascript Sending the Signed Transaction icon=logos:javascript
+// 使用预先签名的交易
+const hash = await client.sendTransferV2Tx({ tx: signedTx, wallet: senderWallet });
+
+// 或者，让发送方法自动处理签名
+const hash2 = await client.sendTransferV2Tx({
+  tx: { itx }, // 仅内部交易
+  wallet: senderWallet,
+});
+
+console.log('交易已发送！哈希：', hash);
+```
+
+您还可以包含一个 `commit: true` 选项，让客户端在解析 promise 之前，等待交易被完全确认并包含在区块中。
+
+## 总结
+
+交易生命周期为与区块链交互提供了一个强大而灵活的框架。通过将过程分解为准备、编码、签名和发送这几个不同阶段，OCAP Client 为开发者提供了对交易创建的精细控制，同时也为常见用例提供了简单的高级辅助函数。
+
+有关如何处理交易费用的更多详情，请参阅[燃料费支付](./core-concepts-gas-payment.md)指南。要了解可用的不同客户端类型，请参阅[客户端架构](./core-concepts-client-architecture.md)文档。

package/docs/core-concepts.ja.md

@@ -0,0 +1,22 @@
+# コアコンセプト
+
+このセクションでは、OCAP Client ライブラリを形成する基本原則とアーキテクチャ上の決定について詳しく説明します。これらのコアコンセプトを理解することで、ライブラリの可能性を最大限に引き出し、より効率的なコードを記述し、問題をより効果的にトラブルシューティングできるようになります。
+
+[ハウツーガイド](./how-to-guides.md)では特定のタスクのステップバイステップの手順を説明していますが、このセクションではその「方法」の背後にある「理由」を説明します。クライアントの構造、トランザクションが最初から最後までどのように処理されるか、リアルタイムイベントのリッスン方法、そしてガスレスなユーザーエクスペリエンスの作成方法について探ります。
+
+<x-cards data-columns="2">
+  <x-card data-title="クライアントアーキテクチャ" data-icon="lucide:architecture" data-href="/core-concepts/client-architecture">
+    さまざまなクライアント実装（Node、ブラウザ、Lite）について学び、パフォーマンスとバンドルサイズを最適化するために、ご自身の環境に適したものを選択する方法を学びます。
+  </x-card>
+  <x-card data-title="トランザクションのライフサイクル" data-icon="lucide:refresh-cw" data-href="/core-concepts/transaction-lifecycle">
+    単純な JavaScript オブジェクトからチェーン上で確認済みのブロックになるまでのトランザクションの過程を追い、作成、エンコード、署名、ブロードキャストまでをカバーします。
+  </x-card>
+  <x-card data-title="イベントサブスクリプション" data-icon="lucide:radio-tower" data-href="/core-concepts/event-subscriptions">
+    WebSocket ベースのサブスクリプション機能を使用してリアルタイムのオンチェーンイベントをリッスンし、動的で応答性の高いアプリケーションを実現する方法を発見します。
+  </x-card>
+  <x-card data-title="ガス支払い" data-icon="lucide:gas-pump" data-href="/core-concepts/gas-payment">
+    指定されたウォレットがユーザーのトランザクション手数料を負担できるようにする強力なガス支払い機能を探索し、シームレスでガスレスな体験を創出します。
+  </x-card>
+</x-cards>
+
+これらの基礎的なトピックを理解することで、OCAP Client を使用して、堅牢でスケーラブル、かつユーザーフレンドリーなアプリケーションを構築するための準備が整います。

package/docs/core-concepts.md

@@ -0,0 +1,22 @@
+# Core Concepts
+
+This section dives into the fundamental principles and architectural decisions that shape the OCAP Client library. Understanding these core concepts will help you leverage the library's full potential, write more efficient code, and troubleshoot issues more effectively.
+
+While the [How-to Guides](./how-to-guides.md) provide step-by-step instructions for specific tasks, this section explains the "why" behind the "how." We'll explore the client's structure, how transactions are processed from start to finish, how to listen for real-time events, and how to create gasless user experiences.
+
+<x-cards data-columns="2">
+  <x-card data-title="Client Architecture" data-icon="lucide:architecture" data-href="/core-concepts/client-architecture">
+    Learn about the different client implementations (Node, Browser, Lite) and how to choose the right one for your environment to optimize performance and bundle size.
+  </x-card>
+  <x-card data-title="Transaction Lifecycle" data-icon="lucide:refresh-cw" data-href="/core-concepts/transaction-lifecycle">
+    Follow a transaction's journey from a simple JavaScript object to a confirmed block on the chain, covering creation, encoding, signing, and broadcasting.
+  </x-card>
+  <x-card data-title="Event Subscriptions" data-icon="lucide:radio-tower" data-href="/core-concepts/event-subscriptions">
+    Discover how to use the WebSocket-based subscription feature to listen for real-time on-chain events, enabling dynamic and responsive applications.
+  </x-card>
+  <x-card data-title="Gas Payment" data-icon="lucide:gas-pump" data-href="/core-concepts/gas-payment">
+    Explore the powerful gas payment feature, which allows a designated wallet to sponsor transaction fees for users, creating seamless, gasless experiences.
+  </x-card>
+</x-cards>
+
+By grasping these foundational topics, you'll be well-equipped to build robust, scalable, and user-friendly applications using the OCAP Client.

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

@@ -0,0 +1,22 @@
+# 核心概念
+
+本節深入探討了 OCAP Client 程式庫的基本原則和架構決策。理解這些核心概念將有助於您充分發揮程式庫的潛力，撰寫更有效率的程式碼，並更有效地解決問題。
+
+[操作指南](./how-to-guides.md) 提供了特定任務的逐步說明，而本節則解釋了「如何做」背後的「為什麼」。我們將探討客戶端的結構、交易從開始到結束的處理過程、如何監聽即時事件，以及如何創造無 Gas 費的使用者體驗。
+
+<x-cards data-columns="2">
+  <x-card data-title="客戶端架構" data-icon="lucide:architecture" data-href="/core-concepts/client-architecture">
+    了解不同的客戶端實作（Node、Browser、Lite），以及如何為您的環境選擇合適的實作以優化效能和打包大小。
+  </x-card>
+  <x-card data-title="交易生命週期" data-icon="lucide:refresh-cw" data-href="/core-concepts/transaction-lifecycle">
+    追蹤一筆交易從簡單的 JavaScript 物件到鏈上確認區塊的完整過程，涵蓋創建、編碼、簽署和廣播。
+  </x-card>
+  <x-card data-title="事件訂閱" data-icon="lucide:radio-tower" data-href="/core-concepts/event-subscriptions">
+    探索如何使用基於 WebSocket 的訂閱功能來監聽即時的鏈上事件，從而實現動態且響應迅速的應用程式。
+  </x-card>
+  <x-card data-title="Gas 費支付" data-icon="lucide:gas-pump" data-href="/core-concepts/gas-payment">
+    探索強大的 Gas 費支付功能，該功能允許指定錢包為使用者支付交易費用，創造無縫、無 Gas 費的體驗。
+  </x-card>
+</x-cards>
+
+掌握這些基礎主題後，您將能充分準備好使用 OCAP Client 建立穩健、可擴展且使用者友善的應用程式。

package/docs/core-concepts.zh.md

@@ -0,0 +1,22 @@
+# 核心概念
+
+本节深入探讨了构成 OCAP Client 库的基本原则和架构决策。理解这些核心概念将帮助您充分发挥该库的潜力，编写更高效的代码，并更有效地解决问题。
+
+虽然[操作指南](./how-to-guides.md)为特定任务提供了分步说明，但本节解释了“如何做”背后的“为什么”。我们将探讨客户端的结构、交易从开始到结束的处理过程、如何监听实时事件以及如何创建无 Gas 费用的用户体验。
+
+<x-cards data-columns="2">
+  <x-card data-title="客户端架构" data-icon="lucide:architecture" data-href="/core-concepts/client-architecture">
+    了解不同的客户端实现（Node、Browser、Lite），以及如何为您的环境选择合适的实现以优化性能和包大小。
+  </x-card>
+  <x-card data-title="交易生命周期" data-icon="lucide:refresh-cw" data-href="/core-concepts/transaction-lifecycle">
+    追踪一笔交易从简单的 JavaScript 对象到链上确认块的全过程，包括创建、编码、签名和广播。
+  </x-card>
+  <x-card data-title="事件订阅" data-icon="lucide:radio-tower" data-href="/core-concepts/event-subscriptions">
+    了解如何使用基于 WebSocket 的订阅功能来监听链上实时事件，从而实现动态和响应迅速的应用程序。
+  </x-card>
+  <x-card data-title="Gas 费支付" data-icon="lucide:gas-pump" data-href="/core-concepts/gas-payment">
+    探索强大的 Gas 费支付功能，该功能允许指定钱包为用户代付交易费用，从而创造无缝、无需 Gas 费的体验。
+  </x-card>
+</x-cards>
+
+通过掌握这些基础主题，您将能够使用 OCAP Client 构建稳健、可扩展且用户友好的应用程序。

package/docs/getting-started-basic-usage.ja.md

@@ -0,0 +1,87 @@
+# 基本的な使い方
+
+このガイドでは、OCAP Clientを使い始めるための基本的な手順を説明します。クライアントの初期化、ArcBlock Beta Chainへの接続、そしてすべてが正しく設定されていることを確認するための基本的なクエリの実行方法を学びます。
+
+このガイドに従うことで、わずか数分でブロックチェーンと対話する準備が整ったクライアントインスタンスを稼働させることができます。
+
+## 1. クライアントの初期化
+
+まず、`@ocap/client` パッケージをインポートし、`GraphQLClient` のインスタンスを作成する必要があります。コンストラクタには、接続したいブロックチェーンノードのGraphQLエンドポイントを渡します。このガイドでは、ArcBlock Beta Chainの公開エンドポイントを使用します。
+
+```javascript Initialize Client icon=logos:javascript
+const GraphQLClient = require('@ocap/client');
+
+// Beta Chainに接続
+const client = new GraphQLClient('https://beta.abtnetwork.io/api');
+
+console.log('OCAP Clientが初期化されました！');
+```
+
+これにより、チェーンのクエリ、トランザクションの送信などのメソッドが事前設定されたクライアントインスタンスが作成されます。
+
+## 2. ブロックチェーンのクエリ
+
+クライアントが初期化されたので、簡単な読み取り専用操作を実行して接続を確認できます。`getChainInfo` メソッドは、接続されたブロックチェーンに関する基本情報を取得し、認証を必要としないため、この目的に最適です。
+
+```javascript Query Chain Info icon=logos:javascript
+(async () => {
+  try {
+    const { info } = await client.getChainInfo();
+    console.log('チェーン情報:', info);
+  } catch (error) {
+    console.error('チェーン情報の取得に失敗しました:', error);
+  }
+})();
+```
+
+リクエストが成功すると、`info` オブジェクトがコンソールに出力されます。これには、チェーンのID、ネットワーク、サポートされているトランザクションタイプなどの詳細が含まれます。これにより、クライアントがブロックチェーンノードと正常に通信していることが確認できます。
+
+## 3. アカウントの準備
+
+トランザクション（書き込み操作）を送信するには、ウォレットが必要です。ローカルで新しいウォレットを生成できます。このウォレットは、オンチェーンでのアカウントIDを表します。
+
+```javascript Create a Wallet icon=logos:javascript
+const { fromRandom } = require('@ocap/wallet');
+
+// 新しいランダムなウォレットを作成
+const wallet = fromRandom();
+
+console.log('新しいウォレットが作成されました:');
+console.log('アドレス:', wallet.address);
+console.log('公開鍵:', wallet.publicKey);
+console.log('秘密鍵:', wallet.secretKey);
+```
+
+**重要:** 新しく生成されたウォレットは単なるキーペアであり、まだブロックチェーン上には存在しません。アカウントは、そのアドレスが最初の受信トランザクションを受け取ったときに、オンチェーンで自動的に作成されます。
+
+新しいアカウントを有効にするには、テストトークンで資金を供給する必要があります。公式フォーセットからBeta Chain用の無料テストトークン（`TBA`）を入手できます：
+
+<x-card data-title="ArcBlockフォーセット" data-icon="lucide:droplet" data-href="https://faucet.abtnetwork.io/" data-cta="テストトークンを取得">
+  フォーセットにアクセスし、新しく生成したアドレスにTBAを送信して有効化してください。
+</x-card>
+
+## 4. アカウント状態のクエリ
+
+フォーセットを使って新しいアカウントに資金を入金したら、その状態をクエリして残高を確認できます。
+
+```javascript Query Account State icon=logos:javascript
+(async () => {
+  try {
+    // フォーセットから資金供給したアドレスに置き換えてください
+    const address = wallet.address;
+
+    const { state } = await client.getAccountState({ address });
+    console.log('アカウント状態:', state);
+  } catch (error) {
+    console.error('アカウント状態の取得に失敗しました:', error);
+  }
+})();
+```
+
+レスポンスの `state` オブジェクトには、アカウントのアドレス、残高、ナンス（送信されたトランザクション数）、その他の詳細が含まれます。残高がゼロでないことを確認できれば、アカウントがフォーセットからトークンを受け取り、ブロックチェーン上で有効になったことが確定します。
+
+## 次のステップ
+
+これでOCAP Clientのセットアップ、ブロックチェーンへの接続、アカウントの確認が正常に完了しました。より高度な操作に進む準備が整いました。
+
+トークンの転送、アセットの管理などの一般的なタスクを実行する方法については、[ハウツーガイド](./how-to-guides.md)をご覧ください。

package/docs/getting-started-basic-usage.md

@@ -0,0 +1,87 @@
+# Basic Usage
+
+This guide will walk you through the essential steps to get started with the OCAP Client. You'll learn how to initialize the client, connect to the ArcBlock Beta Chain, and perform a basic query to ensure everything is set up correctly.
+
+Following this guide, you should have a working client instance ready to interact with the blockchain in just a few minutes.
+
+## 1. Initialize the Client
+
+First, you need to import the `@ocap/client` package and create an instance of `GraphQLClient`. The constructor takes the GraphQL endpoint of the blockchain node you want to connect to. For this guide, we will use the public endpoint for the ArcBlock Beta Chain.
+
+```javascript Initialize Client icon=logos:javascript
+const GraphQLClient = require('@ocap/client');
+
+// Connect to the Beta Chain
+const client = new GraphQLClient('https://beta.abtnetwork.io/api');
+
+console.log('OCAP Client initialized!');
+```
+
+This creates a client instance that is pre-configured with methods for querying the chain, sending transactions, and more.
+
+## 2. Query the Blockchain
+
+Now that the client is initialized, you can perform a simple read-only operation to verify the connection. The `getChainInfo` method is perfect for this, as it fetches basic information about the connected blockchain and doesn't require any authentication.
+
+```javascript Query Chain Info icon=logos:javascript
+(async () => {
+  try {
+    const { info } = await client.getChainInfo();
+    console.log('Chain Info:', info);
+  } catch (error) {
+    console.error('Failed to get chain info:', error);
+  }
+})();
+```
+
+If the request is successful, the `info` object will be logged to the console, containing details about the chain such as its ID, network, and supported transaction types. This confirms your client is successfully communicating with the blockchain node.
+
+## 3. Prepare an Account
+
+To send transactions (write operations), you need a wallet. You can generate a new wallet locally. This wallet represents your on-chain account identity.
+
+```javascript Create a Wallet icon=logos:javascript
+const { fromRandom } = require('@ocap/wallet');
+
+// Create a new random wallet
+const wallet = fromRandom();
+
+console.log('New wallet created:');
+console.log('Address:', wallet.address);
+console.log('PublicKey:', wallet.publicKey);
+console.log('SecretKey:', wallet.secretKey);
+```
+
+**Important:** A newly generated wallet is just a key pair. It does not exist on the blockchain yet. An account is automatically created on-chain when its address receives its first incoming transaction.
+
+To make your new account active, you need to fund it with some test tokens. You can get free test tokens (`TBA`) for the Beta Chain from the official faucet:
+
+<x-card data-title="ArcBlock Faucet" data-icon="lucide:droplet" data-href="https://faucet.abtnetwork.io/" data-cta="Get Test Tokens">
+  Visit the faucet and send some TBA to your newly generated address to activate it.
+</x-card>
+
+## 4. Query Account State
+
+Once you have funded your new account using the faucet, you can query its state to verify the balance.
+
+```javascript Query Account State icon=logos:javascript
+(async () => {
+  try {
+    // Replace with the address you funded from the faucet
+    const address = wallet.address;
+
+    const { state } = await client.getAccountState({ address });
+    console.log('Account State:', state);
+  } catch (error) {
+    console.error('Failed to get account state:', error);
+  }
+})();
+```
+
+The `state` object in the response will contain your account's address, balance, nonce (number of transactions sent), and other details. Seeing a non-zero balance confirms that your account has received the tokens from the faucet and is now active on the blockchain.
+
+## Next Steps
+
+You have successfully set up the OCAP Client, connected to the blockchain, and verified your account. You are now ready to explore more advanced operations.
+
+Check out the [How-to Guides](./how-to-guides.md) to learn how to perform common tasks like transferring tokens, managing assets, and more.