diff --git a/content/concepts/issued-currencies/freeze.md b/content/concepts/issued-currencies/freezes.md similarity index 100% rename from content/concepts/issued-currencies/freeze.md rename to content/concepts/issued-currencies/freezes.md diff --git a/content/concepts/issued-currencies/noripple.md b/content/concepts/issued-currencies/noripple.md deleted file mode 100644 index 7f8210e3fe..0000000000 --- a/content/concepts/issued-currencies/noripple.md +++ /dev/null @@ -1,58 +0,0 @@ -# Understanding the NoRipple Flag - -In the XRP Ledger, the "NoRipple" flag is a setting on a trust line. When an address enables the NoRipple flag on two trust lines, payments from third parties cannot "ripple" through that address on those trust lines. This protects liquidity providers from having balances shift unexpectedly between different issuers of the same currency. - -## Background - -"Rippling" occurs when more than one trust line is adjusted to make a payment. For example, if Alice owes Charlie money, and Alice also owes Bob money, then you could represent that in the XRP Ledger with trust lines like so: - -![Charlie --($10)-- Alice -- ($20) -- Bob](img/noripple-01.png) - -If Bob wants to pay $3 to Charlie, then he could say, "Alice, take $3 of the money you owe me, and pay it to Charlie." Alice transfers some of the debt from Bob to Charlie. In the end, the trust lines work out like so: - -![Charlie --($13)-- Alice --($17)-- Bob](img/noripple-02.png) - -We call this process, where two addresses pay each other by adjusting the balances of trust lines in between them, "rippling". This is a useful and important feature of the XRP Ledger. Rippling occurs when addresses are linked by trust lines that use the same [currency code](reference-rippled.html#currency-codes). The issuer does not need to be the same: in fact, larger chains always involve changing issuers. - -## Justification - -Sometimes you do not want your balances to ripple. For example, imagine Emily has money issued by two different financial institutions, like so - -![Charlie --($10)-- Institution A --($1)-- Emily --($100)-- Institution B --($2)-- Daniel](img/noripple-03.png) - -Now Charlie can pay Daniel by rippling through Emily's address. For example, if Charlie pays Daniel $10: - -![Charlie --($0)-- Institution A --($11)-- Emily --($90)-- Institution B --($12)-- Daniel](img/noripple-04.png) - -This may surprise Emily, who does not know Charlie or Daniel. Even worse, if Institution A charges her higher fees to withdraw her money than Institution B, this could cost Emily money. The NoRipple flag exists to avoid this scenario. If Emily sets it on both trust lines, then payments cannot ripple through her address using those two trust lines. - -For example: - -![Charlie --($10)-- Institution A --($1, NoRipple)-- Emily --($100,NoRipple)-- Institution B --($2)-- Daniel](img/noripple-05.png) - -Now the above scenario, where Charlie pays Daniel while rippling through Emily's address, is no longer possible. - -## Specifics - -The NoRipple flag makes certain paths invalid, so that they cannot be used to make payments. A path is considered invalid if and only if it enters **and** exits an address node through trust lines where NoRipple has been enabled for that address. - -![Diagram demonstrating that NoRipple has to be set on both trust lines by the same address to do anything](img/noripple-06.png) - -## Technical Details - -### Enabling / Disabling NoRipple - -The NoRipple flag can only be enabled on a trust line if the address has a positive or zero balance on that trust line. This is so that the feature cannot be abused to default on the obligation the trust line balance represents. (Of course, you can still default by abandoning the address.) - -In the [`rippled` APIs](reference-rippled.html), you can enable the NoRipple flag by sending a [TrustSet Transaction](reference-transaction-format.html#trustset) with the `tfSetNoRipple` flag. You can disable NoRipple (enable rippling) with the `tfClearNoRipple` flag. - -In [RippleAPI](reference-rippleapi.html), you can enable the NoRipple flag by sending a [Trustline transaction](reference-rippleapi.html#preparetrustline) transaction with the `ripplingDisabled` field of the trust line set to `true`. - - -### Looking Up NoRipple Status - -In the case of two accounts that mutually trust each other, the NoRipple flag is tracked separately for each account. - -In the [`rippled` APIs](reference-rippled.html), you can use the [account_lines method](https://ripple.com/build/rippled-apis/#account-lines) to look up the trust lines associated with an address. For each trust line, the `no_ripple` field shows whether the current address has enabled the NoRipple flag on that trust line, and the `no_ripple_peer` field shows whether the counterparty has enabled the NoRipple flag. - -In [RippleAPI](reference-rippleapi.html), you can use the [getTrustlines](reference-rippleapi.html#gettrustlines) method to look up the trust lines associated with an address. For each trust line, the `ripplingDisabled` field shows whether the current address has enabled the NoRipple flag on that trust line, and the `counterparty.ripplingDisabled` field shows whether the counterparty has enabled the NoRipple flag. diff --git a/content/concepts/issued-currencies/rippling.md b/content/concepts/issued-currencies/rippling.md new file mode 100644 index 0000000000..6d8ac61ab9 --- /dev/null +++ b/content/concepts/issued-currencies/rippling.md @@ -0,0 +1,83 @@ +# Rippling + +In the XRP Ledger, "rippling" describes a process of atomic net settlement between multiple connected parties who have [trust lines](trust-lines-and-issuing.html) for the same currency. Rippling is an essential part of issued currencies, because it allows users who trust the same issuer to send issued balances to each other with the issuer as a passive intermediary. In a sense, rippling is like a passive, two-way [currency exchange order](offers.html) with no limit and a 1:1 exchange rate for two currencies with the same currency code but different issuers. + +Rippling only occurs along the [paths](paths.html) of a payment. + +For non-issuing accounts, rippling can be undesirable because it lets other users shift obligations between issuers of the same currency. Thus, the [NoRipple Flag](#the-noripple-flag) disables rippling on all trust lines by default, unless the account enables rippling by default by enabling the [DefaultRipple flag](#the-defaultripple-flag). + + +## Example of Rippling + +"Rippling" occurs when more than one trust line is adjusted to make a payment. For example, if Alice owes Charlie money, and Alice also owes Bob money, then you could represent that in the XRP Ledger with trust lines like so: + +![Charlie --($10)-- Alice -- ($20) -- Bob](img/noripple-01.png) + +If Bob wants to pay $3 to Charlie, then he could say, "Alice, take $3 of the money you owe me, and pay it to Charlie." Alice transfers some of the debt from Bob to Charlie. In the end, the trust lines work out like so: + +![Charlie --($13)-- Alice --($17)-- Bob](img/noripple-02.png) + +We call this process, where two addresses pay each other by adjusting the balances of trust lines in between them, "rippling". This is a useful and important feature of the XRP Ledger. Rippling occurs when addresses are linked by trust lines that use the same [currency code][]. The issuer does not need to be the same: in fact, larger chains always involve changing issuers. + +## The NoRipple Flag + +Non-issuing accounts, especially liquidity providers who may hold balances from different issuers with different fees and policies, usually do not want their balances to ripple. + +The "NoRipple" flag is a setting on a trust line. When two trust lines both have NoRipple enabled by the same address, payments from third parties cannot "ripple" through that address on those trust lines. This protects liquidity providers from having balances shift unexpectedly between different issuers of the same currency. + +An account can disable NoRipple on a single trust line, which can allow rippling through any pair that includes that trust line. The account can also enable rippling globally by enabling the [DefaultRipple flag](#the-defaultripple-flag). + +For example, imagine Emily has money issued by two different financial institutions, like so + +![Charlie --($10)-- Institution A --($1)-- Emily --($100)-- Institution B --($2)-- Daniel](img/noripple-03.png) + +Now Charlie can pay Daniel by rippling through Emily's address. For example, if Charlie pays Daniel $10: + +![Charlie --($0)-- Institution A --($11)-- Emily --($90)-- Institution B --($12)-- Daniel](img/noripple-04.png) + +This may surprise Emily, who does not know Charlie or Daniel. Even worse, if Institution A charges her higher fees to withdraw her money than Institution B, this could cost Emily money. The NoRipple flag exists to avoid this scenario. If Emily sets it on both trust lines, then payments cannot ripple through her address using those two trust lines. + +For example: + +![Charlie --($10)-- Institution A --($1, NoRipple)-- Emily --($100,NoRipple)-- Institution B --($2)-- Daniel](img/noripple-05.png) + +Now the above scenario, where Charlie pays Daniel while rippling through Emily's address, is no longer possible. + +### Specifics + +The NoRipple flag makes certain paths invalid, so that they cannot be used to make payments. A path is considered invalid if and only if it enters **and** exits an address node through trust lines where NoRipple has been enabled for that address. + +![Diagram demonstrating that NoRipple has to be set on both trust lines by the same address to do anything](img/noripple-06.png) + + +## The DefaultRipple Flag + +The DefaultRipple flag is an account setting that enables rippling on all trust lines by default. Gateways and other currency issuers MUST enable this flag for other addresses to be able to send those the currencies among themselves. + +For more information, see [DefaultRipple in 'Becoming an XRP Ledger Gateway'](become-an-xrp-ledger-gateway.html#defaultripple). + + +## Using NoRipple + + +### Enabling / Disabling NoRipple + +The NoRipple flag can only be enabled on a trust line if the address has a positive or zero balance on that trust line. This is so that the feature cannot be abused to default on the obligation the trust line balance represents. (Of course, you can still default by abandoning the address.) + +In the [`rippled` APIs](rippled-apis.html), you can enable the NoRipple flag by sending a [TrustSet transaction][] with the `tfSetNoRipple` flag. You can disable NoRipple (enable rippling) with the `tfClearNoRipple` flag. + +In [RippleAPI](rippleapi.html), you can enable the NoRipple flag by sending a [Trustline transaction](reference-rippleapi.html#preparetrustline) transaction with the `ripplingDisabled` field of the trust line set to `true`. + + +### Looking Up NoRipple Status + +In the case of two accounts that mutually trust each other, the NoRipple flag is tracked separately for each account. + +In the [`rippled` APIs](reference-rippled.html), you can use the [account_lines method][] to look up the trust lines associated with an address. For each trust line, the `no_ripple` field shows whether the current address has enabled the NoRipple flag on that trust line, and the `no_ripple_peer` field shows whether the counterparty has enabled the NoRipple flag. + +In [RippleAPI](reference-rippleapi.html), you can use the [getTrustlines](rippleapi.html#gettrustlines) method to look up the trust lines associated with an address. For each trust line, the `ripplingDisabled` field shows whether the current address has enabled the NoRipple flag on that trust line, and the `counterparty.ripplingDisabled` field shows whether the counterparty has enabled the NoRipple flag. + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/issued-currencies/trust-lines-and-issuing.md b/content/concepts/issued-currencies/trust-lines-and-issuing.md new file mode 100644 index 0000000000..747d3f2400 --- /dev/null +++ b/content/concepts/issued-currencies/trust-lines-and-issuing.md @@ -0,0 +1,24 @@ +# Trust Lines and Issuing + +Frequently, [issued currencies](issued-currencies.html) in the XRP Ledger, represent value held by _gateways_ in the world outside the XRP Ledger. The address that issues those funds in the XRP Ledger is expected to pay the balance back, outside of the XRP Ledger, when users redeem their XRP Ledger balances by returning them to the issuer. + +Since a computer program cannot force a someone to keep a promise in the outside world, trust lines represent a way of configuring how much you trust an issuer to hold on your behalf. Since a large, reputable financial institution is more likely to be able to pay you back than, say, your broke roommate, you can set different limits on each trust line, to indicate the maximum amount you are willing to let the issuer "owe" you in the XRP Ledger. If the issuer defaults or goes out of business, you can lose up to that much money because the balances you hold in the XRP Ledger can no longer be exchanged for equivalent balances elsewhere. (You can still keep or trade the issued currency in the XRP Ledger, but there is probably no longer any reason to consider that issued currency to be worth anything.) + +There are two cases where you can hold a balance on a trust line that is _greater_ than your limit: when you acquire more of that currency through [trading](decentralized-exchange.html), or when you decrease the limit on your trust line. + +Since a trust line occupies space in the ledger, [a trust line increases the XRP your account must hold in reserve](reserves.html). This applies to the account extending trust, not to the account receiving it. + +Each trust line is specific to a given [currency code][]. Two accounts can have any number of trust lines between them for different currency codes, but only one trust line in either direction for any given currency code. + +## Trust Line Settings + +Trust lines are represented in the ledger's state data as [RippleState objects](ripplestate.html). A single RippleState object represents the potential for a trust line in either direction or both: it has a limit and other settings for each side, but a single shared net balance between the two sides. + +A trust line with settings in the default state is equivalent to no trust line. + +The default state of all trust line flags is off, except for the [NoRipple flag](rippling.html), whose default state depends on the DefaultRipple flag. + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-types/trustset.md b/content/references/rippled-api/transaction-formats/transaction-types/trustset.md index 131dea3426..ff3d3befac 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/trustset.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/trustset.md @@ -34,21 +34,6 @@ Create or modify a trust line linking two accounts. | QualityIn | Unsigned Integer | UInt32 | _(Optional)_ Value incoming balances on this trust line at the ratio of this number per 1,000,000,000 units. A value of `0` is shorthand for treating balances at face value. | | QualityOut | Unsigned Integer | UInt32 | _(Optional)_ Value outgoing balances on this trust line at the ratio of this number per 1,000,000,000 units. A value of `0` is shorthand for treating balances at face value. | -## Trust Limits - -All balances on the XRP Ledger, except for XRP, represent value owed in the world outside the XRP Ledger. The address that issues those funds in the XRP Ledger (identified by the `issuer` field of the `LimitAmount` object) is expected to pay the balance back, outside of the XRP Ledger, when users redeem their XRP Ledger balances by returning them to the issuer. - -Since a computer program cannot force a someone to keep a promise and not default in real life, trust lines represent a way of configuring how much you trust an issuer to hold on your behalf. Since a large, reputable financial institution is more likely to be able to pay you back than, say, your broke roommate, you can set different limits on each trust line, to indicate the maximum amount you are willing to let the issuer "owe" you in the XRP Ledger. If the issuer defaults or goes out of business, you can lose up to that much money because the balances you hold in the XRP Ledger can no longer be exchanged for equivalent balances elsewhere. (You can still keep or trade the issuances in the XRP Ledger, but they no longer have any reason to be worth anything.) - -There are two cases where you can hold a balance on a trust line that is *greater* than your limit: when you acquire more of that currency through [trading](#offercreate), or when you decrease the limit on your trust line. - -Since a trust line occupies space in the ledger, [a trust line increases the XRP your account must hold in reserve](reserves.html). This applies to the account extending trust, not to the account receiving it. - -A trust line with settings in the default state is equivalent to no trust line. - -The default state of all flags is off, except for the [NoRipple flag](noripple.html), whose default state depends on the DefaultRipple flag. - -The Auth flag of a trust line does not determine whether the trust line counts towards its owner's XRP reserve requirement. However, an enabled Auth flag prevents the trust line from being in its default state. An authorized trust line can never be deleted. An issuer can pre-authorize a trust line with the `tfSetfAuth` flag only, even if the limit and balance of the trust line are 0. ## TrustSet Flags @@ -62,6 +47,8 @@ Transactions of the TrustSet type support additional values in the [`Flags` fiel | tfSetFreeze | 0x00100000 | 1048576 | [Freeze](freeze.html) the trustline. | | tfClearFreeze | 0x00200000 | 2097152 | [Unfreeze](freeze.html) the trustline. | +The Auth flag of a trust line does not determine whether the trust line counts towards its owner's XRP reserve requirement. However, an enabled Auth flag prevents the trust line from being in its default state. An authorized trust line can never be deleted. An issuer can pre-authorize a trust line with the `tfSetfAuth` flag only, even if the limit and balance of the trust line are 0. + {% include '_snippets/rippled-api-links.md' %} {% include '_snippets/tx-type-links.md' %} diff --git a/dactyl-config.yml b/dactyl-config.yml index ec9290028f..8d40be7d75 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -286,7 +286,14 @@ pages: targets: - local - # TODO: "Trust Lines and Issuing" (see gateway guide, tx reference on "trust limits" etc.) + - md: concepts/issued-currencies/trust-lines-and-issuing.md + html: trust-lines-and-issuing.html + funnel: Docs + doc_type: Concepts + category: Issued Currencies + blurb: Learn about the properties and rationale of trust lines. + targets: + - local - md: concepts/issued-currencies/authorized-trust-lines.md html: authorized-trust-lines.html @@ -296,7 +303,50 @@ pages: targets: - local - # TODO: Freezes, Rippling, Transfer Fees, Paths, Demurrage + - md: concepts/issued-currencies/freezes.md + html: freezes.html + funnel: Docs + doc_type: Concepts + category: Issued Currencies + blurb: Freezes can suspend trading of issued currencies for compliance purposes. + targets: + - local + + - md: concepts/issued-currencies/rippling.md + html: rippling.html + funnel: Docs + doc_type: Concepts + category: Issued Currencies + blurb: Rippling is automatic multi-party net settlement of issued currency balances. + targets: + - local + + - md: concepts/issued-currencies/transfer-fees.md + html: transfer-fees.html + funnel: Docs + doc_type: Concepts + category: Issued Currencies + blurb: Currency issuers can charge a fee for transferring their issued currencies. + targets: + - local + + - md: concepts/issued-currencies/paths.md + html: paths.html + funnel: Docs + doc_type: Concepts + category: Issued Currencies + blurb: Payments of issued currencies must traverse paths of connected users and order books. + targets: + - local + + - md: concepts/issued-currencies/demurrage.md + html: demurrage.html + funnel: Docs + doc_type: Concepts + category: Issued Currencies + blurb: (Obsolete) Some older XRP Ledger tools used to support currency codes with built-in interest and negative interest rates. + targets: + - local - name: Decentralized Exchange html: decentralized-exchange.html