高階 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('遷移交易雜湊值：', 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('委託交易雜湊值：', txHash);
console.log('委託地址：', 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('撤銷委託交易雜湊值：', 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('建立資產交易雜湊值：', txHash);
console.log('新資產地址：', 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('更新資產交易雜湊值：', 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('建立工廠交易雜湊值：', txHash);
console.log('新工廠地址：', 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('獲取資產交易雜湊值：', 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('鑄造資產交易雜湊值：', 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 個原生代幣
  token: {
    name: 'My Community Token',
    symbol: 'MCT',
    decimal: 18,
    maxTotalSupply: '1000000',
  },
  wallet: creatorWallet,
});
console.log('建立代幣工廠交易雜湊值：', txHash);
console.log('新代幣工廠地址：', 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('更新代幣工廠交易雜湊值：', 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('鑄造代幣交易雜湊值：', 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('銷毀代幣交易雜湊值：', 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('轉帳交易雜湊值：', 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('交換交易雜湊值：', 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('質押交易雜湊值：', txHash);
console.log('新質押地址：', 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('撤銷質押交易雜湊值：', 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('領取質押交易雜湊值：', 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('削減質押交易雜湊值：', txHash);