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