トランザクションヘルパーは、OCAP Client に組み込まれた高レベル関数であり、一般的なトランザクションの作成と署名の複雑さを抽象化します。トランザクションオブジェクトを手動で構築する代わりに、アセットの作成、トークンの転送、ステーキング、アトミックスワップの実行などのワークフローに、これらの便利なメソッドを使用できます。これらのヘルパーは、トランザクション構造が正しいことを保証し、開発プロセスを大幅に簡素化します。
基盤となるトランザクションライフサイクルの詳細については、コアコンセプト:トランザクションライフサイクルを参照してください。
アカウント管理
migrateAccount
アカウントの所有権を新しいキーペアに移行します。これは、キーのローテーションやアカウントの回復に役立ちます。
パラメータ
- from
WalletObject(required) — 移行元のアカウントのウォレットオブジェクト。 - to
WalletObject(required) — 移行先のアカウントのウォレットオブジェクト。
戻り値
- transactionHash
Promise<string>— 送信されたトランザクションのハッシュ。
例
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)に対する制限。
- tokens
- typeUrl
戻り値
- result
Promise<[string, string]>— トランザクションハッシュと新しく作成されたデリゲートアドレスを含む配列。
例
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')。
- typeUrl
戻り値
- transactionHash
Promise<string>— 送信されたトランザクションのハッシュ。
例
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]>— トランザクションハッシュと新しく作成されたアセットのアドレスを含む配列。
例
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>— 送信されたトランザクションのハッシュ。
例
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) — ミントされたアセットの構造を定義します。多くの場合、テンプレートを使用します。
- name
- wallet
WalletObject(required) — ファクトリーを所有するウォレット。
戻り値
- result
Promise<[string, string]>— トランザクションハッシュと新しく作成されたファクトリーのアドレスを含む配列。
例
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>— 送信されたトランザクションのハッシュ。
例
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>— 送信されたトランザクションのハッシュ。
例
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]>— トランザクションハッシュと新しく作成されたトークンファクトリーのアドレスを含む配列。
例
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('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>— 送信されたトランザクションのハッシュ。
例
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>— 送信されたトランザクションのハッシュ。
例
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>— 送信されたトランザクションのハッシュ。
例
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) — 転送するカスタムトークンの量。
- address
- memo
string— トランザクションのオプションのメモ。 - delegator
string— 該当する場合、デリゲーターのアドレス。
戻り値
- transactionHash
Promise<string>— 送信されたトランザクションのハッシュ。
例
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
アトミックスワップ(交換)トランザクションの送信者側を準備します。送信者のオファーに署名し、受信者に渡すことができるトランザクションオブジェクトを返します。
パラメータ
- 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>— 送信されたトランザクションのハッシュ。
例 (完全な交換フロー)
アトミックスワップを実行
// 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]>— トランザクションハッシュと新しく作成されたステークのアドレスを含む配列。
例
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>— 送信されたトランザクションのハッシュ。
例
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>— 送信されたトランザクションのハッシュ。
例
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>— 送信されたトランザクションのハッシュ。
例
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);