バイナリフォーマット

[ソース]

このページでは、XRP Ledgerのトランザクションとその他のデータの正規バイナリフォーマットについて説明します。このバイナリフォーマットは、トランザクションの内容のデジタル署名を作成および検証するために必要であり、サーバ間のピアツーピア通信を含む他の用途にも使用されます。通常、rippled APIは、JSONを使用してクライアントアプリケーションと通信します。ただしJSONは、同じデータをさまざまな同等の方法で表現できるため、デジタル署名を付与するトランザクションをシリアル化するのに適したフォーマットではありません。

トランザクションをJSONまたはその他の表現から正規バイナリフォーマットへシリアル化するプロセスのステップを、以下にまとめます。

1. すべての必須フィールドが指定されていること（必須の「自動入力可能」フィールドを含む）を確認します。

   トランザクションフォーマットリファレンスに、XRP Ledgerトランザクションの必須フィールドと省略可能なフィールドが定義されています。

   注記: SigningPubKeyもこのステップで指定する必要があります。署名の際に、署名用に指定された秘密鍵からこのキーを導出できます。

2. 各フィールドのデータを「内部」バイナリフォーマットに変換します。

3. フィールドを正規順序でソートします。

4. 各フィールドの前にフィールドIDを付加します。

5. フィールド（プレフィクスを含む）をソート順に連結します。

その結果、ECDSA（secp256k1楕円曲線を使用）やEd25519などの既知の署名アルゴリズムを使用して署名できるバイナリBlobが1つ作成されます。XRP Ledgerのために、適切なプレフィクス（シングル署名の場合は0x53545800、マルシグの場合は0x534D5400）を使用してデータをハッシュ化する必要があります。署名後に、指定されているTxnSignatureフィールドを使用してトランザクションを再度シリアル化する必要があります。

注記: XRP Ledgerでは、レジャーオブジェクトや処理済みのトランザクションなど他のタイプのデータを表す場合にも同じシリアル化フォーマットが使用されます。ただし、署名されるトランザクションに追加するのに適切なフィールドは限られています。（たとえば署名自体が指定されているTxnSignatureフィールドは、署名するバイナリBlobに含まれていてはなりません。）このように、「署名」フィールドとされてオブジェクトに署名するときにオブジェクトに含まれるフィールドもあれば、「非署名」とされてオブジェクトに含まれないフィールドもあります。

例

署名済みトランザクションと未署名のトランザクションはいずれも、JSONフォーマットとバイナリフォーマットの両方で表すことができます。同じ署名済みトランザクションのJSONフォーマットとバイナリフォーマットの例を以下に示します。

JSON:

{
  "Account": "rMBzp8CgpE441cp5PVyA9rpVV7oT8hP3ys",
  "Expiration": 595640108,
  "Fee": "10",
  "Flags": 524288,
  "OfferSequence": 1752791,
  "Sequence": 1752792,
  "SigningPubKey": "03EE83BB432547885C219634A1BC407A9DB0474145D69737D09CCDC63E1DEE7FE3",
  "TakerGets": "15000000000",
  "TakerPays": {
    "currency": "USD",
    "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
    "value": "7072.8"
  },
  "TransactionType": "OfferCreate",
  "TxnSignature": "30440220143759437C04F7B61F012563AFE90D8DAFC46E86035E1D965A9CED282C97D4CE02204CFD241E86F17E011298FC1A39B63386C74306A5DE047E213B0F29EFA4571C2C",
  "hash": "73734B611DDA23D3F5F62E20A173B78AB8406AC5015094DA53F53D39B9EDB06C"
}

バイナリ（16進数として表現）:

120007220008000024001ABED82A2380BF2C2019001ABED764D55920AC9391400000000000000000000000000055534400000000000A20B3C85F482532A9578DBB3950B85CA06594D165400000037E11D60068400000000000000A732103EE83BB432547885C219634A1BC407A9DB0474145D69737D09CCDC63E1DEE7FE3744630440220143759437C04F7B61F012563AFE90D8DAFC46E86035E1D965A9CED282C97D4CE02204CFD241E86F17E011298FC1A39B63386C74306A5DE047E213B0F29EFA4571C2C8114DD76483FACDEE26E60D8A586BB58D09F27045C46

サンプルコード

ここで説明するシリアル化プロセスは複数の場所にさまざまなプログラミング言語で実装されています。

• C++: rippledコードベース
• JavaScript: ripple-binary-codecパッケージ
• Python 3: このリポジトリのコードサンプルセクション

