メインコンテンツへスキップ

高レベルAPI

トランザクションヘルパーは、OCAP Client に組み込まれた高レベル関数であり、一般的なトランザクションの作成と署名の複雑さを抽象化します。トランザクションオブジェクトを手動で構築する代わりに、アセットの作成、トークンの転送、ステーキング、アトミックスワップの実行などのワークフローに、これらの便利なメソッドを使用できます。これらのヘルパーは、トランザクション構造が正しいことを保証し、開発プロセスを大幅に簡素化します。

基盤となるトランザクションライフサイクルの詳細については、コアコンセプト:トランザクションライフサイクルを参照してください。

アカウント管理

migrateAccount

アカウントの所有権を新しいキーペアに移行します。これは、キーのローテーションやアカウントの回復に役立ちます。

パラメータ

  • from WalletObject (required) — 移行元のアカウントのウォレットオブジェクト。
  • to WalletObject (required) — 移行先のアカウントのウォレットオブジェクト。

戻り値

  • transactionHash Promise<string> — 送信されたトランザクションのハッシュ。

AccountMigrateTx を送信

javascript
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]> — トランザクションハッシュと新しく作成されたデリゲートアドレスを含む配列。

DelegateTx を送信

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

以前に付与された権限をデリゲート先から取り消します。

パラメータ

  • from WalletObject (required) — デリゲーターのウォレット。
  • to WalletObject (required) — デリゲート先のウォレット。
  • privileges array (required) — 取り消す権限を指定する権限オブジェクトの配列。
    • typeUrl string (required) — 取り消すトランザクションのタイプURL(例:'fg:t')。

戻り値

  • transactionHash Promise<string> — 送信されたトランザクションのハッシュ。

RevokeDelegateTx を送信

javascript
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 を送信

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

既存の読み取り専用でないアセットの monikerdata フィールドを更新します。

パラメータ

  • address string (required) — 更新するアセットのアドレス。
  • moniker string (required) — アセットの新しいモニカー。
  • data object (required) — アセットの新しいJSONデータオブジェクト。
  • wallet WalletObject (required) — アセットの現在の所有者のウォレット。

戻り値

  • transactionHash Promise<string> — 送信されたトランザクションのハッシュ。

UpdateAssetTx を送信

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

アセットファクトリーを作成します。これは、一貫した構造を持つ複数の新しいアセットをミントするためのテンプレートとして機能します。

パラメータ

  • 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]> — トランザクションハッシュと新しく作成されたファクトリーのアドレスを含む配列。

CreateFactoryTx を送信

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

既存のアセットファクトリーから新しいアセットを取得(ミント)します。これは通常、アセットを所有するエンドユーザーによって開始されます。

パラメータ

  • itx AcquireAssetV2Tx (required) — 内部トランザクションオブジェクト。多くの場合、preMintAssetのようなヘルパーを使用して準備されます。
  • wallet WalletObject (required) — アセットを取得するユーザーのウォレット。
  • delegator string — 該当する場合、デリゲーターのアドレス。

戻り値

  • transactionHash Promise<string> — 送信されたトランザクションのハッシュ。

AcquireAssetV2Tx を送信

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の発行者側の対応物です。信頼できる発行者がファクトリーからアセットをミントし、指定された所有者に割り当てることを許可します。

パラメータ

  • itx MintAssetTx (required) — 内部トランザクションオブジェクト。多くの場合、preMintAssetを使用して準備されます。
  • wallet WalletObject (required) — 信頼できる発行者のウォレット。

戻り値

  • transactionHash Promise<string> — 送信されたトランザクションのハッシュ。

MintAssetTx を送信

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

特定のファンジブルトークンをミントおよびバーンするための新しいファクトリーを作成します。多くの場合、ボンディングカーブの価格設定モデルに基づいています。

