# 低レベル API

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

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

1. **エンコード**: トランザクションを準備し、バイナリバッファにシリアル化します。
2. **署名**: エンコードされたトランザクションにデジタル署名を追加します。
3. **マルチ署名**: トランザクションに複数のデジタル署名を追加します。
4. **送信**: 署名されたトランザクションをブロックチェーンにブロードキャストします。


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

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

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

### `encode[Type]Tx(payload)`

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

**パラメータ**

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

**戻り値**

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

**例**

```javascript TransferV2Tx icon=logos: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)`

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

**パラメータ**

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

**戻り値**

<x-field data-name="Promise<object|string>" data-type="Promise<object|string>" data-desc="署名されたトランザクションオブジェクト、または `encoding` が指定されている場合はエンコードされた文字列に解決される Promise。"></x-field>

**例**

```javascript TransferV2Tx icon=logos: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)`

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

**パラメータ**

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

**戻り値**

<x-field data-name="Promise<string>" data-type="Promise<string>" data-desc="トランザクションハッシュに解決される Promise。"></x-field>

**例：自動署名**

```javascript TransferV2Tx icon=logos: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);
```

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

```javascript TransferV2Tx icon=logos: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つ以上の署名があるトランザクションに署名を追加します。

**パラメータ**

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

**戻り値**

<x-field data-name="Promise<object|string>" data-type="Promise<object|string>" data-desc="新しい署名が追加されたトランザクションオブジェクトに解決される Promise。"></x-field>

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

```javascript ExchangeV2Tx icon=logos: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);
```