これらのすべての実装には、一般利用が可能なオープンソースライセンスが提供されているので、学習のためにドキュメントと合わせて使用するだけでなく、必要に応じてコードをインポート、使用、または変更することができます。

内部フォーマット

各フィールドには「内部」バイナリフォーマットがあります。このフォーマットは、rippledソースコードで署名時に（およびその他のほとんどの場合に）そのフィールドを表示するのに使用されます。すべてのフィールドの内部フォーマットは、SField.cppのソースコードに定義されています。（このフィールドには、トランザクションフィールド以外のフィールドも含まれています。）トランザクションフォーマットリファレンスにも、すべてのトランザクションフィールドの内部フォーマットが記載されています。

たとえばFlags共通トランザクションフィールドはUInt32（32ビット符号なし整数）になります。

定義ファイル

以下のJSONファイルには、XRP Ledgerデータをそのバイナリフォーマットにシリアル化し、バイナリからシリアル化解除するのに必要な重要な定数が定義されています。

https://github.com/ripple/ripple-binary-codec/blob/master/src/enums/definitions.json

この定義ファイルの最上位フィールドの定義を以下の表に示します。

署名と送信のためにトランザクションをシリアル化するという目的から、FIELDS、TYPES、およびTRANSACTION_TYPESフィールドが必要です。

FIELDS配列のフィールド定義オブジェクトには以下のフィールドが含まれています。

フィールドID

[ソース - エンコード] [ソース - デコード]

フィールドのタイプコードとフィールドコードを結合すると、フィールドの一意のIDになります。このIDは、最終的なシリアル化Blobでこのフィールドの前に付加されます。フィールドIDのサイズは、タイプコードとその結合対象のフィールドコードに応じて1～3バイトとなります。以下の表をご覧ください。

	タイプコード < 16	タイプコード >= 16
フィールドコード < 16
フィールドコード >= 16

デコードの際には、1番目のバイトのどのビットがゼロであるかによって、フィールドIDのバイト数を把握できます。これは、上記の表の例に対応しています。

注意: フィールドIDは、フィールドのソートに使用される2つの要素で構成されますが、シリアル化されたフィールドID自体に基づいてソートを実行しないでください。これは、フィールドIDのバイト構造によってソート順序が変わるためです。

長さプレフィクスを付加する

一部の可変長フィールドの前には、長さインディケーターが付加されています。Blobフィールド（任意のバイナリデータを含む）がこれに該当します。長さプレフィクスが付加されているタイプのリストについては、タイプリストの表をご覧ください。

注記: 一部のタイプの可変長フィールドには、長さプレフィクスが付加されません。このようなタイプでは、他の方法で内容の終わりが示されます。

長さプレフィクスはフィールドの長さを示す1～3バイトで構成され、タイププレフィクスと内容の間に挿入されます。

• フィールドに0～192バイトのデータが含まれている場合、1番目のバイトは内容の長さを示し、長さバイトの直後にそのバイト数のデータが続きます。

• フィールドに193～12480バイトのデータが含まれている場合、最初の2バイトは以下の式で算出されるフィールドの長さを示します。

  193 + ((byte1 - 193) * 256) + byte2
  

• フィールドに12481～918744バイトのデータが含まれている場合、最初の3バイトは以下の式で算出されるフィールドの長さを示します。

  12481 + ((byte1 - 241) * 65536) + (byte2 * 256) + byte3
  

• 長さプレフィクスが付加されているフィールドに格納できる最大データは918744バイトです。

デコード時に、1番目の長さバイトの値から、追加の長さバイト（0、1、または2）が存在するかどうかを把握できます。

• 1番目の長さバイトの値が192以下の場合、これは唯一の長さバイトであり、フィールドの内容の長さはこのバイトが示すバイト数です。
• 1番目の長さバイトの値が193～240の場合、2つの長さバイトがあります。
• 1番目の長さバイトの値が241～254の場合、3つの長さバイトがあります。

フィールドの正規順序

トランザクションのすべてのフィールドは、まずフィールドのタイプ（特に各タイプに割り当てられている数値の「タイプコード」）に基づいて特定の順序でソートされ、次にフィールド自体（「フィールドコード」）に基づいてソートされます。（たとえば、姓がフィールドのタイプ、名前がフィールド自体とすると、姓で最初にソートし、次に名でソートすることになります。）

タイプコード

各フィールドタイプには任意のタイプコードが含まれており、番号が小さいコードから最初にソートされます。これらのコードはSField.hで定義されています。

たとえば UInt32のタイプコードが2であるので、すべてのUInt32フィールドは、すべてのAmountフィールド（タイプコード6）よりも前に位置します。

定義ファイルには、TYPESマップの各タイプのタイプコードがリストされています。

フィールドコード

各フィールドにはフィールドコードが含まれています。フィールドコードは、同じタイプのフィールドをソートするときに使用され、番号が小さいコードが最初になるようにソートされます。これらのフィールドはSField.cppで定義されています。

たとえばPaymentトランザクションのAccountフィールドのソートコードが1である場合、このフィールドはDestinationフィールド（ソートコードが3であるフィールド）よりも前に位置します。

フィールドコードは異なるフィールドタイプのフィールドで再利用されますが、同じタイプのフィールドに同じフィールドコードが含まれることはありません。タイプコードとフィールドコードを組み合わせると、フィールドの一意のフィールドIDになります。

タイプリスト

トランザクションの指示には、以下のタイプのフィールドを指定できます。

上記のフィールドタイプの他に、レジャーオブジェクトやトランザクションメタデータなどのコンテキストでは以下のタイプが含まれることがあります。

AccountIDフィールド

このタイプのフィールドには、XRP Ledgerアカウントの160ビットのIDが含まれています。JSONではこれらのフィールドはbase58 XRP Ledger「アドレス」および追加のチェックサムデータとして表示されます。このため、スペルミスが有効なアドレスとなることがありません。（このエンコードは「Base58Check」とも呼ばれ、誤ったアドレスへの送金を防止します。）これらのフィールドのバイナリフォーマットにはチェックサムデータは含まれておらず、またアドレスのbase58エンコードで使用される0x00「タイププレフィクス」も含まれていません。（ただし、バイナリフォーマットは主に署名済みトランザクションに使用されるため、署名済みトランザクションを転記する際にスペルミスなどのエラーが発生すると署名が無効となり、送金できなくなります。）

スタンドアロンフィールドとして表示されるAccountID（AccountやDestinationなど）の長さは固定長の160ビットですが、長さプレフィクスが付加されます。その結果、これらのフィールドの長さインディケーターは常に0x14バイトになります。特殊フィールドの子として示されるAccountID（Amount issuer、PathSet accountなど）では長さプレフィクスは付加 されません 。

Amountフィールド

「Amount」タイプは、通貨（XRPまたはトークン）の額を表す特殊なフィールドタイプです。このタイプは2つのサブタイプで構成されます。

• XRP

  XRPは64ビット符号なし整数（ビッグエンディアンオーダー）としてシリアル化されます。ただし、XRPであることを示すため最上位ビットが常に0であり、プラスの値であることを示す最上位から2番目のビットは1となります。XRPの最大額（10¹⁷ drop）には57ビットが必要であるため、XRPのシリアル化フォーマットを計算するには、標準の64ビット符号なし整数をとり、0x4000000000000000のビットOR演算を行います。

• トークン

トークンは以下の3つのセグメントで構成され、セグメントの順序は以下のとおりです。

1. トークンの数量フォーマットの額を示す64ビット。1番目のビットは、これがXRPではないことを示す1です。
2. 通貨コードを示す160ビット。標準APIでは、標準通貨コードフォーマットを使用して「USD」などの3文字のコードが160ビットのコードに変換されますが、160ビットのカスタムコードも使用できます。
3. イシュアーのアカウントIDを示す160ビット。（関連項目: アカウントアドレスエンコード

1番目のビットに基づいて2つのサブタイプのいずれに該当するかを確認できます。0の場合はXRP、1の場合はトークンです。

以下の図に、XRPの額とトークン額のシリアル化フォーマットを示します。

トークンの数量フォーマット

[ソース]

XRP Ledgerは64ビットを使って(代替可能な)トークンの金額をシリアライズします。(JSONフォーマットでは、通貨量オブジェクトのvalueフィールドが数値量になります)。バイナリ形式では、数値は"非XRP"ビット、符号ビット、指数、有効数字の順で構成されます。

1. トークン数量の最初の(最上位)ビットは1で、XRP数量ではないことを示します。(XRPの金額は、このフォーマットと区別するために、最上位ビットが常に0に設定されています)。
2. 符号ビットは、金額がプラスかマイナスかを示します。標準的な2の補数整数とは異なり、XRP Ledgerフォーマットでは1は正を表し、0は負を表します。
3. 次の8ビットは指数を符号なし整数で表します。指数は、-96から+80(含む)の範囲でスケール（有効桁を10の何乗にするか）を示します。しかし、シリアライズするときには、指数に97を加えて符号なし整数としてシリアライズできるようにします。したがって、シリアル化された値1は指数-96を表し、シリアル化された値177は指数80を表します。
4. 残りの54ビットは、符号なし整数として有効数字(mantissa と呼ばれることもあります)を表します。シリアライズするとき、この値は10¹⁵(1000000000000000)から10¹⁶-1(9999999999)の範囲に正規化されます。0の特別なケースでは、符号ビット、指数、有効数字はすべて0ですので、64ビットの値は0x800000000000000000000000としてシリアライズされます。

