高级 API | ArcBlock

交易助手是 OCAP Client 内置的高级函数，它抽象了创建和签署常见交易的复杂性。您无需手动构建交易对象，而是可以使用这些便捷方法来处理创建资产、转移通证、质押和执行原子交换等工作流。这些助手可确保交易结构的正确性，并显著简化开发过程。

如需更深入地了解底层交易生命周期，请参阅核心概念：交易生命周期。

账户管理

migrateAccount

将账户的所有权迁移到新的密钥对。这对于密钥轮换或账户恢复非常有用。

参数

from WalletObject (required) — 要迁出账户的钱包对象。
to WalletObject (required) — 要迁入账户的钱包对象。

返回值

transactionHash Promise<string> — 已提交交易的哈希值。

示例

Send an AccountMigrateTx

const txHash = await client.migrateAccount({
  from: oldWallet,
  to: newWallet,
});
console.log('Migration transaction hash:', txHash);

delegate

授权另一个账户（受托人）代表委托人发送特定类型的交易。这是一项强大的功能，可用于创建安全的沙盒化权限。

参数

from WalletObject (required) — 委托人的钱包，即授予权限的一方。
to WalletObject (required) — 受托人的钱包，即接收权限的一方。
privileges array (required) — 一个权限对象数组，用于指定允许的操作。
- typeUrl string (required) — 被许可交易的类型 URL（例如 'fg:t'）。
- limit object — 对委托的可选限制。
  - tokens array — 对特定可替代通证的限制。
  - assets array — 对特定资产 (NFT) 的限制。

返回值

result Promise<[string, string]> — 一个包含交易哈希和新创建的委托地址的数组。

示例

Send a DelegateTx

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

撤销先前授予受托人的权限。

参数

from WalletObject (required) — 委托人的钱包。
to WalletObject (required) — 受托人的钱包。
privileges array (required) — 一个权限对象数组，用于指定要撤销的权限。
- typeUrl string (required) — 要撤销的交易的类型 URL（例如 'fg:t'）。

返回值

transactionHash Promise<string> — 已提交交易的哈希值。

示例

Send a RevokeDelegateTx

const txHash = await client.revokeDelegate({
  from: userWallet,
  to: appWallet,
  privileges: ['fg:t:transfer_v2'],
});
console.log('Revocation tx hash:', txHash);

资产 (NFT) 管理

createAsset

在区块链上创建一个新资产（非同质化通证）。

参数

moniker string (required) — 资产的简短、人类可读的名称。
data object (required) — 包含资产元数据的 JSON 对象。
wallet WalletObject (required) — 资产初始所有者的钱包。
parent string — 父资产的地址，用于建立层级链接。
ttl number (default: 0) — 首次消费后的存活时间（秒）。
readonly boolean (default: false) — 如果为 true，资产在创建后无法更新。
transferrable boolean (default: true) — 如果为 true，资产可以转移到另一个账户。
display object — 用于资产显示元数据的对象。
endpoint object — 用于资产端点元数据的对象。
tags string[] — 用于分类的标签数组。
delegator string — 如果交易由受托人发送，则为委托人的地址。

返回值

result Promise<[string, string]> — 一个包含交易哈希和新创建资产地址的数组。

示例

Send a CreateAssetTx

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 字段。

参数

address string (required) — 要更新的资产的地址。
moniker string (required) — 资产的新标识。
data object (required) — 资产的新 JSON 数据对象。
wallet WalletObject (required) — 资产当前所有者的钱包。

返回值

transactionHash Promise<string> — 已提交交易的哈希值。

示例

Send an UpdateAssetTx

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

创建一个资产工厂，该工厂可作为模板，用于铸造具有一致结构的多个新资产。

参数

factory object (required) — 包含工厂配置的对象。
- name string (required) — 工厂的名称。
- description string (required) — 工厂的描述。
- limit number (default: 0) — 可铸造资产的最大数量（0 表示无限制）。
- trustedIssuers string[] — 允许从此工厂铸造资产的钱包地址列表。
- input object (required) — 定义铸造所需的输入。
- output object (required) — 定义铸造资产的结构，通常使用模板。
wallet WalletObject (required) — 拥有该工厂的钱包。

