From a6d9b53b6184d9a66356639e5678a8dd0fca7d34 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Fri, 11 Feb 2022 17:58:39 -0800 Subject: [PATCH 01/50] Reword content articles to use "tokens" This replaces the old wording of "issued currencies" and introduces broader usage of the term "stablecoins" to more closely match the terminology in use by the wider industry. I've also added a draft "Common Misunderstandings about Freezes" page so that the Freeze page doesn't have to protest quite so much, and written a very brief word on tokens' use for community credit. This commit only covers the Concepts section, in English, and likely leaves some links to the old URLs for the renamed pages. --- ...issuing-and-operational-addresses-intro.md | 2 +- content/concepts/issued-currencies/freezes.md | 110 ------------------ .../issued-currencies-overview.md | 73 ------------ .../issuing-and-operational-addresses.md | 81 ------------- .../authorized-trust-lines.ja.md | 2 +- .../authorized-trust-lines.md | 35 +++--- .../common-misconceptions-about-freezes.md | 32 +++++ .../demurrage.ja.md | 2 +- .../demurrage.md | 22 ++-- .../freezes.ja.md | 2 +- content/concepts/tokens/freezes.md | 104 +++++++++++++++++ .../issuing-and-operational-addresses.ja.md | 2 +- .../issuing-and-operational-addresses.md | 88 ++++++++++++++ .../non-fungible-tokens.md} | 4 +- .../{issued-currencies => tokens}/paths.ja.md | 2 +- .../{issued-currencies => tokens}/paths.md | 18 +-- .../rippling.ja.md | 2 +- .../{issued-currencies => tokens}/rippling.md | 14 +-- .../tokens.ja.md} | 3 +- content/concepts/tokens/tokens.md | 82 +++++++++++++ .../transfer-fees.ja.md | 2 +- .../transfer-fees.md | 26 +++-- .../trust-lines-and-issuing.ja.md | 2 +- .../trust-lines-and-issuing.md | 14 ++- dactyl-config.yml | 89 ++++++++------ 25 files changed, 445 insertions(+), 368 deletions(-) delete mode 100644 content/concepts/issued-currencies/freezes.md delete mode 100644 content/concepts/issued-currencies/issued-currencies-overview.md delete mode 100644 content/concepts/issued-currencies/issuing-and-operational-addresses.md rename content/concepts/{issued-currencies => tokens}/authorized-trust-lines.ja.md (99%) rename content/concepts/{issued-currencies => tokens}/authorized-trust-lines.md (61%) create mode 100644 content/concepts/tokens/common-misconceptions-about-freezes.md rename content/concepts/{issued-currencies => tokens}/demurrage.ja.md (99%) rename content/concepts/{issued-currencies => tokens}/demurrage.md (72%) rename content/concepts/{issued-currencies => tokens}/freezes.ja.md (99%) create mode 100644 content/concepts/tokens/freezes.md rename content/concepts/{issued-currencies => tokens}/issuing-and-operational-addresses.ja.md (99%) create mode 100644 content/concepts/tokens/issuing-and-operational-addresses.md rename content/concepts/{nft-concepts/nft-conceptual-overview.md => tokens/non-fungible-tokens.md} (98%) rename content/concepts/{issued-currencies => tokens}/paths.ja.md (99%) rename content/concepts/{issued-currencies => tokens}/paths.md (79%) rename content/concepts/{issued-currencies => tokens}/rippling.ja.md (99%) rename content/concepts/{issued-currencies => tokens}/rippling.md (82%) rename content/concepts/{issued-currencies/issued-currencies-overview.ja.md => tokens/tokens.ja.md} (99%) create mode 100644 content/concepts/tokens/tokens.md rename content/concepts/{issued-currencies => tokens}/transfer-fees.ja.md (99%) rename content/concepts/{issued-currencies => tokens}/transfer-fees.md (51%) rename content/concepts/{issued-currencies => tokens}/trust-lines-and-issuing.ja.md (99%) rename content/concepts/{issued-currencies => tokens}/trust-lines-and-issuing.md (62%) diff --git a/content/_snippets/issuing-and-operational-addresses-intro.md b/content/_snippets/issuing-and-operational-addresses-intro.md index b32fee5de3..1e327648e0 100644 --- a/content/_snippets/issuing-and-operational-addresses-intro.md +++ b/content/_snippets/issuing-and-operational-addresses-intro.md @@ -1,4 +1,4 @@ -In the XRP Ledger, financial institutions typically use multiple XRP Ledger addresses to minimize the risk associated with a compromised secret key. Ripple strongly recommends the following separation of roles: +In the XRP Ledger, financial institutions typically use multiple XRP Ledger addresses to minimize the risk associated with a compromised secret key. The industry standard is to separate roles as follows: * One **issuing address**, also known as a "cold wallet." This address is the hub of the financial institution's accounting relationships in the ledger, but sends as few transactions as possible. * One or more **operational addresses**, also known as "hot wallets." Automated, internet-connected systems use the secret keys to these addresses to conduct day-to-day business like transfers to customers and partners. diff --git a/content/concepts/issued-currencies/freezes.md b/content/concepts/issued-currencies/freezes.md deleted file mode 100644 index b90015d367..0000000000 --- a/content/concepts/issued-currencies/freezes.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -html: freezes.html -parent: issued-currencies.html -blurb: Freezes can suspend trading of issued currencies for compliance purposes. -labels: - - Tokens ---- -# Freezing Issued Currencies - -Issuers can freeze the tokens they issue in the XRP Ledger. - -XRP is not an issued currency. XRP is the only native asset on the XRP Ledger and is required to conduct transactions on the XRP Ledger. XRP has no counterparty, meaning that when someone holds XRP, they are not holding a liability, they are holding the actual currency, XRP. Due to this fact, _**XRP CANNOT be frozen by any entity or individual**_. - -All non-XRP currencies can be represented in the XRP Ledger as issued currencies. These issued currencies (sometimes called "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. - -In certain cases, to meet regulatory requirements, or while investigating suspicious activity, an exchange or gateway may want to quickly freeze non-XRP issued currency balances. - -**Tip:** No one can freeze XRP in the XRP Ledger. However, custodial exchanges can always freeze the funds they custody at their own discretion. - -There are three settings related to freezes: - -* [**Individual Freeze**](#individual-freeze) - Freeze one counterparty. -* [**Global Freeze**](#global-freeze) - Freeze all counterparties. -* [**No Freeze**](#no-freeze) - Permanently give up the ability to freeze individual counterparties, as well as the ability to end a global freeze. - -The freeze feature only applies to issued currencies. Because no party has a privileged place in the XRP Ledger, the freeze feature cannot prevent a counterparty from conducting transactions in XRP or funds issued by other counterparties. No one can freeze XRP. - -All freeze settings can be enacted regardless of whether the balance(s) to be frozen are positive or negative. Either the currency issuer or the currency holder can freeze a trust line; however, the effect of a currency holder freezing an issuer is minimal. - - -## Individual Freeze - -The **Individual Freeze** feature is a setting on a [trust line](trust-lines-and-issuing.html). When an issuing address enables the Individual Freeze setting, the following rules apply to the currency of that trust line: - -* Payments can still occur directly between the two parties of the frozen trust line. -* The counterparty of that trust line can no longer decrease its balance on the frozen trust line, except in direct payments to the issuer. The counterparty can only send the frozen currencies directly to the issuer. -* The counterparty can still receive payments from others on the frozen trust line. -* The counterparty's offers to sell the currency issued on the frozen trust line are [considered unfunded](offers.html#lifecycle-of-an-offer). - -Reminder: Trust lines do not hold XRP. XRP cannot be frozen. - -A financial institution can freeze the trust line linking it to a counterparty if that counterparty shows suspicious activity or violates the financial institution's terms of use. The financial institution should also freeze the counterparty in any other systems the financial institution uses that are connected to the XRP Ledger. (Otherwise, an address might still be able to engage in undesired activity by sending payments through the financial institution.) - -An individual address can freeze its trust line to a financial institution. This has no effect on transactions between the institution and other users. It does, however, prevent other addresses, including [operational addresses](issuing-and-operational-addresses.html), from sending that financial institution's issued currencies to the individual address. This type of individual freeze has no effect on offers. - -The Individual Freeze applies to a single currency only. To freeze multiple currencies with a particular counterparty, the address must enable Individual Freeze on the trust lines for each currency individually. - -An address cannot enable the Individual Freeze setting if it has enabled the [No Freeze](#no-freeze) setting. - - -## Global Freeze - -The **Global Freeze** feature is a setting on an address. When an issuing address enables the Global Freeze feature, the following rules apply to all currencies they issue: - -* All counterparties of the frozen issuing address can no longer decrease the balances in their trust lines to the frozen address, except in direct payments to the issuer. (This also affects any [operational addresses](issuing-and-operational-addresses.html).) -* Counterparties of the frozen issuing address can still send and receive payments directly to and from the issuing address. -* All offers to sell currencies issued by the frozen address are [considered unfunded](offers.html#lifecycle-of-an-offer). - -Reminder: addresses cannot issue XRP. Global freezes do not apply to XRP. - -It can be useful to enable Global Freeze on a financial institution's [issuing address](issuing-and-operational-addresses.html) if the secret key to an operational address is compromised, even after regaining control of a such an address. This stops the flow of funds, preventing attackers from getting away with any more money or at least making it easier to track what happened. Besides enacting a Global Freeze in the XRP Ledger, a financial institution should also suspend activities in its connectors to outside systems. - -It can also be useful to enable Global Freeze if a financial institution intends to migrate to a new [issuing address](issuing-and-operational-addresses.html), or if the financial institution intends to cease doing business. This locks the funds at a specific point in time, so users cannot trade them away for other currencies. - -Global Freeze applies to _all_ currencies issued and held by the address. You cannot enable Global Freeze for only one currency. If you want to have the ability to freeze some currencies and not others, you should use different addresses for each currency. - -An address can always enable the Global Freeze setting. However, if the address has enabled the [No Freeze](#no-freeze) setting, it can never _disable_ Global Freeze. - - -## No Freeze - -The **No Freeze** feature is a setting on an address that permanently gives up the ability to freeze issued currencies arbitrarily. An issuer can use this feature to treat its issued funds as "more like physical money" in the sense that the issuer cannot interfere with counterparties trading the currency among themselves. - -Reminder: XRP already cannot be frozen. The No Freeze feature only applies to other currencies issued in the XRP Ledger. - -The No Freeze setting has two effects: - -* The issuing address can no longer enable Individual Freeze on trust lines to any counterparty. -* The issuing address can still enable Global Freeze to enact a global freeze, but the address cannot _disable_ Global Freeze. - -The XRP Ledger cannot force an issuer to honor the obligations that its issued funds represent, so No Freeze does stop an issuer from defaulting on its obligations. However, No Freeze ensures that an issuer does not use the Global Freeze feature unfairly against specific users. - -The No Freeze setting applies to all currencies issued to and from an address. If you want to be able to freeze some currencies but not others, you should use different addresses for each currency. - -You can only enable the No Freeze setting with a transaction signed by your address's master key secret. You cannot use a [Regular Key](setregularkey.html) or a [multi-signed transaction](multi-signing.html) to enable No Freeze. - - - -# See Also - -- [GB-2014-02 New Feature: Balance Freeze](https://ripple.com/files/GB-2014-02.pdf) -- [Freeze Code Samples](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_code-samples/freeze) -- **Concepts:** - - [Trust Lines and Issuing](trust-lines-and-issuing.html) -- **Tutorials:** - - [Enable No Freeze](enable-no-freeze.html) - - [Enact Global Freeze](enact-global-freeze.html) - - [Freeze a Trust Line](freeze-a-trust-line.html) -- **References:** - - [account_lines method][] - - [account_info method][] - - [AccountSet transaction][] - - [TrustSet transaction][] - - [AccountRoot Flags](accountroot.html#accountroot-flags) - - [RippleState (trust line) Flags](ripplestate.html#ripplestate-flags) - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/issued-currencies/issued-currencies-overview.md b/content/concepts/issued-currencies/issued-currencies-overview.md deleted file mode 100644 index 26084d6405..0000000000 --- a/content/concepts/issued-currencies/issued-currencies-overview.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -html: issued-currencies-overview.html -parent: issued-currencies.html -blurb: Get an overview of issued currencies and their properties in the XRP Ledger. -labels: - - Tokens ---- -# Issued Currencies Overview - -All currencies other than XRP can be represented in the XRP Ledger as **issued currencies**. These digital assets (sometimes called "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 [No Ripple flag](rippling.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 [Becoming an XRP Ledger Gateway](become-an-xrp-ledger-gateway.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. - -**Warning:** ICOs may be [regulated as securities](https://www.sec.gov/oiea/investor-alerts-and-bulletins/ib_coinofferings) in the USA. - -Be sure to research the relevant regulations before engaging in any financial service business. - - -## Issued Currency Usage - -A trust line represents an explicit statement of willingness to hold gateway debt obligations. (In other words: "I'll allow you to owe me up to this much money outside the XRP Ledger.") - -The intended model for issued currency usage is with _gateways_, trusted financial institutions that custody outside-world assets and allow them to be used in the XRP Ledger for [cross-currency payments](cross-currency-payments.html) and trading in the [decentralized exchange](decentralized-exchange.html). The flow looks something like this: - -1. A customer sends money to a gateway. This could be fiat money, Bitcoin, or any other assets that aren't native to the XRP Ledger. -2. The gateway takes custody of the money and records it. -3. The gateway issues a balance in the XRP Ledger, denominated in the same currency, to an address belonging to the customer. -4. The customer uses the issued currency in the XRP Ledger however they want, such as by sending [cross-currency payments](cross-currency-payments.html) or by trading in the [decentralized exchange](decentralized-exchange.html). -5. A customer (not necessarily the one who deposited the money initially) sends the issued currency to the gateway's XRP Ledger address. -6. The gateway confirms the identity of the customer who sent the balance in the XRP Ledger funds, and gives the corresponding amount of money _outside the XRP Ledger_ to that customer. - -The details of the process of sending money "into" and "out of" the XRP Ledger can vary based on the gateway, the jurisdiction, the type of assets involved, and other factors. - - -## Issued Currency Properties - -All issued currencies in the XRP Ledger exist in trust lines, represented in the ledger's data as [RippleState objects](ripplestate.html). 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. - -The issuer of a currency can define a percentage [transfer fee](transfer-fees.html) to deduct when two parties transact in its issued currencies. - -Addresses can also [freeze](freezes.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 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](currency-formats.html). - -## See Also - -- **Concepts:** - - [XRP](xrp.html) - - [Cross-Currency Payments](cross-currency-payments.html) - - [Decentralized Exchange](decentralized-exchange.html) -- **Tutorials:** - - [Issue a Fungible Token](issue-a-fungible-token.html) - - [Become an XRP Ledger Gateway](become-an-xrp-ledger-gateway.html) - - [Look Up Transaction Results](look-up-transaction-results.html) - - [Use Specialized Payment Types](use-specialized-payment-types.html) -- **References:** - - [Payment transaction][] - - [TrustSet transaction][] - - [RippleState object](ripplestate.html) - - [account_lines method][] - - [account_currencies method][] - - [gateway_balances method][] - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/issued-currencies/issuing-and-operational-addresses.md b/content/concepts/issued-currencies/issuing-and-operational-addresses.md deleted file mode 100644 index cf1b9618f9..0000000000 --- a/content/concepts/issued-currencies/issuing-and-operational-addresses.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -html: issuing-and-operational-addresses.html -parent: issued-currencies.html -blurb: Businesses sending transactions on the XRP Ledger automatically should set up separate addresses for different purposes to minimize risk. -labels: - - Tokens - - Security ---- -# Issuing and Operational Addresses - -{% include '_snippets/issuing-and-operational-addresses-intro.md' %} - - -## Funds Lifecycle - -All non-XRP balances in the XRP Ledger are _issued currencies_ which are tied to accounting relationships between two XRP Ledger addresses. When a financial institution uses Ripple's recommended separation of roles, funds relating to that institution tend to flow in a cycle. - -{{ include_svg("img/issued-currency-funds-flow.svg", "Diagram: Funds flow from the issuing address to standby addresses, to operational addresses, to customer and partner addresses, and finally back to the issuing address.")}} - -When the issuing address sends payments, it creates balances in the accounting relationships in the XRP Ledger. Within the XRP Ledger, users can exchange balances across different accounting relationships, so we use the term _issued currency_ to describe any non-XRP balance. (These can represent any type of value, not only "currencies" in the traditional sense.) Issued currencies have negative value from the perspective of the issuing address, since they represent obligations. The same issued currencies have positive value from the perspective of the issuing address's counterparties. When the issuing address receives a payment, this reduces its obligations, erasing the issued currencies that were sent. - -The issuing address sends issued currencies to a standby address, or directly to an operational address. The standby addresses send those issued currencies to operational addresses. Operational addresses send payments to other counterparties, such as liquidity providers, partners, and other customers. Because all issued currencies are tied to accounting relationships with the issuing address, payments and exchanges of issued currencies "ripple through" the issuing address. The payment debits the sender's balance in its accounting relationship with the issuing address and credits the recipient's balance in the recipient's accounting relationship with the issuing address. The XRP Ledger also supports more complicated [paths](paths.html) that connect multiple issuers through order books and [liquidity providers who allow their funds to ripple](rippling.html). - -## Issuing Address - -The issuing address is like a vault. Partners, customers, and operational addresses create accounting relationships (trust lines) to the issuing address, but this address sends as few transactions as possible. Periodically, a human operator creates and signs a transaction from the issuing address to refill the balances of a standby or operational address. Ideally, the secret key used to sign these transactions should never be accessible from any internet-connected computer. - -Unlike a vault, the issuing address can receive payments directly from customers and partners. Since all transactions in the XRP Ledger are public, automated systems can monitor for payments to the issuing address without needing a secret key. - -### Issuing Address Compromise - -If a malicious actor learns the secret key behind a institution's issuing address, that actor can create new issued currencies without limit and trade them in the decentralized exchange. This would make it difficult for the financial institution to distinguish legitimately-obtained issued currencies and redeem them fairly. If a financial institution loses control of its issuing address, the institution must create a new issuing address, and all users who have accounting relationships with the old issuing address must create new accounting relationships with the new address. - -### Multiple Issuing Addresses - -A financial institution can issue more than one currency in the XRP Ledger from a single issuing address. However, there are some settings that apply equally to all currencies issued from an address, including the percentage for [transfer fees](transfer-fees.html) and the [global freeze](freezes.html) status. If the financial institution wants the flexibility to manage settings differently for each currency, the institution must use a different issuing address for each currency. - - -## Operational Addresses - -An operational address is like a cash register. It makes payments on behalf of the institution by transferring issued currencies to customers and partners. To sign transactions automatically, the secret key for an operational address must be stored on a server that is connected to the internet. (The secret key can be stored encrypted, but the server must decrypt it to sign transactions.) Customers and partners do not, and should not, create accounting relationships with an operational address. - -Each operational address has a limited balance of issued currencies. When the balance of an operational address gets low, the financial institution refills it by sending a payment from the issuing address or a standby address. - -### Operational Address Compromise - -If a malicious actor learns the secret key behind an operational address, the financial institution can only lose as much currency as that operational address holds. The institution can switch to a new operational address with no action from customers and partners. - - -## Standby Addresses - -Another optional step that an institution can take to balance risk and convenience is to use "standby addresses" as an intermediate step between the issuing address and operational addresses. The institution can fund additional XRP Ledger addresses as standby addresses, whose keys are not stored online, but are entrusted to different trusted users. - -When an operational address is running low on funds, a trusted user can use a standby address to refill the operational address's balance. When a standby addresses run low on funds, the institution can use the issuing address to send more currency to a standby address in a single transaction, and the standby addresses can distribute that currency among themselves if necessary. This improves security of the issuing address, allowing it to make fewer total transactions, without leaving too much money in the control of a single automated system. - -As with operational addresses, a standby address must have an accounting relationship with the issuing address, and not with customers or partners. All precautions that apply to operational addresses also apply to standby addresses. - -### Standby Address Compromise - -If a standby address is compromised, the consequences are like an operational address being compromised. A malicious actor can steal any balances possessed by the standby address, and the financial institution can change to a new standby address with no action from customers and partners. - - -## See Also - -- **Concepts:** - - [Accounts](accounts.html) - - [Cryptographic Keys](cryptographic-keys.html) -- **Tutorials:** - - [Become an XRP Ledger Gateway](become-an-xrp-ledger-gateway.html) - - [Assign a Regular Key Pair](assign-a-regular-key-pair.html) - - [Change or Remove a Regular Key Pair](change-or-remove-a-regular-key-pair.html) -- **References:** - - [account_info method][] - - [SetRegularKey transaction][] - - [AccountRoot object](accountroot.html) - - - -{% include '_snippets/rippled-api-links.md' %} -{% include '_snippets/tx-type-links.md' %} -{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/issued-currencies/authorized-trust-lines.ja.md b/content/concepts/tokens/authorized-trust-lines.ja.md similarity index 99% rename from content/concepts/issued-currencies/authorized-trust-lines.ja.md rename to content/concepts/tokens/authorized-trust-lines.ja.md index f54aa65106..65ba7b9400 100644 --- a/content/concepts/issued-currencies/authorized-trust-lines.ja.md +++ b/content/concepts/tokens/authorized-trust-lines.ja.md @@ -1,6 +1,6 @@ --- html: authorized-trust-lines.html -parent: issued-currencies.html +parent: tokens.html blurb: 通貨発行者が自己の発行済み通貨を保有できる人を制限できる、Authorized Trust Lineについて説明します。 labels: - トークン diff --git a/content/concepts/issued-currencies/authorized-trust-lines.md b/content/concepts/tokens/authorized-trust-lines.md similarity index 61% rename from content/concepts/issued-currencies/authorized-trust-lines.md rename to content/concepts/tokens/authorized-trust-lines.md index 5424fd3c3a..cf8abeaac3 100644 --- a/content/concepts/issued-currencies/authorized-trust-lines.md +++ b/content/concepts/tokens/authorized-trust-lines.md @@ -1,36 +1,41 @@ --- html: authorized-trust-lines.html -parent: issued-currencies.html -blurb: Learn about authorized trust lines, which enable a currency issuer to limit who can hold its issued (non-XRP) currencies. +parent: tokens.html +blurb: Authorized trust lines is a setting to limit who can hold a token. labels: - Tokens - Security --- # Authorized Trust Lines -The XRP Ledger's Authorized Trust Lines feature enables a currency issuer to limit who can hold its issued (non-XRP) currencies, so that unknown XRP Ledger addresses cannot hold those currencies. The Authorized Trust Lines feature only applies to issued currencies and has no effect on XRP. +The Authorized Trust Lines feature enables issuers to create tokens that can only be held by accounts that the issuer specifically authorizes. This feature only applies to tokens, not XRP. -To use the Authorized Trust Lines feature, enable the `RequireAuth` flag on your issuing address. After doing so, your issuing address can send [TrustSet transactions][] to authorize trust lines from other addresses. While RequireAuth is enabled, other addresses can only hold funds issued by your address if the trust line to your issuing address has been authorized. +To use the Authorized Trust Lines feature, enable the `RequireAuth` flag on your issuing account. While the setting is enabled, other accounts can only hold tokens you issue if you have authorized those accounts' trust lines to your issuing account. -The transaction to authorize a trust line must be signed by the issuing address, which unfortunately means an increased risk exposure for that address. The process for sending funds into the XRP Ledger with `RequireAuth` enabled looks like the following: +You can authorize a trust line by sending a [TrustSet transaction][] from your issuing address, configuring the trust line between your account and the account to authorize. After you have authorized a trust line, you can never revoke that authorization. (You can, however, [freeze](freezes.html) that trust line if you need to.) -1. An issuing gateway publishes its issuing address to customers. -2. A customer sends a [TrustSet transaction][] to create a trust line from her XRP Ledger address to the gateway's issuing address. This indicates that she is willing to hold a specific currency issued by the gateway, up to a specific numeric limit. -3. The gateway's issuing address sends a TrustSet transaction authorizing the customer's trust line. +The transaction to authorize a trust line must be signed by the issuing address, which unfortunately means an increased risk exposure for that address. -**Tip:** An issuing gateway can authorize a trust line preemptively (step 3), before the customer has created it. This creates a trust line with zero limit, so that the customer's TrustSet transaction (step 2) sets the limit on the pre-authorized trust line. _(Added by the [TrustSetAuth amendment][].)_ +**Caution:** You can only enable `RequireAuth` if your account has no trust lines and no Offers in the XRP Ledger, so you must decide whether or not to use it _before_ you start issuing tokens. -## RequireAuth Setting +## With Stablecoin Issuing - +With a stablecoin on the XRP Ledger and use Authorized Trust Lines, the process of onboarding a new customer might look something like the following: -The `RequireAuth` setting prevents all counterparties from holding balances issued by an address unless the issuing address has specifically approved a trust line with that counterparty for the currency in question. +1. The customer registers with the stablecoin issuer's systems and sends proof of their identity (also known as "Know Your Customer", or KYC, information). +2. The customer and stablecoin issuer tell each other their XRP Ledger addresses. +3. The customer sends a [TrustSet transaction][] to create a trust line to the issuer's address, with a positive limit. +4. The issuer sends a TrustSet transaction to authorize the customer's trust line. -As a precaution, Ripple recommends that issuing gateways always enable `RequireAuth` on [operational addresses and standby addresses](issuing-and-operational-addresses.html), and then never approve any trust lines to those addresses. This prevents operational addresses and standby addresses from issuing currency in the XRP Ledger even by accident. This is a purely precautionary measure, and does not stop those addresses from transferring issued currency balances created by the issuing address, as they are intended to do. +**Tip:** The issuer can authorize a trust line preemptively (step 3), before the customer has created it. This creates a trust line with zero limit, so that the customer's TrustSet transaction (step 2) sets the limit on the pre-authorized trust line. _(Added by the [TrustSetAuth amendment][].)_ -To use the Authorized Trust Lines feature, an issuer must also enable `RequireAuth` on its issuing address. After doing so, the issuing address must [submit a `TrustSet` transaction to approve each trust line](#authorizing-trust-lines) from a customer. +## As a Precaution -**Caution:** An account can only enable `RequireAuth` if it owns no trust lines and no offers in the XRP Ledger, so you must decide whether or not to use it before you start doing business in the XRP Ledger. +Even if you don't intend to use Authorized Trust Lines, you can enable the `RequireAuth` setting on [operational and standby accounts](issuing-and-operational-addresses.html), and then never have those accounts approve any trust lines. This prevents those accounts from issuing tokens by accident (for example, if a user accidentally trusts the wrong address). This is a purely precautionary measure, and does not stop the operational and standby accounts from transferring the _issuer's_ tokens, as intended. + + +## Technical Details + ### Enabling RequireAuth diff --git a/content/concepts/tokens/common-misconceptions-about-freezes.md b/content/concepts/tokens/common-misconceptions-about-freezes.md new file mode 100644 index 0000000000..2d18c1b351 --- /dev/null +++ b/content/concepts/tokens/common-misconceptions-about-freezes.md @@ -0,0 +1,32 @@ +--- +parent: freezes.html +blurb: Clarify common misunderstandings about the XRP Ledger's freeze feature. +labels: + - Tokens +--- +# Common Misunderstandings about Freezes + +It is a common misconception that Ripple or others can freeze XRP, similar to how centralized services like PayPal can suspend your account and prevent you from accessing your funds. In reality, while the XRP Ledger does have a [freeze feature](freezes.html), it can only be used on issued tokens, not on XRP. **No one can freeze XRP.** + +Tokens in the XRP Ledger are [fundamentally different than XRP](currency-formats.html#comparison). Tokens always exist _in trust lines_, which _can_ be frozen. XRP exists in accounts, which _cannot_ be frozen. + +## Isn't XRP Just Ripple's Token? + +No, XRP is different from tokens. XRP is the only native asset on the XRP Ledger and is required to conduct transactions on the XRP Ledger. XRP has no counterparty, meaning that when someone holds XRP, they are not holding a liability, they are holding the actual currency, XRP. Due to this fact, _**XRP CANNOT be frozen by any entity or individual**_. + +## Can Ripple Freeze My Tokens? Or the XRP Ledger Foundation? + +The XRP Ledger is decentralized so that no one party has control over it—not Ripple, not the XRP Ledger Foundation, and not anyone else. + +The _issuer_ of a token can freeze your trust line for _that token specifically_. They can't freeze the rest of your account, or any tokens from different issuers, and they can't stop you from using the XRP Ledger. + +Furthermore, token issuers can voluntarily and permanently _give up_ their ability to freeze tokens. This ["No Freeze"](freezes.html#no-freeze) setting is intended to allow tokens to behave more like physical cash, in that third parties can't stop you from using it. + + +## But I Heard Ripple Froze Jed McCaleb's XRP? + +This is a misrepresentation of events that actually happened in 2015–2016. Jed McCaleb, a Ripple founder who left the company in 2013, attempted to sell over $1 million US worth of XRP on Bitstamp, a custodial exchange. Ripple representatives argued that this sale would breach an agreement that Jed and Ripple made in 2014. At Ripple's request, [Bitstamp froze Jed's Bitstamp account](https://www.coindesk.com/markets/2015/04/02/1-million-legal-fight-ensnares-ripple-bitstamp-and-jed-mccaleb/) and took the dispute to court. The case was [eventually settled](https://www.coindesk.com/markets/2016/02/12/ripple-settles-1-million-lawsuit-with-former-executive-and-founder/) with both sides declaring they were happy with the outcome. + +Notably, the "freeze" did not happen on the XRP Ledger and did not involve the XRP Ledger's freeze feature. Like any custodial exchange, Bitstamp has the ability to freeze its users' accounts and stop them from trading or withdrawing funds, especially if those funds are involved in a legal dispute. + +In contrast, when trading in the XRP Ledger's [decentralized exchange](decentralized-exchange.html), you custody your own assets so no one can stop you from dealing in XRP. diff --git a/content/concepts/issued-currencies/demurrage.ja.md b/content/concepts/tokens/demurrage.ja.md similarity index 99% rename from content/concepts/issued-currencies/demurrage.ja.md rename to content/concepts/tokens/demurrage.ja.md index 9ba80d4dc5..a688c7e5dc 100644 --- a/content/concepts/issued-currencies/demurrage.ja.md +++ b/content/concepts/tokens/demurrage.ja.md @@ -1,6 +1,6 @@ --- html: demurrage.html -parent: issued-currencies.html +parent: tokens.html blurb: (廃止) 一部の古いXRP Ledgerツールは、組み込み金利やマイナス金利を持つ通貨コードをサポートしていました。. status: removed --- diff --git a/content/concepts/issued-currencies/demurrage.md b/content/concepts/tokens/demurrage.md similarity index 72% rename from content/concepts/issued-currencies/demurrage.md rename to content/concepts/tokens/demurrage.md index b7ac6bfc13..27fba3a48e 100644 --- a/content/concepts/issued-currencies/demurrage.md +++ b/content/concepts/tokens/demurrage.md @@ -1,6 +1,6 @@ --- html: demurrage.html -parent: issued-currencies.html +parent: tokens.html blurb: (Obsolete) Some older XRP Ledger tools used to support currency codes with built-in interest and negative interest rates. status: removed --- @@ -8,11 +8,11 @@ status: removed **Warning:** Demurrage is a deprecated feature with no ongoing support. This page describes historical behavior of older versions of XRP Ledger 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](currency-formats.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)". +[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 a token in the XRP Ledger, you can track it using a custom [currency code](currency-formats.html#currency-codes) that indicates the demurrage rate. This effectively creates separate versions of the token 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 +## Representing Demurraging Token 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. +Rather than continuously update all amounts in the XRP Ledger, this approach divides amounts of interest-bearing or demurraging tokens 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. @@ -23,7 +23,7 @@ Thus, client software must apply two conversions: ### Calculating Demurrage -The full formula for calculating demurrage on a currency is as follows: +The full formula for calculating demurrage is as follows: ``` D = A × ( e ^ (t ÷ τ) ) @@ -41,12 +41,12 @@ To convert between display amounts and ledger amounts, you can use the following 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](currency-formats.html#issued-currency-precision). +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 [token format](currency-formats.html#issued-currency-precision). ## Interest-Bearing Currency Code Format -Rather than using the [standard currency code format](currency-formats.html#currency-codes), currencies that have positive interest or negative interest (demurrage) use a 160-bit currency code in the following format: +Rather than using the [standard currency code format](currency-formats.html#currency-codes), tokens 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) @@ -72,13 +72,13 @@ To calculate an e-folding time for a given rate of annual percent interest: ## Client Support -To support interest-bearing and demurraging currencies, client applications must implement several features: +To support interest-bearing and demurraging tokens, 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 displaying the amount of a demurraging token 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. +- When accepting input for a demurraging token, the client must convert amounts from a display format to the ledger format. (With demurrage, the ledger values 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)". +- Clients must distinguish between tokens that do and do not have interest or demurrage, and among tokens 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/concepts/issued-currencies/freezes.ja.md b/content/concepts/tokens/freezes.ja.md similarity index 99% rename from content/concepts/issued-currencies/freezes.ja.md rename to content/concepts/tokens/freezes.ja.md index 964597d4cd..435dd01ae3 100644 --- a/content/concepts/issued-currencies/freezes.ja.md +++ b/content/concepts/tokens/freezes.ja.md @@ -1,6 +1,6 @@ --- html: freezes.html -parent: issued-currencies.html +parent: tokens.html blurb: 凍結では、コンプライアンス目的で発行済み通貨の取引を停止できます。 labels: - トークン diff --git a/content/concepts/tokens/freezes.md b/content/concepts/tokens/freezes.md new file mode 100644 index 0000000000..514a561f77 --- /dev/null +++ b/content/concepts/tokens/freezes.md @@ -0,0 +1,104 @@ +--- +html: freezes.html +parent: tokens.html +blurb: Issuers can freeze their issued tokens for compliance purposes. +labels: + - Tokens +--- +# Freezing Tokens + +Issuers can freeze the tokens they issue in the XRP Ledger. **This does not apply to XRP,** which is the native asset of the XRP Ledger, not an issued token. + +In certain cases, to meet regulatory requirements, or while investigating suspicious activity, an exchange or gateway may want to freeze token balances. + +**Tip:** No one can freeze XRP in the XRP Ledger. However, custodial exchanges can always freeze the funds they custody at their own discretion. For more details, see [Common Misunderstandings about Freezes](common-misconceptions-about-freezes.html). + +There are three settings related to freezes: + +* [**Individual Freeze**](#individual-freeze) - Freeze one counterparty. +* [**Global Freeze**](#global-freeze) - Freeze all counterparties. +* [**No Freeze**](#no-freeze) - Permanently give up the ability to freeze individual counterparties, as well as the ability to end a global freeze. + +All freeze settings can be enacted regardless of whether the balance(s) to be frozen are positive or negative. Either the token issuer or the currency holder can freeze a trust line; however, the effect is minimal when a currency holder enacts a freeze. + + +## Individual Freeze + +The **Individual Freeze** feature is a setting on a [trust line](trust-lines-and-issuing.html). When an issuer enables the Individual Freeze setting, the following rules apply to the tokens in that trust line: + +* Payments can still occur directly between the two parties of the frozen trust line. +* The counterparty of that trust line can no longer decrease its balance on the frozen trust line, except in direct payments to the issuer. The counterparty can only send the frozen currencies directly to the issuer. +* The counterparty can still receive payments from others on the frozen trust line. +* The counterparty's offers to sell the tokens in the frozen trust line are [considered unfunded](offers.html#lifecycle-of-an-offer). + +Reminder: Trust lines do not hold XRP. XRP cannot be frozen. + +A financial institution can freeze the trust line linking it to a counterparty if that counterparty shows suspicious activity or violates the financial institution's terms of use. The financial institution should also freeze the counterparty in any other systems the financial institution uses that are connected to the XRP Ledger. (Otherwise, an address might still be able to engage in undesired activity by sending payments through the financial institution.) + +An individual address can freeze its trust line to a financial institution. This has no effect on transactions between the institution and other users. It does, however, prevent other addresses, including [operational addresses](issuing-and-operational-addresses.html), from sending that financial institution's issued currencies to the individual address. This type of individual freeze has no effect on offers. + +The Individual Freeze applies to a single trust line. To freeze multiple tokens with a particular counterparty, the address must enable Individual Freeze on the trust lines for each separate currency code. + +An address cannot enable the Individual Freeze setting if it has enabled the [No Freeze](#no-freeze) setting. + + +## Global Freeze + +The **Global Freeze** feature is a setting on an account. An account can enable a global freeze only on itself. When an issuer enables the Global Freeze feature, the following rules apply to all tokens they issue: + +* All counterparties of the frozen issuer can no longer decrease the balances in their trust lines to the frozen account, except in direct payments to the issuer. (This also affects the issuer's own [operational addresses](issuing-and-operational-addresses.html).) +* Counterparties of the frozen issuer can still send and receive payments directly to and from the issuing address. +* All offers to sell tokens issued by the frozen address are [considered unfunded](offers.html#lifecycle-of-an-offer). + +Reminder: addresses cannot issue XRP. Global freezes do not apply to XRP. + +It can be useful to enable Global Freeze on a financial institution's [issuing account](issuing-and-operational-addresses.html) if the issuer's [secret key](cryptographic-keys.html) is compromised, even after regaining control of a such an address. This stops the flow of funds, preventing attackers from getting away with any more money or at least making it easier to track what happened. Besides enacting a Global Freeze in the XRP Ledger, the issuer should also suspend activities in its outside systems. + +It can also be useful to enable Global Freeze if a financial institution intends to migrate to a new [issuing address](issuing-and-operational-addresses.html), or if the financial institution intends to cease doing business. This locks the funds at a specific point in time, so users cannot trade them away for other currencies. + +Global Freeze applies to _all_ tokens issued and held by the address. You cannot enable Global Freeze for only one currency code. If you want to have the ability to freeze some tokens and not others, you should use different addresses for each token. + +An address can always enable the Global Freeze setting. However, if the address has enabled the [No Freeze](#no-freeze) setting, it can never _disable_ Global Freeze. + + +## No Freeze + +The **No Freeze** feature is a setting on an address that permanently gives up the ability to freeze tokens arbitrarily. An issuer can use this feature to make its tokens as "more like physical money" in the sense that the issuer cannot interfere with counterparties trading the tokens among themselves. + +Reminder: XRP already cannot be frozen. The No Freeze feature only applies to other tokens issued in the XRP Ledger. + +The No Freeze setting has two effects: + +* The issuer can no longer enable Individual Freeze on trust lines to any counterparty. +* The issuer can still enact a Global Freeze, but cannot _disable_ the Global Freeze. + +The XRP Ledger cannot force an issuer to honor the obligations that its issued funds represent, so No Freeze does stop a stablecoin issuer from defaulting on its obligations. However, No Freeze ensures that an issuer does not use the Global Freeze feature unfairly against specific users. + +The No Freeze setting applies to all tokens issued to and from an address. If you want to be able to freeze some tokens but not others, you should use different addresses for each. + +You can only enable the No Freeze setting with a transaction signed by your address's master key secret. You cannot use a [Regular Key](setregularkey.html) or a [multi-signed transaction](multi-signing.html) to enable No Freeze. + + + +# See Also + +- [GB-2014-02 New Feature: Balance Freeze](https://ripple.com/files/GB-2014-02.pdf) +- [Freeze Code Samples](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_code-samples/freeze) +- **Concepts:** + - [Trust Lines and Issuing](trust-lines-and-issuing.html) +- **Tutorials:** + - [Enable No Freeze](enable-no-freeze.html) + - [Enact Global Freeze](enact-global-freeze.html) + - [Freeze a Trust Line](freeze-a-trust-line.html) +- **References:** + - [account_lines method][] + - [account_info method][] + - [AccountSet transaction][] + - [TrustSet transaction][] + - [AccountRoot Flags](accountroot.html#accountroot-flags) + - [RippleState (trust line) Flags](ripplestate.html#ripplestate-flags) + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/issued-currencies/issuing-and-operational-addresses.ja.md b/content/concepts/tokens/issuing-and-operational-addresses.ja.md similarity index 99% rename from content/concepts/issued-currencies/issuing-and-operational-addresses.ja.md rename to content/concepts/tokens/issuing-and-operational-addresses.ja.md index 20fad5f1f7..ee04830a37 100644 --- a/content/concepts/issued-currencies/issuing-and-operational-addresses.ja.md +++ b/content/concepts/tokens/issuing-and-operational-addresses.ja.md @@ -1,6 +1,6 @@ --- html: issuing-and-operational-addresses.html -parent: issued-currencies.html +parent: tokens.html blurb: XRP Ledgerで自動的にトランザクションを送信するビジネスは、リスクを最小限に抑えるために目的ごとに別のアドレスを設定することをおすすめします。 labels: - トークン diff --git a/content/concepts/tokens/issuing-and-operational-addresses.md b/content/concepts/tokens/issuing-and-operational-addresses.md new file mode 100644 index 0000000000..ca3afd3d0d --- /dev/null +++ b/content/concepts/tokens/issuing-and-operational-addresses.md @@ -0,0 +1,88 @@ +--- +html: issuing-and-operational-addresses.html +parent: tokens.html +blurb: Businesses sending transactions on the XRP Ledger automatically should set up separate addresses for different purposes to minimize risk. +labels: + - Tokens + - Security +--- +# Issuing and Operational Addresses + +{% include '_snippets/issuing-and-operational-addresses-intro.md' %} + + +## Funds Lifecycle + +When a token issuer follows this separation of roles, funds tend to flow in specific directions, as in the following diagram: + +{{ include_svg("img/issued-currency-funds-flow.svg", "Diagram: Funds flow from the issuing address to standby addresses, to operational addresses, to customer and partner addresses, and finally back to the issuing address.")}} + +The issuing address creates tokens by sending payments to standby addresses. These tokens have negative value from the perspective of the issuing address, since they (often) represent obligations. The same tokens have positive value from other perspectives, including from the perspective of a standby address. + +The standby addresses, which are operated by actual humans, send those tokens to operational addresses. This step allows the issuing address to be used as little as possible after this point, while having at least some tokens available on standby. + +Operational addresses, which are operated by automated systems, send payments to other counterparties, such as liquidity providers, partners, and other customers. Those counterparties may send funds freely among themselves multiple times. + +As always, token payments must "ripple through" the issuer across trust lines with sufficient limits. + +Eventually, someone sends tokens back to the issuer. This destroys those tokens, reducing the issuer's obligations in the XRP Ledger. If the token is a stablecoin, this is the first step of redeeming the tokens for the corresponding off-ledger assets. + + +## Issuing Address + +The issuing address is like a vault. Partners, customers, and operational addresses create trust lines to the issuing address, but this address sends as few transactions as possible. Periodically, a human operator creates and signs a transaction from the issuing address to refill the balances of a standby or operational address. Ideally, the secret key used to sign these transactions should never be accessible from any internet-connected computer. + +Unlike a vault, the issuing address can receive payments directly from customers and partners. Since all transactions in the XRP Ledger are public, automated systems can watch for payments to the issuing address without needing a secret key. + +### Issuing Address Compromise + +If a malicious actor learns the secret key behind a institution's issuing address, that actor can create new tokens and send them to users or trade them in the decentralized exchange. This can make a stablecoin issuer insolvent. It can become difficult for the financial institution to distinguish legitimately-obtained tokens and redeem them fairly. If a financial institution loses control of its issuing address, the institution must create a new issuing address, and all users who have trust lines to the old issuing address must create new trust lines with the new address. + +### Multiple Issuing Addresses + +A financial institution can issue more than one type of token in the XRP Ledger from a single issuing address. However, there are some settings that apply equally to all (fungible) tokens issued from an address, including the percentage for [transfer fees](transfer-fees.html) and the [global freeze](freezes.html) status. If the financial institution wants the flexibility to manage settings differently for each type of token, the institution must multiple issuing addresses. + + +## Operational Addresses + +An operational address is like a cash register. It makes payments on behalf of the institution by transferring tokens to customers and partners. To sign transactions automatically, the secret key for an operational address must be stored on a server that is connected to the internet. (The secret key can be stored encrypted, but the server must decrypt it to sign transactions.) Customers and partners do not, and should not, create trust lines to an operational address. + +Each operational address has a limited balance of tokens and XRP. When the balance of an operational address gets low, the financial institution refills it by sending a payment from the issuing address or a standby address. + +### Operational Address Compromise + +If a malicious actor learns the secret key behind an operational address, the financial institution can only lose as much as that operational address holds. The institution can switch to a new operational address with no action from customers and partners. + + +## Standby Addresses + +Another optional step that an institution can take to balance risk and convenience is to use "standby addresses" as an intermediate step between the issuing address and operational addresses. The institution can fund additional XRP Ledger addresses as standby addresses, whose keys are not available to always-online servers, but are entrusted to different trusted users. + +When an operational address is running low on funds (either tokens or XRP), a trusted user can use a standby address to refill the operational address's balance. When a standby addresses run low on funds, the institution can use the issuing address to send more funds to a standby address in a single transaction, and the standby addresses can distribute those funds among themselves if necessary. This improves security of the issuing address, allowing it to make fewer total transactions, without leaving too much money in the control of a single automated system. + +As with operational addresses, a standby address must have an accounting relationship with the issuing address, and not with customers or partners. All precautions that apply to operational addresses also apply to standby addresses. + +### Standby Address Compromise + +If a standby address is compromised, the consequences are like an operational address being compromised. A malicious actor can steal any balances possessed by the standby address, and the financial institution can change to a new standby address with no action from customers and partners. + + +## See Also + +- **Concepts:** + - [Accounts](accounts.html) + - [Cryptographic Keys](cryptographic-keys.html) +- **Tutorials:** + - [Become an XRP Ledger Gateway](become-an-xrp-ledger-gateway.html) + - [Assign a Regular Key Pair](assign-a-regular-key-pair.html) + - [Change or Remove a Regular Key Pair](change-or-remove-a-regular-key-pair.html) +- **References:** + - [account_info method][] + - [SetRegularKey transaction][] + - [AccountRoot object](accountroot.html) + + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/nft-concepts/nft-conceptual-overview.md b/content/concepts/tokens/non-fungible-tokens.md similarity index 98% rename from content/concepts/nft-concepts/nft-conceptual-overview.md rename to content/concepts/tokens/non-fungible-tokens.md index b74813b36a..3e454b002b 100644 --- a/content/concepts/nft-concepts/nft-conceptual-overview.md +++ b/content/concepts/tokens/non-fungible-tokens.md @@ -1,6 +1,6 @@ --- -html: nft-conceptual-overview.html -parent: nft-concepts.html +html: non-fungible-tokens.html +parent: tokens.html blurb: Introduction to XRPL NFTs. filters: - include_code diff --git a/content/concepts/issued-currencies/paths.ja.md b/content/concepts/tokens/paths.ja.md similarity index 99% rename from content/concepts/issued-currencies/paths.ja.md rename to content/concepts/tokens/paths.ja.md index 9a606eb65d..b87d9dfa21 100644 --- a/content/concepts/issued-currencies/paths.ja.md +++ b/content/concepts/tokens/paths.ja.md @@ -1,6 +1,6 @@ --- html: paths.html -parent: issued-currencies.html +parent: tokens.html blurb: 発行済み通貨の支払いは、接続されているユーザーのパスとオーダーブックを通す必要があります。 labels: - 支払い diff --git a/content/concepts/issued-currencies/paths.md b/content/concepts/tokens/paths.md similarity index 79% rename from content/concepts/issued-currencies/paths.md rename to content/concepts/tokens/paths.md index b6fcd4d623..d680f4e293 100644 --- a/content/concepts/issued-currencies/paths.md +++ b/content/concepts/tokens/paths.md @@ -1,6 +1,6 @@ --- html: paths.html -parent: issued-currencies.html +parent: tokens.html blurb: Payments of issued currencies must traverse paths of connected users and order books. labels: - Payments @@ -8,9 +8,9 @@ labels: --- # Paths -In the XRP Ledger, paths define a way for [issued currency](issued-currencies-overview.html) payments to flow through intermediary steps on their way from sender to receiver. Paths enable [cross-currency payments](cross-currency-payments.html) by connecting sender and receiver through orders in the XRP Ledger's [decentralized exchange](decentralized-exchange.html). Paths also enable complex settlement of offsetting debts. +In the XRP Ledger, paths define a way for [tokens](tokens.html) to flow through intermediary steps as part of a payment. Paths enable [cross-currency payments](cross-currency-payments.html) by connecting sender and receiver through orders in the XRP Ledger's [decentralized exchange](decentralized-exchange.html). Paths also enable complex settlement of offsetting debts. -A single Payment transaction in the XRP Ledger can use multiple paths, combining liquidity from different sources to deliver the desired amount. Thus, a transaction includes a _path set_, which is a collection of possible paths to take. The paths in a path set must start and end with the same currency. +A single Payment transaction in the XRP Ledger can use multiple paths, combining liquidity from different sources to deliver the desired amount. Thus, a transaction includes a _path set_, which is a collection of possible paths to take. All paths in a path set must start with the same currency, and must also end with the same currency as each other. Since XRP can be sent directly to any address, an [XRP-to-XRP transaction](direct-xrp-payments.html) does not use any paths. @@ -19,13 +19,13 @@ Since XRP can be sent directly to any address, an [XRP-to-XRP transaction](direc A path is made of steps that connect the sender to the receiver of the payment. Every step is either: * Rippling through another address with the same currency -* Exchanging currency at an order book +* Trading tokens or XRP using an order book -Rippling through another address is the process of moving debt around. In the typical case, this involves reducing an issuer's obligation to one party and increasing the obligation to another party. Rippling can occur between any addresses that are connected by trust lines. See [Understanding the No Ripple Flag](rippling.html) for more examples of rippling. +[Rippling](rippling.html) is the process of exchanging equivalent tokens using the same currency code. In the typical case, rippling through an issuer involves reducing the tokens issued to one party and increasing the tokens issued to another party by an equal amount. The path step specifies which account to ripple through. -In the case of a currency exchange step, the path step specifies which currency to change to, but does not record the state of the Offers in the order book. The canonical order of transactions is not final until a ledger is validated, so you cannot know for certain which Offers a transaction will take, until after the transaction has been validated. (You can make an educated guess, since each transaction takes the best available Offers at the time it executes in the final ledger.) +[Trading tokens and possibly XRP](decentralized-exchange.html) involves going to an order book and finding the best exchange rate between the assets involved for the amount being sent. The path step specifies which currency to change to, but does not record the state of the Offers in the order book. The canonical order of transactions is not final until a ledger is validated, so you cannot know for certain which Offers a transaction will take, until after the transaction has been validated. (You can make an educated guess, since each transaction takes the best available Offers at the time it executes in the final ledger.) -In both types of steps, each intermediate address gains and loses approximately equal value: either a balance ripples from a trust line to another trust line in the same currency, or they exchange currencies according to a previously-placed order. In some cases, the amounts gained and lost may not be exactly equivalent, due to [transfer fees](transfer-fees.html), trust line quality, or rounding. +In both types of steps, each intermediate address gains and loses approximately equal value: either a balance ripples from a trust line to another trust line in the same currency, or they exchange currencies according to a previously-placed order. In some cases, the amounts gained and lost may not be exactly equivalent, due to [transfer fees](transfer-fees.html), trust line quality settings, or rounding. {{ include_svg("img/paths-examples.svg", "Diagram of three example paths") }} @@ -50,7 +50,7 @@ By convention, several steps of a path are implied by the [fields of the Payment * The first step of a path is always implied to be the sender of the transaction, as defined by the transaction's `Account` field. * If the transaction includes a `SendMax` field with an `issuer` that is not the sender of the transaction, that issuer is implied to be the second step of the path. - * If `issuer` of the `SendMax` _is_ the sending address, then the path starts at the sending address, and may use any of that address's trust lines in the given currency. See [special values for `SendMax` and `Amount`](payment.html#special-issuer-values-for-sendmax-and-amount) for details. + * If `issuer` of the `SendMax` _is_ the sending address, then the path starts at the sending address, and may use any of that address's trust lines for the given currency code. See [special values for `SendMax` and `Amount`](payment.html#special-issuer-values-for-sendmax-and-amount) for details. * If the `Amount` field of the transaction includes an `issuer` that is not the same as the `Destination` of the transaction, that issuer is implied to be the second-to-last step of the path. * Finally, last step of a path is always implied to be the receiver of a transaction, as defined by the transaction's `Destination` field. @@ -61,7 +61,7 @@ In addition to explicitly specified paths, a transaction can execute along the _ The default path could be any of the following: -* If the transaction is uses only one currency (regardless of issuer), then the default path assumes the payment should ripple through the addresses involved. This path only works if those addresses are connected by trust lines. +* If the transaction is uses only one token (regardless of issuer), then the default path assumes the payment should ripple through the addresses involved. This path only works if those addresses are connected by trust lines. * If `SendMax` is omitted, or the `issuer` of the `SendMax` is the sender, the default path needs a trust line from the sending `Account` to the `issuer` of the destination `Amount` to work. * If the `SendMax` and `Amount` have different `issuer` values, and neither are the sender or receiver, the default path is probably not useful because it would need to ripple across a trust line between the two issuers. Ripple (the company) typically discourages issuers from trusting one another directly. * For cross-currency transactions, the default path uses the order book between the source currency (as specified in the `SendMax` field) and the destination currency (as specified in the `Amount` field). diff --git a/content/concepts/issued-currencies/rippling.ja.md b/content/concepts/tokens/rippling.ja.md similarity index 99% rename from content/concepts/issued-currencies/rippling.ja.md rename to content/concepts/tokens/rippling.ja.md index 364fff776e..558a8e6986 100644 --- a/content/concepts/issued-currencies/rippling.ja.md +++ b/content/concepts/tokens/rippling.ja.md @@ -1,6 +1,6 @@ --- html: rippling.html -parent: issued-currencies.html +parent: tokens.html blurb: Ripplingは、複数当事者間での発行済み通貨残高の自動ネット決済です。 labels: - トークン diff --git a/content/concepts/issued-currencies/rippling.md b/content/concepts/tokens/rippling.md similarity index 82% rename from content/concepts/issued-currencies/rippling.md rename to content/concepts/tokens/rippling.md index f46ea3f64b..f31a7f4a2f 100644 --- a/content/concepts/issued-currencies/rippling.md +++ b/content/concepts/tokens/rippling.md @@ -1,20 +1,20 @@ --- html: rippling.html -parent: issued-currencies.html -blurb: Rippling is automatic multi-party net settlement of issued currency balances. +parent: tokens.html +blurb: Rippling is automatic multi-party net settlement of token balances. labels: - Tokens - Cross-Currency --- # 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. +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 token. Rippling is essential, because it allows users who hold tokens to send those to each other with the issuer as a passive intermediary. In a sense, rippling is like a passive, two-way [exchange order](offers.html) with no limit and a 1:1 exchange rate for two tokens with the same currency code but different issuers. Rippling only occurs along the [paths](paths.html) of a payment. [Direct XRP-to-XRP payments](direct-xrp-payments.html) do not involve rippling. -For non-issuing accounts, rippling can be undesirable because it lets other users shift obligations between issuers of the same currency. Thus, the [No Ripple Flag](#the-no-ripple-flag) disables rippling on incoming trust lines by default, unless the account enables rippling by default by enabling the [Default Ripple flag](#the-default-ripple-flag). +For non-issuing accounts, rippling can be undesirable because it lets other users shift obligations between tokens with the same currency code but different issuers. The [No Ripple Flag](#the-no-ripple-flag) disables rippling by default when others open trust lines to your account, unless you enable rippling by default using the [Default Ripple flag](#the-default-ripple-flag). -**Caution:** If you create a trust line to another address, you must explicitly enable the `tfSetNoRipple` flag to block rippling on your side of that trust line. +**Caution:** When you create a trust line, you must explicitly enable the `tfSetNoRipple` flag to block rippling on your side of that trust line. ## Example of Rippling @@ -32,7 +32,7 @@ We call this process, where two addresses pay each other by adjusting the balanc 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 **No Ripple** flag is a setting on a trust line. When two trust lines both have No Ripple 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. +The **No Ripple** flag is a setting on a trust line. When two trust lines both have No Ripple 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 using the same currency code. An account can disable No Ripple on a single trust line, which can allow rippling through any pair that includes that trust line. The account can also enable rippling by default by enabling the [Default Ripple flag](#the-default-ripple-flag). @@ -61,7 +61,7 @@ The No Ripple flag makes certain paths invalid, so that they cannot be used to m ## The Default Ripple Flag -The **Default Ripple** flag is an account setting that enables rippling on all incoming trust lines by default. Gateways and other currency issuers MUST enable this flag for their customers to be able to send those currencies to each other. +The **Default Ripple** flag is an account setting that enables rippling on all _incoming_ trust lines by default. Issuers MUST enable this flag for their customers to be able to send tokens to each other. The Default Ripple setting of your account does not affect trust lines that you create; only trust lines that others open to you. If you change the Default Ripple setting of your account, trust lines that were created before the change keep their existing No Ripple settings. You can use a [TrustSet transaction][] to change the No Ripple setting of a trust line to match your address's new default. diff --git a/content/concepts/issued-currencies/issued-currencies-overview.ja.md b/content/concepts/tokens/tokens.ja.md similarity index 99% rename from content/concepts/issued-currencies/issued-currencies-overview.ja.md rename to content/concepts/tokens/tokens.ja.md index a3841afaeb..437f1616cc 100644 --- a/content/concepts/issued-currencies/issued-currencies-overview.ja.md +++ b/content/concepts/tokens/tokens.ja.md @@ -1,6 +1,5 @@ --- -html: issued-currencies-overview.html -parent: issued-currencies.html +parent: concepts.html blurb: 発行済み通貨の概要と、XRP Ledgerにおけるその特性について説明します。 labels: - トークン diff --git a/content/concepts/tokens/tokens.md b/content/concepts/tokens/tokens.md new file mode 100644 index 0000000000..eb653e0a0c --- /dev/null +++ b/content/concepts/tokens/tokens.md @@ -0,0 +1,82 @@ +--- +parent: concepts.html +blurb: Anyone can make tokens representing digital value on the XRP Ledger. +labels: + - Tokens +--- +# Tokens + +All assets other than XRP can be represented in the XRP Ledger as **tokens**. Standard tokens are tracked in relationships called [trust lines](trust-lines-and-issuing) between accounts. Any account can issue tokens to other recipients who are willing to hold them, but you cannot unilaterally give tokens away to users who don't want them. Tokens can represent any type of value, including "stablecoins" backed by assets that exist outside of the ledger, purely digital tokens created specifically on the XRP Ledger, community credit, and more. + +Standard tokens are fungible: meaning, all units of that token are interchangeable and indistinguishable. Non-fungible tokens are also possible: see [Non-Fungible Tokens](non-fungible-tokens.html) :not_enabled: for details of the XRP Ledger's native support. + +Tokens can used for [cross-currency payments](cross-currency-payments.html) and can be traded in the [decentralized exchange](decentralized-exchange.html). + +The balance on a trust line is negative or positive depending on which side you view it from. The side with the negative balance is called the "issuer" and can control some properties of how those tokens behave. When you send tokens to another account that isn't the issuer, those tokens "ripple" through the issuer and possibly other accounts using the same currency code. This is useful in some cases, but can cause unexpected and undesirable behavior in others. You can use the [No Ripple flag](rippling.html) on trust lines to prevent those trust lines from rippling. + + +## Stablecoins + +A common model for tokens in the XRP Ledger is that an issuer holds assets of equivalent value outside of the XRP Ledger, and issues tokens representing that value on the ledger. This type of issuer is sometimes called a _gateway_ because currency can move into and out of the XRP Ledger through their service. If the assets that back a token use the same amounts and denomination as the tokens in the ledger, that token can be considered a "stablecoin" because—in theory—the exchange rate between that token and its off-ledger representation should be stable at 1:1. + +A stablecoin issuer should offer _deposits_ and _withdrawals_ to exchange the tokens for the actual currency or asset in the world outside the XRP Ledger. + +In practice, the XRP Ledger is a computer system that cannot enforce any rules outside of itself, so stablecoins on the XRP Ledger depend on their issuer's integrity. If you can't count on the stablecoin's issuer to redeem your tokens for the real thing on demand, then you shouldn't expect the stablecoin to retain its value. As a user, you should be mindful of who's issuing the tokens: are they reliable, lawful, and solvent? If not, it's probably best not to hold those tokens. + +For more information on how to run a gateway, see the [Becoming an XRP Ledger Gateway](become-an-xrp-ledger-gateway.html). + + +## Community Credit + +Another way you can use the XRP Ledger is for "community credit", a system where individuals who know each other can use the XRP Ledger to track who owes who else how much money. A powerful feature of the XRP Ledger is that it can automatically and atomically use these debts to settle payments through [rippling](rippling.html). + +For example, if Asheesh owes Marcus $20, and Marcus owes Bharath $50, Bharath can "pay" Asheesh $20 by canceling that much of Marcus's debt to him in exchange for canceling Asheesh's debt to Marcus. The reverse is also possible: Asheesh can pays Bharath through Marcus by increasing their respective debts. The XRP Ledger can settle complex chains of exchanges like this in a single transaction without the accounts in the middle needing to do anything manually. + +For more on this type of usage, see [paths](paths.html). + + +## Other Tokens + +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. + +Be sure to research the relevant regulations before engaging in any financial service business. + + +## Token Properties + +Tokens in the XRP Ledger are [fundamentally different than XRP](currency-formats.html#comparison). Tokens always exist _in trust lines_, and all transfers of tokens move along trust lines. You cannot cause someone else's account to hold more of a token than the _limit_ configured on their trust line. (You _can_ cause your own trust line to go over the limit, for example by buying more of it in the [decentralized exchange](decentralized-exchange.html) or by decreasing the limit after you already have a positive balance.) + +Tokens use decimal (base-10) math with 15 digits of precision and an exponent that allows them to express very large values (up to 9999999999999999 × 1080) and very small values (down to 1.0 × 10-81). + +Anyone can issue tokens by sending a [Payment transaction][] if the necessary trust lines are in place. You can "burn" tokens by sending them back to the issuer. In some cases, [cross-currency payments](cross-currency-payments.html) or trades can also create more tokens according to an issuer's settings. + +Issuers can charge a [transfer fee](transfer-fees.html) that is automatically deducted when users transfer their tokens. Issuers can also define a [tick size](ticksize.html) for exchanges rates involving their tokens. Both issuers and regular accounts can [freeze](freezes.html) trust lines, which limits how the tokens in those trust lines can be used. (None of these things applies to XRP.) + +For a tutorial of the technical steps involved in issuing a token, see [Issue a Fungible Token](issue-a-fungible-token.html). + + +## See Also + +- **Concepts:** + - [XRP](xrp.html) + - [Cross-Currency Payments](cross-currency-payments.html) + - [Decentralized Exchange](decentralized-exchange.html) +- **Tutorials:** + - [Issue a Fungible Token](issue-a-fungible-token.html) + - [Become an XRP Ledger Gateway](become-an-xrp-ledger-gateway.html) + - [Look Up Transaction Results](look-up-transaction-results.html) + - [Use Specialized Payment Types](use-specialized-payment-types.html) +- **References:** + - [Payment transaction][] + - [TrustSet transaction][] + - [RippleState object](ripplestate.html) + - [account_lines method][] + - [account_currencies method][] + - [gateway_balances method][] + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/issued-currencies/transfer-fees.ja.md b/content/concepts/tokens/transfer-fees.ja.md similarity index 99% rename from content/concepts/issued-currencies/transfer-fees.ja.md rename to content/concepts/tokens/transfer-fees.ja.md index 25cab1b6f3..8b7addc6ef 100644 --- a/content/concepts/issued-currencies/transfer-fees.ja.md +++ b/content/concepts/tokens/transfer-fees.ja.md @@ -1,6 +1,6 @@ --- html: transfer-fees.html -parent: issued-currencies.html +parent: tokens.html blurb: 通貨発行者は、自己の発行済み通貨の送金に手数料を課すことができます。 labels: - 手数料 diff --git a/content/concepts/issued-currencies/transfer-fees.md b/content/concepts/tokens/transfer-fees.md similarity index 51% rename from content/concepts/issued-currencies/transfer-fees.md rename to content/concepts/tokens/transfer-fees.md index 6e58fea4d7..39d83f7150 100644 --- a/content/concepts/issued-currencies/transfer-fees.md +++ b/content/concepts/tokens/transfer-fees.md @@ -1,21 +1,29 @@ --- html: transfer-fees.html -parent: issued-currencies.html -blurb: Currency issuers can charge a fee for transferring their issued currencies. +parent: tokens.html +blurb: Token issuers can charge a fee for transferring their tokens. labels: - Fees - Tokens --- # Transfer Fees -The `TransferRate` setting in the XRP Ledger allows [financial institutions that issue currency in the XRP Ledger](become-an-xrp-ledger-gateway.html) to charge users a _transfer fee_ for sending the currencies issued by that financial institution. The sender of the transfer is debited an extra percentage based on the transfer fee, while the recipient of the transfer is credited the intended amount. The difference is the transfer fee, which becomes the property of the issuing address, and is no longer tracked in the XRP Ledger. The transfer fee does not apply when sending or receiving _directly_ to and from the issuing account, but it does apply when transferring from an [operational address][] to another user. +[Token](tokens.html) issuers can charge a _transfer fee_ that applies when users transfer those tokens among themselves. The sender of the transfer is debited an extra percentage based on the transfer fee, while the recipient of the transfer is credited the intended amount. The difference is the transfer fee. + +For standard tokens, the tokens paid in the transfer fee are burned, and no longer tracked in the XRP Ledger. If the token is backed by off-ledger assets, this reduces the amount of those assets the issuer has to hold in reserve to meet its obligations in the XRP Ledger. Transfer fees are usually not appropriate for tokens that aren't backed with outside assets. + +Non-fungible tokens :not_enabled: can also have transfer fees, but they work differently. For details, see [Non-Fungible Tokens](non-fungible-tokens.html). + +The transfer fee does not apply when sending or receiving _directly_ to and from the issuing account, but it does apply when transferring from an [operational address][] to another user. [operational address]: issuing-and-operational-addresses.html [issuing address]: issuing-and-operational-addresses.html XRP never has a transfer fee, because it never has an issuer. -For example, ACME Bank might set the transfer fee to 1%. For the recipient of a payment to get 2 EUR.ACME, the sender must send 2.02 EUR.ACME. After the transaction, ACME's outstanding obligations in the XRP Ledger have decreased by 0.02€, which means that ACME no longer needs to hold that amount in the account backing its issued currencies. +## Example + +In this example, ACME Bank issues a EUR stablecoin on the XRP Ledger. ACME Bank might set the transfer fee to 1%. For the recipient of a payment to get 2 EUR.ACME, the sender must send 2.02 EUR.ACME. After the transaction, ACME's outstanding obligations in the XRP Ledger have decreased by 0.02€, which means that ACME no longer needs to hold that amount in the bank account backing its EUR stablecoin. The following diagram shows an XRP Ledger payment of 2 EUR.ACME from Alice to Charlie with a transfer fee of 1%: @@ -31,11 +39,11 @@ In accounting terms, Alice's, ACME's, and Charlie's balance sheets may have chan -A transfer fee applies whenever an individual transfer would move issued currency from one party to another through the issuing account. In more complex transactions, this can occur multiple times. Transfer fees apply starting from the end and working backwards, so that ultimately the sender of a payment must send enough to account for all fees. For example: +A transfer fee applies whenever an individual transfer would move tokens from one party to another (except when going to/from the issuing account directly). In more complex transactions, this can occur multiple times. Transfer fees apply starting from the end and working backwards, so that ultimately the sender of a payment must send enough to account for all fees. For example: {{ include_svg("img/transfer-fees-in-paths.svg", "Diagram of cross-currency payment with transfer fees") }} -In this scenario, Salazar (the sender) holds EUR issued by ACME, and wants to deliver 100 USD issued by WayGate to Rosa (the recipient). FXMaker is a currency trader with the best offer in the order book, at a rate of 1 USD.WayGate for every 0.9 EUR.ACME. If there were no transfer fees, Salazar could deliver 100 USD to Rosa by sending 90 EUR. However, ACME has a transfer fee of 1% and WayGate has a transfer fee of 0.2%. This means: +In this scenario, Salazar (the sender) holds EUR issued by ACME, and wants to deliver 100 USD issued by WayGate to Rosa (the recipient). FXMaker is a trader with the best offer in the order book, at a rate of 1 USD.WayGate for every 0.9 EUR.ACME. If there were no transfer fees, Salazar could deliver 100 USD to Rosa by sending 90 EUR. However, ACME has a transfer fee of 1% and WayGate has a transfer fee of 0.2%. This means: * FXMaker must send 100.20 USD.WayGate for Rosa to receive 100 USD.WayGate. * FXMaker's current ask is 90.18 EUR.ACME to send 100.20 USD.WayGate. @@ -45,15 +53,15 @@ In this scenario, Salazar (the sender) holds EUR issued by ACME, and wants to de # Technical Details -The transfer fee is represented by a setting on the [issuing address][]. The transfer fee cannot be less than 0% or more than 100% and is rounded down to the nearest 0.0000001%. The transfer fee applies to all currencies issued by the same account. If you want to have different transfer fees for different currencies, use different [issuing addresses][issuing address] for each currency. +The transfer fee is represented by a setting on the [issuing address][]. The transfer fee cannot be less than 0% or more than 100% and is rounded down to the nearest 0.0000001%. The transfer fee applies to all tokens issued by the same account. If you want to have different transfer fees for different tokens, use multiple [issuing addresses][issuing address]. -In the [XRP Ledger protocol](protocol-reference.html), the transfer fee is specified in the `TransferRate` field, as an integer which represents the amount you must send for the recipient to get 1 billion units of the same currency. A `TransferRate` of `1005000000` is equivalent to a transfer fee of 0.5%. By default, the `TransferRate` is set to no fee. The value of `TransferRate` cannot be set to less than `1000000000` ("0%" fee) or more than `2000000000` (a "100%" fee). The value `0` is special case for no fee, equivalent to `1000000000`. +In the [XRP Ledger protocol](protocol-reference.html), the transfer fee is specified in the `TransferRate` field, as an integer which represents the amount you must send for the recipient to get 1 billion units of the same token. A `TransferRate` of `1005000000` is equivalent to a transfer fee of 0.5%. By default, the `TransferRate` is set to no fee. The value of `TransferRate` cannot be set to less than `1000000000` ("0%" fee) or more than `2000000000` (a "100%" fee). The value `0` is special case for no fee, equivalent to `1000000000`. A token issuer can submit an [AccountSet transaction][] from its [issuing address][] to change the `TransferRate` for all its tokens. Anyone can check an account's `TransferRate` with the [account_info method][]. If the `TransferRate` is omitted, then that indicates no fee. -**Note:** The [fix1201 amendment](amendments.html), introduced in `rippled` v0.80.0 and enabled on 2017-11-14, lowered the maximum transfer fee to 100% from an effective limit of approximately 329% (based on the maximum size of a 32-bit integer). The ledger may still contain accounts with a transfer fee setting higher than 100% (a `TransferRate` of `2000000000`). Any transfer fees already set continue to apply at their stated rate. +**Note:** The [fix1201 amendment](amendments.html), introduced in `rippled` v0.80.0 and enabled on 2017-11-14, lowered the maximum transfer fee to 100% (a `TransferRate` of `2000000000`) from an effective limit of approximately 329% (based on the maximum size of a 32-bit integer). The ledger may still contain accounts with a transfer fee setting higher than 100% because transfer fees that were already set continue to apply at their stated rate. ## Client Library Support diff --git a/content/concepts/issued-currencies/trust-lines-and-issuing.ja.md b/content/concepts/tokens/trust-lines-and-issuing.ja.md similarity index 99% rename from content/concepts/issued-currencies/trust-lines-and-issuing.ja.md rename to content/concepts/tokens/trust-lines-and-issuing.ja.md index 574ae6e9ae..6126e05e94 100644 --- a/content/concepts/issued-currencies/trust-lines-and-issuing.ja.md +++ b/content/concepts/tokens/trust-lines-and-issuing.ja.md @@ -1,6 +1,6 @@ --- html: trust-lines-and-issuing.html -parent: issued-currencies.html +parent: tokens.html blurb: トラストラインの特性と根本原理について説明します。 labels: - トークン diff --git a/content/concepts/issued-currencies/trust-lines-and-issuing.md b/content/concepts/tokens/trust-lines-and-issuing.md similarity index 62% rename from content/concepts/issued-currencies/trust-lines-and-issuing.md rename to content/concepts/tokens/trust-lines-and-issuing.md index 75b5820de1..9b2260d9a6 100644 --- a/content/concepts/issued-currencies/trust-lines-and-issuing.md +++ b/content/concepts/tokens/trust-lines-and-issuing.md @@ -1,17 +1,21 @@ --- html: trust-lines-and-issuing.html -parent: issued-currencies.html +parent: tokens.html blurb: Learn about the properties and rationale of trust lines. labels: - Tokens --- # Trust Lines and Issuing -[Issued currencies](issued-currencies.html) in the XRP Ledger often 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. +[Tokens](tokens.html) in the XRP Ledger are often "stablecoins" backed by value held by the issuer in the world outside the XRP Ledger. The is expected to pay the equivalent amount back, outside of the XRP Ledger, when users redeem their stablecoins by returning them to the issuer in the XRP Ledger. In other cases, XRP Ledger tokens represent community credit that can be swapped between people within relatively small limits. -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.) +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 tokens you hold in the XRP Ledger can no longer be exchanged for equivalent balances elsewhere. (You can still keep or trade those tokens within the XRP Ledger, but there is probably no longer any reason to consider that token 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. +There are three cases where you can hold a balance on a trust line that is _greater_ than your limit: + +1. When you acquire more of that token through [trading](decentralized-exchange.html). +2. When you decrease the limit on a trust line that has a positive balance. +3. When you acquire more of that token by [cashing a Check](checks.html). (_Requires the [CheckCashMakesTrustLine amendment][] :not_enabled:_) 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. @@ -19,7 +23,7 @@ Each trust line is specific to a given [currency code][]. Two accounts can have ## 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. +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 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. diff --git a/dactyl-config.yml b/dactyl-config.yml index 9a46743967..acf9f1424f 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -692,91 +692,102 @@ pages: targets: - ja - - name: Issued Currencies - html: issued-currencies.html - parent: concepts.html - template: pagetype-category.html.jinja - blurb: All currencies other than XRP can be represented in the XRP Ledger as issued currencies. Learn more about how issued currencies function in the XRP Ledger. + - md: concepts/tokens/tokens.md targets: - en - - name: 発行済み通貨 + - md: concepts/tokens/tokens.ja.md + targets: + - ja + + # Redirects from old (emptyish) landing pages. + - name: Tokens html: issued-currencies.html - parent: concepts.html - template: pagetype-category.html.jinja + template: pagetype-redirect.html.jinja + redirect_url: tokens.html + blurb: Anyone can make tokens representing digital value on the XRP Ledger. + targets: + - en + + - name: トークン + html: issued-currencies.html + template: pagetype-redirect.html.jinja + redirect_url: tokens.html blurb: XRP Ledgerでは、XRP以外の通貨はすべて発行済み通貨とされます。XRP Ledgerで発行済み通貨がどのように機能するか説明します。 targets: - ja - - md: concepts/issued-currencies/issued-currencies-overview.md + - md: concepts/tokens/trust-lines-and-issuing.md targets: - en - - md: concepts/issued-currencies/issued-currencies-overview.ja.md + - md: concepts/tokens/trust-lines-and-issuing.ja.md targets: - ja - - md: concepts/issued-currencies/trust-lines-and-issuing.md + - md: concepts/tokens/authorized-trust-lines.md targets: - en - - md: concepts/issued-currencies/trust-lines-and-issuing.ja.md + - md: concepts/tokens/authorized-trust-lines.ja.md targets: - ja - - md: concepts/issued-currencies/authorized-trust-lines.md + - md: concepts/tokens/non-fungible-tokens.md + targets: + - en + - ja + + - md: concepts/tokens/freezes.md targets: - en - - md: concepts/issued-currencies/authorized-trust-lines.ja.md + - md: concepts/tokens/freezes.ja.md targets: - ja - - md: concepts/issued-currencies/freezes.md + - md: concepts/tokens/common-misconceptions-about-freezes.md + targets: + - en + - ja + + - md: concepts/tokens/rippling.md targets: - en - - md: concepts/issued-currencies/freezes.ja.md + - md: concepts/tokens/rippling.ja.md targets: - ja - - md: concepts/issued-currencies/rippling.md + - md: concepts/tokens/transfer-fees.md targets: - en - - md: concepts/issued-currencies/rippling.ja.md + - md: concepts/tokens/transfer-fees.ja.md targets: - ja - - md: concepts/issued-currencies/transfer-fees.md + - md: concepts/tokens/issuing-and-operational-addresses.md targets: - en - - md: concepts/issued-currencies/transfer-fees.ja.md + - md: concepts/tokens/issuing-and-operational-addresses.ja.md targets: - ja - - md: concepts/issued-currencies/issuing-and-operational-addresses.md + - md: concepts/tokens/paths.md targets: - en - - md: concepts/issued-currencies/issuing-and-operational-addresses.ja.md + - md: concepts/tokens/paths.ja.md targets: - ja - - md: concepts/issued-currencies/paths.md + - md: concepts/tokens/demurrage.md targets: - en - - md: concepts/issued-currencies/paths.ja.md - targets: - - ja - - - md: concepts/issued-currencies/demurrage.md - targets: - - en - - - md: concepts/issued-currencies/demurrage.ja.md + - md: concepts/tokens/demurrage.ja.md targets: - ja @@ -1019,20 +1030,28 @@ pages: targets: - ja + # Redirect old NFT articles - name: Non-fungible Tokens (NFTs) html: nft-concepts.html - parent: concepts.html - template: pagetype-category.html.jinja + template: pagetype-redirect.html.jinja + redirect_url: non-fungible-tokens.html blurb: Explore XRPL-native support for NFTs. + nav_omit: true targets: - en - ja - - md: concepts/nft-concepts/nft-conceptual-overview.md + - name: NFT Conceptual Overview + html: nft-conceptual-overview.html + template: pagetype-redirect.html.jinja + redirect_url: non-fungible-tokens.html + blurb: Explore XRPL-native support for NFTs. + nav_omit: true targets: - en - ja + # Tutorials -------------------------------------------------------------------- - name: Tutorials From 41e70d3d95622f9d1d3891e19be2f952ce1c8828 Mon Sep 17 00:00:00 2001 From: Elliot Lee Date: Tue, 15 Feb 2022 13:31:26 -0800 Subject: [PATCH 02/50] fix: link to new consensus mechanism explainer (#1317) * fix: link to new consensus mechanism explainer * Update link for consistency Similar update was made in PR#1306 Co-authored-by: Amarantha Kulkarni --- content/concepts/consensus-network/consensus.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/concepts/consensus-network/consensus.md b/content/concepts/consensus-network/consensus.md index 2719835b97..f8578642f9 100644 --- a/content/concepts/consensus-network/consensus.md +++ b/content/concepts/consensus-network/consensus.md @@ -175,7 +175,7 @@ Best practices for applications submitting transactions include: - **Concepts:** - [Introduction to Consensus](intro-to-consensus.html) - [Consensus Research](consensus-research.html) - - [Ripple Consensus Video](https://www.youtube.com/watch?v=pj1QVb1vlC0) + - [The Consensus Mechanism (YouTube)](https://www.youtube.com/watch?v=k6VqEkqRTmk&list=PLJQ55Tj1hIVZtJ_JdTvSum2qMTsedWkNi&index=2) - **Tutorials:** - [Reliable Transaction Submission](reliable-transaction-submission.html) - [Run `rippled` as a Validator](run-rippled-as-a-validator.html) From ca80f66efe1c40cb2cc33f23c7b650e7ec2206d8 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Tue, 15 Feb 2022 18:45:03 -0800 Subject: [PATCH 03/50] Tokens renaming: more find-and-replace --- content/_snippets/checkcash-prereqs.md | 3 +- content/_snippets/data_types/currency_code.md | 4 +- content/_snippets/string-number-formatting.md | 2 +- .../amendments/known-amendments.md | 6 +- .../concepts/consensus-network/consensus.md | 2 +- .../concepts/decentralized-exchange/offers.md | 8 +-- .../decentralized-exchange/ticksize.md | 2 +- .../introduction/xrp-ledger-overview.md | 2 +- content/concepts/introduction/xrp.md | 4 +- .../accounts/depositauth.md | 12 ++-- content/concepts/payment-types/checks.md | 18 +++-- .../payment-types/cross-currency-payments.md | 13 ++-- .../payment-types/direct-xrp-payments.md | 4 +- content/concepts/payment-types/escrow.md | 2 +- .../payment-types/partial-payments.md | 4 +- content/concepts/tokens/freezes.md | 2 +- .../concepts/tokens/non-fungible-tokens.md | 2 +- content/concepts/tokens/paths.md | 2 +- content/concepts/tokens/tokens.md | 2 +- .../tokens/trust-lines-and-issuing.md | 69 +++++++++++++++---- .../data-types/basic-data-types.md | 2 +- .../data-types/currency-formats.md | 50 +++++++------- .../ledger-object-types/accountroot.md | 2 +- .../ledger-object-types/directorynode.md | 2 +- .../ledger-object-types/ripplestate.md | 6 +- .../protocol-reference/serialization.md | 28 ++++---- .../transaction-types/accountset.md | 2 +- .../transaction-types/checkcreate.md | 2 +- .../transactions/transaction-types/payment.md | 14 ++-- content/references/xrp-ledger-toml.md | 6 +- ...onitor-incoming-payments-with-websocket.md | 8 +-- .../offline-account-setup.md | 8 +-- .../look-up-transaction-results.md | 20 +++--- .../cash-a-check-for-a-flexible-amount.md | 10 +-- .../cash-a-check-for-an-exact-amount.md | 4 +- .../use-checks/send-a-check.md | 2 +- .../use-tokens/issue-a-fungible-token.md | 2 +- 37 files changed, 184 insertions(+), 147 deletions(-) diff --git a/content/_snippets/checkcash-prereqs.md b/content/_snippets/checkcash-prereqs.md index 9fb1731c62..e7d9f4e111 100644 --- a/content/_snippets/checkcash-prereqs.md +++ b/content/_snippets/checkcash-prereqs.md @@ -3,7 +3,6 @@ The prerequisites for cashing a check are the same whether you are cashing it fo - You need the ID of a Check object currently in the ledger. - For example, the ID of one Check in these examples is `838766BA2B995C00744175F69A1B11E32C3DBC40E64801A4056FCBD657F57334`, although you must use a different ID to go through these steps yourself. - The **address** and **secret key** of the Check's stated recipient. The address must match the `Destination` address in the Check object. -- If the Check is for an issued currency, you (the recipient) must have a trust line to the issuer. Your limit on that trust line must be high enough to hold your previous balance plus the amount you would receive. - - For more information on trust lines and limits, see [Issued Currencies](issued-currencies.html) and [Trust Lines and Issuing](trust-lines-and-issuing.html). +- If the Check is for a [token](tokens.html), you (the recipient) must have a [trust line](trust-lines-and-issuing.html) to the issuer. Your limit on that trust line must be high enough to hold your previous balance plus the amount you would receive. - A [secure way to sign transactions](set-up-secure-signing.html). - A [client library](client-libraries.html) that can connect to the XRP Ledger, or [any HTTP or WebSocket client](get-started-using-http-websocket-apis.html). diff --git a/content/_snippets/data_types/currency_code.md b/content/_snippets/data_types/currency_code.md index 0d7c38c05a..40e2dab4af 100644 --- a/content/_snippets/data_types/currency_code.md +++ b/content/_snippets/data_types/currency_code.md @@ -1,6 +1,6 @@ -The [`rippled` APIs](rippled-api.html) support two formats of currency code for issued currencies: +The [HTTP / WebSocket APIs](rippled-api.html) support two formats of currency code: - **[Standard Currency Codes](currency-formats.html#standard-currency-codes):** As a 3-character string such as `"EUR"` or `"USD"`. - **[Nonstandard Currency Codes](currency-formats.html#nonstandard-currency-codes):** As a 160-bit hexadecimal string, such as `"0158415500000000C1F76FF6ECB0BAC600000000"`. This is uncommon. -Currencies with the same code can [ripple](rippling.html) across connected trust lines. Currency codes have no other behavior built into the XRP Ledger. +Tokens with the same code can [ripple](rippling.html) across connected trust lines. Currency codes have no other behavior built into the XRP Ledger. diff --git a/content/_snippets/string-number-formatting.md b/content/_snippets/string-number-formatting.md index 66fa1b30ca..07f0fd5c71 100644 --- a/content/_snippets/string-number-formatting.md +++ b/content/_snippets/string-number-formatting.md @@ -1,4 +1,4 @@ -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: +XRP Ledger APIs generally use strings, rather than native JSON numbers, to represent numeric amounts of currency for both [XRP](xrp.html) and [tokens](tokens.html). 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. diff --git a/content/concepts/consensus-network/amendments/known-amendments.md b/content/concepts/consensus-network/amendments/known-amendments.md index 4a6d354819..6269a18757 100644 --- a/content/concepts/consensus-network/amendments/known-amendments.md +++ b/content/concepts/consensus-network/amendments/known-amendments.md @@ -159,7 +159,7 @@ With this amendment, new accounts start with their `Sequence` numbers equal to t Adds a new account flag, `DepositAuth`, which lets an account strictly reject any incoming money from transactions sent by other accounts. Businesses can use this flag to comply with strict regulations that require due diligence before receiving money from any source. -When an account enables this flag, Payment transactions fail if the account is the destination, regardless of whether the Payment would have delivered XRP or an issued currency. EscrowFinish and PaymentChannelClaim transactions fail if the account is the destination unless the destination account itself sends those transactions. If the [Checks][] amendment is enabled, the account can receive XRP or issued currencies by sending CheckCash transactions. +When an account enables this flag, Payment transactions fail if the account is the destination, regardless of whether the Payment would have delivered XRP or a token. EscrowFinish and PaymentChannelClaim transactions fail if the account is the destination unless the destination account itself sends those transactions. If the [Checks][] amendment is enabled, the account can receive XRP or tokens by sending CheckCash transactions. As an exception, accounts with `DepositAuth` enabled can receive Payment transactions for small amounts of XRP (equal or less than the minimum [account reserve](reserves.html)) if their current XRP balance is below the account reserve. @@ -254,7 +254,7 @@ A transaction remains in the queue until one of the following happens: | Default Vote (Latest stable release) | Yes | | Pre-amendment functionality retired? | Yes | -Correctly implements a limit on [transfer fees](transfer-fees.html) to a 100% fee, represented by a maximum `TransferRate` value of `2000000000`. (A 100% fee in this case means you must send 2 units of the issued currency for every 1 unit you want to deliver.) Without the amendment, the effective limit is a `TransferRate` value of 232-1, for approximately a 329% fee. +Correctly implements a limit on [transfer fees](transfer-fees.html) to a 100% fee, represented by a maximum `TransferRate` value of `2000000000`. (A 100% fee in this case means you must send 2 units of the token for every 1 unit you want to deliver.) Without the amendment, the effective limit is a `TransferRate` value of 232-1, for approximately a 329% fee. With this amendment enabled, an [AccountSet][] transaction that attempts to set `TransferRate` higher than `2000000000` fails with the result code `temBAD_TRANSFER_RATE`. Any existing `TransferRate` which was set to a higher value under the previous rules continues to apply at the higher rate. @@ -716,7 +716,7 @@ Implements a "Negative UNL" system, where the network can track which validators | Default Vote (Latest stable release) | N/A | | Pre-amendment functionality retired? | No | -Fixes an inconsistency in the way [transfer fees](transfer-fees.html) are calculated between [OfferCreate](offercreate.html) and [Payment](payment.html) transaction types. Without this amendment, the holder of the issued currency pays the transfer fee if an offer is executed in offer placement, but the initial sender of a transaction pays the transfer fees for offers that are executed as part of payment processing. With this amendment, the holder of the issued currency always pays the transfer fee, regardless of whether the offer is executed as part of a Payment or an OfferCreate transaction. Offer processing outside of payments is unaffected. +Fixes an inconsistency in the way [transfer fees](transfer-fees.html) are calculated between [OfferCreate](offercreate.html) and [Payment](payment.html) transaction types. Without this amendment, the holder of the token pays the transfer fee if an offer is executed in offer placement, but the initial sender of a transaction pays the transfer fees for offers that are executed as part of payment processing. With this amendment, the holder of the token always pays the transfer fee, regardless of whether the offer is executed as part of a Payment or an OfferCreate transaction. Offer processing outside of payments is unaffected. This Amendment requires the [Flow Amendment](#flow) to be enabled. diff --git a/content/concepts/consensus-network/consensus.md b/content/concepts/consensus-network/consensus.md index 2719835b97..9db4110dfb 100644 --- a/content/concepts/consensus-network/consensus.md +++ b/content/concepts/consensus-network/consensus.md @@ -19,7 +19,7 @@ When building applications on the XRP Ledger, it is important to understand this The peer-to-peer XRP Ledger network provides a worldwide, shared ledger, which gives applications authoritative information about the state of its contents. This state information includes: - settings for each [account](accounts.html) -- balances of XRP and [issued currencies](issued-currencies.html) +- balances of XRP and [tokens](tokens.html) - offers in the distributed exchange - network settings, such as [transaction costs](transaction-cost.html) and [reserve](reserves.html) amounts - a timestamp diff --git a/content/concepts/decentralized-exchange/offers.md b/content/concepts/decentralized-exchange/offers.md index 72af06867b..092965dc3d 100644 --- a/content/concepts/decentralized-exchange/offers.md +++ b/content/concepts/decentralized-exchange/offers.md @@ -7,7 +7,7 @@ labels: --- # Offers -In the XRP Ledger's decentralized exchange, orders to trade currency are called "Offers". Offers can trade XRP with issued currencies, or issued currencies with each other, including issued currencies with the same currency code but different issuers. (Currencies with the same code but different issuers can also sometimes be exchanged through [rippling](rippling.html).) +In the XRP Ledger's decentralized exchange, trade orders are called "Offers". Offers can trade XRP with [tokens](tokens.html), or tokens for other tokens, including tokens with the same currency code but different issuers. (Tokens with the same code but different issuers can also sometimes be exchanged through [rippling](rippling.html).) - To create an Offer, send an [OfferCreate transaction][]. - Offers that aren't fully filled immediately become [Offer objects](offer.html) in the ledger data. Later Offers and Payments can consume the Offer object from the ledger. @@ -51,11 +51,11 @@ A client application can locally track the funding status of offers. To do this, ## Offers and Trust -The limit values of trust lines (See [TrustSet](trustset.html)) do not affect offers. In other words, you can use an offer to acquire more than the maximum amount you trust an issuer to redeem. +The limit values of [trust lines](trust-lines-and-issuing.html) do not affect Offers. In other words, you can use an Offer to acquire more than the maximum amount you trust an issuer to redeem. However, holding non-XRP balances still requires a trust line to the address issuing those balances. When an offer is taken, it automatically creates any necessary trust lines, setting their limits to 0. Because [trust lines increase the reserve an account must hold](reserves.html), any offers that would require a new trust line also require the address to have enough XRP to meet the reserve for that trust line. -A trust line indicates an issuer you trust enough to accept their issued currencies as payment, within limits. Offers are explicit instructions to acquire certain issued currencies, so they are allowed to go beyond those limits. +Trust lines limits protect you from receiving more of a token as payment than you want. Offers can go beyond those limits because they are an explicit statement of how much of the token you want. ## Offer Preference @@ -78,7 +78,7 @@ If an OfferCreate transaction has an `Expiration` time that has already passed w ## See Also - **Concepts:** - - [Issued Currencies Overview](issued-currencies-overview.html) + - [Tokens](tokens.html) - [Paths](paths.html) - **Tutorials:** - [List Your Exchange on XRP Charts](list-your-exchange-on-xrp-charts.html) - for off-ledger exchanges diff --git a/content/concepts/decentralized-exchange/ticksize.md b/content/concepts/decentralized-exchange/ticksize.md index b4f6b51e66..37dc4f3a9d 100644 --- a/content/concepts/decentralized-exchange/ticksize.md +++ b/content/concepts/decentralized-exchange/ticksize.md @@ -10,7 +10,7 @@ labels: _(Added by the [TickSize amendment][].)_ -When an Offer is placed into an order book, its exchange rate is truncated based on the `TickSize` values set by the issuers of the currencies involved in the Offer. When a trader offers to exchange XRP and an issued currency, the `TickSize` from the issuer of the currency applies. When a trader offers to exchange two issued currencies, the offer uses the smaller `TickSize` value (that is, the one with fewer significant digits). If neither currency has a `TickSize` set, the default behavior applies. +When an Offer is placed into an order book, its exchange rate is truncated based on the `TickSize` values set by the issuers of the currencies involved in the Offer. When trading XRP and a token, the `TickSize` from the token's issuer applies. When trading two tokens, the Offer uses the smaller `TickSize` value (that is, the one with fewer significant digits). If neither token has a `TickSize` set, the default behavior applies. The `TickSize` value truncates the number of _significant digits_ in the exchange rate of an offer when it gets placed in an order book. Issuers can set `TickSize` to an integer from `3` to `15` using an [AccountSet transaction][]. The exchange rate is represented as significant digits and an exponent; the `TickSize` does not affect the exponent. This allows the XRP Ledger to represent exchange rates between assets that vary greatly in value (for example, a highly inflated currency compared to a rare commodity). The lower the `TickSize` an issuer sets, the larger the increment traders must offer to be considered a higher exchange rate than the existing Offers. diff --git a/content/concepts/introduction/xrp-ledger-overview.md b/content/concepts/introduction/xrp-ledger-overview.md index 77f500c42c..b6a93e53e1 100644 --- a/content/concepts/introduction/xrp-ledger-overview.md +++ b/content/concepts/introduction/xrp-ledger-overview.md @@ -102,6 +102,6 @@ A sample of advanced features in the XRP Ledger: ## On-Ledger Decentralized Exchange [On-Ledger Decentralized Exchange]: #on-ledger-decentralized-exchange -One of the biggest features that sets the XRP Ledger apart from other cryptocurrency networks is that it also contains a full currency exchange that runs on the XRP Ledger. Within this system, businesses (typically called "gateways") can freely issue any currency they want to customers, and those customers can freely trade issued currencies for XRP or other issued currencies issued by any gateway. The XRP Ledger can execute atomic cross-currency transactions this way, using orders in the exchange to provide liquidity. +One of the biggest features that sets the XRP Ledger apart from other cryptocurrency networks is that it also contains a full currency exchange that runs on the XRP Ledger. Within this system, businesses (typically called "gateways") can freely issue any currency they want to customers, and those customers can freely trade tokens for XRP or other tokens. The XRP Ledger can execute atomic cross-currency transactions this way, using orders in the exchange to provide liquidity. For more information on how the decentralized exchange works, see [Decentralized Exchange](decentralized-exchange.html). For more information on the gateway business model, see the [Become an XRP Ledger Gateway](become-an-xrp-ledger-gateway.html). diff --git a/content/concepts/introduction/xrp.md b/content/concepts/introduction/xrp.md index ea71ee3ba1..1f63680469 100644 --- a/content/concepts/introduction/xrp.md +++ b/content/concepts/introduction/xrp.md @@ -7,9 +7,9 @@ labels: --- # XRP -**XRP** is the native cryptocurrency of the XRP Ledger. All [accounts](accounts.html) in the XRP Ledger can send XRP among one another and must hold a minimum amount of XRP as a [reserve](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. +**XRP** is the native cryptocurrency of the XRP Ledger. All [accounts](accounts.html) in the XRP Ledger can send XRP among one another and must hold a minimum amount of XRP as a [reserve](reserves.html). XRP can be sent directly from any XRP Ledger address to any other. This helps make XRP a convenient bridge currency. -Some advanced features of the XRP Ledger, such as [Escrow](escrow.html) and [Payment Channels](use-payment-channels.html), only work with XRP. Order book [auto-bridging](autobridging.html) 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, auto-bridging matches USD:XRP and XRP:EUR orders to augment USD:EUR order books.) +Some advanced features of the XRP Ledger, such as [Escrow](escrow.html) and [Payment Channels](use-payment-channels.html), only work with XRP. Order book [auto-bridging](autobridging.html) uses XRP to deepen liquidity for tokens in the decentralized exchange by using XRP as an intermediary when doing so is cheaper. (For example, auto-bridging 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 offset the costs of maintaining the XRP Ledger. The [transaction cost](transaction-cost.html) and [reserve](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](accountroot.html). diff --git a/content/concepts/payment-system-basics/accounts/depositauth.md b/content/concepts/payment-system-basics/accounts/depositauth.md index d591d10788..a61a3d2303 100644 --- a/content/concepts/payment-system-basics/accounts/depositauth.md +++ b/content/concepts/payment-system-basics/accounts/depositauth.md @@ -10,7 +10,7 @@ labels: _(Added by the [DepositAuth amendment][].)_ -Deposit Authorization is an optional [account](accounts.html) setting in the XRP Ledger. If enabled, Deposit Authorization blocks all transfers from strangers, including transfers of XRP and issued currencies. An account with Deposit Authorization can only receive value in two ways: +Deposit Authorization is an optional [account](accounts.html) setting in the XRP Ledger. If enabled, Deposit Authorization blocks all transfers from strangers, including transfers of XRP and [tokens](tokens.html). An account with Deposit Authorization can only receive value in two ways: - From accounts it has [preauthorized](#preauthorization). - By sending a transaction to receive the funds. For example, an account with Deposit Authorization could finish an [Escrow](escrow.html) that was initiated by a stranger. @@ -48,13 +48,13 @@ An account with Deposit Authorization enabled: - Can receive XRP from [EscrowFinish transactions][] **only in the following cases**: - The sender of the EscrowFinish transaction is the destination of the escrow. - The destination of the EscrowFinish transaction has [preauthorized](#preauthorization) the sender of the EscrowFinish. _(Added by the [DepositPreauth amendment][])_ -- **Can** receive XRP or issued currencies by sending a [CheckCash][] transaction. _(Added by the [Checks amendment][].)_ -- **Can** receive XRP or issued currencies by sending [OfferCreate transactions][]. - - If the account sends an OfferCreate transaction that is not fully executed immediately, it **can** receive the rest of the ordered XRP or issued currency later when the offer is consumed by other accounts' [Payment][] and [OfferCreate][] transactions. -- If the account has created any trust lines without the [No Ripple flag](rippling.html) enabled, or has enabled the Default Ripple flag and issued any currency, the account **can** receive the issued currencies of those trust lines in [Payment transactions][] as a result of rippling. It cannot be the destination of those transactions. +- **Can** receive XRP or tokens by sending a [CheckCash][] transaction. _(Added by the [Checks amendment][].)_ +- **Can** receive XRP or tokens by sending [OfferCreate transactions][]. + - If the account sends an OfferCreate transaction that is not fully executed immediately, it **can** receive the rest of the ordered XRP or token later when the offer is consumed by other accounts' [Payment][] and [OfferCreate][] transactions. +- If the account has created any trust lines without the [No Ripple flag](rippling.html) enabled, or has enabled the Default Ripple flag and issued any currency, the account **can** receive the tokens of those trust lines in [Payment transactions][] as a result of rippling. It cannot be the destination of those transactions. - In general, an account in the XRP Ledger **cannot** receive any non-XRP currencies in the XRP Ledger as long as all of the following are true. (This rule is not specific to the DepositAuth flag.) - The account has not created any trust lines with a nonzero limit. - - The account has not issued currency on trust lines created by others + - The account has not issued tokens on trust lines created by others - The account has not placed any offers. The following table summarizes whether a transaction type can deposit money with DepositAuth enabled or disabled: diff --git a/content/concepts/payment-types/checks.md b/content/concepts/payment-types/checks.md index 8e117d94a4..2e2cb2af06 100644 --- a/content/concepts/payment-types/checks.md +++ b/content/concepts/payment-types/checks.md @@ -11,17 +11,17 @@ labels: _(Added by the [Checks amendment][].)_ -The Checks feature in the XRP Ledger allows users to create deferred payments that can be canceled or cashed by the intended recipients. Like personal paper checks, XRP Ledger Checks start with the sender of the funds creating a Check that specifies an amount and a recipient. The recipient cashes the check to pull the funds from the sender's account into the recipient's account. No money moves until the recipient cashes the Check. Because funds are not put on hold when the Check is created, cashing a Check can fail if the sender doesn't have enough funds when the recipient tries to cash it, like traditional checks. If there's a failure cashing the check, the check's recipient can retry until the Check expires. +The Checks feature in the XRP Ledger allows users to create deferred payments that can be canceled or cashed by the intended recipients. Like personal paper checks, XRP Ledger Checks start with the sender of the funds creating a Check that specifies an amount and a recipient. The recipient cashes the check to pull the funds from the sender's account into the recipient's account. No money moves until the recipient cashes the Check. Because funds are not put on hold when the Check is created, cashing a Check can fail if the sender doesn't have enough funds when the recipient tries to cash it. If there's a failure cashing the check, the check's recipient can retry until the Check expires. -XRP Ledger Checks may have expiration times after which they may no longer be cashed. If the recipient doesn't successfully cash the Check before it expires, the Check object remains in the XRP Ledger until someone cancels it. Anyone may cancel the Check after it expires. Only the sender and recipient can cancel the Check before it expires or is cashed. The Check object is removed from the Ledger when the sender successfully cashes the check or someone cancels it. +XRP Ledger Checks may have expiration times after which they may no longer be cashed. If the recipient doesn't successfully cash the Check before it expires, the Check can no longer be cashed, but the object remains in the XRP Ledger until someone cancels it. Anyone may cancel the Check after it expires. Only the sender and recipient can cancel the Check before it expires. The Check object is removed from the Ledger when the sender successfully cashes the check or someone cancels it. Checks have some similarities to [Escrow](escrow.html) and [Payment Channels](use-payment-channels.html), but there are some important differences between those features and Checks: -* You can send issued currency with Checks. With Payment Channels and Escrow, you can only send XRP. +* You can send [tokens](tokens.html) with Checks. With Payment Channels and Escrow, you can only send XRP. * Checks do not lock up or set aside any funds. The XRP involved in Payment Channels and Escrow cannot be spent until it is redeemed with a claim provided by the sender (Payment Channels), or released by an expiration or crypto-condition (Escrow). -* You can send XRP to yourself through Escrow. You cannot use Checks or Payment Channels to send XRP (or, in the case of Checks, issued currencies) to yourself. +* You can send XRP to yourself through Escrow. You cannot send Checks to yourself. **Note:** The [Checks amendment][] changes the expiration behavior of the [OfferCreate][] transaction. For more information, see [Offer Expiration](offers.html#offer-expiration). @@ -29,16 +29,14 @@ Checks have some similarities to [Escrow](escrow.html) and [Payment Channels](us ## Why Checks? -Traditional paper checks allow people to transfer balances without immediately exchanging physical currency. XRP Ledger Checks allow people to exchange funds asynchronously using a process that is familiar to and accepted by the banking industry. +Traditional paper checks allow people to transfer funds without immediately exchanging physical currency. XRP Ledger Checks allow people to exchange funds asynchronously using a process that is familiar to and accepted by the banking industry. XRP Ledger Checks also solve a problem that is unique to the XRP Ledger: they allow users to reject unwanted payments or accept only part of a payment. This is useful for institutions that need to be careful about accepting payments for compliance reasons. -Checks potentially enable many other use cases. Ripple encourages the community to find new and creative applications for Checks. - ### Use Case: Payment Authorization -**Problem:** To comply with regulations like [BSA, KYC, AML, and CFT](become-an-xrp-ledger-gateway.html#gateway-compliance), financial institutions must provide documentation about the source of funds they receive. Such regulations seek to prevent the illicit transfer of funds by requiring institutions to know the source and destination of all payments processed by the institution. Because of the nature of the XRP Ledger, anyone could potentially send XRP (and, under the right circumstances, issued currencies) to an institution's account on the XRP Ledger. Dealing with such unwanted payments adds significant cost and time delays to these institutions' compliance departments, including potential fines or penalties. +**Problem:** To comply with regulations like [BSA, KYC, AML, and CFT](become-an-xrp-ledger-gateway.html#gateway-compliance), financial institutions must provide documentation about the source of funds they receive. Such regulations seek to prevent the illicit transfer of funds by requiring institutions to know the source and destination of all payments processed by the institution. Because of the nature of the XRP Ledger, anyone could potentially send XRP (and, under the right circumstances, tokens) to an institution's account on the XRP Ledger. Dealing with such unwanted payments adds significant cost and time delays to these institutions' compliance departments, including potential fines or penalties. **Solution:** Institutions can enable [Deposit Authorization](depositauth.html) on their XRP Ledger accounts by [setting the `asfDepositAuth` flag in an `AccountSet` transaction](accountset.html). This makes the account unable to receive Payment transactions. Accounts with Deposit Authorization enabled can only receive funds through Escrow, Payment Channels, or Checks. Checks are the most straightforward, familiar, and flexible way to transfer funds if Deposit Authorization is enabled. @@ -86,9 +84,9 @@ All Checks start the same way, so **Steps 1 and 2** are the same. ## Availability of Checks -Checks require `rippled` v0.90.0 or later. As of 2020-06-08, the Checks amendment is in voting to become enabled on the production XRP Ledger. For the latest status of all known amendments, see [Known Amendments](known-amendments.html). For more information about how amendments are enabled and voted on, see [Amendment Process](amendments.html#amendment-process). +The [Checks amendment][] became enabled on the XRP Ledger Mainnet on 2020-06-18. For more information about how amendments are enabled and voted on, see [Amendment Process](amendments.html#amendment-process). -To check the status of an amendment on a test net or private XRP Ledger network, use the [feature method][]. +To check the status of an amendment on a test network or private network, use the [feature method][]. ## See Also diff --git a/content/concepts/payment-types/cross-currency-payments.md b/content/concepts/payment-types/cross-currency-payments.md index 07b65dbf62..54e9a2971d 100644 --- a/content/concepts/payment-types/cross-currency-payments.md +++ b/content/concepts/payment-types/cross-currency-payments.md @@ -8,29 +8,28 @@ labels: --- # Cross-Currency Payments -In the XRP Ledger, you can send cross-currency payments that exchange one or more issued currencies, XRP, or both. Like [direct XRP payments](use-simple-xrp-payments.html), these payments use the [Payment transaction type][Payment]. Cross-currency payments within the XRP Ledger are fully atomic, meaning that either the payment fully executes or no part of it executes. +In the XRP Ledger, you can send cross-currency payments that exchange tokens, XRP, or both. Like [direct XRP payments](use-simple-xrp-payments.html), these payments use the [Payment transaction type][Payment]. Cross-currency payments within the XRP Ledger are fully atomic, meaning that either the payment fully executes or no part of it executes. By default, cross-currency payments deliver a fixed amount to their destination at a variable cost to their source. Cross-currency payments can also be [partial payments](partial-payments.html), which deliver a variable amount to the destination within a fixed sending limit. ## Prerequisites -- By definition, a cross-currency payment involves at least two currencies, which means that at least one currency involved must be a non-XRP issued currency. - - Typically, this means using one or more currencies issued by an [XRP Ledger Gateway](become-an-xrp-ledger-gateway.html). Such currencies are backed by funds outside the XRP Ledger, and can be withdrawn through the gateway. - - Issued currencies can also be digital tokens that are only issued within the XRP Ledger, with no outside backing. Of course, the parties involved must be willing to send or receive those tokens and treat them as something of value. -- There must be at least one [Path](paths.html) between the sender and receiver, and the total liquidity across all paths must be enough to execute the payment. Cross-currency payments convert from one currency to another by consuming [Offers](offers.html) in the XRP Ledger's decentralized exchange. +- By definition, a cross-currency payment involves at least two currencies, which means that at least one currency involved must be a non-XRP [token](tokens.html). +- There must be at least one [Path](paths.html) between the sender and receiver, and the total liquidity across all paths must be enough to execute the payment. Cross-currency payments convert from one currency to another by consuming [Offers](offers.html) in the XRP Ledger's [decentralized exchange](decentralized-exchange.html). ## Auto-Bridging -Cross-currency payments that exchange two issued currencies automatically use XRP, when it decreases the cost of the payment, by connecting order books to deepen the pool of available liquidity. For example, a payment sending from USD to MXN automatically converts USD to XRP and then XRP to MXN if doing so is cheaper than converting USD to MXN directly. +Cross-currency payments that exchange one token for another token can automatically use XRP, when it decreases the cost of the payment, by connecting order books to deepen the pool of available liquidity. For example, a payment sending from USD to MXN automatically converts USD to XRP and then XRP to MXN if doing so is cheaper than converting USD to MXN directly. For more information, see [Auto-Bridging](autobridging.html). + ## See Also - **Concepts:** - - [Issued Currencies](issued-currencies.html) + - [Tokens](tokens.html) - [Decentralized Exchange](decentralized-exchange.html) - [Paths](paths.html) - **References:** diff --git a/content/concepts/payment-types/direct-xrp-payments.md b/content/concepts/payment-types/direct-xrp-payments.md index 224964d323..711c89e6cc 100644 --- a/content/concepts/payment-types/direct-xrp-payments.md +++ b/content/concepts/payment-types/direct-xrp-payments.md @@ -73,8 +73,8 @@ From a relatively high level, the XRP Ledger's transaction processing engine app ## Comparison to Other Payment Types - **Direct XRP Payments** are the only way to both send and receive XRP in a single transaction. They are a good balance of speed, simplicity, and low cost. -- [Cross-currency payments](cross-currency-payments.html) also use the [Payment][] transaction type, but can send any combination of XRP and non-XRP [issued currencies](issued-currencies.html) except XRP-to-XRP. They can also be [partial payments](partial-payments.html). Cross-currency payments are good for payments not denominated in XRP or for taking arbitrage opportunities in the [decentralized exchange](decentralized-exchange.html). -- [Checks](checks.html) let the sender set up an obligation without transferring any money immediately. The recipient can cash it any time before it expires, but the amount is not guaranteed. Checks can send either XRP or issued currencies. Checks are good for giving the recipient the autonomy to claim the payment. +- [Cross-currency payments](cross-currency-payments.html) also use the [Payment][] transaction type, but can send any combination of XRP and non-XRP [tokens](tokens.html) except XRP-to-XRP. They can also be [partial payments](partial-payments.html). Cross-currency payments are good for payments not denominated in XRP or for taking arbitrage opportunities in the [decentralized exchange](decentralized-exchange.html). +- [Checks](checks.html) let the sender set up an obligation without transferring any money immediately. The recipient can cash it any time before it expires, but the amount is not guaranteed. Checks can send either XRP or [tokens](tokens.html). Checks are good for giving the recipient the autonomy to claim the payment. - [Escrow](escrow.html) sets aside XRP which can be claimed by its intended recipient when certain conditions are met. The XRP amount is fully guaranteed and cannot be otherwise used by the sender unless the Escrow expires. Escrow is good for smart contracts in large amounts. - [Payment Channels](payment-channels.html) set aside XRP. The recipient can claim XRP from the channel in bulk using signed authorizations. Individual authorizations can be verified without sending a full XRP Ledger transaction. Payment channels are good for extremely high-volume micropayments or "streaming" payments. diff --git a/content/concepts/payment-types/escrow.md b/content/concepts/payment-types/escrow.md index 581a9b627b..e4c833f6e2 100644 --- a/content/concepts/payment-types/escrow.md +++ b/content/concepts/payment-types/escrow.md @@ -41,7 +41,7 @@ All escrows start the same way, so **Steps 1 and 2** are the same as in the succ Escrow is designed as a feature to enable the XRP Ledger to be used in the [Interledger Protocol][] and with other smart contracts. The current version has a modest scope to avoid complexity. -- Escrow only works with XRP, not issued currencies. +- Escrow only works with XRP, not tokens. - Escrow requires sending at least two transactions: one to create the escrow, and one to finish or cancel it. Thus, it may not be financially sensible to escrow payments for very small amounts, because the participants must destroy the [transaction cost](transaction-cost.html) of the two transactions. - When using Crypto-Conditions, the [cost of the transaction to finish the escrow](#escrowfinish-transaction-cost) is higher than usual. - All escrows must be created with a "finish-after" time or a [crypto-condition][], or both. If the escrow does not have a finish-after time, it must have an expiration time. diff --git a/content/concepts/payment-types/partial-payments.md b/content/concepts/payment-types/partial-payments.md index 747fb85b3e..e12430edf6 100644 --- a/content/concepts/payment-types/partial-payments.md +++ b/content/concepts/payment-types/partial-payments.md @@ -52,14 +52,14 @@ Partial Payments have the following limitations: To help understand how much a partial payment actually delivered, the metadata of a successful Payment transaction includes a `delivered_amount` field. This field describes the amount actually delivered, in the [same format](basic-data-types.html#specifying-currency-amounts) as the `Amount` field. -For non-partial payments, the `delivered_amount` field of the transaction metadata is equal to the `Amount` field of the transaction. When a payment delivers an issued currency, the `delivered_amount` may be slightly different than the `Amount` field due to rounding. +For non-partial payments, the `delivered_amount` field of the transaction metadata is equal to the `Amount` field of the transaction. When a payment delivers [tokens](tokens.html), the `delivered_amount` may be slightly different than the `Amount` field due to rounding. The delivered amount is **not available** for transactions that meet **both** of the following criteria: - Is a partial payment - Is included in a validated ledger before 2014-01-20 -If both conditions are true, then `delivered_amount` contains the string value `unavailable` instead of an actual amount. If this happens, you can only determine the actual delivered amount by reading the `AffectedNodes` in the transaction's metadata. If the transaction delivered an issued currency and the `issuer` of the `Amount` is the same account as the `Destination` address, the delivered amount may be divided among multiple `AffectedNodes` members representing trust lines to different counterparties. +If both conditions are true, then `delivered_amount` contains the string value `unavailable` instead of an actual amount. If this happens, you can only determine the actual delivered amount by reading the `AffectedNodes` in the transaction's metadata. If the transaction delivered tokens and the `issuer` of the `Amount` is the same account as the `Destination` address, the delivered amount may be divided among multiple `AffectedNodes` members representing trust lines to different counterparties. You can find the `delivered_amount` field in the following places: diff --git a/content/concepts/tokens/freezes.md b/content/concepts/tokens/freezes.md index 514a561f77..11a77aa57f 100644 --- a/content/concepts/tokens/freezes.md +++ b/content/concepts/tokens/freezes.md @@ -35,7 +35,7 @@ Reminder: Trust lines do not hold XRP. XRP cannot be frozen. A financial institution can freeze the trust line linking it to a counterparty if that counterparty shows suspicious activity or violates the financial institution's terms of use. The financial institution should also freeze the counterparty in any other systems the financial institution uses that are connected to the XRP Ledger. (Otherwise, an address might still be able to engage in undesired activity by sending payments through the financial institution.) -An individual address can freeze its trust line to a financial institution. This has no effect on transactions between the institution and other users. It does, however, prevent other addresses, including [operational addresses](issuing-and-operational-addresses.html), from sending that financial institution's issued currencies to the individual address. This type of individual freeze has no effect on offers. +An individual address can freeze its trust line to a financial institution. This has no effect on transactions between the institution and other users. It does, however, prevent other addresses, including [operational addresses](issuing-and-operational-addresses.html), from sending that financial institution's tokens to the individual address. This type of individual freeze has no effect on offers. The Individual Freeze applies to a single trust line. To freeze multiple tokens with a particular counterparty, the address must enable Individual Freeze on the trust lines for each separate currency code. diff --git a/content/concepts/tokens/non-fungible-tokens.md b/content/concepts/tokens/non-fungible-tokens.md index 3e454b002b..13e1180827 100644 --- a/content/concepts/tokens/non-fungible-tokens.md +++ b/content/concepts/tokens/non-fungible-tokens.md @@ -12,7 +12,7 @@ status: not_enabled # NFT Conceptual Overview {% include '_snippets/nfts-disclaimer.md' %} -The XRP Ledger offers support for tokens, also known as _IOUs_ or [_issued currencies_](issued-currencies.html). Such assets are, primarily, fungible. +The XRP Ledger offers support for [tokens](tokens.html), also known as _IOUs_. Such assets are, primarily, fungible. > Fun·gi·ble /ˈfənjəbəl/ (adj) > diff --git a/content/concepts/tokens/paths.md b/content/concepts/tokens/paths.md index d680f4e293..5f7667fcb9 100644 --- a/content/concepts/tokens/paths.md +++ b/content/concepts/tokens/paths.md @@ -1,7 +1,7 @@ --- html: paths.html parent: tokens.html -blurb: Payments of issued currencies must traverse paths of connected users and order books. +blurb: Payments of tokens must traverse paths of connected users and order books. labels: - Payments - Cross-Currency diff --git a/content/concepts/tokens/tokens.md b/content/concepts/tokens/tokens.md index eb653e0a0c..8d40ca0ed2 100644 --- a/content/concepts/tokens/tokens.md +++ b/content/concepts/tokens/tokens.md @@ -37,7 +37,7 @@ For more on this type of usage, see [paths](paths.html). diff --git a/content/concepts/tokens/trust-lines-and-issuing.md b/content/concepts/tokens/trust-lines-and-issuing.md index 9b2260d9a6..0d9a118350 100644 --- a/content/concepts/tokens/trust-lines-and-issuing.md +++ b/content/concepts/tokens/trust-lines-and-issuing.md @@ -7,27 +7,70 @@ labels: --- # Trust Lines and Issuing -[Tokens](tokens.html) in the XRP Ledger are often "stablecoins" backed by value held by the issuer in the world outside the XRP Ledger. The is expected to pay the equivalent amount back, outside of the XRP Ledger, when users redeem their stablecoins by returning them to the issuer in the XRP Ledger. In other cases, XRP Ledger tokens represent community credit that can be swapped between people within relatively small limits. +Trust lines are structures in the XRP Ledger for holding [tokens](tokens.html). Trust lines enforce the XRP Ledger's rule that you cannot cause someone else to hold a token they don't want. This precaution is necessary to enable the XRP Ledger's use case for [community credit](tokens.html#community-credit) among other benefits. -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 tokens you hold in the XRP Ledger can no longer be exchanged for equivalent balances elsewhere. (You can still keep or trade those tokens within the XRP Ledger, but there is probably no longer any reason to consider that token to be worth anything.) +Each "trust line" is a _bidirectional_ relationship consisting of: -There are three cases where you can hold a balance on a trust line that is _greater_ than your limit: +- The identifiers for the **two [accounts](accounts.html)** that the trust line connects. +- A single, shared **balance**, which is positive from the perspective of one account and negative from the other perspective. + - The account with a negative balance is generally considered the "issuer" of the tokens. However, in the [APIs](rippled-apis.html), the name `issuer` can refer to either side. +- Various **settings** and metadata. _Each_ of the two accounts can control its own settings on the trust line. + - Most importantly, each side sets a **limit** on the trust line, which is 0 by default. Each account's balance (from its perspective on the trust line) can't go above that account's limit, except [through that account's own actions](#going-below-the-limit). + +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 shared trust line for any particular currency code. + + +## Creation + +Any account can unilaterally "trust" another account to issue a token by sending a [TrustSet transaction][] with a nonzero limit and their own settings. This creates a line with a zero balance, and sets the other side's settings to the default. + +Trust lines can be implicitly created by some transactions, such as when you buy a token in the [decentralized exchange](decentralized-exchange.html). In this case, the trust line uses entirely default settings. + + +## Going Below the Limit + +There are three cases where you can hold a balance that is _greater_ than your limit on that trust line: 1. When you acquire more of that token through [trading](decentralized-exchange.html). 2. When you decrease the limit on a trust line that has a positive balance. 3. When you acquire more of that token by [cashing a Check](checks.html). (_Requires the [CheckCashMakesTrustLine amendment][] :not_enabled:_) -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 settings for each side, but a single shared net balance between the two sides. +In addition to the shared balance, each account has its own settings on the trust line, which consist of the following: -A trust line with settings in the default state is equivalent to no trust line. +- The **Limit**, a number from 0 to the [maximum token amount](currency-formats.html). Payments and other accounts' actions cannot cause the trust line's balance (from this account's perspective) to go over the limit. The default is `0`. +- **Authorized**: A true/false value used with [Authorized Trust Lines](authorized-trust-lines.html) to allow the other side to hold tokens this account issues. The default is `false`. Once set to `true`, this cannot be changed back. +- **No Ripple**: A true/false value to control whether tokens can [ripple](rippling.html) through this trust line. The default depends on the account's "Default Ripple" setting; for new accounts, "Default Ripple" is off which means that `true` is the default for No Ripple. Usually, issuers should allow rippling and non-issuers should disable rippling unless they are using trust lines for community credit. +- **Freeze**: A true/false value indicating whether an [individual freeze](freezes.html#individual freeze) is in effect on this trust line. The default is `false`. +- **Quality In** and **Quality Out** settings, which allow the account to value tokens issued by the other account on this trust line at less (or more) than face value. For example, if a stablecoin issuer charges a 3% fee for withdrawing tokens for the equivalent off-ledger assets, you could use these settings to value those tokens at 97% of face value. The default, `0`, represents face value. + + +## Reserves and Deletion + +Since a trust line occupies space in the ledger, [a trust line increases the XRP your account must hold in reserve](reserves.html). Either or both accounts in the trust line may be charged the reserve for the trust line, depending on the status of the trust line: if any of your settings are not the default, or if you hold a positive balance, it counts as one item toward your owner reserve. + +Generally, this means that the account that created the trust line is responsible for the reserve and the issuer is not. + +Trust lines are automatically deleted if both sides' settings are in the default state and the balance is 0. This means that, to delete a trust line, you need to: + +1. Send a [TrustSet transaction][] to set your settings to the defaults. +2. Offload any positive balance you have on the trust line. You could do this by sending a [payment](cross-currency-payments.html), or by selling the currency in the [decentralized exchange](decentralized-exchange.html). + +If your balance is negative (you are the issuer) or the other side's settings are not in the default state, you cannot cause the trust line to be totally deleted, but you can make it so that it does not count towards your owner reserve by following the same steps. + +Since the **Authorized** setting cannot be turned off after it has been turned on, it does not count toward the trust line's default state. + +### Free Trust Lines +[[Source]](https://github.com/ripple/rippled/blob/72377e7bf25c4eaee5174186d2db3c6b4210946f/src/ripple/app/tx/impl/SetTrust.cpp#L148-L168) + +Since trust lines are a powerful feature of the XRP Ledger, there is a special feature to make an account's first two trust lines "free". + +When an account creates a new trust line, if the account owns at most 2 items in the ledger including the new line, the account's owner reserve is treated as zero instead of the normal amount. This allows the transaction to succeed even if the account does not hold enough XRP to meet the increased reserve requirement for owning objects in the ledger. + +When an account owns 3 or more objects in the ledger, the full owner reserve applies. -The default state of all trust line flags is off, except for the [No Ripple flag](rippling.html), whose default state depends on the Default Ripple flag. ## See Also @@ -37,10 +80,10 @@ The default state of all trust line flags is off, except for the [No Ripple flag - **Tutorials:** - [Become an XRP Ledger Gateway](become-an-xrp-ledger-gateway.html) - **References:** - - [account_lines method][] - - [gateway_balances method][] - - [RippleState (trust line) object](ripplestate.html) - - [TrustSet transaction][] + - [account_lines method][] - Look up trust lines attached to a given account + - [gateway_balances method][] - Look up an issuer's total balance issued + - [RippleState object](ripplestate.html) - The data format for trust lines in the ledger's state data. + - [TrustSet transaction][] - The transaction to create or modify trust lines. {% include '_snippets/rippled-api-links.md' %} diff --git a/content/references/protocol-reference/data-types/basic-data-types.md b/content/references/protocol-reference/data-types/basic-data-types.md index 25ab8cbea4..bcbe811efa 100644 --- a/content/references/protocol-reference/data-types/basic-data-types.md +++ b/content/references/protocol-reference/data-types/basic-data-types.md @@ -101,7 +101,7 @@ Reporting Mode does not record ledger data until it has been validated. If you m ## Specifying Currency Amounts -There are two kinds of currencies in the XRP Ledger: XRP, and issued currencies. These two types of currencies are specified in different formats, with different precision and rounding behavior. +There are two kinds of currencies in the XRP Ledger: XRP, and tokens. These two types of currencies are specified in different formats, with different precision and rounding behavior. Some fields, such as the destination `Amount` of a [Payment transaction][], can be either type. Some fields only accept XRP specifically, such as the `Fee` field ([transaction cost](transaction-cost.html)). diff --git a/content/references/protocol-reference/data-types/currency-formats.md b/content/references/protocol-reference/data-types/currency-formats.md index 36987375bb..5ae77a188f 100644 --- a/content/references/protocol-reference/data-types/currency-formats.md +++ b/content/references/protocol-reference/data-types/currency-formats.md @@ -8,13 +8,13 @@ label: --- # Currency Formats -The XRP Ledger has two kinds of money: [XRP](xrp.html), and [issued currencies](issued-currencies.html). Both types have high precision, although their formats are different. +The XRP Ledger has two kinds of digital asset: [XRP](xrp.html), and [tokens](tokens.html). Both types have high precision, although their formats are different. ## Comparison -The following table summarizes some of the differences between XRP and [issued currencies](issued-currencies.html) in the XRP Ledger: +The following table summarizes some of the differences between XRP and tokens in the XRP Ledger: -| XRP | Issued Currencies | +| XRP | Tokens | |:---------------------------------------------------------|:------------------| | Has no issuer. | Always issued by an XRP Ledger account. | | Specified as a string. | Specified as an object. | @@ -22,19 +22,19 @@ The following table summarizes some of the differences between XRP and [issued c | Can never be created; can only be destroyed. | Can be issued or redeemed freely. | | Minimum value: `0`. (Cannot be negative.) | Minimum value: `-9999999999999999e80`. Minimum nonzero absolute value: `1000000000000000e-96`. | Maximum value `100000000000` (1011) XRP. That's `100000000000000000` (1017) "drops". | Maximum value `9999999999999999e80`. | -| Precise to the nearest "drop" (0.000001 XRP) | 15 decimal digits of precision. | +| Precise to the nearest "drop" (0.000001 XRP) | 15 decimal digits of precision. | | Can't be [frozen](freezes.html). | The issuer can [freeze](freezes.html) balances. | | No transfer fees; XRP-to-XRP payments are always direct. | Can take indirect [paths](paths.html) with each issuer charging a percentage [transfer fee](transfer-fees.html). | | Can be used in [Payment Channels](payment-channels.html) and [Escrow](escrow.html). | Not compatible with Payment Channels or Escrow. | -For more information, see [XRP](xrp.html) and the [Issued Currencies Overview](issued-currencies-overview.html). +For more information, see [XRP](xrp.html) and [Tokens](tokens.html). ## Specifying Currency Amounts Use the appropriate format for the type of currency you want to specify: - [XRP Amounts](#xrp-amounts) -- [Issued Currency Amounts](#issued-currency-amounts) +- [Token Amounts](#token-amounts) ### XRP Amounts @@ -48,15 +48,15 @@ To specify an amount of XRP, use a [String Number][] indicating _drops_ of XRP, XRP amounts cannot be negative. -### Issued Currency Amounts +### Token Amounts -To specify an amount of any issued currency (including fiat dollars, precious metals, cryptocurrencies, or other custom currency), use a currency specification object. This is a JSON object with three fields: +To specify an amount of a [(fungible) token](tokens.html), use an Amount object. This is a JSON object with three fields: | `Field` | Type | Description | |:-----------|:---------------------------|:-----------------------------------| -| `currency` | String - [Currency Code][] | Arbitrary code for currency to issue. Cannot be `XRP`. | -| `value` | [String Number][] | Quoted decimal representation of the amount of currency. This can include scientific notation, such as `1.23e11` meaning 123,000,000,000. Both `e` and `E` may be used. | -| `issuer` | String | Unique account address of the entity issuing the currency. In other words, the person or business where the currency can be redeemed. | +| `currency` | String - [Currency Code][] | Arbitrary currency code for the token. Cannot be `XRP`. | +| `value` | [String Number][] | Quoted decimal representation of the amount of the token. This can include scientific notation, such as `1.23e11` meaning 123,000,000,000. Both `e` and `E` may be used. This can be negative when displaying balances, but negative values are disallowed in other contexts such as specifying how much to send. | +| `issuer` | String | Generally, the [account](accounts.html) that issues this token. In special cases, this can refer to the account that holds the token instead. | [String Number]: #string-numbers @@ -64,7 +64,7 @@ To specify an amount of any issued currency (including fiat dollars, precious me For example, to represent $153.75 US dollars issued by account `r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59`, you would specify: -``` +```json { "currency": "USD", "value": "153.75", @@ -72,31 +72,29 @@ For example, to represent $153.75 US dollars issued by account `r9cZA1mLK5R5Am25 } ``` -### String Numbers +### Specifying Without Amounts -{% include '_snippets/string-number-formatting.md' %} - - -#### Specifying Currencies Without Amounts - -If you are specifying a non-XRP currency without an amount (typically for defining an order book of currency exchange offers) you should specify it as above, but omit the `value` field. +If you are specifying a token without an amount (typically for defining an order book in the [decentralized exchange](decentralized-exchange.html)) you should specify it a a currency object, but omit the `value` field. If you are specifying XRP without an amount (typically for defining an order book) you should specify it as a JSON object with _only_ a `currency` field. Never include an `issuer` field for XRP. -Finally, if the recipient account of the payment trusts multiple issuers for a currency, you can indicate that the payment should be made in any combination of issuers that the recipient accepts. To do this, specify the recipient account's address as the `issuer` value in the JSON object. +## String Numbers + +{% 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. It uses integer math, so that any amount less than a full drop is rounded down. -## Issued Currency Precision +## Token Precision -The issued currency format can store a wide variety of assets, including those typically measured in very small or very large denominations. This format uses significant digits and a power-of-ten exponent in a similar way to scientific notation. The format supports positive and negative significant digits and exponents within the specified range. 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. Multiplication and division have adjustments to compensate for over-rounding in the least significant digits. +Tokens can represent a wide variety of assets, including those typically measured in very small or very large denominations. This format uses significant digits and a power-of-ten exponent in a similar way to scientific notation. The format supports positive and negative significant digits and exponents within the specified range. 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. Multiplication and division have adjustments to compensate for over-rounding in the least significant digits. -When sending issued currency amounts in the XRP Ledger's peer-to-peer network, servers [serialize](serialization.html) the amount to a 64-bit binary value. +When sending token amounts in the XRP Ledger's peer-to-peer network, servers [serialize](serialization.html) the amount to a 64-bit binary value. -**Note:** The XRP Ledger does not **natively** support issued currencies that are not [fungible](https://en.wikipedia.org/wiki/Fungibility). It also does not support limiting an issued currency to whole number amounts only. All issued currencies in the XRP Ledger are always divisible down to the minimum amount. However non-fungible issued currencies can be implemented in clients following a proposed standard like [XLS-14d](https://github.com/XRPLF/XRPL-Standards/discussions/30). +**Note:** Native support for [Non-Fungible Tokens (NFTs) :not_enabled:](non-fungible-tokens.html) is currently in an experimental state. There are also deprecated, alternative standards for implementing NFTs without changes to the XRP Ledger protocol, including [XLS-14d](https://github.com/XRPLF/XRPL-Standards/discussions/30) and [XLS-19d](https://github.com/XRPLF/XRPL-Standards/discussions/40). ## Currency Codes [Currency Code]: #currency-codes @@ -117,6 +115,6 @@ At the protocol level, this format is [serialized](serialization.html#currency-c ### 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 "standard" currency code, the first 8 bits MUST NOT be `0x00`. +You can also use a 160-bit (40-character) hexadecimal string such as `015841551A748AD2C1F76FF6ECB0CCCD00000000` as the currency code. To prevent this from being treated as a "standard" currency code, the first 8 bits MUST NOT be `0x00`. -**Deprecated:** Some previous versions of [ripple-lib](https://github.com/XRPLF/xrpl.js) 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](demurrage.html). +**Deprecated:** Some previous versions of [ripple-lib](https://github.com/XRPLF/xrpl.js) supported an "interest-bearing" or "demurraging" currency code type. These codes 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](demurrage.html). diff --git a/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md b/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md index ec8adf996a..fbf4f923f5 100644 --- a/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md +++ b/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md @@ -72,7 +72,7 @@ AccountRoot objects can have the following flag values: | `lsfGlobalFreeze` | `0x00400000` | 4194304 | `asfGlobalFreeze` | All assets issued by this address are frozen. | | `lsfNoFreeze` | `0x00200000` | 2097152 | `asfNoFreeze` | This address cannot freeze trust lines connected to it. Once enabled, cannot be disabled. | | `lsfPasswordSpent` | `0x00010000` | 65536 | (None) | The account has used its free SetRegularKey transaction. | -| `lsfRequireAuth` | `0x00040000` | 262144 | `asfRequireAuth` | This account must individually approve other users for those users to hold this account's issued currencies. | +| `lsfRequireAuth` | `0x00040000` | 262144 | `asfRequireAuth` | This account must individually approve other users for those users to hold this account's tokens. | | `lsfRequireDestTag` | `0x00020000` | 131072 | `asfRequireDest` | Requires incoming payments to specify a Destination Tag. | ## AccountRoot ID Format diff --git a/content/references/protocol-reference/ledger-data/ledger-object-types/directorynode.md b/content/references/protocol-reference/ledger-data/ledger-object-types/directorynode.md index 54211fe18b..f1e178cbac 100644 --- a/content/references/protocol-reference/ledger-data/ledger-object-types/directorynode.md +++ b/content/references/protocol-reference/ledger-data/ledger-object-types/directorynode.md @@ -14,7 +14,7 @@ The `DirectoryNode` object type provides a list of links to other objects in the There are two kinds of Directories: * **Owner directories** list other objects owned by an account, such as [`RippleState` (trust line)](ripplestate.html) or [`Offer`](offer.html) objects. -* **Offer directories** list the offers available in the [decentralized exchange](decentralized-exchange.html). A single Offer directory contains all the offers that have the same exchange rate for the same issued currency. +* **Offer directories** list the offers available in the [decentralized exchange](decentralized-exchange.html). A single Offer directory contains all the offers that have the same exchange rate for the same token (currency code and issuer). ## Example {{currentpage.name}} JSON diff --git a/content/references/protocol-reference/ledger-data/ledger-object-types/ripplestate.md b/content/references/protocol-reference/ledger-data/ledger-object-types/ripplestate.md index d0735236b9..9b44aef198 100644 --- a/content/references/protocol-reference/ledger-data/ledger-object-types/ripplestate.md +++ b/content/references/protocol-reference/ledger-data/ledger-object-types/ripplestate.md @@ -54,7 +54,7 @@ A `RippleState` object has the following fields: |-----------------|-----------|---------------|-------------| | `LedgerEntryType` | String | UInt16 | The value `0x0072`, mapped to the string `RippleState`, indicates that this object is a RippleState object. | | `Flags` | Number | UInt32 | A bit-map of boolean options enabled for this object. | -| `Balance` | Object | Amount | The balance of the trust line, from the perspective of the low account. A negative balance indicates that the low account has issued currency to the high account. The issuer in this is always set to the neutral value [ACCOUNT_ONE](accounts.html#special-addresses). | +| `Balance` | Object | Amount | The balance of the trust line, from the perspective of the low account. A negative balance indicates that the low account has tokens to the high account. The issuer in this is always set to the neutral value [ACCOUNT_ONE](accounts.html#special-addresses). | | `LowLimit` | Object | Amount | The limit that the low account has set on the trust line. The `issuer` is the address of the low account that set this limit. | | `HighLimit` | Object | Amount | The limit that the high account has set on the trust line. The `issuer` is the address of the high account that set this limit. | | `PreviousTxnID` | String | Hash256 | The identifying hash of the transaction that most recently modified this object. | @@ -76,8 +76,8 @@ RippleState objects can have the following flag values: |-------------------|--------------|---------------|-----------------|---------| | `lsfLowReserve` | `0x00010000` | 65536 | (None) | This RippleState object [contributes to the low account's owner reserve](#contributing-to-the-owner-reserve). | | `lsfHighReserve` | `0x00020000` | 131072 | (None) | This RippleState object [contributes to the high account's owner reserve](#contributing-to-the-owner-reserve). | -| `lsfLowAuth` | `0x00040000` | 262144 | `tfSetAuth` | The low account has authorized the high account to hold the low account's issued currency. | -| `lsfHighAuth` | `0x00080000` | 524288 | `tfSetAuth` | The high account has authorized the low account to hold the high account's issued currency. | +| `lsfLowAuth` | `0x00040000` | 262144 | `tfSetAuth` | The low account has authorized the high account to hold tokens issued by the low account. | +| `lsfHighAuth` | `0x00080000` | 524288 | `tfSetAuth` | The high account has authorized the low account to hold tokens issued by the high account. | | `lsfLowNoRipple` | `0x00100000` | 1048576 | `tfSetNoRipple` | The low account [has disabled rippling](rippling.html) from this trust line. | | `lsfHighNoRipple` | `0x00200000` | 2097152 | `tfSetNoRipple` | The high account [has disabled rippling](rippling.html) from this trust line. | | `lsfLowFreeze` | `0x00400000` | 4194304 | `tfSetFreeze` | The low account has frozen the trust line, preventing the high account from transferring the asset. | diff --git a/content/references/protocol-reference/serialization.md b/content/references/protocol-reference/serialization.md index ec2fcad625..67e590c5fa 100644 --- a/content/references/protocol-reference/serialization.md +++ b/content/references/protocol-reference/serialization.md @@ -177,7 +177,7 @@ Transaction instructions may contain fields of any of the following types: | Type Name | Type Code | Bit Length | [Length-prefixed]? | Description | |:--------------|:----------|:-----------|:-------------------|----------------| | [AccountID][] | 8 | 160 | Yes | The unique identifier for an [account](accounts.html). | -| [Amount][] | 6 | 64 or 384 | No | An amount of XRP or issued currency. The length of the field is 64 bits for XRP or 384 bits (64+160+160) for issued currencies. | +| [Amount][] | 6 | 64 or 384 | No | An amount of XRP or tokens. The length of the field is 64 bits for XRP or 384 bits (64+160+160) for tokens. | | [Blob][] | 7 | Variable | Yes | Arbitrary binary data. One important such field is `TxnSignature`, the signature that authorizes a transaction. | | [Hash128][] | 4 | 128 | No | A 128-bit arbitrary binary value. The only such field is `EmailHash`, which is intended to store the MD-5 hash of an account owner's email for purposes of fetching a [Gravatar](https://www.gravatar.com/). | | [Hash160][] | 17 | 160 | No | A 160-bit arbitrary binary value. This may define a currency code or issuer. | @@ -214,45 +214,45 @@ AccountIDs that appear as stand-alone fields (such as `Account` and `Destination ### Amount Fields [Amount]: #amount-fields -The "Amount" type is a special field type that represents an amount of currency, either XRP or an issued currency. This type consists of two sub-types: +The "Amount" type is a special field type that represents an amount of currency, either XRP or a token. This type consists of two sub-types: - **XRP** XRP is serialized as a 64-bit unsigned integer (big-endian order), except that the most significant bit is always 0 to indicate that it's XRP, and the second-most-significant bit is `1` to indicate that it is positive. Since the maximum amount of XRP (1017 drops) only requires 57 bits, you can calculate XRP serialized format by taking standard 64-bit unsigned integer and performing a bitwise-OR with `0x4000000000000000`. -- **Issued Currencies** +- **Tokens** - Issued currencies consist of three segments in order: + Tokens consist of three segments in order: 1. 64 bits indicating the amount in the [internal currency amount format](#issued-currency-amount-format). The first bit is `1` to indicate that this is not XRP. 2. 160 bits indicating the [currency code](currency-formats.html#currency-codes). The standard API converts 3-character codes such as "USD" into 160-bit codes using the [standard currency code format](currency-formats.html#standard-currency-codes), but custom 160-bit codes are also possible. 3. 160 bits indicating the issuer's Account ID. (See also: [Account Address Encoding](accounts.html#address-encoding)) -You can tell which of the two sub-types it is based on the first bit: `0` for XRP; `1` for issued currency. +You can tell which of the two sub-types it is based on the first bit: `0` for XRP; `1` for tokens. -The following diagram shows the serialization formats for both XRP amounts and issued currency amounts: +The following diagram shows the serialization formats for both XRP amounts and token amounts: -{{ include_svg("img/serialization-amount.svg", 'XRP amounts have a "not XRP" bit, a sign bit, and 62 bits of precision. Issued currency amounts consist of a "not XRP" bit, a sign bit, an exponent (8 bits), mantissa (54 bits), currency code (160 bits), and issuer (160 bits).') }} +{{ include_svg("img/serialization-amount.svg", 'XRP amounts have a "not XRP" bit, a sign bit, and 62 bits of precision. Token amounts consist of a "not XRP" bit, a sign bit, an exponent (8 bits), mantissa (54 bits), currency code (160 bits), and issuer (160 bits).') }} -#### Issued Currency Amount Format +#### Token Amount Format [[Source]](https://github.com/ripple/rippled/blob/35fa20a110e3d43ffc1e9e664fc9017b6f2747ae/src/ripple/protocol/impl/STAmount.cpp "Source") -{{ include_svg("img/currency-number-format.svg", "Issued Currency Amount Format diagram") }} +{{ include_svg("img/currency-number-format.svg", "Token Amount Format diagram") }} -The XRP Ledger uses 64 bits to serialize the numeric amount of an issued currency. (In JSON format, the numeric amount is the `value` field of a currency amount object.) In binary format, the numeric amount consists of a "not XRP" bit, a sign bit, significant digits, and an exponent, in order: +The XRP Ledger uses 64 bits to serialize the numeric amount of a (fungible) token. (In JSON format, the numeric amount is the `value` field of a currency amount object.) In binary format, the numeric amount consists of a "not XRP" bit, a sign bit, significant digits, and an exponent, in order: -1. The first (most significant) bit for an issued currency amount is `1` to indicate that it is not an XRP amount. (XRP amounts always have the most significant bit set to `0` to distinguish them from this format.) +1. The first (most significant) bit for an token amount is `1` to indicate that it is not an XRP amount. (XRP amounts always have the most significant bit set to `0` to distinguish them from this format.) 2. The sign bit indicates whether the amount is positive or negative. Unlike standard [two's complement](https://en.wikipedia.org/wiki/Two%27s_complement) integers, `1` indicates **positive** in the XRP Ledger format, and `0` indicates negative. 3. The next 8 bits represent the exponent as an unsigned integer. The exponent indicates the scale (what power of 10 the significant digits should be multiplied by) in the range -96 to +80 (inclusive). However, when serializing, we add 97 to the exponent to make it possible to serialize as an unsigned integer. Thus, a serialized value of `1` indicates an exponent of `-96`, a serialized value of `177` indicates an exponent of 80, and so on. 4. The remaining 54 bits represent the significant digits as an unsigned integer. When serializing, this value is normalized to the range 1015 (`1000000000000000`) to 1016-1 (`9999999999999999`) inclusive, except for the special case of the value 0. In the special case for 0, the sign bit, exponent, and mantissa are all zeroes, so the 64-bit value is serialized as `0x8000000000000000000000000000000000000000`. -The numeric amount is serialized alongside the [currency code][] and issuer to form a full [issued currency amount](#amount-fields). +The numeric amount is serialized alongside the [currency code][] and issuer to form a full [token amount](#amount-fields). #### Currency Codes At a protocol level, currency codes in the XRP Ledger are arbitrary 160-bit values, except the following values have special meaning: -- The currency code `0x0000000000000000000000005852500000000000` is **always disallowed**. (This is the "standard format" for an issued currency with code "XRP".) +- The currency code `0x0000000000000000000000005852500000000000` is **always disallowed**. (This is the code "XRP" in the "standard format".) - The currency code `0x0000000000000000000000000000000000000000` (all zeroes) is **generally disallowed**. Usually, XRP amounts are not specified with currency codes. However, this code is used to indicate XRP in rare cases where a field must specify a currency code for XRP. The [`rippled` APIs](rippled-api.html) support a **standard format** for translating three-character ASCII codes to 160-bit hex values as follows: @@ -262,7 +262,7 @@ The [`rippled` APIs](rippled-api.html) support a **standard format** for transla 1. The first 8 bits must be `0x00`. 2. The next 88 bits are reserved, and should be all `0`'s. 3. The next 24 bits represent 3 characters of ASCII. - Ripple recommends using [ISO 4217](https://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. + Ripple recommends using [ISO 4217](https://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 tokens. 4. The next 40 bits are reserved and should be all `0`'s. The **nonstandard format** is any 160 bits of data as long as the first 8 bits are not `0x00`. diff --git a/content/references/protocol-reference/transactions/transaction-types/accountset.md b/content/references/protocol-reference/transactions/transaction-types/accountset.md index 3435ef8b28..6051633859 100644 --- a/content/references/protocol-reference/transactions/transaction-types/accountset.md +++ b/content/references/protocol-reference/transactions/transaction-types/accountset.md @@ -36,7 +36,7 @@ An AccountSet transaction modifies the properties of an [account in the XRP Ledg | `EmailHash` | String | Hash128 | _(Optional)_ Hash of an email address to be used for generating an avatar image. Conventionally, clients use [Gravatar](http://en.gravatar.com/site/implement/hash/) to display this image. | | `MessageKey` | String | Blob | _(Optional)_ Public key for sending encrypted messages to this account. To set the key, it must be exactly 33 bytes, with the first byte indicating the key type: `0x02` or `0x03` for secp256k1 keys, `0xED` for Ed25519 keys. To remove the key, use an empty value. | | [`SetFlag`](#accountset-flags) | Number | UInt32 | _(Optional)_ Integer flag to enable for this account. | -| [`TransferRate`](#transferrate) | Number | UInt32 | _(Optional)_ The fee to charge when users transfer this account's issued currencies, represented as billionths of a unit. Cannot be more than `2000000000` or less than `1000000000`, except for the special case `0` meaning no fee. | +| [`TransferRate`](#transferrate) | Number | UInt32 | _(Optional)_ The fee to charge when users transfer this account's tokens, represented as billionths of a unit. Cannot be more than `2000000000` or less than `1000000000`, except for the special case `0` meaning no fee. | | [`TickSize`](ticksize.html) | Number | UInt8 | _(Optional)_ Tick size to use for offers involving a currency issued by this address. The exchange rates of those offers is rounded to this many significant digits. Valid values are `3` to `15` inclusive, or `0` to disable. _(Added by the [TickSize amendment][].)_ | | `WalletLocator` | String | Hash256 | _(Optional)_ Not used. | | `WalletSize` | Number | UInt32 | _(Optional)_ Not used. | diff --git a/content/references/protocol-reference/transactions/transaction-types/checkcreate.md b/content/references/protocol-reference/transactions/transaction-types/checkcreate.md index 36ec69c9fa..4c40088b57 100644 --- a/content/references/protocol-reference/transactions/transaction-types/checkcreate.md +++ b/content/references/protocol-reference/transactions/transaction-types/checkcreate.md @@ -43,7 +43,7 @@ Create a Check object in the ledger, which is a deferred payment that can be cas - If the `Destination` is the sender of the transaction, the transaction fails with the result code `temREDUNDANT`. - If the `Destination` [account](accounts.html) does not exist in the ledger, the transaction fails with the result code `tecNO_DST`. - If the `Destination` account has the `RequireDest` flag enabled but the transaction does not include a `DestinationTag` field, the transaction fails with the result code `tecDST_TAG_NEEDED`. -- If `SendMax` specifies an issued currency which is [frozen](freezes.html), the transaction fails with the result `tecFROZEN`. +- If `SendMax` specifies a token which is [frozen](freezes.html), the transaction fails with the result `tecFROZEN`. - If the `Expiration` of the transaction is in the past, the transaction fails with the result `tecEXPIRED`. - If the sender does not have enough XRP to meet the [owner reserve](reserves.html#owner-reserves) after adding the Check, the transaction fails with the result `tecINSUFFICIENT_RESERVE`. - If either the sender or the destination of the Check cannot own more objects in the ledger, the transaction fails with the result `tecDIR_FULL`. diff --git a/content/references/protocol-reference/transactions/transaction-types/payment.md b/content/references/protocol-reference/transactions/transaction-types/payment.md index 8dcc9861bf..9f44be70d6 100644 --- a/content/references/protocol-reference/transactions/transaction-types/payment.md +++ b/content/references/protocol-reference/transactions/transaction-types/payment.md @@ -54,13 +54,13 @@ The Payment transaction type is a general-purpose tool that can represent severa | Payment type | `Amount` | `SendMax` | `Paths` | `Address` = `Destination`? | Description | |:-------------|:----------|:-----------|:----------|:---------------------------|:--| | [Direct XRP-to-XRP Payment][] | String (XRP) | Omitted | Omitted | No | Transfers XRP directly from one account to another. Always delivers the exact amount. No fee applies other than the basic [transaction cost](transaction-cost.html). | -| [Creating or redeeming issued currency][] | Object | Object (optional) | Optional | No | Increases or decreases the amount of a non-XRP currency or asset tracked in the XRP Ledger. [Transfer fees](transfer-fees.html) and [freezes](freezes.html) do not apply when sending and redeeming directly. | -| [Cross-currency Payment][] | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Usually required | No | Send issued currency from one holder to another. The `Amount` and `SendMax` cannot _both_ be XRP. These payments [ripple through](rippling.html) the issuer and can take longer [paths](paths.html) through several intermediaries if the transaction specifies a path set. [Transfer fees](transfer-fees.html) set by the issuer(s) apply to this type of transaction. These transactions consume offers in the [decentralized exchange](decentralized-exchange.html) to connect between different currencies, or possibly even between currencies with the same currency code and different issuers. | +| [Creating or redeeming tokens][] | Object | Object (optional) | Optional | No | Increases or decreases the amount of a non-XRP currency or asset tracked in the XRP Ledger. [Transfer fees](transfer-fees.html) and [freezes](freezes.html) do not apply when sending and redeeming directly. | +| [Cross-currency Payment][] | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Usually required | No | Send tokens from one holder to another. The `Amount` or `SendMax` can be XRP or tokens, but they cannot both be XRP. These payments [ripple through](rippling.html) the issuer and can take longer [paths](paths.html) through several intermediaries if the transaction specifies a path set. [Transfer fees](transfer-fees.html) set by the issuer(s) apply to this type of transaction. These transactions consume offers in the [decentralized exchange](decentralized-exchange.html) to connect between different currencies, or possibly even between currencies with the same currency code and different issuers. | | [Partial payment][] | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Usually required | No | Sends _up to_ a specific amount of any currency. Uses the [`tfPartialPayment` flag](#payment-flags). May include a `DeliverMin` amount specifying the minimum that the transaction must deliver to be successful; if the transaction does not specify `DeliverMin`, it can succeed by delivering _any positive amount_. | | Currency conversion | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Required | Yes | Consumes offers in the [decentralized exchange](decentralized-exchange.html) to convert one currency to another, possibly taking [arbitrage](https://en.wikipedia.org/wiki/Arbitrage) opportunities. The `Amount` and `SendMax` cannot both be XRP. Also called a _circular payment_ because it delivers money to the sender. The [Data API](data-api.html) tracks this type of transaction as an "exchange" and not a "payment". | [Direct XRP-to-XRP Payment]: direct-xrp-payments.html -[Creating or redeeming issued currency]: issued-currencies-overview.html +[Creating or redeeming tokens]: tokens.html [Cross-currency Payment]: cross-currency-payments.html [Partial payment]: partial-payments.html @@ -69,11 +69,11 @@ The Payment transaction type is a general-purpose tool that can represent severa -Most of the time, the `issuer` field of a non-XRP [Currency Amount][] indicates a financial institution's [issuing address](issuing-and-operational-addresses.html). However, when describing payments, there are special rules for the `issuer` field in the `Amount` and `SendMax` fields of a payment. +Most of the time, the `issuer` field of a non-XRP [Currency Amount][] indicates the issuer of a token. However, when describing payments, there are special rules for the `issuer` field in the `Amount` and `SendMax` fields of a payment. -* There is only ever one balance for the same currency between two addresses. This means that, sometimes, the `issuer` field of an amount actually refers to a counterparty that is redeeming the issued currency, instead of the address that issued the currency. -* When the `issuer` field of the destination `Amount` field matches the `Destination` address, it is treated as a special case meaning "any issuer that the destination accepts." This includes all addresses to which the destination has extended trust lines, as well as currencies issued by the destination. -* When the `issuer` field of the `SendMax` field matches the source account's address, it is treated as a special case meaning "any issuer that the source can use." This includes creating new issued currencies on trust lines that other accounts have extended to the source account, and sending issued currencies the source account holds from other issuers. +* There is only ever one balance between two addresses for the same currency code. This means that, sometimes, the `issuer` field of an amount actually refers to a counterparty, instead of the address that issued the token. +* When the `issuer` field of the destination `Amount` field matches the `Destination` address, it is treated as a special case meaning "any issuer that the destination accepts." This includes all addresses to which the destination has trust lines with a positive limit, as well as tokens with the same currency code issued by the destination. +* When the `issuer` field of the `SendMax` field matches the source account's address, it is treated as a special case meaning "any issuer that the source can use." This includes creating new tokens on trust lines that other accounts have extended to the source account, and sending tokens the source account holds from other issuers. ## Creating Accounts diff --git a/content/references/xrp-ledger-toml.md b/content/references/xrp-ledger-toml.md index 8d2b834b15..19be5bd7ab 100644 --- a/content/references/xrp-ledger-toml.md +++ b/content/references/xrp-ledger-toml.md @@ -233,14 +233,14 @@ For all URLs in this section, the trailing slash is RECOMMENDED. If omitted, cli ### Currencies -If you issue any assets, tokens, or currencies in the XRP Ledger, you can provide information about them in the `[[CURRENCIES]]` list. If present, the currencies list MUST BE presented as an array of tables, with each entry using the header `[[CURRENCIES]]`, including double square brackets. Each entry describes a separate issued currency or asset. For _each_ `[[CURRENCIES]]` entry, you MAY provide any of the following fields: +If you issue any assets, tokens, or currencies in the XRP Ledger, you can provide information about them in the `[[CURRENCIES]]` list. If present, the currencies list MUST BE presented as an array of tables, with each entry using the header `[[CURRENCIES]]`, including double square brackets. Each entry describes a separate token or asset. For _each_ `[[CURRENCIES]]` entry, you MAY provide any of the following fields: | Field | Type | Description | |:--------|:-------|:------------------------------------------------------| -| `code` | String | The (case-sensitive) ticker symbol of this currency in the XRP Ledger. This can be a three-digit code, a 40-character hex code, or a custom format (for clients that know how to represent the non-standard code in the XRP Ledger). See the [Currency Code reference](currency-formats.html#currency-codes) for information on the XRP Ledger's currency code formats. | +| `code` | String | The (case-sensitive) ticker symbol of this token in the XRP Ledger. This can be a three-digit code, a 40-character hex code, or a custom format (for clients that know how to represent the non-standard code in the XRP Ledger). See the [Currency Code reference](currency-formats.html#currency-codes) for information on the XRP Ledger's currency code formats. | | `display_decimals` | Number | The number of decimals that a client application should use to display amounts of this currency. | | `issuer` | String | The address of the XRP Ledger account where you issue this currency, encoded in the XRP Ledger's base58 format (typically, this starts with an `r`). You SHOULD also list this address in the `[[ACCOUNTS]]` list. (Reminder: the presence of an address here is not authoritative on its own. See [Account Verification](#account-verification) for details.) | -| `network` | String | The network chain where you issue this currency. Use `main` to explicitly specify the production XRP Ledger. If omitted, clients SHOULD assume that the currency is issued on the production XRP Ledger. Use `testnet` for Ripple's XRP Ledger Test Net. You MAY provide other values to describe other test nets or non-standard network chains. | +| `network` | String | The network chain where you issue this token. Use `main` to explicitly specify the production XRP Ledger. If omitted, clients SHOULD assume that the currency is issued on the production XRP Ledger. Use `testnet` for Ripple's XRP Ledger Test Net. You MAY provide other values to describe other test nets or non-standard network chains. | | `symbol` | String | The text symbol, such "$" or "€", that should be used with amounts of this asset or currency, if it has a symbol in the Unicode standard. | diff --git a/content/tutorials/get-started/monitor-incoming-payments-with-websocket.md b/content/tutorials/get-started/monitor-incoming-payments-with-websocket.md index 41e0319e40..dbc7416cd2 100644 --- a/content/tutorials/get-started/monitor-incoming-payments-with-websocket.md +++ b/content/tutorials/get-started/monitor-incoming-payments-with-websocket.md @@ -19,7 +19,7 @@ WebSocket follows a model where the client and server establish one connection, - The examples in this page use JavaScript and the WebSocket protocol, which are available in all major modern browsers. If you have some JavaScript knowledge and expertise in another programming language with a WebSocket client, you can follow along while adapting the instructions to the language of your choice. - You need a stable internet connection and access to a `rippled` server. The embedded examples connect to Ripple's pool of public servers. If you [run your own `rippled` server](install-rippled.html), you can also connect to that server locally. -- To properly handle XRP values without rounding errors, you need access to a number type that can do math on 64-bit unsigned integers. The examples in this tutorial use [big.js](https://github.com/MikeMcl/big.js/). If you are working with [issued currencies](issued-currencies.html), you need even more precision. For more information, see [Currency Precision](currency-formats.html#xrp-precision). +- To properly handle XRP values without rounding errors, you need access to a number type that can do math on 64-bit unsigned integers. The examples in this tutorial use [big.js](https://github.com/MikeMcl/big.js/). If you are working with [tokens](tokens.html), you need even more precision. For more information, see [Currency Precision](currency-formats.html#xrp-precision). @@ -333,13 +333,13 @@ WS_HANDLERS["transaction"] = log_tx ## {{n.next()}}. Read Incoming Payments -When you subscribe to an account, you get messages for _all transactions to or from the account_, as well as _transactions that affect the account indirectly_, such as trading its [issued currencies](issued-currencies.html). If your goal is to recognize when the account has received incoming payments, you must filter the transactions stream and process the payments based on the amount they actually delivered. Look for the following information: +When you subscribe to an account, you get messages for _all transactions to or from the account_, as well as _transactions that affect the account indirectly_, such as trading its [tokens](tokens.html). If your goal is to recognize when the account has received incoming payments, you must filter the transactions stream and process the payments based on the amount they actually delivered. Look for the following information: - The **`validated` field** indicates that the transaction's outcome is [final](finality-of-results.html). This should always be the case when you subscribe to `accounts`, but if you _also_ subscribe to `accounts_proposed` or the `transactions_proposed` stream then the server sends similar messages on the same connection for unconfirmed transactions. As a precaution, it's best to always check the `validated` field. - The **`meta.TransactionResult` field** is the [transaction result](transaction-results.html). If the result is not `tesSUCCESS`, the transaction failed and cannot have delivered any value. - The **`transaction.Account`** field is the sender of the transaction. If you are only looking for transactions sent by others, you can ignore any transactions where this field matches your account's address. (Keep in mind, it _is_ possible to make a cross-currency payment to yourself.) - The **`transaction.TransactionType` field** is the type of transaction. The transaction types that can possibly deliver currency to an account are as follows: - - **[Payment transactions][]** can deliver XRP or [issued currencies](issued-currencies.html). Filter these by the `transaction.Destination` field, which contains the address of the recipient, and always use the `meta.delivered_amount` to see how much the payment actually delivered. XRP amounts are [formatted as strings](basic-data-types.html#specifying-currency-amounts). + - **[Payment transactions][]** can deliver XRP or [tokens](tokens.html). Filter these by the `transaction.Destination` field, which contains the address of the recipient, and always use the `meta.delivered_amount` to see how much the payment actually delivered. XRP amounts are [formatted as strings](basic-data-types.html#specifying-currency-amounts). **Warning:** If you use the `transaction.Amount` field instead, you may be vulnerable to the [partial payments exploit](partial-payments.html#partial-payments-exploit). Malicious users can use this exploit to trick you into allowing the malicious user to trade or withdraw more money than they paid you. @@ -347,7 +347,7 @@ When you subscribe to an account, you get messages for _all transactions to or f - **[EscrowFinish transactions][]** can deliver XRP by finishing an [Escrow](escrow.html) created by a previous [EscrowCreate transaction][]. Look at the metadata of the **EscrowFinish transaction** to see which account received XRP from the escrow and how much. - - **[OfferCreate transactions][]** can deliver XRP or issued currencies by consuming offers your account has previously placed in the XRP Ledger's [decentralized exchange](decentralized-exchange.html). If you never place offers, you cannot receive money this way. Look at the metadata to see what currency the account received, if any, and how much. + - **[OfferCreate transactions][]** can deliver XRP or tokens by consuming offers your account has previously placed in the XRP Ledger's [decentralized exchange](decentralized-exchange.html). If you never place offers, you cannot receive money this way. Look at the metadata to see what currency the account received, if any, and how much. - **[PaymentChannelClaim transactions][]** can deliver XRP from a [payment channel](payment-channels.html). Look at the metadata to see which accounts, if any, received XRP from the transaction. diff --git a/content/tutorials/manage-account-settings/offline-account-setup.md b/content/tutorials/manage-account-settings/offline-account-setup.md index af257ea908..1da67bf8f3 100644 --- a/content/tutorials/manage-account-settings/offline-account-setup.md +++ b/content/tutorials/manage-account-settings/offline-account-setup.md @@ -147,10 +147,10 @@ On the offline machine, prepare and sign transactions for configuring your accou - [Require destination tags](require-destination-tags.html) so that users can't send you payments without tagging the reason they sent it or the customer it's intended for. - [Set Up Multi-Signing](set-up-multi-signing.html) for a higher bar of account security. - [Enable DepositAuth](depositauth.html) so you can only receive payments you've explicitly accepted or from parties you've pre-approved. -- [Require Auth](become-an-xrp-ledger-gateway.html#enabling-require-auth) so that users can't open [trust lines](trust-lines-and-issuing.html) to you without your permission. If you don't plan to use the XRP Ledger's decentralized exchange or issued currency features, you may want to do this as a precaution. -- Issued currency [Gateways](become-an-xrp-ledger-gateway.html) may have additional setup, such as: - - [Set a Transfer Fee](become-an-xrp-ledger-gateway.html#transfer-fees) for users transferring your issued currencies. - - [Disallow XRP payments](become-an-xrp-ledger-gateway.html#disallow-xrp) if you plan to use this address for issued currencies only. +- [Require Auth](become-an-xrp-ledger-gateway.html#enabling-require-auth) so that users can't open [trust lines](trust-lines-and-issuing.html) to you without your permission. If you don't plan to use the XRP Ledger's decentralized exchange or [token](tokens.html) features, you may want to do this as a precaution. +- [Token Issuers](become-an-xrp-ledger-gateway.html) may have additional setup, such as: + - [Set a Transfer Fee](become-an-xrp-ledger-gateway.html#transfer-fees) for users transferring your tokens. + - [Disallow XRP payments](become-an-xrp-ledger-gateway.html#disallow-xrp) if you plan to use this address for tokens only. At this stage, you are only signing the transactions, not submitting them. For each transaction, you must provide all fields, including fields that are normally auto-fillable such as the `Fee` ([transaction cost](transaction-cost.html)) and `Sequence` ([sequence number][]). If you prepare multiple transactions at the same time, you must use sequentially increasing `Sequence` numbers in the order you want the transactions to execute. diff --git a/content/tutorials/production-readiness/look-up-transaction-results.md b/content/tutorials/production-readiness/look-up-transaction-results.md index 5f2891107b..0f7832c709 100644 --- a/content/tutorials/production-readiness/look-up-transaction-results.md +++ b/content/tutorials/production-readiness/look-up-transaction-results.md @@ -193,7 +193,7 @@ Example of increasing an Account's `OwnerCount`: } ``` -Many transaction types create or modify [DirectoryNode objects](directorynode.html). These objects are for bookkeeping: tracking all objects owned by an account, or all Offers to exchange currency at the same exchange rate. If the transaction created new objects in the ledger, it may need to add entries to an existing DirectoryNode object, or add another DirectoryNode object to represent another page of the directory. If the transaction removed objects from the ledger, it may delete one or more DirectoryNode objects that are no longer needed. +Many transaction types create or modify [DirectoryNode objects](directorynode.html). These objects are for bookkeeping: tracking all objects attached to an account, or all exchange Offers at the same exchange rate. If the transaction created new objects in the ledger, it may need to add entries to an existing DirectoryNode object, or add another DirectoryNode object to represent another page of the directory. If the transaction removed objects from the ledger, it may delete one or more DirectoryNode objects that are no longer needed. Example of a `CreatedNode` representing a new Offer Directory: @@ -216,7 +216,7 @@ Other things to look for when processing transaction metadata depend on the tran ### Payments -A [Payment transaction][] can represent a direct XRP-to-XRP transaction, a [cross-currency payment](cross-currency-payments.html), or a direct transaction in an [issued (non-XRP) currency](issued-currencies.html). Anything other than a direct XRP-to-XRP transaction can be a [partial payment](partial-payments.html), including issued currency to XRP or XRP to issued currency transactions. +A [Payment transaction][] can represent a direct XRP-to-XRP transaction, a [cross-currency payment](cross-currency-payments.html), or a direct transaction of a fungible [token](tokens.html). Anything other than a direct XRP-to-XRP transaction can be a [partial payment](partial-payments.html), including token-to-XRP or XRP-to-token transactions. XRP amounts are tracked in the `Balance` field of `AccountRoot` objects. (XRP can also exist in [Escrow objects](escrow-object.html) and [PayChannel objects](paychannel.html), but Payment transactions cannot affect those.) @@ -224,21 +224,21 @@ You should always use [the `delivered_amount` field](partial-payments.html#the-d If the payment contains a `CreatedNode` with `"LedgerEntryType": "AccountRoot"`, that means the payment [funded a new account](accounts.html#creating-accounts) in the ledger. -#### Issued Currency Payments +#### Token Payments -Payments involving issued currencies are a bit more complicated. +Payments involving tokens are a bit more complicated. -All changes in issued currency balances are reflected in [RippleState objects](ripplestate.html), which represent [trust lines](trust-lines-and-issuing.html). An increase to one party's balance on a trust line is considered to decrease the counterparty's balance by equal amount; in the metadata, this is only recorded as a single change to the shared `Balance` for the RippleState object. Whether this change is recorded as an "increase" or "decrease" depends on which account has the numerically higher address. +All changes in token balances are reflected in [RippleState objects](ripplestate.html), which represent [trust lines](trust-lines-and-issuing.html). An increase to one party's balance on a trust line is considered to decrease the counterparty's balance by equal amount; in the metadata, this is only recorded as a single change to the shared `Balance` for the RippleState object. Whether this change is recorded as an "increase" or "decrease" depends on which account has the numerically higher address. A single payment may go across a long [path](paths.html) consisting of several trust lines and order books. The process of changing the balances on several trust lines to connect parties indirectly is called [rippling](rippling.html). Depending on the `issuer` specified in the transaction's `Amount` field, it is also possible that the amount delivered may be split between several trust lines (`RippleState` accounts) connected to the destination account. **Tip:** The order that modified objects are presented in the metadata does not necessarily match the order those objects were visited while processing a payment. To better understand payment execution, it may help to reorder `AffectedNodes` members to reconstruct the paths the funds took through the ledger. -Cross-currency payments consume [Offers](offer.html) in part or entirely to change between currencies with different currency codes and issuers. If a transaction shows `DeletedNode` objects for `Offer` types, that can indicate an Offer that was fully consumed, or an Offer that was found to be [expired or unfunded](offers.html#lifecycle-of-an-offer) at the time of processing. If a transaction shows a `ModifiedNode` of type `Offer`, that indicates an Offer that was partially consumed. +Cross-currency payments consume [Offers](offer.html) in part or entirely to change between different currency codes and issuers. If a transaction shows `DeletedNode` objects for `Offer` types, that can indicate an Offer that was fully consumed, or an Offer that was found to be [expired or unfunded](offers.html#lifecycle-of-an-offer) at the time of processing. If a transaction shows a `ModifiedNode` of type `Offer`, that indicates an Offer that was partially consumed. -The [`QualityIn` and `QualityOut` settings of trust lines](trustset.html) can affect how one side of a trust line values the issued currency, so that the numeric change in balances is different from how the sender values that currency. The `delivered_amount` shows how much was delivered as valued by the recipient. +The [`QualityIn` and `QualityOut` settings of trust lines](trustset.html) can affect how one side of a trust line values the token, so that the numeric change in balances is different from how the sender values that token. The `delivered_amount` shows how much was delivered as valued by the recipient. -If the amount to be sent or received is outside of the [issued currency precision](currency-formats.html#issued-currency-precision), it is possible that one side may be debited for an amount that is rounded to nothing on the other side of the transaction. Therefore, when two parties transact while their balances are different by a factor of 1016, it is possible that rounding may effectively "create" or "destroy" small amounts of the issued currency. (XRP is never rounded, so this is not possible with XRP.) +If the amount to be sent or received is outside of the [token precision](currency-formats.html#token-precision), it is possible that one side may be debited for an amount that is rounded to nothing on the other side of the transaction. Therefore, when two parties transact while their balances are different by a factor of 1016, it is possible that rounding may effectively "create" or "destroy" small amounts of the token. (XRP is never rounded, so this is not possible with XRP.) Depending on the length of the [paths](paths.html), the metadata for cross-currency payments can be _long_. For example, [transaction 8C55AFC2A2AA42B5CE624AEECDB3ACFDD1E5379D4E5BF74A8460C5E97EF8706B](https://xrpcharts.ripple.com/#/transactions/8C55AFC2A2AA42B5CE624AEECDB3ACFDD1E5379D4E5BF74A8460C5E97EF8706B) delivered 2.788 GCB issued by `rHaaans...`, spending XRP but passing through USD from 2 issuers, paying XRP to 2 accounts, removing an unfunded offer from `r9ZoLsJ...` to trade EUR for ETH, plus bookkeeping for a total of 17 different ledger objects modified. @@ -267,7 +267,7 @@ An [OfferCreate transaction][] may or may not create an object in the ledger, de } ``` -A `ModifiedNode` of type `Offer` indicates an Offer that was matched and partially consumed. A single transaction can consume a large number of Offers. An Offer to trade two issued currencies might also consume Offers to trade XRP because of [auto-bridging](autobridging.html). All or part of an exchange can be auto-bridged. +A `ModifiedNode` of type `Offer` indicates an Offer that was matched and partially consumed. A single transaction can consume a large number of Offers. An Offer to trade two tokens might also consume Offers to trade XRP because of [auto-bridging](autobridging.html). All or part of an exchange can be auto-bridged. A `DeletedNode` of type `Offer` can indicate a matching Offer that was fully consumed, an Offer that was found to be [expired or unfunded](offers.html#lifecycle-of-an-offer) at the time of processing, or an Offer that was canceled as part of placing a new Offer. You can recognize a canceled Offer because the `Account` that placed it is the sender of the transaction that deleted it. @@ -303,7 +303,7 @@ Offers can create, delete, and modify both types of [DirectoryNode objects](dire An [OfferCancel transaction][] may have the code `tesSUCCESS` even if there was no Offer to delete. Look for a `DeletedNode` of type `Offer` to confirm that the transaction actually deleted an Offer. If not, the Offer may already have been removed by a previous transaction, or the OfferCancel transaction may have used the wrong sequence number in the `OfferSequence` field. -If an OfferCreate transaction shows a `CreatedNode` of type `RippleState`, that indicates that [the Offer created a trust line](offers.html#offers-and-trust) to hold an issued currency received in the trade. +If an OfferCreate transaction shows a `CreatedNode` of type `RippleState`, that indicates that [the Offer created a trust line](offers.html#offers-and-trust) to hold a token received in the trade. ### Escrows diff --git a/content/tutorials/use-specialized-payment-types/use-checks/cash-a-check-for-a-flexible-amount.md b/content/tutorials/use-specialized-payment-types/use-checks/cash-a-check-for-a-flexible-amount.md index 4e8a4b31ac..ab804baa11 100644 --- a/content/tutorials/use-specialized-payment-types/use-checks/cash-a-check-for-a-flexible-amount.md +++ b/content/tutorials/use-specialized-payment-types/use-checks/cash-a-check-for-a-flexible-amount.md @@ -31,7 +31,7 @@ Figure out the values of the [CheckCash transaction][] fields. To cash a check f | `TransactionType` | String | The value `CheckCash` indicates this is a CheckCash transaction. | | `Account` | String (Address) | The address of the sender who is cashing the Check. (In other words, your address.) | | `CheckID` | String | The ID of the Check object in the ledger to cash. You can get this information by looking up the metadata of the CheckCreate transaction using the [tx method][] or by looking for Checks using the [account_objects method][]. | -| `DeliverMin` | String or Object (Amount) | A minimum amount to receive from the Check. If you cannot receive at least this much, cashing the Check fails, leaving the Check in the ledger so you can try again. For XRP, this must be a string specifying drops of XRP. For issued currencies, this is an object with `currency`, `issuer`, and `value` fields. The `currency` and `issuer` fields must match the corresponding fields in the Check object, and the `value` must be less than or equal to the amount in the Check object. For more information on specifying currency amounts, see [Specifying Currency Amounts][]. | +| `DeliverMin` | String or Object (Amount) | A minimum amount to receive from the Check. If you cannot receive at least this much, cashing the Check fails, leaving the Check in the ledger so you can try again. For XRP, this must be a string specifying drops of XRP. For tokens, this is an object with `currency`, `issuer`, and `value` fields. The `currency` and `issuer` fields must match the corresponding fields in the Check object, and the `value` must be less than or equal to the amount in the Check object. For more information on specifying currency amounts, see [Specifying Currency Amounts][]. | ### Example CheckCash Preparation for a flexible amount @@ -162,7 +162,7 @@ If cashing the Check failed with a `tec`-class code, look up the code in the [Fu | `tecNO_LINE` | The recipient doesn't have a trust line for the Check's currency. | If you want to hold this currency from this issuer, create a trust line for the specified currency and issuer with a reasonable limit using a [TrustSet transaction][], then try to cash the check again. | | `tecNO_PERMISSION` | The sender of the CheckCash transaction isn't the `Destination` of the Check. | Double-check the `Destination` of the Check. | | `tecNO_AUTH` | The issuer of the currency from the check is using [Authorized Trust Lines](authorized-trust-lines.html) but the recipient's trust line to the issuer is not approved. | Ask the issuer to authorize this trust line, then try again to cash the Check after they do. | -| `tecPATH_PARTIAL` | The Check could not deliver enough issued currency, either due to trust line limits or because the sender does not have enough balance of the currency to send (after including the issuer's [transfer fee](transfer-fees.html), if there is one). | If the problem is the trust line limit, send a [TrustSet transaction][] to increase your limit (if desired) or lower your balance by spending some of the currency, then try to cash the Check again. If the problem is the sender's balance, wait for the sender to have more of the Check's currency, or try again to cash the Check for a lesser amount. | +| `tecPATH_PARTIAL` | The Check could not deliver enough tokens, either due to trust line limits or because the sender does not have enough balance of the token to send (including the issuer's [transfer fee](transfer-fees.html), if there is one). | If the problem is the trust line limit, send a [TrustSet transaction][] to increase your limit (if desired) or lower your balance by spending some of the currency, then try to cash the Check again. If the problem is the sender's balance, wait for the sender to have more of the Check's currency, or try again to cash the Check for a lesser amount. | | `tecUNFUNDED_PAYMENT` | The Check could not deliver enough XRP. | Wait for the sender to have more XRP, or try again to cash the Check for a lesser amount. | ## {{cash_flex_n.next()}}. Confirm delivered amount @@ -200,15 +200,15 @@ If the Check was cashed for a flexible `DeliverMin` amount and succeeded, you ca "DeliverMin" : "95000000", "Fee" : "10", -- For issued currencies where the sender or recipient of the check is the issuer, the `RippleState` object representing the trust line between those accounts has its `Balance` adjusted in the favor of the Check's recipient. +- For tokens where the sender or recipient of the check is the issuer, the `RippleState` object representing the trust line between those accounts has its `Balance` adjusted in the favor of the Check's recipient. -- For issued currencies with a third-party issuer, there are changes to two `RippleState` objects, representing the trust lines connecting the sender to the issuer, and the issuer to the recipient. The `RippleState` object representing the relationship between the Check's sender and the issuer has its `Balance` changed in favor of the issuer, and the `RippleState` object representing the relationship between the issuer and the recipient has its `Balance` changed in favor of the recipient. +- For tokens with a third-party issuer, there are changes to two `RippleState` objects, representing the trust lines connecting the sender to the issuer, and the issuer to the recipient. The `RippleState` object representing the relationship between the Check's sender and the issuer has its `Balance` changed in favor of the issuer, and the `RippleState` object representing the relationship between the issuer and the recipient has its `Balance` changed in favor of the recipient. - - If the issued currency has a [transfer fee](transfer-fees.html), the Check's sender may be debited more than the recipient is credited. (The difference is the transfer fee, which is returned to the issuer as a decreased net obligation.) + - If the token has a [transfer fee](transfer-fees.html), the Check's sender may be debited more than the recipient is credited. (The difference is the transfer fee, which is returned to the issuer as a decreased net obligation.) {% include '_snippets/tx-type-links.md' %} diff --git a/content/tutorials/use-specialized-payment-types/use-checks/cash-a-check-for-an-exact-amount.md b/content/tutorials/use-specialized-payment-types/use-checks/cash-a-check-for-an-exact-amount.md index 46351186a6..5b8e95446b 100644 --- a/content/tutorials/use-specialized-payment-types/use-checks/cash-a-check-for-an-exact-amount.md +++ b/content/tutorials/use-specialized-payment-types/use-checks/cash-a-check-for-an-exact-amount.md @@ -28,7 +28,7 @@ Figure out the values of the [CheckCash transaction][] fields. To cash a check f | `TransactionType` | String | The value `CheckCash` indicates this is a CheckCash transaction. | | `Account` | String (Address) | The address of the sender who is cashing the Check. (In other words, your address.) | | `CheckID` | String | The ID of the Check object in the ledger to cash. You can get this information by looking up the metadata of the CheckCreate transaction using the [tx method][] or by looking for Checks using the [account_objects method][]. | -| `Amount` | String or Object (Amount) | The amount to redeem from the Check. For XRP, this must be a string specifying drops of XRP. For issued currencies, this is an object with `currency`, `issuer`, and `value` fields. The `currency` and `issuer` fields must match the corresponding fields in the Check object, and the `value` must be less than or equal to the amount in the Check object. (For currencies with transfer fees, you must cash the Check for less than its `SendMax` so the transfer fee can be paid by the `SendMax`.) If you cannot receive this much, cashing the Check fails, leaving the Check in the ledger so you can try again. For more information on specifying currency amounts, see [Specifying Currency Amounts][]. | +| `Amount` | String or Object (Amount) | The amount to redeem from the Check. For XRP, this must be a string specifying drops of XRP. For tokens, this is an object with `currency`, `issuer`, and `value` fields. The `currency` and `issuer` fields must match the corresponding fields in the Check object, and the `value` must be less than or equal to the amount in the Check object. (For currencies with transfer fees, you must cash the Check for less than its `SendMax` so the transfer fee can be paid by the `SendMax`.) If you cannot receive this much, cashing the Check fails, leaving the Check in the ledger so you can try again. For more information on specifying currency amounts, see [Specifying Currency Amounts][]. | ### Example CheckCash Preparation for an exact amount @@ -125,7 +125,7 @@ The following examples show how to prepare a transaction to cash a Check for a f Use the [tx method][] with the CheckCash transaction's identifying hash to check its status. Look for a `"TransactionResult": "tesSUCCESS"` field in the transaction's metadata, indicating that the transaction succeeded, and the field `"validated": true` in the result, indicating that this result is final. -If the check was cashed for an exact `Amount` and succeeded, you can assume that the recipient was credited for exactly that amount (with possible rounding for very large or very small amounts of issued currencies). +If the check was cashed for an exact `Amount` and succeeded, you can assume that the recipient was credited for exactly that amount (with possible rounding for very large or very small amounts of tokens). If cashing the Check failed, the Check remains in the ledger so you can try cashing again later. You may want to [cash the Check for a flexible amount](cash-a-check-for-a-flexible-amount.html) instead. diff --git a/content/tutorials/use-specialized-payment-types/use-checks/send-a-check.md b/content/tutorials/use-specialized-payment-types/use-checks/send-a-check.md index bff9ed8d46..867d5f84dc 100644 --- a/content/tutorials/use-specialized-payment-types/use-checks/send-a-check.md +++ b/content/tutorials/use-specialized-payment-types/use-checks/send-a-check.md @@ -38,7 +38,7 @@ Decide how much money the Check is for and who can cash it. Figure out the value | `TransactionType` | String | Use the string `CheckCreate` here. | | `Account` | String (Address) | The address of the sender who is creating the Check. (In other words, your address.) | | `Destination` | String (Address) | The address of the intended recipient who can cash the Check. | -| `SendMax` | String or Object (Amount) | The maximum amount the sender can be debited when this Check gets cashed. For XRP, use a string representing drops of XRP. For issued currencies, use an object with `currency`, `issuer`, and `value` fields. See [Specifying Currency Amounts][] for details. If you want the recipient to be able to cash the Check for an exact amount of a non-XRP currency with a [transfer fee](transfer-fees.html), remember to include an extra percentage to pay for the transfer fee. (For example, for the recipient to cash a Check for 100 CAD from an issuer with a 2% transfer fee, you must set the `SendMax` to 102 CAD from that issuer.) | +| `SendMax` | String or Object (Amount) | The maximum amount the sender can be debited when this Check gets cashed. For XRP, use a string representing drops of XRP. For tokens, use an object with `currency`, `issuer`, and `value` fields. See [Specifying Currency Amounts][] for details. If you want the recipient to be able to cash the Check for an exact amount of a non-XRP currency with a [transfer fee](transfer-fees.html), remember to include an extra percentage to pay for the transfer fee. (For example, for the recipient to cash a Check for 100 CAD from an issuer with a 2% transfer fee, you must set the `SendMax` to 102 CAD from that issuer.) | ### Example CheckCreate Preparation diff --git a/content/tutorials/use-tokens/issue-a-fungible-token.md b/content/tutorials/use-tokens/issue-a-fungible-token.md index 7c95a76fc3..5b5ce32355 100644 --- a/content/tutorials/use-tokens/issue-a-fungible-token.md +++ b/content/tutorials/use-tokens/issue-a-fungible-token.md @@ -391,7 +391,7 @@ Now you can create tokens by sending a [Payment transaction][] from the cold add |---|---| | `TransactionType` | `"Payment"` | | `Account` | The cold address issuing the token. | -| `Amount` | An [issued currency amount](basic-data-types.html#specifying-currency-amounts) specifying how much of which token to create. | +| `Amount` | An [token amount](basic-data-types.html#specifying-currency-amounts) specifying how much of which token to create. | | `Amount.currency` | The currency code of the token. | | `Amount.value` | Decimal amount of the token to issue, as a string. | | `Amount.issuer` | The cold address issuing the token. | From ce4b5abe7b8608193254513e4b421a09b5d734c5 Mon Sep 17 00:00:00 2001 From: Bharath Chari Date: Wed, 16 Feb 2022 16:31:16 +0200 Subject: [PATCH 04/50] Remove contact information Contact information for Ripple should not be in this document. --- .../xrp-ledger-businesses/become-an-xrp-ledger-gateway.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/content/tutorials/xrp-ledger-businesses/become-an-xrp-ledger-gateway.md b/content/tutorials/xrp-ledger-businesses/become-an-xrp-ledger-gateway.md index d321ee2610..717246287d 100644 --- a/content/tutorials/xrp-ledger-businesses/become-an-xrp-ledger-gateway.md +++ b/content/tutorials/xrp-ledger-businesses/become-an-xrp-ledger-gateway.md @@ -17,14 +17,6 @@ labels: This document explains the concepts and steps necessary to become an XRP Ledger gateway. In this document, we use a fictional online currency exchange named "ACME" and its customers as examples, to show how ACME can expand its business to include being an XRP Ledger gateway. -## Contact Information - -You are not on your own. Ripple wants gateways to succeed, so we are here to help. Please contact us if you need help building and growing your gateway. - -* Contact [partners@ripple.com](mailto:partners@ripple.com) for enterprise-class integrations, infrastructure advice, and other business development needs. -* Contact [support@ripple.com](mailto:support@ripple.com) for technical questions, clarifications, bug reports, and feature requests. - - ## Gateways Explained {% include '_snippets/gateways-intro.md' %} From a1021441c7745311db967ff54b068539376c052f Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Wed, 16 Feb 2022 10:46:28 -0800 Subject: [PATCH 05/50] Support pages in subfolder Pages that exist in subfolders such as /tutorials/ are now OK, as long as the add this line to the frontmatter: prefix: "/" This ensures that nav elements including top nav, sidebar, breadcrumbs, all work, and that the appropriate JavaScript loads as intended. --- template/base.html.jinja | 10 +++---- template/component-top-nav.html.jinja | 12 ++++----- template/page-calculator.html.jinja | 30 ++++++++++----------- template/page-impact.html.jinja | 4 +-- template/page-toml-checker.html.jinja | 4 +-- template/page-tx-sender.html.jinja | 18 ++++++------- template/page-websocket-api-tool.html.jinja | 12 ++++----- template/page-xrp-faucets.html.jinja | 6 ++--- template/page-xrp-overview.html.jinja | 4 +-- template/page-xrpl-overview.html.jinja | 2 +- template/pagetype-doc.html.jinja | 4 +-- template/pdf-doc.html.jinja | 2 +- 12 files changed, 54 insertions(+), 54 deletions(-) diff --git a/template/base.html.jinja b/template/base.html.jinja index 33f2d6c486..e761a1bfe3 100644 --- a/template/base.html.jinja +++ b/template/base.html.jinja @@ -58,15 +58,15 @@ {% if "js_editor" in currentpage.filters %} - - - - + + + + {% endif %} {% if target.light_theme_enabled %} - + {% endif %} {% block head %} diff --git a/template/component-top-nav.html.jinja b/template/component-top-nav.html.jinja index d5ab663766..23b7155cc9 100644 --- a/template/component-top-nav.html.jinja +++ b/template/component-top-nav.html.jinja @@ -1,6 +1,6 @@