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

低レベル API

低レベル API は、トランザクションのライフサイクル全体にわたるきめ細やかな制御を提供します。高レベル API が詳細を抽象化するのとは異なり、これらのメソッドを使用すると、トランザクションを手動で構築、エンコード、署名、送信できます。これは、ブロードキャストされる前に異なる関係者がトランザクショ

低レベル API は、トランザクションのライフサイクル全体にわたるきめ細やかな制御を提供します。高レベル API が詳細を抽象化するのとは異なり、これらのメソッドを使用すると、トランザクションを手動で構築、エンコード、署名、送信できます。これは、ブロードキャストされる前に異なる関係者がトランザクションに署名する必要があるマルチシグネチャワークフローなどの高度なシナリオに最適です。

この API は、トランザクションライフサイクルの各段階に対応する4つの主要なメソッドグループに整理されています。

  1. エンコード

    トランザクションを準備し、バイナリバッファにシリアル化します。

  2. 署名

    エンコードされたトランザクションにデジタル署名を追加します。

  3. マルチ署名

    トランザクションに複数のデジタル署名を追加します。

  4. 送信

    署名されたトランザクションをブロックチェーンにブロードキャストします。

トランザクションのエンコード

エンコードは、トランザクションを作成する最初のステップです。encode[Type]Tx メソッドは、コアトランザクションデータ (itx) を受け取り、それを標準的なトランザクション構造でラップし、chainId や nonce などの必要な詳細を追加します。結果として、人間が読める形式のトランザクションオブジェクトと、署名準備ができたバイナリバッファが生成されます。

チェーンでサポートされているすべてのトランザクションタイプに対して encode メソッドが存在します。client.getTxEncodeMethods() を呼び出すことで、全リストを取得できます。

encode[Type]Tx(payload)

トランザクションを署名せずにエンコードします。

パラメータ

  • tx object (required) — トランザクションデータオブジェクト。
    • itx object (required) — トランザクションタイプに固有の内部トランザクションオブジェクト。
    • from string — 送信者のアドレス。指定されていない場合は、ウォレットから派生します。
    • nonce number — トランザクションのナンス。設定されていない場合は、Date.now() がデフォルト値となります。
    • chainId string — チェーン ID。指定されていない場合は、接続されたノードから取得されます。
  • wallet WalletObject (required) — 送信者のアドレスと公開鍵を派生させるために使用されるウォレットオブジェクト。
  • delegator string — 該当する場合、権限を委任しているアカウントのアドレス。

戻り値

  • Promise Promise<object> — エンコードされたトランザクションを含むオブジェクトに解決される Promise。
    • object object — 人間が読める形式のトランザクションオブジェクト。
    • buffer Buffer — 署名準備ができた、シリアル化されたトランザクションのバイナリバッファ。

例

TransferV2Tx

javascript
const { encodeTransferV2Tx } = client;
const senderWallet = fromRandom();
const receiverAddress = 'z1...';

const { object, buffer } = await encodeTransferV2Tx({
  tx: {
    itx: {
      to: receiverAddress,
      value: await client.fromTokenToUnit(10), // 10 ネイティブトークンを転送
    },
  },
  wallet: senderWallet,
});

console.log('Encoded TX Object:', object);
console.log('Buffer to Sign:', buffer.toString('hex'));

トランザクションへの署名

sign[Type]Tx メソッドは、エンコードステップにデジタル署名を追加することで、そのステップを基盤としています。これらのメソッドはトランザクションをエンコードし、提供されたウォレットを使用して結果のバイナリバッファに署名します。

client.getTxSignMethods() を呼び出すことで、利用可能な署名メソッドの全リストを取得できます。

sign[Type]Tx(payload)

トランザクションをエンコードし、署名します。

パラメータ

  • tx object (required) — トランザクションデータオブジェクト。エンコード用と同じです。
  • wallet WalletObject (required) — トランザクションへの署名に使用されるウォレット。
  • delegator string — 該当する場合、デリゲータのアドレス。
  • encoding string — 出力のオプションのエンコーディング ('base16', 'hex', 'base58', 'base64')。省略された場合、トランザクションオブジェクトを返します。

戻り値

  • Promise<object|string> Promise<object|string> — 署名されたトランザクションオブジェクト、または encoding が指定されている場合はエンコードされた文字列に解決される Promise。

例

TransferV2Tx

javascript
const { signTransferV2Tx } = client;
const senderWallet = fromRandom();
const receiverAddress = 'z1...';