数値の金額は、通貨コードおよび発行者とともにシリアライズされ、完全なトークン金額を形成します。

通貨コード

プロトコルレベルでは、XRP Ledgerの通貨コードは任意の160bit値ですが、以下の値には特別な意味があります。

• 通貨コード0x0000000000000000000000005852500000000000は使用できません 。(これは"標準フォーマット"において"XRP"を表します)。
• 通貨コード0x0000000000000000000000000000000000000000(すべてゼロ)は、許可されません。通常、XRPの金額を通貨コードで指定することはありません。しかし、XRPの通貨コードを指定しなければならないフィールドが存在する場合、このコードはXRPを示すために使用されます。

rippled APIは、3文字のASCIIコードを160ビットの16進数に変換するための標準フォーマットを以下のようにサポートしています。

1. 最初の8ビットは0x00でなければなりません。
2. 次の88ビットは予約済みで、すべて0でなければなりません。
3. 次の24ビットはASCIIの3文字を表します。 ISO 4217 コード、または "BTC"のような一般的な擬似 ISO 4217コードの使用を推奨します。すべての大文字と小文字、数字、記号 ?, !, @, #, $, %, ^, &, *, <, >, (, ), {, }, [, ], |が利用可能です。 通貨コードXRP(すべて大文字)はXRPのために予約済みであり、トークンで使用することはできません。
4. 次の40ビットは予約済みで、すべて0でなければなりません。

非標準フォーマットは、最初の8ビットが0x00以外の160ビットのデータです。

配列フィールド

一部のトランザクションフィールド（SignerListSetトランザクションのSignerEntriesやMemosなど）はオブジェクトの配列です（「STArray」タイプと呼ばれます）。

配列には、さまざまなオブジェクトフィールドがそのネイティブバイナリフォーマットで特定の順序で含まれています。JSONでは、各配列メンバーが1つのフィールド（メンバーオブジェクトフィールドの名前）を含むJSON「ラッパー」オブジェクトです。そのフィールドの値は（「内部」）オブジェクト自体です。

バイナリフォーマットでは、配列の各メンバーにはフィールドIDプレフィクス（ラッパーオブジェクトの単一キーに基づく）と内容（オブジェクトとしてシリアル化された内部オブジェクトからなる）が含まれています。配列の終わりをマークするため、アイテムにフィールドID 0xf1（配列のタイプコードとフィールドコード1）を付加し、内容は指定しません。

以下の例は、配列のシリアル化フォーマットを示します（SignerEntriesフィールド）。

Blobフィールド

Blobタイプは、任意のデータを持つ長さプレフィクスが付加されているフィールドです。このタイプを使用する2種類の一般的なフィールドとして、SigningPubKeyとTxnSignatureがあります。これらのフィールドにはそれぞれ、トランザクションの実行を承認する公開鍵と署名が含まれています。

両方のフィールドにはこれ以上の内容構造がないため、フィールドIDと長さプレフィクスの後に可変長エンコードで示される正確なバイト数で構成されます。

ハッシュフィールド

XRP LedgerのハッシュタイプにはHash128、Hash160、Hash256があります。これらのフィールドには特定のビット数のバイナリデータが含まれており、それらのデータはハッシュ演算の結果を表す場合とそうでない場合があります。

これらのフィールドは、長さインディケーターを使用せずに、ビッグエンディアンバイトオーダーで特定数のビットとしてシリアル化されます。

Issueフィールド

いくつかのフィールドは、XRPやトークンといったアセットタイプを指定します。これらのフィールドは、1つまたは2つの160ビットから構成されています：

1. 最初の160ビットはアセットの通貨コードです。XRPの場合、これはすべて0です。
2. 最初の160ビットが全て0の場合(アセットがXRPの場合)、フィールドはそこで終了します。そうでない場合、アセットはトークンであり、次の160ビットはトークン発行者のAccountIDです。

オブジェクトフィールド