返回值

result Promise<[string, string]> — 一个包含交易哈希和新创建工厂地址的数组。

示例

Send a CreateFactoryTx

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

从现有资产工厂获取（铸造）一个新资产。此操作通常由将拥有该资产的最终用户发起。

参数

itx AcquireAssetV2Tx (required) — 内部交易对象，通常使用 preMintAsset 等助手函数来准备。
wallet WalletObject (required) — 获取资产的用户的钱包。
delegator string — 委托人的地址（如适用）。

返回值

transactionHash Promise<string> — 已提交交易的哈希值。

示例

Send an AcquireAssetV2Tx

// 首先，准备铸造交易（例如，在服务器上）
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 对应的发行方操作。它允许受信任的发行人从工厂铸造资产并将其分配给指定的所有者。

参数

itx MintAssetTx (required) — 内部交易对象，通常使用 preMintAsset 准备。
wallet WalletObject (required) — 受信任发行人的钱包。

返回值

transactionHash Promise<string> — 已提交交易的哈希值。

示例

Send a MintAssetTx

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

创建一个新工厂，用于铸造和销毁特定的可替代通证，通常基于联合曲线定价模型。

参数

feeRate number (default: 0) — 铸造和销毁操作的费率。
curve object (required) — 用于定价的联合曲线配置。
token object (required) — 要创建的通证的配置。这包括 name、symbol、decimal 和 maxTotalSupply 等属性。
data object — 通证工厂的可选元数据。
wallet WalletObject (required) — 工厂所有者的钱包。

返回值

result Promise<[string, string]> — 一个包含交易哈希和新创建的通证工厂地址的数组。

示例

Send a CreateTokenFactoryTx

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。

参数

address string (required) — 要更新的通证工厂的地址。
feeRate number — 铸造和销毁的新费率。
data object — 通证工厂的新元数据。
wallet WalletObject (required) — 工厂所有者的钱包。

返回值

transactionHash Promise<string> — 已提交交易的哈希值。

示例

Send an UpdateTokenFactoryTx

const txHash = await client.updateTokenFactory({
  address: 'z2f...',
  feeRate: 50, // 0.5%
  wallet: ownerWallet,
});
console.log('Update token factory tx hash:', txHash);

mintToken

从通证工厂铸造新通证，以换取储备通证（通常是原生链通证）。成本由工厂的联合曲线决定。

参数

tokenFactory string (required) — 通证工厂的地址。
amount number (required) — 要铸造的新通证数量。
receiver string (required) — 将接收新铸造通证的地址。
maxReserve number (required) — 用户愿意支付的储备通证的最大数量。这可以起到滑点保护的作用。
data object — 交易的可选元数据。
wallet WalletObject (required) — 发起铸造的钱包。

返回值

transactionHash Promise<string> — 已提交交易的哈希值。

示例

Send a MintTokenTx

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

在工厂销毁现有通证，以换取底层的储备通证。收到的储备通证数量由工厂的联合曲线决定。

参数

tokenFactory string (required) — 通证工厂的地址。
amount number (required) — 要销毁的通证数量。
receiver string (required) — 将接收储备通证的地址。
minReserve number (required) — 用户期望收到的储备通证的最低数量。这可以起到滑点保护的作用。
data object — 交易的可选元数据。
wallet WalletObject (required) — 发起销毁的钱包。

返回值

transactionHash Promise<string> — 已提交交易的哈希值。

示例

Send a BurnTokenTx

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）转移到另一个账户。

参数

to string (required) — 接收方的地址。
wallet WalletObject (required) — 发送方的钱包。
token number (default: 0) — 要转移的链上原生通证的数量。
assets string[] — 要转移的资产地址（NFT）数组。
tokens object[] — 要转移的自定义可替代通证对象数组。
- address string (required) — 自定义通证合约的地址。
- value number (required) — 要转移的自定义通证的数量。
memo string — 交易的可选备注。
delegator string — 委托人的地址（如适用）。

返回值

transactionHash Promise<string> — 已提交交易的哈希值。

示例

