Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 8 additions & 17 deletions docs/references/protocol/binary-format.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,12 @@
---
html: serialization.html
parent: protocol-reference.html
seo:
description: Conversion between JSON and canonical binary format for XRP Ledger transactions and other objects.
labels:
- Blockchain
- Transaction Sending
curated_anchors:
- name: Sample Code
anchor: "#sample-code"
- name: Canonical Field Order
anchor: "#canonical-field-order"
- name: Type List
anchor: "#type-list"
- Blockchain
- Transaction Sending
---
# Binary Format
[[Source]](https://github.com/XRPLF/rippled/blob/develop/include/xrpl/protocol/SField.h "Source")
[[Source]](https://github.com/XRPLF/rippled/blob/master/include/xrpl/protocol/SField.h "Source")

This page describes the XRP Ledger's canonical binary format for transactions and other data. This binary format is necessary to create and verify digital signatures of those transactions' contents, and is also used in other places including in the [peer-to-peer communications between servers](../../concepts/networks-and-servers/peer-protocol.md). The [`rippled` APIs](../http-websocket-apis/index.md) typically use JSON to communicate with client applications. However, JSON is unsuitable as a format for serializing transactions for being digitally signed, because JSON can represent the same data in many different but equivalent ways.

Expand Down Expand Up @@ -55,7 +46,7 @@ Both signed and unsigned transactions can be represented in both JSON and binary

The serialization processes described here are implemented in multiple places and programming languages:

- In C++ [in the `rippled` code base](https://github.com/XRPLF/rippled/blob/develop/src/ripple/protocol/impl/STObject.cpp).
- In C++ [in the `rippled` code base](https://github.com/XRPLF/rippled/blob/master/src/libxrpl/protocol/STObject.cpp).
- In JavaScript in {% repo-link path="_code-samples/tx-serialization/" %}this repository's code samples section{% /repo-link %}.
- In Python 3 in {% repo-link path="_code-samples/tx-serialization/" %}this repository's code samples section{% /repo-link %}.

Expand All @@ -65,7 +56,7 @@ Additionally, many [client libraries](../client-libraries.md) provide serializat

## Internal Format

Each field has an canonical binary format, or _internal format_ used in the XRP Ledger protocol to represent that field in transactions and ledger data. The binary format is needed for signing, but it is also used in peer-to-peer communications, in ledger storage, and in other places. The binary formats for all fields are defined in the source code of [`SField.h`](https://github.com/XRPLF/rippled/blob/develop/include/xrpl/protocol/SField.h). The JSON format for transactions and ledger data is standardized for convenience, but JSON is only used in APIs and client libraries: strictly speaking, only the binary format exists at the level of the XRP Ledger protocol.
Each field has an canonical binary format, or _internal format_ used in the XRP Ledger protocol to represent that field in transactions and ledger data. The binary format is needed for signing, but it is also used in peer-to-peer communications, in ledger storage, and in other places. The binary formats for all fields are defined in the source code of [`SField.h`](https://github.com/XRPLF/rippled/blob/master/include/xrpl/protocol/SField.h). The JSON format for transactions and ledger data is standardized for convenience, but JSON is only used in APIs and client libraries: strictly speaking, only the binary format exists at the level of the XRP Ledger protocol.

The [Transaction Format Reference](transactions/index.md) and [Ledger Data Reference](ledger-data/index.md) list both the JSON and the internal (binary) formats for all fields. For example, the `Flags` [common transaction field](transactions/common-fields.md) is a Number in JSON and a UInt32 in binary. Even though the JSON representation uses a data type that can contain decimal places or very large values, the field is limited to values that can be represented as a 32-bit unsigned integer.

Expand Down Expand Up @@ -265,7 +256,7 @@ The following diagram shows the serialization formats for all three amount forma
[{% inline-svg file="/docs/img/serialization-amount.svg" /%}](/docs/img/serialization-amount.svg 'The first bit is an amount type bit (0 = XRP or MPT, 1 = fungible token). XRP has a sign bit (always 1 for positive), an MPT indicator bit (0=XRP) and 61 bits of precision. MPTs have a sign bit (always 1 for positive), an MPT indicator bit (1=MPT), 5 reserved bits, 64 bit integer quantity, and a 192 bit MPT Issuance ID which consists of the 32-bit Sequence number followed by 160-bit issuer AccountID. Fungible Token amounts consist start with an amount type bit of 1, a sign bit which can be 1 or 0, an exponent (8 bits), significant digits (54 bits), currency code (160 bits), and issuer (160 bits).')

#### Token Amount Format
[[Source]](https://github.com/XRPLF/rippled/blob/35fa20a110e3d43ffc1e9e664fc9017b6f2747ae/src/ripple/protocol/impl/STAmount.cpp "Source")
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/libxrpl/protocol/STAmount.cpp "Source")

[{% inline-svg file="/docs/img/currency-number-format.svg" /%}](/docs/img/currency-number-format.svg "Token Amount Format diagram")

Expand Down Expand Up @@ -354,12 +345,12 @@ The following example shows the serialization format for an object (a single `Me

The `Paths` field of a cross-currency [Payment transaction][] is a "PathSet", represented in JSON as an array of arrays. For more information on what paths are used for, see [Paths](../../concepts/tokens/fungible-tokens/paths.md).

A PathSet is serialized as **1 to 6** individual paths in sequence[[Source]](https://github.com/XRPLF/rippled/blob/4cff94f7a4a05302bdf1a248515379da99c5bcd4/src/ripple/app/tx/impl/Payment.h#L35-L36 "Source"). Each complete path is followed by a byte that indicates what comes next:
A PathSet is serialized as **1 to 6** individual paths in sequence[[Source]](https://github.com/XRPLF/rippled/blob/5e33ca56fd51b02a5490e8e156e2de65937cf88e/src/xrpld/app/tx/detail/Payment.h#L30 "Source"). Each complete path is followed by a byte that indicates what comes next:

- `0xff` indicates another path follows
- `0x00` indicates the end of the PathSet

Each path consists of **1 to 8** path steps in order[[Source]](https://github.com/XRPLF/rippled/blob/4cff94f7a4a05302bdf1a248515379da99c5bcd4/src/ripple/app/tx/impl/Payment.h#L38-L39 "Source"). Each step starts with a **type** byte, followed by one or more fields describing the path step. The type indicates which fields are present in that path step through bitwise flags. (For example, the value `0x30` indicates changing both currency and issuer.) If more than one field is present, the fields are always placed in a specific order.
Each path consists of **1 to 8** path steps in order[[Source]](https://github.com/XRPLF/rippled/blob/5e33ca56fd51b02a5490e8e156e2de65937cf88e/src/xrpld/app/tx/detail/Payment.h#L33 "Source"). Each step starts with a **type** byte, followed by one or more fields describing the path step. The type indicates which fields are present in that path step through bitwise flags. (For example, the value `0x30` indicates changing both currency and issuer.) If more than one field is present, the fields are always placed in a specific order.

The following table describes the possible fields and the bitwise flags to set in the type byte to indicate them:

Expand Down
2 changes: 1 addition & 1 deletion docs/references/protocol/data-types/basic-data-types.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Each closed [Ledger](../ledger-data/index.md) has a [Ledger Index][] and a [Hash


### Hash Prefixes
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/HashPrefix.h "Source")
[[Source]](https://github.com/XRPLF/rippled/blob/master/include/xrpl/protocol/HashPrefix.h "Source")

In many cases, the XRP Ledger prefixes an object's binary data with a 4-byte code before calculating its hash, so that objects of different types have different hashes even if their binary formats are the same. The existing 4-byte codes are structured as three alphabetic characters, encoded as ASCII, followed by a zero byte.

Expand Down
7 changes: 3 additions & 4 deletions docs/references/protocol/ledger-data/common-fields.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
---
html: ledger-entry-common-fields.html
seo:
description: These common fields are part of every ledger entry.
---
# Ledger Entry Common Fields
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/LedgerFormats.cpp)
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/libxrpl/protocol/LedgerFormats.cpp)

Every entry in a [ledger](../../../concepts/ledgers/index.md)'s state data has the same set of common fields, plus additional fields based on the [ledger entry type](ledger-entry-types/index.md). Field names are case-sensitive. The common fields for all ledger entries are:

Expand All @@ -19,9 +18,9 @@ Every entry in a [ledger](../../../concepts/ledgers/index.md)'s state data has t

## Ledger Entry ID

[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/Indexes.cpp)
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/libxrpl/protocol/Indexes.cpp)

Each ledger entry has a unique ID. The ID is derived by hashing important contents of the entry, along with a [namespace identifier](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/LedgerFormats.h). The [ledger entry type](ledger-entry-types/index.md) determines the namespace identifier to use and which contents to include in the hash. This ensures every ID is unique. The hash function is [SHA-512Half][].
Each ledger entry has a unique ID. The ID is derived by hashing important contents of the entry, along with a _namespace identifier_ which is a 16 bit value. The [ledger entry type](ledger-entry-types/index.md) determines the namespace identifier to use and which contents to include in the hash. This ensures every ID is unique. The hash function is [SHA-512Half][].

Generally, a ledger entry's ID is returned as the `index` field in JSON, at the same level as the object's contents. In [transaction metadata](../transactions/metadata.md), the ledger object's ID in JSON is `LedgerIndex`.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ In addition to the [common fields](../common-fields.md), {% code-page-name /%} e
| `AMMID` | String | UInt256 | No | {% amendment-disclaimer name="AMM" /%} The ledger entry ID of the corresponding AMM ledger entry. Set during account creation; cannot be modified. If present, indicates that this is a special AMM AccountRoot; always omitted on non-AMM accounts. |
| `Balance` | String | Amount | No | The account's current [XRP balance in drops][XRP, in drops], represented as a string. |
| `BurnedNFTokens` | Number | UInt32 | No | How many total of this account's issued [non-fungible tokens](../../../../concepts/tokens/nfts/index.md) have been burned. This number is always equal or less than `MintedNFTokens`. |
| `Domain` | String | Blob | No | A domain associated with this account. In JSON, this is the hexadecimal for the ASCII representation of the domain. [Cannot be more than 256 bytes in length.](https://github.com/xrplf/rippled/blob/55dc7a252e08a0b02cd5aa39e9b4777af3eafe77/src/ripple/app/tx/impl/SetAccount.h#L34) |
| `Domain` | String | Blob | No | A domain associated with this account. In JSON, this is the hexadecimal for the ASCII representation of the domain. [Cannot be more than 256 bytes in length.](https://github.com/XRPLF/rippled/blob/70d5c624e8cf732a362335642b2f5125ce4b43c1/include/xrpl/protocol/Protocol.h#L98) |
| `EmailHash` | String | UInt128 | No | The md5 hash of an email address. Clients can use this to look up an avatar through services such as [Gravatar](https://en.gravatar.com/). |
| `FirstNFTokenSequence` | Number | UInt32 | No | The account's [Sequence Number][] at the time it minted its first [non-fungible-token](../../../../concepts/tokens/nfts/index.md). {% amendment-disclaimer name="fixNFTokenRemint" /%} |
| `LedgerEntryType` | String | UInt16 | Yes | The value `0x0061`, mapped to the string `AccountRoot`, indicates that this is an AccountRoot object. |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ There are no flags defined for {% code-page-name /%} entries.


## Check ID Format
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/Indexes.cpp#L193-L200 "Source")
[[Source]](https://github.com/XRPLF/rippled/blob/70d5c624e8cf732a362335642b2f5125ce4b43c1/src/libxrpl/protocol/Indexes.cpp#L335-L339 "Source")

The ID of a `Check` entry is the [SHA-512Half][] of the following values, concatenated in order:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ There are no flags defined for {% code-page-name /%} entries.


## LedgerHashes ID Formats
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/Indexes.cpp#L26-L42)
[[Source]](https://github.com/XRPLF/rippled/blob/70d5c624e8cf732a362335642b2f5125ce4b43c1/src/libxrpl/protocol/Indexes.cpp#L195-L211)

There are two formats for `LedgerHashes` ledger entry IDs, depending on whether the entry is a "recent history" sub-type or a "previous history" sub-type.

Expand Down
2 changes: 1 addition & 1 deletion docs/references/protocol/ledger-data/ledger-header.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ labels:
- Blockchain
---
# Ledger Header
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/ledger/ReadView.h#L71 "Source")
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/xrpld/app/consensus/RCLCxLedger.h "Source")

Every [ledger version](../../../concepts/ledgers/index.md) has a unique header that describes the contents. You can look up a ledger's header information with the [ledger method][]. The contents of the ledger header are as follows:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ labels:
---
# Transaction Results

[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/TER.h "Source")
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/libxrpl/protocol/TER.cpp "Source")

The `rippled` server summarizes transaction results with result codes, which appear in fields such as `engine_result` and `meta.TransactionResult`. These codes are grouped into several categories of with different prefixes:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ labels:
- Transaction Sending
---
# tec Codes
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/TER.cpp "Source")
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/libxrpl/protocol/TER.cpp "Source")

These codes indicate that the transaction did not succeed, but it was applied to a ledger to apply the [transaction cost](../../../../concepts/transactions/transaction-cost.md) and may have had other side effects to the ledger. The `tec` codes have numerical values in the range 100 to 199. It is recommended to use the text code, not the numeric value.

Expand Down
2 changes: 1 addition & 1 deletion docs/references/protocol/transactions/types/accountset.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Modify the settings or properties of an [account in the XRP Ledger](../../../../
| Field | JSON Type | [Internal Type][] | Description |
|:-----------------|:-----------------|:------------------|:-------------------|
| [`ClearFlag`](#accountset-flags) | Number | UInt32 | Unique identifier of a flag to disable for this account. |
| [`Domain`](#domain) | String | Blob | The domain that owns this account, as a string of hex representing the ASCII for the domain in lowercase. [Cannot be more than 256 bytes in length.](https://github.com/XRPLF/rippled/blob/55dc7a252e08a0b02cd5aa39e9b4777af3eafe77/src/ripple/app/tx/impl/SetAccount.h#L34) |
| [`Domain`](#domain) | String | Blob | The domain that owns this account, as a string of hex representing the ASCII for the domain in lowercase. [Cannot be more than 256 bytes in length.](https://github.com/XRPLF/rippled/blob/70d5c624e8cf732a362335642b2f5125ce4b43c1/include/xrpl/protocol/Protocol.h#L98) |
| `EmailHash` | String | UInt128 | An arbitrary 128-bit value. Conventionally, clients treat this as the md5 hash of an email address to use for displaying a [Gravatar](http://en.gravatar.com/site/implement/hash/) image. |
| `MessageKey` | String | Blob | Public key for sending encrypted messages to this account. To set the key, it must be exactly 33 bytes, with the first byte indicating the key type: `0x02` or `0x03` for secp256k1 keys, `0xED` for Ed25519 keys. To remove the key, use an empty value. |
| `NFTokenMinter` | String - [Address][] | AccountID | Another account that can [mint NFTokens for you](../../../../tutorials/javascript/nfts/assign-an-authorized-minter.md). {% amendment-disclaimer name="NonFungibleTokensV1_1" /%} |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ labels:
---
# SetRegularKey

[[Source]](https://github.com/XRPLF/rippled/blob/4239880acb5e559446d2067f00dabb31cf102a23/src/ripple/app/transactors/SetRegularKey.cpp "Source")
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/xrpld/app/tx/detail/SetRegularKey.cpp "Source")

Assign, change, or remove the [regular key pair](../../../../concepts/accounts/cryptographic-keys.md) associated with your account.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ labels:
status: not_enabled
---
# XChainAccountCreateCommit
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/TxFormats.cpp#L466-L474 "Source")
[[Source]](https://github.com/XRPLF/rippled/blob/70d5c624e8cf732a362335642b2f5125ce4b43c1/src/xrpld/app/tx/detail/XChainBridge.h#L235 "Source")

Create a new account for a [witness server](../../../../concepts/xrpl-sidechains/witness-servers.md) to submit transactions on an issuing chain. This transaction can only be used for XRP-XRP bridges.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ labels:
status: not_enabled
---
# XChainAddAccountCreateAttestation
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/TxFormats.cpp#L447-L464 "Source")
[[Source]](https://github.com/XRPLF/rippled/blob/70d5c624e8cf732a362335642b2f5125ce4b43c1/src/xrpld/app/tx/detail/XChainBridge.h#L189 "Source")

Provide an attestation from a [witness server](../../../../concepts/xrpl-sidechains/witness-servers.md) that an `XChainAccountCreateCommit` transaction occurred on the other chain.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ labels:
status: not_enabled
---
# XChainAddClaimAttestation
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/TxFormats.cpp#L429-L445 "Source")
[[Source]](https://github.com/XRPLF/rippled/blob/70d5c624e8cf732a362335642b2f5125ce4b43c1/src/xrpld/app/tx/detail/XChainBridge.h#L169 "Source")

Provide proof from a [witness server](../../../../concepts/xrpl-sidechains/witness-servers.md) attesting to an `XChainCommit` transaction.

Expand Down