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

Money in the XRP Ledger concept article (to be split into more/less technical articles

Browse Source
This commit is contained in:
mDuo13
2017-11-02 19:19:25 -07:00
parent 5ec1df054a
commit e69ced8847
8 changed files with 468 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
content/concept-money.md
View File

@@ -1,6 +1,6 @@
# Money in the XRP Ledger
The XRP Ledger is an advanced blockchain-like system that was designed to let people transact in multiple currencies, seamlessly tracking, trading, and settling multiple currencies in an exchange that's as decentralized as the network itself. Users have the power to create their own currency-like digital assets in the XRP Ledger, which may or may not be tied to traditional currencies and assets. Tying it all together is XRP, the XRP Ledger's native cryptocurrency, which serves anti-spam purposes and acting as a medium of exchange.
The XRP Ledger is an advanced blockchain-like system that was designed to let people transact in multiple currencies, seamlessly tracking, trading, and settling multiple currencies in an exchange that's as decentralized as the network itself. Users have the power to create their own currency-like digital assets in the XRP Ledger, which may or may not represent obligations owed outside the XRP Ledger. Tying it all together is XRP, the XRP Ledger's native cryptocurrency, which serves anti-spam purposes and acts as a medium of exchange.
## XRP
@@ -32,9 +32,7 @@ Addresses can also [freeze](concept-freeze.html) issued currencies, which may be
### Issued Currency Properties
Issued currencies in the XRP Ledger are represented with a custom number format that aims to provide high precision for a wide variety of assets, including those typically measured in very small or very large denominations, while keeping the numeric representation compact.
The precision for amounts of **non-XRP currency** in the XRP Ledger is as follows:
Issued currencies in the XRP Ledger are represented with a custom format with the following precision:
* Minimum nonzero absolute value: `1000000000000000e-96`
* Maximum value: `9999999999999999e80`
@@ -42,9 +40,47 @@ The precision for amounts of **non-XRP currency** in the XRP Ledger is as follow
* 15 decimal digits of precision
### Issued Currency Math
[[Source]<br>](https://github.com/ripple/rippled/blob/35fa20a110e3d43ffc1e9e664fc9017b6f2747ae/src/ripple/protocol/impl/STAmount.cpp "Source")
Numbers for issued currencies are represented as a 56-bit mantissa and an 8-bit exponent, which are joined into a 64-bit format when transmitting across the network.
![Issued Currency Amount Format diagram](img/currency-number-format.png)
The mantissa contains the significant digits of the currency. It is normalized such that `1000000000000000e-15` is the canonical representation of 1 unit of currency.
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.
These are normalized to use the lowest (in some cases, most negative) exponent possible without losing precision. For example, the display value "1" can be represented as
The internal format consists of three parts: a sign bit, a mantissa, and an exponent. The mantissa contains up to 15 significant digits (in base-10), and the exponent contains a scale (from -96 to +80). The sign bit indicates whether the amount is positive or negative. Before recording any amount, `rippled` "canonicalizes" the value so that the mantissa is within the range `1000000000000000` to `9999999999999999` (inclusive) and the exponent is in the range -96 to 80 (inclusive). (Exception: the value `0` is represented with a mantissa of `0`.) 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.
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 mantissa occupies the remaining 54 bits.
### Currency Codes
All non-XRP currencies in the XRP Ledger have a 160-bit currency code. The [`rippled` APIs](reference-rippled.html) map 3-character ASCII strings (case-sensitive) to 160-bit currency codes using a standard mapping. The currency code `XRP` is disallowed for issued currencies. Currencies with the same code can [ripple](concept-noripple.html) across connected trustlines. The currency code has no other behavior built into the XRP Ledger.
#### Standard Mapping
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.
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 <code>&#124;</code>. 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.
#### Nonstandard Mappings
You can also issue currency of other types by using a 160-bit (40-character) hexadecimal string such as `015841551A748AD2C1F76FF6ECB0CCCD00000000` as the currency code. To prevent this from being treated as a different currency code type, the first 8 bits MUST NOT be `0x00`.
**Deprecated:** Some previous versions of [ripple-lib](https://github.com/ripple/ripple-lib) supported an "interest-bearing" or "demurraging" currency code type. Currencies of this type were valued at a different amount than their face value based on the current time and the interest rate incorporated in the currency code. Demurraging / interest-bearing currencies are no longer supported, but you may encounter them in ledger data. These currencies have the following format:
![Demurraging Currency Code Format](img/demurrage-currency-code-format.png)
1. The first 8 bits must be `0x01`.
2. The next 24 bits represent 3 characters of ASCII.
This is expected to be an ISO 4217 code. It supports the same characters as the standard format's ASCII characters.
3. The next 24 bits MUST be all `0`s.
4. The next 64 bits are the interest rate of the currency, represented as "e-folding time" in an IEEE 754 double format.
5. The next 24 bits are reserved and should be all `0`s.
For more information, see [Gateway demurrage on the Ripple Wiki](https://wiki.ripple.com/Gateway_demurrage).

139
content/img-sources/currency_code_format.uxf Normal file
View File

@@ -0,0 +1,139 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<diagram program="umlet" version="14.2">
<zoom_level>10</zoom_level>
<element>
<id>UMLClass</id>
<coordinates>
<x>40</x>
<y>70</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>90</y>
<w>60</w>
<h>60</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;10.0;40.0;40.0;40.0</additional_attributes>
</element>
<element>
<id>Text</id>
<coordinates>
<x>80</x>
<y>120</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>70</y>
<w>220</w>
<h>30</h>
</coordinates>
<panel_attributes>Reserved (96 bits)</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>460</x>
<y>70</y>
<w>20</w>
<h>30</h>
</coordinates>
<panel_attributes/>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>460</x>
<y>90</y>
<w>40</w>
<h>60</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;10.0;40.0;20.0;40.0</additional_attributes>
</element>
<element>
<id>Text</id>
<coordinates>
<x>480</x>
<y>120</y>
<w>250</w>
<h>60</h>
</coordinates>
<panel_attributes>Version (8 bits)
Increment if currency is reissued
with the same code</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>490</x>
<y>70</y>
<w>150</w>
<h>30</h>
</coordinates>
<panel_attributes>Reserved (24 bits)</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>300</x>
<y>70</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>40</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>90</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>110</y>
<w>130</w>
<h>30</h>
</coordinates>
<panel_attributes>3 chars of ASCII</panel_attributes>
<additional_attributes/>
</element>
</diagram>

105
content/img-sources/currency_format.uxf Normal file
View File

@@ -0,0 +1,105 @@
<?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>20</x>
<y>20</y>
<w>650</w>
<h>70</h>
</coordinates>
<panel_attributes>Issued Currency Number Format</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>30</x>
<y>50</y>
<w>20</w>
<h>30</h>
</coordinates>
<panel_attributes/>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>60</x>
<y>50</y>
<w>20</w>
<h>30</h>
</coordinates>
<panel_attributes/>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>90</x>
<y>50</y>
<w>150</w>
<h>30</h>
</coordinates>
<panel_attributes>exponent (8 bits)</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>250</x>
<y>50</y>
<w>410</w>
<h>30</h>
</coordinates>
<panel_attributes>mantissa (54 bits)</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>60</x>
<y>70</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>90</x>
<y>100</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>70</x>
<y>130</y>
<w>270</w>
<h>30</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>30</x>
<y>70</y>
<w>60</w>
<h>90</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;10.0;70.0;40.0;70.0</additional_attributes>
</element>
</diagram>

174
content/img-sources/demurrage-currency-code-format.uxf Normal file
View File

@@ -0,0 +1,174 @@
<?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>20</x>
<y>20</y>
<w>620</w>
<h>70</h>
</coordinates>
<panel_attributes>Demurraging Currency Code Format</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>30</x>
<y>50</y>
<w>20</w>
<h>30</h>
</coordinates>
<panel_attributes>01</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>60</x>
<y>50</y>
<w>80</w>
<h>30</h>
</coordinates>
<panel_attributes/>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>150</x>
<y>50</y>
<w>120</w>
<h>30</h>
</coordinates>
<panel_attributes>Unused (24 bits)</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>280</x>
<y>50</y>
<w>200</w>
<h>30</h>
</coordinates>
<panel_attributes>e-folding time (64 bits)</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>490</x>
<y>50</y>
<w>140</w>
<h>30</h>
</coordinates>
<panel_attributes>Reserved (40 bits)</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLNote</id>
<coordinates>
<x>660</x>
<y>30</y>
<w>120</w>
<h>70</h>
</coordinates>
<panel_attributes>Legacy only. Not currently supported.
bg=red
style=wordwrap</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>340</x>
<y>70</y>
<w>40</w>
<h>60</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;10.0;40.0;20.0;40.0</additional_attributes>
</element>
<element>
<id>Text</id>
<coordinates>
<x>360</x>
<y>100</y>
<w>130</w>
<h>30</h>
</coordinates>
<panel_attributes>IEEE 754 Double</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Text</id>
<coordinates>
<x>220</x>
<y>100</y>
<w>130</w>
<h>30</h>
</coordinates>
<panel_attributes>Must be all 0's</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>200</x>
<y>70</y>
<w>40</w>
<h>60</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;10.0;40.0;20.0;40.0</additional_attributes>
</element>
<element>
<id>Text</id>
<coordinates>
<x>80</x>
<y>90</y>
<w>130</w>
<h>60</h>
</coordinates>
<panel_attributes>ISO 4217 code
in ASCII
(24 bits)</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>60</x>
<y>70</y>
<w>40</w>
<h>60</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;10.0;40.0;20.0;40.0</additional_attributes>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>30</x>
<y>70</y>
<w>70</w>
<h>110</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;-</panel_attributes>
<additional_attributes>10.0;10.0;10.0;90.0;50.0;90.0</additional_attributes>
</element>
<element>
<id>Text</id>
<coordinates>
<x>80</x>
<y>150</y>
<w>210</w>
<h>40</h>
</coordinates>
<panel_attributes>Type code (8 bits)
0x01 for demurraging currency</panel_attributes>
<additional_attributes/>
</element>
</diagram>

7
dactyl-config.yml
View File

@@ -295,6 +295,13 @@ pages:
- local
- ripple.com
- md: concept-money.md
category: Features
html: concept-money.html
targets:
- local
- ripple.com
- md: concept-partial-payments.md
category: Features
html: concept-partial-payments.html

BIN
img/currency-code-format.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
img/currency-number-format.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.6 KiB

BIN
img/demurrage-currency-code-format.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB