From 08558478e454e6acce22475e0b99a600c3f4f403 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Mon, 7 Jul 2025 14:33:40 -0700 Subject: [PATCH] Binary format: edits per review --- .../tx-serialization/py/serialize.py | 4 +- docs/img/_sources/serialization-amount.uxf | 438 +++++++++++++---- docs/img/serialization-amount.svg | 452 ++++++++++++------ docs/references/protocol/binary-format.md | 22 +- 4 files changed, 677 insertions(+), 239 deletions(-) diff --git a/_code-samples/tx-serialization/py/serialize.py b/_code-samples/tx-serialization/py/serialize.py index c8ca3ad276..e4dd1214c1 100755 --- a/_code-samples/tx-serialization/py/serialize.py +++ b/_code-samples/tx-serialization/py/serialize.py @@ -407,8 +407,8 @@ def uint192_to_bytes(i): def uint384_to_bytes(i): b = hex_to_bytes(i) - if len(b) != 8: # 8 bytes = 64 bits - raise ValueError("UInt64 is not 64 bits long") + if len(b) != 48: # 48 bytes = 384 bits + raise ValueError("UInt384 is not 384 bits long") return b def vector256_to_bytes(strlist): diff --git a/docs/img/_sources/serialization-amount.uxf b/docs/img/_sources/serialization-amount.uxf index 61b7d4d3fd..286f5482d9 100644 --- a/docs/img/_sources/serialization-amount.uxf +++ b/docs/img/_sources/serialization-amount.uxf @@ -5,7 +5,7 @@ UMLClass 40 - 270 + 560 20 30 @@ -16,7 +16,7 @@ UMLClass 70 - 270 + 560 20 30 @@ -27,7 +27,7 @@ UMLClass 100 - 270 + 560 150 30 @@ -38,7 +38,7 @@ UMLClass 260 - 270 + 560 190 30 @@ -49,7 +49,7 @@ Relation 70 - 290 + 580 50 60 @@ -60,7 +60,7 @@ Text 100 - 320 + 610 260 30 @@ -72,12 +72,12 @@ style=wordwrap Text 80 - 350 + 640 160 60 - "Not XRP" bit -(0=XRP, 1=not XRP) + Amount type bit +(0=XRP or MPT, 1=fungible token) style=wordwrap @@ -85,7 +85,7 @@ style=wordwrap Relation 40 - 290 + 580 50 90 @@ -96,7 +96,7 @@ style=wordwrap UMLClass 460 - 270 + 560 200 30 @@ -107,18 +107,18 @@ style=wordwrap UMLClass 670 - 270 - 200 + 560 + 220 30 - issuer AccountID (160 bits) + issuer's AccountID (160 bits) UMLClass 40 - 510 + 800 20 30 @@ -129,7 +129,7 @@ style=wordwrap Relation 40 - 520 + 810 60 70 @@ -140,7 +140,7 @@ style=wordwrap Text 80 - 560 + 850 300 40 @@ -152,29 +152,29 @@ style=wordwrap UMLClass 70 - 510 + 800 220 30 - Reserved (88 bits) + reserved (88 bits) UMLClass 460 - 510 + 800 180 30 - Reserved (40 bits) + reserved (40 bits) UMLClass 300 - 510 + 800 150 30 @@ -185,7 +185,7 @@ style=wordwrap Relation 310 - 530 + 820 40 50 @@ -196,7 +196,7 @@ style=wordwrap Text 330 - 550 + 840 130 30 @@ -207,7 +207,7 @@ style=wordwrap Relation 20 - 290 + 580 460 230 @@ -218,7 +218,7 @@ style=wordwrap Relation 640 - 290 + 580 40 230 @@ -228,7 +228,7 @@ style=wordwrap UMLClass - 40 + 30 60 20 30 @@ -239,7 +239,7 @@ style=wordwrap UMLClass - 70 + 60 60 20 30 @@ -247,11 +247,192 @@ style=wordwrap 1 + + Text + + 90 + 120 + 260 + 30 + + Sign bit (always 1 for positive) +style=wordwrap + + + + Relation + + 60 + 80 + 50 + 70 + + lt=<<- + 10.0;10.0;10.0;50.0;30.0;50.0 + + + Text + + 70 + 140 + 160 + 60 + + Amount type bit +(0=XRP or MPT, 1=fungible token) +style=wordwrap + + + + Relation + + 30 + 80 + 60 + 110 + + lt=<<- + 10.0;10.0;10.0;90.0;40.0;90.0 + + + UMLClass + + 120 + 60 + 510 + 30 + + integer drops (61 bits) + + + + UMLClass + + 20 + 50 + 620 + 50 + + + + + + Text + + 20 + 20 + 190 + 30 + + *XRP Amount Format* + + + + Text + + 30 + 520 + 310 + 30 + + *Fungible Token Amount Format* + + + + UMLClass + + 30 + 550 + 870 + 50 + + + + + + Text + + 90 + 760 + 240 + 30 + + Standard Currency Code Format + + + + UMLClass + + 30 + 790 + 620 + 50 + + + + + + Text + + 20 + 240 + 190 + 30 + + *MPT Amount Format* + + + + UMLClass + + 30 + 270 + 670 + 50 + + + + + + UMLClass + + 40 + 280 + 20 + 30 + + 0 + + + + Text + + 80 + 380 + 160 + 60 + + Amount type bit +(0=XRP or MPT, 1=fungible token) +style=wordwrap + + + + Relation + + 40 + 300 + 60 + 130 + + lt=<<- + 10.0;10.0;10.0;110.0;40.0;110.0 + Text 100 - 110 + 350 260 30 @@ -263,7 +444,52 @@ style=wordwrap Relation 70 - 80 + 300 + 50 + 80 + + lt=<<- + 10.0;10.0;10.0;60.0;30.0;60.0 + + + UMLClass + + 70 + 280 + 20 + 30 + + 1 + + + + UMLClass + + 100 + 280 + 20 + 30 + + 1 + + + + Text + + 130 + 330 + 260 + 30 + + MPT indicator bit (1=MPT, 0=XRP) +style=wordwrap + + + + Relation + + 100 + 300 50 60 @@ -271,104 +497,136 @@ style=wordwrap 10.0;10.0;10.0;40.0;30.0;40.0 - Text + UMLClass - 80 - 140 - 160 - 60 + 90 + 60 + 20 + 30 - "Not XRP" bit -(0=XRP, 1=not XRP) -style=wordwrap + 0 Relation - 40 + 90 80 50 - 90 + 50 lt=<<- - 10.0;10.0;10.0;70.0;30.0;70.0 + 10.0;10.0;10.0;30.0;30.0;30.0 - UMLClass + Text - 100 - 60 - 540 + 120 + 100 + 260 30 - integer drops (62 bits) + MPT indicator bit (1=MPT, 0=XRP) +style=wordwrap UMLClass - 30 - 50 - 620 + 130 + 280 + 140 + 30 + + reserved (5 bits) + + + + UMLClass + + 280 + 280 + 190 + 30 + + integer quantity (64 bits) + + + + UMLClass + + 480 + 280 + 210 + 30 + + MPT issuance ID (192 bits) + + + + UMLClass + + 390 + 390 + 510 50 - Text + Relation - 30 - 20 - 160 + 380 + 300 + 120 + 110 + + lt=.. + 10.0;90.0;100.0;10.0 + + + Relation + + 680 + 300 + 210 + 110 + + lt=.. + 190.0;90.0;10.0;10.0 + + + UMLClass + + 400 + 400 + 210 30 - XRP Amount Format + Sequence number (32 bits) + + + + UMLClass + + 620 + 400 + 270 + 30 + + issuer's AccountID (160 bits) Text - 30 - 230 + 430 + 360 240 30 - Token Amount Format - - - - UMLClass - - 30 - 260 - 850 - 50 - - - - - - Text - - 90 - 470 - 240 - 30 - - Standard Currency Code Format - - - - UMLClass - - 30 - 500 - 620 - 50 - - + MPT Issuance ID Format diff --git a/docs/img/serialization-amount.svg b/docs/img/serialization-amount.svg index 601e8cf0c3..3297d25434 100644 --- a/docs/img/serialization-amount.svg +++ b/docs/img/serialization-amount.svg @@ -1,7 +1,7 @@ -MPT Issuance ID Formatissuer's AccountID (160 bits)Sequence number (32 bits)MPT issuance ID (192 bits)integer quantity (64 bits)reserved (5 bits)MPT indicator bit (1=MPT, 0=XRP)0MPT indicator bit (1=MPT, 0=XRP)11Sign bit (always 1 for positive)Amount type bit(0=XRP or MPT,1=fungible token)0MPT Amount FormatStandard Currency Code FormatToken Amount FormatFungible Token Amount FormatXRP Amount Formatinteger drops (62 bits)integer drops (61 bits)"Not XRP" bit(0=XRP, 1=not XRP)Amount type bit(0=XRP or MPT,1=fungible token)Sign bit (always 1 for positive)03 chars of ASCIIISO code (24 bits)Reserved (40 bits)reserved (40 bits)Reserved (88 bits)reserved (88 bits)Type code (8 bits)0x00 for ISO 4217/pseudo-ISO currency00issuer AccountID (160 bits)issuer's AccountID (160 bits)currency code (160 bits)"Not XRP" bit(0=XRP, 1=not XRP)Amount type bit(0=XRP or MPT,1=fungible token)Sign bit (0=negative, 1=positive)significant digits (54 bits)exponent (8 bits)163-1.) - 3. 32 bits indicating the `Sequence` number of the transaction that created the MPT issuance. - 4. 160 bits indicating the [AccountID][] of the MPT's issuer. + 3. 192 bits for the MPT Issuance ID, which is made of the following parts in order: + 1. 32 bits indicating the `Sequence` number of the transaction that created the MPT issuance. + 2. 160 bits indicating the [AccountID][] of the MPT's issuer. You can tell which of the three sub-types an amount is based on the first and third most significant bits: @@ -259,9 +260,9 @@ You can tell which of the three sub-types an amount is based on the first and th Not all types of amount are valid in all places. Some fields can only represent XRP, or XRP and fungible tokens but not MPTs. These limitations are defined by the individual transactions and ledger entries. {% /admonition %} -The following diagram shows the serialization formats for both XRP amounts and token amounts: ***TODO: update*** +The following diagram shows the serialization formats for all three amount formats: -[{% inline-svg file="/docs/img/serialization-amount.svg" /%}](/docs/img/serialization-amount.svg 'XRP amounts have a "not XRP" bit, a sign bit, and 62 bits of precision. Token amounts consist of a "not XRP" bit, a sign bit, an exponent (8 bits), significant digits (54 bits), currency code (160 bits), and issuer (160 bits).') +[{% 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") @@ -296,9 +297,6 @@ The [`rippled` APIs](../http-websocket-apis/index.md) support a **standard forma The **nonstandard format** is any 160 bits of data as long as the first 8 bits are not `0x00`. -#### MPT Amount Format - -The following diagram shows the amount serialization for MPTs. ***TODO: consolidate or not?*** ### Array Fields [Array]: #array-fields @@ -325,9 +323,9 @@ Blob fields have no further structure to their contents, so they consist of exac ### Currency Fields [Currency]: #currency-fields -Some fields specify a currency code, which could be an a fungible token, the ticker symbol for an off-ledger asset, or some other identifier for a currency. This field type is currently used only in [Price Oracles](../../concepts/decentralized-storage/price-oracles.md). +Some fields specify a currency code, which could be a fungible token, the ticker symbol for an off-ledger asset, or some other identifier for a currency. This field type is currently used only in [Price Oracles](../../concepts/decentralized-storage/price-oracles.md). -These fields consists of 160 bits of binary data. If the data matches the ["standard" currency code format](#currency-codes), it may be represented as a three-letter currency code string in JSON. Otherwise, it is represented as hexadecimal. Client libraries _may_ attempt to interpret this as a string of ASCII or UTF-8, but it is not guaranteed to be valid. +These fields consist of 160 bits of binary data. If the data matches the ["standard" currency code format](#currency-codes), it may be represented as a three-letter currency code string in JSON. Otherwise, it is represented as hexadecimal. Client libraries _may_ attempt to interpret this as a string of ASCII or UTF-8, but it is not guaranteed to be valid. The {% repo-link path="_code-samples/normalize-currency-codes/" %}Normalize Currency Codes code sample{% /repo-link %} demonstrates best practices for converting most common formats for this data into a string for humans to read. ### Issue Fields