パラメータ

  • feeRate number (default: 0) — ミントおよびバーン操作の手数料率。
  • curve object (required) — 価格設定のためのボンディングカーブの設定。
  • token object (required) — 作成されるトークンの設定。これにはname、symbol、decimal、maxTotalSupplyなどのプロパティが含まれます。
  • data object — トークンファクトリーのオプションのメタデータ。
  • wallet WalletObject (required) — ファクトリーの所有者のウォレット。

戻り値

  • result Promise<[string, string]> — トランザクションハッシュと新しく作成されたトークンファクトリーのアドレスを含む配列。

CreateTokenFactoryTx を送信

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('Create token factory tx hash:', txHash);
console.log('New token factory address:', factoryAddress);

updateTokenFactory

既存のトークンファクトリーの feeRatedata を更新します。

パラメータ

  • address string (required) — 更新するトークンファクトリーのアドレス。
  • feeRate number — ミントおよびバーンの新しい手数料率。
  • data object — トークンファクトリーの新しいメタデータ。
  • wallet WalletObject (required) — ファクトリーの所有者のウォレット。

戻り値

  • transactionHash Promise<string> — 送信されたトランザクションのハッシュ。

UpdateTokenFactoryTx を送信

javascript
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 を送信

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

ファクトリーで既存のトークンをバーンして、基礎となるリザーブトークンを返してもらいます。受け取るリザーブトークンの量は、ファクトリーのボンディングカーブによって決定されます。

パラメータ

  • tokenFactory string (required) — トークンファクトリーのアドレス。
  • amount number (required) — バーンするトークンの量。
  • receiver string (required) — リザーブトークンを受け取るアドレス。
  • minReserve number (required) — ユーザーが受け取ることを期待するリザーブトークンの最小量。これはスリッページ保護として機能します。
  • data object — トランザクションのオプションのメタデータ。
  • wallet WalletObject (required) — バーンを開始するウォレット。

戻り値

  • transactionHash Promise<string> — 送信されたトランザクションのハッシュ。

BurnTokenTx を送信

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)を、単一のトランザクションで別のアカウントに転送します。

パラメータ

  • 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> — 送信されたトランザクションのハッシュ。

TransferV2Tx を送信

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

アトミックスワップ(交換)トランザクションの送信者側を準備します。送信者のオファーに署名し、受信者に渡すことができるトランザクションオブジェクトを返します。

パラメータ

  • 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> — 送信されたトランザクションのハッシュ。

例 (完全な交換フロー)

アトミックスワップを実行

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

トークンおよび/またはアセットを受信者アドレスにステークします。ステーキングはリソースをロックし、多くの場合、報酬と引き換えに、またはセキュリティを提供するために行われます。

パラメータ

  • to string (required) — ステークの受信者のアドレス。
  • wallet WalletObject (required) — ステーカーのウォレット。
  • assets string[] — ステークするアセットアドレスの配列。
  • tokens object[] — ステークするファンジブルトークンオブジェクトの配列。
  • locked boolean (default: false) — 作成時にステークがロックされるかどうか。
  • slashers string[] — このステークをスラッシュすることが許可されているアドレスのリスト。
  • message string — ステークのオプションのメモ。

戻り値

  • result Promise<[string, string]> — トランザクションハッシュと新しく作成されたステークのアドレスを含む配列。

StakeTx を送信

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

以前にステークされたトークンおよび/またはアセットを取り消し、所有者への返還プロセスを開始します。アセットが請求可能になるまでにアンボンディング期間がある場合があることに注意してください。

パラメータ

  • from string (required) — 取り消すステークのアドレス。
  • wallet WalletObject (required) — ステーク所有者のウォレット。
  • assets string[] — 取り消すアセットアドレスの配列。
  • tokens object[] — 取り消すファンジブルトークンオブジェクトの配列。

戻り値

  • transactionHash Promise<string> — 送信されたトランザクションのハッシュ。

RevokeStakeTx を送信

javascript
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 を送信

javascript
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 を送信

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);