From 5ec1df054a7c7a25960d186d281312fd14405ed1 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Fri, 27 Oct 2017 18:06:43 -0700 Subject: [PATCH 1/5] Money in the XRP Ledger (incomplete draft) --- content/concept-money.md | 50 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 content/concept-money.md diff --git a/content/concept-money.md b/content/concept-money.md new file mode 100644 index 0000000000..876f352ce2 --- /dev/null +++ b/content/concept-money.md @@ -0,0 +1,50 @@ +# 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. + +## XRP + +**XRP** is the native cryptocurrency of the XRP Ledger. All [accounts](concept-accounts.html) in the XRP Ledger can send XRP among one another and . Unlike other currencies in the XRP Ledger, XRP is not tied to a "trust line" (accounting relationship) between addresses. XRP can be sent directly from any XRP Ledger address to any other, without needing a gateway or liquidity provider. This helps make XRP a convenient bridge currency. + +Some advanced features of the XRP Ledger, such as [Escrow](concept-escrow.html) and [Payment Channels](tutorial-paychan.html), only work with XRP. Order book [autobridging](https://ripple.com/dev-blog/introducing-offer-autobridging/) uses XRP to deepen liquidity in the decentralized exchange by merging order books of two issued currencies (such as USD:EUR) with XRP order books (USD:XRP + XRP:EUR results in more trades for the USD:EUR book). + +XRP also serves as a protective measure against spamming the network. All XRP Ledger addresses need a small amount of XRP to pay the costs of maintaining the XRP Ledger. The [transaction cost](concept-transaction-cost.html) and [reserve](concept-reserves.html) are neutral fees denoted in XRP and not paid to any party. + +For more information on XRP's use cases, benefits, and news, see the [XRP Portal](https://ripple.com/xrp-portal/). + +### XRP Properties + +XRP is the only native currency in the XRP Ledger. The very first ledger contained 100 billion XRP, and no new XRP can be created. XRP can be destroyed by [transaction costs](concept-transaction-cost.html) or lost by sending it to addresses for which no one holds a key, so XRP is slightly [deflationary](https://en.wikipedia.org/wiki/Deflation) by nature. No need to worry about running out, though: at the current rate of destruction, it would take at least 70,000 years to destroy all XRP, and XRP prices and fees can be adjusted as the total supply of XRP changes. + +Technically, XRP Ledger software uses unsigned 64-bit integers to store and calculate XRP amounts down to 6 decimal places. The smallest indivisible amount of XRP is 0.000001, called a "drop" of XRP. Thus, 1 XRP is represented as `1000000` in the internal representation, and 1 drop of XRP is `1` in the internal representation. + +## Issued Currencies + +All currencies other than XRP are represented as "issued currencies". These digital assets, sometimes called "issuances" or "IOUs", are tracked in accounting relationships, called "trust lines," between addresses. Issued currencies are typically considered as liabilities from one perspective and assets from the other, so the balance of a trust line is negative or positive depending on which side you view it from. An address freely issue (non-XRP) currency, limited only by how much other addresses are willing to hold. + +Issued currencies can "ripple" through multiple issuers and holders if they use the same currency code. This is useful in some cases, but can cause unexpected and undesirable behavior in others. You can use the [NoRipple flag](concept-noripple.html) on trust lines to prevent those trust lines from rippling. + +In the typical model, an issued currency is tied to holdings of currency or other assets outside the XRP Ledger. The issuer of the currency, called a _gateway_, handles deposits and withdrawals to exchange currency outside the XRP Ledger for equivalent balances of issued currency in the XRP Ledger. For more information on how to run a gateway, see the [Gateway Guide](tutorial-gateway-guide.html). + +There are other use cases for issued currencies in the XRP Ledger. For example, you can create an "Initial Coin Offering" (ICO) by issuing a fixed amount of currency to a secondary address, then throwing away the key to the issuer. (Be aware: ICOs may be [regulated as securities](https://www.sec.gov/oiea/investor-alerts-and-bulletins/ib_coinofferings) in the USA.) Ripple recommends researching the relevant regulations before engaging in any financial service business. + +Addresses can also [freeze](concept-freeze.html) issued currencies, which may be useful for businesses to comply with financial regulations in their jurisdiction. If you do not need this feature and do not want to freeze currencies, you can give up your address's ability to freeze individual trust lines and to undo a global freeze. XRP can never be frozen. + +### 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: + +* Minimum nonzero absolute value: `1000000000000000e-96` +* Maximum value: `9999999999999999e80` +* Minimum value: `-9999999999999999e80` +* 15 decimal digits of precision + +### Issued Currency Math + +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. + +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. + +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 From e69ced884766a1432ff99e8d53fd48acf888b908 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Thu, 2 Nov 2017 19:19:25 -0700 Subject: [PATCH 2/5] Money in the XRP Ledger concept article (to be split into more/less technical articles --- content/concept-money.md | 50 ++++- content/img-sources/currency_code_format.uxf | 139 ++++++++++++++ content/img-sources/currency_format.uxf | 105 +++++++++++ .../demurrage-currency-code-format.uxf | 174 ++++++++++++++++++ dactyl-config.yml | 7 + img/currency-code-format.png | Bin 0 -> 12848 bytes img/currency-number-format.png | Bin 0 -> 8817 bytes img/demurrage-currency-code-format.png | Bin 0 -> 16571 bytes 8 files changed, 468 insertions(+), 7 deletions(-) create mode 100644 content/img-sources/currency_code_format.uxf create mode 100644 content/img-sources/currency_format.uxf create mode 100644 content/img-sources/demurrage-currency-code-format.uxf create mode 100644 img/currency-code-format.png create mode 100644 img/currency-number-format.png create mode 100644 img/demurrage-currency-code-format.png diff --git a/content/concept-money.md b/content/concept-money.md index 876f352ce2..6de4045136 100644 --- a/content/concept-money.md +++ b/content/concept-money.md @@ -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]
](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 |. 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). diff --git a/content/img-sources/currency_code_format.uxf b/content/img-sources/currency_code_format.uxf new file mode 100644 index 0000000000..af8c3a77f6 --- /dev/null +++ b/content/img-sources/currency_code_format.uxf @@ -0,0 +1,139 @@ + + + 10 + + UMLClass + + 40 + 70 + 20 + 30 + + 00 + + + + Relation + + 40 + 90 + 60 + 60 + + lt=<<- + 10.0;10.0;10.0;40.0;40.0;40.0 + + + Text + + 80 + 120 + 300 + 40 + + Type code (8 bits) +0x00 for ISO 4217/pseudo-ISO currency + + + + UMLClass + + 70 + 70 + 220 + 30 + + Reserved (96 bits) + + + + UMLClass + + 460 + 70 + 20 + 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) + + + + UMLClass + + 300 + 70 + 150 + 30 + + ISO code (24 bits) + + + + UMLPackage + + 30 + 40 + 620 + 70 + + Issued Currency Code Format + + + + Relation + + 310 + 90 + 40 + 50 + + lt=<<- + 10.0;10.0;10.0;30.0;20.0;30.0 + + + Text + + 330 + 110 + 130 + 30 + + 3 chars of ASCII + + + diff --git a/content/img-sources/currency_format.uxf b/content/img-sources/currency_format.uxf new file mode 100644 index 0000000000..476e45b7e4 --- /dev/null +++ b/content/img-sources/currency_format.uxf @@ -0,0 +1,105 @@ + + + 10 + + UMLPackage + + 20 + 20 + 650 + 70 + + Issued Currency Number Format + + + + UMLClass + + 30 + 50 + 20 + 30 + + + + + + UMLClass + + 60 + 50 + 20 + 30 + + + + + + UMLClass + + 90 + 50 + 150 + 30 + + exponent (8 bits) + + + + UMLClass + + 250 + 50 + 410 + 30 + + mantissa (54 bits) + + + + Relation + + 60 + 70 + 50 + 60 + + lt=<<- + 10.0;10.0;10.0;40.0;30.0;40.0 + + + Text + + 90 + 100 + 260 + 30 + + Sign bit (0=negative, 1=positive) +style=wordwrap + + + + Text + + 70 + 130 + 270 + 30 + + "Not XRP" bit (0=XRP, 1=not XRP) +style=wordwrap + + + + Relation + + 30 + 70 + 60 + 90 + + lt=<<- + 10.0;10.0;10.0;70.0;40.0;70.0 + + diff --git a/content/img-sources/demurrage-currency-code-format.uxf b/content/img-sources/demurrage-currency-code-format.uxf new file mode 100644 index 0000000000..283412b417 --- /dev/null +++ b/content/img-sources/demurrage-currency-code-format.uxf @@ -0,0 +1,174 @@ + + + 10 + + UMLPackage + + 20 + 20 + 620 + 70 + + Demurraging Currency Code Format + + + + UMLClass + + 30 + 50 + 20 + 30 + + 01 + + + + UMLClass + + 60 + 50 + 80 + 30 + + + + + + UMLClass + + 150 + 50 + 120 + 30 + + Unused (24 bits) + + + + UMLClass + + 280 + 50 + 200 + 30 + + e-folding time (64 bits) + + + + UMLClass + + 490 + 50 + 140 + 30 + + Reserved (40 bits) + + + + UMLNote + + 660 + 30 + 120 + 70 + + Legacy only. Not currently supported. +bg=red +style=wordwrap + + + + Relation + + 340 + 70 + 40 + 60 + + lt=<<- + 10.0;10.0;10.0;40.0;20.0;40.0 + + + Text + + 360 + 100 + 130 + 30 + + IEEE 754 Double + + + + Text + + 220 + 100 + 130 + 30 + + Must be all 0's + + + + Relation + + 200 + 70 + 40 + 60 + + lt=<<- + 10.0;10.0;10.0;40.0;20.0;40.0 + + + Text + + 80 + 90 + 130 + 60 + + ISO 4217 code +in ASCII +(24 bits) + + + + Relation + + 60 + 70 + 40 + 60 + + lt=<<- + 10.0;10.0;10.0;40.0;20.0;40.0 + + + Relation + + 30 + 70 + 70 + 110 + + lt=<<- + 10.0;10.0;10.0;90.0;50.0;90.0 + + + Text + + 80 + 150 + 210 + 40 + + Type code (8 bits) +0x01 for demurraging currency + + + diff --git a/dactyl-config.yml b/dactyl-config.yml index 8f2a8a317c..cb83985348 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -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 diff --git a/img/currency-code-format.png b/img/currency-code-format.png new file mode 100644 index 0000000000000000000000000000000000000000..c76a9df58f0d377fac4de63b1be54074e32b04ef GIT binary patch literal 12848 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 literal 0 HcmV?d00001 From 96965cb43ff00cd9815bf322412bf443cf8a325d Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Fri, 3 Nov 2017 17:48:52 -0700 Subject: [PATCH 3/5] Split off currency reference, migrate demurrage page --- content/concept-demurrage.md | 119 ++++++++++++++++++++++++++++++++++ content/concept-money.md | 73 +++++---------------- content/reference-currency.md | 60 +++++++++++++++++ dactyl-config.yml | 14 ++++ 4 files changed, 208 insertions(+), 58 deletions(-) create mode 100644 content/concept-demurrage.md create mode 100644 content/reference-currency.md diff --git a/content/concept-demurrage.md b/content/concept-demurrage.md new file mode 100644 index 0000000000..aeca34a3ba --- /dev/null +++ b/content/concept-demurrage.md @@ -0,0 +1,119 @@ +# Demurrage + +**Warning:** Demurrage is a deprecated feature with no ongoing support. This page describes historical behavior of older versions of Ripple software. + +[Demurrage](http://en.wikipedia.org/wiki/Demurrage_%28currency%29) is a negative interest rate on assets held that represents the cost of holding those assets. To represent the demurrage on an issued currency in the XRP Ledger, you can track it using a custom [currency code](reference-currency.html#currency-codes) that indicates the demurrage rate. This effectively creates separate versions of the currency for each varying amount of demurrage. Client applications can support this by representing the demurraging currency code with an annual percentage rate alongside the currency code. For example: "XAU (-0.5%pa)". + +## Representing Demurraging Currency Amounts + +Rather than continuously update all amounts in the XRP Ledger, this approach divides amounts of interest-bearing or demurraging currency into two types of amount: "ledger values" recorded in the XRP Ledger, and "display values" shown to people. The "ledger values" represent the value of the currency at a fixed point, namely the "Ripple Epoch" of midnight January 1, 2000. The "display values" represent the amount at a later point in time (usually the current time) after calculating continuous interest or demurrage from the Ripple Epoch until that time. + +**Tip:** You can think of demurrage as similar to inflation, where the value of all assets affected by it decreases over time, but the ledger always holds amounts in year-2000 values. This does not reflect actual real-world inflation; demurrage is more like hypothetical inflation at a constant rate. + +Thus, client software must apply two conversions: + +- Taking display values at a given time and converting them to ledger values to be recorded. +- Taking ledger values and converting them to a display value at a given point in time. + +### Calculating Demurrage + +The full formula for calculating demurrage on a currency is as follows: + +``` +D = A × ( e ^ (t ÷ τ) ) +``` + +- **D** is the amount after demurrage +- **A** is the pre-demurrage amount as recorded in the global ledger +- **e** is Euler's number +- **t** is the number of seconds since the Ripple Epoch (0:00 on January 1, 2000 UTC) +- **τ** is the e-folding time in seconds. This value is [calculated from the desired interest rate](#calculating-e-folding-time). + +To convert between display amounts and ledger amounts, you can use the following steps: + +1. Calculate the value of `( e ^ (t ÷ τ) )`. We call this number the "demurrage coefficient". The demurrage coefficient is always relative to a specific time, such as the current time. +2. Apply it to the amount to convert: + - To convert ledger values to display values, multiply by the demurrage coefficient. + - To convert display values to ledger values, divide by the demurrage coefficient. +3. If necessary, adjust the resulting value so that it can be represented to the desired accuracy. Ledger values are limited to 15 decimal digits of precision, according to the XRP Ledger's [issued currency format](reference-currency.html#issued-currency-precision). + + +## Interest-Bearing Currency Code Format + +Rather than using the [standard currency code format](reference-currency.html#currency-codes), currencies that have positive interest or negative interest (demurrage) use a 160-bit currency code in 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](http://en.wikipedia.org/wiki/E-folding)" in an IEEE 754 double format. +5. The next 24 bits are reserved and should be all `0`s. + +### Calculating e-folding Time + +To convert between ledger amounts and display amounts, or to calculate a currency code for an interest-bearing/demurraging currency, you need the interest rate as an "e-folding time". The e-folding time is the amount of time it takes a quantity to increase by a factor of _e_ (Euler's number). By convention, e-folding time is written as the letter **τ** in formulas. + +To calculate an e-folding time for a given rate of annual percent interest: + +1. Add the interest rate to 100% to get the percentage of the initial amount present after applying annual interest. For demurrage, use a negative interest rate. For example, 0.5% demurrage would be an interest rate of -0.5%, resulting in **99.5%** remaining. +2. Represent the percentage as a decimal. For example, 99.5% becomes **0.995**. +3. Take the natural log of that number. For example, **ln(0.995) = -0.005012541823544286**. (This number is positive if the initial interest rate was positive, and negative if the interest rate was negative.) +4. Take the number of seconds in one year (31536000) and divide by the natural log result from the previous step. For example, **31536000 ÷ -0.005012541823544286 = -6291418827.045599**. This result is the e-folding time in seconds. + +**Note:** By convention, Ripple's interest/demurrage rules use a fixed number of seconds per year (31536000), which is not adjusted for leap days or leap seconds. + +## Client Support + +To support interest-bearing and demurraging currencies, client applications must implement several features: + +- When displaying the amount of a demurraging currency retrieved from ledger or transaction data, the client must convert from the ledger value to the display value. (With demurrage, the display values are smaller than the ledger values.) +- When accepting input for a demurraging currency, the client must convert amounts from a display format to the ledger format. (With demurrage, the ledger values are are larger than the user input value.) The client must use the ledger value when creating payments, offers, and other types of transaction. +- Clients must distinguish between currencies that do and do not have interest or demurrage, and among currencies that have different rates of interest or demurrage. Clients should be able to parse the [Interest-Bearing Currency Code Format](#interest-bearing-currency-code-format) into a display such as "XAU (-0.5% pa)". + +### ripple-lib Support + +Demurrage was supported in ripple-lib versions **0.7.37** through **0.12.9**. Demurrage is ***not supported*** in [RippleAPI](reference-rippleapi.html). + +The following code samples demonstrate how to use compatible versions of ripple-lib to convert between ledger values and display values. Also see the [Ripple Demurrage Calculator](https://ripple.github.io/ripple-demurrage-tool/). + +To convert from a display value to a ledger value, use `Amount.from_human()`: + +```js +// create an Amount object for the display amount of the demurring currency +// and pass in a reference_date that represents the current date +// (in this case, ledger value 10 XAU with 0.5% annual demurrage, +// at 2017-11-04T00:07:50Z.) +var demAmount = ripple.Amount.from_human('10 0158415500000000C1F76FF6ECB0BAC600000000', + {reference_date:563069270}); + +// set the issuer +demAmount.set_issuer("rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh"); + +// get the JSON format for the ledger amount +console.log(demAmount.to_json()); + +// { "value": "10.93625123082769", +// "currency": "0158415500000000C1F76FF6ECB0BAC600000000", +// "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh" } +``` + +To convert from a ledger value to a display value: + +```js +// create an Amount object with the ledger value, +ledgerAmount = ripple.Amount.from_json({ + "currency": "015841551A748AD2C1F76FF6ECB0CCCD00000000", + "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh", + "value": "10.93625123082769"}) + +// apply interest up to the current time to get the display amount +var displayAmount = demAmount.applyInterest(new Date()); + +console.log(displayAmount.to_json()); + +// { "value": "9.999998874657716", +// "currency": "0158415500000000C1F76FF6ECB0BAC600000000", +// "issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh" } +``` diff --git a/content/concept-money.md b/content/concept-money.md index 6de4045136..4be9c4149f 100644 --- a/content/concept-money.md +++ b/content/concept-money.md @@ -1,86 +1,43 @@ # 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 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. +The XRP Ledger is an advanced blockchain-like system that was designed to let people transact in multiple currencies. Users of the XRP Ledger can seamlessly track, trade, and settle multiple currencies in an exchange that's as decentralized as the network itself. Users can issue their own currency-like digital assets, 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 -**XRP** is the native cryptocurrency of the XRP Ledger. All [accounts](concept-accounts.html) in the XRP Ledger can send XRP among one another and . Unlike other currencies in the XRP Ledger, XRP is not tied to a "trust line" (accounting relationship) between addresses. XRP can be sent directly from any XRP Ledger address to any other, without needing a gateway or liquidity provider. This helps make XRP a convenient bridge currency. +**XRP** is the native cryptocurrency of the XRP Ledger. All [accounts](concept-accounts.html) in the XRP Ledger can send XRP among one another and must hold a minimum amount of XRP as a [reserve](concept-reserves.html). XRP can be sent directly from any XRP Ledger address to any other, without needing a gateway or liquidity provider. This helps make XRP a convenient bridge currency. -Some advanced features of the XRP Ledger, such as [Escrow](concept-escrow.html) and [Payment Channels](tutorial-paychan.html), only work with XRP. Order book [autobridging](https://ripple.com/dev-blog/introducing-offer-autobridging/) uses XRP to deepen liquidity in the decentralized exchange by merging order books of two issued currencies (such as USD:EUR) with XRP order books (USD:XRP + XRP:EUR results in more trades for the USD:EUR book). +Some advanced features of the XRP Ledger, such as [Escrow](concept-escrow.html) and [Payment Channels](tutorial-paychan.html), only work with XRP. Order book [autobridging](https://ripple.com/dev-blog/introducing-offer-autobridging/) uses XRP to deepen liquidity in the decentralized exchange by merging order books of two issued currencies with XRP order books to create synthetic combined order books. (For example, autobridging matches USD:XRP and XRP:EUR orders to augment USD:EUR order books.) -XRP also serves as a protective measure against spamming the network. All XRP Ledger addresses need a small amount of XRP to pay the costs of maintaining the XRP Ledger. The [transaction cost](concept-transaction-cost.html) and [reserve](concept-reserves.html) are neutral fees denoted in XRP and not paid to any party. +XRP also serves as a protective measure against spamming the network. All XRP Ledger addresses need a small amount of XRP to pay the costs of maintaining the XRP Ledger. The [transaction cost](concept-transaction-cost.html) and [reserve](concept-reserves.html) are neutral fees denoted in XRP and not paid to any party. In the ledger's data format, XRP is stored in [AccountRoot objects](reference-ledger-format.html#accountroot). For more information on XRP's use cases, benefits, and news, see the [XRP Portal](https://ripple.com/xrp-portal/). ### XRP Properties -XRP is the only native currency in the XRP Ledger. The very first ledger contained 100 billion XRP, and no new XRP can be created. XRP can be destroyed by [transaction costs](concept-transaction-cost.html) or lost by sending it to addresses for which no one holds a key, so XRP is slightly [deflationary](https://en.wikipedia.org/wiki/Deflation) by nature. No need to worry about running out, though: at the current rate of destruction, it would take at least 70,000 years to destroy all XRP, and XRP prices and fees can be adjusted as the total supply of XRP changes. +The very first ledger contained 100 billion XRP, and no new XRP can be created. XRP can be destroyed by [transaction costs](concept-transaction-cost.html) or lost by sending it to addresses for which no one holds a key, so XRP is slightly [deflationary](https://en.wikipedia.org/wiki/Deflation) by nature. No need to worry about running out, though: at the current rate of destruction, it would take at least 70,000 years to destroy all XRP, and XRP [prices and fees can be adjusted](concept-fee-voting.html) as the total supply of XRP changes. -Technically, XRP Ledger software uses unsigned 64-bit integers to store and calculate XRP amounts down to 6 decimal places. The smallest indivisible amount of XRP is 0.000001, called a "drop" of XRP. Thus, 1 XRP is represented as `1000000` in the internal representation, and 1 drop of XRP is `1` in the internal representation. +In technical contexts, XRP is measured precisely to the nearest 0.000001 XRP, called a "drop" of XRP. The [`rippled` APIs](reference-rippled.html) require all XRP amounts to be specified in drops of XRP. For example, 1 XRP is represented as `1000000` drops. For more detailed information, see the [currency format reference](reference-currency.html). ## Issued Currencies -All currencies other than XRP are represented as "issued currencies". These digital assets, sometimes called "issuances" or "IOUs", are tracked in accounting relationships, called "trust lines," between addresses. Issued currencies are typically considered as liabilities from one perspective and assets from the other, so the balance of a trust line is negative or positive depending on which side you view it from. An address freely issue (non-XRP) currency, limited only by how much other addresses are willing to hold. +All currencies other than XRP are represented as **issued currencies**. These digital assets, sometimes called "issuances" or "IOUs", are tracked in accounting relationships, called "trust lines," between addresses. Issued currencies are typically considered as liabilities from one perspective and assets from the other, so the balance of a trust line is negative or positive depending on which side you view it from. Any address may freely issue (non-XRP) currencies, limited only by how much other addresses are willing to hold. Issued currencies can "ripple" through multiple issuers and holders if they use the same currency code. This is useful in some cases, but can cause unexpected and undesirable behavior in others. You can use the [NoRipple flag](concept-noripple.html) on trust lines to prevent those trust lines from rippling. +Issued currencies can be traded with XRP or each other in the XRP Ledger's decentralized exchange. + In the typical model, an issued currency is tied to holdings of currency or other assets outside the XRP Ledger. The issuer of the currency, called a _gateway_, handles deposits and withdrawals to exchange currency outside the XRP Ledger for equivalent balances of issued currency in the XRP Ledger. For more information on how to run a gateway, see the [Gateway Guide](tutorial-gateway-guide.html). -There are other use cases for issued currencies in the XRP Ledger. For example, you can create an "Initial Coin Offering" (ICO) by issuing a fixed amount of currency to a secondary address, then throwing away the key to the issuer. (Be aware: ICOs may be [regulated as securities](https://www.sec.gov/oiea/investor-alerts-and-bulletins/ib_coinofferings) in the USA.) Ripple recommends researching the relevant regulations before engaging in any financial service business. - -Addresses can also [freeze](concept-freeze.html) issued currencies, which may be useful for businesses to comply with financial regulations in their jurisdiction. If you do not need this feature and do not want to freeze currencies, you can give up your address's ability to freeze individual trust lines and to undo a global freeze. XRP can never be frozen. +There are other use cases for issued currencies in the XRP Ledger. For example, you can create an "Initial Coin Offering" (ICO) by issuing a fixed amount of currency to a secondary address, then "throwing away the key" to the issuer. (Be aware: ICOs may be [regulated as securities](https://www.sec.gov/oiea/investor-alerts-and-bulletins/ib_coinofferings) in the USA.) Ripple recommends researching the relevant regulations before engaging in any financial service business. ### Issued Currency Properties -Issued currencies in the XRP Ledger are represented with a custom format with the following precision: +All issued currencies in the XRP Ledger exist in trust lines, represented in the ledger's data as [RippleState objects](reference-ledger-format.html#ripplestate). To create an issued currency, the issuing address sends a [Payment transaction][] to an address which has a trust line to the issuer with a nonzero limit for that currency. (You can also create issued currency by rippling "through" such a trust line.) You can erase issued currency by sending it back to the issuer. -* Minimum nonzero absolute value: `1000000000000000e-96` -* Maximum value: `9999999999999999e80` -* Minimum value: `-9999999999999999e80` -* 15 decimal digits of precision +The issuer of a currency can define a percentage [transfer fee](concept-transfer-fees.html) to deduct when two parties transact in its issued currencies. -### Issued Currency Math -[[Source]
](https://github.com/ripple/rippled/blob/35fa20a110e3d43ffc1e9e664fc9017b6f2747ae/src/ripple/protocol/impl/STAmount.cpp "Source") +Addresses can also [freeze](concept-freeze.html) issued currencies, which may be useful for businesses to comply with financial regulations in their jurisdiction. If you do not need this feature and do not want to freeze currencies, you can give up your address's ability to freeze individual trust lines and to undo a global freeze. XRP cannot be frozen. -![Issued Currency Amount Format diagram](img/currency-number-format.png) +Issued currencies are designed to be able to represent any kind of currency or asset, including those with very small or very large nominal values. For detailed technical information on the types of currency codes and the numeric limits of issued currency representation, see the [currency format reference](reference-currency.html). -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, 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 |. 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). +{% include 'snippets/tx-type-links.md' %} diff --git a/content/reference-currency.md b/content/reference-currency.md new file mode 100644 index 0000000000..1649ae771b --- /dev/null +++ b/content/reference-currency.md @@ -0,0 +1,60 @@ +# Currency Formats + +The XRP Ledger has [two kinds of money](concept-money.html): XRP, and issued currencies. In the XRP Ledger, both types have high precision, although their formats are different. + +## String Formatting + +XRP Ledger APIs generally use strings, rather than native JSON numbers, to represent numeric amounts of currency for both XRP and issued currencies. This protects against a loss of precision when using JSON parsers, which may automatically try to represent all JSON numbers in a floating-point format. + +## XRP Precision + +XRP has the same precision as a 64-bit unsigned integer where each unit is equivalent to 0.000001 XRP. Its properties are: + +* Minimum value: `0` +* Maximum value: `100000000000` (10^11) XRP + - `"100000000000000000"` (10^17) drops of XRP +* Precise to the nearest `0.000001` (10^-6) XRP + - `"1"` drop of XRP + +## Issued Currency Precision + +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` +* Minimum value: `-9999999999999999e80` +* 15 decimal digits of precision + +## Issued Currency Math +[[Source]
](https://github.com/ripple/rippled/blob/35fa20a110e3d43ffc1e9e664fc9017b6f2747ae/src/ripple/protocol/impl/STAmount.cpp "Source") + +![Issued Currency Amount Format diagram](img/currency-number-format.png) + +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, 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. Currency codes have no other behavior built into the XRP Ledger. + +### Standard Currency Codes + +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 |. 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 Currency Codes + +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. These currencies have the first 8 bits `0x01`. Demurraging / interest-bearing currencies are no longer supported, but you may encounter them in ledger data. For more information, see [Demurrage](concept-demurrage.html). diff --git a/dactyl-config.yml b/dactyl-config.yml index cb83985348..69efff1004 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -158,6 +158,13 @@ pages: - local - ripple.com + - md: reference-currency.md + category: References + html: reference-currency.html + targets: + - local + - ripple.com + # Tutorials are step-by-step guides to a specific goal - name: How to Multi-Sign category: Tutorials @@ -302,6 +309,13 @@ pages: - local - ripple.com + - md: concept-demurrage.md + category: Features + html: concept-demurrage.html + targets: + - local + - ripple.com + - md: concept-partial-payments.md category: Features html: concept-partial-payments.html From b6573902128970ef0264a2201e7d45d47f1ac12b Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Mon, 6 Nov 2017 10:50:33 -0800 Subject: [PATCH 4/5] Money intro/ref: Edits per @nbougalis & @bachase reviews --- content/concept-money.md | 10 +++++++--- content/reference-currency.md | 8 ++++---- content/reference-data-api.md | 10 +--------- content/snippets/string-number-formatting.md | 7 +++++++ 4 files changed, 19 insertions(+), 16 deletions(-) create mode 100644 content/snippets/string-number-formatting.md diff --git a/content/concept-money.md b/content/concept-money.md index 4be9c4149f..34522491cb 100644 --- a/content/concept-money.md +++ b/content/concept-money.md @@ -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. Users of the XRP Ledger can seamlessly track, trade, and settle multiple currencies in an exchange that's as decentralized as the network itself. Users can issue their own currency-like digital assets, 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. +The XRP Ledger is an advanced blockchain-like system that was designed to let people transact in multiple currencies. Users of the XRP Ledger can seamlessly track, trade, and settle multiple currencies in an exchange that's as decentralized as the network itself. Users can issue their own currency-like digital assets, 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 acts as a medium of exchange and serves anti-spam purposes. ## XRP @@ -8,7 +8,7 @@ The XRP Ledger is an advanced blockchain-like system that was designed to let pe Some advanced features of the XRP Ledger, such as [Escrow](concept-escrow.html) and [Payment Channels](tutorial-paychan.html), only work with XRP. Order book [autobridging](https://ripple.com/dev-blog/introducing-offer-autobridging/) uses XRP to deepen liquidity in the decentralized exchange by merging order books of two issued currencies with XRP order books to create synthetic combined order books. (For example, autobridging matches USD:XRP and XRP:EUR orders to augment USD:EUR order books.) -XRP also serves as a protective measure against spamming the network. All XRP Ledger addresses need a small amount of XRP to pay the costs of maintaining the XRP Ledger. The [transaction cost](concept-transaction-cost.html) and [reserve](concept-reserves.html) are neutral fees denoted in XRP and not paid to any party. In the ledger's data format, XRP is stored in [AccountRoot objects](reference-ledger-format.html#accountroot). +XRP also serves as a protective measure against spamming the network. All XRP Ledger addresses need a small amount of XRP to pay the costs of maintaining the XRP Ledger. The [transaction cost](concept-transaction-cost.html) and [reserve](concept-reserves.html) are neutral fees denominated in XRP and not paid to any party. In the ledger's data format, XRP is stored in [AccountRoot objects](reference-ledger-format.html#accountroot). For more information on XRP's use cases, benefits, and news, see the [XRP Portal](https://ripple.com/xrp-portal/). @@ -28,7 +28,11 @@ Issued currencies can be traded with XRP or each other in the XRP Ledger's decen In the typical model, an issued currency is tied to holdings of currency or other assets outside the XRP Ledger. The issuer of the currency, called a _gateway_, handles deposits and withdrawals to exchange currency outside the XRP Ledger for equivalent balances of issued currency in the XRP Ledger. For more information on how to run a gateway, see the [Gateway Guide](tutorial-gateway-guide.html). -There are other use cases for issued currencies in the XRP Ledger. For example, you can create an "Initial Coin Offering" (ICO) by issuing a fixed amount of currency to a secondary address, then "throwing away the key" to the issuer. (Be aware: ICOs may be [regulated as securities](https://www.sec.gov/oiea/investor-alerts-and-bulletins/ib_coinofferings) in the USA.) Ripple recommends researching the relevant regulations before engaging in any financial service business. +There are other use cases for issued currencies in the XRP Ledger. For example, you can create an "Initial Coin Offering" (ICO) by issuing a fixed amount of currency to a secondary address, then "throwing away the key" to the issuer. + +**Warning:** ICOs may be [regulated as securities](https://www.sec.gov/oiea/investor-alerts-and-bulletins/ib_coinofferings) in the USA. + +Ripple recommends researching the relevant regulations before engaging in any financial service business. ### Issued Currency Properties diff --git a/content/reference-currency.md b/content/reference-currency.md index 1649ae771b..ef295a69b9 100644 --- a/content/reference-currency.md +++ b/content/reference-currency.md @@ -4,16 +4,16 @@ The XRP Ledger has [two kinds of money](concept-money.html): XRP, and issued cur ## String Formatting -XRP Ledger APIs generally use strings, rather than native JSON numbers, to represent numeric amounts of currency for both XRP and issued currencies. This protects against a loss of precision when using JSON parsers, which may automatically try to represent all JSON numbers in a floating-point format. +{% include 'snippets/string-number-formatting.md' %} ## XRP Precision XRP has the same precision as a 64-bit unsigned integer where each unit is equivalent to 0.000001 XRP. Its properties are: * Minimum value: `0` -* Maximum value: `100000000000` (10^11) XRP - - `"100000000000000000"` (10^17) drops of XRP -* Precise to the nearest `0.000001` (10^-6) XRP +* Maximum value: `100000000000` (1011) XRP + - `"100000000000000000"` (1017) drops of XRP +* Precise to the nearest `0.000001` (10-6) XRP - `"1"` drop of XRP ## Issued Currency Precision diff --git a/content/reference-data-api.md b/content/reference-data-api.md index ee90f045a7..dc683dff88 100644 --- a/content/reference-data-api.md +++ b/content/reference-data-api.md @@ -4980,15 +4980,7 @@ As a REST API, the Data API v2 uses [JSON](http://json.org/)'s native datatypes ### Numbers and Precision ### [String - Number]: #numbers-and-precision -Currency amounts in the XRP Ledger require more precision than most native number types, so the Data API v2 uses the String type to represent some values. - -Within the String value, the numbers are serialized in the same way as native JSON numbers: - -* Base-10. -* Non-zero-prefaced. -* May contain `.` as a decimal point. For example, ½ is represented as `0.5`. (American style, not European) -* May contain `E` or `e` to indicate being raised to a power of 10. For example, `1.2E5` is equivalent to `120000`. -* No comma (`,`) characters are used. +{% include 'snippets/string-number-formatting.md' %} The precision for amounts of **non-XRP currency** in the XRP Ledger is as follows: diff --git a/content/snippets/string-number-formatting.md b/content/snippets/string-number-formatting.md new file mode 100644 index 0000000000..1ccad7c80d --- /dev/null +++ b/content/snippets/string-number-formatting.md @@ -0,0 +1,7 @@ +XRP Ledger APIs generally use strings, rather than native JSON numbers, to represent numeric amounts of currency for both XRP and issued currencies. This protects against a loss of precision when using JSON parsers, which may automatically try to represent all JSON numbers in a floating-point format. Within the String value, the numbers are serialized in the same way as native JSON numbers: + +* Base-10. +* Non-zero-prefaced. +* May contain `.` as a decimal point. For example, ½ is represented as `0.5`. (American style, not European) +* May contain `E` or `e` to indicate being raised to a power of 10 (scientific notation). For example, `1.2E5` is equivalent to 1.2×105, or `120000`. +* No comma (`,`) characters are used. From 43034c276bdb75f7dd75679b8bf9a2bb1cb440e7 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Thu, 9 Nov 2017 15:22:29 -0800 Subject: [PATCH 5/5] Money intro/currency format/demurrage: edits per reviews --- content/concept-demurrage.md | 2 ++ content/concept-money.md | 4 ++-- content/reference-currency.md | 4 ++-- 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/content/concept-demurrage.md b/content/concept-demurrage.md index aeca34a3ba..de40743194 100644 --- a/content/concept-demurrage.md +++ b/content/concept-demurrage.md @@ -69,7 +69,9 @@ To calculate an e-folding time for a given rate of annual percent interest: To support interest-bearing and demurraging currencies, client applications must implement several features: - When displaying the amount of a demurraging currency retrieved from ledger or transaction data, the client must convert from the ledger value to the display value. (With demurrage, the display values are smaller than the ledger values.) + - When accepting input for a demurraging currency, the client must convert amounts from a display format to the ledger format. (With demurrage, the ledger values are are larger than the user input value.) The client must use the ledger value when creating payments, offers, and other types of transaction. + - Clients must distinguish between currencies that do and do not have interest or demurrage, and among currencies that have different rates of interest or demurrage. Clients should be able to parse the [Interest-Bearing Currency Code Format](#interest-bearing-currency-code-format) into a display such as "XAU (-0.5% pa)". ### ripple-lib Support diff --git a/content/concept-money.md b/content/concept-money.md index 34522491cb..ebbafc499a 100644 --- a/content/concept-money.md +++ b/content/concept-money.md @@ -20,7 +20,7 @@ In technical contexts, XRP is measured precisely to the nearest 0.000001 XRP, ca ## Issued Currencies -All currencies other than XRP are represented as **issued currencies**. These digital assets, sometimes called "issuances" or "IOUs", are tracked in accounting relationships, called "trust lines," between addresses. Issued currencies are typically considered as liabilities from one perspective and assets from the other, so the balance of a trust line is negative or positive depending on which side you view it from. Any address may freely issue (non-XRP) currencies, limited only by how much other addresses are willing to hold. +All currencies other than XRP are represented as **issued currencies**. These digital assets (sometimes called "issuances" or "IOUs") are tracked in accounting relationships, called "trust lines," between addresses. Issued currencies are typically considered as liabilities from one perspective and assets from the other, so the balance of a trust line is negative or positive depending on which side you view it from. Any address may freely issue (non-XRP) currencies, limited only by how much other addresses are willing to hold. Issued currencies can "ripple" through multiple issuers and holders if they use the same currency code. This is useful in some cases, but can cause unexpected and undesirable behavior in others. You can use the [NoRipple flag](concept-noripple.html) on trust lines to prevent those trust lines from rippling. @@ -32,7 +32,7 @@ There are other use cases for issued currencies in the XRP Ledger. For example, **Warning:** ICOs may be [regulated as securities](https://www.sec.gov/oiea/investor-alerts-and-bulletins/ib_coinofferings) in the USA. -Ripple recommends researching the relevant regulations before engaging in any financial service business. +Ripple strongly recommends researching the relevant regulations before engaging in any financial service business. ### Issued Currency Properties diff --git a/content/reference-currency.md b/content/reference-currency.md index ef295a69b9..a59a682737 100644 --- a/content/reference-currency.md +++ b/content/reference-currency.md @@ -32,9 +32,9 @@ 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, 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. +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. -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. +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. ## Currency Codes