@ocap/client 1.25.3 → 1.25.5

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 发送 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 发送 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 发送 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 发送 CreateAssetTx icon=logos:javascript
+const [txHash, assetAddress] = await client.createAsset({
+  moniker: '我的第一个 NFT',
+  data: {
+    typeUrl: 'json',
+    value: { name: '数字收藏品', description: '一个独特的物品。' },
+  },
+  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="资产的新别名。"></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 发送 UpdateAssetTx icon=logos:javascript
+const txHash = await client.updateAsset({
+  address: 'z3g...',
+  moniker: '更新后的 NFT 名称',
+  data: {
+    typeUrl: 'json',
+    value: { name: '更新后的收藏品', description: '现在有更多功能！' },
+  },
+  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 发送 CreateFactoryTx icon=logos:javascript
+const factoryConfig = {
+  name: '票务工厂',
+  description: '铸造活动门票',
+  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 发送 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 发送 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 发送 CreateTokenFactoryTx icon=logos:javascript
+const [txHash, factoryAddress] = await client.createTokenFactory({
+  feeRate: 100, // 1%
+  curve: { fixedPrice: '1' }, // 每个新代币 1 个原生代币
+  token: {
+    name: '我的社区代币',
+    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 发送 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 发送 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 发送 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 发送 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: '支付服务费用',
+  wallet: senderWallet,
+});
+console.log('转账交易哈希:', txHash);
+```
+
+### prepareExchange
+
+准备原子交换交易的发送方部分。它会对发送方的报价进行签名，并返回一个可以传递给接收方的交易对象。
+
+**参数**
+
+<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 执行原子交换 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 发送 StakeTx icon=logos:javascript
+const [txHash, stakeAddress] = await client.stake({
+  to: 'z1v...',
+  tokens: [{ address: 'z2t...', value: 5000 }],
+  message: '为验证者奖励而质押',
+  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 发送 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 发送 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 发送 SlashStakeTx icon=logos:javascript
+const txHash = await client.slashStake({
+  from: 'z6s...',
+  reason: '验证者停机',
+  tokens: [{ address: 'z2t...', value: 500 }],
+  wallet: slasherWallet,
+});
+console.log('惩罚质押交易哈希:', txHash);
+```

package/docs/api-reference.ja.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>