トランザクションフィールドの一部（SignerListSetトランザクションのSignerEntryやMemos配列のMemoなど）はオブジェクトです（「STObject」タイプと呼ばれます）。オブジェクトのシリアル化は配列のシリアル化に似ていますが、唯一異なる点としてオブジェクトフィールド内ではオブジェクトのメンバーを正規順序に従って配置する必要がある点があげられます。配列フィールドではすでに順序が明示的に設定されています。

オブジェクトフィールドの正規フィールド順序は、すべての最上位フィールドの正規フィールド順序と同じですが、オブジェクトのメンバーはオブジェクト内でソートする必要があります。最終メンバーの後には、「オブジェクトの終わり」を示すフィールドID（0xe1）があり、このフィールドには内容がありません。

以下の例は、オブジェクトのシリアル化フォーマットを示します（Memos配列内の1つのMemoオブジェクト）。

PathSetフィールド

クロスカレンシーのPaymentトランザクションのPathsフィールドは、JSONで配列からなる配列として表される「PathSet」です。使用されるパスについての詳細は、パスをご覧ください。

PathSetは、1～6の個別パスとして順序どおりにシリアル化されます[ソース]。それぞれの完全なパスの後には、パスの後に続く内容を示すバイトが配置されます。

• 0xffは別のパスが続くことを示します。
• 0x00はPathSetの終わりを示します。

各パスには1～8のパスステップがこの順序で含まれています[ソース]。各ステップはタイプを示すバイトで始まり、その後にパスステップを記述する1つ以上のフィールドが続きます。タイプは、ビット単位のフラグを使用してそのパスステップに含まれるフィールドを示します。（たとえば値が0x30の場合、通貨とイシュアーの両方が変更されます。）複数のフィールドが含まれている場合、フィールドは常に特定の順序で配置されます。

以下の表に、有効なフィールドと、タイプバイトでフィールドを示すために設定されるビット単位のフラグを示します。

いくつかの組み合わせは無効です。詳細は、パスの仕様をご覧ください。

accountフィールドとissuerフィールドのAccountIDには、長さプレフィクスは付加 されていません 。currencyがXRPの場合、通貨コードは160ビットのゼロとして表されます。

各ステップの直後にはパス上の次のステップが続きます。前述したように、パスの最終ステップの後には0xff（別のパスが続く場合）または0x00（これが最終パスの終わりの場合）が続きます。

以下の例は、PathSetのシリアル化フォーマットを示します。

UIntフィールド

XRP Ledgerには符号なし整数タイプUInt8、UInt16、UInt32、UInt64があります。これらのタイプはすべて、指定されたビット数の標準ビッグエンディアンバイナリー符号なし整数です。

JSONオブジェクトにこれらのフィールドが含まれている場合、ほとんどはデフォルトでJSONの数値として表されます。例外として、UInt64は文字列として表されます。これは、一部のJSONデコーダーがこれらの整数を64ビットの「倍精度」浮動小数点数として表現しようとするためです。64ビットの「倍精度」浮動小数点数では、すべてのUInt64値を完全な精度で表現することができません。

もう1つの特殊なケースとしてTransactionTypeフィールドがあります。JSONではこのフィールドは便宜上、トランザクションタイプの名前の文字列として表現されますが、バイナリではこのフィールドはUInt16です。定義ファイル内のTRANSACTION_TYPESオブジェクトにより、これらの文字列が特定の数値にマップされます。

XChainBridgeフィールド

XChainBridgeフィールドは、クロスチェーンブリッジに関連するトランザクションとレジャーエントリで使用され、XChainBridgeタイプの唯一のフィールドです。XChainBridgeフィールドは4つの要素から構成され、ブロックチェーン間のブリッジを定義します。

• ロックチェーンのドアアカウント、長さ接頭辞付きのAccountID。
• ロックチェーンの資産タイプ、STIssue。
• 発行チェーンのドアアカウント、長さ接頭辞付きのAccountID。
• 発行チェーンの資産タイプ、STIssue。

ネストされた2つのSTIssueタイプは、それぞれ160ビットまたは320ビットです。STIssueフィールドに含まれる通貨コードがすべて0の場合、STIssueフィールドは160ビットで、ブリッジされた資産がそれぞれのチェーンのネイティブ資産、例えばXRP Ledger MainnetのXRPであることを意味します。通貨コードが0でない場合、STIssueフィールドにはトークンのネイティブチェーンにおける発行者の(長さ接頭辞のない)AccountIDも含まれます。

注記: ドアアカウントのAccountIDの値は長さ接頭辞付きですが、発行者のAccountIDの値は長さ接頭辞付きではありません。

全体として、XChainBridgeフィールドは常に656、816、または976ビット（82、102、または122バイト）のいずれかになります。