@ocap/client 1.25.3 → 1.25.4

package/docs/core-concepts-gas-payment.zh.md

@@ -0,0 +1,111 @@
+# Gas 费支付
+
+在大多数区块链系统中，每笔交易都需要发起人支付一笔费用，通常称为“Gas”。对于可能没有原生货币来支付这些费用的新用户来说，这可能是一个巨大的障碍。OCAP Client 引入了 Gas 费支付功能，允许应用程序开发者代付这些费用，从而为用户创造无缝的“免 Gas”体验。
+
+这一强大功能使 dApp 能够将 Gas 的复杂性抽象出来，从而改善用户入门体验和应用的整体可用性。
+
+## 工作原理
+
+Gas 费支付机制通过标准的 HTTP 标头实现。当您在客户端实例上配置 Gas 支付方钱包时，客户端会自动将两个特殊的标头附加到它发送给区块链节点的每个 `sendTx` 变更中：
+
+- `x-gas-payer-pk`：将支付 Gas 费的钱包的公钥。
+- `x-gas-payer-sig`：由 Gas 支付方私钥签名的 JSON Web Token (JWT)。此令牌包含交易的哈希值，作为代付方为该特定交易支付费用的可验证授权。
+
+当区块链节点收到交易时，它会执行两个关键的验证：
+
+1. 验证用户在交易本身的签名。
+2. 根据交易哈希验证标头中 Gas 支付方的签名。
+
+如果两个签名都有效，交易将在用户的授权下执行，但相应的 Gas 费将从 Gas 支付方的账户余额中扣除。
+
+### 工作流图
+
+下图说明了从交易发起 Gas 费支付到执行的整个流程：
+
+```d2 Gas 费支付工作流 icon=mdi:gas-station
+direction: down
+
+User-App: {
+  label: "用户应用"
+  shape: rectangle
+}
+
+Gas-Payer-Wallet: {
+  label: "Gas 支付方钱包\n(应用后端钱包)"
+  shape: cylinder
+}
+
+OCAP-Client: {
+  label: "OCAP Client 实例"
+}
+
+Blockchain-Node: {
+  label: "区块链节点"
+  shape: rectangle
+}
+
+User-App -> OCAP-Client: "1. 用户发起交易"
+OCAP-Client -> OCAP-Client: "2. 使用用户钱包准备\n并签署交易"
+Gas-Payer-Wallet -> OCAP-Client: "3. 为 Gas 签署交易哈希"
+OCAP-Client -> Blockchain-Node: "4. 发送交易 + Gas 支付方标头"
+Blockchain-Node -> Blockchain-Node: "5. 验证双方签名"
+Blockchain-Node: "6. 执行交易"
+Blockchain-Node -> Gas-Payer-Wallet: "7. 扣除 Gas 费"
+```
+
+## 使用示例
+
+要启用免 Gas 交易，您只需为代付账户创建一个钱包实例，并使用 `setGasPayer` 方法在客户端上进行设置。
+
+```javascript Gas 支付方设置和使用 icon=logos:javascript
+import Client from '@ocap/client';
+import Wallet, { fromRandom } from '@ocap/wallet';
+
+// 1. 初始化客户端以连接到 Beta 链
+const client = new Client('https://beta.abtnetwork.io/api');
+
+// 2. 为 Gas 支付方（您的应用钱包）创建一个钱包
+// 此钱包必须有足够数量的原生代币（TBA）来支付交易费用。
+// 您可以从水龙头获取测试代币：https://faucet.abtnetwork.io/
+const gasPayerWallet = Wallet.fromJSON({
+  sk: '...your_sponsor_secret_key...',
+  pk: '...your_sponsor_public_key...',
+  address: '...your_sponsor_address...',
+});
+
+// 3. 在客户端实例上设置 Gas 支付方
+client.setGasPayer(gasPayerWallet);
+
+// 4. 为最终用户创建一个钱包。
+const userWallet = fromRandom();
+
+// 5. 使用用户的钱包发送一笔交易。
+// 该交易由用户签名，但 Gas 费由 gasPayerWallet 支付。
+async function performGaslessTransaction() {
+  try {
+    // 注意：虽然新账户在收到第一笔入账交易时会在链上创建，
+    // 但它必须在链上存在才能 *发送* 交易。
+    // 您可以通过从水龙头向其发送少量代币来初始化它。
+
+    const receiverAddress = 'z1...'; // 一个有效的接收地址
+    const hash = await client.transfer({
+      to: receiverAddress,
+      tokens: [{ value: '0.1' }], // 发送 0.1 TBA
+      wallet: userWallet,
+    });
+
+    console.log('免 Gas 交易成功。哈希：', hash);
+    console.log(`在浏览器中查看: https://beta.abtnetwork.io/explorer/txs/${hash}`);
+  } catch (error) {
+    console.error('交易失败：', error);
+  }
+}
+
+performGaslessTransaction();
+```
+
+在此示例中，即使 `userWallet` 的原生代币余额为零，它也可以成功发送交易，因为 `gasPayerWallet` 支付了费用。这创造了一种无摩擦的体验，特别是对于加入您应用的新用户。
+
+---
+
+要了解交易从创建到最终确认的完整过程，请参阅 [交易生命周期](./core-concepts-transaction-lifecycle.md) 文档。

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

@@ -0,0 +1,183 @@
+# Transaction Lifecycle
+
+Every action that modifies the state of the blockchain, such as transferring tokens or creating an asset, is executed through a transaction. Understanding the lifecycle of a transaction is fundamental to building applications with the OCAP Client. This process involves four main stages: Preparation, Encoding, Signing, and Sending.
+
+The OCAP Client provides a flexible set of methods that allow you to either perform these steps individually for maximum control or use high-level helpers that combine them for convenience.
+
+This guide breaks down each stage and illustrates both single-signature and multi-signature workflows.
+
+## Lifecycle Overview
+
+The following diagram illustrates the complete journey of a transaction from preparation to its final submission to the blockchain.
+
+```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
+```
+
+## Stage 1: Preparation (Creating the `itx`)
+
+Every transaction begins with an `itx` (inner transaction). This is a plain JavaScript object that contains the specific data for the action you want to perform. For example, a transfer `itx` would include the recipient's address and the amount.
+
+```javascript Preparing the itx icon=logos:javascript
+// The core data for our transfer transaction
+const itx = {
+  to: 'z2C8j81aL2oXpA5t42s2h4g9o8p1k6m3n7b', // Recipient's address
+  value: await client.fromTokenToUnit(10),   // Amount to send, converted to the chain's base unit
+};
+```
+
+## Stage 2: Encoding
+
+Encoding transforms the `itx` and other metadata into a standardized, binary format that can be cryptographically signed. The client provides an `encode{TxType}Tx` method for each transaction type (e.g., `encodeTransferV2Tx`).
+
+During this stage, the client automatically adds essential metadata:
+
+*   **`from`**: The sender's address, derived from the provided wallet.
+*   **`chainId`**: The identifier of the target blockchain, fetched automatically.
+*   **`nonce`**: A unique number to prevent replay attacks, which defaults to the current timestamp (`Date.now()`).
+*   **`pk`**: The public key of the sender's wallet.
+
+The encoding function returns both the full transaction object and a `Buffer` of the serialized data, which is used for signing.
+
+```javascript Encoding the Transaction icon=logos:javascript
+const { object: encodedTx, buffer: txBuffer } = await client.encodeTransferV2Tx({
+  tx: { itx },
+  wallet: senderWallet,
+});
+
+console.log('Encoded TX Object:', encodedTx);
+console.log('Buffer to be signed:', txBuffer);
+```
+
+## Stage 3: Signing
+
+Signing proves ownership of the account and authorizes the transaction. The process differs for single-signature and multi-signature workflows.
+
+### Single-Signature Workflow
+
+This is the most common scenario, where a single user signs a transaction. The `sign{TxType}Tx` methods take the encoded transaction, sign the binary buffer with the user's private key, and populate the `signature` field.
+
+```javascript Signing with a Single Signature icon=logos:javascript
+const signedTx = await client.signTransferV2Tx({
+  tx: encodedTx, // The object from the encoding step
+  wallet: senderWallet,
+});
+
+console.log('Signature:', signedTx.signature);
+```
+
+### Multi-Signature Workflow
+
+Multi-signature (multisig) transactions require approval from multiple parties. This is commonly used for atomic swaps or shared accounts. The process is sequential:
+
+1.  **Preparation**: The initial transaction is created with a `signaturesList` that defines all required signers.
+2.  **Sequential Signing**: The transaction is passed from one signer to the next. Each signer uses the corresponding `multiSign{TxType}Tx` method to add their signature.
+
+Internally, the `multiSign` method ensures that each party signs the exact same transaction digest by temporarily stripping all existing signatures before encoding the transaction for signing.
+
+Here’s an example for an `ExchangeTx`, where two parties swap assets.
+
+```javascript Multi-Signature Signing Example icon=logos:javascript
+// Step 1: Alice (the offerer) prepares and signs the exchange transaction.
+const txFromAlice = await client.prepareExchange({
+  offerToken: 10,
+  demandToken: 20,
+  receiver: bobWallet.address,
+  wallet: aliceWallet,
+});
+
+// Step 2: The transaction is sent to Bob.
+// Bob (the demander) adds his signature to finalize it.
+const txFromBob = await client.finalizeExchange({
+  tx: txFromAlice, // Transaction signed by Alice
+  wallet: bobWallet,
+});
+
+console.log('Alice\'s Signature:', txFromBob.signaturesList[0].signature);
+console.log('Bob\'s Signature:', txFromBob.signaturesList[1].signature);
+```
+
+## Stage 4: Sending
+
+Once a transaction is fully signed, it can be sent to the blockchain node for processing. The `send{TxType}Tx` methods handle this final step.
+
+For convenience, these methods can also perform the signing step implicitly if you provide a wallet and an unsigned transaction. The method returns a promise that resolves with the transaction hash upon successful submission.
+
+```javascript Sending the Signed Transaction icon=logos:javascript
+// Using a pre-signed transaction
+const hash = await client.sendTransferV2Tx({ tx: signedTx, wallet: senderWallet });
+
+// Or, letting the send method handle the signing automatically
+const hash2 = await client.sendTransferV2Tx({
+  tx: { itx }, // Just the inner transaction
+  wallet: senderWallet,
+});
+
+console.log('Transaction sent! Hash:', hash);
+```
+
+You can also include a `commit: true` option to make the client wait until the transaction is fully confirmed and included in a block before resolving the promise.
+
+## Summary
+
+The transaction lifecycle provides a robust and flexible framework for interacting with the blockchain. By breaking the process into distinct stages—Preparation, Encoding, Signing, and Sending—the OCAP Client offers developers granular control over transaction creation while also providing simple, high-level helpers for common use cases.
+
+For more details on how transaction fees are handled, see the [Gas Payment](./core-concepts-gas-payment.md) guide. To understand the different client types available, refer to the [Client Architecture](./core-concepts-client-architecture.md) documentation.

package/docs/core-concepts-transaction-lifecycle.zh.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: "传递已签名的交易"
+  Multi-Sign-2 -> Multi-Sign-N: "传递已签名的交易"
+}
+
+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('编码后的交易对象:', 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.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.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.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.