ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-20 03:35:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

Amount diagram; standardize diagrams; link example code

Browse Source
This commit is contained in:
mDuo13
2018-11-29 15:33:25 -08:00
parent af35d5a4d9
commit 1904ce1de9
7 changed files with 422 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

341
content/_img-sources/serialization-amount.uxf Normal file
View File

@@ -0,0 +1,341 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<diagram program="umlet" version="14.2">
<zoom_level>10</zoom_level>
<element>
<id>UMLPackage</id>
<coordinates>
<x>30</x>
<y>240</y>
<w>850</w>
<h>70</h>
</coordinates>
<panel_attributes>Issued Currency Amount Format</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>40</x>
<y>270</y>
<w>20</w>
<h>30</h>
</coordinates>
<panel_attributes>1</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>70</x>
<y>270</y>
<w>20</w>
<h>30</h>
</coordinates>
<panel_attributes/>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>100</x>
<y>270</y>
<w>150</w>
<h>30</h>
</coordinates>
<panel_attributes>exponent (8 bits)</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>260</x>
<y>270</y>
<w>190</w>
<h>30</h>
</coordinates>
<panel_attributes>mantissa (54 bits)</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>70</x>
<y>290</y>
<w>50</w>
<h>60</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;10.0;40.0;30.0;40.0</additional_attributes>
</element>
<element>
<id>Text</id>
<coordinates>
<x>100</x>
<y>320</y>
<w>260</w>
<h>30</h>
</coordinates>
<panel_attributes>Sign bit (0=negative, 1=positive)
style=wordwrap</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Text</id>
<coordinates>
<x>80</x>
<y>350</y>
<w>160</w>
<h>60</h>
</coordinates>
<panel_attributes>"Not XRP" bit
(0=XRP, 1=not XRP)
style=wordwrap</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>40</x>
<y>290</y>
<w>50</w>
<h>90</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;10.0;70.0;30.0;70.0</additional_attributes>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>460</x>
<y>270</y>
<w>200</w>
<h>30</h>
</coordinates>
<panel_attributes>currency code (160 bits)</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>670</x>
<y>270</y>
<w>200</w>
<h>30</h>
</coordinates>
<panel_attributes>issuer AccountID (160 bits)</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>40</x>
<y>510</y>
<w>20</w>
<h>30</h>
</coordinates>
<panel_attributes>00</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>40</x>
<y>520</y>
<w>60</w>
<h>70</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;10.0;50.0;40.0;50.0</additional_attributes>
</element>
<element>
<id>Text</id>
<coordinates>
<x>80</x>
<y>560</y>
<w>300</w>
<h>40</h>
</coordinates>
<panel_attributes>Type code (8 bits)
0x00 for ISO 4217/pseudo-ISO currency</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>70</x>
<y>510</y>
<w>220</w>
<h>30</h>
</coordinates>
<panel_attributes>Reserved (88 bits)</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>460</x>
<y>510</y>
<w>180</w>
<h>30</h>
</coordinates>
<panel_attributes>Reserved (40 bits)</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>300</x>
<y>510</y>
<w>150</w>
<h>30</h>
</coordinates>
<panel_attributes>ISO code (24 bits)</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLPackage</id>
<coordinates>
<x>30</x>
<y>480</y>
<w>620</w>
<h>70</h>
</coordinates>
<panel_attributes>Issued Currency Code Format</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>310</x>
<y>530</y>
<w>40</w>
<h>50</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;10.0;30.0;20.0;30.0</additional_attributes>
</element>
<element>
<id>Text</id>
<coordinates>
<x>330</x>
<y>550</y>
<w>130</w>
<h>30</h>
</coordinates>
<panel_attributes>3 chars of ASCII</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>20</x>
<y>290</y>
<w>460</w>
<h>210</h>
</coordinates>
<panel_attributes>lt=..</panel_attributes>
<additional_attributes>10.0;190.0;440.0;10.0</additional_attributes>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>640</x>
<y>290</y>
<w>40</w>
<h>230</h>
</coordinates>
<panel_attributes>lt=..</panel_attributes>
<additional_attributes>10.0;210.0;20.0;10.0</additional_attributes>
</element>
<element>
<id>UMLPackage</id>
<coordinates>
<x>30</x>
<y>30</y>
<w>620</w>
<h>70</h>
</coordinates>
<panel_attributes>XRP Amount Format</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>40</x>
<y>60</y>
<w>20</w>
<h>30</h>
</coordinates>
<panel_attributes>0</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>70</x>
<y>60</y>
<w>20</w>
<h>30</h>
</coordinates>
<panel_attributes>1</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Text</id>
<coordinates>
<x>100</x>
<y>110</y>
<w>260</w>
<h>30</h>
</coordinates>
<panel_attributes>Sign bit (always 1 for positive)
style=wordwrap</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>70</x>
<y>80</y>
<w>50</w>
<h>60</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;10.0;40.0;30.0;40.0</additional_attributes>
</element>
<element>
<id>Text</id>
<coordinates>
<x>80</x>
<y>140</y>
<w>160</w>
<h>60</h>
</coordinates>
<panel_attributes>"Not XRP" bit
(0=XRP, 1=not XRP)
style=wordwrap</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>40</x>
<y>80</y>
<w>50</w>
<h>90</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;10.0;70.0;30.0;70.0</additional_attributes>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>100</x>
<y>60</y>
<w>540</w>
<h>30</h>
</coordinates>
<panel_attributes>integer drops (62 bits)</panel_attributes>
<additional_attributes/>
</element>
</diagram>

