mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-04 11:55:50 +00:00
Update links in protocol references
This commit is contained in:
mDuo13
@@ -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.
|
||||
|
||||
@@ -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 %}.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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")
|
||||
|
||||
@@ -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:
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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`.
|
||||
|
||||
|
||||
@@ -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. |
|
||||
|
||||
@@ -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:
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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" /%} |
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user