const signedTx = await signTransferV2Tx({
  tx: {
    itx: {
      to: receiverAddress,
      value: await client.fromTokenToUnit(10),
    },
  },
  wallet: senderWallet,
});

console.log('Signed TX:', signedTx);

トランザクションの送信

send[Type]Tx メソッドは、トランザクションをブロックチェーンにブロードキャストする役割を担います。これらのメソッドは、署名されていないトランザクションとウォレットが提供された場合に署名ステップを暗黙的に実行することも、すでに署名されたトランザクションを送信することもできます。

送信メソッドの全リストは client.getTxSendMethods() を介して利用できます。

send[Type]Tx(payload)

トランザクションに署名し（必要な場合）、チェーンに送信します。

パラメータ

  • tx object (required) — トランザクションオブジェクト。署名済みでも未署名でもかまいません。
  • wallet WalletObject (required) — トランザクションに署名するためのウォレット。トランザクションが事前に署名されていても、送信者を特定するために必要です。
  • signature string — トランザクションの事前に計算された署名。指定された場合、ウォレットは再署名に使用されません。
  • delegator string — 該当する場合、デリゲータのアドレス。
  • commit boolean (default: false) — 解決する前に、トランザクションがブロックにコミットされるのを待つかどうか。

戻り値

  • Promise Promise<string> — トランザクションハッシュに解決される Promise。

例：自動署名

TransferV2Tx

javascript
const { sendTransferV2Tx } = client;
const senderWallet = fromRandom();
const receiverAddress = 'z1...';

// クライアントは送信前に senderWallet を使用してこのトランザクションに署名します。
const txHash = await sendTransferV2Tx({
  tx: {
    itx: {
      to: receiverAddress,
      value: await client.fromTokenToUnit(10),
    },
  },
  wallet: senderWallet,
});

console.log('Transaction sent with hash:', txHash);

例：署名済みトランザクションの送信

TransferV2Tx

javascript
// signedTx は sign[Type]Tx の例からのものと仮定します
const { sendTransferV2Tx } = client;

const txHash = await sendTransferV2Tx({
  tx: signedTx, // 署名済みのトランザクションオブジェクト全体を渡します
  wallet: senderWallet,
});

console.log('Pre-signed transaction sent with hash:', txHash);

マルチシグネチャトランザクション

アトミックスワップのように複数の署名を必要とするワークフローでは、multiSign[Type]Tx メソッドが使用されます。このプロセスでは、まず一方の当事者が（標準の sign[Type]Tx メソッドを使用して）トランザクションに署名し、後続の当事者が対応する multiSign[Type]Tx メソッドを使用して自身の署名を追加します。

client.getTxMultiSignMethods() を介して、複数の署名をサポートするトランザクションのリストを取得できます。

multiSign[Type]Tx(payload)

すでに1つ以上の署名があるトランザクションに署名を追加します。

パラメータ

  • tx object (required) — トランザクションオブジェクト。少なくとも1つの署名がすでに含まれている必要があります。
  • wallet WalletObject (required) — 現在の署名者のウォレット。
  • delegator string — 該当する場合、現在の署名者のデリゲータのアドレス。
  • data any — 署名に含めるオプションのデータ。
  • encoding string — 出力のオプションのエンコーディング ('base16', 'hex', 'base58', 'base64')。

戻り値

  • Promise<object|string> Promise<object|string> — 新しい署名が追加されたトランザクションオブジェクトに解決される Promise。

例：アトミックスワップ (ExchangeV2Tx)

ExchangeV2Tx

javascript
// 2者のウォレット
const aliceWallet = fromRandom();
const bobWallet = fromRandom();

// 1. アリスが最初の交換トランザクションを準備し、署名します
const exchangeTx = {
  itx: {
    to: bobWallet.address,
    sender: {
      value: await client.fromTokenToUnit(10), // アリスは10トークンを提供します
    },
    receiver: {
      value: await client.fromTokenToUnit(5), // アリスは5トークンを要求します
    },
  },
};

const signedByAlice = await client.signExchangeV2Tx({
  tx: exchangeTx,
  wallet: aliceWallet,
});

// 2. アリスは `signedByAlice` をボブに送信します。ボブは自身の署名を追加します。
const signedByBoth = await client.multiSignExchangeV2Tx({
  tx: signedByAlice,
  wallet: bobWallet,
});

// 3. ボブは `signedByBoth` をアリスに返送します。アリスが最終的なトランザクションを送信します。
const txHash = await client.sendExchangeV2Tx({
  tx: signedByBoth,
  wallet: aliceWallet, // 送信者のウォレットが提出に使用されます
});

console.log('Atomic swap transaction sent:', txHash);