22
content/_img-sources/serialization-array.uxf
View File

@@ -1,17 +1,6 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <?xml version="1.0" encoding="UTF-8" standalone="no"?>
<diagram program="umlet" version="14.2"> <diagram program="umlet" version="14.2">
<zoom_level>10</zoom_level> <zoom_level>10</zoom_level>
<element>
<id>UMLClass</id>
<coordinates>
<x>130</x>
<y>110</y>
<w>600</w>
<h>50</h>
</coordinates>
<panel_attributes/>
<additional_attributes/>
</element>
<element> <element>
<id>UMLClass</id> <id>UMLClass</id>
<coordinates> <coordinates>
@@ -148,4 +137,15 @@ Field ID</panel_attributes>
<panel_attributes>(SignerEntry Contents)</panel_attributes> <panel_attributes>(SignerEntry Contents)</panel_attributes>
<additional_attributes/> <additional_attributes/>
</element> </element>
<element>
<id>UMLPackage</id>
<coordinates>
<x>130</x>
<y>90</y>
<w>600</w>
<h>70</h>
</coordinates>
<panel_attributes>SignerEntries field</panel_attributes>
<additional_attributes/>
</element>
</diagram> </diagram>

119
content/_img-sources/serialization-object.uxf
View File

@@ -1,17 +1,6 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <?xml version="1.0" encoding="UTF-8" standalone="no"?>
<diagram program="umlet" version="14.2"> <diagram program="umlet" version="14.2">
<zoom_level>10</zoom_level> <zoom_level>10</zoom_level>
<element>
<id>UMLClass</id>
<coordinates>
<x>80</x>
<y>160</y>
<w>600</w>
<h>50</h>
</coordinates>
<panel_attributes/>
<additional_attributes/>
</element>
<element> <element>
<id>UMLClass</id> <id>UMLClass</id>
<coordinates> <coordinates>
@@ -73,17 +62,17 @@ Field ID</panel_attributes>
<coordinates> <coordinates>
<x>630</x> <x>630</x>
<y>190</y> <y>190</y>
<w>30</w> <w>80</w>
<h>80</h> <h>60</h>
</coordinates> </coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes> <panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;10.0;60.0</additional_attributes> <additional_attributes>10.0;10.0;10.0;30.0;60.0;30.0;60.0;40.0</additional_attributes>
</element> </element>
<element> <element>
<id>Text</id> <id>Text</id>
<coordinates> <coordinates>
<x>590</x> <x>640</x>
<y>250</y> <y>230</y>
<w>100</w> <w>100</w>
<h>60</h> <h>60</h>
</coordinates> </coordinates>
@@ -109,22 +98,10 @@ no contents</panel_attributes>
<x>160</x> <x>160</x>
<y>190</y> <y>190</y>
<w>50</w> <w>50</w>
<h>80</h> <h>60</h>
</coordinates> </coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes> <panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;10.0;60.0;30.0;60.0</additional_attributes> <additional_attributes>10.0;10.0;10.0;40.0;30.0;40.0</additional_attributes>
</element>
<element>
<id>Text</id>
<coordinates>
<x>220</x>
<y>120</y>
<w>190</w>
<h>50</h>
</coordinates>
<panel_attributes>Length prefix for
variable-length Blob fields</panel_attributes>
<additional_attributes/>
</element> </element>
<element> <element>
<id>UMLClass</id> <id>UMLClass</id>
@@ -148,22 +125,11 @@ variable-length Blob fields</panel_attributes>
<panel_attributes/> <panel_attributes/>
<additional_attributes/> <additional_attributes/>
</element> </element>
<element>
<id>Relation</id>
<coordinates>
<x>190</x>
<y>130</y>
<w>50</w>
<h>60</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;40.0;10.0;10.0;30.0;10.0</additional_attributes>
</element>
<element> <element>
<id>Text</id> <id>Text</id>
<coordinates> <coordinates>
<x>190</x> <x>190</x>
<y>230</y> <y>210</y>
<w>110</w> <w>110</w>
<h>50</h> <h>50</h>
</coordinates> </coordinates>
@@ -193,33 +159,22 @@ Field ID</panel_attributes>
<panel_attributes/> <panel_attributes/>
<additional_attributes/> <additional_attributes/>
</element> </element>
<element>
<id>Relation</id>
<coordinates>
<x>400</x>
<y>130</y>
<w>70</w>
<h>60</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>50.0;40.0;50.0;10.0;10.0;10.0</additional_attributes>
</element>
<element> <element>
<id>Relation</id> <id>Relation</id>
<coordinates> <coordinates>
<x>130</x> <x>130</x>
<y>80</y> <y>210</y>
<w>490</w> <w>500</w>
<h>90</h> <h>90</h>
</coordinates> </coordinates>
<panel_attributes>lt=.</panel_attributes> <panel_attributes>lt=.</panel_attributes>
<additional_attributes>10.0;60.0;10.0;20.0;220.0;20.0;220.0;10.0;220.0;20.0;470.0;20.0;470.0;70.0</additional_attributes> <additional_attributes>10.0;10.0;10.0;70.0;480.0;70.0;480.0;10.0</additional_attributes>
</element> </element>
<element> <element>
<id>Text</id> <id>Text</id>
<coordinates> <coordinates>
<x>290</x> <x>300</x>
<y>40</y> <y>280</y>
<w>170</w> <w>170</w>
<h>50</h> <h>50</h>
</coordinates> </coordinates>
@@ -230,24 +185,56 @@ style=wordwrap</panel_attributes>
<element> <element>
<id>Text</id> <id>Text</id>
<coordinates> <coordinates>
<x>340</x> <x>290</x>
<y>230</y> <y>230</y>
<w>110</w> <w>150</w>
<h>50</h> <h>30</h>
</coordinates> </coordinates>
<panel_attributes>MemoData <panel_attributes>MemoData Field ID</panel_attributes>
Field ID</panel_attributes>
<additional_attributes/> <additional_attributes/>
</element> </element>
<element> <element>
<id>Relation</id> <id>Relation</id>
<coordinates> <coordinates>
<x>390</x> <x>350</x>
<y>190</y> <y>190</y>
<w>30</w> <w>70</w>
<h>60</h> <h>60</h>
</coordinates> </coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes> <panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;10.0;40.0</additional_attributes> <additional_attributes>50.0;10.0;50.0;30.0;10.0;30.0;10.0;40.0</additional_attributes>
</element>
<element>
<id>UMLPackage</id>
<coordinates>
<x>80</x>
<y>140</y>
<w>600</w>
<h>70</h>
</coordinates>
<panel_attributes>Memos field</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>430</x>
<y>190</y>
<w>50</w>
<h>50</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;10.0;30.0;30.0;30.0</additional_attributes>
</element>
<element>
<id>Text</id>
<coordinates>
<x>460</x>
<y>210</y>
<w>140</w>
<h>40</h>
</coordinates>
<panel_attributes>Length prefix</panel_attributes>
<additional_attributes/>
</element> </element>
</diagram> </diagram>

