@ocap/client 1.25.3 → 1.25.4

package/docs/api-reference.zh.md

@@ -0,0 +1,23 @@
+# API 参考
+
+欢迎使用 OCAP 客户端 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/core-concepts-client-architecture.md

@@ -0,0 +1,102 @@
+# Client Architecture
+
+The OCAP Client is designed with a modular architecture to cater to different JavaScript environments and specific use cases. Instead of a one-size-fits-all library, it offers several client implementations, each optimized for a particular context, such as a Node.js backend or a bundle-size-sensitive web application. This approach allows you to choose the most efficient client for your needs, ensuring better performance and a smaller footprint where necessary.
+
+All client variations are built upon a common base, `GraphQLClientBase`, which provides the core functionality for interacting with the blockchain's GraphQL API.
+
+### Inheritance Diagram
+
+The following diagram illustrates the relationship between the different client implementations:
+
+```d2
+direction: down
+
+GraphQLClientBase: {
+  label: "GraphQLClientBase\n(Core Functionality)"
+  shape: rectangle
+}
+
+GraphQLClient: {
+  label: "GraphQLClient\n(Full Client + Helpers)"
+  shape: rectangle
+}
+
+GraphqlClientLite: {
+  label: "GraphqlClientLite\n(Browser-Optimized)"
+  shape: rectangle
+}
+
+NativeGraphqlClient: {
+  label: "NativeGraphqlClient\n(Node.js-Optimized)"
+  shape: rectangle
+}
+
+GraphQLClientBase -> GraphQLClient: "Extends"
+GraphQLClientBase -> GraphqlClientLite: "Extends"
+GraphQLClient -> NativeGraphqlClient: "Extends"
+```
+
+## Client Implementations
+
+Here's a breakdown of each available client and its intended use case.
+
+### `GraphQLClientBase` (The Core)
+
+This is the foundational, lightweight client that all other clients extend. It provides the essential features for communicating with the blockchain:
+
+- Sending GraphQL queries and mutations.
+- Establishing WebSocket connections for real-time event subscriptions.
+- Handling gas payment headers for sponsored transactions.
+- It is environment-agnostic but requires you to provide compatible implementations for WebSockets and EventEmitters if you use subscriptions.
+
+This client is ideal if you only need basic, read-only functionality and want to minimize dependencies.
+
+### `GraphQLClient` (The Full Client)
+
+This is the standard, general-purpose client and the one you'll likely use most often. It extends `GraphQLClientBase` and adds a rich set of high-level helper methods that simplify common on-chain operations. These helpers cover tasks like creating assets, transferring tokens, and managing stakes, abstracting away the complexity of raw GraphQL mutations.
+
+By default, it also automatically initializes its context upon instantiation, making it ready to use immediately.
+
+### `NativeGraphqlClient` (For Node.js)
+
+This client is specifically optimized for the Node.js runtime. It extends the full `GraphQLClient` and configures it to use Node.js's native `events` module for its event handling. This makes it the most performant and reliable choice for any backend application, command-line tool, or script running on a server.
+
+### `GraphqlClientLite` (For Browsers)
+
+Designed for front-end web applications, the `GraphqlClientLite` extends `GraphQLClientBase` and is optimized for minimal bundle size. It swaps out Node.js-specific dependencies for browser-compatible alternatives like `wolfy87-eventemitter`. If you are building a web application where performance and load times are critical, this client provides the core OCAP functionality without the extra weight of the full helper method suite.
+
+## Which Client Should I Use?
+
+To help you decide, here is a summary of the recommended client for each scenario:
+
+| Environment | Use Case                                     | Recommended Client       | Import Path             |
+| :---------- | :------------------------------------------- | :----------------------- | :---------------------- |
+| Node.js     | Backend services, scripts, CLI tools         | `NativeGraphqlClient`    | `@ocap/client/node`     |
+| Browser     | General web applications (e.g., React, Vue)  | `GraphQLClient`          | `@ocap/client`          |
+| Browser     | Bundle-size sensitive applications           | `GraphqlClientLite`      | `@ocap/client/lite`     |
+| Any         | Read-only, minimal functionality required    | `GraphQLClientBase`      | `@ocap/client/base`     |
+
+### Example Imports
+
+Here’s how you would import each client in your code:
+
+```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');
+```
+
+## Summary
+
+Understanding the different client implementations allows you to make an informed choice that best fits your application's environment and requirements. By selecting the appropriate client, you can optimize for performance, bundle size, and ease of use.
+
+Now that you understand the client architecture, you can dive deeper into how transactions are constructed and processed. Learn more in the [Transaction Lifecycle](./core-concepts-transaction-lifecycle.md) guide.

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

