@ocap/client 1.25.3 → 1.25.4

package/docs/api-reference-transaction-helpers.zh.md

@@ -0,0 +1,649 @@
+# 高级 API
+
+交易助手是 OCAP Client 内置的高级函数，它抽象了创建和签署常见交易的复杂性。您可以使用这些便捷的方法来处理创建资产、转移通证、质押和执行原子交换等工作流程，而无需手动构建交易对象。这些助手确保了交易结构的正确性，并显著简化了开发过程。
+
+要更深入地了解底层交易生命周期，请参阅[核心概念：交易生命周期](./core-concepts-transaction-lifecycle.md)。
+
+---
+
+## 账户管理
+
+### migrateAccount
+
+将账户的所有权迁移到新的密钥对。这对于密钥轮换或账户恢复很有用。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="from" data-type="WalletObject" data-required="true" data-desc="要从中迁移的账户的钱包对象。"></x-field>
+  <x-field data-name="to" data-type="WalletObject" data-required="true" data-desc="要迁移到的账户的钱包对象。"></x-field>
+</x-field-group>
+
+**返回**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="已提交交易的哈希值。"></x-field>
+
+**示例**
+
+```javascript Send an AccountMigrateTx icon=logos:javascript
+const txHash = await client.migrateAccount({
+  from: oldWallet,
+  to: newWallet,
+});
+console.log('迁移交易哈希:', txHash);
+```
+
+### delegate
+
+授权另一个账户（受托人）代表委托人发送特定类型的交易。这是一个用于创建安全的沙盒权限的强大功能。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="from" data-type="WalletObject" data-required="true" data-desc="授予权限的委托人的钱包。"></x-field>
+  <x-field data-name="to" data-type="WalletObject" data-required="true" data-desc="接收权限的受托人的钱包。"></x-field>
+  <x-field data-name="privileges" data-type="array" data-required="true" data-desc="一个指定允许操作的权限对象数组。">
+    <x-field data-name="typeUrl" data-type="string" data-required="true" data-desc="被允许的交易的类型 URL（例如，'fg:t:transfer_v2'）。"></x-field>
+    <x-field data-name="limit" data-type="object" data-required="false" data-desc="对委托的可选限制。">
+      <x-field data-name="tokens" data-type="array" data-desc="对特定可替代通证的限制。"></x-field>
+      <x-field data-name="assets" data-type="array" data-desc="对特定资产 (NFT) 的限制。"></x-field>
+    </x-field>
+  </x-field>
+</x-field-group>
+
+**返回**
+
+<x-field data-name="result" data-type="Promise<[string, string]>" data-desc="一个包含交易哈希和新创建的委托地址的数组。"></x-field>
+
+**示例**
+
+```javascript Send a DelegateTx icon=logos:javascript
+const [txHash, delegateAddress] = await client.delegate({
+  from: userWallet,
+  to: appWallet,
+  privileges: [
+    {
+      typeUrl: 'fg:t:transfer_v2',
+    },
+  ],
+});
+console.log('委托交易哈希:', txHash);
+console.log('委托地址:', delegateAddress);
+```
+
+### revokeDelegate
+
+从受托人处撤销先前授予的权限。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="from" data-type="WalletObject" data-required="true" data-desc="委托人的钱包。"></x-field>
+  <x-field data-name="to" data-type="WalletObject" data-required="true" data-desc="受托人的钱包。"></x-field>
+  <x-field data-name="privileges" data-type="array" data-required="true" data-desc="一个指定要撤销权限的权限对象数组。">
+     <x-field data-name="typeUrl" data-type="string" data-required="true" data-desc="要撤销的交易的类型 URL（例如，'fg:t:transfer_v2'）。"></x-field>
+  </x-field>
+</x-field-group>
+
+**返回**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="已提交交易的哈希值。"></x-field>
+
+**示例**
+
+```javascript Send a RevokeDelegateTx icon=logos:javascript
+const txHash = await client.revokeDelegate({
+  from: userWallet,
+  to: appWallet,
+  privileges: ['fg:t:transfer_v2'],
+});
+console.log('撤销委托交易哈希:', txHash);
+```
+
+---
+
+## 资产 (NFT) 管理
+
+### createAsset
+
+在区块链上创建一个新资产（非同质化代币）。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="moniker" data-type="string" data-required="true" data-desc="资产的简短、人类可读的名称。"></x-field>
+  <x-field data-name="data" data-type="object" data-required="true" data-desc="包含资产元数据的 JSON 对象。"></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="资产初始所有者的钱包。"></x-field>
+  <x-field data-name="parent" data-type="string" data-required="false" data-desc="父资产的地址，用于建立层级链接。"></x-field>
+  <x-field data-name="ttl" data-type="number" data-required="false" data-default="0" data-desc="首次消费后的存活时间（秒）。"></x-field>
+  <x-field data-name="readonly" data-type="boolean" data-required="false" data-default="false" data-desc="如果为 true，资产在创建后无法更新。"></x-field>
+  <x-field data-name="transferrable" data-type="boolean" data-required="false" data-default="true" data-desc="如果为 true，资产可以转移到另一个账户。"></x-field>
+  <x-field data-name="display" data-type="object" data-required="false" data-desc="用于资产显示元数据的对象。"></x-field>
+  <x-field data-name="endpoint" data-type="object" data-required="false" data-desc="用于资产端点元数据的对象。"></x-field>
+  <x-field data-name="tags" data-type="string[]" data-required="false" data-desc="用于分类的标签数组。"></x-field>
+  <x-field data-name="delegator" data-type="string" data-required="false" data-desc="委托人的地址，如果交易由受托人发送。"></x-field>
+</x-field-group>
+
+**返回**
+
+<x-field data-name="result" data-type="Promise<[string, string]>" data-desc="一个包含交易哈希和新创建资产地址的数组。"></x-field>
+
+**示例**
+
+```javascript Send a CreateAssetTx icon=logos:javascript
+const [txHash, assetAddress] = await client.createAsset({
+  moniker: 'My First NFT',
+  data: {
+    typeUrl: 'json',
+    value: { name: 'Digital Collectible', description: 'A unique item.' },
+  },
+  wallet: userWallet,
+});
+console.log('创建资产交易哈希:', txHash);
+console.log('新资产地址:', assetAddress);
+```
+
+### updateAsset
+
+更新现有非只读资产的 `moniker` 和 `data` 字段。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="address" data-type="string" data-required="true" data-desc="要更新的资产地址。"></x-field>
+  <x-field data-name="moniker" data-type="string" data-required="true" data-desc="资产的新 moniker。"></x-field>
+  <x-field data-name="data" data-type="object" data-required="true" data-desc="资产的新 JSON 数据对象。"></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="资产当前所有者的钱包。"></x-field>
+</x-field-group>
+
+**返回**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="已提交交易的哈希值。"></x-field>
+
+**示例**
+
+```javascript Send an UpdateAssetTx icon=logos:javascript
+const txHash = await client.updateAsset({
+  address: 'z3g...',
+  moniker: 'Updated NFT Name',
+  data: {
+    typeUrl: 'json',
+    value: { name: 'Updated Collectible', description: 'Now with more features!' },
+  },
+  wallet: userWallet,
+});
+console.log('更新资产交易哈希:', txHash);
+```
+
+### createAssetFactory
+
+创建一个资产工厂，它作为模板用于铸造具有一致结构的多个新资产。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="factory" data-type="object" data-required="true" data-desc="包含工厂配置的对象。">
+    <x-field data-name="name" data-type="string" data-required="true" data-desc="工厂的名称。"></x-field>
+    <x-field data-name="description" data-type="string" data-required="true" data-desc="工厂的描述。"></x-field>
+    <x-field data-name="limit" data-type="number" data-required="false" data-default="0" data-desc="可以铸造的最大资产数量（0 表示无限制）。"></x-field>
+    <x-field data-name="trustedIssuers" data-type="string[]" data-required="false" data-desc="允许从此工厂铸造的钱包地址列表。"></x-field>
+    <x-field data-name="input" data-type="object" data-required="true" data-desc="定义铸造所需的输入。"></x-field>
+    <x-field data-name="output" data-type="object" data-required="true" data-desc="定义铸造资产的结构，通常使用模板。"></x-field>
+  </x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="拥有该工厂的钱包。"></x-field>
+</x-field-group>
+
+**返回**
+
+<x-field data-name="result" data-type="Promise<[string, string]>" data-desc="一个包含交易哈希和新创建工厂地址的数组。"></x-field>
+
+**示例**
+
+```javascript Send a CreateFactoryTx icon=logos:javascript
+const factoryConfig = {
+  name: 'Ticket Factory',
+  description: 'Mints event tickets',
+  limit: 1000,
+  input: { ... },
+  output: { ... },
+};
+
+const [txHash, factoryAddress] = await client.createAssetFactory({
+  factory: factoryConfig,
+  wallet: eventCreatorWallet,
+});
+console.log('创建工厂交易哈希:', txHash);
+console.log('新工厂地址:', factoryAddress);
+```
+
+### acquireAsset
+
+从现有资产工厂获取（铸造）一个新资产。这通常由将拥有该资产的最终用户发起。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="itx" data-type="AcquireAssetV2Tx" data-required="true" data-desc="内部交易对象，通常使用像 `preMintAsset` 这样的辅助函数准备。"></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="获取资产的用户的钱包。"></x-field>
+  <x-field data-name="delegator" data-type="string" data-required="false" data-desc="委托人的地址（如果适用）。"></x-field>
+</x-field-group>
+
+**返回**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="已提交交易的哈希值。"></x-field>
+
+**示例**
+
+```javascript Send an AcquireAssetV2Tx icon=logos:javascript
+// 首先，准备铸造交易（例如，在服务器上）
+const itx = await client.preMintAsset({
+  factory: factoryAddress,
+  owner: userWallet.address,
+  wallet: issuerWallet,
+});
+
+// 然后，用户发送交易
+const txHash = await client.acquireAsset({ itx, wallet: userWallet });
+console.log('获取资产交易哈希:', txHash);
+```
+
+### mintAsset
+
+这是 `acquireAsset` 的发行方对应操作。它允许受信任的发行方从工厂铸造资产并将其分配给指定的所有者。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="itx" data-type="MintAssetTx" data-required="true" data-desc="内部交易对象，通常使用 `preMintAsset` 准备。"></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="受信任发行方的钱包。"></x-field>
+</x-field-group>
+
+**返回**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="已提交交易的哈希值。"></x-field>
+
+**示例**
+
+```javascript Send a MintAssetTx icon=logos:javascript
+const itx = await client.preMintAsset({
+  factory: factoryAddress,
+  owner: userWallet.address,
+  wallet: issuerWallet,
+});
+
+const txHash = await client.mintAsset({ itx, wallet: issuerWallet });
+console.log('铸造资产交易哈希:', txHash);
+```
+
+---
+
+## 通证管理
+
+### createTokenFactory
+
+创建一个用于铸造和销毁特定可替代通证的新工厂，通常基于联合曲线定价模型。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="feeRate" data-type="number" data-required="false" data-default="0" data-desc="铸造和销毁操作的费率。"></x-field>
+  <x-field data-name="curve" data-type="object" data-required="true" data-desc="用于定价的联合曲线配置。"></x-field>
+  <x-field data-name="token" data-type="object" data-required="true">
+    <x-field-desc markdown>要创建的通证的配置。这包括 `name`、`symbol`、`decimal` 和 `maxTotalSupply` 等属性。</x-field-desc>
+  </x-field>
+  <x-field data-name="data" data-type="object" data-required="false" data-desc="通证工厂的可选元数据。"></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="工厂所有者的钱包。"></x-field>
+</x-field-group>
+
+**返回**
+
+<x-field data-name="result" data-type="Promise<[string, string]>" data-desc="一个包含交易哈希和新创建的通证工厂地址的数组。"></x-field>
+
+**示例**
+
+```javascript Send a CreateTokenFactoryTx icon=logos:javascript
+const [txHash, factoryAddress] = await client.createTokenFactory({
+  feeRate: 100, // 1%
+  curve: { fixedPrice: '1' }, // 每个新通证 1 个原生通证
+  token: {
+    name: 'My Community Token',
+    symbol: 'MCT',
+    decimal: 18,
+    maxTotalSupply: '1000000',
+  },
+  wallet: creatorWallet,
+});
+console.log('创建通证工厂交易哈希:', txHash);
+console.log('新通证工厂地址:', factoryAddress);
+```
+
+### updateTokenFactory
+
+更新现有通证工厂的 `feeRate` 和 `data`。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="address" data-type="string" data-required="true" data-desc="要更新的通证工厂地址。"></x-field>
+  <x-field data-name="feeRate" data-type="number" data-required="false" data-desc="新的铸造和销毁费率。"></x-field>
+  <x-field data-name="data" data-type="object" data-required="false" data-desc="通证工厂的新元数据。"></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="工厂所有者的钱包。"></x-field>
+</x-field-group>
+
+**返回**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="已提交交易的哈希值。"></x-field>
+
+**示例**
+
+```javascript Send an UpdateTokenFactoryTx icon=logos:javascript
+const txHash = await client.updateTokenFactory({
+  address: 'z2f...',
+  feeRate: 50, // 0.5%
+  wallet: ownerWallet,
+});
+console.log('更新通证工厂交易哈希:', txHash);
+```
+
+### mintToken
+
+从通证工厂铸造新通证，以换取储备通证（通常是原生链通证）。成本由工厂的联合曲线决定。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="tokenFactory" data-type="string" data-required="true" data-desc="通证工厂的地址。"></x-field>
+  <x-field data-name="amount" data-type="number" data-required="true" data-desc="要铸造的新通证数量。"></x-field>
+  <x-field data-name="receiver" data-type="string" data-required="true" data-desc="将接收新铸造通证的地址。"></x-field>
+  <x-field data-name="maxReserve" data-type="number" data-required="true" data-desc="用户愿意支付的储备通证的最大数量。这起到滑点保护的作用。"></x-field>
+  <x-field data-name="data" data-type="object" data-required="false" data-desc="交易的可选元数据。"></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="发起铸造的钱包。"></x-field>
+</x-field-group>
+
+**返回**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="已提交交易的哈希值。"></x-field>
+
+**示例**
+
+```javascript Send a MintTokenTx icon=logos:javascript
+const txHash = await client.mintToken({
+  tokenFactory: 'z2f...',
+  amount: 100,
+  receiver: userWallet.address,
+  maxReserve: 105, // 愿意最多支付 105 个原生通证
+  wallet: userWallet,
+});
+console.log('铸造通证交易哈希:', txHash);
+```
+
+### burnToken
+
+在工厂销毁现有通证，以换取底层的储备通证。收到的储备通证数量由工厂的联合曲线决定。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="tokenFactory" data-type="string" data-required="true" data-desc="通证工厂的地址。"></x-field>
+  <x-field data-name="amount" data-type="number" data-required="true" data-desc="要销毁的通证数量。"></x-field>
+  <x-field data-name="receiver" data-type="string" data-required="true" data-desc="将接收储备通证的地址。"></x-field>
+  <x-field data-name="minReserve" data-type="number" data-required="true" data-desc="用户期望收到的储备通证的最小数量。这起到滑点保护的作用。"></x-field>
+  <x-field data-name="data" data-type="object" data-required="false" data-desc="交易的可选元数据。"></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="发起销毁的钱包。"></x-field>
+</x-field-group>
+
+**返回**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="已提交交易的哈希值。"></x-field>
+
+**示例**
+
+```javascript Send a BurnTokenTx icon=logos:javascript
+const txHash = await client.burnToken({
+  tokenFactory: 'z2f...',
+  amount: 50,
+  receiver: userWallet.address,
+  minReserve: 48, // 期望至少收到 48 个原生通证
+  wallet: userWallet,
+});
+console.log('销毁通证交易哈希:', txHash);
+```
+
+---
+
+## 转账与交换
+
+### transfer
+
+在单笔交易中将原生通证、自定义可替代通证和/或资产（NFT）转移到另一个账户。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="to" data-type="string" data-required="true" data-desc="接收方的地址。"></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="发送方的钱包。"></x-field>
+  <x-field data-name="token" data-type="number" data-required="false" data-default="0" data-desc="要转移的链原生通证的数量。"></x-field>
+  <x-field data-name="assets" data-type="string[]" data-required="false" data-desc="要转移的资产地址（NFT）数组。"></x-field>
+  <x-field data-name="tokens" data-type="object[]" data-required="false" data-desc="要转移的自定义可替代通证对象数组。">
+    <x-field data-name="address" data-type="string" data-required="true" data-desc="自定义通证合约的地址。"></x-field>
+    <x-field data-name="value" data-type="number" data-required="true" data-desc="要转移的自定义通证数量。"></x-field>
+  </x-field>
+  <x-field data-name="memo" data-type="string" data-required="false" data-desc="交易的可选备注。"></x-field>
+  <x-field data-name="delegator" data-type="string" data-required="false" data-desc="委托人的地址（如果适用）。"></x-field>
+</x-field-group>
+
+**返回**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="已提交交易的哈希值。"></x-field>
+
+**示例**
+
+```javascript Send a TransferV2Tx icon=logos:javascript
+const txHash = await client.transfer({
+  to: 'z1sb...',
+  token: 1.5, // 1.5 个原生链通证
+  assets: ['z3g...'], // 一个 NFT
+  tokens: [{ address: 'z2t...', value: 100 }], // 100 个自定义通证
+  memo: 'Payment for services',
+  wallet: senderWallet,
+});
+console.log('转账交易哈希:', txHash);
+```
+
+### prepareExchange
+
+准备原子交换（exchange）交易的发送方部分。它对发送方的报价进行签名，并返回一个可以传递给接收方的交易对象。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="receiver" data-type="string" data-required="true" data-desc="交换中另一方的地址。"></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="发出报价的用户的钱包。"></x-field>
+  <x-field data-name="offerToken" data-type="number" data-required="false" data-desc="报价的原生通证数量。"></x-field>
+  <x-field data-name="offerAssets" data-type="string[]" data-required="false" data-desc="报价的资产地址数组。"></x-field>
+  <x-field data-name="offerTokens" data-type="object[]" data-required="false" data-desc="报价的自定义可替代通证数组。"></x-field>
+  <x-field data-name="demandToken" data-type="number" data-required="false" data-desc="要求的回报原生通证数量。"></x-field>
+  <x-field data-name="demandAssets" data-type="string[]" data-required="false" data-desc="要求的回报资产地址数组。"></x-field>
+  <x-field data-name="demandTokens" data-type="object[]" data-required="false" data-desc="要求的回报自定义可替代通证数组。"></x-field>
+  <x-field data-name="memo" data-type="string" data-required="false" data-desc="交易的可选备注。"></x-field>
+</x-field-group>
+
+**返回**
+
+<x-field data-name="transactionObject" data-type="Promise<object>" data-desc="部分签名的交易对象。"></x-field>
+
+### finalizeExchange
+
+最终确定原子交换的接收方部分。它接收来自 `prepareExchange` 的部分签名交易，添加接收方的签名，并返回完全签名的交易对象。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="tx" data-type="object" data-required="true" data-desc="从 `prepareExchange` 返回的交易对象。"></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="接受报价的用户的钱包。"></x-field>
+  <x-field data-name="data" data-type="object" data-required="false" data-desc="多重签名中的额外数据。"></x-field>
+</x-field-group>
+
+**返回**
+
+<x-field data-name="transactionObject" data-type="Promise<object>" data-desc="完全签名的多重签名交易对象。"></x-field>
+
+### exchange
+
+将完全签名的交换交易发送到区块链。在 `finalizeExchange` 完成后，任何一方都可以调用此函数。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="tx" data-type="object" data-required="true" data-desc="从 `finalizeExchange` 返回的交易对象。"></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="提交交易的用户的钱包。"></x-field>
+</x-field-group>
+
+**返回**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="已提交交易的哈希值。"></x-field>
+
+**示例 (完整的交换流程)**
+
+```javascript Perform an atomic swap icon=logos:javascript
+// 1. 报价方准备交易
+const offerTx = await client.prepareExchange({
+  receiver: receiverWallet.address,
+  offerAssets: ['z3g...'], // 报价一个 NFT
+  demandToken: 10, // 要求 10 个原生通证
+  wallet: offererWallet,
+});
+
+// 2. 接收方最终确定交易
+const finalTx = await client.finalizeExchange({
+  tx: offerTx,
+  wallet: receiverWallet,
+});
+
+// 3. 任何一方都可以发送最终确定的交易
+const txHash = await client.exchange({ tx: finalTx, wallet: offererWallet });
+console.log('交换交易哈希:', txHash);
+```
+
+---
+
+## 质押
+
+### stake
+
+将通证和/或资产质押到一个接收地址。质押会锁定资源，通常用于换取奖励或提供安全性。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="to" data-type="string" data-required="true" data-desc="质押接收方的地址。"></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="质押者的钱包。"></x-field>
+  <x-field data-name="assets" data-type="string[]" data-required="false" data-desc="要质押的资产地址数组。"></x-field>
+  <x-field data-name="tokens" data-type="object[]" data-required="false" data-desc="要质押的可替代通证对象数组。"></x-field>
+  <x-field data-name="locked" data-type="boolean" data-required="false" data-default="false" data-desc="创建时质押是否被锁定。"></x-field>
+  <x-field data-name="slashers" data-type="string[]" data-required="false" data-desc="允许削减此质押的地址列表。"></x-field>
+  <x-field data-name="message" data-type="string" data-required="false" data-desc="质押的可选备注。"></x-field>
+</x-field-group>
+
+**返回**
+
+<x-field data-name="result" data-type="Promise<[string, string]>" data-desc="一个包含交易哈希和新创建的质押地址的数组。"></x-field>
+
+**示例**
+
+```javascript Send a StakeTx icon=logos:javascript
+const [txHash, stakeAddress] = await client.stake({
+  to: 'z1v...',
+  tokens: [{ address: 'z2t...', value: 5000 }],
+  message: 'Staking for validator rewards',
+  wallet: userWallet,
+});
+console.log('质押交易哈希:', txHash);
+console.log('新质押地址:', stakeAddress);
+```
+
+### revokeStake
+
+撤销先前质押的通证和/或资产，启动将其返还给所有者的过程。请注意，在资产可以被认领之前可能存在一个解绑期。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="from" data-type="string" data-required="true" data-desc="要从中撤销的质押地址。"></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="质押所有者的钱包。"></x-field>
+  <x-field data-name="assets" data-type="string[]" data-required="false" data-desc="要撤销的资产地址数组。"></x-field>
+  <x-field data-name="tokens" data-type="object[]" data-required="false" data-desc="要撤销的可替代通证对象数组。"></x-field>
+</x-field-group>
+
+**返回**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="已提交交易的哈希值。"></x-field>
+
+**示例**
+
+```javascript Send a RevokeStakeTx icon=logos:javascript
+const txHash = await client.revokeStake({
+  from: 'z6s...',
+  tokens: [{ address: 'z2t...', value: 1000 }],
+  wallet: userWallet,
+});
+console.log('撤销质押交易哈希:', txHash);
+```
+
+### claimStake
+
+从已成功撤销并度过解绑期的质押中认领项目。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="from" data-type="string" data-required="true" data-desc="要从中认领的质押地址。"></x-field>
+  <x-field data-name="evidence" data-type="string" data-required="true" data-desc="`revokeStake` 交易的交易哈希。"></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="质押所有者的钱包。"></x-field>
+</x-field-group>
+
+**返回**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="已提交交易的哈希值。"></x-field>
+
+**示例**
+
+```javascript Send a ClaimStakeTx icon=logos:javascript
+const revokeTxHash = '0x123...abc';
+const txHash = await client.claimStake({
+  from: 'z6s...',
+  evidence: revokeTxHash,
+  wallet: userWallet,
+});
+console.log('认领质押交易哈希:', txHash);
+```
+
+### slashStake
+
+允许指定的削减者对质押进行惩罚，通常是因为不当行为。被削减的资产将转移到指定的金库地址。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="from" data-type="string" data-required="true" data-desc="要削减的质押地址。"></x-field>
+  <x-field data-name="reason" data-type="string" data-required="true" data-desc="解释削减原因的消息。"></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="指定削减者的钱包。"></x-field>
+  <x-field data-name="assets" data-type="string[]" data-required="false" data-desc="要削减的资产地址数组。"></x-field>
+  <x-field data-name="tokens" data-type="object[]" data-required="false" data-desc="要削减的可替代通证对象数组。"></x-field>
+</x-field-group>
+
+**返回**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="已提交交易的哈希值。"></x-field>
+
+**示例**
+
+```javascript Send a SlashStakeTx icon=logos:javascript
+const txHash = await client.slashStake({
+  from: 'z6s...',
+  reason: 'Validator downtime',
+  tokens: [{ address: 'z2t...', value: 500 }],
+  wallet: slasherWallet,
+});
+console.log('削减质押交易哈希:', txHash);
+```