19
content/references/rippled-api/api-conventions/serialization.md
View File

@@ -1,5 +1,5 @@
# Serialization Format # Serialization Format
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/impl/STObject.cpp#L697-L718 "Source") [[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/impl/STObject.cpp#L696-L718 "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. The [rippled APIs](rippled-apis.html) 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. 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. The [rippled APIs](rippled-apis.html) 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.
@@ -18,6 +18,17 @@ The result is a single binary blob that can be signed using well-known signature
**Note:** The XRP Ledger uses the same serialization format to represent other types of data, such as [ledger objects](ledger-object-types.html) and processed transactions. However, only certain fields are appropriate for including in a transaction that gets signed. (For example, the `TxnSignature` field, containing the signature itself, should not be present in the binary blob that you sign.) Thus, some fields are designated as "Signing" fields, which are included in objects when those objects are signed, and "non-signing" fields, which are not. **Note:** The XRP Ledger uses the same serialization format to represent other types of data, such as [ledger objects](ledger-object-types.html) and processed transactions. However, only certain fields are appropriate for including in a transaction that gets signed. (For example, the `TxnSignature` field, containing the signature itself, should not be present in the binary blob that you sign.) Thus, some fields are designated as "Signing" fields, which are included in objects when those objects are signed, and "non-signing" fields, which are not.
## Sample Code
The serialization processes described here are implemented in multiple places and programming languages:
- In C++ [in the `rippled` code base](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/impl/STObject.cpp).
- In JavaScript in the [`ripple-binary-codec`](https://github.com/ripple/ripple-binary-codec/) package.
- In Python 3 [this repository's code samples section]({{target.github_forkurl}}/blob/{{target.github_branch}}/content/_code-samples/tx-serialization/serialize.py).
These implementations are all provided with permissive open-source licenses, so you can import, use, or adapt the code for your needs in addition to using it alongside these documents for learning purposes.
## Internal Format ## Internal Format
@@ -165,7 +176,7 @@ AccountIDs that appear as stand-alone fields (such as `Account` and `Destination
The "Amount" type is a special field type that represents an amount of currency, either XRP or an issued currency. This type consists of two sub-types: The "Amount" type is a special field type that represents an amount of currency, either XRP or an issued currency. This type consists of two sub-types:
- **XRP** - **XRP**
XRP is serialized as a 64-bit unsigned integer (big-endian order), except that the second-most-significant bit is `1` to indicate that it is positive. In other words, take a standard UInt64 and calculate the bitwise-OR of that with `0x4000000000000000` to get the serialized format. XRP is serialized as a 64-bit unsigned integer (big-endian order), except that the most significant bit is always 0 to indicate that it's XRP, and the second-most-significant bit is `1` to indicate that it is positive. Since the maximum amount of XRP (10<sup>17</sup> drops) only requires 57 bits, you can calculate XRP serialized format by taking standard 64-bit unsigned integer and performing a bitwise-OR with `0x4000000000000000`.
- **Issued Currencies** - **Issued Currencies**
Issued currencies consist of three segments in order: Issued currencies consist of three segments in order:
1. 64 bits indicating the amount in the [internal currency format](currency-formats.html#issued-currency-math). The first bit is `1` to indicate that this is not XRP. 1. 64 bits indicating the amount in the [internal currency format](currency-formats.html#issued-currency-math). The first bit is `1` to indicate that this is not XRP.
@@ -174,6 +185,10 @@ The "Amount" type is a special field type that represents an amount of currency,
You can tell which of the two sub-types it is based on the first bit: `0` for XRP; `1` for issued currency. You can tell which of the two sub-types it is based on the first bit: `0` for XRP; `1` for issued currency.
The following diagram shows the serialization formats for both XRP amounts and issued currency amounts:
![XRP amounts have a "not XRP" bit, a sign bit, and 62 bits of precision. Issued currency amounts consist of a "not XRP" bit, a sign bit, an exponent (8 bits), mantissa (54 bits), currency code (160 bits), and issuer (160 bits).](img/serialization-amount.png)
### Array Fields ### Array Fields
[STArray]: #array-fields [STArray]: #array-fields

BIN
img/serialization-amount.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

BIN
img/serialization-array.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 7.7 KiB

After

Width:  |  Height:  |  Size: 9.0 KiB

BIN
img/serialization-object.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 12 KiB