# トランザクションのライフサイクル

トークンの転送やアセットの作成など、ブロックチェーンの状態を変更するすべてのアクションは、トランザクションを通じて実行されます。トランザクションのライフサイクルを理解することは、OCAP Client を使用してアプリケーションを構築する上で基本となります。このプロセスには、準備、エンコード、署名、送信という4つの主要な段階が含まれます。

OCAP Client は柔軟なメソッドセットを提供しており、最大限の制御のためにこれらのステップを個別に実行することも、利便性のためにこれらを組み合わせた高レベルのヘルパーを使用することもできます。

このガイドでは、各段階を詳しく解説し、単一署名と複数署名の両方のワークフローを説明します。


## ライフサイクルの概要

以下の図は、準備からブロックチェーンへの最終的な送信までのトランザクションの完全な流れを示しています。

<!-- DIAGRAM_IMAGE_START:flowchart:4:3 -->

![Transaction Lifecycle](assets/diagram/core-concepts-transaction-lifecycle-01.jpg)

<!-- DIAGRAM_IMAGE_END -->


## ステージ1: 準備（`itx`の作成）

すべてのトランザクションは `itx` (内部トランザクション) から始まります。これは、実行したいアクションの特定のデータを含むプレーンな JavaScript オブジェクトです。例えば、転送用の `itx` には、受信者のアドレスと金額が含まれます。

```javascript Preparing the itx icon=logos:javascript
// 転送トランザクションのコアデータ
const itx = {
  to: 'z2C8j81aL2oXpA5t42s2h4g9o8p1k6m3n7b', // 受信者のアドレス
  value: await client.fromTokenToUnit(10),   // 送信する金額、チェーンの基本単位に変換済み
};
```


## ステージ2: エンコード

エンコードは、`itx` とその他のメタデータを、暗号学的に署名可能な標準化されたバイナリ形式に変換します。クライアントは、各トランザクションタイプごとに `encode{TxType}Tx` メソッド（例：`encodeTransferV2Tx`）を提供します。

この段階で、クライアントは自動的に必須のメタデータを追加します。

* **`from`**: 送信者のアドレス。提供されたウォレットから派生します。
* **`chainId`**: ターゲットブロックチェーンの識別子。自動的に取得されます。
* **`nonce`**: リプレイ攻撃を防ぐためのユニークな番号。デフォルトでは現在のタイムスタンプ（`Date.now()`）になります。
* **`pk`**: 送信者ウォレットの公開鍵。

エンコード関数は、完全なトランザクションオブジェクトと、署名に使用されるシリアライズされたデータの `Buffer` の両方を返します。

```javascript Encoding the Transaction icon=logos:javascript
const { object: encodedTx, buffer: txBuffer } = await client.encodeTransferV2Tx({
  tx: { itx },
  wallet: senderWallet,
});

console.log('Encoded TX Object:', encodedTx);
console.log('Buffer to be signed:', txBuffer);
```


## ステージ3: 署名

署名は、アカウントの所有権を証明し、トランザクションを承認するものです。このプロセスは、単一署名と複数署名のワークフローで異なります。

### 単一署名ワークフロー

これは、単一のユーザーがトランザクションに署名する、最も一般的なシナリオです。`sign{TxType}Tx` メソッドは、エンコードされたトランザクションを受け取り、ユーザーの秘密鍵でバイナリバッファに署名し、`signature` フィールドに値を設定します。

```javascript Signing with a Single Signature icon=logos:javascript
const signedTx = await client.signTransferV2Tx({
  tx: encodedTx, // エンコードステップで得られたオブジェクト
  wallet: senderWallet,
});

console.log('Signature:', signedTx.signature);
```

### 複数署名ワークフロー

複数署名（マルチシグ）トランザクションは、複数の当事者からの承認を必要とします。これは、アトミックスワップや共有アカウントで一般的に使用されます。プロセスは順次的に行われます。

1. **準備**: 最初のトランザクションは、必要なすべての署名者を定義する `signaturesList` とともに作成されます。
2. **順次署名**: トランザクションは署名者から次の署名者へと渡されます。各署名者は、対応する `multiSign{TxType}Tx` メソッドを使用して自身の署名を追加します。

内部的に、`multiSign` メソッドは、署名のためにトランザクションをエンコードする前に、既存のすべての署名を一時的に取り除くことで、各当事者が全く同じトランザクションダイジェストに署名することを保証します。

以下は、2つの当事者がアセットを交換する `ExchangeTx` の例です。

```javascript Multi-Signature Signing Example icon=logos:javascript
// ステップ1: Alice（オファー側）が交換トランザクションを準備し、署名します。
const txFromAlice = await client.prepareExchange({
  offerToken: 10,
  demandToken: 20,
  receiver: bobWallet.address,
  wallet: aliceWallet,
});

// ステップ2: トランザクションが Bob に送信されます。
// Bob（デマンド側）が署名を追加して完了させます。
const txFromBob = await client.finalizeExchange({
  tx: txFromAlice, // Alice によって署名されたトランザクション
  wallet: bobWallet,
});

console.log('Alice\'s Signature:', txFromBob.signaturesList[0].signature);
console.log('Bob\'s Signature:', txFromBob.signaturesList[1].signature);
```


## ステージ4: 送信

トランザクションが完全に署名されると、処理のためにブロックチェーンノードに送信できます。`send{TxType}Tx` メソッドがこの最終ステップを処理します。

利便性のために、これらのメソッドは、ウォレットと未署名のトランザクションを提供した場合、署名ステップを暗黙的に実行することもできます。このメソッドは、送信が成功するとトランザクションハッシュで解決されるプロミスを返します。

```javascript Sending the Signed Transaction icon=logos:javascript
// 事前に署名されたトランザクションを使用
const hash = await client.sendTransferV2Tx({ tx: signedTx, wallet: senderWallet });

// または、send メソッドに署名を自動的に処理させる
const hash2 = await client.sendTransferV2Tx({
  tx: { itx }, // 内部トランザクションのみ
  wallet: senderWallet,
});

console.log('Transaction sent! Hash:', hash);
```

また、`commit: true` オプションを含めることで、プロミスが解決される前に、トランザクションが完全に確認され、ブロックに含まれるまでクライアントを待機させることもできます。


## まとめ

トランザクションのライフサイクルは、ブロックチェーンと対話するための堅牢で柔軟なフレームワークを提供します。プロセスを準備、エンコード、署名、送信という明確な段階に分けることで、OCAP Client は開発者にトランザクション作成に対するきめ細やかな制御を提供すると同時に、一般的なユースケースのためのシンプルで高レベルなヘルパーも提供します。

トランザクション手数料の処理方法に関する詳細は、[ガス支払い](./core-concepts-gas-payment.md)ガイドを参照してください。利用可能なさまざまなクライアントタイプを理解するには、[クライアントアーキテクチャ](./core-concepts-client-architecture.md)のドキュメントを参照してください。