package/docs/api-reference.md

@@ -0,0 +1,23 @@
+# API Reference
+
+Welcome to the OCAP Client API Reference. This section provides a comprehensive and searchable reference for all available classes, methods, and data types. Whether you're looking for the specifics of a GraphQL method, the parameters for a transaction helper, or the structure of a response object, you'll find the detailed information you need here.
+
+Explore the following sections to dive deeper into the client's capabilities:
+
+<x-cards data-columns="2">
+  <x-card data-title="Helper Methods" data-icon="lucide:function-square" data-href="/api-reference/client-methods">
+    Detailed documentation for core client helper methods, such as `getType`, `decodeTx`, and `fromUnitToToken`.
+  </x-card>
+  <x-card data-title="Query & Mutation Methods" data-icon="lucide:database-zap" data-href="/api-reference/query-mutation-methods">
+    A complete list of all available GraphQL query and mutation methods for reading from and writing to the chain.
+  </x-card>
+  <x-card data-title="High-level API" data-icon="lucide:zap" data-href="/api-reference/transaction-helpers">
+    Reference for high-level functions that simplify common workflows like transferring tokens and managing assets.
+  </x-card>
+  <x-card data-title="Low-level API" data-icon="lucide:cpu" data-href="/api-reference/low-level-api">
+    Learn how to manually construct, sign, and send transactions for full control over the transaction lifecycle.
+  </x-card>
+  <x-card data-title="Data Types" data-icon="lucide:box" data-href="/api-reference/data-types">
+    Defines all the custom data structures, input parameters, and response objects used throughout the client API.
+  </x-card>
+</x-cards>