diff --git a/content/_img-sources/currency_code_format.uxf b/content/_img-sources/currency_code_format.uxf index af8c3a77f6..e9c40499df 100644 --- a/content/_img-sources/currency_code_format.uxf +++ b/content/_img-sources/currency_code_format.uxf @@ -28,11 +28,12 @@ 80 120 - 300 - 40 + 200 + 60 Type code (8 bits) -0x00 for ISO 4217/pseudo-ISO currency +0x00 for ISO 4217 or +pseudo-ISO currency @@ -43,7 +44,7 @@ 220 30 - Reserved (96 bits) + Reserved (88 bits) @@ -51,45 +52,10 @@ 460 70 - 20 + 180 30 - - - - - Relation - - 460 - 90 - 40 - 60 - - lt=<<- - 10.0;10.0;10.0;40.0;20.0;40.0 - - - Text - - 480 - 120 - 250 - 60 - - Version (8 bits) -Increment if currency is reissued -with the same code - - - - UMLClass - - 490 - 70 - 150 - 30 - - Reserved (24 bits) + Reserved (40 bits) @@ -120,10 +86,10 @@ with the same code 310 90 40 - 50 + 60 lt=<<- - 10.0;10.0;10.0;30.0;20.0;30.0 + 10.0;10.0;10.0;40.0;20.0;40.0 Text @@ -131,9 +97,32 @@ with the same code 330 110 130 + 40 + + 3 chars of ASCII +(can't be "XRP") + + + + UMLPackage + + 30 + 220 + 620 + 70 + + Special Case XRP Currency Code + + + + UMLClass + + 40 + 250 + 600 30 - 3 chars of ASCII + 0x00000000000000000000000000000000000000000 (160 bits of 0's) diff --git a/content/_img-sources/currency_format.uxf b/content/_img-sources/currency_format.uxf index 476e45b7e4..250d29ec4c 100644 --- a/content/_img-sources/currency_format.uxf +++ b/content/_img-sources/currency_format.uxf @@ -4,12 +4,12 @@ UMLPackage - 20 - 20 + 30 + 250 650 70 - Issued Currency Number Format + Special Case (Issued currency amount = 0) @@ -61,17 +61,17 @@ 60 70 - 50 - 60 + 40 + 90 lt=<<- - 10.0;10.0;10.0;40.0;30.0;40.0 + 10.0;10.0;10.0;70.0;20.0;70.0 Text - 90 - 100 + 80 + 130 260 30 @@ -82,8 +82,8 @@ style=wordwrap Text - 70 - 130 + 60 + 170 270 30 @@ -96,10 +96,102 @@ style=wordwrap 30 70 - 60 - 90 + 50 + 130 lt=<<- - 10.0;10.0;10.0;70.0;40.0;70.0 + 10.0;10.0;10.0;110.0;30.0;110.0 + + + Relation + + 140 + 70 + 90 + 60 + + lt=<<- + 10.0;10.0;10.0;40.0;70.0;40.0 + + + Text + + 210 + 100 + 280 + 30 + + Unsigned integer; original value +97 +style=wordwrap + + + + Relation + + 500 + 70 + 50 + 100 + + lt=<<- + 10.0;10.0;10.0;80.0;30.0;80.0 + + + Text + + 530 + 110 + 150 + 90 + + Normalized to the range +(10¹⁵, 10¹⁶-1) inclusive +style=wordwrap + + + + UMLPackage + + 20 + 20 + 650 + 70 + + Issued Currency Number Format + + + + UMLClass + + 40 + 280 + 630 + 30 + + 0x8000000000000000000000000000000000000000 + + + + Relation + + 60 + 300 + 90 + 60 + + lt=<<- + 10.0;10.0;10.0;40.0;70.0;40.0 + + + Text + + 130 + 330 + 280 + 30 + + Most significant bit is 1, the rest is 0's +style=wordwrap + diff --git a/content/references/rippled-api/api-conventions/currency-formats.md b/content/references/rippled-api/api-conventions/currency-formats.md index 50f4c38a1a..ceb6babcd3 100644 --- a/content/references/rippled-api/api-conventions/currency-formats.md +++ b/content/references/rippled-api/api-conventions/currency-formats.md @@ -33,9 +33,16 @@ Issued currencies in the XRP Ledger are represented with a custom format with th Internally, `rippled` represents numbers for issued currencies in a custom number format. This format can store a wide variety of assets, including those typically measured in very small or very large denominations. Unlike typical floating-point representations of non-whole numbers, this format uses integer math for all calculations, so it always maintains 15 decimal digits of precision. Unlike "arbitrary precision" number formats, the custom format can always be stored in a fixed size of 64 bits. -The internal format consists of three parts: a sign bit, significant digits, and an exponent. (It uses them in the same way as scientific notation.) The sign bit indicates whether the amount is positive or negative. The significant digits are represented using an integer in the range `1000000000000000` to `9999999999999999` (inclusive), except for the special case of the value 0, whose significant digits use the value `0`. The exponent indicates the scale (what power of 10 the significant digits should be multiplied by) in the range -96 to +80 (inclusive). Before recording any amount, `rippled` "canonicalizes" the value so that the significant digits and exponent are within the expected range. For example, the canonical representation of 1 unit of currency is `1000000000000000e-15`. The internal calculations generally use integer math so that numbers are always precise within 15 digits. Multiplication and division have adjustments to compensate for over-rounding in the least significant digits. +The internal format consists of four parts: a "not XRP" bit, a sign bit, significant digits, and an exponent. (It uses them in the same way as scientific notation.) They are present in order: -When transmitting non-XRP amounts across the network or recording them in ledgers, the amounts are joined into a 64-bit format. The most significant bit indicates whether the amount is XRP or issued currency. (The value `1` indicates a non-XRP amount.) The next bit is the sign bit, 1 for positive or 0 for negative. (Caution: This is the opposite of how sign bits work in most other numeric representations!) The next 8 bits are the exponent, and the significant digits occupy the remaining 54 bits. +1. The first (most significant) bit for an issued currency amount is `1` to indicate that it is not an XRP amount. (XRP amounts always have the most significant bit set to `0` to distinguish them from this format.) +2. The sign bit indicates whether the amount is positive or negative. Unlike standard [two's complement](https://en.wikipedia.org/wiki/Two%27s_complement) integers, `1` indicates **positive** in the XRP Ledger format, and `0` indicates negative. +3. The next 8 bits represent the exponent as an unsigned integer. The exponent indicates the scale (what power of 10 the significant digits should be multiplied by) in the range -96 to +80 (inclusive). However, when serializing, we add 97 to the exponent to make it possible to serialize as an unsigned integer. Thus, a serialized value of `1` indicates an exponent of `-96`, a serialized value of `177` indicates an exponent of 80, and so on. +4. The remaining 54 bits represent the significant digits as an unsigned integer. When serializing, this value is normalized to the range 1015 (`1000000000000000`) to 1016-1 (`9999999999999999`) inclusive, except for the special case of the value 0, whose significant digits and sig use the value `0`. + +Before recording any amount, `rippled` "canonicalizes" the value so that the significant digits and exponent are within the expected range. For example, the canonical representation of 1 unit of currency is `1000000000000000e-15`. The internal calculations generally use integer math so that numbers are always precise within 15 digits. Multiplication and division have adjustments to compensate for over-rounding in the least significant digits. + +There is a special case for the value 0. In this case, the sign bit, exponent, and mantissa are all zeroes, so the 64-bit value is serialized as `0x8000000000000000000000000000000000000000`. ## Currency Codes @@ -48,11 +55,12 @@ The standard currency mapping allocates the bits as follows: ![Standard Currency Code Format](img/currency-code-format.png) 1. The first 8 bits must be `0x00`. -2. The next 96 bits are reserved, and should be all `0`s. +2. The next 88 bits are reserved, and should be all `0`'s. 3. The next 24 bits represent 3 characters of ASCII. Ripple recommends using [ISO 4217](http://www.xe.com/iso4217.php) codes, or popular pseudo-ISO 4217 codes such as "BTC". However, any combination of the following characters is permitted: all uppercase and lowercase letters, digits, as well as the symbols `?`, `!`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `<`, `>`, `(`, `)`, `{`, `}`, `[`, `]`, and |. The currency code `XRP` (all-uppercase) is reserved for XRP and cannot be used by issued currencies. -4. The next 8 bits indicate the currency version. If the same currency is reissued with a different value, you can increment this value to keep the currencies separate. -5. The next 24 bits are reserved and should be all `0`s. +4. The next 40 bits are reserved and should be all `0`'s. + +Usually, XRP amounts are not specified with currency codes. In the rare case that a field specifies a currency code for XRP, the currency code's binary format is all zeroes. ### Nonstandard Currency Codes diff --git a/img/currency-code-format.png b/img/currency-code-format.png index c76a9df58f..aba97c1926 100644 Binary files a/img/currency-code-format.png and b/img/currency-code-format.png differ diff --git a/img/currency-number-format.png b/img/currency-number-format.png index 1984a8c8ea..5e8fc8cc2d 100644 Binary files a/img/currency-number-format.png and b/img/currency-number-format.png differ