# 高级 API
交易助手是 OCAP Client 内置的高级函数，它抽象了创建和签署常见交易的复杂性。您无需手动构建交易对象，而是可以使用这些便捷方法来处理创建资产、转移通证、质押和执行原子交换等工作流。这些助手可确保交易结构的正确性，并显著简化开发过程。
如需更深入地了解底层交易生命周期，请参阅[核心概念：交易生命周期](./core-concepts-transaction-lifecycle.md)。
---
## 账户管理
### migrateAccount
将账户的所有权迁移到新的密钥对。这对于密钥轮换或账户恢复非常有用。
**参数**
**返回值**
**示例**
```javascript Send an AccountMigrateTx icon=logos:javascript
const txHash = await client.migrateAccount({
from: oldWallet,
to: newWallet,
});
console.log('Migration transaction hash:', txHash);
```
### delegate
授权另一个账户（受托人）代表委托人发送特定类型的交易。这是一项强大的功能，可用于创建安全的沙盒化权限。
**参数**
**返回值**
**示例**
```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('Delegation tx hash:', txHash);
console.log('Delegate address:', delegateAddress);
```
### revokeDelegate
撤销先前授予受托人的权限。
**参数**
**返回值**
**示例**
```javascript Send a RevokeDelegateTx icon=logos:javascript
const txHash = await client.revokeDelegate({
from: userWallet,
to: appWallet,
privileges: ['fg:t:transfer_v2'],
});
console.log('Revocation tx hash:', txHash);
```
---
## 资产 (NFT) 管理
### createAsset
在区块链上创建一个新资产（非同质化通证）。
**参数**
**返回值**
**示例**
```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('Create asset tx hash:', txHash);
console.log('New asset address:', assetAddress);
```
### updateAsset
更新现有非只读资产的 `moniker` 和 `data` 字段。
**参数**
**返回值**
**示例**
```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('Update asset tx hash:', txHash);
```
### createAssetFactory
创建一个资产工厂，该工厂可作为模板，用于铸造具有一致结构的多个新资产。
**参数**
**返回值**
**示例**
```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('Create factory tx hash:', txHash);
console.log('New factory address:', factoryAddress);
```
### acquireAsset
从现有资产工厂获取（铸造）一个新资产。此操作通常由将拥有该资产的最终用户发起。
**参数**
**返回值**
**示例**
```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('Acquire asset tx hash:', txHash);
```
### mintAsset
这是与 `acquireAsset` 对应的发行方操作。它允许受信任的发行人从工厂铸造资产并将其分配给指定的所有者。
**参数**
**返回值**
**示例**
```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('Mint asset tx hash:', txHash);
```
---
## 通证管理
### createTokenFactory
创建一个新工厂，用于铸造和销毁特定的可替代通证，通常基于联合曲线定价模型。
**参数**
要创建的通证的配置。这包括 `name`、`symbol`、`decimal` 和 `maxTotalSupply` 等属性。
**返回值**
**示例**
```javascript Send a CreateTokenFactoryTx icon=logos:javascript
const [txHash, factoryAddress] = await client.createTokenFactory({
feeRate: 100, // 1%
curve: { fixedPrice: '1' }, // 1 个原生通证兑换 1 个新通证
token: {
name: 'My Community Token',
symbol: 'MCT',
decimal: 18,
maxTotalSupply: '1000000',
},
wallet: creatorWallet,
});
console.log('Create token factory tx hash:', txHash);
console.log('New token factory address:', factoryAddress);
```
### updateTokenFactory
更新现有通证工厂的 `feeRate` 和 `data`。
**参数**
**返回值**
**示例**
```javascript Send an UpdateTokenFactoryTx icon=logos:javascript
const txHash = await client.updateTokenFactory({
address: 'z2f...',
feeRate: 50, // 0.5%
wallet: ownerWallet,
});
console.log('Update token factory tx hash:', txHash);
```
### mintToken
从通证工厂铸造新通证，以换取储备通证（通常是原生链通证）。成本由工厂的联合曲线决定。
**参数**
**返回值**
**示例**
```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('Mint token tx hash:', txHash);
```
### burnToken
在工厂销毁现有通证，以换取底层的储备通证。收到的储备通证数量由工厂的联合曲线决定。
**参数**
**返回值**
**示例**
```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('Burn token tx hash:', txHash);
```
---
## 转账与交换
### transfer
在单笔交易中将原生通证、自定义可替代通证和/或资产（NFT）转移到另一个账户。
**参数**
**返回值**
**示例**
```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('Transfer tx hash:', txHash);
```
### prepareExchange
准备原子交换（exchange）交易的发送方部分。它会对发送方的报价进行签名，并返回一个可以传递给接收方的交易对象。
**参数**
**返回值**
### finalizeExchange
完成原子交换的接收方部分。它接收来自 `prepareExchange` 的部分签名交易，添加接收方的签名，并返回完全签名的交易对象。
**参数**
**返回值**
### exchange
将完全签名的交换交易发送到区块链。在 `finalizeExchange` 完成后，任何一方都可以调用此函数。
**参数**
**返回值**
**示例（完整交换流程）**
```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('Exchange tx hash:', txHash);
```
---
## 质押
### stake
将通证和/或资产质押到接收方地址。质押会锁定资源，通常用于换取奖励或提供安全性。
**参数**
**返回值**
**示例**
```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('Stake tx hash:', txHash);
console.log('New stake address:', stakeAddress);
```
### revokeStake
撤销先前质押的通证和/或资产，启动将其返还给所有者的流程。请注意，在资产可以被认领之前，可能存在一个解绑期。
**参数**
**返回值**
**示例**
```javascript Send a RevokeStakeTx icon=logos:javascript
const txHash = await client.revokeStake({
from: 'z6s...',
tokens: [{ address: 'z2t...', value: 1000 }],
wallet: userWallet,
});
console.log('Revoke stake tx hash:', txHash);
```
### claimStake
从已成功撤销并度过解绑期的质押中认领项目。
**参数**
**返回值**
**示例**
```javascript Send a ClaimStakeTx icon=logos:javascript
const revokeTxHash = '0x123...abc';
const txHash = await client.claimStake({
from: 'z6s...',
evidence: revokeTxHash,
wallet: userWallet,
});
console.log('Claim stake tx hash:', txHash);
```
### slashStake
允许指定的削减者惩罚质押，通常是针对不当行为。被削减的资产将被转移到指定的金库地址。
**参数**
**返回值**
**示例**
```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('Slash stake tx hash:', txHash);
```