Send a TransferV2Tx

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）交易的发送方部分。它会对发送方的报价进行签名，并返回一个可以传递给接收方的交易对象。

参数

receiver string (required) — 交换中另一方的地址。
wallet WalletObject (required) — 发起报价的用户的钱包。
offerToken number — 报价的原生通证数量。
offerAssets string[] — 报价的资产地址数组。
offerTokens object[] — 报价的自定义可替代通证数组。
demandToken number — 要求的回报原生通证数量。
demandAssets string[] — 要求的回报资产地址数组。
demandTokens object[] — 要求的回报自定义可替代通证数组。
memo string — 交易的可选备注。

返回值

transactionObject Promise<object> — 部分签名的交易对象。

finalizeExchange

完成原子交换的接收方部分。它接收来自 prepareExchange 的部分签名交易，添加接收方的签名，并返回完全签名的交易对象。

参数

tx object (required) — 从 prepareExchange 返回的交易对象。
wallet WalletObject (required) — 接受报价的用户的钱包。
data object — 多重签名中的额外数据。

返回值

transactionObject Promise<object> — 完全签名的多重签名交易对象。

exchange

将完全签名的交换交易发送到区块链。在 finalizeExchange 完成后，任何一方都可以调用此函数。

参数

tx object (required) — 从 finalizeExchange 返回的交易对象。
wallet WalletObject (required) — 提交交易的用户的钱包。

返回值

transactionHash Promise<string> — 已提交交易的哈希值。

示例（完整交换流程）

Perform an atomic swap

// 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

将通证和/或资产质押到接收方地址。质押会锁定资源，通常用于换取奖励或提供安全性。

参数

to string (required) — 质押接收方的地址。
wallet WalletObject (required) — 质押者的钱包。
assets string[] — 要质押的资产地址数组。
tokens object[] — 要质押的可替代通证对象数组。
locked boolean (default: false) — 质押在创建时是否被锁定。
slashers string[] — 被允许削减此质押的地址列表。
message string — 质押的可选备注。

返回值

result Promise<[string, string]> — 一个包含交易哈希和新创建质押地址的数组。

示例

Send a StakeTx

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

撤销先前质押的通证和/或资产，启动将其返还给所有者的流程。请注意，在资产可以被认领之前，可能存在一个解绑期。

参数

from string (required) — 要从中撤销质押的质押地址。
wallet WalletObject (required) — 质押所有者的钱包。
assets string[] — 要撤销的资产地址数组。
tokens object[] — 要撤销的可替代通证对象数组。

返回值

transactionHash Promise<string> — 已提交交易的哈希值。

示例

Send a RevokeStakeTx

const txHash = await client.revokeStake({
  from: 'z6s...',
  tokens: [{ address: 'z2t...', value: 1000 }],
  wallet: userWallet,
});
console.log('Revoke stake tx hash:', txHash);

claimStake

从已成功撤销并度过解绑期的质押中认领项目。

参数

from string (required) — 要从中认领的质押地址。
evidence string (required) — revokeStake 交易的交易哈希。
wallet WalletObject (required) — 质押所有者的钱包。

返回值

transactionHash Promise<string> — 已提交交易的哈希值。

示例

Send a ClaimStakeTx

const revokeTxHash = '0x123...abc';
const txHash = await client.claimStake({
  from: 'z6s...',
  evidence: revokeTxHash,
  wallet: userWallet,
});
console.log('Claim stake tx hash:', txHash);

slashStake

允许指定的削减者惩罚质押，通常是针对不当行为。被削减的资产将被转移到指定的金库地址。

参数

from string (required) — 要削减的质押地址。
reason string (required) — 解释削减原因的消息。
wallet WalletObject (required) — 指定削减者的钱包。
assets string[] — 要削减的资产地址数组。
tokens object[] — 要削减的可替代通证对象数组。

返回值

transactionHash Promise<string> — 已提交交易的哈希值。

示例

Send a SlashStakeTx

const txHash = await client.slashStake({
  from: 'z6s...',
  reason: 'Validator downtime',
  tokens: [{ address: 'z2t...', value: 500 }],
  wallet: slasherWallet,
});
console.log('Slash stake tx hash:', txHash);