RCL Accounts
-An "Account" in the Ripple Consensus Ledger represents a holder of XRP and a sender of transactions. The core elements of an account are:
+XRP Ledger Accounts
+An "Account" in the XRP Ledger represents a holder of XRP and a sender of transactions. The core elements of an account are:
- An identifying address, such as
rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn - An XRP balance. Some of this XRP is set aside for the Reserve. @@ -173,9 +173,9 @@
In the ledger's data tree, an account's core data is stored in the AccountRoot ledger node type. An account can also be the owner (or partial owner) of several other types of data.
-Tip: An "Account" in the Ripple Consensus Ledger is somewhere between the financial usage (like "bank account") and the computing usage (like "UNIX account"). Non-XRP currencies and assets aren't stored in an RCL Account itself; each such asset is stored in an accounting relationship called a "Trust Line" that connects two parties.
+Tip: An "Account" in the XRP Ledger is somewhere between the financial usage (like "bank account") and the computing usage (like "UNIX account"). Non-XRP currencies and assets aren't stored in an XRP Ledger Account itself; each such asset is stored in an accounting relationship called a "Trust Line" that connects two parties.
Addresses
-Accounts in the RCL are identified by a base58 Ripple Address. The address is derived from the account's master public key, which is in turn derived from a secret key. An address is represented as a string in JSON and has the following characteristics:
+Accounts in the XRP Ledger are identified by a base58 Ripple Address. The address is derived from the account's master public key, which is in turn derived from a secret key. An address is represented as a string in JSON and has the following characteristics:
- Between 25 and 35 characters in length
- Starts with the character
r
@@ -183,11 +183,11 @@
- Case-sensitive
- Includes a 4-byte checksum so that the probability of generating a valid address from random characters is approximately 1 in 2^32
Any valid address can become an account in the Ripple Consensus Ledger by receiving a Payment of XRP, as long as the amount of XRP delivered is greater than or equal to the account reserve. This is called funding the account. You can also use an address that has not been funded to represent a regular key or a member of a signer list. Only a funded account can be the sender of a transaction.
-Creating a valid address is a strictly mathematical task starting with a key pair. You can generate a key pair and calculate its address entirely offline without communicating to the Ripple Consensus Ledger or any other party. The conversion from a public key to an address involves a one-way hash function, so it is possible to confirm that a public key matches an address but it is impossible to derive the public key from the address alone. (This is part of the reason why signed transactions include the public key and the address of the sender.)
+Any valid address can become an account in the XRP Ledger by receiving a Payment of XRP, as long as the amount of XRP delivered is greater than or equal to the account reserve. This is called funding the account. You can also use an address that has not been funded to represent a regular key or a member of a signer list. Only a funded account can be the sender of a transaction.
+Creating a valid address is a strictly mathematical task starting with a key pair. You can generate a key pair and calculate its address entirely offline without communicating to the XRP Ledger or any other party. The conversion from a public key to an address involves a one-way hash function, so it is possible to confirm that a public key matches an address but it is impossible to derive the public key from the address alone. (This is part of the reason why signed transactions include the public key and the address of the sender.)
For more technical details of how to calculate a Ripple address, see Address Encoding.
Special Addresses
-Some addresses have special meaning, or historical uses, in the Ripple Consensus Ledger. In many cases, these are "black hole" addresses, meaning the address is not derived from a known secret key. Since it is effectively impossible to guess a secret key from only an address, any XRP possessed by black hole addresses is lost forever.
+Some addresses have special meaning, or historical uses, in the XRP Ledger. In many cases, these are "black hole" addresses, meaning the address is not derived from a known secret key. Since it is effectively impossible to guess a secret key from only an address, any XRP possessed by black hole addresses is lost forever.
Permanence of Accounts
-Once created, an account exists in the Ripple Consensus Ledger's data tree forever. This is because the current sequence number for a transaction must be tracked forever, so that old transactions cannot be processed a second time.
-Unlike Bitcoin and many other crypto-currencies, each new version of the Ripple Consensus Ledger's public ledger chain contains the full state of the ledger, which increases in size with each new account. For that reason, Ripple discourages creating new accounts unless entirely necessary. Institutions who send and receive value on behalf of many users can use Source Tags and Destination Tags to distinguish payments from and to their customers while only using one (or a handful) of accounts in the Ripple Consensus Ledger.
+Once created, an account exists in the XRP Ledger's data tree forever. This is because the current sequence number for a transaction must be tracked forever, so that old transactions cannot be processed a second time.
+Unlike Bitcoin and many other crypto-currencies, each new version of the XRP Ledger's public ledger chain contains the full state of the ledger, which increases in size with each new account. For that reason, Ripple discourages creating new accounts unless entirely necessary. Institutions who send and receive value on behalf of many users can use Source Tags and Destination Tags to distinguish payments from and to their customers while only using one (or a handful) of accounts in the Ripple Consensus Ledger.
Transaction History
-In the Ripple Consensus Ledger, transaction history is tracked by a "thread" of transactions linked by a transaction's identifying hash and the ledger index. The AccountRoot ledger node has the identifying hash and ledger of the transaction that most recently modified it; the metadata of that transaction includes the previous state of the AccountRoot node, so it is possible to iterate through the history of a single account this way. This transaction history includes any transactions that modify the AccountRoot node directly, including:
In the XRP Ledger, transaction history is tracked by a "thread" of transactions linked by a transaction's identifying hash and the ledger index. The AccountRoot ledger node has the identifying hash and ledger of the transaction that most recently modified it; the metadata of that transaction includes the previous state of the AccountRoot node, so it is possible to iterate through the history of a single account this way. This transaction history includes any transactions that modify the AccountRoot node directly, including:
- Transactions sent by the account, because they modify the account's
Sequencenumber. These transactions also modify the account's XRP balance because of the transaction cost. - Transactions that modified the account's XRP balance, including incoming Payment transactions and other types of transactions such as PaymentChannelClaim and EscrowFinish. @@ -250,7 +250,7 @@
For more information on each of these objects, see the Ledger Format Reference.
Address Encoding
-Tip: These technical details are only relevant for people building low-level library software for RCL compatibility!
+Tip: These technical details are only relevant for people building low-level library software for XRP Ledger compatibility!
Ripple addresses are encoded using base58 with the Ripple dictionary: rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz. Since Ripple encodes several types of keys with base58, Ripple prefixes the encoded data with a one-byte "type prefix" (also called a "version prefix") to distinguish them. The type prefix causes addresses to usually start with different letters in base58 format.
The following diagram shows the relationship between keys and addresses:
diff --git a/concept-amendments.html b/concept-amendments.html index 823de9e216..453423ded2 100644 --- a/concept-amendments.html +++ b/concept-amendments.html @@ -83,7 +83,7 @@- Accounts
- Amendments @@ -128,7 +128,7 @@
- Category: RCL Features +
- Category: Features
- Accounts
- Amendments
- Fee Voting @@ -185,7 +185,7 @@
- Rounding is slightly different in some cases.
- Due to differences in rounding, some combinations of offers may be ranked higher or lower than by the old logic, and taken preferentially. @@ -591,7 +591,7 @@ TrustSetAuth
-
- RCL Features
+ Features
- Accounts
- Amendments @@ -128,7 +128,7 @@
- - RCL Features + Features
-
- RCL Features
+ Features
- Accounts
- Amendments @@ -128,7 +128,7 @@
- Category: RCL Features +
- Category: Features
- Accounts
- Amendments
- Fee Voting @@ -174,13 +174,13 @@
- Individual Freeze - Freeze one counterparty.
- Global Freeze - Freeze all counterparties.
- No Freeze - Permanently give up the ability to freeze individual counterparties, as well as the ability to end a global freeze.
- 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. -
- 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. -
- 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. -
-
- RCL Features
+ Features
- Accounts
- Amendments @@ -158,24 +158,24 @@
- 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.
- Optional standby addresses, also known as "warm wallets." Trusted human operators use these addresses to transfer money to the operational addresses.
-
- RCL Features
+ Features
- Accounts
- Amendments @@ -128,7 +128,7 @@
- Category: RCL Features +
- Category: Features
- Accounts
- Amendments
- Fee Voting @@ -160,13 +160,13 @@
- - RCL Features + Features
In this category:
-
-
Understanding the NoRipple Flag
-In the Ripple Consensus Ledger (RCL), the "NoRipple" flag is a setting on a trust line. When an address enables the NoRipple flag on two trust lines, payments from third parties cannot "ripple" through that address on those trust lines. This protects liquidity providers from having balances shift unexpectedly between different issuers of the same currency.
+In the XRP Ledger (XRP Ledger), the "NoRipple" flag is a setting on a trust line. When an address enables the NoRipple flag on two trust lines, payments from third parties cannot "ripple" through that address on those trust lines. This protects liquidity providers from having balances shift unexpectedly between different issuers of the same currency.
Background
"Rippling" occurs when more than one trust line is adjusted to make a payment. For example, if Alice owes Charlie money, and Alice also owes Bob money, then you could represent that in Ripple with trust lines like so:
If Bob wants to pay $3 to Charlie, then he could say, "Alice, take $3 of the money you owe me, and pay it to Charlie." Alice transfers some of the debt from Bob to Charlie. In the end, the Ripple trust lines work out like so:
-
We call this process, where two addresses pay each other by adjusting the balances of trust lines in between them, "rippling". This is a useful and important feature of the Ripple Consensus Ledger. Rippling occurs when addresses are linked by trust lines that use the same currency code. The issuer does not need to be the same: in fact, larger chains always involve changing issuers.
+We call this process, where two addresses pay each other by adjusting the balances of trust lines in between them, "rippling". This is a useful and important feature of the XRP Ledger. Rippling occurs when addresses are linked by trust lines that use the same currency code. The issuer does not need to be the same: in fact, larger chains always involve changing issuers.
Justification
Sometimes you do not want your balances to ripple. For example, imagine Emily has money issued by two different financial institutions, like so
diff --git a/concept-partial-payments.html b/concept-partial-payments.html index 885049def0..d11319ed29 100644 --- a/concept-partial-payments.html +++ b/concept-partial-payments.html @@ -83,7 +83,7 @@
Issuing and Operational Addresses
-In the Ripple Consensus Ledger, financial institutions typically use multiple Ripple 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 Ripple addresses to minimize the risk associated with a compromised secret key. Ripple strongly recommends the following separation of roles:
Funds Lifecycle
-All non-XRP currency balances (issuances) in the Ripple Consensus Ledger (RCL) are tied to accounting relationships between two Ripple addresses. When a financial institution uses Ripple's recommended separation of roles, funds relating to that institution tend to flow in a cycle.
+All non-XRP currency balances (issuances) in the XRP Ledger (XRP Ledger) are tied to accounting relationships between two Ripple addresses. When a financial institution uses Ripple's recommended separation of roles, funds relating to that institution tend to flow in a cycle.
-
When the issuing address sends payments, it creates balances in the accounting relationships in the Ripple Consensus Ledger. Within the RCL, users can exchange balances across different accounting relationships, so we use the term issuances to describe any non-XRP balance. Issuances have negative value from the perspective of the issuing address, since they represent obligations. The same issuances 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 issuances that were sent.
-The issuing address sends issuances to a standby address, or directly to an operational address. The standby addresses send those issuances to operational addresses. Operational addresses send payments to other counterparties, such as liquidity providers, partners, and other customers. Because all issuances are tied to accounting relationships with the issuing address, payments and exchanges of issuances "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 Ripple Consensus Ledger also supports more complicated paths that connect multiple issuers through order books and liquidity providers who allow their funds to ripple.
+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 issuances to describe any non-XRP balance. Issuances have negative value from the perspective of the issuing address, since they represent obligations. The same issuances 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 issuances that were sent.
+The issuing address sends issuances to a standby address, or directly to an operational address. The standby addresses send those issuances to operational addresses. Operational addresses send payments to other counterparties, such as liquidity providers, partners, and other customers. Because all issuances are tied to accounting relationships with the issuing address, payments and exchanges of issuances "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 that connect multiple issuers through order books and liquidity providers who allow their funds to ripple.
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 Ripple Consensus Ledger are public, automated systems can monitor for payments to the issuing address without needing a secret key.
+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 issuances without limit and trade them in the decentralized exchange. This would make it difficult for the financial institution to distinguish legitimately-obtained issuances 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 Ripple Consensus 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 and the global freeze 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.
+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 and the global freeze 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 issuances 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 issuances. 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.
diff --git a/concept-noripple.html b/concept-noripple.html index 43c5344dbd..b48498ec65 100644 --- a/concept-noripple.html +++ b/concept-noripple.html @@ -83,7 +83,7 @@
In this category:
-
-
Freeze Features
-The Ripple Consensus Ledger gives addresses the ability to freeze non-XRP balances, which can be useful to meet regulatory requirements, or while investigating suspicious activity. There are three settings related to freezes:
+The XRP Ledger gives addresses the ability to freeze non-XRP balances, which can be useful to meet regulatory requirements, or while investigating suspicious activity. There are three settings related to freezes:
Because no party has a privileged place in the Ripple Consensus Ledger, the freeze feature cannot prevent a counterparty from conducting transactions in XRP or funds issued by other counterparties. No one can freeze XRP.
+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. When an issuing address enables the Individual Freeze setting, the following rules apply:
@@ -190,7 +190,7 @@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 operates that are connected to the Ripple Consensus Ledger. (Otherwise, an address might still be able to engage in undesired activity by sending payments through the financial institution.)
+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 operates 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, from sending that financial institution's issuances 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 setting.
@@ -201,7 +201,7 @@It can be useful to enable Global Freeze on a financial institution's issuing address 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 Ripple Consensus Ledger, a financial institution should also suspend activities in its connectors to outside systems.
+It can be useful to enable Global Freeze on a financial institution's issuing address 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, 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 setting, it can never disable Global Freeze.
@@ -211,7 +211,7 @@The Ripple Consensus Ledger cannot force a financial institution to honor the obligations that its issued funds represent, so giving up the ability to enable a Global Freeze cannot protect customers. However, giving up the ability to disable a Global Freeze ensures that the Global Freeze feature is not used unfairly against some customers.
+The XRP Ledger cannot force a financial institution to honor the obligations that its issued funds represent, so giving up the ability to enable a Global Freeze cannot protect customers. However, giving up the ability to disable a Global Freeze ensures that the Global Freeze feature is not used unfairly against some customers.
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 or a multi-signed transaction to enable No Freeze.
Technical Details
diff --git a/concept-issuing-and-operational-addresses.html b/concept-issuing-and-operational-addresses.html index efc2c40ba3..3307812b67 100644 --- a/concept-issuing-and-operational-addresses.html +++ b/concept-issuing-and-operational-addresses.html @@ -83,7 +83,7 @@
In this category:
- The malicious actor sends a Payment transaction to the institution. This transaction has a large
Amountfield and has the tfPartialPayment flag enabled. - The partial payment succeeds (result code
tesSUCCESS) but actually delivers a very small amount of the currency specified. - The vulnerable institution reads the transaction's
Amountfield without looking at theFlagsfield ordelivered_amountmetadata field.
- - The vulnerable institution credits the malicious actor in an external system, such as the institution's own ledger, for the full
Amount, despite only receiving a much smallerdelivered_amountin the Ripple Consensus Ledger.
+ - The vulnerable institution credits the malicious actor in an external system, such as the institution's own ledger, for the full
Amount, despite only receiving a much smallerdelivered_amountin the XRP Ledger. - The malicious actor withdraws as much of the balance as possible to another system before the vulnerable institution notices the discrepancy.
- Malicious actors usually prefer to convert the balance to another crypto-currency such as Bitcoin, because blockchain transactions are usually irreversible. With a withdrawal to a fiat currency system, the financial institution may be able to reverse or cancel the transaction several days after it initially executes. -
- In the case of an exchange, the malicious actor can also withdraw an XRP balance directly back into the Ripple Consensus Ledger. +
- In the case of an exchange, the malicious actor can also withdraw an XRP balance directly back into the XRP Ledger.
@@ -257,13 +257,13 @@
- The malicious actor sends a Payment transaction to the merchant. This transaction has a large
Amountfield and has the tfPartialPayment flag enabled. - The partial payment succeeds (result code
tesSUCCESS) but delivers only a very small amount of the currency specified. - The vulnerable merchant reads the transaction's
Amountfield without looking at theFlagsfield ordelivered_amountmetadata field.
- - The vulnerable merchant treats the invoice as paid and provides the goods or services to the malicious actor, despite only receiving a much smaller
delivered_amountin the Ripple Consensus Ledger.
+ - The vulnerable merchant treats the invoice as paid and provides the goods or services to the malicious actor, despite only receiving a much smaller
delivered_amountin the XRP Ledger. - The malicious actor uses, resells, or absconds with the goods and services before the merchant notices the discrepancy.
- Add additional sanity checks to your business logic for processing withdrawals. Never process a withdrawal if the total balance you hold in the Ripple Consensus Ledger does not match your expected assets and obligations. +
- Add additional sanity checks to your business logic for processing withdrawals. Never process a withdrawal if the total balance you hold in the XRP Ledger does not match your expected assets and obligations.
- Follow "Know Your Customer" guidelines and strictly verify your customers' identities. You may be able to recognize and block malicious users in advance, or pursue legal action against a malicious actor who exploits your system.
In this category:
-
-
Background
Any changes to transaction processing could cause servers to build a different ledger with the same set of transactions. If some validators (rippled servers participating in consensus) have upgraded to a new version of the software while other validators use the old version, this could cause anything from minor inconveniences to full outages. In the minor case, a minority of servers spend more time and bandwidth fetching the actual consensus ledger because they cannot build it using the transaction processing rules they already know. In the worst case, the consensus process might be unable to validate new ledger versions because servers with different rules could not reach a consensus on the exact ledger to build.
Amendments solve this problem, so that new features can be enabled only when enough validators support those features.
-Users and businesses who rely on the Ripple Consensus Ledger can also use Amendments to provide advance notice of changes in transaction processing that might affect their business. However, API changes that do not impact transaction processing or the consensus process do not need Amendments.
+Users and businesses who rely on the XRP Ledger can also use Amendments to provide advance notice of changes in transaction processing that might affect their business. However, API changes that do not impact transaction processing or the consensus process do not need Amendments.
About Amendments
An amendment is a fully-functional feature or change, waiting to be enabled by the peer-to-peer network as a part of the consensus process. A rippled server that wants to use an amendment has code for two modes: without the amendment (old behavior) and with the amendment (new behavior).
Every amendment has a unique identifying hex value and a short name. The short name is for human use, and is not used in the amendment process. Two servers can support the same amendment ID while using different names to describe it. An amendment's name is not guaranteed to be unique.
@@ -245,7 +245,7 @@ TrustSetAuthKnown Amendments
-The following is a comprehensive list of all known amendments and their status on the production Ripple Consensus Ledger:
+The following is a comprehensive list of all known amendments and their status on the production XRP Ledger:
Adds sanity checks to transaction processing to ensure that certain conditions are always met. This provides an extra, independent layer of protection against bugs in transaction processing that could otherwise cause exploits and vulnerabilities in the Ripple Consensus Ledger. Ripple expects to add more invariant checks in future versions of rippled without additional amendments.
Adds sanity checks to transaction processing to ensure that certain conditions are always met. This provides an extra, independent layer of protection against bugs in transaction processing that could otherwise cause exploits and vulnerabilities in the XRP Ledger. Ripple expects to add more invariant checks in future versions of rippled without additional amendments.
Introduces two new transaction error codes, tecINVARIANT_FAILED and tefINVARIANT_FAILED. Changes transaction processing to add the new checks.
Examples of invariant checks:
-
@@ -400,7 +400,7 @@ TrustSetAuth
Replaces the SusPay and CryptoConditions amendments.
-Provides "suspended payments" for XRP for escrow within the Ripple Consensus Ledger, including support for Interledger Protocol Crypto-Conditions. Creates a new ledger node type for suspended payments and new transaction types to create, execute, and cancel suspended payments.
+Provides "suspended payments" for XRP for escrow within the XRP Ledger, including support for Interledger Protocol Crypto-Conditions. Creates a new ledger node type for suspended payments and new transaction types to create, execute, and cancel suspended payments.
FeeEscalation
Streamlines the offer crossing logic in the RCL's decentralized exchange. Uses the updated code from the Flow amendment to power offer crossing, so OfferCreate transactions and Payment transactions share more code. This has subtle differences in how offers are processed:
+Streamlines the offer crossing logic in the XRP Ledger's decentralized exchange. Uses the updated code from the Flow amendment to power offer crossing, so OfferCreate transactions and Payment transactions share more code. This has subtle differences in how offers are processed:
Changes the hash tree structure that rippled uses to represent a ledger. The new structure is more compact and efficient than the previous version. This affects how ledger hashes are calculated, but has no other user-facing consequences.
When this amendment is activated, the Ripple Consensus Ledger will undergo a brief scheduled unavailability while the network calculates the changes to the hash tree structure.
+When this amendment is activated, the XRP Ledger will undergo a brief scheduled unavailability while the network calculates the changes to the hash tree structure.
SusPay
Changes the way Offers are ranked in order books, so that currency issuers can configure how many significant digits are taken into account when ranking Offers by exchange rate. With this amendment, the exchange rates of Offers are rounded to the configured number of significant digits, so that more Offers have the same exact exchange rate. The intent of this change is to require a meaningful improvement in price to outrank a previous Offer. If used by major issuers, this should reduce the incentive to spam the ledger with Offers that are only a tiny fraction of a percentage point better than existing offers. It may also increase the efficiency of order book storage in the ledger, because Offers can be grouped into fewer exchange rates.
-Introduces a TickSize field to accounts, which can be set with the AccountSet transaction type. If a currency issuer sets the TickSize field, the Ripple Consensus Ledger truncates the exchange rate (ratio of funds in to funds out) of Offers to trade the issuer's currency, and adjusts the amounts of the Offer to match the truncated exchange rate. If only one currency in the trade has a TickSize set, that number of significant digits applies. When trading two currencies that have different TickSize values, whichever TickSize indicates the fewest significant digits applies. XRP does not have a TickSize.
Introduces a TickSize field to accounts, which can be set with the AccountSet transaction type. If a currency issuer sets the TickSize field, the XRP Ledger truncates the exchange rate (ratio of funds in to funds out) of Offers to trade the issuer's currency, and adjusts the amounts of the Offer to match the truncated exchange rate. If only one currency in the trade has a TickSize set, that number of significant digits applies. When trading two currencies that have different TickSize values, whichever TickSize indicates the fewest significant digits applies. XRP does not have a TickSize.
Tickets
Partial Payments Exploit
-If a financial institution's integration with the Ripple Consensus Ledger assumes that the Amount field of a Payment is always the full amount delivered, malicious actors may be able to exploit that assumption to steal money from the institution. This exploit can be used against gateways, exchanges, or merchants as long as those institutions' software does not process partial payments correctly.
If a financial institution's integration with the XRP Ledger assumes that the Amount field of a Payment is always the full amount delivered, malicious actors may be able to exploit that assumption to steal money from the institution. This exploit can be used against gateways, exchanges, or merchants as long as those institutions' software does not process partial payments correctly.
The correct way to process incoming Payment transactions is to use the delivered_amount metadata field, not the Amount field. This way, an institution is never mistaken about how much it actually received.
Exploit Scenario Steps
To exploit a vulnerable financial institution, a malicious actor does something like this:
@@ -243,10 +243,10 @@Further Mitigations
Using the delivered_amount field when processing incoming transactions is sufficient to avoid this exploit. Still, additional proactive business practices can also avoid or mitigate the likelihood of this and similar exploits. For example:
-
-
- Accounts
- Amendments @@ -128,7 +128,7 @@
- Category: RCL Features +
- Category: Features
- Accounts
- Amendments
- Fee Voting @@ -160,8 +160,8 @@
- - RCL Features + Features
-
- RCL Features
+ Features
- Accounts
- Amendments @@ -128,7 +128,7 @@
-
- RCL Features
+ Features
- Accounts
- Amendments @@ -128,7 +128,7 @@
-
- RCL Features
+ Features
- Accounts
- Amendments @@ -128,7 +128,7 @@
- Category: RCL Features +
- Category: Features
- Accounts
- Amendments
- Fee Voting @@ -158,7 +158,7 @@
- - RCL Features + Features
- - RCL Features + Features
- - RCL Features + Features
- - RCL Features + Features
- Between 25 and 35 characters in length
- Starts with the character
r
@@ -7448,7 +7448,7 @@ Content-Type: image/svg+xml
- To authorize transactions, a public key is attached to the transaction. The public key must be mathematically associated with the sending Ripple address or the sender's regular key address.
- To secure peer-to-peer communications between
rippledservers. This uses a "node public key" that the server generates randomly when it starts with an empty database.
@@ -7490,10 +7490,10 @@ Content-Type: image/svg+xml
- Three-character currency code. We recommend using all-uppercase ISO 4217 Currency Codes. However, any combination of the following characters is permitted: all uppercase and lowercase letters, digits, as well as the symbols
?,!,@,#,$,%,^,&,*,<,>,(,),{,},[,], and|. The currency codeXRP(all-uppercase) is reserved for XRP and cannot be used by issued currencies. - 160-bit hexadecimal values, such as
0158415500000000C1F76FF6ECB0BAC600000000, according to Ripple's internal Currency Format. This representation is uncommon.
@@ -7641,7 +7641,7 @@ Content-Type: image/svg+xml
-
- RCL Features
+ Features
- Accounts
- Amendments @@ -173,7 +173,7 @@
- - RCL Features + Features
-
- RCL Features
+ Features
- Accounts
- Amendments @@ -248,7 +248,7 @@
rippledSetup- API Reference @@ -271,7 +271,7 @@
- Between 25 and 35 characters in length
- Starts with the character
r
@@ -649,8 +649,8 @@ Null method
- Three-character currency code. We recommend using all-uppercase ISO 4217 Currency Codes. However, any combination of the following characters is permitted: all uppercase and lowercase letters, digits, as well as the symbols
?,!,@,#,$,%,^,&,*,<,>,(,),{,},[,], and|. The currency codeXRP(all-uppercase) is reserved for XRP and cannot be used by issued currencies. - 160-bit hexadecimal values, such as
0158415500000000C1F76FF6ECB0BAC600000000, according to Ripple's internal Currency Format. This representation is uncommon.
@@ -814,7 +814,7 @@ Null method
json- Pass JSON through the commandline- Caution: The next sequence number for the account is not incremented until this transaction is applied. If you sign multiple transactions without submitting and waiting for the response to each one, you must manually provide the correct sequence numbers for each transaction after the first. -
Fee- If you omit theFeeparameter, the server tries to fill in an appropriate transaction cost automatically. On the production Ripple Consensus Ledger, this fails withrpcHIGH_FEEunless you provide an appropriatefee_mult_maxvalue.-
-
- The
fee_mult_maxandfee_div_maxparameters limit how high the automatically-provided transaction cost can be, in terms of the load-scaling multiplier that gets applied to the reference transaction cost. The default settings return an error if the automatically-provided value would use greater than a 10× multiplier. However, the production Ripple Consensus Ledger typically has a 1000× load multiplier.
- - The commandline syntax does not support
fee_mult_maxandfee_div_max. For the production Ripple Consensus Ledger, you must provide aFeevalue.
+ Fee- If you omit theFeeparameter, the server tries to fill in an appropriate transaction cost automatically. On the production XRP Ledger, this fails withrpcHIGH_FEEunless you provide an appropriatefee_mult_maxvalue.-
+
- The
fee_mult_maxandfee_div_maxparameters limit how high the automatically-provided transaction cost can be, in terms of the load-scaling multiplier that gets applied to the reference transaction cost. The default settings return an error if the automatically-provided value would use greater than a 10× multiplier. However, the production XRP Ledger typically has a 1000× load multiplier.
+ - The commandline syntax does not support
fee_mult_maxandfee_div_max. For the production XRP Ledger, you must provide aFeevalue. - Caution: A malicious server can specify an excessively high transaction cost, ignoring the values of
fee_mult_maxandfee_div_max.
@@ -13618,9 +13618,9 @@ Connecting to 127.0.0.1:5005
- The
- Any of the universal error types.
Peer Protocol
-Servers in the Ripple Consensus Ledger communicate to each other using the Ripple peer protocol, also known as RTXP. Peer servers connect via HTTPS and then perform an HTTP upgrade to RTXP. (For more information, see the Overlay Network article in the
+rippledrepository.)Servers in the XRP Ledger communicate to each other using the Ripple peer protocol, also known as RTXP. Peer servers connect via HTTPS and then perform an HTTP upgrade to RTXP. (For more information, see the Overlay Network article in the
rippledrepository.)Configuring the Peer Protocol
-In order to participate in the Ripple Consensus Ledger,
+rippledservers connects to arbitrary peers using the peer protocol. (All such peers are treated as untrusted, unless they are clustered with the current server.)In order to participate in the XRP Ledger,
rippledservers connects to arbitrary peers using the peer protocol. (All such peers are treated as untrusted, unless they are clustered with the current server.)Ideally, the server should be able to send and receive connections on the peer port. You should forward the port used for the peer protocol through your firewall to the
rippledserver. The defaultrippledconfiguration file listens for incoming peer protocol connections on port 51235 on all network interfaces. You can change the port used by editing the appropriate stanza in yourrippled.cfgfile.Example:
[port_peer] diff --git a/reference-transaction-format.html b/reference-transaction-format.html index 0e1e9d8210..594a0c7b42 100644 --- a/reference-transaction-format.html +++ b/reference-transaction-format.html @@ -83,7 +83,7 @@- The
-
- RCL Features
+ Features
Authorizing Transactions
-In the decentralized Ripple Consensus Ledger, a digital signature proves that a transaction is authorized to do a specific set of actions. Only signed transactions can be submitted to the network and included in a validated ledger. A signed transaction is immutable: its contents cannot change, and the signature is not valid for any other transaction.
+In the decentralized XRP Ledger, a digital signature proves that a transaction is authorized to do a specific set of actions. Only signed transactions can be submitted to the network and included in a validated ledger. A signed transaction is immutable: its contents cannot change, and the signature is not valid for any other transaction.
A transaction can be authorized by any of the following types of signatures:
- A single signature from the master secret key that is mathematically associated with the sending address. You can disable or enable the master key using an AccountSet transaction. @@ -237,7 +237,7 @@
- You can never remove the last method of signing transactions from an address.
Signing and Submitting Transactions
-Sending a transaction to the Ripple Consensus Ledger involves several steps:
+Sending a transaction to the XRP Ledger involves several steps:
- Create an unsigned transaction in JSON format.
- Use one or more signatures to authorize the transaction. @@ -262,7 +262,7 @@ "Sequence": 2, } -
- Convert it to a binary blob and sign it offline. This is preferable, since it means that the account secret used for signing the transaction is never transmitted over any network connection.
- You can use RippleAPI for offline signing. @@ -370,7 +370,7 @@ }
Multi-Signing
-Multi-signing in Ripple is the act of authorizing transactions for the Ripple Consensus Ledger by using a combination of multiple secret keys. You can have any combination of authorization methods enabled for your address, including multi-signing, a master key, and a regular key. (The only requirement is that at least one method must be enabled.)
+Multi-signing in Ripple is the act of authorizing transactions for the XRP Ledger by using a combination of multiple secret keys. You can have any combination of authorization methods enabled for your address, including multi-signing, a master key, and a regular key. (The only requirement is that at least one method must be enabled.)
The SignerListSet transaction defines which addresses can authorize transactions from your address. You can include up to 8 addresses in a SignerList. You can control how many signatures are needed, in which combinations, by using the quorum and weight values of the SignerList.
To successfully submit a multi-signed transaction, you must do all of the following:
-
@@ -503,7 +503,7 @@
For a production system, we recommend not leaving these fields to be filled by the server. For example, if transaction costs become high due to a temporary spike in network load, you may want to wait for the cost to decrease before sending some transactions, instead of paying the temporarily-high cost.
The
Pathsfield of the Payment transaction type can also be automatically filled in.Transaction Cost
-To protect the Ripple Consensus Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of XRP. This transaction cost is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network.
+To protect the XRP Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of XRP. This transaction cost is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network.
The
Feefield specifies an amount, in drops of XRP, to destroy as the cost for relaying this transaction. If the transaction is included in a validated ledger (whether or not it achieves its intended purpose), then the amount of XRP specified in theFeeparameter is destroyed forever. You can look up the transaction cost in advance, or letrippledset it automatically when you sign a transaction.Note: Multi-signed transactions require additional fees to relay to the network.
Canceling or Skipping a Transaction
@@ -654,7 +654,7 @@AccountSet
-An AccountSet transaction modifies the properties of an account in the Ripple Consensus Ledger.
+An AccountSet transaction modifies the properties of an account in the XRP Ledger.
Example AccountSet:
{ "TransactionType": "AccountSet", @@ -1036,7 +1036,7 @@Note: The minimum transaction cost to submit an EscrowFinish transaction increases if it contains a fulfillment. If the transaction has no fulfillment, the transaction cost is the standard 10 drops. If the transaction contains a fulfillment, the transaction cost is 330 drops of XRP plus another 10 drops for every 16 bytes in size of the preimage.
OfferCancel
-An OfferCancel transaction removes an Offer node from the Ripple Consensus Ledger.
+An OfferCancel transaction removes an Offer node from the XRP Ledger.
{ "TransactionType": "OfferCancel", "Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", @@ -1069,7 +1069,7 @@The OfferCancel method returns tesSUCCESS even if it did not find an offer with the matching sequence number.
OfferCreate
-An OfferCreate transaction is effectively a limit order. It defines an intent to exchange currencies, and creates an Offer node in the Ripple Consensus Ledger if not completely fulfilled when placed. Offers can be partially fulfilled.
+An OfferCreate transaction is effectively a limit order. It defines an intent to exchange currencies, and creates an Offer node in the XRP Ledger if not completely fulfilled when placed. Offers can be partially fulfilled.
{ "TransactionType": "OfferCreate", "Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", @@ -1164,7 +1164,7 @@TickSize
Requires the TickSize amendment.
When an Offer is placed into an order book, its exchange rate is truncated based on the
-TickSizevalues set by the issuers of the currencies involved in the Offer. When a trader offers to exchange XRP and an issued currency, theTickSizefrom the issuer of the currency applies. When a trader offers to exchange two issued currencies, the offer uses the smallerTickSizevalue (that is, the one with fewer significant digits). If neither currency has aTickSizeset, the default behavior applies.The
+TickSizevalue truncates the number of significant digits in the exchange rate of an offer when it gets placed in an order book. Issuers can setTickSizeto an integer from3to15using an AccountSet transaction. The exchange rate is represented as a number of significant digits plus an exponent; theTickSizedoes not affect the exponent. This allows the Ripple Consensus Ledger to represent exchange rates between assets that vary greatly in value (for example, a hyperinflated currency compared to a rare commodity). The lower theTickSizean issuer sets, the larger the increment traders must offer to be considered a higher exchange rate than the existing Offers.The
TickSizevalue truncates the number of significant digits in the exchange rate of an offer when it gets placed in an order book. Issuers can setTickSizeto an integer from3to15using an AccountSet transaction. The exchange rate is represented as a number of significant digits plus an exponent; theTickSizedoes not affect the exponent. This allows the XRP Ledger to represent exchange rates between assets that vary greatly in value (for example, a hyperinflated currency compared to a rare commodity). The lower theTickSizean issuer sets, the larger the increment traders must offer to be considered a higher exchange rate than the existing Offers.The
TickSizedoes not affect the portion of an Offer that can be executed immediately. (For that reason, OfferCreate transactions withtfImmediateOrCancelare unaffected byTickSizevalues.) If the Offer cannot be fully executed, the transaction processing engine calculates the exchange rate and truncates it based onTickSize. Then, the engine rounds the remaining amount of the Offer from the "less important" side to match the truncated exchange rate. For a default OfferCreate transaction (a "buy" Offer), theTakerPaysamount (the amount being bought) gets rounded. If thetfSellflag is enabled (a "sell" Offer) theTakerGetsamount (the amount being sold) gets rounded.When an issuer enables, disables, or changes the
TickSize, Offers that were placed under the previous setting are unaffected.Expiration
@@ -1173,7 +1173,7 @@Note: Since only new transactions can modify the ledger, an expired offer can stay on the ledger after it becomes inactive. The offer is treated as unfunded and has no effect, but it can continue to appear in results (for example, from the ledger_entry command). Later on, the expired offer can get finally deleted as a result of another transaction (such as another OfferCreate) if the server finds it while processing.
If an OfferCreate transaction has an
Expirationtime that has already passed when the transaction first gets included in a ledger, the transaction does not execute the offer but still results in atesSUCCESStransaction code. (This is because such a transaction could still successfully cancel another offer.)Auto-Bridging
-Any OfferCreate that would exchange two non-XRP currencies could potentially use XRP as an intermediary currency in a synthetic order book. This is because of auto-bridging, which serves to improve liquidity across all currency pairs by using XRP as a vehicle currency. This works because of XRP's nature as a native cryptocurrency to the Ripple Consensus Ledger. Offer execution can use a combination of direct and auto-bridged offers to achieve the best total exchange rate.
+Any OfferCreate that would exchange two non-XRP currencies could potentially use XRP as an intermediary currency in a synthetic order book. This is because of auto-bridging, which serves to improve liquidity across all currency pairs by using XRP as a vehicle currency. This works because of XRP's nature as a native cryptocurrency to the XRP Ledger. Offer execution can use a combination of direct and auto-bridged offers to achieve the best total exchange rate.
Example: Anita places an offer to sell GBP and buy BRL. She might fund that this uncommon currency market has few offers. There is one offer with a good rate, but it has insufficient quantity to satisfy Anita's trade. However, both GBP and BRL have active, competitive markets to XRP. Auto-bridging software finds a way to complete Anita's offer by purchasing XRP with GBP from one trader, then selling the XRP to another trader to buy BRL. Anita automatically gets the best rate possible by combining the small offer in the direct GBP:BRL market with the better composite rates created by pairing GBP:XRP and XRP:BRL offers.
Auto-bridging happens automatically on any OfferCreate transaction. Payment transactions do not autobridge by default, but path-finding can find paths that have the same effect.
OfferCreate Flags
@@ -1299,7 +1299,7 @@- When the
issuerfield of theSendMaxfield 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 issuances on trust lines that other accounts have extended to the source account, and sending issuances the source account holds from other issuers.Creating Accounts
-The Payment transaction type is the only way to create new accounts in the Ripple Consensus Ledger. To do so, send an amount of XRP that is equal or greater than the account reserve to a mathematically-valid account address that does not exist yet. When the Payment is processed, a new AccountRoot node is added to the ledger.
+The Payment transaction type is the only way to create new accounts in the XRP Ledger. To do so, send an amount of XRP that is equal or greater than the account reserve to a mathematically-valid account address that does not exist yet. When the Payment is processed, a new AccountRoot node is added to the ledger.
If you send an insufficient amount of XRP, or any other currency, the Payment fails.
Paths
If present, the
@@ -1728,8 +1728,8 @@Pathsfield must contain a path set - an array of path arrays. Each individual path represents one way value can flow from the sender to receiver through various intermediary accounts and order books. A single transaction can potentially use multiple paths, for example if the transaction exchanges currency using several different order books to achieve the best rate.
The Ripple Consensus Ledger only relays and executes a transaction if the transaction object has been authorized by the sending address (in the
+Account) field. For transactions authorized by only a single signature, you have two options:The XRP Ledger only relays and executes a transaction if the transaction object has been authorized by the sending address (in the
Account) field. For transactions authorized by only a single signature, you have two options:
rippled
-The core peer-to-peer server that manages the Ripple Consensus Ledger (RCL) is called
+rippled. Eachrippledserver connects to a network of peers, relays cryptographically signed transactions, and maintains a local copy of the complete shared global ledger. The source code forrippledis written in C++, and is available on GitHub under an open-source license.The core peer-to-peer server that manages the XRP Ledger (XRP Ledger) is called
rippled. Eachrippledserver connects to a network of peers, relays cryptographically signed transactions, and maintains a local copy of the complete shared global ledger. The source code forrippledis written in C++, and is available on GitHub under an open-source license.Alternatively, you can run your own local copy of
rippled. This is required if you want to access any of the Admin Commands. In this case, you should use whatever IP and port you configured the server to bind. (For example,127.0.0.1:54321) Additionally, to access admin functionality, you must connect from a port/IP address marked as admin in the config file.The example config file listens for connections on the local loopback network (127.0.0.1), with JSON-RPC (HTTP) on port 5005 and WebSocket (WS) on port 6006, and treats all connected clients as admin.
WebSocket API
-If you are looking to try out some methods on the Ripple Consensus Ledger, you can skip writing your own WebSocket code and go straight to using the API at the Ripple WebSocket API Tool. Later on, when you want to connect to your own
+rippledserver, you can build your own client in the browser or in Node.js.If you are looking to try out some methods on the XRP Ledger, you can skip writing your own WebSocket code and go straight to using the API at the Ripple WebSocket API Tool. Later on, when you want to connect to your own
rippledserver, you can build your own client in the browser or in Node.js.Request Formatting
After you open a WebSocket to the
rippledserver, you can send commands as a JSON object, with the following attributes:-
@@ -629,7 +629,7 @@ Null method
Transactions are identified by a Hash of the transaction's binary format. You can also identify a transaction by its sending account and Sequence Number.
Each closed Ledger has a Ledger Index and a Hash value. When Specifying a Ledger Instance you can use either one.
Addresses
-Accounts in the RCL are identified by a base58 Ripple Address. The address is derived from the account's master public key, which is in turn derived from a secret key. An address is represented as a string in JSON and has the following characteristics:
+Accounts in the XRP Ledger are identified by a base58 Ripple Address. The address is derived from the account's master public key, which is in turn derived from a secret key. An address is represented as a string in JSON and has the following characteristics:
Note: SHA-512Half has similar security to the officially-defined SHA-512/256 hash function. However, Ripple's usage predates SHA-512/256 and is also easier to implement on top of an existing SHA-512 function. (As of this writing, SHA-512 support in cryptographic libraries is much more common than for SHA-512/256.)
Account Sequence
A Sequence number is a 32-bit unsigned integer used to identify a transaction or Offer relative to a specific account.
-Every account object in the Ripple Consensus Ledger has a Sequence number, which starts at 1. For a transaction to be relayed to the network and possibly included in a validated ledger, it must have a
-Sequencefield that matches the sending account's currentSequencenumber. An account's Sequence field is incremented whenever a transaction from that account is included in a validated ledger (regardless of whether the transaction succeeded or failed). This preserves the order of transactions submitted by an account, and differentiates transactions that would otherwise be the same.Every Offer node in the Ripple Consensus Ledger is marked with the sending
+AccountAddress and theSequencevalue of the OfferCreate transaction that created it. These two fields, together, uniquely identify the Offer.Every account object in the XRP Ledger has a Sequence number, which starts at 1. For a transaction to be relayed to the network and possibly included in a validated ledger, it must have a
+Sequencefield that matches the sending account's currentSequencenumber. An account's Sequence field is incremented whenever a transaction from that account is included in a validated ledger (regardless of whether the transaction succeeded or failed). This preserves the order of transactions submitted by an account, and differentiates transactions that would otherwise be the same.Every Offer node in the XRP Ledger is marked with the sending
AccountAddress and theSequencevalue of the OfferCreate transaction that created it. These two fields, together, uniquely identify the Offer.Ledger Index
A ledger index is a 32-bit unsigned integer used to identify a ledger. The ledger index is also known as the ledger's sequence number. The very first ledger was ledger index 1, and each new ledger has a ledger index 1 higher than that of the ledger immediately before it.
The ledger index indicates the order of the ledgers; the Hash value identifies the exact contents of the ledger. Two ledgers with the same hash are always the same. For validated ledgers, hash values and sequence numbers are equally valid and correlate 1:1. However, this is not true for in-progress ledgers:
@@ -675,7 +675,7 @@ Null methodIf you do not specify a ledger, the
current(in-progress) ledger is chosen by default. If you provide more than one field specifying ledgers, the deprecatedledgerfield is used first if it exists, falling back toledger_hash. Theledger_indexfield is ignored unless neither of the other two are present.Note: Do not rely on this default behavior for specifying a ledger; it is subject to change. Always specify a ledger version in the request if you can.
Currencies
-There are two kinds of currencies in the Ripple Consensus Ledger: XRP, and everything else. There are many differences between the two:
+There are two kinds of currencies in the XRP Ledger: XRP, and everything else. There are many differences between the two:
@@ -761,7 +761,7 @@ Null method 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
currencyfield. Never include anissuerfield 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
issuervalue in the JSON object.Currency Codes
-There are two kinds of currency code in the Ripple Consensus Ledger:
+There are two kinds of currency code in the XRP Ledger:
Some methods return more data than can efficiently fit into one response. When there are more results than contained, the response includes a
markerfield. You can use this to retrieve more pages of data across multiple calls. In each request, pass themarkervalue from the previous response to resume from the point where you left off. If themarkeris omitted from a response, then you have reached the end of the data set.The format of the
markerfield is intentionally undefined. Each server can define amarkerfield as desired, so it may take the form of a string, a nested object, or another type. Different servers, and different methods provided by the same server, can have differentmarkerdefinitions. Eachmarkeris ephemeral, and may not work as expected after 10 minutes.Modifying the Ledger
-All changes to the Ripple Consensus Ledger (RCL) happen as the result of transactions. The only API methods that can change the contents of the RCL are the
+submitcommand and thesubmit_multisignedcommand. Most other methods represent different ways to view the data represented in the RCL. The remaining commands generate data for your convenience. (Thewallet_propose,path_find, andrandomcommands fall into this category.)All changes to the XRP Ledger (XRP Ledger) happen as the result of transactions. The only API methods that can change the contents of the RCL are the
submitcommand and thesubmit_multisignedcommand. Most other methods represent different ways to view the data represented in the RCL. The remaining commands generate data for your convenience. (Thewallet_propose,path_find, andrandomcommands fall into this category.)For more information on the various transactions you can submit, see the Transaction Format.
API Methods
API methods for the Websocket and JSON-RPC APIs are defined by command names, and are divided into Public Commands and Admin Commands. Public Commands are not necessarily meant for the general public, but they are used by any client attached to the server. (Think of Public Commands as being for members or customers of the organization running the server, while the Admin Commands are for the personnel in charge of keeping the server operational.) Public Commands include the general operations for Ripple use, including checking the state of the ledger, finding a path to connecting users, and submitting a transaction, among others. Admin Commands, on the other hand, are meant only for the operators of the server, and include commands for managing the state of the server, the nodes it uses for validation, and other administrative features.
@@ -888,7 +888,7 @@ Null methodAccount Information
-An "Account" in the Ripple Consensus Ledger represents a holder of XRP and a sender of transactions. Accounts can send and receive XRP and issued assets, participate in the decentralized exchange, and change their own settings. Creating an account involves generating keys and then receiving XRP from another account. For more information, see Accounts.
+An "Account" in the XRP Ledger represents a holder of XRP and a sender of transactions. Accounts can send and receive XRP and issued assets, participate in the decentralized exchange, and change their own settings. Creating an account involves generating keys and then receiving XRP from another account. For more information, see Accounts.
account_currencies
The
@@ -3947,7 +3947,7 @@ There is also a deprecated legacy variation of theaccount_currenciescommand retrieves a list of currencies that an account can send or receive, based on its trust lines. (This is not a thoroughly confirmed list, but it can be used to populate user interfaces.)account_txmethowallet_propose
-Use the
+wallet_proposemethod to generate a key pair and Ripple address. This command only generates keys, and does not affect the Ripple Consensus Ledger itself in any way. To become a funded address stored in the ledger, the address must receive a Payment transaction that provides enough XRP to meet the reserve requirement.Use the
wallet_proposemethod to generate a key pair and Ripple address. This command only generates keys, and does not affect the XRP Ledger itself in any way. To become a funded address stored in the ledger, the address must receive a Payment transaction that provides enough XRP to meet the reserve requirement.The
wallet_proposerequest is an admin command that cannot be run by unprivileged users! (This command is restricted to protect against people sniffing network traffic for account secrets, since admin commands are not usually transmitted over the outside network.)
Request Format
@@ -4943,7 +4943,7 @@ rippled ledger_currentledger_entry
-The
+ledger_entrymethod returns a single ledger node from the Ripple Consensus Ledger in its raw format. See ledger format for information on the different types of objects you can retrieve.The
ledger_entrymethod returns a single ledger node from the XRP Ledger in its raw format. See ledger format for information on the different types of objects you can retrieve.Note: There is no commandline version of this method. You can use the
jsoncommand to access this method from the commandline instead.Request Format
An example of the request format:
@@ -7936,9 +7936,9 @@ rippled sign s██████████████████████Trust Limits
-All balances on the Ripple Consensus Ledger (RCL), except for XRP, represent value owed in the world outside the Ripple Ledger. The address that issues those funds in Ripple (identified by the
-issuerfield of theLimitAmountobject) is expected to pay the balance back, outside of the Ripple Consensus Ledger, when users redeem their Ripple balances by returning them to the issuer.Since a computer program cannot force a someone to keep a promise and not default in real life, trust lines represent a way of configuring how much you trust an issuer to hold on your behalf. Since a large, reputable financial institution is more likely to be able to pay you back than, say, your broke roommate, you can set different limits on each trust line, to indicate the maximum amount you are willing to let the issuer "owe" you in the RCL. If the issuer defaults or goes out of business, you can lose up to that much money because the balances you hold in the Ripple Consensus Ledger can no longer be exchanged for equivalent balances elsewhere. (You can still keep or trade the issuances in the RCL, but they no longer have any reason to be worth anything.)
+All balances on the XRP Ledger (XRP Ledger), except for XRP, represent value owed in the world outside the Ripple Ledger. The address that issues those funds in Ripple (identified by the
+issuerfield of theLimitAmountobject) is expected to pay the balance back, outside of the Ripple Consensus Ledger, when users redeem their Ripple balances by returning them to the issuer.Since a computer program cannot force a someone to keep a promise and not default in real life, trust lines represent a way of configuring how much you trust an issuer to hold on your behalf. Since a large, reputable financial institution is more likely to be able to pay you back than, say, your broke roommate, you can set different limits on each trust line, to indicate the maximum amount you are willing to let the issuer "owe" you in the XRP Ledger. If the issuer defaults or goes out of business, you can lose up to that much money because the balances you hold in the XRP Ledger can no longer be exchanged for equivalent balances elsewhere. (You can still keep or trade the issuances in the RCL, but they no longer have any reason to be worth anything.)
There are two cases where you can hold a balance on a trust line that is greater than your limit: when you acquire more of that currency through trading, or when you decrease the limit on your trust line.
Since a trust line occupies space in the ledger, a trust line increases the XRP your account must hold in reserve. This applies to the account extending trust, not to the account receiving it.
A trust line with settings in the default state is equivalent to no trust line.
@@ -2080,7 +2080,7 @@
The Ledger
-The Ripple Consensus Ledger is a shared, global ledger that is open to all. Individual participants can trust the integrity of the ledger without having to trust any single institution to manage it. The
+rippledserver software accomplishes this by managing a ledger database that can only be updated according to very specific rules. Each instance ofrippledkeeps a full copy of the ledger, and the peer-to-peer network ofrippledservers distributes candidate transactions among themselves. The consensus process determines which transactions get applied to each new version of the ledger. See also: The Consensus Process.The XRP Ledger is a shared, global ledger that is open to all. Individual participants can trust the integrity of the ledger without having to trust any single institution to manage it. The
rippledserver software accomplishes this by managing a ledger database that can only be updated according to very specific rules. Each instance ofrippledkeeps a full copy of the ledger, and the peer-to-peer network ofrippledservers distributes candidate transactions among themselves. The consensus process determines which transactions get applied to each new version of the ledger. See also: The Consensus Process.
The shared global ledger is actually a series of individual ledgers, or ledger versions, which
rippledkeeps in its internal database. Every ledger version has a ledger index which identifies the order in which ledgers occur. Each closed ledger version also has an identifying hash value, which uniquely identifies the contents of that ledger. At any given time, arippledinstance has an in-progress "current" open ledger, plus some number of closed ledgers that have not yet been approved by consensus, and any number of historical ledgers that have been validated by consensus. Only the validated ledgers are certain to be correct and immutable.A single ledger version consists of several parts:
diff --git a/reference-rippleapi.html b/reference-rippleapi.html index cdd2d8379d..c9e645a735 100644 --- a/reference-rippleapi.html +++ b/reference-rippleapi.html @@ -83,7 +83,7 @@ - - RCL Features + Features
- - RCL Features + Features
-
- RCL Features
+ Features
- Accounts
- Amendments @@ -163,9 +163,9 @@
- Ripple Integration
- Before Ripple Integration
- Sending from Gateway to Ripple -
- Requirements for Sending to RCL -
- Sending from RCL to Gateway -
- Requirements for Receiving from RCL +
- Requirements for Sending to XRP Ledger +
- Sending from XRP Ledger to Gateway +
- Requirements for Receiving from XRP Ledger
- Precautions
- Trading on Ripple
- Freeze @@ -198,10 +198,10 @@
- By enabling its customers to send and receive value in the Ripple Consensus Ledger, the business increases its value proposition to customers. -
- By accepting payments from the Ripple Consensus Ledger, the business increases the number of ways that customers can fund accounts at its business, even internationally. +
- By enabling its customers to send and receive value in the XRP Ledger, the business increases its value proposition to customers. +
- By accepting payments from the XRP Ledger, the business increases the number of ways that customers can fund accounts at its business, even internationally.
- The business can use Ripple-related services as a new source of revenue.
- Contact support@ripple.com for technical questions, clarifications, bug reports, and feature requests.
- An Issuing Gateway receives money (or other assets of value) outside of Ripple, and creates issuances in the Ripple Consensus Ledger. This provides a direct way for customers to get money in and out of the RCL. All currencies in the Ripple Consensus Ledger, except for XRP, take the form of issuances tied to a specific issuing gateway. -
- A Private Exchange holds XRP and lets its customers buy and sell that XRP in its own system. Most cryptocurrencies rely on private exchanges to provide a market for the cryptocurrency, but the Ripple Consensus Ledger has a currency exchange built into the protocol itself. -
- Merchants accept payment within the Ripple Consensus Ledger in exchange for goods and services in the outside world. Currently, Ripple does not have widespread support for merchant operations. +
- An Issuing Gateway receives money (or other assets of value) outside of Ripple, and creates issuances in the XRP Ledger. This provides a direct way for customers to get money in and out of the XRP Ledger. All currencies in the Ripple Consensus Ledger, except for XRP, take the form of issuances tied to a specific issuing gateway. +
- A Private Exchange holds XRP and lets its customers buy and sell that XRP in its own system. Most cryptocurrencies rely on private exchanges to provide a market for the cryptocurrency, but the XRP Ledger has a currency exchange built into the protocol itself. +
- Merchants accept payment within the XRP Ledger in exchange for goods and services in the outside world. Currently, Ripple does not have widespread support for merchant operations.
- Use separate Issuing and Operational Addresses to limit your risk profile on the network.
- Comply with anti-money-laundering regulations for your jurisdiction, such as the Bank Secrecy Act. This usually includes requirements to collect "Know-Your-Customer" (KYC) information. @@ -242,7 +242,7 @@
- Publicize all your policies and fees.
- 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. @@ -253,10 +253,10 @@
- Withdrawal and Deposit fees. Gateways typically charge a small fee (such as 1%) for the service of adding or removing money from Ripple. You have the power to determine the rate you credit people when they move money onto and off of Ripple through your gateway. -
- Transfer fees. You can set a percentage fee to charge automatically when customers send each other issuances created by your issuing address. This amount is debited from the Ripple Consensus Ledger, decreasing your obligation each time your issuances change hands. See TransferRate for details. +
- Transfer fees. You can set a percentage fee to charge automatically when customers send each other issuances created by your issuing address. This amount is debited from the XRP Ledger, decreasing your obligation each time your issuances change hands. See TransferRate for details.
- Indirect revenue from value added. Ripple integration can provide valuable functionality for your customers that distinguishes your business from your competitors. -
- Interest on Ripple-backed funds. You can keep the collateral for the funds you issue in RCL in a bank account that earns interest. Make sure you can always access enough funds to service customer withdrawals. -
- Financial Exchange. A gateway can also make offers to buy and sell its issuances for other issuances in the RCL, providing liquidity to cross-currency payments and possibly making a profit. (As with all financial exchange, profits are not guaranteed.) +
- Interest on Ripple-backed funds. You can keep the collateral for the funds you issue in XRP Ledger in a bank account that earns interest. Make sure you can always access enough funds to service customer withdrawals. +
- Financial Exchange. A gateway can also make offers to buy and sell its issuances for other issuances in the XRP Ledger, providing liquidity to cross-currency payments and possibly making a profit. (As with all financial exchange, profits are not guaranteed.)
- Alice asks to send €3 of her ACME balance into the RCL. +
- Alice asks to send €3 of her ACME balance into the XRP Ledger.
- In its system of record, ACME debits Alice's balance €3. -
- ACME submits a Ripple transaction, sending €3 to Alice's Ripple address. The €3 is marked in the Ripple Consensus Ledger as being "issued" by ACME (3 EUR.ACME). +
- ACME submits a Ripple transaction, sending €3 to Alice's Ripple address. The €3 is marked in the XRP Ledger as being "issued" by ACME (3 EUR.ACME).
- Alice already has an address in the Ripple Consensus Ledger separate from her ACME account. Alice manages her Ripple address using a third-party client application. +
- Alice already has an address in the XRP Ledger separate from her ACME account. Alice manages her Ripple address using a third-party client application.
- ACME sets aside money that is issued in the Ripple Consensus Ledger. ACME can query the RCL to see who holds its issuances at any time. There are several ways ACME may do this:
-
-
- ACME may create a Ripple Consensus Ledger collateral account in ACME's system of record. +
- ACME sets aside money that is issued in the XRP Ledger. ACME can query the XRP Ledger to see who holds its issuances at any time. There are several ways ACME may do this:
-
+
- ACME may create a XRP Ledger collateral account in ACME's system of record.
- ACME can store the funds allocated to Ripple in a separate bank account.
- If ACME is a cryptocurrency exchange, ACME can create a separate wallet to hold the funds allocated to Ripple, as publicly-verifiable proof to customers that the gateway is solvent.
- - ACME must control an address in the Ripple Consensus Ledger. Ripple's best practices recommend using a separate issuing address and operational address. See Issuing and Operational Addresses for details.
-
+
- ACME must control an address in the XRP Ledger. Ripple's best practices recommend using a separate issuing address and operational address. See Issuing and Operational Addresses for details.
- ACME must enable the DefaultRipple Flag on its issuing address for customers to send and receive its issuances.
@@ -431,16 +431,16 @@
- ACME must control an address in the XRP Ledger. Ripple's best practices recommend using a separate issuing address and operational address. See Issuing and Operational Addresses for details.
See Sending Payments to Customers for an example of how to send payments into Ripple.
-Sending from RCL to Gateway
-A payment out of the Ripple Consensus Ledger means the Gateway receives a payment in the RCL, and credits a user in the gateway's system of record.
+Sending from XRP Ledger to Gateway
+A payment out of the XRP Ledger means the Gateway receives a payment in the XRP Ledger, and credits a user in the gateway's system of record.
An example flow of a payment out of Ripple:
- Bob sends Ripple transaction of €1 to ACME's issuing address.
- In ACME's system of record, ACME credits Bob's balance €1.
Payments going from the Ripple Consensus Ledger to a gateway can be single-currency or cross-currency payments. The gateway's issuing address can only receive issuances it created (or XRP).
-Requirements for Receiving from RCL
-In addition to the requirements for sending into Ripple, there are several prerequisites that ACME must meet to process payments coming from Ripple:
+Payments going from the XRP Ledger to a gateway can be single-currency or cross-currency payments. The gateway's issuing address can only receive issuances it created (or XRP).
+Requirements for Receiving from XRP Ledger
+In addition to the requirements for sending into Ripple, there are several prerequisites that ACME must meet to process payments coming from Ripple:
- ACME must monitor its Ripple addresses for incoming payments.
- ACME must know which user to credit in its system of record for the incoming payments.
-
@@ -455,34 +455,34 @@
- Protect yourself against reversible deposits. Ripple payments are irreversible, but many electronic money systems like credit cards or PayPal are not. Scammers can abuse this to take their fiat money back by canceling a deposit after receiving Ripple issuances.
- When sending into Ripple, specify the issuing address as the issuer of the currency. Otherwise, you might accidentally use paths that deliver the same currency issued by other addresses.
- Before sending a payment into Ripple, double check the cost of the payment. A payment from your operational address to a customer should not cost more than the destination amount plus any transfer fee you have set. -
- Before processing a payment out of Ripple, make sure you know the customer's identity. This makes it harder for anonymous attackers to scam you. Most anti-money-laundering regulations require this anyway. This is especially important because the users sending money from the RCL could be different than the ones that initially received the money in the RCL. +
- Before processing a payment out of Ripple, make sure you know the customer's identity. This makes it harder for anonymous attackers to scam you. Most anti-money-laundering regulations require this anyway. This is especially important because the users sending money from the XRP Ledger could be different than the ones that initially received the money in the RCL.
- Follow the guidelines for reliable transaction submission when sending Ripple transactions.
- Robustly monitor for incoming payments, and read the correct amount. Don't mistakenly credit someone the full amount if they only sent a partial payment. -
- Track your obligations and balances within the Ripple Consensus Ledger, and compare with the assets in your collateral account. If they do not match up, stop processing withdrawals and deposits until you resolve the discrepancy. +
- Track your obligations and balances within the XRP Ledger, and compare with the assets in your collateral account. If they do not match up, stop processing withdrawals and deposits until you resolve the discrepancy.
- Avoid ambiguous situations. We recommend the following:
- Enable the
DisallowXRPflag for the issuing address and all operational addresses, so customers do not accidentally send you XRP. (Private exchanges should not set this flag, since they trade XRP normally.) - Enable the
RequireDestflag for the issuing address and all operational addresses, so customers do not accidentally send a payment without the destination tag to indicate who should be credited. - Enable the
RequireAuthflag on all operational addresses so they cannot issue currency by accident.
- - Enable the
- Monitor for suspicious or abusive behavior. For example, a user could repeatedly send funds into and out of the RCL, as a denial of service attack that effectively empties an operational address's balance. Suspend customers whose addresses are involved in suspicious behavior by not processing their Ripple payments. +
- Monitor for suspicious or abusive behavior. For example, a user could repeatedly send funds into and out of the XRP Ledger, as a denial of service attack that effectively empties an operational address's balance. Suspend customers whose addresses are involved in suspicious behavior by not processing their Ripple payments.
Trading on Ripple
-After the issuances have been created in the Ripple Consensus Ledger, they can be freely transferred and traded by RCL users. There are several consequences of this situation:
+After the issuances have been created in the XRP Ledger, they can be freely transferred and traded by XRP Ledger users. There are several consequences of this situation:
- Anyone can buy/sell EUR.ACME on Ripple. If ACME issues multiple currencies on Ripple, a separate trust line is necessary for each.
-
-
- This includes RCL users who do not have an account in ACME Exchange's systems. To withdraw the funds successfully from ACME, users still have to register with ACME. -
- Optionally, ACME uses the Authorized Accounts feature to limit who can hold EUR.ACME in the RCL. -
- If ACME determines that a customer has acted in bad faith, ACME can Freeze that user's accounting relationships to ACME in the RCL, so that the user can no longer trade in the gateway's issuances. +
- This includes XRP Ledger users who do not have an account in ACME Exchange's systems. To withdraw the funds successfully from ACME, users still have to register with ACME. +
- Optionally, ACME uses the Authorized Accounts feature to limit who can hold EUR.ACME in the XRP Ledger. +
- If ACME determines that a customer has acted in bad faith, ACME can Freeze that user's accounting relationships to ACME in the XRP Ledger, so that the user can no longer trade in the gateway's issuances.
- - RCL users trading and sending EUR.ACME to one another requires no intervention by ACME. -
- All exchanges and balances in the RCL are publicly viewable. +
- XRP Ledger users trading and sending EUR.ACME to one another requires no intervention by ACME. +
- All exchanges and balances in the XRP Ledger are publicly viewable.
The following diagram depicts a Ripple payment sending 2EUR.ACME from Alice to Charlie. ACME can query the RCL to see updates to its balances any time after the transaction has occurred:
+The following diagram depicts a Ripple payment sending 2EUR.ACME from Alice to Charlie. ACME can query the XRP Ledger to see updates to its balances any time after the transaction has occurred:
Freeze
-A gateway can freeze accounting relationships in the Ripple Consensus Ledger to meet regulatory requirements:
+A gateway can freeze accounting relationships in the XRP Ledger to meet regulatory requirements:
- Gateways can freeze individual accounting relationships, in case a customer address shows suspicious activity or violates a gateway's terms of use.
- Gateways can freeze all accounting relationships to their issuing address, in case of a major security compromise or for migrating to a new issuing address. @@ -490,9 +490,9 @@
For more information, see the Freeze article.
Authorized Accounts
-The Ripple Consensus Ledger's Authorized Accounts feature enables a gateway to limit who can hold that gateway's issuances, so that unknown Ripple addresses cannot hold the currency the gateway issues. Ripple feels this is not necessary in most cases, since gateways have full control over the process of redeeming Ripple balances for value in the outside world. (You can collect customer information and impose limits on withdrawals at that stage without worrying about what happens within the Ripple Consensus Ledger.)
+The XRP Ledger's Authorized Accounts feature enables a gateway to limit who can hold that gateway's issuances, so that unknown Ripple addresses cannot hold the currency the gateway issues. Ripple feels this is not necessary in most cases, since gateways have full control over the process of redeeming Ripple balances for value in the outside world. (You can collect customer information and impose limits on withdrawals at that stage without worrying about what happens within the Ripple Consensus Ledger.)
To use the Authorized Accounts feature, a gateway enables the
-RequireAuthflag for its issuing address, and then individually approves each accounting relationship. An address can only hold funds issued by a gateway after its accounting relationship with that gateway is approved.The transaction to authorize an accounting relationship must be signed by the issuing address, which unfortunately means an increased risk exposure for that address. The process for sending funds into the Ripple Consensus Ledger with RequireAuth enabled looks like the following:
+The transaction to authorize an accounting relationship 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:
- ACME publishes its issuing address to customers.
- Alice creates an accounting relationship from her Ripple address to ACME's issuing address, indicating that she is willing to hold ACME's issuances. @@ -533,7 +533,7 @@
rippledprovides JSON-RPC and WebSocket APIs that can be used as a low-level interface to all core Ripple functionality.- RippleAPI provides a simplified API for JavaScript applications. @@ -594,7 +594,7 @@
- Some transactions change your balances without being payments directly to or from one of your addresses. For example, if ACME sets a nonzero TransferRate, then ACME's issuing address's outstanding obligations decrease each time Bob and Charlie exchange ACME issuances. See TransferRate for more information.
- Use
rippled'sgateway_balancescommand or RippleAPI'sgetTrustlinesmethod to check your balances.
- - If you have a TransferRate set, then your obligations within the RCL decrease slightly whenever other Ripple addresses transfer your issuances among themselves. +
- If you have a TransferRate set, then your obligations within the XRP Ledger decrease slightly whenever other Ripple addresses transfer your issuances among themselves.
- In
rippled's APIs, you should set theSendMaxtransaction parameter higher than the destinationAmountparameter. - In RippleAPI, you should set the
source.maxAmountparameter higher than thedestination.amountparameter; or, set thesource.amountparameter higher than thedestination.minAmountparameter.
For the gateway's own security as well as the stability of the network, we recommend that each gateway run its own
rippledservers. Ripple (the company) provides detailed and individualized recommendations to businesses interested in running a significant Ripple-based business.Contact partners@ripple.com to see how Ripple can help.
APIs and Middleware
-There are several interfaces you can use to connect to the Ripple Consensus Ledger, depending on your needs and your existing software:
+There are several interfaces you can use to connect to the XRP Ledger, depending on your needs and your existing software:
We recommend making a user interface to generate a destination tag on-demand when a customer intends to send money to the gateway. Then, consider that destination tag valid only for a payment with the expected amount. Later, bounce any other transactions that reuse the same destination tag.
Enable the RequireDest flag on your issuing and operational addresses so that customers must use a destination tag to indicate where funds should go when they send Ripple payments to your gateway.
DisallowXRP
-The DisallowXRP setting (
+disallowIncomingXRPin RippleAPI) is designed to discourage RCL users from sending XRP to an address by accident. This reduces the costs and effort of bouncing undesired payments, if your gateway does not trade XRP. The DisallowXRP flag is not strictly enforced, because doing so could allow addresses to become permanently unusable if they run out of XRP. Client applications should honor the DisallowXRP flag by default.The DisallowXRP setting (
disallowIncomingXRPin RippleAPI) is designed to discourage XRP Ledger users from sending XRP to an address by accident. This reduces the costs and effort of bouncing undesired payments, if your gateway does not trade XRP. The DisallowXRP flag is not strictly enforced, because doing so could allow addresses to become permanently unusable if they run out of XRP. Client applications should honor the DisallowXRP flag by default.An issuing gateway that does not trade XRP should enable the DisallowXRP flag on the gateway's issuing and operational addresses. A private exchange that trades in XRP should only enable the DisallowXRP flag on addresses that are not expected to receive XRP.
The following is an example of using a locally-hosted
rippled'ssubmitcommand to send an AccountSet transaction to enable the DisallowXRP flag:Request:
@@ -639,7 +639,7 @@ }RequireDest
-The
+RequireDestsetting (requireDestinationTagin RippleAPI) is designed to prevent customers from sending payments to your address while accidentally forgetting the destination tag that identifies who should be credited for the payment. When enabled, the Ripple Consensus Ledger rejects any payment to your address that does not specify a destination tag.The
RequireDestsetting (requireDestinationTagin RippleAPI) is designed to prevent customers from sending payments to your address while accidentally forgetting the destination tag that identifies who should be credited for the payment. When enabled, the XRP Ledger rejects any payment to your address that does not specify a destination tag.We recommend enabling the
RequireDestflag on all gateway issuing and operational addresses.The following is an example of using a locally-hosted
rippled'ssubmitcommand to send an AccountSet transaction to enable theRequireDestflag:Request:
@@ -689,7 +689,7 @@ Content-Type: application/jsonThe
RequireAuthsetting (requireAuthorizationin RippleAPI) prevents all counterparties from holding balances issued by an address unless the address has specifically approved an accounting relationship with that counterparty.We recommend always enabling
RequireAuthfor operational addresses and standby addresses, and then never approving any accounting relationships. This prevents operational addresses from creating issuances even by accident. This is a purely precautionary measure, and does not stop those addresses from transferring issuances created by the issuing address, as they are intended to do.If you want to use the Authorized Accounts feature, you must also enable
-RequireAuthon your issuing address. When using Authorized Accounts, your issuing address must submit aTrustSettransaction to approve each accounting relationship that customers create with your issuing address.You can only enable
+RequireAuthif the address owns no accounting relationships (trust lines) and no offers in the Ripple Consensus Ledger, so you must decide whether or not to use it before you start doing business in the RCL.You can only enable
RequireAuthif the address owns no accounting relationships (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.Enabling RequireAuth
The following is an example of using a locally-hosted
rippled'ssubmitcommand to send an AccountSet transaction to enable the RequireAuth flag: (This method works the same way regardless of whether the address is an issuing address, operational address, or standby address.)Request:
@@ -712,7 +712,7 @@ Content-Type: application/jsonCaution: Never submit a secret key to a server you do not control. Do not send a secret key unencrypted over the network.
Authorizing Trust Lines
-If you are using the Authorized Accounts feature, customers cannot hold balances you issue unless you first authorize their accounting relationships to you in the RCL.
+If you are using the Authorized Accounts feature, customers cannot hold balances you issue unless you first authorize their accounting relationships to you in the XRP Ledger.
To authorize an accounting relationship, submit a TrustSet transaction from your issuing address, with the user to trust as the
issuerof theLimitAmount. Leave thevalue(the amount to trust them for) as 0, and enable the tfSetfAuth flag for the transaction.The following is an example of using a locally-hosted
rippled'ssubmitcommand to send a TrustSet transaction authorizing the customer address rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn to hold issuances of USD from the issuing address rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW:Request:
@@ -751,10 +751,10 @@ Content-Type: application/jsonTo make things simpler for your customers, we recommend accepting payments to either operational addresses and issuing addresses.
-As an added precaution, we recommend comparing the balances of your issuing address with the Ripple-backing funds in your internal accounting system as of each new Ripple ledger version. The issuing address's negative balances should match the assets you have allocated to RCL outside the network. If the two do not match up, then you should suspend processing payments into and out of the RCL until you have resolved the discrepancy.
+As an added precaution, we recommend comparing the balances of your issuing address with the Ripple-backing funds in your internal accounting system as of each new Ripple ledger version. The issuing address's negative balances should match the assets you have allocated to XRP Ledger outside the network. If the two do not match up, then you should suspend processing payments into and out of the RCL until you have resolved the discrepancy.
TransferRate
The TransferRate setting (
@@ -805,8 +805,8 @@ Content-Type: application/jsontransferRatein RippleAPI) defines a fee to charge for transferring issuances from one Ripple address to another. See Transfer Fees for more information.
Note: The TransferRate does not apply when sending issuances directly to the issuing address. The issuing address must always accept its issuances at face value in the RCL. This means that customers don't have to pay the TransferRate if they send payments to the issuing address directly, but they do when sending to an operational address. If you accept payments at both addresses, you may want to adjust the amount you credit customers in your system of record when customers send payments to the operational address, to compensate for the TransferRate the customer pays.
-For example: If ACME sets a transfer fee of 1%, a Ripple payment to deliver 5 EUR.ACME from a customer address to ACME's issuing address would cost exactly 5 EUR.ACME. However, the customer would need to send 5.05 EUR.ACME to deliver 5 EUR.ACME to ACME's operational address. (The issuing address's total obligations in the RCL decrease by 0.05 EUR.ACME.) When ACME credits customers for payments to ACME's operational address, ACME credits the customer for the amount delivered to the operational address and the transfer fee, giving the customer €5,05 in ACME's systems.
+Note: The TransferRate does not apply when sending issuances directly to the issuing address. The issuing address must always accept its issuances at face value in the XRP Ledger. This means that customers don't have to pay the TransferRate if they send payments to the issuing address directly, but they do when sending to an operational address. If you accept payments at both addresses, you may want to adjust the amount you credit customers in your system of record when customers send payments to the operational address, to compensate for the TransferRate the customer pays.
+For example: If ACME sets a transfer fee of 1%, a Ripple payment to deliver 5 EUR.ACME from a customer address to ACME's issuing address would cost exactly 5 EUR.ACME. However, the customer would need to send 5.05 EUR.ACME to deliver 5 EUR.ACME to ACME's operational address. (The issuing address's total obligations in the XRP Ledger decrease by 0.05 EUR.ACME.) When ACME credits customers for payments to ACME's operational address, ACME credits the customer for the amount delivered to the operational address and the transfer fee, giving the customer €5,05 in ACME's systems.
Sending Payments to Customers
When you build an automated system to send payments into Ripple for your customers, you must make sure that it constructs payments carefully. Malicious actors are constantly trying to find ways to trick a system into paying them more money than it should.
One common pitfall is performing pathfinding before sending sending a payment to customers in Ripple. If you specify the issuers correctly, the default paths can deliver the currency as intended.
@@ -877,7 +877,7 @@ Content-Type: application/jsonBouncing Payments
When one of your addresses receives a payment whose purpose is unclear, we recommend that you try to return the money to its sender. While this is more work than pocketing the money, it demonstrates good faith towards customers. You can have an operator bounce payments manually, or create a system to do so automatically.
The first requirement to bouncing payments is robustly monitoring for incoming payments. You do not want to accidentally refund a customer for more than they sent you! (This is particularly important if your bounce process is automated.) The Partial Payment Flag Gateway Bulletin (PDF) explains how to avoid a common problem.
-Second, you should send bounced payments as Partial Payments. Since third parties can manipulate the cost of pathways between addresses, Partial Payments allow you to divest yourself of the full amount without being concerned about exchange rates within the Ripple Consensus Ledger. You should publicize your bounced payments policy as part of your terms of use. Send the bounced payment from either an operational address or a standby address.
+Second, you should send bounced payments as Partial Payments. Since third parties can manipulate the cost of pathways between addresses, Partial Payments allow you to divest yourself of the full amount without being concerned about exchange rates within the XRP Ledger. You should publicize your bounced payments policy as part of your terms of use. Send the bounced payment from either an operational address or a standby address.
- To send a Partial Payment using
rippled, enable the tfPartialPayment flag on the transaction. Set theAmountfield to the amount you received and omit theSendMaxfield. - To send a Partial Payment using RippleAPI, set the
allowPartialPaymentfield of the Payment object totrue. Set thesource.maxAmountanddestination.amountboth equal to the amount you received.
diff --git a/tutorial-listing-xrp.html b/tutorial-listing-xrp.html
index dec702b323..28c89a6a3b 100644
--- a/tutorial-listing-xrp.html
+++ b/tutorial-listing-xrp.html
@@ -83,7 +83,7 @@
- - RCL Features + Features
Becoming a Ripple Gateway
-Gateways are the businesses that link the Ripple Consensus Ledger to the rest of the world. An existing online financial institution can expand to act as a gateway in the the Ripple Consensus Ledger (RCL). By becoming a Ripple gateway, a financial services business can gain several advantages:
+Gateways are the businesses that link the XRP Ledger to the rest of the world. An existing online financial institution can expand to act as a gateway in the the Ripple Consensus Ledger (XRP Ledger). By becoming a Ripple gateway, a financial services business can gain several advantages:
-
-
This document explains the concepts and steps necessary to become a Ripple 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 a Ripple gateway.
@@ -212,29 +212,29 @@Ripple Gateways Explained
-Gateways are businesses that provide a way for money and other forms of value to move in and out of the Ripple Consensus Ledger. There are three major models that gateways can follow, with different purposes and modes of operation.
+Gateways are businesses that provide a way for money and other forms of value to move in and out of the XRP Ledger. There are three major models that gateways can follow, with different purposes and modes of operation.
-
-
This guide focuses on running an issuing gateway.
Ripple Trust Lines and Issuances
-All assets in the Ripple Consensus Ledger, except for the native cryptocurrency XRP, are represented as issuances, which are digital balances that represent currency or assets of value held by an issuer. Within the RCL, counterparties can send and trade issuances without requiring intervention from the issuer. Typically, a gateway sends issuances to customers when it receives money in systems and ledgers outside the RCL, and promises to send money to customers in outside systems in exchange for being repaid in issuances in the RCL. Issuances get their value from a gateway's agreement to honor the obligation that the issuances represent. No computer system can force a Ripple gateway to honor that obligation.
-The Ripple Consensus Ledger has a system of directional accounting relationships, called trust lines, to make sure that users only hold issuances from counterparties they trust.
-A "trust line" is link between two addresses in Ripple. A trust line represents an explicit statement of willingness to hold gateway debt obligations. When a customer sends money into the RCL, a gateway takes custody of those assets outside of Ripple, and sends issuances in the RCL to the customer's address. When a customer sends money out of the RCL, she makes a Ripple payment to the gateway, and the gateway credits the customer in its own system of record, or in some other account.
+All assets in the XRP Ledger, except for the native cryptocurrency XRP, are represented as issuances, which are digital balances that represent currency or assets of value held by an issuer. Within the XRP Ledger, counterparties can send and trade issuances without requiring intervention from the issuer. Typically, a gateway sends issuances to customers when it receives money in systems and ledgers outside the RCL, and promises to send money to customers in outside systems in exchange for being repaid in issuances in the RCL. Issuances get their value from a gateway's agreement to honor the obligation that the issuances represent. No computer system can force a Ripple gateway to honor that obligation.
+The XRP Ledger has a system of directional accounting relationships, called trust lines, to make sure that users only hold issuances from counterparties they trust.
+A "trust line" is link between two addresses in Ripple. A trust line represents an explicit statement of willingness to hold gateway debt obligations. When a customer sends money into the XRP Ledger, a gateway takes custody of those assets outside of Ripple, and sends issuances in the RCL to the customer's address. When a customer sends money out of the RCL, she makes a Ripple payment to the gateway, and the gateway credits the customer in its own system of record, or in some other account.
XRP
-XRP is the native cryptocurrency of the Ripple Consensus Ledger. Like issuances, XRP can be freely sent and exchanged among Ripple addresses. Unlike issuances, XRP is not tied to an accounting relationship. XRP can be sent directly from any Ripple address to any other, without going through a gateway or liquidity provider. This helps make XRP a convenient bridge currency. For more information on XRP, see the XRP Portal.
-XRP also serves other purposes in the RCL, in particular as a protective measure against spamming the network. All Ripple addresses need a small amount of XRP to pay the costs of maintaining the Ripple Consensus Ledger. The transaction cost and reserve are neutral fees denoted in XRP and not paid to any party.
+XRP is the native cryptocurrency of the XRP Ledger. Like issuances, XRP can be freely sent and exchanged among Ripple addresses. Unlike issuances, XRP is not tied to an accounting relationship. XRP can be sent directly from any Ripple address to any other, without going through a gateway or liquidity provider. This helps make XRP a convenient bridge currency. For more information on XRP, see the XRP Portal.
+XRP also serves other purposes in the XRP Ledger, in particular as a protective measure against spamming the network. All Ripple addresses need a small amount of XRP to pay the costs of maintaining the XRP Ledger. The transaction cost and reserve are neutral fees denoted in XRP and not paid to any party.
Issuing gateways do not need to accumulate or exchange XRP. They must only hold a small balance of XRP to send transactions through the network. The XRP equivalent of $10 USD should be enough for at least one year of transaction costs for a busy gateway.
Private exchanges and liquidity providers may choose to hold additional XRP for trading. Ripple (the company) does not promote XRP as a speculative investment.
Liquidity and Currency Exchange
-The Ripple Consensus Ledger contains a currency exchange, where any user can place and fulfill bids to exchange XRP and issuances in any combination. Cross-currency payments automatically use the currency exchange to convert currency atomically when the transaction is executed. In this way, users who choose make offers in the distributed exchange provide the liquidity that makes the RCL useful.
+The XRP Ledger contains a currency exchange, where any user can place and fulfill bids to exchange XRP and issuances in any combination. Cross-currency payments automatically use the currency exchange to convert currency atomically when the transaction is executed. In this way, users who choose make offers in the distributed exchange provide the liquidity that makes the XRP Ledger useful.
Currency traders who hold a gateway's issuances can provide liquidity to other popular currencies, without the gateway needing to float a large reserve in various destination currencies. The gateway also does not need to take on the risk of financial exchange. However, a gateway may still want to provide liquidity to XRP or other popular currencies at a baseline rate, especially when the gateway is new to the exchange. If you do provide liquidity, use a different address for trading than your issuing address.
Third-party liquidity providers can use RippleAPI, Ripple Stream, or a third-party client application to access the distributed exchange. Some client applications look up the addresses associated with a gateway using ripple.txt, so it can be helpful to publish a good ripple.txt.
Contact partners@ripple.com for help establishing liquidity between your gateway and others.
Suggested Business Practices
-The value of a gateway's issuances in the Ripple Consensus Ledger comes directly from the trust that customers can redeem them with the gateway when needed. We recommend the following precautions to reduce the risk of business interruptions:
+The value of a gateway's issuances in the XRP Ledger comes directly from the trust that customers can redeem them with the gateway when needed. We recommend the following precautions to reduce the risk of business interruptions:
Hot and Cold Wallets
-In the Ripple Consensus Ledger, financial institutions typically use multiple Ripple 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 Ripple addresses to minimize the risk associated with a compromised secret key. Ripple strongly recommends the following separation of roles:
There are several ways in which a gateway can seek to profit from Ripple integration. These can include:
Choosing Fee Rates
Fees imposed by gateways are optional. Higher fees earn more revenue when a gateway's services are used. On the other hand, high fees discourage customers from using your services. Consider the fees that are charged by other gateways, especially ones issuing similar currencies, as well as traditional payment systems outside of Ripple, such as wire fees. Choosing the right fee structure is a matter of balancing your pricing with what the market is willing to pay.
@@ -396,28 +396,28 @@Sending from Gateway to Ripple
-Ripple payments can automatically bridge between currencies, but an issuing gateway normally only sends single-currency payments that go directly to customers. This means debiting a customer's current balance in your system, and then sending the equivalent amount of issuances in the RCL to the customer's Ripple address.
-An example flow for a payment into the RCL:
+Ripple payments can automatically bridge between currencies, but an issuing gateway normally only sends single-currency payments that go directly to customers. This means debiting a customer's current balance in your system, and then sending the equivalent amount of issuances in the XRP Ledger to the customer's Ripple address.
+An example flow for a payment into the XRP Ledger:
-
-
Assumptions:
-
-
-
Requirements for Sending to RCL
+Requirements for Sending to XRP Ledger
There are several prerequisites that ACME must meet for this to happen:
-
-
In this category:
-
-
Transfer Fees
-The
+TransferRatesetting in the Ripple Consensus Ledger (RCL) allows financial institutions that issue currency in the RCL 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 Ripple Consensus 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.The
TransferRatesetting in the XRP Ledger (XRP Ledger) allows financial institutions that issue currency in the RCL 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 Ripple Consensus 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.XRP never has a transfer fee, because it never has an issuer.
For example, ACME Bank might set the transfer fee to 0.5% for ACME issuances. For the recipient of a payment to get 2 EUR.ACME, the sender must send 2.01 EUR.ACME. After the transaction, ACME's outstanding obligations in Ripple have decreased by 0.01€, which means that ACME no longer needs to hold that amount in the account backing its Ripple issuances.
The following diagram shows a Ripple payment of 2 EUR.ACME from Alice to Charlie with a transfer fee of 1%:
diff --git a/content/concept-accounts.md b/content/concept-accounts.md index 7465a4f423..5db9a2e5f9 100644 --- a/content/concept-accounts.md +++ b/content/concept-accounts.md @@ -1,6 +1,6 @@ -# RCL Accounts +# XRP Ledger Accounts -An "Account" in the Ripple Consensus Ledger represents a holder of XRP and a sender of [transactions](reference-transaction-format.html). The core elements of an account are: +An "Account" in the XRP Ledger represents a holder of XRP and a sender of [transactions](reference-transaction-format.html). The core elements of an account are: - An identifying **address**, such as `rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn` - An **XRP balance**. Some of this XRP is set aside for the [Reserve](concept-reserves.html). @@ -13,21 +13,21 @@ An "Account" in the Ripple Consensus Ledger represents a holder of XRP and a sen In the ledger's data tree, an account's core data is stored in the [AccountRoot](reference-ledger-format.html#accountroot) ledger node type. An account can also be the owner (or partial owner) of several other types of data. -**Tip:** An "Account" in the Ripple Consensus Ledger is somewhere between the financial usage (like "bank account") and the computing usage (like "UNIX account"). Non-XRP currencies and assets aren't stored in an RCL Account itself; each such asset is stored in an accounting relationship called a "Trust Line" that connects two parties. +**Tip:** An "Account" in the XRP Ledger is somewhere between the financial usage (like "bank account") and the computing usage (like "UNIX account"). Non-XRP currencies and assets aren't stored in an XRP Ledger Account itself; each such asset is stored in an accounting relationship called a "Trust Line" that connects two parties. ## Addresses {% include 'data_types/address.md' %} -Any valid address can become an account in the Ripple Consensus Ledger by receiving a [Payment][] of XRP, as long as the amount of XRP delivered is greater than or equal to the [account reserve](concept-reserves.html). This is called _funding_ the account. You can also use an address that has not been funded to represent a [regular key](reference-transaction-format.html#setregularkey) or a member of a [signer list](reference-transaction-format.html#multi-signing). Only a funded account can be the sender of a transaction. +Any valid address can become an account in the XRP Ledger by receiving a [Payment][] of XRP, as long as the amount of XRP delivered is greater than or equal to the [account reserve](concept-reserves.html). This is called _funding_ the account. You can also use an address that has not been funded to represent a [regular key](reference-transaction-format.html#setregularkey) or a member of a [signer list](reference-transaction-format.html#multi-signing). Only a funded account can be the sender of a transaction. -Creating a valid address is a strictly mathematical task starting with a key pair. You can generate a key pair and calculate its address entirely offline without communicating to the Ripple Consensus Ledger or any other party. The conversion from a public key to an address involves a one-way hash function, so it is possible to confirm that a public key matches an address but it is impossible to derive the public key from the address alone. (This is part of the reason why signed transactions include the public key _and_ the address of the sender.) +Creating a valid address is a strictly mathematical task starting with a key pair. You can generate a key pair and calculate its address entirely offline without communicating to the XRP Ledger or any other party. The conversion from a public key to an address involves a one-way hash function, so it is possible to confirm that a public key matches an address but it is impossible to derive the public key from the address alone. (This is part of the reason why signed transactions include the public key _and_ the address of the sender.) For more technical details of how to calculate a Ripple address, see [Address Encoding](#address-encoding). ### Special Addresses -Some addresses have special meaning, or historical uses, in the Ripple Consensus Ledger. In many cases, these are "black hole" addresses, meaning the address is not derived from a known secret key. Since it is effectively impossible to guess a secret key from only an address, any XRP possessed by black hole addresses is lost forever. +Some addresses have special meaning, or historical uses, in the XRP Ledger. In many cases, these are "black hole" addresses, meaning the address is not derived from a known secret key. Since it is effectively impossible to guess a secret key from only an address, any XRP possessed by black hole addresses is lost forever. | Address | Name | Meaning | Black Hole? | |-----------------------------|------|---------|-------------| @@ -40,14 +40,14 @@ Some addresses have special meaning, or historical uses, in the Ripple Consensus ## Permanence of Accounts -Once created, an account exists in the Ripple Consensus Ledger's data tree forever. This is because the current sequence number for a transaction must be tracked forever, so that old transactions cannot be processed a second time. +Once created, an account exists in the XRP Ledger's data tree forever. This is because the current sequence number for a transaction must be tracked forever, so that old transactions cannot be processed a second time. -Unlike Bitcoin and many other crypto-currencies, each new version of the Ripple Consensus Ledger's public ledger chain contains the full state of the ledger, which increases in size with each new account. For that reason, Ripple discourages creating new accounts unless entirely necessary. Institutions who send and receive value on behalf of many users can use [**Source Tags** and **Destination Tags**](tutorial-gateway-guide.html#source-and-destination-tags) to distinguish payments from and to their customers while only using one (or a handful) of accounts in the Ripple Consensus Ledger. +Unlike Bitcoin and many other crypto-currencies, each new version of the XRP Ledger's public ledger chain contains the full state of the ledger, which increases in size with each new account. For that reason, Ripple discourages creating new accounts unless entirely necessary. Institutions who send and receive value on behalf of many users can use [**Source Tags** and **Destination Tags**](tutorial-gateway-guide.html#source-and-destination-tags) to distinguish payments from and to their customers while only using one (or a handful) of accounts in the Ripple Consensus Ledger. ## Transaction History -In the Ripple Consensus Ledger, transaction history is tracked by a "thread" of transactions linked by a transaction's identifying hash and the ledger index. The `AccountRoot` ledger node has the identifying hash and ledger of the transaction that most recently modified it; the metadata of that transaction includes the previous state of the `AccountRoot` node, so it is possible to iterate through the history of a single account this way. This transaction history includes any transactions that modify the `AccountRoot` node directly, including: +In the XRP Ledger, transaction history is tracked by a "thread" of transactions linked by a transaction's identifying hash and the ledger index. The `AccountRoot` ledger node has the identifying hash and ledger of the transaction that most recently modified it; the metadata of that transaction includes the previous state of the `AccountRoot` node, so it is possible to iterate through the history of a single account this way. This transaction history includes any transactions that modify the `AccountRoot` node directly, including: - Transactions sent by the account, because they modify the account's `Sequence` number. These transactions also modify the account's XRP balance because of the [transaction cost](concept-transaction-cost.html). - Transactions that modified the account's XRP balance, including incoming [Payment transactions][] and other types of transactions such as [PaymentChannelClaim][] and [EscrowFinish][]. @@ -66,7 +66,7 @@ For more information on each of these objects, see the [Ledger Format Reference] ## Address Encoding -**Tip:** These technical details are only relevant for people building low-level library software for RCL compatibility! +**Tip:** These technical details are only relevant for people building low-level library software for XRP Ledger compatibility! [[Source]
](https://github.com/ripple/rippled/blob/35fa20a110e3d43ffc1e9e664fc9017b6f2747ae/src/ripple/protocol/impl/AccountID.cpp#L109-L140 "Source") diff --git a/content/concept-amendments.md b/content/concept-amendments.md index a3dfd8c66b..30ce985bc4 100644 --- a/content/concept-amendments.md +++ b/content/concept-amendments.md @@ -13,7 +13,7 @@ Any changes to transaction processing could cause servers to build a different l Amendments solve this problem, so that new features can be enabled only when enough validators support those features. -Users and businesses who rely on the Ripple Consensus Ledger can also use Amendments to provide advance notice of changes in transaction processing that might affect their business. However, API changes that do not impact transaction processing or [the consensus process](https://ripple.com/build/ripple-ledger-consensus-process/) do not need Amendments. +Users and businesses who rely on the XRP Ledger can also use Amendments to provide advance notice of changes in transaction processing that might affect their business. However, API changes that do not impact transaction processing or [the consensus process](https://ripple.com/build/ripple-ledger-consensus-process/) do not need Amendments. ## About Amendments ## @@ -109,7 +109,7 @@ TrustSetAuth # Known Amendments # [[Source]
](https://github.com/ripple/rippled/blob/release/src/ripple/app/main/Amendments.cpp "Source") -The following is a comprehensive list of all known amendments and their status on the production Ripple Consensus Ledger: +The following is a comprehensive list of all known amendments and their status on the production XRP Ledger: | Name | Introduced | Status | |:--------------------------------------|:-----------|:------------------------| @@ -148,7 +148,7 @@ Although this amendment is enabled, it has no effect unless the [SusPay](#suspay |:-----------------------------------------------------------------|:--------| | DC9CA96AEA1DCF83E527D1AFC916EFAF5D27388ECA4060A88817C1238CAEE0BF | Enabled | -Adds sanity checks to transaction processing to ensure that certain conditions are always met. This provides an extra, independent layer of protection against bugs in transaction processing that could otherwise cause exploits and vulnerabilities in the Ripple Consensus Ledger. Ripple expects to add more invariant checks in future versions of `rippled` without additional amendments. +Adds sanity checks to transaction processing to ensure that certain conditions are always met. This provides an extra, independent layer of protection against bugs in transaction processing that could otherwise cause exploits and vulnerabilities in the XRP Ledger. Ripple expects to add more invariant checks in future versions of `rippled` without additional amendments. Introduces two new transaction error codes, `tecINVARIANT_FAILED` and `tefINVARIANT_FAILED`. Changes transaction processing to add the new checks. @@ -169,7 +169,7 @@ Examples of invariant checks: Replaces the [SusPay](#suspay) and [CryptoConditions](#cryptoconditions) amendments. -Provides "suspended payments" for XRP for escrow within the Ripple Consensus Ledger, including support for [Interledger Protocol Crypto-Conditions](https://tools.ietf.org/html/draft-thomas-crypto-conditions-02). Creates a new ledger node type for suspended payments and new transaction types to create, execute, and cancel suspended payments. +Provides "suspended payments" for XRP for escrow within the XRP Ledger, including support for [Interledger Protocol Crypto-Conditions](https://tools.ietf.org/html/draft-thomas-crypto-conditions-02). Creates a new ledger node type for suspended payments and new transaction types to create, execute, and cancel suspended payments. @@ -227,7 +227,7 @@ The Flow Engine also makes it easier to improve and expand the payment engine wi |:-----------------------------------------------------------------|:----------| | 3012E8230864E95A58C60FD61430D7E1B4D3353195F2981DC12B0C7C0950FFAC | Released but not enabled | -Streamlines the offer crossing logic in the RCL's decentralized exchange. Uses the updated code from the [Flow](#flow) amendment to power offer crossing, so [OfferCreate transactions][] and [Payment transactions][] share more code. This has subtle differences in how offers are processed: +Streamlines the offer crossing logic in the XRP Ledger's decentralized exchange. Uses the updated code from the [Flow](#flow) amendment to power offer crossing, so [OfferCreate transactions][] and [Payment transactions][] share more code. This has subtle differences in how offers are processed: - Rounding is slightly different in some cases. - Due to differences in rounding, some combinations of offers may be ranked higher or lower than by the old logic, and taken preferentially. @@ -298,7 +298,7 @@ For more information, see the [Payment Channels Tutorial](tutorial-paychan.html) Changes the hash tree structure that `rippled` uses to represent a ledger. The new structure is more compact and efficient than the previous version. This affects how ledger hashes are calculated, but has no other user-facing consequences. -When this amendment is activated, the Ripple Consensus Ledger will undergo a brief scheduled unavailability while the network calculates the changes to the hash tree structure. +When this amendment is activated, the XRP Ledger will undergo a brief scheduled unavailability while the network calculates the changes to the hash tree structure. ## SusPay @@ -328,7 +328,7 @@ With this amendment enabled, a `TrustSet` transaction with [`tfSetfAuth` enabled Changes the way [Offers](reference-transaction-format.html#lifecycle-of-an-offer) are ranked in order books, so that currency issuers can configure how many significant digits are taken into account when ranking Offers by exchange rate. With this amendment, the exchange rates of Offers are rounded to the configured number of significant digits, so that more Offers have the same exact exchange rate. The intent of this change is to require a meaningful improvement in price to outrank a previous Offer. If used by major issuers, this should reduce the incentive to spam the ledger with Offers that are only a tiny fraction of a percentage point better than existing offers. It may also increase the efficiency of order book storage in the ledger, because Offers can be grouped into fewer exchange rates. -Introduces a `TickSize` field to accounts, which can be set with the [AccountSet transaction type](reference-transaction-format.html#accountset). If a currency issuer sets the `TickSize` field, the Ripple Consensus Ledger truncates the exchange rate (ratio of funds in to funds out) of Offers to trade the issuer's currency, and adjusts the amounts of the Offer to match the truncated exchange rate. If only one currency in the trade has a `TickSize` set, that number of significant digits applies. When trading two currencies that have different `TickSize` values, whichever `TickSize` indicates the fewest significant digits applies. XRP does not have a `TickSize`. +Introduces a `TickSize` field to accounts, which can be set with the [AccountSet transaction type](reference-transaction-format.html#accountset). If a currency issuer sets the `TickSize` field, the XRP Ledger truncates the exchange rate (ratio of funds in to funds out) of Offers to trade the issuer's currency, and adjusts the amounts of the Offer to match the truncated exchange rate. If only one currency in the trade has a `TickSize` set, that number of significant digits applies. When trading two currencies that have different `TickSize` values, whichever `TickSize` indicates the fewest significant digits applies. XRP does not have a `TickSize`. ## Tickets ## diff --git a/content/concept-fees.md b/content/concept-fees.md index b52c05a9c6..18690dea49 100644 --- a/content/concept-fees.md +++ b/content/concept-fees.md @@ -1,8 +1,8 @@ # Fees (Disambiguation) # -The Ripple Consensus Ledger is a decentralized ledger, secured by cryptography and operated by a distributed peer-to-peer network of servers. This means that no one party, not even Ripple, can require a fee for access to the network. +The XRP Ledger is a decentralized ledger, secured by cryptography and operated by a distributed peer-to-peer network of servers. This means that no one party, not even Ripple, can require a fee for access to the network. -However, the rules of the Ripple Consensus Ledger include several types of fees, including neutral fees which protect the ledger against abuse. These neutral fees are not paid to anyone. There are also several optional ways that users can collect fees from each other, both inside and outside the Ripple Consensus Ledger. +However, the rules of the XRP Ledger include several types of fees, including neutral fees which protect the ledger against abuse. These neutral fees are not paid to anyone. There are also several optional ways that users can collect fees from each other, both inside and outside the Ripple Consensus Ledger. ## In the Ledger ## @@ -15,13 +15,13 @@ The _**reserve requirement**_ is a minimum amount of XRP that an account must ho ### Optional Fees ### -_**Transfer fees**_ are optional percentage fees that issuers can charge to transfer the currencies they issue to other addresses within the Ripple Consensus Ledger. See [Transfer Fees](concept-transfer-fees.html) for more information. +_**Transfer fees**_ are optional percentage fees that issuers can charge to transfer the currencies they issue to other addresses within the XRP Ledger. See [Transfer Fees](concept-transfer-fees.html) for more information. _**Trust line quality**_ is a setting that allows an account to value balances on a trust line at higher or lower than face value. This can lead to situations that are like charging a fee. Trust line quality does not apply to XRP, which is not tied to a trust line. ## Outside the Ledger ## -Although the fees described above are the only fees built into the Ripple Consensus Ledger, people can still invent ways to charge fees associated with the ledger. For example, financial institutions commonly charge their customers to send money into and out of the Ripple Consensus Ledger. +Although the fees described above are the only fees built into the XRP Ledger, people can still invent ways to charge fees associated with the ledger. For example, financial institutions commonly charge their customers to send money into and out of the Ripple Consensus Ledger. -Many other fees are also possible. Businesses might charge for access to a client application, maintenance of non-Ripple accounts, exchange services (especially when buying XRP on a private market instead of directly within the Ripple Consensus Ledger) and any number of other services. Always be aware of the fee schedule before doing business with any financial institution. +Many other fees are also possible. Businesses might charge for access to a client application, maintenance of non-Ripple accounts, exchange services (especially when buying XRP on a private market instead of directly within the XRP Ledger) and any number of other services. Always be aware of the fee schedule before doing business with any financial institution. diff --git a/content/concept-freeze.md b/content/concept-freeze.md index b75a68204b..1a862c4126 100644 --- a/content/concept-freeze.md +++ b/content/concept-freeze.md @@ -1,13 +1,13 @@ Freeze Features =============== -The Ripple Consensus Ledger gives addresses the ability to freeze non-XRP balances, which can be useful to meet regulatory requirements, or while investigating suspicious activity. There are three settings related to freezes: +The XRP Ledger gives addresses the ability to freeze non-XRP balances, which can be useful to meet regulatory requirements, or while investigating suspicious activity. 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. -Because no party has a privileged place in the Ripple Consensus Ledger, the freeze feature cannot prevent a counterparty from conducting transactions in XRP or funds issued by other counterparties. No one can freeze XRP. +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. @@ -22,7 +22,7 @@ The **Individual Freeze** feature is a setting on a trust line. When an issuing * 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](reference-transaction-format.html#lifecycle-of-an-offer). -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 operates that are connected to the Ripple Consensus Ledger. (Otherwise, an address might still be able to engage in undesired activity by sending payments through the financial institution.) +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 operates 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](concept-issuing-and-operational-addresses.html), from sending that financial institution's issuances to the individual address. This type of individual freeze has no effect on offers. @@ -40,7 +40,7 @@ The **Global Freeze** feature is a setting on an address. When an issuing addres * 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](reference-transaction-format.html#lifecycle-of-an-offer). -It can be useful to enable Global Freeze on a financial institution's [issuing address](concept-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 Ripple Consensus Ledger, a financial institution should also suspend activities in its connectors to outside systems. +It can be useful to enable Global Freeze on a financial institution's [issuing address](concept-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](concept-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. @@ -57,7 +57,7 @@ The **No Freeze** feature is a setting on an address that permanently gives up t * 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 Ripple Consensus Ledger cannot force a financial institution to honor the obligations that its issued funds represent, so giving up the ability to enable a Global Freeze cannot protect customers. However, giving up the ability to _disable_ a Global Freeze ensures that the Global Freeze feature is not used unfairly against some customers. +The XRP Ledger cannot force a financial institution to honor the obligations that its issued funds represent, so giving up the ability to enable a Global Freeze cannot protect customers. However, giving up the ability to _disable_ a Global Freeze ensures that the Global Freeze feature is not used unfairly against some customers. 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. diff --git a/content/concept-issuing-and-operational-addresses.md b/content/concept-issuing-and-operational-addresses.md index ffe7a8250d..ae02a9d8d3 100644 --- a/content/concept-issuing-and-operational-addresses.md +++ b/content/concept-issuing-and-operational-addresses.md @@ -4,19 +4,19 @@ ## Funds Lifecycle ## -All non-XRP currency balances (issuances) in the Ripple Consensus Ledger (RCL) are tied to accounting relationships between two Ripple addresses. When a financial institution uses Ripple's recommended separation of roles, funds relating to that institution tend to flow in a cycle. +All non-XRP currency balances (issuances) in the XRP Ledger (XRP Ledger) are tied to accounting relationships between two Ripple addresses. When a financial institution uses Ripple's recommended separation of roles, funds relating to that institution tend to flow in a cycle. [](img/funds_flow_diagram.png) -When the issuing address sends payments, it creates balances in the accounting relationships in the Ripple Consensus Ledger. Within the RCL, users can exchange balances across different accounting relationships, so we use the term _issuances_ to describe any non-XRP balance. Issuances have negative value from the perspective of the issuing address, since they represent obligations. The same issuances 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 issuances that were sent. +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 _issuances_ to describe any non-XRP balance. Issuances have negative value from the perspective of the issuing address, since they represent obligations. The same issuances 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 issuances that were sent. -The issuing address sends issuances to a standby address, or directly to an operational address. The standby addresses send those issuances to operational addresses. Operational addresses send payments to other counterparties, such as liquidity providers, partners, and other customers. Because all issuances are tied to accounting relationships with the issuing address, payments and exchanges of issuances "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 Ripple Consensus Ledger also supports more complicated [paths](concept-paths.html) that connect multiple issuers through order books and [liquidity providers who allow their funds to ripple](concept-noripple.html). +The issuing address sends issuances to a standby address, or directly to an operational address. The standby addresses send those issuances to operational addresses. Operational addresses send payments to other counterparties, such as liquidity providers, partners, and other customers. Because all issuances are tied to accounting relationships with the issuing address, payments and exchanges of issuances "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](concept-paths.html) that connect multiple issuers through order books and [liquidity providers who allow their funds to ripple](concept-noripple.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 Ripple Consensus Ledger are public, automated systems can monitor for payments to the issuing address without needing a secret key. +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 ### @@ -24,7 +24,7 @@ If a malicious actor learns the secret key behind a institution's issuing addres ### Multiple Issuing Addresses ### -A financial institution can issue more than one currency in the Ripple Consensus 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](concept-transfer-fees.html) and the [global freeze](concept-freeze.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. +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](concept-transfer-fees.html) and the [global freeze](concept-freeze.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 ## diff --git a/content/concept-noripple.md b/content/concept-noripple.md index 8b63043c54..9537478dc3 100644 --- a/content/concept-noripple.md +++ b/content/concept-noripple.md @@ -1,6 +1,6 @@ # Understanding the NoRipple Flag # -In the Ripple Consensus Ledger (RCL), the "NoRipple" flag is a setting on a trust line. When an address enables the NoRipple flag on two trust lines, payments from third parties cannot "ripple" through that address on those trust lines. This protects liquidity providers from having balances shift unexpectedly between different issuers of the same currency. +In the XRP Ledger (XRP Ledger), the "NoRipple" flag is a setting on a trust line. When an address enables the NoRipple flag on two trust lines, payments from third parties cannot "ripple" through that address on those trust lines. This protects liquidity providers from having balances shift unexpectedly between different issuers of the same currency. ## Background ## @@ -12,7 +12,7 @@ If Bob wants to pay $3 to Charlie, then he could say, "Alice, take $3 of the mon  -We call this process, where two addresses pay each other by adjusting the balances of trust lines in between them, "rippling". This is a useful and important feature of the Ripple Consensus Ledger. Rippling occurs when addresses are linked by trust lines that use the same [currency code](reference-rippled.html#currency-codes). The issuer does not need to be the same: in fact, larger chains always involve changing issuers. +We call this process, where two addresses pay each other by adjusting the balances of trust lines in between them, "rippling". This is a useful and important feature of the XRP Ledger. Rippling occurs when addresses are linked by trust lines that use the same [currency code](reference-rippled.html#currency-codes). The issuer does not need to be the same: in fact, larger chains always involve changing issuers. ## Justification ## diff --git a/content/concept-partial-payments.md b/content/concept-partial-payments.md index 707358057a..0c72c8d5c2 100644 --- a/content/concept-partial-payments.md +++ b/content/concept-partial-payments.md @@ -1,10 +1,10 @@ # Partial Payments -In the default case, the `Amount` field of a [Payment transaction][] in the Ripple Consensus Ledger specifies the exact amount to deliver, after charging for exchange rates and [transfer fees](concept-transfer-fees.html). The "Partial Payment" flag ([**tfPartialPayment**](reference-transaction-format.html#payment-flags)) allows a payment to succeed by reducing the amount received instead of increasing the amount sent. Partial payments are useful for [returning payments](tutorial-gateway-guide.html#bouncing-payments) without incurring additional costs to oneself. +In the default case, the `Amount` field of a [Payment transaction][] in the XRP Ledger specifies the exact amount to deliver, after charging for exchange rates and [transfer fees](concept-transfer-fees.html). The "Partial Payment" flag ([**tfPartialPayment**](reference-transaction-format.html#payment-flags)) allows a payment to succeed by reducing the amount received instead of increasing the amount sent. Partial payments are useful for [returning payments](tutorial-gateway-guide.html#bouncing-payments) without incurring additional costs to oneself. The amount of XRP used for the [transaction cost](concept-transaction-cost.html) is always deducted from the sender’s account, regardless of the type of transaction. -Partial payments can be used to exploit naive integrations with the Ripple Consensus Ledger to steal money from exchanges and gateways. The [Partial Payments Exploit](#partial-payments-exploit) section of this document describes how this exploit works and how you can avoid it. +Partial payments can be used to exploit naive integrations with the XRP Ledger to steal money from exchanges and gateways. The [Partial Payments Exploit](#partial-payments-exploit) section of this document describes how this exploit works and how you can avoid it. ## Semantics @@ -16,7 +16,7 @@ In other words: Amount + (fees) = (sent amount) ≤ SendMax -In this formula, "fees" refers to [transfer fees](concept-transfer-fees.html) and currency exchange rates. The "sent amount" and the delivered amount (`Amount`) may be denominated in different currencies and converted by consuming Offers in the Ripple Consensus Ledger's decentralized exchange. +In this formula, "fees" refers to [transfer fees](concept-transfer-fees.html) and currency exchange rates. The "sent amount" and the delivered amount (`Amount`) may be denominated in different currencies and converted by consuming Offers in the XRP Ledger's decentralized exchange. **Note:** The `Fee` field of the transaction refers to the XRP [transaction cost](concept-transaction-cost.html), which is destroyed to relay the transaction to the network. The exact transaction cost specified is always debited from the sender and is completely separate from the fee calculations for any type of payment. @@ -68,7 +68,7 @@ You can find the `delivered_amount` field in the following places: ## Partial Payments Exploit -If a financial institution's integration with the Ripple Consensus Ledger assumes that the `Amount` field of a Payment is always the full amount delivered, malicious actors may be able to exploit that assumption to steal money from the institution. This exploit can be used against gateways, exchanges, or merchants as long as those institutions' software does not process partial payments correctly. +If a financial institution's integration with the XRP Ledger assumes that the `Amount` field of a Payment is always the full amount delivered, malicious actors may be able to exploit that assumption to steal money from the institution. This exploit can be used against gateways, exchanges, or merchants as long as those institutions' software does not process partial payments correctly. **The correct way to process incoming Payment transactions is to use [the `delivered_amount` metadata field](#the-delivered-amount-field),** not the `Amount` field. This way, an institution is never mistaken about how much it _actually_ received. @@ -80,10 +80,10 @@ To exploit a vulnerable financial institution, a malicious actor does something 1. The malicious actor sends a Payment transaction to the institution. This transaction has a large `Amount` field and has the **tfPartialPayment** flag enabled. 2. The partial payment succeeds (result code `tesSUCCESS`) but actually delivers a very small amount of the currency specified. 3. The vulnerable institution reads the transaction's `Amount` field without looking at the `Flags` field or `delivered_amount` metadata field. -4. The vulnerable institution credits the malicious actor in an external system, such as the institution's own ledger, for the full `Amount`, despite only receiving a much smaller `delivered_amount` in the Ripple Consensus Ledger. +4. The vulnerable institution credits the malicious actor in an external system, such as the institution's own ledger, for the full `Amount`, despite only receiving a much smaller `delivered_amount` in the XRP Ledger. 5. The malicious actor withdraws as much of the balance as possible to another system before the vulnerable institution notices the discrepancy. - Malicious actors usually prefer to convert the balance to another crypto-currency such as Bitcoin, because blockchain transactions are usually irreversible. With a withdrawal to a fiat currency system, the financial institution may be able to reverse or cancel the transaction several days after it initially executes. - - In the case of an exchange, the malicious actor can also withdraw an XRP balance directly back into the Ripple Consensus Ledger. + - In the case of an exchange, the malicious actor can also withdraw an XRP balance directly back into the XRP Ledger. In the case of a merchant, the order of operations is slightly different, but the concept is the same: @@ -92,14 +92,14 @@ In the case of a merchant, the order of operations is slightly different, but th 3. The malicious actor sends a Payment transaction to the merchant. This transaction has a large `Amount` field and has the **tfPartialPayment** flag enabled. 4. The partial payment succeeds (result code `tesSUCCESS`) but delivers only a very small amount of the currency specified. 5. The vulnerable merchant reads the transaction's `Amount` field without looking at the `Flags` field or `delivered_amount` metadata field. -6. The vulnerable merchant treats the invoice as paid and provides the goods or services to the malicious actor, despite only receiving a much smaller `delivered_amount` in the Ripple Consensus Ledger. +6. The vulnerable merchant treats the invoice as paid and provides the goods or services to the malicious actor, despite only receiving a much smaller `delivered_amount` in the XRP Ledger. 7. The malicious actor uses, resells, or absconds with the goods and services before the merchant notices the discrepancy. ### Further Mitigations Using [the `delivered_amount` field](#the-delivered-amount-field) when processing incoming transactions is sufficient to avoid this exploit. Still, additional proactive business practices can also avoid or mitigate the likelihood of this and similar exploits. For example: -- Add additional sanity checks to your business logic for processing withdrawals. Never process a withdrawal if the total balance you hold in the Ripple Consensus Ledger does not match your expected assets and obligations. +- Add additional sanity checks to your business logic for processing withdrawals. Never process a withdrawal if the total balance you hold in the XRP Ledger does not match your expected assets and obligations. - Follow "Know Your Customer" guidelines and strictly verify your customers' identities. You may be able to recognize and block malicious users in advance, or pursue legal action against a malicious actor who exploits your system. {% include 'snippets/tx-type-links.md' %} diff --git a/content/concept-paths.md b/content/concept-paths.md index f839144fdd..da912f7f52 100644 --- a/content/concept-paths.md +++ b/content/concept-paths.md @@ -1,8 +1,8 @@ # Paths # -In the Ripple Consensus Ledger, paths define a way for payments to flow through intermediary steps on their way from sender to receiver. Paths enable cross-currency payments by connecting sender and receiver through order books. Paths also enable complex settlement of offsetting debts. +In the XRP Ledger, paths define a way for payments to flow through intermediary steps on their way from sender to receiver. Paths enable cross-currency payments by connecting sender and receiver through order books. Paths also enable complex settlement of offsetting debts. -A single Payment transaction in the Ripple Consensus 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. The paths in a path set must start and end with the same currency. Since XRP can be sent directly to any address, an XRP-to-XRP transaction does not use any paths. diff --git a/content/concept-reserves.md b/content/concept-reserves.md index 0fd0f56c70..2b1e08ef23 100644 --- a/content/concept-reserves.md +++ b/content/concept-reserves.md @@ -1,6 +1,6 @@ # Reserves # -The Ripple Consensus Ledger applies _reserve requirements_, in XRP, to protect the shared global ledger from growing excessively large as the result of spam or malicious usage. The goal is to constrain the growth of the ledger to match improvements in technology so that a current commodity-level machine can always fit the current ledger in RAM and the full ledger history on disk. +The XRP Ledger applies _reserve requirements_, in XRP, to protect the shared global ledger from growing excessively large as the result of spam or malicious usage. The goal is to constrain the growth of the ledger to match improvements in technology so that a current commodity-level machine can always fit the current ledger in RAM and the full ledger history on disk. To submit transactions, an address must hold a minimum amount of XRP in the shared global ledger. You cannot send this XRP to other addresses. To fund a new address, you must send enough XRP to meet the reserve requirement. @@ -27,7 +27,7 @@ Many objects in the ledger are owned by a particular address, and count toward t #### Owner Reserve Edge Cases #### -The Ripple Consensus Ledger considers an [OfferCreate transaction][] to be an explicit statement of willingness to hold an asset. Consuming the offer automatically creates a trust line (with limit 0, and a balance above that limit) for the `taker_pays` currency if such a trust line does not exist. However, if the offer's owner does not hold enough XRP to also meet the owner reserve requirement of the new trust line, the offer is considered unfunded. See also: [Lifecycle of an Offer](reference-transaction-format.html#lifecycle-of-an-offer). +The XRP Ledger considers an [OfferCreate transaction][] to be an explicit statement of willingness to hold an asset. Consuming the offer automatically creates a trust line (with limit 0, and a balance above that limit) for the `taker_pays` currency if such a trust line does not exist. However, if the offer's owner does not hold enough XRP to also meet the owner reserve requirement of the new trust line, the offer is considered unfunded. See also: [Lifecycle of an Offer](reference-transaction-format.html#lifecycle-of-an-offer). @@ -41,6 +41,6 @@ When an address holds less XRP than its current reserve requirement, it cannot s ## Changing the Reserve Requirements ## -The Ripple Consensus Ledger has a mechanism to adjust the reserve requirements for long-term changes in the value of XRP. Any changes have to be approved by the consensus process. See [Fee Voting](concept-fee-voting.html) for more information. +The XRP Ledger has a mechanism to adjust the reserve requirements for long-term changes in the value of XRP. Any changes have to be approved by the consensus process. See [Fee Voting](concept-fee-voting.html) for more information. {% include 'snippets/tx-type-links.md' %} diff --git a/content/concept-stand-alone-mode.md b/content/concept-stand-alone-mode.md index 27cf054c12..42639fee0e 100644 --- a/content/concept-stand-alone-mode.md +++ b/content/concept-stand-alone-mode.md @@ -13,7 +13,7 @@ When you run `rippled` in stand-alone mode, you have to tell it what ledger vers New Genesis Ledger ------------------------------------------------------------------------------- -In stand-alone mode, you can have `rippled` create a new genesis ledger. This provides a known state, with none of the ledger history from the production Ripple Consensus Ledger. (This is very useful for unit tests, among other things.) +In stand-alone mode, you can have `rippled` create a new genesis ledger. This provides a known state, with none of the ledger history from the production XRP Ledger. (This is very useful for unit tests, among other things.) * To start `rippled` in stand-alone mode with a new genesis ledger, use the [`-a`](https://wiki.ripple.com/Rippled#--standalone.2C_-a) and [`--start`](https://wiki.ripple.com/Rippled#--start) options: diff --git a/content/concept-transaction-cost.md b/content/concept-transaction-cost.md index 0419de5769..d1c2c16a8d 100644 --- a/content/concept-transaction-cost.md +++ b/content/concept-transaction-cost.md @@ -1,6 +1,6 @@ # Transaction Cost # -To protect the Ripple Consensus Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of [XRP](https://ripple.com/xrp-portal/). This _transaction cost_ is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network. +To protect the XRP Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of [XRP](https://ripple.com/xrp-portal/). This _transaction cost_ is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network. Every transaction must [specify how much XRP to destroy](#specifying-the-transaction-cost) to pay the transaction cost. @@ -130,7 +130,7 @@ The [`server_state` command](reference-rippled.html#server-state) returns a dire Every signed transaction must include the transaction cost in the [`Fee` field](reference-transaction-format.html#common-fields). Like all fields of a signed transaction, this field cannot be changed without invalidating the signature. -As a rule, the Ripple Consensus Ledger executes transactions _exactly_ as they are signed. (To do anything else would be difficult to coordinate across a decentralized consensus network, at the least.) As a consequence of this, every transaction destroys the exact amount of XRP specified by the `Fee` field, even if the specified amount is much more than the current minimum transaction cost for any part of the network. The transaction cost can even destroy XRP that would otherwise be set aside for an account's [reserve requirement](concept-reserves.html). +As a rule, the XRP Ledger executes transactions _exactly_ as they are signed. (To do anything else would be difficult to coordinate across a decentralized consensus network, at the least.) As a consequence of this, every transaction destroys the exact amount of XRP specified by the `Fee` field, even if the specified amount is much more than the current minimum transaction cost for any part of the network. The transaction cost can even destroy XRP that would otherwise be set aside for an account's [reserve requirement](concept-reserves.html). Before signing a transaction, we recommend [looking up the current load-based transaction cost](#querying-the-transaction-cost). If the transaction cost is high due to load scaling, you may want to wait for it to decrease. If you do not plan on submitting the transaction immediately, we recommend specifying a slightly higher transaction cost to account for future load-based fluctuations in the transaction cost. @@ -176,6 +176,6 @@ When the [FeeEscalation amendment](concept-amendments.html#feeescalation) is ena ## Changing the Transaction Cost ## -The Ripple Consensus Ledger has a mechanism for changing the minimum transaction cost to account for long-term changes in the value of XRP. Any changes have to be approved by the consensus process. See [Fee Voting](concept-fee-voting.html) for more information. +The XRP Ledger has a mechanism for changing the minimum transaction cost to account for long-term changes in the value of XRP. Any changes have to be approved by the consensus process. See [Fee Voting](concept-fee-voting.html) for more information. {% include 'snippets/rippled_versions.md' %} diff --git a/content/concept-transfer-fees.md b/content/concept-transfer-fees.md index e86d0b3961..ed95ded320 100644 --- a/content/concept-transfer-fees.md +++ b/content/concept-transfer-fees.md @@ -1,6 +1,6 @@ # Transfer Fees # -The `TransferRate` setting in the Ripple Consensus Ledger (RCL) allows [financial institutions that issue currency in the RCL](tutorial-gateway-guide.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 Ripple Consensus 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. +The `TransferRate` setting in the XRP Ledger (XRP Ledger) allows [financial institutions that issue currency in the RCL](tutorial-gateway-guide.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 Ripple Consensus 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. [operational address]: concept-issuing-and-operational-addresses.html [issuing address]: concept-issuing-and-operational-addresses.html diff --git a/content/data_types/account_sequence.md b/content/data_types/account_sequence.md index 8a5d198904..5f49e6bbbb 100644 --- a/content/data_types/account_sequence.md +++ b/content/data_types/account_sequence.md @@ -1,5 +1,5 @@ A Sequence number is a 32-bit unsigned integer used to identify a transaction or Offer relative to a specific account. -Every [account object in the Ripple Consensus Ledger](reference-ledger-format.html#accountroot) has a Sequence number, which starts at 1. For a transaction to be relayed to the network and possibly included in a validated ledger, it must have a `Sequence` field that matches the sending account's current `Sequence` number. An account's Sequence field is incremented whenever a transaction from that account is included in a validated ledger (regardless of whether the transaction succeeded or failed). This preserves the order of transactions submitted by an account, and differentiates transactions that would otherwise be the same. +Every [account object in the XRP Ledger](reference-ledger-format.html#accountroot) has a Sequence number, which starts at 1. For a transaction to be relayed to the network and possibly included in a validated ledger, it must have a `Sequence` field that matches the sending account's current `Sequence` number. An account's Sequence field is incremented whenever a transaction from that account is included in a validated ledger (regardless of whether the transaction succeeded or failed). This preserves the order of transactions submitted by an account, and differentiates transactions that would otherwise be the same. -Every [Offer node in the Ripple Consensus Ledger](reference-ledger-format.html#offer) is marked with the sending `Account` [Address][] and the `Sequence` value of the [OfferCreate transaction](reference-transaction-format.html#offercreate) that created it. These two fields, together, uniquely identify the Offer. +Every [Offer node in the XRP Ledger](reference-ledger-format.html#offer) is marked with the sending `Account` [Address][] and the `Sequence` value of the [OfferCreate transaction](reference-transaction-format.html#offercreate) that created it. These two fields, together, uniquely identify the Offer. diff --git a/content/data_types/address.md b/content/data_types/address.md index 59a44d0c63..8d623bdd5a 100644 --- a/content/data_types/address.md +++ b/content/data_types/address.md @@ -1,4 +1,4 @@ -Accounts in the RCL are identified by a base58 Ripple Address. The address is derived from the account's master [public key](https://en.wikipedia.org/wiki/Public-key_cryptography), which is in turn derived from a secret key. An address is represented as a string in JSON and has the following characteristics: +Accounts in the XRP Ledger are identified by a base58 Ripple Address. The address is derived from the account's master [public key](https://en.wikipedia.org/wiki/Public-key_cryptography), which is in turn derived from a secret key. An address is represented as a string in JSON and has the following characteristics: * Between 25 and 35 characters in length * Starts with the character `r` diff --git a/content/data_types/currency_code.md b/content/data_types/currency_code.md index c7b50d21cc..930fb6ce1d 100644 --- a/content/data_types/currency_code.md +++ b/content/data_types/currency_code.md @@ -1,4 +1,4 @@ -There are two kinds of currency code in the Ripple Consensus Ledger: +There are two kinds of currency code in the XRP Ledger: * Three-character currency code. We recommend using all-uppercase [ISO 4217 Currency Codes](http://www.xe.com/iso4217.php). 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. * 160-bit hexadecimal values, such as `0158415500000000C1F76FF6ECB0BAC600000000`, according to Ripple's internal [Currency Format](https://wiki.ripple.com/Currency_format). This representation is uncommon. diff --git a/content/data_types/public_key.md b/content/data_types/public_key.md index f0ecf5570a..8ea25a8297 100644 --- a/content/data_types/public_key.md +++ b/content/data_types/public_key.md @@ -1,4 +1,4 @@ -The Ripple Consensus Ledger (RCL) uses public keys to verify cryptographic signatures in several places: +The XRP Ledger (XRP Ledger) uses public keys to verify cryptographic signatures in several places: * To authorize transactions, a public key is attached to the transaction. The public key must be mathematically associated with the sending Ripple address or the sender's regular key address. * To secure peer-to-peer communications between `rippled` servers. This uses a "node public key" that the server generates randomly when it starts with an empty database. diff --git a/content/exchange-guide.md b/content/exchange-guide.md index ebec688c3d..62b97bb670 100644 --- a/content/exchange-guide.md +++ b/content/exchange-guide.md @@ -1,6 +1,6 @@ # Listing XRP as an Exchange -This document describes the steps that an exchange needs to take to list XRP. For details about other aspects of `rippled` and the Ripple Consensus Ledger (RCL), see the [Ripple Developer Center](https://ripple.com/build). +This document describes the steps that an exchange needs to take to list XRP. For details about other aspects of `rippled` and the XRP Ledger (XRP Ledger), see the [Ripple Developer Center](https://ripple.com/build). ## Alpha Exchange @@ -18,9 +18,9 @@ For illustrative purposes, this document uses a fictitious business called _Alph Alpha Exchange wants to list BTC/XRP and XRP/USD trading pairs partially because listing these pairs will benefit its users. Specifically, this support will allow its users to: -* Deposit XRP _to_ Alpha Exchange _from_ the RCL +* Deposit XRP _to_ Alpha Exchange _from_ the XRP Ledger -* Withdraw XRP _from_ Alpha Exchange _to_ the RCL +* Withdraw XRP _from_ Alpha Exchange _to_ the XRP Ledger * Trade XRP with other currencies, such as BTC, USD, amongst others @@ -36,17 +36,17 @@ See also: * [Gateway Compliance](https://ripple.com/build/gateway-guide/#gateway-compliance) — Gateways and exchanges are different, but exchanges should also ensure that they are complying with local regulations and reporting to the appropriate agencies. -* [Requirements for Sending to RCL](https://ripple.com/build/gateway-guide/#requirements-for-sending-to-rcl) +* [Requirements for Sending to XRP Ledger](https://ripple.com/build/gateway-guide/#requirements-for-sending-to-rcl) -* [Requirements for Receiving from RCL](https://ripple.com/build/gateway-guide/#requirements-for-receiving-from-rcl) +* [Requirements for Receiving from XRP Ledger](https://ripple.com/build/gateway-guide/#requirements-for-receiving-from-rcl) * [Gateway Precautions](https://ripple.com/build/gateway-guide/#precautions) ### Accounts -XRP is held in *accounts* (sometimes referred to as *wallets* ) on the Ripple Consensus Ledger (RCL). Accounts on the RCL are different than accounts on other blockchain ledgers, such as Bitcoin, where accounts incur little to no overhead. To submit transactions (for example, [OfferCreate](https://ripple.com/build/transactions/#offercreate) and others used for trading), RCL accounts require XRP [reserves](https://ripple.com/build/reserves/) to protect the ledger against spam and malicious usage. On other blockchains, balances are derived from the previous block. On the RCL, [account objects](https://ripple.com/build/ledger-format/#accountroot) describe several other properties of the account in addition to balances, so accounts are represented in each ledger and can never be destroyed or removed. Exchanges do not need to create accounts for each customer that holds XRP; they can store all of their customers’ XRP in just a few RCL accounts. For more information about RCL accounts, see the [Accounts](https://ripple.com/build/accounts/) article. +XRP is held in *accounts* (sometimes referred to as *wallets* ) on the XRP Ledger (XRP Ledger). Accounts on the RCL are different than accounts on other blockchain ledgers, such as Bitcoin, where accounts incur little to no overhead. To submit transactions (for example, [OfferCreate](https://ripple.com/build/transactions/#offercreate) and others used for trading), RCL accounts require XRP [reserves](https://ripple.com/build/reserves/) to protect the ledger against spam and malicious usage. On other blockchains, balances are derived from the previous block. On the RCL, [account objects](https://ripple.com/build/ledger-format/#accountroot) describe several other properties of the account in addition to balances, so accounts are represented in each ledger and can never be destroyed or removed. Exchanges do not need to create accounts for each customer that holds XRP; they can store all of their customers’ XRP in just a few RCL accounts. For more information about RCL accounts, see the [Accounts](https://ripple.com/build/accounts/) article. -To comply with Ripple's recommend best practices, Alpha Exchange should create at least two new [accounts](https://ripple.com/build/accounts/) on the RCL. To minimize the risks associated with a compromised secret key, Ripple recommends creating [_issuing_, _operational_, and _standby_ accounts](https://ripple.com/build/issuing-operational-addresses/) (these are sometimes referred to, respectively, as cold, hot, and warm wallets). The operational/standby/issuing model is intended to balance security and convenience. Exchanges listing XRP should create the following accounts: +To comply with Ripple's recommend best practices, Alpha Exchange should create at least two new [accounts](https://ripple.com/build/accounts/) on the XRP Ledger. To minimize the risks associated with a compromised secret key, Ripple recommends creating [_issuing_, _operational_, and _standby_ accounts](https://ripple.com/build/issuing-operational-addresses/) (these are sometimes referred to, respectively, as cold, hot, and warm wallets). The operational/standby/issuing model is intended to balance security and convenience. Exchanges listing XRP should create the following accounts: * An [_issuing_ account](https://ripple.com/build/issuing-operational-addresses/#issuing-address) to securely hold the majority of XRP and customers' funds. To provide optimal security, this account should be offline. @@ -75,7 +75,7 @@ See also: Alpha Exchange will custody its customers' XRP, so it needs to track each customer's balance(s). To do this, Alpha Exchange must create and maintain an additional balance sheet. The following table illustrates what this balance sheet might look like. -The new RCL accounts (_Alpha Operational_, _Alpha Standby_, _Alpha Issuing_) are in the *User* column of the *XRP Balances on RCL* table. +The new XRP Ledger accounts (_Alpha Operational_, _Alpha Standby_, _Alpha Issuing_) are in the *User* column of the *XRP Balances on RCL* table. The *Alpha Exchange XRP Balances* table represents new, additional balance sheet. Alpha Exchange’s software manages their users’ balances of XRP on this accounting system. @@ -83,7 +83,7 @@ The *Alpha Exchange XRP Balances* table represents new, additional balance sheetXRP Balances -on RCL +on XRP LedgerAlpha Exchange @@ -159,7 +159,7 @@ XRP Balances #### XRP Amounts -Amounts of XRP are represented on the RCL as an unsigned integer count of *drops*, where one XRP == 1,000,000 drops. Ripple recommends that software store XRP balances as integer amounts of drops, and perform integer arithmetic on these values. However, user interfaces should present balances in units of XRP. +Amounts of XRP are represented on the XRP Ledger as an unsigned integer count of *drops*, where one XRP == 1,000,000 drops. Ripple recommends that software store XRP balances as integer amounts of drops, and perform integer arithmetic on these values. However, user interfaces should present balances in units of XRP. One drop (.000001 XRP) cannot be further subdivided. Bear this in mind when calculating and displaying FX rates between XRP and other assets. @@ -169,7 +169,7 @@ For more informtion, see [Specifying Currency Amounts](https://ripple.com/build/ With exchanges like _Alpha Exchange_, XRP can be "on-ledger" or "off-ledger": -* **On-Ledger XRP**: XRP that can be queried through the public RCL by specifying the public [address](https://ripple.com/build/accounts/#addresses) of the XRP holder. The counterparty to these balances is the RCL. For more information, see [Currencies](https://ripple.com/build/rippled-apis/#currencies). +* **On-Ledger XRP**: XRP that can be queried through the public XRP Ledger by specifying the public [address](https://ripple.com/build/accounts/#addresses) of the XRP holder. The counterparty to these balances is the RCL. For more information, see [Currencies](https://ripple.com/build/rippled-apis/#currencies). * **Off-Ledger XRP**: XRP that is held by the accounting system of an exchange and can be queried through the exchange interface. Off-ledger XRP balances are credit-based. The counterparty is the exchange holding the XRP. @@ -193,13 +193,13 @@ There are four main steps involved in an exchange's typical flow of funds: This list does not include the [prerequisites](#prerequisites-for-supporting-xrp) required of an exchange. -At this point, _Alpha Exchange_ has created [operational, standby, and issuing accounts](#accounts) on the RCL and added them to its balance sheet, but has not accepted any deposits from its users. +At this point, _Alpha Exchange_ has created [operational, standby, and issuing accounts](#accounts) on the XRP Ledger and added them to its balance sheet, but has not accepted any deposits from its users.XRP Balances -on RCL +on XRP LedgerAlpha Exchange @@ -293,7 +293,7 @@ A user named Charlie wants to deposit 50,000 XRP to Alpha Exchange. Doing this i XRP Balances -on RCL +on XRP LedgerAlpha Exchange @@ -381,16 +381,16 @@ XRP Balances ### Trade XRP on The Exchange -Alpha Exchange users (like Charlie) can trade credit-based balances on Alpha Exchange. Alpha Exchange should keep track of user balances on its new balance sheet as these trades are made. These trades are _off-ledger_ and independent from the RCL, so the balance changes are not recorded there. +Alpha Exchange users (like Charlie) can trade credit-based balances on Alpha Exchange. Alpha Exchange should keep track of user balances on its new balance sheet as these trades are made. These trades are _off-ledger_ and independent from the XRP Ledger, so the balance changes are not recorded there. -For more information about trading _on_ the RCL, see [Lifecycle of an Offer](https://ripple.com/build/transactions/#lifecycle-of-an-offer). +For more information about trading _on_ the XRP Ledger, see [Lifecycle of an Offer](https://ripple.com/build/transactions/#lifecycle-of-an-offer). ### Rebalance XRP Holdings -Exchanges can adjust the balances between their operational and issuing accounts at any time. Each balance adjustment consumes a [transaction fee](https://ripple.com/build/fees-disambiguation/), but does not otherwise affect the aggregate balance of all the accounts. The aggregate, on-ledger balance should always exceed the total balance available for trade on the exchange. (The excess should be sufficient to cover the RCL's [transaction fees](https://ripple.com/build/transaction-cost/).) +Exchanges can adjust the balances between their operational and issuing accounts at any time. Each balance adjustment consumes a [transaction fee](https://ripple.com/build/fees-disambiguation/), but does not otherwise affect the aggregate balance of all the accounts. The aggregate, on-ledger balance should always exceed the total balance available for trade on the exchange. (The excess should be sufficient to cover the XRP Ledger's [transaction fees](https://ripple.com/build/transaction-cost/).) -The following table demonstrates a balance adjustment of 80,000 XRP (via a [_payment_](https://ripple.com/build/transactions/#payment) on the RCL) between Alpha Exchange's issuing account and its operational account, where the issuing account was debited and the operational account was credited. If the payment were reversed (debit the operational account and credit the issuing account), the operational account balance would decrease. Balance adjustments like these allow an exchange to limit the risks associated with holding XRP in online operational accounts. +The following table demonstrates a balance adjustment of 80,000 XRP (via a [_payment_](https://ripple.com/build/transactions/#payment) on the XRP Ledger) between Alpha Exchange's issuing account and its operational account, where the issuing account was debited and the operational account was credited. If the payment were reversed (debit the operational account and credit the issuing account), the operational account balance would decrease. Balance adjustments like these allow an exchange to limit the risks associated with holding XRP in online operational accounts.@@ -408,7 +408,7 @@ Off-Ledger Balances
User Balance - RCL Account +XRP Ledger Account Balance @@ -466,22 +466,22 @@ Off-Ledger Balances ### Withdraw XRP from Exchange -Withdrawals allow an exchange's users to move XRP from the exchange's off-ledger balance sheet to an account on the RCL. +Withdrawals allow an exchange's users to move XRP from the exchange's off-ledger balance sheet to an account on the XRP Ledger. In this example, Charlie withdraws 25,000 XRP from Alpha Exchange. This involves the following steps: -1. Charlie initiates the process on Alpha Exchange’s website. He provides instructions to transfer 25,000 XRP to a specific account on the RCL (named "Charlie RCL" in the following table). +1. Charlie initiates the process on Alpha Exchange’s website. He provides instructions to transfer 25,000 XRP to a specific account on the XRP Ledger (named "Charlie RCL" in the following table). 2. In response to Charlie’s instructions, Alpha Exchange does the following: a. Debits the amount (25,000 XRP) from Charlie’s account on its off-ledger balance sheet - b. Submits a payment on the RCL for the same amount (25,000 XRP), from Alpha Exchange's operational account to Charlie’s RCL account + b. Submits a payment on the XRP Ledger for the same amount (25,000 XRP), from Alpha Exchange's operational account to Charlie’s RCL account - RCL On-Ledger XRP Balances +XRP Ledger On-Ledger XRP Balances Alpha Exchange XRP @@ -500,7 +500,7 @@ Off-Ledger Balances User Balance - RCL Account +XRP Ledger Account Balance @@ -538,7 +538,7 @@ Off-Ledger Balances - Charlie RCL +Charlie XRP Ledger 50,000
75,000diff --git a/content/reference-data-api.md b/content/reference-data-api.md index 9811b859aa..765f647fe8 100644 --- a/content/reference-data-api.md +++ b/content/reference-data-api.md @@ -1,7 +1,7 @@ Ripple Data API v2 ================== -The Ripple Data API v2 provides access to information about changes in the Ripple Consensus Ledger, including transaction history and processed analytical data. This information is stored in a dedicated database, which frees `rippled` servers to keep fewer historical ledger versions. The Data API v2 also acts as data source for applications such as [Ripple Charts](https://www.ripplecharts.com/) and [ripple.com](https://www.ripple.com). +The Ripple Data API v2 provides access to information about changes in the XRP Ledger, including transaction history and processed analytical data. This information is stored in a dedicated database, which frees `rippled` servers to keep fewer historical ledger versions. The Data API v2 also acts as data source for applications such as [Ripple Charts](https://www.ripplecharts.com/) and [ripple.com](https://www.ripple.com). Ripple provides a live instance of the Data API with as complete a transaction record as possible at the following address: @@ -1175,7 +1175,7 @@ Response (trimmed for size): ## Get Stats ## [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/stats.js "Source") -Retrieve statistics about transaction activity in the Ripple Consensus Ledger, divided into intervals of time. +Retrieve statistics about transaction activity in the XRP Ledger, divided into intervals of time. #### Request Format #### @@ -2027,7 +2027,7 @@ Response: ## Get Top Currencies ## [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/topCurrencies.js "Source") -Returns the top currencies on the Ripple Consensus Ledger, ordered from highest rank to lowest. The ranking is determined by the volume and count of transactions and the number of unique counterparties. By default, returns results for the 30-day rolling window ending on the current date. You can specify a date to get results for the 30-day window ending on that date. _(New in [v2.1.0][])_ +Returns the top currencies on the XRP Ledger, ordered from highest rank to lowest. The ranking is determined by the volume and count of transactions and the number of unique counterparties. By default, returns results for the 30-day rolling window ending on the current date. You can specify a date to get results for the 30-day window ending on that date. _(New in [v2.1.0][])_ #### Request Format #### @@ -2130,7 +2130,7 @@ Response: ## Get Top Markets ## [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/topMarkets.js "Source") -Returns the top exchange markets on the Ripple Consensus Ledger, ordered from highest rank to lowest. The rank is determined by the number and volume of exchanges and the number of counterparties participating. By default, returns top markets for the 30-day rolling window ending on the current date. You can specify a date to get results for the 30-day window ending on that date. _(New in [v2.1.0][])_ +Returns the top exchange markets on the XRP Ledger, ordered from highest rank to lowest. The rank is determined by the number and volume of exchanges and the number of counterparties participating. By default, returns top markets for the 30-day rolling window ending on the current date. You can specify a date to get results for the 30-day window ending on that date. _(New in [v2.1.0][])_ #### Request Format #### @@ -3506,7 +3506,7 @@ Content-Type: image/svg+xml ## Get Accounts ## [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/accounts.js "Source") -Retrieve information about the creation of new accounts in the Ripple Consensus Ledger. +Retrieve information about the creation of new accounts in the XRP Ledger. #### Request Format #### @@ -3914,7 +3914,7 @@ Optionally, you can provide the following query parameters: | `limit` | Integer | Maximum results per page. Defaults to 20. Cannot be more than 1,000. | | `marker` | String | [Pagination](#pagination) key from previously returned response. | -**Note:** This method cannot return CSV format; only JSON results are supported for raw RCL transactions. +**Note:** This method cannot return CSV format; only JSON results are supported for raw XRP Ledger transactions. #### Response Format #### @@ -5113,7 +5113,7 @@ Due to a mishap early in Ripple's history, ledgers 1 through 32569 were lost. Th ## Account Creation Objects ## -An account creation object represents the action of creating an account in the Ripple Consensus Ledger. There are two variations, depending on whether the account was already present in ledger 32570, the earliest ledger available. Accounts that were already present in ledger 32570 are termed _genesis accounts_. +An account creation object represents the action of creating an account in the XRP Ledger. There are two variations, depending on whether the account was already present in ledger 32570, the earliest ledger available. Accounts that were already present in ledger 32570 are termed _genesis accounts_. | Field | Value | Description | |-------|-------|-------------| @@ -5130,7 +5130,7 @@ An account creation object represents the action of creating an account in the R ## Exchange Objects ## [Exchange Objects]: #exchange-objects -An exchange object represents an actual exchange of currency, which can occur in the Ripple Consensus Ledger as the result of executing either an OfferCreate transaction or a Payment transaction. In order for currency to actually change hands, there must be a previously-unfilled Offer previously placed in the ledger with an OfferCreate transaction. +An exchange object represents an actual exchange of currency, which can occur in the XRP Ledger as the result of executing either an OfferCreate transaction or a Payment transaction. In order for currency to actually change hands, there must be a previously-unfilled Offer previously placed in the ledger with an OfferCreate transaction. A single transaction can cause several exchanges to occur. In this case, the sender of the transaction is the taker for all the exchanges, but each exchange has a different provider, currency pair, or both. diff --git a/content/reference-ledger-format.md b/content/reference-ledger-format.md index 8c11f2d078..06863b5a8c 100644 --- a/content/reference-ledger-format.md +++ b/content/reference-ledger-format.md @@ -1,6 +1,6 @@ # The Ledger # -The Ripple Consensus Ledger is a shared, global ledger that is open to all. Individual participants can trust the integrity of the ledger without having to trust any single institution to manage it. The `rippled` server software accomplishes this by managing a ledger database that can only be updated according to very specific rules. Each instance of `rippled` keeps a full copy of the ledger, and the peer-to-peer network of `rippled` servers distributes candidate transactions among themselves. The consensus process determines which transactions get applied to each new version of the ledger. See also: [The Consensus Process](https://ripple.com/build/ripple-ledger-consensus-process/). +The XRP Ledger is a shared, global ledger that is open to all. Individual participants can trust the integrity of the ledger without having to trust any single institution to manage it. The `rippled` server software accomplishes this by managing a ledger database that can only be updated according to very specific rules. Each instance of `rippled` keeps a full copy of the ledger, and the peer-to-peer network of `rippled` servers distributes candidate transactions among themselves. The consensus process determines which transactions get applied to each new version of the ledger. See also: [The Consensus Process](https://ripple.com/build/ripple-ledger-consensus-process/).  diff --git a/content/reference-rippled.md b/content/reference-rippled.md index f527b45090..ed3a83a9b0 100755 --- a/content/reference-rippled.md +++ b/content/reference-rippled.md @@ -1,6 +1,6 @@ # rippled # -The core peer-to-peer server that manages the Ripple Consensus Ledger (RCL) is called `rippled`. Each `rippled` server connects to a network of peers, relays cryptographically signed transactions, and maintains a local copy of the complete shared global ledger. The source code for `rippled` is written in C++, and is [available on GitHub under an open-source license](https://github.com/ripple/rippled). +The core peer-to-peer server that manages the XRP Ledger (XRP Ledger) is called `rippled`. Each `rippled` server connects to a network of peers, relays cryptographically signed transactions, and maintains a local copy of the complete shared global ledger. The source code for `rippled` is written in C++, and is [available on GitHub under an open-source license](https://github.com/ripple/rippled). * [`rippled` Setup](tutorial-rippled-setup.html) * [API Reference](#api-methods) @@ -36,7 +36,7 @@ The [example config file](https://github.com/ripple/rippled/blob/release/doc/rip ### WebSocket API ### -If you are looking to try out some methods on the Ripple Consensus Ledger, you can skip writing your own WebSocket code and go straight to using the API at the [Ripple WebSocket API Tool](ripple-api-tool.html). Later on, when you want to connect to your own `rippled` server, you can [build your own client in the browser](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications) or [in Node.js](https://www.npmjs.com/package/ws). +If you are looking to try out some methods on the XRP Ledger, you can skip writing your own WebSocket code and go straight to using the API at the [Ripple WebSocket API Tool](ripple-api-tool.html). Later on, when you want to connect to your own `rippled` server, you can [build your own client in the browser](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications) or [in Node.js](https://www.npmjs.com/package/ws). #### Request Formatting #### @@ -399,7 +399,7 @@ If you do not specify a ledger, the `current` (in-progress) ledger is chosen by ## Currencies ## -There are two kinds of currencies in the Ripple Consensus Ledger: XRP, and everything else. There are many differences between the two: +There are two kinds of currencies in the XRP Ledger: XRP, and everything else. There are many differences between the two: | `XRP` | Issued Currencies | |:----------------------------------------------------------------|:-----------| @@ -499,7 +499,7 @@ The format of the `marker` field is intentionally undefined. Each server can def ## Modifying the Ledger ## -All changes to the Ripple Consensus Ledger (RCL) happen as the result of transactions. The only API methods that can change the contents of the RCL are the [`submit` command](#submit) and the [`submit_multisigned` command](#submit-multisigned). Most other methods represent different ways to view the data represented in the RCL. The remaining commands generate data for your convenience. (The [`wallet_propose`](#wallet-propose), [`path_find`](#path-find), and [`random`](#random) commands fall into this category.) +All changes to the XRP Ledger (XRP Ledger) happen as the result of transactions. The only API methods that can change the contents of the RCL are the [`submit` command](#submit) and the [`submit_multisigned` command](#submit-multisigned). Most other methods represent different ways to view the data represented in the RCL. The remaining commands generate data for your convenience. (The [`wallet_propose`](#wallet-propose), [`path_find`](#path-find), and [`random`](#random) commands fall into this category.) For more information on the various transactions you can submit, see the [Transaction Format](reference-transaction-format.html). @@ -587,7 +587,7 @@ You can use the `rippled` application (as a separate instance) as a JSON-RPC cli # Account Information # -An "Account" in the Ripple Consensus Ledger represents a holder of XRP and a sender of transactions. Accounts can send and receive XRP and issued assets, participate in the decentralized exchange, and change their own settings. Creating an account involves generating keys and then receiving XRP from another account. For more information, see [Accounts](concept-accounts.html). +An "Account" in the XRP Ledger represents a holder of XRP and a sender of transactions. Accounts can send and receive XRP and issued assets, participate in the decentralized exchange, and change their own settings. Creating an account involves generating keys and then receiving XRP from another account. For more information, see [Accounts](concept-accounts.html). ## account_currencies ## @@ -3125,7 +3125,7 @@ The response follows the [standard format](#response-formatting), with a success ## wallet_propose ## [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/WalletPropose.cpp "Source") -Use the `wallet_propose` method to generate a key pair and Ripple [address]. This command only generates keys, and does not affect the Ripple Consensus Ledger itself in any way. To become a funded address stored in the ledger, the address must [receive a Payment transaction](reference-transaction-format.html#creating-accounts) that provides enough XRP to meet the [reserve requirement](concept-reserves.html). +Use the `wallet_propose` method to generate a key pair and Ripple [address]. This command only generates keys, and does not affect the XRP Ledger itself in any way. To become a funded address stored in the ledger, the address must [receive a Payment transaction](reference-transaction-format.html#creating-accounts) that provides enough XRP to meet the [reserve requirement](concept-reserves.html). *The `wallet_propose` request is an [admin command](#connecting-to-rippled) that cannot be run by unprivileged users!* (This command is restricted to protect against people sniffing network traffic for account secrets, since admin commands are not usually transmitted over the outside network.) @@ -3951,7 +3951,7 @@ The format of each object in the `state` array depends on whether `binary` was s ## ledger_entry ## [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/LedgerEntry.cpp "Source") -The `ledger_entry` method returns a single ledger node from the Ripple Consensus Ledger in its raw format. See [ledger format][] for information on the different types of objects you can retrieve. +The `ledger_entry` method returns a single ledger node from the XRP Ledger in its raw format. See [ledger format][] for information on the different types of objects you can retrieve. **Note:** There is no commandline version of this method. You can use the [`json` command](#json) to access this method from the commandline instead. @@ -6691,9 +6691,9 @@ The server automatically tries to fill in certain fields in `tx_json` (the [Tran * `Sequence` - The server automatically uses the next Sequence number from the sender's account information. * **Caution:** The next sequence number for the account is not incremented until this transaction is applied. If you sign multiple transactions without submitting and waiting for the response to each one, you must manually provide the correct sequence numbers for each transaction after the first. -* `Fee` - If you omit the `Fee` parameter, the server tries to fill in an appropriate transaction cost automatically. On the production Ripple Consensus Ledger, this fails with `rpcHIGH_FEE` unless you provide an appropriate `fee_mult_max` value. - * The `fee_mult_max` and `fee_div_max` parameters limit how high the automatically-provided transaction cost can be, in terms of the load-scaling multiplier that gets applied to the [reference transaction cost](concept-transaction-cost.html#reference-transaction-cost). The default settings return an error if the automatically-provided value would use greater than a 10× multiplier. However, the production Ripple Consensus Ledger [typically has a 1000× load multiplier](concept-transaction-cost.html#current-transaction-cost). - * The commandline syntax does not support `fee_mult_max` and `fee_div_max`. For the production Ripple Consensus Ledger, you must provide a `Fee` value. +* `Fee` - If you omit the `Fee` parameter, the server tries to fill in an appropriate transaction cost automatically. On the production XRP Ledger, this fails with `rpcHIGH_FEE` unless you provide an appropriate `fee_mult_max` value. + * The `fee_mult_max` and `fee_div_max` parameters limit how high the automatically-provided transaction cost can be, in terms of the load-scaling multiplier that gets applied to the [reference transaction cost](concept-transaction-cost.html#reference-transaction-cost). The default settings return an error if the automatically-provided value would use greater than a 10× multiplier. However, the production XRP Ledger [typically has a 1000× load multiplier](concept-transaction-cost.html#current-transaction-cost). + * The commandline syntax does not support `fee_mult_max` and `fee_div_max`. For the production XRP Ledger, you must provide a `Fee` value. * **Caution:** A malicious server can specify an excessively high transaction cost, ignoring the values of `fee_mult_max` and `fee_div_max`. * `Paths` - For Payment-type transactions (excluding XRP-to-XRP transfers), the Paths field can be automatically filled, as if you did a [ripple_path_find](#ripple-path-find). Only filled if `build_path` is provided. @@ -11737,11 +11737,11 @@ The response follows the [standard format](#response-formatting), with a success # Peer Protocol # -Servers in the Ripple Consensus Ledger communicate to each other using the Ripple peer protocol, also known as RTXP. Peer servers connect via HTTPS and then perform an [HTTP upgrade](https://tools.ietf.org/html/rfc7230#section-6.7) to RTXP. (For more information, see the [Overlay Network](https://github.com/ripple/rippled/blob/906ef761bab95f80b0a7e0cab3b4c594b226cf57/src/ripple/overlay/README.md#handshake) article in the [`rippled` repository](https://github.com/ripple/rippled).) +Servers in the XRP Ledger communicate to each other using the Ripple peer protocol, also known as RTXP. Peer servers connect via HTTPS and then perform an [HTTP upgrade](https://tools.ietf.org/html/rfc7230#section-6.7) to RTXP. (For more information, see the [Overlay Network](https://github.com/ripple/rippled/blob/906ef761bab95f80b0a7e0cab3b4c594b226cf57/src/ripple/overlay/README.md#handshake) article in the [`rippled` repository](https://github.com/ripple/rippled).) ## Configuring the Peer Protocol ## -In order to participate in the Ripple Consensus Ledger, `rippled` servers connects to arbitrary peers using the peer protocol. (All such peers are treated as untrusted, unless they are [clustered](tutorial-rippled-setup.html#clustering) with the current server.) +In order to participate in the XRP Ledger, `rippled` servers connects to arbitrary peers using the peer protocol. (All such peers are treated as untrusted, unless they are [clustered](tutorial-rippled-setup.html#clustering) with the current server.) Ideally, the server should be able to send _and_ receive connections on the peer port. You should forward the port used for the peer protocol through your firewall to the `rippled` server. The [default `rippled` configuration file](https://github.com/ripple/rippled/blob/develop/doc/rippled-example.cfg) listens for incoming peer protocol connections on port 51235 on all network interfaces. You can change the port used by editing the appropriate stanza in your `rippled.cfg` file. diff --git a/content/reference-transaction-format.md b/content/reference-transaction-format.md index 8c9716966a..73b84e0bad 100644 --- a/content/reference-transaction-format.md +++ b/content/reference-transaction-format.md @@ -11,7 +11,7 @@ A _Transaction_ is the only way to modify the Ripple Ledger. Transactions are on ## Authorizing Transactions ## -In the decentralized Ripple Consensus Ledger, a digital signature proves that a transaction is authorized to do a specific set of actions. Only signed transactions can be submitted to the network and included in a validated ledger. A signed transaction is immutable: its contents cannot change, and the signature is not valid for any other transaction. +In the decentralized XRP Ledger, a digital signature proves that a transaction is authorized to do a specific set of actions. Only signed transactions can be submitted to the network and included in a validated ledger. A signed transaction is immutable: its contents cannot change, and the signature is not valid for any other transaction. A transaction can be authorized by any of the following types of signatures: @@ -27,7 +27,7 @@ Any signature type can authorize any type of transaction, with the following exc ## Signing and Submitting Transactions ## -Sending a transaction to the Ripple Consensus Ledger involves several steps: +Sending a transaction to the XRP Ledger involves several steps: 1. Create an [unsigned transaction in JSON format](#unsigned-transaction-format). 2. Use one or more signatures to [authorize the transaction](#authorizing-transactions). @@ -56,7 +56,7 @@ Here is an example of an unsigned [Payment transaction][] in JSON: } ``` -The Ripple Consensus Ledger only relays and executes a transaction if the transaction object has been authorized by the sending address (in the `Account`) field. For transactions authorized by only a single signature, you have two options: +The XRP Ledger only relays and executes a transaction if the transaction object has been authorized by the sending address (in the `Account`) field. For transactions authorized by only a single signature, you have two options: 1. Convert it to a binary blob and sign it offline. This is preferable, since it means that the account secret used for signing the transaction is never transmitted over any network connection. * You can use [RippleAPI](reference-rippleapi.html#sign) for offline signing. @@ -170,7 +170,7 @@ Example response from the `tx` command: ### Multi-Signing ### -Multi-signing in Ripple is the act of [authorizing transactions](#authorizing-transactions) for the Ripple Consensus Ledger by using a combination of multiple secret keys. You can have any combination of authorization methods enabled for your address, including multi-signing, a master key, and a [regular key](#setregularkey). (The only requirement is that _at least one_ method must be enabled.) +Multi-signing in Ripple is the act of [authorizing transactions](#authorizing-transactions) for the XRP Ledger by using a combination of multiple secret keys. You can have any combination of authorization methods enabled for your address, including multi-signing, a master key, and a [regular key](#setregularkey). (The only requirement is that _at least one_ method must be enabled.) The [SignerListSet transaction][] defines which addresses can authorize transactions from your address. You can include up to 8 addresses in a SignerList. You can control how many signatures are needed, in which combinations, by using the quorum and weight values of the SignerList. @@ -255,7 +255,7 @@ The [`Paths` field](#paths) of the [Payment](#payment) transaction type can also ### Transaction Cost ### -To protect the Ripple Consensus Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of XRP. This _[transaction cost](concept-transaction-cost.html)_ is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network. +To protect the XRP Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of XRP. This _[transaction cost](concept-transaction-cost.html)_ is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network. The `Fee` field specifies an amount, in [drops of XRP][Currency Amount], to destroy as the cost for relaying this transaction. If the transaction is included in a validated ledger (whether or not it achieves its intended purpose), then the amount of XRP specified in the `Fee` parameter is destroyed forever. You can [look up the transaction cost](concept-transaction-cost.html#querying-the-transaction-cost) in advance, or [let `rippled` set it automatically](concept-transaction-cost.html#automatically-specifying-the-transaction-cost) when you sign a transaction. @@ -385,7 +385,7 @@ _Pseudo-Transactions_ that are not created and submitted in the usual way, but m [[Source]
](https://github.com/ripple/rippled/blob/f65cea66ef99b1de149c02c15f06de6c61abf360/src/ripple/app/transactors/SetAccount.cpp "Source") -An AccountSet transaction modifies the properties of an [account in the Ripple Consensus Ledger](reference-ledger-format.html#accountroot). +An AccountSet transaction modifies the properties of an [account in the XRP Ledger](reference-ledger-format.html#accountroot). Example AccountSet: @@ -590,7 +590,7 @@ Any account may submit an EscrowFinish transaction. [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/CancelOffer.cpp "Source") -An OfferCancel transaction removes an Offer node from the Ripple Consensus Ledger. +An OfferCancel transaction removes an Offer node from the XRP Ledger. ``` { @@ -618,7 +618,7 @@ The OfferCancel method returns [tesSUCCESS](#transaction-results) even if it did [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/CreateOffer.cpp "Source") -An OfferCreate transaction is effectively a [limit order](http://en.wikipedia.org/wiki/limit_order). It defines an intent to exchange currencies, and creates an Offer node in the Ripple Consensus Ledger if not completely fulfilled when placed. Offers can be partially fulfilled. +An OfferCreate transaction is effectively a [limit order](http://en.wikipedia.org/wiki/limit_order). It defines an intent to exchange currencies, and creates an Offer node in the XRP Ledger if not completely fulfilled when placed. Offers can be partially fulfilled. ``` { @@ -697,7 +697,7 @@ _Requires the [TickSize amendment](concept-amendments.html#ticksize)._ 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. -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 a number of significant digits plus an exponent; the `TickSize` does not affect the exponent. This allows the Ripple Consensus Ledger to represent exchange rates between assets that vary greatly in value (for example, a hyperinflated 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. +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 a number of significant digits plus 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 hyperinflated 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. The `TickSize` does not affect the portion of an Offer that can be executed immediately. (For that reason, OfferCreate transactions with `tfImmediateOrCancel` are unaffected by `TickSize` values.) If the Offer cannot be fully executed, the transaction processing engine calculates the exchange rate and truncates it based on `TickSize`. Then, the engine rounds the remaining amount of the Offer from the "less important" side to match the truncated exchange rate. For a default OfferCreate transaction (a "buy" Offer), the `TakerPays` amount (the amount being bought) gets rounded. If the `tfSell` flag is enabled (a "sell" Offer) the `TakerGets` amount (the amount being sold) gets rounded. @@ -716,7 +716,7 @@ If an OfferCreate transaction has an `Expiration` time that has already passed w ### Auto-Bridging ### -Any OfferCreate that would exchange two non-XRP currencies could potentially use XRP as an intermediary currency in a synthetic order book. This is because of auto-bridging, which serves to improve liquidity across all currency pairs by using XRP as a vehicle currency. This works because of XRP's nature as a native cryptocurrency to the Ripple Consensus Ledger. Offer execution can use a combination of direct and auto-bridged offers to achieve the best total exchange rate. +Any OfferCreate that would exchange two non-XRP currencies could potentially use XRP as an intermediary currency in a synthetic order book. This is because of auto-bridging, which serves to improve liquidity across all currency pairs by using XRP as a vehicle currency. This works because of XRP's nature as a native cryptocurrency to the XRP Ledger. Offer execution can use a combination of direct and auto-bridged offers to achieve the best total exchange rate. Example: _Anita places an offer to sell GBP and buy BRL. She might fund that this uncommon currency market has few offers. There is one offer with a good rate, but it has insufficient quantity to satisfy Anita's trade. However, both GBP and BRL have active, competitive markets to XRP. Auto-bridging software finds a way to complete Anita's offer by purchasing XRP with GBP from one trader, then selling the XRP to another trader to buy BRL. Anita automatically gets the best rate possible by combining the small offer in the direct GBP:BRL market with the better composite rates created by pairing GBP:XRP and XRP:BRL offers._ @@ -785,7 +785,7 @@ Most of the time, the `issuer` field of a non-XRP [Currency Amount][] indicates ### Creating Accounts ### -The Payment transaction type is the only way to create new accounts in the Ripple Consensus Ledger. To do so, send an amount of XRP that is equal or greater than the [account reserve](concept-reserves.html) to a mathematically-valid account address that does not exist yet. When the Payment is processed, a new [AccountRoot node](reference-ledger-format.html#accountroot) is added to the ledger. +The Payment transaction type is the only way to create new accounts in the XRP Ledger. To do so, send an amount of XRP that is equal or greater than the [account reserve](concept-reserves.html) to a mathematically-valid account address that does not exist yet. When the Payment is processed, a new [AccountRoot node](reference-ledger-format.html#accountroot) is added to the ledger. If you send an insufficient amount of XRP, or any other currency, the Payment fails. @@ -1079,9 +1079,9 @@ Create or modify a trust line linking two accounts. ### Trust Limits ### -All balances on the Ripple Consensus Ledger (RCL), except for XRP, represent value owed in the world outside the Ripple Ledger. The address that issues those funds in Ripple (identified by the `issuer` field of the `LimitAmount` object) is expected to pay the balance back, outside of the Ripple Consensus Ledger, when users redeem their Ripple balances by returning them to the issuer. +All balances on the XRP Ledger (XRP Ledger), except for XRP, represent value owed in the world outside the Ripple Ledger. The address that issues those funds in Ripple (identified by the `issuer` field of the `LimitAmount` object) is expected to pay the balance back, outside of the Ripple Consensus Ledger, when users redeem their Ripple balances by returning them to the issuer. -Since a computer program cannot force a someone to keep a promise and not default in real life, trust lines represent a way of configuring how much you trust an issuer to hold on your behalf. Since a large, reputable financial institution is more likely to be able to pay you back than, say, your broke roommate, you can set different limits on each trust line, to indicate the maximum amount you are willing to let the issuer "owe" you in the RCL. If the issuer defaults or goes out of business, you can lose up to that much money because the balances you hold in the Ripple Consensus Ledger can no longer be exchanged for equivalent balances elsewhere. (You can still keep or trade the issuances in the RCL, but they no longer have any reason to be worth anything.) +Since a computer program cannot force a someone to keep a promise and not default in real life, trust lines represent a way of configuring how much you trust an issuer to hold on your behalf. Since a large, reputable financial institution is more likely to be able to pay you back than, say, your broke roommate, you can set different limits on each trust line, to indicate the maximum amount you are willing to let the issuer "owe" you in the XRP Ledger. If the issuer defaults or goes out of business, you can lose up to that much money because the balances you hold in the XRP Ledger can no longer be exchanged for equivalent balances elsewhere. (You can still keep or trade the issuances in the RCL, but they no longer have any reason to be worth anything.) There are two cases where you can hold a balance on a trust line that is *greater* than your limit: when you acquire more of that currency through [trading](#offercreate), or when you decrease the limit on your trust line. @@ -1271,7 +1271,7 @@ Any other transaction result is potentially not final. In that case, the transac ## Understanding Transaction Metadata ## -The metadata section of a transaction includes detailed information about all the changes to the shared Ripple Consensus Ledger that the transaction caused. This is true of any transaction that gets included in a ledger, whether or not it is successful. Naturally, the changes are only final if the transaction is validated. +The metadata section of a transaction includes detailed information about all the changes to the shared XRP Ledger that the transaction caused. This is true of any transaction that gets included in a ledger, whether or not it is successful. Naturally, the changes are only final if the transaction is validated. Some fields that may appear in transaction metadata include: diff --git a/content/snippets/gateways-intro.md b/content/snippets/gateways-intro.md index a10c6ac9f8..697e4965a4 100644 --- a/content/snippets/gateways-intro.md +++ b/content/snippets/gateways-intro.md @@ -1,5 +1,5 @@ -Gateways are businesses that provide a way for money and other forms of value to move in and out of the Ripple Consensus Ledger. There are three major models that gateways can follow, with different purposes and modes of operation. +Gateways are businesses that provide a way for money and other forms of value to move in and out of the XRP Ledger. There are three major models that gateways can follow, with different purposes and modes of operation. -* An **Issuing Gateway** receives money (or other assets of value) outside of Ripple, and creates issuances in the Ripple Consensus Ledger. This provides a direct way for customers to get money in and out of the RCL. All currencies in the Ripple Consensus Ledger, except for XRP, take the form of issuances tied to a specific issuing gateway. -* A **Private Exchange** holds XRP and lets its customers buy and sell that XRP in its own system. Most cryptocurrencies rely on private exchanges to provide a market for the cryptocurrency, but the Ripple Consensus Ledger has a currency exchange built into the protocol itself. -* **Merchants** accept payment within the Ripple Consensus Ledger in exchange for goods and services in the outside world. Currently, Ripple does not have widespread support for merchant operations. +* An **Issuing Gateway** receives money (or other assets of value) outside of Ripple, and creates issuances in the XRP Ledger. This provides a direct way for customers to get money in and out of the XRP Ledger. All currencies in the Ripple Consensus Ledger, except for XRP, take the form of issuances tied to a specific issuing gateway. +* A **Private Exchange** holds XRP and lets its customers buy and sell that XRP in its own system. Most cryptocurrencies rely on private exchanges to provide a market for the cryptocurrency, but the XRP Ledger has a currency exchange built into the protocol itself. +* **Merchants** accept payment within the XRP Ledger in exchange for goods and services in the outside world. Currently, Ripple does not have widespread support for merchant operations. diff --git a/content/snippets/issuing-and-operational-addresses-intro.md b/content/snippets/issuing-and-operational-addresses-intro.md index 6c82fcbc53..0b4dc9a831 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 Ripple Consensus Ledger, financial institutions typically use multiple Ripple 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 Ripple addresses to minimize the risk associated with a compromised secret key. Ripple strongly recommends the following separation of roles: * 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/tutorial-escrow.md b/content/tutorial-escrow.md index 3474fd9f65..66f07e885f 100644 --- a/content/tutorial-escrow.md +++ b/content/tutorial-escrow.md @@ -1,6 +1,6 @@ # Escrow Tutorials -The Ripple Consensus Ledger supports held payments that can be executed only after a certain time has passed or a cryptographic condition has been fulfilled. You can use these simple features to build publicly-provable smart contracts. This article explains basic tasks relating to held payments. +The XRP Ledger supports held payments that can be executed only after a certain time has passed or a cryptographic condition has been fulfilled. You can use these simple features to build publicly-provable smart contracts. This article explains basic tasks relating to held payments. - Send a time-held payment - Send a conditionally-held payment diff --git a/content/tutorial-gateway-guide.md b/content/tutorial-gateway-guide.md index 47959105e8..9255630fe2 100644 --- a/content/tutorial-gateway-guide.md +++ b/content/tutorial-gateway-guide.md @@ -1,9 +1,9 @@ # Becoming a Ripple Gateway # -**Gateways** are the businesses that link the Ripple Consensus Ledger to the rest of the world. An existing online financial institution can expand to act as a gateway in the the Ripple Consensus Ledger (RCL). By becoming a Ripple gateway, a financial services business can gain several advantages: +**Gateways** are the businesses that link the XRP Ledger to the rest of the world. An existing online financial institution can expand to act as a gateway in the the Ripple Consensus Ledger (XRP Ledger). By becoming a Ripple gateway, a financial services business can gain several advantages: -* By enabling its customers to send and receive value in the Ripple Consensus Ledger, the business increases its value proposition to customers. -* By accepting payments from the Ripple Consensus Ledger, the business increases the number of ways that customers can fund accounts at its business, even internationally. +* By enabling its customers to send and receive value in the XRP Ledger, the business increases its value proposition to customers. +* By accepting payments from the XRP Ledger, the business increases the number of ways that customers can fund accounts at its business, even internationally. * The business can use Ripple-related services as a new source of revenue. This document explains the concepts and steps necessary to become a Ripple 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 a Ripple gateway. @@ -25,18 +25,18 @@ This guide focuses on running an **issuing gateway**. ### Ripple Trust Lines and Issuances ### -All assets in the Ripple Consensus Ledger, except for the native cryptocurrency XRP, are represented as _issuances_, which are digital balances that represent currency or assets of value held by an issuer. Within the RCL, counterparties can send and trade issuances without requiring intervention from the issuer. Typically, a gateway sends issuances to customers when it receives money in systems and ledgers outside the RCL, and promises to send money to customers in outside systems in exchange for being repaid in issuances in the RCL. Issuances get their value from a gateway's agreement to honor the obligation that the issuances represent. No computer system can force a Ripple gateway to honor that obligation. +All assets in the XRP Ledger, except for the native cryptocurrency XRP, are represented as _issuances_, which are digital balances that represent currency or assets of value held by an issuer. Within the XRP Ledger, counterparties can send and trade issuances without requiring intervention from the issuer. Typically, a gateway sends issuances to customers when it receives money in systems and ledgers outside the RCL, and promises to send money to customers in outside systems in exchange for being repaid in issuances in the RCL. Issuances get their value from a gateway's agreement to honor the obligation that the issuances represent. No computer system can force a Ripple gateway to honor that obligation. -The Ripple Consensus Ledger has a system of directional accounting relationships, called _trust lines_, to make sure that users only hold issuances from counterparties they trust. +The XRP Ledger has a system of directional accounting relationships, called _trust lines_, to make sure that users only hold issuances from counterparties they trust. -A "trust line" is link between two addresses in Ripple. A trust line represents an explicit statement of willingness to hold gateway debt obligations. When a customer sends money into the RCL, a gateway takes custody of those assets outside of Ripple, and sends issuances in the RCL to the customer's address. When a customer sends money out of the RCL, she makes a Ripple payment to the gateway, and the gateway credits the customer in its own system of record, or in some other account. +A "trust line" is link between two addresses in Ripple. A trust line represents an explicit statement of willingness to hold gateway debt obligations. When a customer sends money into the XRP Ledger, a gateway takes custody of those assets outside of Ripple, and sends issuances in the RCL to the customer's address. When a customer sends money out of the RCL, she makes a Ripple payment to the gateway, and the gateway credits the customer in its own system of record, or in some other account. ### XRP ### -**XRP** is the native cryptocurrency of the Ripple Consensus Ledger. Like issuances, XRP can be freely sent and exchanged among Ripple addresses. Unlike issuances, XRP is not tied to an accounting relationship. XRP can be sent directly from any Ripple address to any other, without going through a gateway or liquidity provider. This helps make XRP a convenient bridge currency. For more information on XRP, see the [XRP Portal](https://ripple.com/xrp-portal/). +**XRP** is the native cryptocurrency of the XRP Ledger. Like issuances, XRP can be freely sent and exchanged among Ripple addresses. Unlike issuances, XRP is not tied to an accounting relationship. XRP can be sent directly from any Ripple address to any other, without going through a gateway or liquidity provider. This helps make XRP a convenient bridge currency. For more information on XRP, see the [XRP Portal](https://ripple.com/xrp-portal/). -XRP also serves other purposes in the RCL, in particular as a protective measure against spamming the network. All Ripple addresses need a small amount of XRP to pay the costs of maintaining the Ripple Consensus Ledger. The [transaction cost](concept-transaction-cost.html) and [reserve](concept-reserves.html) are neutral fees denoted in XRP and not paid to any party. +XRP also serves other purposes in the XRP Ledger, in particular as a protective measure against spamming the network. All Ripple addresses need a small amount of XRP to pay the costs of maintaining the XRP Ledger. The [transaction cost](concept-transaction-cost.html) and [reserve](concept-reserves.html) are neutral fees denoted in XRP and not paid to any party. Issuing gateways do not need to accumulate or exchange XRP. They must only hold a small balance of XRP to send transactions through the network. The XRP equivalent of $10 USD should be enough for at least one year of transaction costs for a busy gateway. @@ -44,7 +44,7 @@ Private exchanges and liquidity providers may choose to hold additional XRP for ### Liquidity and Currency Exchange ### -The Ripple Consensus Ledger contains a currency exchange, where any user can place and fulfill bids to exchange XRP and _issuances_ in any combination. Cross-currency payments automatically use the currency exchange to convert currency atomically when the transaction is executed. In this way, users who choose make offers in the distributed exchange provide the liquidity that makes the RCL useful. +The XRP Ledger contains a currency exchange, where any user can place and fulfill bids to exchange XRP and _issuances_ in any combination. Cross-currency payments automatically use the currency exchange to convert currency atomically when the transaction is executed. In this way, users who choose make offers in the distributed exchange provide the liquidity that makes the XRP Ledger useful. Currency traders who hold a gateway's issuances can provide liquidity to other popular currencies, without the gateway needing to float a large reserve in various destination currencies. The gateway also does not need to take on the risk of financial exchange. However, a gateway may still want to provide liquidity to XRP or other popular currencies at a baseline rate, especially when the gateway is new to the exchange. If you do provide liquidity, use a different address for trading than your issuing address. @@ -55,7 +55,7 @@ Contact [partners@ripple.com](mailto:partners@ripple.com) for help establishing ## Suggested Business Practices ## -The value of a gateway's issuances in the Ripple Consensus Ledger comes directly from the trust that customers can redeem them with the gateway when needed. We recommend the following precautions to reduce the risk of business interruptions: +The value of a gateway's issuances in the XRP Ledger comes directly from the trust that customers can redeem them with the gateway when needed. We recommend the following precautions to reduce the risk of business interruptions: * Use separate [Issuing and Operational Addresses](concept-issuing-and-operational-addresses.html) to limit your risk profile on the network. * Comply with anti-money-laundering regulations for your jurisdiction, such as the [Bank Secrecy Act](http://en.wikipedia.org/wiki/Bank_Secrecy_Act). This usually includes requirements to collect ["Know-Your-Customer" (KYC) information](http://en.wikipedia.org/wiki/Know_your_customer). @@ -75,10 +75,10 @@ For more information, see [Issuing and Operational Addresses](concept-issuing-an There are several ways in which a gateway can seek to profit from Ripple integration. These can include: * Withdrawal and Deposit fees. Gateways typically charge a small fee (such as 1%) for the service of adding or removing money from Ripple. You have the power to determine the rate you credit people when they move money onto and off of Ripple through your gateway. -* Transfer fees. You can set a percentage fee to charge automatically when customers send each other issuances created by your issuing address. This amount is debited from the Ripple Consensus Ledger, decreasing your obligation each time your issuances change hands. See [TransferRate](#transferrate) for details. +* Transfer fees. You can set a percentage fee to charge automatically when customers send each other issuances created by your issuing address. This amount is debited from the XRP Ledger, decreasing your obligation each time your issuances change hands. See [TransferRate](#transferrate) for details. * Indirect revenue from value added. Ripple integration can provide valuable functionality for your customers that distinguishes your business from your competitors. -* Interest on Ripple-backed funds. You can keep the collateral for the funds you issue in RCL in a bank account that earns interest. Make sure you can always access enough funds to service customer withdrawals. -* [Financial Exchange](#liquidity-and-currency-exchange). A gateway can also make offers to buy and sell its issuances for other issuances in the RCL, providing liquidity to cross-currency payments and possibly making a profit. (As with all financial exchange, profits are not guaranteed.) +* Interest on Ripple-backed funds. You can keep the collateral for the funds you issue in XRP Ledger in a bank account that earns interest. Make sure you can always access enough funds to service customer withdrawals. +* [Financial Exchange](#liquidity-and-currency-exchange). A gateway can also make offers to buy and sell its issuances for other issuances in the XRP Ledger, providing liquidity to cross-currency payments and possibly making a profit. (As with all financial exchange, profits are not guaranteed.) ### Choosing Fee Rates ### @@ -216,31 +216,31 @@ In the following diagram, ACME Exchange starts with €5 on hand, including €1 ## Sending from Gateway to Ripple ## -Ripple payments can automatically bridge between currencies, but an issuing gateway normally only sends single-currency payments that go directly to customers. This means debiting a customer's current balance in your system, and then sending the equivalent amount of issuances in the RCL to the customer's Ripple address. +Ripple payments can automatically bridge between currencies, but an issuing gateway normally only sends single-currency payments that go directly to customers. This means debiting a customer's current balance in your system, and then sending the equivalent amount of issuances in the XRP Ledger to the customer's Ripple address. -An example flow for a payment into the RCL: +An example flow for a payment into the XRP Ledger: -1. Alice asks to send €3 of her ACME balance into the RCL. +1. Alice asks to send €3 of her ACME balance into the XRP Ledger. 2. In its system of record, ACME debits Alice's balance €3. -3. ACME submits a Ripple transaction, sending €3 to Alice's Ripple address. The €3 is marked in the Ripple Consensus Ledger as being "issued" by ACME (3 EUR.ACME). +3. ACME submits a Ripple transaction, sending €3 to Alice's Ripple address. The €3 is marked in the XRP Ledger as being "issued" by ACME (3 EUR.ACME). **Assumptions:** -* Alice already has an address in the Ripple Consensus Ledger separate from her ACME account. Alice manages her Ripple address using a third-party client application. +* Alice already has an address in the XRP Ledger separate from her ACME account. Alice manages her Ripple address using a third-party client application.  -### Requirements for Sending to RCL ### +### Requirements for Sending to XRP Ledger ### There are several prerequisites that ACME must meet for this to happen: -- ACME sets aside money that is issued in the Ripple Consensus Ledger. ACME can query the RCL to see who holds its issuances at any time. There are several ways ACME may do this: - - ACME may create a Ripple Consensus Ledger collateral account in ACME's system of record. +- ACME sets aside money that is issued in the XRP Ledger. ACME can query the XRP Ledger to see who holds its issuances at any time. There are several ways ACME may do this: + - ACME may create a XRP Ledger collateral account in ACME's system of record. - ACME can store the funds allocated to Ripple in a separate bank account. - If ACME is a cryptocurrency exchange, ACME can create a separate wallet to hold the funds allocated to Ripple, as publicly-verifiable proof to customers that the gateway is solvent. -- ACME must control an address in the Ripple Consensus Ledger. Ripple's best practices recommend using a separate issuing address and operational address. See [Issuing and Operational Addresses](concept-issuing-and-operational-addresses.html) for details. +- ACME must control an address in the XRP Ledger. Ripple's best practices recommend using a separate issuing address and operational address. See [Issuing and Operational Addresses](concept-issuing-and-operational-addresses.html) for details. - ACME must enable the [DefaultRipple Flag](#defaultripple) on its issuing address for customers to send and receive its issuances. - Alice must create an accounting relationship (trust line) from her Ripple address to ACME's issuing address. She can do this from any Ripple client application as long as she knows ACME's issuing address. - ACME should publicize its issuing address on its website where customers can find it. It can also use [ripple.txt](#rippletxt) to publish the issuing address to automated systems. @@ -250,20 +250,20 @@ There are several prerequisites that ACME must meet for this to happen: See [Sending Payments to Customers](#sending-payments-to-customers) for an example of how to send payments into Ripple. -## Sending from RCL to Gateway ## +## Sending from XRP Ledger to Gateway ## -A payment out of the Ripple Consensus Ledger means the Gateway receives a payment in the RCL, and credits a user in the gateway's system of record. +A payment out of the XRP Ledger means the Gateway receives a payment in the XRP Ledger, and credits a user in the gateway's system of record. An example flow of a payment out of Ripple: 1. Bob sends Ripple transaction of €1 to ACME's issuing address. 2. In ACME's system of record, ACME credits Bob's balance €1. -Payments going from the Ripple Consensus Ledger to a gateway can be single-currency or cross-currency payments. The gateway's issuing address can only receive issuances it created (or XRP). +Payments going from the XRP Ledger to a gateway can be single-currency or cross-currency payments. The gateway's issuing address can only receive issuances it created (or XRP). -### Requirements for Receiving from RCL ### +### Requirements for Receiving from XRP Ledger ### -In addition to the [requirements for sending into Ripple](#requirements-for-sending-to-rcl), there are several prerequisites that ACME must meet to process payments coming from Ripple: +In addition to the [requirements for sending into Ripple](#requirements-for-sending-to-xrp-ledger), there are several prerequisites that ACME must meet to process payments coming from Ripple: - ACME must monitor its Ripple addresses for incoming payments. - ACME must know which user to credit in its system of record for the incoming payments. @@ -278,29 +278,29 @@ Processing payments to and from Ripple naturally comes with some risks, so a gat - Protect yourself against reversible deposits. Ripple payments are irreversible, but many electronic money systems like credit cards or PayPal are not. Scammers can abuse this to take their fiat money back by canceling a deposit after receiving Ripple issuances. - When sending into Ripple, specify the issuing address as the issuer of the currency. Otherwise, you might accidentally use paths that deliver the same currency issued by other addresses. - Before sending a payment into Ripple, double check the cost of the payment. A payment from your operational address to a customer should not cost more than the destination amount plus any [transfer fee](#transferrate) you have set. -- Before processing a payment out of Ripple, make sure you know the customer's identity. This makes it harder for anonymous attackers to scam you. Most anti-money-laundering regulations require this anyway. This is especially important because the users sending money from the RCL could be different than the ones that initially received the money in the RCL. +- Before processing a payment out of Ripple, make sure you know the customer's identity. This makes it harder for anonymous attackers to scam you. Most anti-money-laundering regulations require this anyway. This is especially important because the users sending money from the XRP Ledger could be different than the ones that initially received the money in the RCL. - Follow the guidelines for [reliable transaction submission](#reliable-transaction-submission) when sending Ripple transactions. - [Robustly monitor for incoming payments](#robustly-monitoring-for-payments), and read the correct amount. Don't mistakenly credit someone the full amount if they only sent a [partial payment](reference-transaction-format.html#partial-payments). -- Track your obligations and balances within the Ripple Consensus Ledger, and compare with the assets in your collateral account. If they do not match up, stop processing withdrawals and deposits until you resolve the discrepancy. +- Track your obligations and balances within the XRP Ledger, and compare with the assets in your collateral account. If they do not match up, stop processing withdrawals and deposits until you resolve the discrepancy. - Avoid ambiguous situations. We recommend the following: - Enable the [`DisallowXRP` flag](#disallowxrp) for the issuing address and all operational addresses, so customers do not accidentally send you XRP. (Private exchanges should *not* set this flag, since they trade XRP normally.) - Enable the [`RequireDest` flag](#requiredest) for the issuing address and all operational addresses, so customers do not accidentally send a payment without the destination tag to indicate who should be credited. - Enable the [`RequireAuth` flag](#requireauth) on all operational addresses so they cannot issue currency by accident. -- Monitor for suspicious or abusive behavior. For example, a user could repeatedly send funds into and out of the RCL, as a denial of service attack that effectively empties an operational address's balance. Suspend customers whose addresses are involved in suspicious behavior by not processing their Ripple payments. +- Monitor for suspicious or abusive behavior. For example, a user could repeatedly send funds into and out of the XRP Ledger, as a denial of service attack that effectively empties an operational address's balance. Suspend customers whose addresses are involved in suspicious behavior by not processing their Ripple payments. ## Trading on Ripple ## -After the issuances have been created in the Ripple Consensus Ledger, they can be freely transferred and traded by RCL users. There are several consequences of this situation: +After the issuances have been created in the XRP Ledger, they can be freely transferred and traded by XRP Ledger users. There are several consequences of this situation: - Anyone can buy/sell EUR.ACME on Ripple. If ACME issues multiple currencies on Ripple, a separate trust line is necessary for each. - - This includes RCL users who do not have an account in ACME Exchange's systems. To withdraw the funds successfully from ACME, users still have to register with ACME. - - Optionally, ACME uses the [Authorized Accounts](#authorized-accounts) feature to limit who can hold EUR.ACME in the RCL. - - If ACME determines that a customer has acted in bad faith, ACME can [Freeze](#freeze) that user's accounting relationships to ACME in the RCL, so that the user can no longer trade in the gateway's issuances. -- RCL users trading and sending EUR.ACME to one another requires no intervention by ACME. -- All exchanges and balances in the RCL are publicly viewable. + - This includes XRP Ledger users who do not have an account in ACME Exchange's systems. To withdraw the funds successfully from ACME, users still have to register with ACME. + - Optionally, ACME uses the [Authorized Accounts](#authorized-accounts) feature to limit who can hold EUR.ACME in the XRP Ledger. + - If ACME determines that a customer has acted in bad faith, ACME can [Freeze](#freeze) that user's accounting relationships to ACME in the XRP Ledger, so that the user can no longer trade in the gateway's issuances. +- XRP Ledger users trading and sending EUR.ACME to one another requires no intervention by ACME. +- All exchanges and balances in the XRP Ledger are publicly viewable. -The following diagram depicts a Ripple payment sending 2EUR.ACME from Alice to Charlie. ACME can query the RCL to see updates to its balances any time after the transaction has occurred: +The following diagram depicts a Ripple payment sending 2EUR.ACME from Alice to Charlie. ACME can query the XRP Ledger to see updates to its balances any time after the transaction has occurred:  @@ -308,7 +308,7 @@ The following diagram depicts a Ripple payment sending 2EUR.ACME from Alice to C ## Freeze ## -A gateway can freeze accounting relationships in the Ripple Consensus Ledger to meet regulatory requirements: +A gateway can freeze accounting relationships in the XRP Ledger to meet regulatory requirements: * Gateways can freeze individual accounting relationships, in case a customer address shows suspicious activity or violates a gateway's terms of use. * Gateways can freeze all accounting relationships to their issuing address, in case of a major security compromise or for migrating to a new issuing address. @@ -319,11 +319,11 @@ For more information, see the [Freeze article](concept-freeze.html). ## Authorized Accounts ## -The Ripple Consensus Ledger's Authorized Accounts feature enables a gateway to limit who can hold that gateway's issuances, so that unknown Ripple addresses cannot hold the currency the gateway issues. Ripple feels this is *not necessary* in most cases, since gateways have full control over the process of redeeming Ripple balances for value in the outside world. (You can collect customer information and impose limits on withdrawals at that stage without worrying about what happens within the Ripple Consensus Ledger.) +The XRP Ledger's Authorized Accounts feature enables a gateway to limit who can hold that gateway's issuances, so that unknown Ripple addresses cannot hold the currency the gateway issues. Ripple feels this is *not necessary* in most cases, since gateways have full control over the process of redeeming Ripple balances for value in the outside world. (You can collect customer information and impose limits on withdrawals at that stage without worrying about what happens within the Ripple Consensus Ledger.) To use the Authorized Accounts feature, a gateway enables the `RequireAuth` flag for its issuing address, and then individually approves each accounting relationship. An address can only hold funds issued by a gateway after its accounting relationship with that gateway is approved. -The transaction to authorize an accounting relationship must be signed by the issuing address, which unfortunately means an increased risk exposure for that address. The process for sending funds into the Ripple Consensus Ledger with RequireAuth enabled looks like the following: +The transaction to authorize an accounting relationship 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: 1. ACME publishes its issuing address to customers. 2. Alice creates an accounting relationship from her Ripple address to ACME's issuing address, indicating that she is willing to hold ACME's issuances. @@ -378,7 +378,7 @@ Contact [partners@ripple.com](mailto:partners@ripple.com) to see how Ripple can ### APIs and Middleware ### -There are several interfaces you can use to connect to the Ripple Consensus Ledger, depending on your needs and your existing software: +There are several interfaces you can use to connect to the XRP Ledger, depending on your needs and your existing software: * [`rippled`](reference-rippled.html) provides JSON-RPC and WebSocket APIs that can be used as a low-level interface to all core Ripple functionality. * [RippleAPI](reference-rippleapi.html) provides a simplified API for JavaScript applications. @@ -465,7 +465,7 @@ Enable the [RequireDest](#requiredest) flag on your issuing and operational addr ## DisallowXRP ## -The DisallowXRP setting (`disallowIncomingXRP` in RippleAPI) is designed to discourage RCL users from sending XRP to an address by accident. This reduces the costs and effort of bouncing undesired payments, if your gateway does not trade XRP. The DisallowXRP flag is not strictly enforced, because doing so could allow addresses to become permanently unusable if they run out of XRP. Client applications should honor the DisallowXRP flag by default. +The DisallowXRP setting (`disallowIncomingXRP` in RippleAPI) is designed to discourage XRP Ledger users from sending XRP to an address by accident. This reduces the costs and effort of bouncing undesired payments, if your gateway does not trade XRP. The DisallowXRP flag is not strictly enforced, because doing so could allow addresses to become permanently unusable if they run out of XRP. Client applications should honor the DisallowXRP flag by default. An issuing gateway that does not trade XRP should enable the DisallowXRP flag on the gateway's issuing and operational addresses. A private exchange that trades in XRP should only enable the DisallowXRP flag on addresses that are not expected to receive XRP. @@ -522,7 +522,7 @@ Response: ## RequireDest ## -The `RequireDest` setting (`requireDestinationTag` in RippleAPI) is designed to prevent customers from sending payments to your address while accidentally forgetting the [destination tag](#source-and-destination-tags) that identifies who should be credited for the payment. When enabled, the Ripple Consensus Ledger rejects any payment to your address that does not specify a destination tag. +The `RequireDest` setting (`requireDestinationTag` in RippleAPI) is designed to prevent customers from sending payments to your address while accidentally forgetting the [destination tag](#source-and-destination-tags) that identifies who should be credited for the payment. When enabled, the XRP Ledger rejects any payment to your address that does not specify a destination tag. We recommend enabling the `RequireDest` flag on all gateway issuing and operational addresses. @@ -586,7 +586,7 @@ We recommend always [enabling `RequireAuth`](#enabling-requireauth) for operatio If you want to use the [Authorized Accounts](#authorized-accounts) feature, you must also enable `RequireAuth` on your issuing address. When using Authorized Accounts, your issuing address must [submit a `TrustSet` transaction to approve each accounting relationship](#authorizing-trust-lines) that customers create with your issuing address. -You can only enable `RequireAuth` if the address owns no accounting relationships (trust lines) and no offers in the Ripple Consensus Ledger, so you must decide whether or not to use it before you start doing business in the RCL. +You can only enable `RequireAuth` if the address owns no accounting relationships (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. ### Enabling RequireAuth ### @@ -617,7 +617,7 @@ POST http://localhost:5005/ ### Authorizing Trust Lines ### -If you are using the [Authorized Accounts](#authorized-accounts) feature, customers cannot hold balances you issue unless you first authorize their accounting relationships to you in the RCL. +If you are using the [Authorized Accounts](#authorized-accounts) feature, customers cannot hold balances you issue unless you first authorize their accounting relationships to you in the XRP Ledger. To authorize an accounting relationship, submit a TrustSet transaction from your issuing address, with the user to trust as the `issuer` of the `LimitAmount`. Leave the `value` (the amount to trust them for) as **0**, and enable the [tfSetfAuth](reference-transaction-format.html#trustset-flags) flag for the transaction. @@ -664,10 +664,10 @@ To robustly check for incoming payments, gateways should do the following: To make things simpler for your customers, we recommend accepting payments to either operational addresses and issuing addresses. -As an added precaution, we recommend comparing the balances of your issuing address with the Ripple-backing funds in your internal accounting system as of each new Ripple ledger version. The issuing address's negative balances should match the assets you have allocated to RCL outside the network. If the two do not match up, then you should suspend processing payments into and out of the RCL until you have resolved the discrepancy. +As an added precaution, we recommend comparing the balances of your issuing address with the Ripple-backing funds in your internal accounting system as of each new Ripple ledger version. The issuing address's negative balances should match the assets you have allocated to XRP Ledger outside the network. If the two do not match up, then you should suspend processing payments into and out of the RCL until you have resolved the discrepancy. * Use [`rippled`'s `gateway_balances` command](reference-rippled.html#gateway-balances) or [RippleAPI's `getTrustlines` method](reference-rippleapi.html#gettrustlines) to check your balances. -* If you have a [TransferRate](#transferrate) set, then your obligations within the RCL decrease slightly whenever other Ripple addresses transfer your issuances among themselves. +* If you have a [TransferRate](#transferrate) set, then your obligations within the XRP Ledger decrease slightly whenever other Ripple addresses transfer your issuances among themselves. ## TransferRate ## @@ -729,9 +729,9 @@ All Ripple addresses, including operational and standby addresses, are subject t * In `rippled`'s APIs, you should set the [`SendMax` transaction parameter](reference-transaction-format.html#payment) higher than the destination `Amount` parameter. * In RippleAPI, you should set the `source.maxAmount` parameter higher than the `destination.amount` parameter; or, set the `source.amount` parameter higher than the `destination.minAmount` parameter. -**Note:** The TransferRate does not apply when sending issuances directly to the issuing address. The issuing address must always accept its issuances at face value in the RCL. This means that customers don't have to pay the TransferRate if they send payments to the issuing address directly, but they do when sending to an operational address. If you accept payments at both addresses, you may want to adjust the amount you credit customers in your system of record when customers send payments to the operational address, to compensate for the TransferRate the customer pays. +**Note:** The TransferRate does not apply when sending issuances directly to the issuing address. The issuing address must always accept its issuances at face value in the XRP Ledger. This means that customers don't have to pay the TransferRate if they send payments to the issuing address directly, but they do when sending to an operational address. If you accept payments at both addresses, you may want to adjust the amount you credit customers in your system of record when customers send payments to the operational address, to compensate for the TransferRate the customer pays. -For example: If ACME sets a transfer fee of 1%, a Ripple payment to deliver 5 EUR.ACME from a customer address to ACME's issuing address would cost exactly 5 EUR.ACME. However, the customer would need to send 5.05 EUR.ACME to deliver 5 EUR.ACME to ACME's operational address. (The issuing address's total obligations in the RCL decrease by 0.05 EUR.ACME.) When ACME credits customers for payments to ACME's operational address, ACME credits the customer for the amount delivered to the operational address _and_ the transfer fee, giving the customer €5,05 in ACME's systems. +For example: If ACME sets a transfer fee of 1%, a Ripple payment to deliver 5 EUR.ACME from a customer address to ACME's issuing address would cost exactly 5 EUR.ACME. However, the customer would need to send 5.05 EUR.ACME to deliver 5 EUR.ACME to ACME's operational address. (The issuing address's total obligations in the XRP Ledger decrease by 0.05 EUR.ACME.) When ACME credits customers for payments to ACME's operational address, ACME credits the customer for the amount delivered to the operational address _and_ the transfer fee, giving the customer €5,05 in ACME's systems. ## Sending Payments to Customers ## @@ -819,7 +819,7 @@ When one of your addresses receives a payment whose purpose is unclear, we recom The first requirement to bouncing payments is [robustly monitoring for incoming payments](#robustly-monitoring-for-payments). You do not want to accidentally refund a customer for more than they sent you! (This is particularly important if your bounce process is automated.) The [Partial Payment Flag Gateway Bulletin (PDF)](https://ripple.com/files/GB-2014-06.pdf) explains how to avoid a common problem. -Second, you should send bounced payments as Partial Payments. Since third parties can manipulate the cost of pathways between addresses, Partial Payments allow you to divest yourself of the full amount without being concerned about exchange rates within the Ripple Consensus Ledger. You should publicize your bounced payments policy as part of your terms of use. Send the bounced payment from either an operational address or a standby address. +Second, you should send bounced payments as Partial Payments. Since third parties can manipulate the cost of pathways between addresses, Partial Payments allow you to divest yourself of the full amount without being concerned about exchange rates within the XRP Ledger. You should publicize your bounced payments policy as part of your terms of use. Send the bounced payment from either an operational address or a standby address. * To send a Partial Payment using `rippled`, enable the [tfPartialPayment flag](reference-transaction-format.html#payment-flags) on the transaction. Set the `Amount` field to the amount you received and omit the `SendMax` field. * To send a Partial Payment using RippleAPI, set the `allowPartialPayment` field of the [Payment object](reference-rippleapi.html#payment) to `true`. Set the `source.maxAmount` and `destination.amount` both equal to the amount you received. diff --git a/content/tutorial-listing-xrp.md b/content/tutorial-listing-xrp.md index 8749b2e727..96709bf24c 100644 --- a/content/tutorial-listing-xrp.md +++ b/content/tutorial-listing-xrp.md @@ -1,6 +1,6 @@ # Listing XRP as an Exchange -This document describes the steps that an exchange needs to take to list XRP. For details about other aspects of `rippled` and the Ripple Consensus Ledger (RCL), see the [Ripple Developer Center](https://ripple.com/build). +This document describes the steps that an exchange needs to take to list XRP. For details about other aspects of `rippled` and the XRP Ledger (XRP Ledger), see the [Ripple Developer Center](https://ripple.com/build). ## Alpha Exchange @@ -18,9 +18,9 @@ For illustrative purposes, this document uses a fictitious business called _Alph Alpha Exchange wants to list BTC/XRP and XRP/USD trading pairs partially because listing these pairs will benefit its users. Specifically, this support will allow its users to: -* Deposit XRP _to_ Alpha Exchange _from_ the RCL +* Deposit XRP _to_ Alpha Exchange _from_ the XRP Ledger -* Withdraw XRP _from_ Alpha Exchange _to_ the RCL +* Withdraw XRP _from_ Alpha Exchange _to_ the XRP Ledger * Trade XRP with other currencies, such as BTC, USD, among others @@ -36,15 +36,15 @@ See also: * [Gateway Compliance](tutorial-gateway-guide.html#gateway-compliance) — Gateways and exchanges are different, but exchanges should also ensure that they are complying with local regulations and reporting to the appropriate agencies. -* [Requirements for Sending to RCL](tutorial-gateway-guide.html#requirements-for-sending-to-rcl) +* [Requirements for Sending to XRP Ledger](tutorial-gateway-guide.html#requirements-for-sending-to-xrp-ledger) -* [Requirements for Receiving from RCL](tutorial-gateway-guide.html#requirements-for-receiving-from-rcl) +* [Requirements for Receiving from XRP Ledger](tutorial-gateway-guide.html#requirements-for-receiving-from-xrp-ledger) * [Gateway Precautions](tutorial-gateway-guide.html#precautions) ### Partial Payments -Before integrating, exchanges should be aware of the [partial payments](reference-transaction-format.html#partial-payments) feature. This feature allows RCL users to send successful payments that reduce the amount received instead of increasing the `SendMax`. This feature can be useful for [returning payments](tutorial-gateway-guide.html#bouncing-payments) without incurring additional cost as the sender. +Before integrating, exchanges should be aware of the [partial payments](reference-transaction-format.html#partial-payments) feature. This feature allows XRP Ledger users to send successful payments that reduce the amount received instead of increasing the `SendMax`. This feature can be useful for [returning payments](tutorial-gateway-guide.html#bouncing-payments) without incurring additional cost as the sender. #### Partial Payments Warning @@ -54,9 +54,9 @@ When the [tfPartialPayment flag](reference-transaction-format.html#payment-flags ### Accounts -XRP is held in _accounts_ (also referred to as _wallets_ or _addresses_ ) on the Ripple Consensus Ledger (RCL). Accounts on the RCL are different than accounts on other blockchain ledgers, such as Bitcoin, where accounts incur little to no overhead. In the RCL, accounts can [never be deleted](concept-accounts.html#permanence-of-accounts), and each account must hold a separate [reserve of XRP](concept-reserves.html) that cannot be sent to others. For these reasons, Ripple recommends that institutions not create excessive or needless accounts. +XRP is held in _accounts_ (also referred to as _wallets_ or _addresses_ ) on the XRP Ledger (XRP Ledger). Accounts on the RCL are different than accounts on other blockchain ledgers, such as Bitcoin, where accounts incur little to no overhead. In the RCL, accounts can [never be deleted](concept-accounts.html#permanence-of-accounts), and each account must hold a separate [reserve of XRP](concept-reserves.html) that cannot be sent to others. For these reasons, Ripple recommends that institutions not create excessive or needless accounts. -To comply with Ripple's recommended best practices, Alpha Exchange should create at least two new accounts on the RCL. To minimize the risks associated with a compromised secret key, Ripple recommends creating [_cold_, _hot_, and _warm_ accounts](https://ripple.com/build/issuing-operational-addresses/) (these are sometimes referred to, respectively, as cold, hot, and warm wallets). The hot/warm/cold model is intended to balance security and convenience. Exchanges listing XRP should create the following accounts: +To comply with Ripple's recommended best practices, Alpha Exchange should create at least two new accounts on the XRP Ledger. To minimize the risks associated with a compromised secret key, Ripple recommends creating [_cold_, _hot_, and _warm_ accounts](https://ripple.com/build/issuing-operational-addresses/) (these are sometimes referred to, respectively, as cold, hot, and warm wallets). The hot/warm/cold model is intended to balance security and convenience. Exchanges listing XRP should create the following accounts: * A [_cold wallet_](concept-issuing-and-operational-addresses.html#issuing-address) to securely hold the majority of XRP and customers' funds. For exchanges, this is also the address to which its users send [deposits](#deposit-xrp-into-exchange). To provide optimal security, this account's secret key should be offline. @@ -70,7 +70,7 @@ To comply with Ripple's recommended best practices, Alpha Exchange should create * If the regular key or signer list are comromised, the exchange can regain control of the cold wallet. However, some of a malicious actor's actions cannot easily be undone: - * The malicious actor could issue currency in the RCL by using the cold wallet, but that currency should not be valued by anyone (unless the exchange explicitly stated it was also a gateway). + * The malicious actor could issue currency in the XRP Ledger by using the cold wallet, but that currency should not be valued by anyone (unless the exchange explicitly stated it was also a gateway). * If a malicious actor sets the asfRequireAuth flag for the account, that cannot be unset, although this only relates issuing currency and therefore should not affect an exchange that's not also a gateway. Any other settings a malicious actor sets or unsets with a master key can be reverted. @@ -97,7 +97,7 @@ See also: To custody its ccustomers' XRP, Alpha Exchange must track each customer's XRP balance and its own holdings. To do this, Alpha Exchange must create and maintain an additional balance sheet or accounting system. The following table illustrates what this balance sheet might look like. -The new RCL accounts (_Alpha Hot_, _Alpha Warm_, _Alpha Cold_) are in the *User* column of the *XRP Balances on RCL* table. +The new XRP Ledger accounts (_Alpha Hot_, _Alpha Warm_, _Alpha Cold_) are in the *User* column of the *XRP Balances on RCL* table. The *Alpha Exchange XRP Balances* table represents new, additional balance sheet. Alpha Exchange’s software manages their users’ balances of XRP on this accounting system. @@ -105,7 +105,7 @@ The *Alpha Exchange XRP Balances* table represents new, additional balance sheetXRP Balances -on RCL +on XRP LedgerAlpha Exchange @@ -181,7 +181,7 @@ XRP Balances #### XRP Amounts -Amounts of XRP are represented on the RCL as an unsigned integer count of _drops_, where one XRP is 1,000,000 drops. Ripple recommends that software store XRP balances as integer amounts of drops, and perform integer arithmetic on these values. However, user interfaces should present balances in units of XRP. +Amounts of XRP are represented on the XRP Ledger as an unsigned integer count of _drops_, where one XRP is 1,000,000 drops. Ripple recommends that software store XRP balances as integer amounts of drops, and perform integer arithmetic on these values. However, user interfaces should present balances in units of XRP. One drop (.000001 XRP) cannot be further subdivided. Keep this in mind when calculating and displaying FX rates between XRP and other assets. @@ -191,7 +191,7 @@ For more information, see [Specifying Currency Amounts](reference-rippled.html#s With exchanges like _Alpha Exchange_, XRP can be "on-ledger" or "off-ledger": -* **On-Ledger XRP**: XRP that can be queried through the public RCL by specifying the public [address](concept-accounts.html#addresses) of the XRP holder. The counterparty to these balances is the RCL. For more information, see [Currencies](reference-rippled.html#currencies). +* **On-Ledger XRP**: XRP that can be queried through the public XRP Ledger by specifying the public [address](concept-accounts.html#addresses) of the XRP holder. The counterparty to these balances is the RCL. For more information, see [Currencies](reference-rippled.html#currencies). * **Off-Ledger XRP**: XRP that is held by the accounting system of an exchange and can be queried through the exchange interface. Off-ledger XRP balances are credit-based. The counterparty is the exchange holding the XRP. @@ -215,13 +215,13 @@ There are four main steps involved in an exchange's typical flow of funds: This list does not include the [prerequisites](#prerequisites-for-supporting-xrp) required of an exchange. -At this point, _Alpha Exchange_ has created [hot, warm, and cold wallets](#accounts) on the RCL and added them to its balance sheet, but has not accepted any deposits from its users. +At this point, _Alpha Exchange_ has created [hot, warm, and cold wallets](#accounts) on the XRP Ledger and added them to its balance sheet, but has not accepted any deposits from its users.XRP Balances -on RCL +on XRP LedgerAlpha Exchange @@ -315,7 +315,7 @@ A user named Charlie wants to deposit 50,000 XRP to Alpha Exchange. Doing this i XRP Balances -on RCL +on XRP LedgerAlpha Exchange @@ -403,16 +403,16 @@ XRP Balances ### Trade XRP on the Exchange -Alpha Exchange users (like Charlie) can trade credit-based balances on Alpha Exchange. Alpha Exchange should keep track of user balances on its new balance sheet as these trades are made. These trades are _off-ledger_ and independent from the RCL, so the balance changes are not recorded on the RCL. +Alpha Exchange users (like Charlie) can trade credit-based balances on Alpha Exchange. Alpha Exchange should keep track of user balances on its new balance sheet as these trades are made. These trades are _off-ledger_ and independent from the XRP Ledger, so the balance changes are not recorded on the RCL. -Customers who hold XRP in their own RCL accounts can also use the distributed exchange built into the RCL to trade currencies issued by gateways. For more information about trading _on_ the RCL, see [Lifecycle of an Offer](reference-transaction-format.html#lifecycle-of-an-offer). +Customers who hold XRP in their own XRP Ledger accounts can also use the distributed exchange built into the RCL to trade currencies issued by gateways. For more information about trading _on_ the RCL, see [Lifecycle of an Offer](reference-transaction-format.html#lifecycle-of-an-offer). ### Rebalance XRP Holdings -Exchanges can adjust the balances between their hot and cold wallets at any time. Each balance adjustment consumes a [transaction cost](concept-transaction-cost.html), but does not otherwise affect the aggregate balance of all the accounts. The aggregate, on-ledger balance should always exceed the total balance available for trade on the exchange. (The excess should be sufficient to cover the RCL's transaction cost.) +Exchanges can adjust the balances between their hot and cold wallets at any time. Each balance adjustment consumes a [transaction cost](concept-transaction-cost.html), but does not otherwise affect the aggregate balance of all the accounts. The aggregate, on-ledger balance should always exceed the total balance available for trade on the exchange. (The excess should be sufficient to cover the XRP Ledger's transaction cost.) -The following table demonstrates a balance adjustment of 80,000 XRP (via a [_payment_](reference-transaction-format.html#payment) on the RCL) between Alpha Exchange's cold wallet and its hot wallet, where the cold wallet was debited and the hot wallet was credited. If the payment were reversed (debiting the hot wallet and crediting the cold wallet), the hot wallet balance would decrease. Balance adjustments like these allow an exchange to limit the risks associated with holding XRP in online hot wallets. +The following table demonstrates a balance adjustment of 80,000 XRP (via a [_payment_](reference-transaction-format.html#payment) on the XRP Ledger) between Alpha Exchange's cold wallet and its hot wallet, where the cold wallet was debited and the hot wallet was credited. If the payment were reversed (debiting the hot wallet and crediting the cold wallet), the hot wallet balance would decrease. Balance adjustments like these allow an exchange to limit the risks associated with holding XRP in online hot wallets.@@ -430,7 +430,7 @@ Off-Ledger Balances
User Balance - RCL Account +XRP Ledger Account Balance @@ -488,22 +488,22 @@ Off-Ledger Balances ### Withdraw XRP from Exchange -Withdrawals allow an exchange's users to move XRP from the exchange's off-ledger balance sheet to an account on the RCL. +Withdrawals allow an exchange's users to move XRP from the exchange's off-ledger balance sheet to an account on the XRP Ledger. In this example, Charlie withdraws 25,000 XRP from Alpha Exchange. This involves the following steps: -1. Charlie initiates the process on Alpha Exchange’s website. He provides instructions to transfer 25,000 XRP to a specific account on the RCL (named "Charlie RCL" in the following table). +1. Charlie initiates the process on Alpha Exchange’s website. He provides instructions to transfer 25,000 XRP to a specific account on the XRP Ledger (named "Charlie RCL" in the following table). 2. In response to Charlie’s instructions, Alpha Exchange does the following: a. Debits the amount (25,000 XRP) from Charlie’s account on its off-ledger balance sheet - b. Submits a payment on the RCL for the same amount (25,000 XRP), from Alpha Exchange's hot wallet to Charlie’s RCL account + b. Submits a payment on the XRP Ledger for the same amount (25,000 XRP), from Alpha Exchange's hot wallet to Charlie’s RCL account
-- RCL On-Ledger XRP Balances +XRP Ledger On-Ledger XRP Balances Alpha Exchange XRP @@ -522,7 +522,7 @@ Off-Ledger Balances User Balance - RCL Account +XRP Ledger Account Balance @@ -560,7 +560,7 @@ Off-Ledger Balances - Charlie RCL +Charlie XRP Ledger 50,000
75,000diff --git a/content/tutorial-multisign.md b/content/tutorial-multisign.md index 317f5a36b0..88005d4cff 100644 --- a/content/tutorial-multisign.md +++ b/content/tutorial-multisign.md @@ -1,7 +1,7 @@ How to Multi-Sign ============================= -Multi-signing is one of three ways to authorize transactions for the Ripple Consensus Ledger, alongside signing with [regular keys](reference-transaction-format.html#setregularkey) and master keys. You can configure your address to allow any combination of the three methods to authorize transactions. +Multi-signing is one of three ways to authorize transactions for the XRP Ledger, alongside signing with [regular keys](reference-transaction-format.html#setregularkey) and master keys. You can configure your address to allow any combination of the three methods to authorize transactions. Benefits of multi-signing include: @@ -33,7 +33,7 @@ To force the multi-signing feature to be enabled, add the following stanza to yo Setting up Multi-Signing ------------------------ -To multi-sign transactions from a particular address, you must create a list of addresses that can contribute to a multi-signature for your address. This list is stored in the Ripple Consensus Ledger as a [SignerList node](reference-ledger-format.html#signerlist). The following procedure demonstrates how to set up a SignerList for your address: +To multi-sign transactions from a particular address, you must create a list of addresses that can contribute to a multi-signature for your address. This list is stored in the XRP Ledger as a [SignerList node](reference-ledger-format.html#signerlist). The following procedure demonstrates how to set up a SignerList for your address: ### 1. Prepare a funded address ### diff --git a/content/tutorial-paychan.md b/content/tutorial-paychan.md index 8cbbc2dbab..cad4ac6c71 100644 --- a/content/tutorial-paychan.md +++ b/content/tutorial-paychan.md @@ -4,7 +4,7 @@ Payment Channels are an advanced feature for sending "asynchronous" XRP payments ## Background -The process of using a payment channel always involves two parties, a payer and a payee. The payer is an individual person or institution using the Ripple Consensus Ledger who is a customer of the payee. The payee is a person or business who is doing business on the Ripple Consensus Ledger (RCL), receiving XRP as payment for goods or services. +The process of using a payment channel always involves two parties, a payer and a payee. The payer is an individual person or institution using the XRP Ledger who is a customer of the payee. The payee is a person or business who is doing business on the Ripple Consensus Ledger (XRP Ledger), receiving XRP as payment for goods or services. The types of goods and services are not defined by the software or in this tutorial. However, the types of goods and services that are a good fit for payment channels are: @@ -358,7 +358,7 @@ For purposes of this tutorial, the payee can give the payer a high-five or equiv ## 7. Repeat steps 3-6 as desired. -The payer and payee can repeat steps 3 through 6 (creating, transmitting, and verifying claims in exchange for goods and services) as many times and as often as they like without waiting for the Ripple Consensus Ledger itself. The two main limits of this process are: +The payer and payee can repeat steps 3 through 6 (creating, transmitting, and verifying claims in exchange for goods and services) as many times and as often as they like without waiting for the XRP Ledger itself. The two main limits of this process are: - The amount of XRP in the payment channel. (If necessary, the payer can send a [PaymentChannelFund transaction][] to increase the total amount of XRP available to the channel.) diff --git a/content/tutorial-reliable-transaction-submission.md b/content/tutorial-reliable-transaction-submission.md index 2c778c5107..082ce7c2c8 100644 --- a/content/tutorial-reliable-transaction-submission.md +++ b/content/tutorial-reliable-transaction-submission.md @@ -1,6 +1,6 @@ # Reliable Transaction Submission -Financial institutions and other services using the Ripple Consensus Ledger should use the best practices described here to make sure that transactions are validated or rejected in a verifiable and prompt way. You should submit transactions to trusted (locally operated) `rippled` servers. +Financial institutions and other services using the XRP Ledger should use the best practices described here to make sure that transactions are validated or rejected in a verifiable and prompt way. You should submit transactions to trusted (locally operated) `rippled` servers. The best practices detailed in this document allow applications to submit transactions to the Ripple network while achieving: @@ -54,7 +54,7 @@ Each validated ledger has a canonical order in which transactions apply. This or ### LastLedgerSequence -[`LastLedgerSequence`](reference-transaction-format.html#lastledgersequence) is an optional parameter of all transactions. This instructs the Ripple Consensus Ledger that a transaction must be validated on or before a specific ledger instance. The Ripple Consensus Ledger never includes a transaction in a ledger instance whose sequence number is higher than the transaction's `LastLedgerSequence` parameter. +[`LastLedgerSequence`](reference-transaction-format.html#lastledgersequence) is an optional parameter of all transactions. This instructs the XRP Ledger that a transaction must be validated on or before a specific ledger instance. The Ripple Consensus Ledger never includes a transaction in a ledger instance whose sequence number is higher than the transaction's `LastLedgerSequence` parameter. Use the `LastLedgerSequence` parameter to prevent undesirable cases where a transaction is not confirmed promptly but could be included in a future ledger. You should specify the `LastLedgerSequence` parameter on every transaction. Automated processes should use a value of 4 greater than the last validated ledger index to make sure that a transaction is validated or rejected in a predictable and prompt way. diff --git a/content/tutorial-rippleapi-beginners-guide.md b/content/tutorial-rippleapi-beginners-guide.md index c9945cda0f..0fb219bb1d 100644 --- a/content/tutorial-rippleapi-beginners-guide.md +++ b/content/tutorial-rippleapi-beginners-guide.md @@ -1,6 +1,6 @@ # RippleAPI Beginners Guide # -This tutorial guides you through the basics of building a Ripple-connected application using [Node.js](http://nodejs.org/) and [RippleAPI](reference-rippleapi.html), a JavaScript API for accessing the Ripple Consensus Ledger. +This tutorial guides you through the basics of building a Ripple-connected application using [Node.js](http://nodejs.org/) and [RippleAPI](reference-rippleapi.html), a JavaScript API for accessing the XRP Ledger. The scripts and configuration files used in this guide are [available in the Ripple Dev Portal GitHub Repository](https://github.com/ripple/ripple-dev-portal/tree/master/content/code_samples/rippleapi_quickstart). @@ -138,7 +138,7 @@ The one argument to the constructor is an options object, which has [a variety o * The example `server` setting uses a secure WebSocket connection to connect to one of the public servers that Ripple (the company) operates. * If you don't include the `server` option, RippleAPI runs in [offline mode](reference-rippleapi.html#offline-functionality) instead, which only provides methods that don't need network connectivity. -* You can specify a [Ripple Test Net](https://ripple.com/build/ripple-test-net/) server instead to connect to the parallel-world Test Network instead of the production Ripple Consensus Ledger. +* You can specify a [Ripple Test Net](https://ripple.com/build/ripple-test-net/) server instead to connect to the parallel-world Test Network instead of the production XRP Ledger. * If you [run your own `rippled`](tutorial-rippled-setup.html), you can instruct it to connect to your local server. For example, you might say `server: 'ws://localhost:5005'` instead. ### Connecting and Promises ### @@ -147,7 +147,7 @@ The one argument to the constructor is an options object, which has [a variety o api.connect().then(() => { ``` -The [connect() method](reference-rippleapi.html#connect) is one of many RippleAPI methods that returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), which is a special kind of JavaScript object. A Promise is designed to do an asynchronous operation that returns a value later, such as querying the Ripple Consensus Ledger. +The [connect() method](reference-rippleapi.html#connect) is one of many RippleAPI methods that returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), which is a special kind of JavaScript object. A Promise is designed to do an asynchronous operation that returns a value later, such as querying the XRP Ledger. When you get a Promise back from some expression (like `api.connect()`), you call the Promise's `then` method and pass in a callback function. Passing a function as an argument is conventional in JavaScript, taking advantage of how JavaScript functions are [first-class objects](https://en.wikipedia.org/wiki/First-class_function). @@ -191,13 +191,13 @@ The `getAccountInfo` API method returns another Promise, so the line `}).then( i }).catch(console.error); ``` -The rest of the sample code is mostly more [boilerplate code](reference-rippleapi.html#boilerplate). The first line ends the previous callback function, then chains to another callback to run when it ends. That method disconnects cleanly from the Ripple Consensus Ledger, and has yet another callback which writes to the console when it finishes. If your script waits on [RippleAPI events](reference-rippleapi.html#api-events), do not disconnect until you are done waiting for events. +The rest of the sample code is mostly more [boilerplate code](reference-rippleapi.html#boilerplate). The first line ends the previous callback function, then chains to another callback to run when it ends. That method disconnects cleanly from the XRP Ledger, and has yet another callback which writes to the console when it finishes. If your script waits on [RippleAPI events](reference-rippleapi.html#api-events), do not disconnect until you are done waiting for events. The `catch` method ends this Promise chain. The callback provided here runs if any of the Promises or their callback functions encounters an error. In this case, we pass the standard `console.error` function, which writes to the console, instead of defining a custom callback. You could define a smarter callback function here to intelligently catch certain error types. # Waiting for Validation # -One of the biggest challenges in using the Ripple Consensus Ledger (or any decentralized system) is knowing the final, immutable transaction results. Even if you [follow the best practices](tutorial-reliable-transaction-submission.html) you still have to wait for the [consensus process](https://ripple.com/build/ripple-ledger-consensus-process/) to finally accept or reject your transaction. The following example code demonstrates how to wait for the final outcome of a transaction: +One of the biggest challenges in using the XRP Ledger (or any decentralized system) is knowing the final, immutable transaction results. Even if you [follow the best practices](tutorial-reliable-transaction-submission.html) you still have to wait for the [consensus process](https://ripple.com/build/ripple-ledger-consensus-process/) to finally accept or reject your transaction. The following example code demonstrates how to wait for the final outcome of a transaction: ``` {% include 'code_samples/rippleapi_quickstart/submit-and-verify.js' %} diff --git a/data-api-v2-tool.html b/data-api-v2-tool.html index 0c48de7e27..54a6d9a5ee 100644 --- a/data-api-v2-tool.html +++ b/data-api-v2-tool.html @@ -64,7 +64,7 @@ Note: This method cannot return CSV format; only JSON results are supported for raw RCL transactions.
+Note: This method cannot return CSV format; only JSON results are supported for raw XRP Ledger transactions.
Response Format
A successful response uses the HTTP code 200 OK and has a JSON body with the following:
@@ -7438,7 +7438,7 @@ Content-Type: image/svg+xml
In other words, XRP has the same precision as a 64-bit unsigned integer where each unit is equivalent to 0.000001 XRP.
Addresses
-Accounts in the RCL are identified by a base58 Ripple Address. The address is derived from the account's master public key, which is in turn derived from a secret key. An address is represented as a string in JSON and has the following characteristics:
+Accounts in the XRP Ledger are identified by a base58 Ripple Address. The address is derived from the account's master public key, which is in turn derived from a secret key. An address is represented as a string in JSON and has the following characteristics:
For more information, see Accounts.
Public Keys
-The Ripple Consensus Ledger (RCL) uses public keys to verify cryptographic signatures in several places:
+The XRP Ledger (XRP Ledger) uses public keys to verify cryptographic signatures in several places:
Account Sequence
A Sequence number is a 32-bit unsigned integer used to identify a transaction or Offer relative to a specific account.
-Every account object in the Ripple Consensus Ledger has a Sequence number, which starts at 1. For a transaction to be relayed to the network and possibly included in a validated ledger, it must have a
-Sequencefield that matches the sending account's currentSequencenumber. An account's Sequence field is incremented whenever a transaction from that account is included in a validated ledger (regardless of whether the transaction succeeded or failed). This preserves the order of transactions submitted by an account, and differentiates transactions that would otherwise be the same.Every Offer node in the Ripple Consensus Ledger is marked with the sending
+AccountAddress and theSequencevalue of the OfferCreate transaction that created it. These two fields, together, uniquely identify the Offer.Every account object in the XRP Ledger has a Sequence number, which starts at 1. For a transaction to be relayed to the network and possibly included in a validated ledger, it must have a
+Sequencefield that matches the sending account's currentSequencenumber. An account's Sequence field is incremented whenever a transaction from that account is included in a validated ledger (regardless of whether the transaction succeeded or failed). This preserves the order of transactions submitted by an account, and differentiates transactions that would otherwise be the same.Every Offer node in the XRP Ledger is marked with the sending
AccountAddress and theSequencevalue of the OfferCreate transaction that created it. These two fields, together, uniquely identify the Offer.Currency Code
-There are two kinds of currency code in the Ripple Consensus Ledger:
+There are two kinds of currency code in the XRP Ledger:
Genesis Ledger
Due to a mishap early in Ripple's history, ledgers 1 through 32569 were lost. Thus, ledger #32570 is the earliest ledger available anywhere. For purposes of the Data API v2, ledger #32570 is considered the genesis ledger.
Account Creation Objects
-An account creation object represents the action of creating an account in the Ripple Consensus Ledger. There are two variations, depending on whether the account was already present in ledger 32570, the earliest ledger available. Accounts that were already present in ledger 32570 are termed genesis accounts.
+An account creation object represents the action of creating an account in the XRP Ledger. There are two variations, depending on whether the account was already present in ledger 32570, the earliest ledger available. Accounts that were already present in ledger 32570 are termed genesis accounts.
@@ -7694,7 +7694,7 @@ Content-Type: image/svg+xml Exchange Objects
-An exchange object represents an actual exchange of currency, which can occur in the Ripple Consensus Ledger as the result of executing either an OfferCreate transaction or a Payment transaction. In order for currency to actually change hands, there must be a previously-unfilled Offer previously placed in the ledger with an OfferCreate transaction.
+An exchange object represents an actual exchange of currency, which can occur in the XRP Ledger as the result of executing either an OfferCreate transaction or a Payment transaction. In order for currency to actually change hands, there must be a previously-unfilled Offer previously placed in the ledger with an OfferCreate transaction.
A single transaction can cause several exchanges to occur. In this case, the sender of the transaction is the taker for all the exchanges, but each exchange has a different provider, currency pair, or both.
diff --git a/reference-ledger-format.html b/reference-ledger-format.html index c3e6b9776c..1273b47400 100644 --- a/reference-ledger-format.html +++ b/reference-ledger-format.html @@ -83,7 +83,7 @@
Any other transaction result is potentially not final. In that case, the transaction could still succeed or fail later, especially if conditions change such that the transaction is no longer prevented from applying. For example, trying to send a non-XRP currency to an account that does not exist yet would fail, but it could succeed if another transaction sends enough XRP to create the destination account. A server might even store a temporarily-failed, signed transaction and then successfully apply it later without asking first.
Understanding Transaction Metadata
-The metadata section of a transaction includes detailed information about all the changes to the shared Ripple Consensus Ledger that the transaction caused. This is true of any transaction that gets included in a ledger, whether or not it is successful. Naturally, the changes are only final if the transaction is validated.
+The metadata section of a transaction includes detailed information about all the changes to the shared XRP Ledger that the transaction caused. This is true of any transaction that gets included in a ledger, whether or not it is successful. Naturally, the changes are only final if the transaction is validated.
Some fields that may appear in transaction metadata include:
diff --git a/ripple-api-tool.html b/ripple-api-tool.html index dbb3d67e7a..e158b464bc 100644 --- a/ripple-api-tool.html +++ b/ripple-api-tool.html @@ -64,7 +64,7 @@
In this category:
In this category:
Caution: In stand-alone mode, you must manually advance the ledger.
New Genesis Ledger
-In stand-alone mode, you can have
+rippledcreate a new genesis ledger. This provides a known state, with none of the ledger history from the production Ripple Consensus Ledger. (This is very useful for unit tests, among other things.)In stand-alone mode, you can have
diff --git a/concept-transaction-cost.html b/concept-transaction-cost.html index 4eb126352c..cd8ac90f97 100644 --- a/concept-transaction-cost.html +++ b/concept-transaction-cost.html @@ -83,7 +83,7 @@rippledcreate a new genesis ledger. This provides a known state, with none of the ledger history from the production XRP Ledger. (This is very useful for unit tests, among other things.)
In this category:
-
-
Paths
-In the Ripple Consensus Ledger, paths define a way for payments to flow through intermediary steps on their way from sender to receiver. Paths enable cross-currency payments by connecting sender and receiver through order books. Paths also enable complex settlement of offsetting debts.
-A single Payment transaction in the Ripple Consensus 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.
+In the XRP Ledger, paths define a way for payments to flow through intermediary steps on their way from sender to receiver. Paths enable cross-currency payments by connecting sender and receiver through order books. 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.
Since XRP can be sent directly to any address, an XRP-to-XRP transaction does not use any paths.
Path Steps
A path is made of steps that connect the sender to the receiver of the payment. Every step is either:
diff --git a/concept-reserves.html b/concept-reserves.html index c2c48ea236..c357bd8064 100644 --- a/concept-reserves.html +++ b/concept-reserves.html @@ -83,7 +83,7 @@