@@ -0,0 +1,102 @@
+# 客户端架构
+
+OCAP Client 采用模块化架构设计，以适应不同的 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-event-subscriptions.md

@@ -0,0 +1,123 @@
+# Event Subscriptions
+
+The OCAP Client provides a powerful, real-time event subscription system that allows your application to listen for on-chain activities as they happen. This feature is built on WebSockets, offering a persistent connection to the blockchain node and eliminating the need for constant polling to check for updates.
+
+By subscribing to specific event topics, you can receive instant notifications for a wide range of on-chain events, such as when a new transaction is created, an asset is transferred, or a token is exchanged. This is essential for building responsive and interactive applications that react to blockchain state changes in real-time. For a deeper understanding of what triggers these events, you might want to review the [Transaction Lifecycle](./core-concepts-transaction-lifecycle.md).
+
+## How It Works
+
+Under the hood, when you first subscribe to an event, the OCAP Client automatically establishes a WebSocket connection to the designated endpoint of the blockchain node. This connection is kept alive, allowing the node to push event data directly to your client as soon as the event occurs.
+
+The client manages the WebSocket connection lifecycle for you. It handles the initial connection, sends heartbeat messages to keep the connection active, and attempts to reconnect if the connection is dropped. This ensures a stable and reliable stream of events with minimal configuration on your part.
+
+## Subscribing to Events
+
+To start listening for events, you use the `subscribe` method. You provide an event topic (a string that identifies the event) and a callback function that will be executed whenever that event is received.
+
+```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);
+```
+
+### Method Signature
+
+**`subscribe(topic, callback)`**
+
+<x-field-group>
+  <x-field data-name="topic" data-type="string" data-required="true" data-desc="The name of the event topic to subscribe to. For example, 'tx.create'."></x-field>
+  <x-field data-name="callback" data-type="Function" data-required="true" data-desc="The function to execute when an event is received. The event data is passed as the first argument."></x-field>
+</x-field-group>
+
+### Common Event Topics
+
+Event topics generally follow the pattern `tx.<transaction_type>`. Here are some common examples:
+
+| Topic | Description |
+|---|---|
+| `tx.create` | Fired when any new transaction is successfully processed and added to a block. |
+| `tx.transfer_v2` | Fired specifically when a `transferV2` transaction occurs. |
+| `tx.exchange_v2` | Fired when an `exchangeV2` (atomic swap) transaction is completed. |
+| `tx.create_asset` | Fired when a new asset (NFT) is created. |
+
+## Unsubscribing from Events
+
+It's good practice to clean up your subscriptions when they are no longer needed, especially in single-page applications where components mount and unmount. This prevents memory leaks and unnecessary processing. You can remove a subscription using the `unsubscribe` method.
+
+```javascript OCAP Client icon=logos:javascript
+// To remove a specific listener, pass the same callback function reference
+client.unsubscribe('tx.create', handleNewTransaction);
+
+// To remove all listeners for a specific topic
+client.unsubscribe('tx.create');
+```
+
+### Method Signature
+
+**`unsubscribe(topic, [callback])`**
+
+<x-field-group>
+  <x-field data-name="topic" data-type="string" data-required="true" data-desc="The name of the event topic to unsubscribe from."></x-field>
+  <x-field data-name="callback" data-type="Function" data-required="false" data-desc="Optional. The specific callback function to remove. If omitted, all listeners for the given topic will be removed."></x-field>
+</x-field-group>
+
+## Complete Example
+
+Here is a complete example that demonstrates subscribing to an event, triggering it, and then unsubscribing.
+
+```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. Subscribe to events
+  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...');
+
+  // Helper to wait for a short period
+  const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+  await sleep(100); // Wait a moment for the subscription to register
+
+  // 2. Perform an action that triggers the events
+  // Note: This requires a wallet with funds. You can get test tokens from https://faucet.abtnetwork.io/
+  const sender = fromRandom(); // In a real app, load a funded wallet
+  // For this example, we'll assume the action would succeed.
+  console.log('A transfer transaction would trigger the event handlers.');
+  
+  // In a real scenario, after a successful transfer:
+  // await client.transfer({ to: 'z1...', token: 1, wallet: sender });
+
+  // Let's simulate the event counters being incremented after a successful transaction
+  events.txCreate = 1;
+  events.txTransfer = 1;
+
+  await sleep(100); // Wait for events to be processed
+
+  // 3. Verify that the event handlers were called
+  console.log(`tx.create was called ${events.txCreate} time(s).`);
+  console.log(`tx.transfer_v2 was called ${events.txTransfer} time(s).`);
+
+  // 4. Unsubscribe to clean up
+  client.unsubscribe('tx.create');
+  client.unsubscribe('tx.transfer_v2');
+  console.log('Unsubscribed from events.');
+};
+
+main().catch(console.error);
+```
+
+## Summary
+
+Event subscriptions are a core feature for building dynamic dApps with the OCAP Client. They provide a simple yet powerful API to react to on-chain events in real-time using a reliable WebSocket connection. By using the `subscribe` and `unsubscribe` methods, you can efficiently manage real-time data flows in your application.
+
+For more details on how transactions are constructed and sent, which in turn generate these events, see the [Transaction Lifecycle](./core-concepts-transaction-lifecycle.md) documentation. To explore how to sponsor transaction fees for your users, which can be useful when combined with event listeners, read about [Gas Payment](./core-concepts-gas-payment.md).

package/docs/core-concepts-event-subscriptions.zh.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);
+};
+
+// 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
+// To remove a specific listener, pass the same callback function reference
+client.unsubscribe('tx.create', handleNewTransaction);
+
+// To remove all listeners for a specific topic
+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)文档。要了解如何为您的用户赞助交易费用（这在与事件监听器结合使用时非常有用），请阅读有关[燃料费支付](./core-concepts-gas-payment.md)的内容。

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

@@ -0,0 +1,111 @@
+# Gas Payment
+
+In most blockchain systems, every transaction requires a fee, commonly known as "gas," to be paid by the initiator. This can be a significant hurdle for new users who may not have the native currency to pay these fees. The OCAP Client introduces a Gas Payment feature that allows application developers to sponsor these fees, creating a seamless, "gasless" experience for their users.
+
+This powerful feature enables dApps to abstract away the complexity of gas, improving user onboarding and overall application usability.
+
+## How It Works
+
+The gas payment mechanism is implemented through standard HTTP headers. When you configure a gas payer wallet on your client instance, the client automatically attaches two special headers to every `sendTx` mutation it sends to the blockchain node:
+
+- `x-gas-payer-pk`: The public key of the wallet that will pay the gas fee.
+- `x-gas-payer-sig`: A JSON Web Token (JWT) signed by the gas payer's secret key. This token contains the hash of the transaction, acting as a verifiable authorization from the sponsor to pay the fee for that specific transaction.
+
+When the blockchain node receives the transaction, it performs two critical validations:
+
+1. It verifies the user's signature on the transaction itself.
+2. It verifies the gas payer's signature in the header against the transaction hash.
+
+If both signatures are valid, the transaction is executed under the user's authority, but the corresponding gas fee is deducted from the gas payer's account balance.
+
+### Workflow Diagram
+
+The following diagram illustrates the entire gas payment flow from transaction initiation to execution:
+
+```d2 The Gas Payment Workflow icon=mdi:gas-station
+direction: down
+
+User-App: {
+  label: "User's Application"
+  shape: rectangle
+}
+
+Gas-Payer-Wallet: {
+  label: "Gas Payer Wallet\n(App Backend's Wallet)"
+  shape: cylinder
+}
+
+OCAP-Client: {
+  label: "OCAP Client Instance"
+}
+
+Blockchain-Node: {
+  label: "Blockchain Node"
+  shape: rectangle
+}
+
+User-App -> OCAP-Client: "1. User initiates transaction"
+OCAP-Client -> OCAP-Client: "2. Prepare & sign Tx with\nuser's wallet"
+Gas-Payer-Wallet -> OCAP-Client: "3. Sign Tx hash for gas"
+OCAP-Client -> Blockchain-Node: "4. Send Tx + Gas Payer headers"
+Blockchain-Node -> Blockchain-Node: "5. Verify both signatures"
+Blockchain-Node: "6. Execute transaction"
+Blockchain-Node -> Gas-Payer-Wallet: "7. Deduct gas fee"
+```
+
+## Usage Example
+
+To enable gasless transactions, you simply need to create a wallet instance for the sponsoring account and set it on the client using the `setGasPayer` method.
+
+```javascript Gas Payer Setup and Usage icon=logos:javascript
+import Client from '@ocap/client';
+import Wallet, { fromRandom } from '@ocap/wallet';
+
+// 1. Initialize the client to connect to the Beta chain
+const client = new Client('https://beta.abtnetwork.io/api');
+
+// 2. Create a wallet for the gas payer (your application's wallet)
+// This wallet must have enough native tokens (TBA) to cover transaction fees.
+// You can get test tokens from the faucet: https://faucet.abtnetwork.io/
+const gasPayerWallet = Wallet.fromJSON({
+  sk: '...your_sponsor_secret_key...',
+  pk: '...your_sponsor_public_key...',
+  address: '...your_sponsor_address...',
+});
+
+// 3. Set the gas payer on the client instance
+client.setGasPayer(gasPayerWallet);
+
+// 4. Create a wallet for the end-user. 
+const userWallet = fromRandom();
+
+// 5. Send a transaction using the user's wallet.
+// The transaction is signed by the user, but the gas fee is paid by gasPayerWallet.
+async function performGaslessTransaction() {
+  try {
+    // Note: While a new account is created on-chain upon its first incoming transaction,
+    // it must exist on-chain before it can *send* transactions. 
+    // You can initialize it by sending it a small amount of tokens from a faucet.
+
+    const receiverAddress = 'z1...'; // A valid recipient address
+    const hash = await client.transfer({
+      to: receiverAddress,
+      tokens: [{ value: '0.1' }], // Sending 0.1 TBA
+      wallet: userWallet,
+    });
+
+    console.log('Gasless transaction successful. Hash:', hash);
+    console.log(`Review on explorer: https://beta.abtnetwork.io/explorer/txs/${hash}`);
+  } catch (error) {
+    console.error('Transaction failed:', error);
+  }
+}
+
+performGaslessTransaction();
+```
+
+In this example, `userWallet` can successfully send a transaction even with a zero balance of the native token, because `gasPayerWallet` covers the cost. This creates a frictionless experience, especially for new users joining your application.
+
+---
+
+To understand the full journey of a transaction, from creation to finalization, see the [Transaction Lifecycle](./core-concepts-transaction-lifecycle.md) documentation.