diff --git a/charts-api-tool.html b/charts-api-tool.html index bbcf1d2bc4..9c43778305 100644 --- a/charts-api-tool.html +++ b/charts-api-tool.html @@ -45,28 +45,32 @@
diff --git a/charts_api.html b/charts_api.html index 43d61f80f1..202ad6954f 100644 --- a/charts_api.html +++ b/charts_api.html @@ -72,28 +72,32 @@
diff --git a/content/fees.md b/content/fees.md new file mode 100644 index 0000000000..f5f5bb96cf --- /dev/null +++ b/content/fees.md @@ -0,0 +1,21 @@ +# 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 the Ripple, Inc., can charge a fee for access to the network. + +However, the rules of the Ripple Consensus Ledger include several types of fees, including the [_transaction cost_](tx-cost.html) and [_reserve requirement_](https://wiki.ripple.com/Reserves), which protect the ledger against abuse. (These neutral fees are not paid to anyone.) There are also several optional ways that users of the Consensus Ledger can collect fees from each other, both inside and outside the Ripple Consensus Ledger. + +## In the Ledger ## + +The _transaction cost_ (sometimes called the transaction fee) is a miniscule amount of XRP destroyed in order to send a transaction. This cost scales with the load of the network, which protects it from being overwhelmed with spam. See [Transaction Cost](tx-cost.html) for more information. + +The _account reserve_ is a minimum amount of XRP that an account must possess. It scales with the number of objects the account owns in the ledger. This serves to disincentivize spam that would increase the size of the ledger. See [Reserves](https://wiki.ripple.com/Reserves) for more information. + +_Transfer fees_ are optional percentage fees that gateways can charge to transfer the currencies they issue to other accounts within the Ripple Consensus Ledger. See [Transfer Fees](https://ripple.com/knowledge_center/transfer-fees/) 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 similar to charging a fee. Trust line quality does not apply to XRP, which is not tied to a trust line. + +## Outside the Ledger ## + +While the above values are the only fees built into the ledger, people can still invent ways to charge fees outside the Ripple ledger. A common example is withdrawal or deposit fees charged by gateways, which are assessed when you use the gateway to get money into or out of the Ripple Consensus Ledger. This may cover the costs of transferring balances on traditional payment rails, or it may be in addition to those costs. + +Many other fees are also possible. Businesses might charge for access, account maintenance, 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 gateway or other financial institution. diff --git a/content/tx-cost.md b/content/tx-cost.md new file mode 100644 index 0000000000..1ec8f85586 --- /dev/null +++ b/content/tx-cost.md @@ -0,0 +1,52 @@ +# Transaction Cost # + +In order 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 scale up with the load on the network, in order to quickly bankrupt abusers while imposing as little cost as possible on legitimate, respectful users. + +Every transaction must specify how much XRP it will destroy in order to pay the transaction cost. This value goes in the [`Fee` field](transactions.html#common-fields). + +## Current Transaction Cost ## + +The current transaction cost required by the network is typically **0.01 XRP** (10,000 drops), although it sometimes increases due to network load. + +## Load Scaling ## + +Each server independently scales the transaction cost based on its current load. If you submit a transaction with a `Fee` value that is lower than current load-based transaction cost of the `rippled` server, that server drops the transaction: it neither applies not relays it. (**Exception:** If you submit a transaction through an admin connection, the server applies and relays the transaction as long as the fee meets the overall minimum.) However, your transaction is very unlikely to survive the consensus process unless its `Fee` value meets the requirements of a majority of servers. + +The transaction cost is only debited from the sender's XRP balance when the transaction actually becomes included in a validated ledger. The cost does not apply if the transaction is not included in a validated ledger. However, even failed transactions can be included in a validated ledger. + +When you sign a transaction online, you can omit the `Fee` field. In this case, `rippled` or ripple-lib looks up an appropriate value based on the state of the peer-to-peer network, and includes it before signing the transaction. There are several drawbacks and limitations to this system, however: + +* If the network's transaction fee goes up between signing and distributing the transaction, the transaction may not be confirmed. + * In the worst case, the transaction may be stuck in a state of being neither definitively confirmed or rejected, unless it included a `LastLedgerSequence` parameter or until you cancel it with a new transaction that uses the same `Sequence` number. See [reliable transaction submission](reliable-tx.html) for best practices. +* If the network's transaction fee is abnormally high, you may end up destroying more of your XRP than expected. You can avoid this by double-checking the details of the signed transaction before submitting it. + * If you are using `rippled`, you can also use the `fee_mult_max` parameter of the [`sign` command](rippled-apis.html#sign) to set a limit to the load scaling you will allow. +* You cannot look up the fee if you are offline. + +### Paying More Than Necessary ### + +As a rule, the Ripple Consensus Ledger executes transactions _exactly_ as they are signed, to the extent possible. (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`, even if it is much more than the current load fee 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. + + + +## Fee Voting ## + +In the long term, it may be necessary to change the basic fee schedule to reflect long-term changes in the value of XRP, especially because XRP only gets more scarce over time. In this case, validators can vote for changes to the XRP fee schedule, including the transaction fee as well as reserve amounts. If the fee preferences in a validator's configuration are different than the network's current fee schedule, the validator expresses its preferences to the network periodically. If a quorum of validators agrees on a change, they can apply a fee change that takes effect thereafter. + +You can set fee preferences in the `[voting]` stanza of the `rippled.cfg` file. Changes here should not be made lightly: insufficient fees could expose the Ripple peer-to-peer network to denial-of-service attacks. The parameters you can set are as follows: + +| Parameter | Description | Recommended Value | +|-----------|-------------|-------------------| +| reference\_fee | Amount of XRP, in _drops_, that must be destroyed to send the reference transaction, the cheapest possible transaction. (1 XRP = 1 million drops.) The actual transaction fee, which varies dynamically based on the load of individual servers, is derived from this value. | 10 | +| account\_reserve | Minimum amount of XRP, in drops, that an account must have on reserve. This is the smallest amount that can be sent to fund a new account in the ledger. | 20000000 | +| owner\_reserve | Additional amount of XRP, in drops, that an account must have on reserve for _each_ object it owns in the ledger. | 5000000 | + +Every 256th ledger is called a "flag" ledger. In the ledger immediately before the flag ledger, validators whose fee preferences are different than the current network setting distribute a "vote" message alongside their ledger validation, indicating the fee values they would prefer. In the flag ledger itself, nothing happens, but validators receive and take note of the votes from other validators they trust. + +After seeing the votes of other validators, each validator that wants to change the fee tries to find a fee schedule which is closest to its own preferences and also approved by a majority of other validators it trusts. (For example, if one validator wants to raise the fee from 10 to 100, but most validators only want to raise it from 10 to 20, the one validator settles on the change to raise the fee to 20.) If this seems possible, the validator inserts a [SetFee pseudo-transaction](transactions.html#setfee) into its proposal for the ledger following the flag ledger, with the expectation that other validators who also want the same fee change will insert an identical SetFee pseudo-transaction into their proposals for the same ledger. If a SetFee psuedotransaction survives the consensus process to be included in a validated ledger, then the new fee schedule denoted by the SetFee pseudotransaction takes effect starting with the following ledger. + +In short: + +* **Flag ledger -1**: Validators submit votes +* **Flag ledger**: Validators tally votes and decide what SetFee to include, if any +* **Flag ledger +1**: Validators insert SetFee pseudo-transaction into their proposed ledgers +* **Flag ledger +2**: New fee settings take effect, if a SetFee psuedotransaction achieved consensus diff --git a/data-api-v2-tool.html b/data-api-v2-tool.html index ad2e64be93..c6b052da3a 100644 --- a/data-api-v2-tool.html +++ b/data-api-v2-tool.html @@ -45,28 +45,32 @@
diff --git a/data_api_v2.html b/data_api_v2.html index 24fb25d966..b308ff352a 100644 --- a/data_api_v2.html +++ b/data_api_v2.html @@ -72,28 +72,32 @@
diff --git a/fees.html b/fees.html new file mode 100644 index 0000000000..e0af0d9cec --- /dev/null +++ b/fees.html @@ -0,0 +1,194 @@ + + + + + + + + Fees (Disambiguation) - Ripple Developer Portal + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+
+
+
+
+
+
+ + + diff --git a/gateway_guide.html b/gateway_guide.html index ac53097f89..fadfbcc900 100644 --- a/gateway_guide.html +++ b/gateway_guide.html @@ -72,28 +72,32 @@
diff --git a/historical_data.html b/historical_data.html index 763ba2b96c..509da60957 100644 --- a/historical_data.html +++ b/historical_data.html @@ -72,28 +72,32 @@
diff --git a/historicaldb-api-tool.html b/historicaldb-api-tool.html index a37e50d112..11005873dd 100644 --- a/historicaldb-api-tool.html +++ b/historicaldb-api-tool.html @@ -45,28 +45,32 @@
diff --git a/index.html b/index.html index fafaa23ed9..0f07bda49a 100644 --- a/index.html +++ b/index.html @@ -58,28 +58,32 @@
diff --git a/paths.html b/paths.html index be2849f86d..f39fce4b1a 100644 --- a/paths.html +++ b/paths.html @@ -72,28 +72,32 @@
diff --git a/reliable_tx.html b/reliable_tx.html index eb0f461971..2c13dbc1e0 100644 --- a/reliable_tx.html +++ b/reliable_tx.html @@ -72,28 +72,32 @@
diff --git a/rest-api-tool.html b/rest-api-tool.html index 6c2653112b..4128bd7ae9 100644 --- a/rest-api-tool.html +++ b/rest-api-tool.html @@ -45,28 +45,32 @@
diff --git a/ripple-api-tool.html b/ripple-api-tool.html index a33e874389..9c86cfc01e 100644 --- a/ripple-api-tool.html +++ b/ripple-api-tool.html @@ -45,28 +45,32 @@
diff --git a/ripple-ledger.html b/ripple-ledger.html index 4afdbf9c22..d6a7569538 100644 --- a/ripple-ledger.html +++ b/ripple-ledger.html @@ -5,7 +5,7 @@ - The Ledger - Ripple Developer Portal + Ripple Consensus Ledger - Ripple Developer Portal @@ -72,28 +72,32 @@
diff --git a/ripple-rest.html b/ripple-rest.html index 5a0ed1bea8..aa63feb746 100644 --- a/ripple-rest.html +++ b/ripple-rest.html @@ -72,28 +72,32 @@
diff --git a/rippled-apis.html b/rippled-apis.html index 8de1d07190..8344c3ad63 100644 --- a/rippled-apis.html +++ b/rippled-apis.html @@ -72,28 +72,32 @@
diff --git a/rippled-setup.html b/rippled-setup.html index f9947cc36e..1ba397904c 100644 --- a/rippled-setup.html +++ b/rippled-setup.html @@ -72,28 +72,32 @@
diff --git a/tool/pages.json b/tool/pages.json index eb0dad22dc..49be16e76b 100644 --- a/tool/pages.json +++ b/tool/pages.json @@ -2,72 +2,86 @@ { "name": "rippled", "md":"rippled.md", - "html":"rippled-apis.html" + "html":"rippled-apis.html", + "type": "reference" }, { "name": "rippled Setup", "md":"rippled-setup.md", - "html":"rippled-setup.html" + "html":"rippled-setup.html", + "type": "tutorial" }, { "name": "Ripple-REST", "md": "ripplerest_api.md", - "html": "ripple-rest.html" + "html": "ripple-rest.html", + "type": "reference" }, { "name": "Transactions", "md":"tx_format.md", - "html":"transactions.html" + "html":"transactions.html", + "type": "reference" }, { - "name": "The Ledger", + "name": "Ripple Consensus Ledger", "md":"ledger_format.md", - "html":"ripple-ledger.html" + "html":"ripple-ledger.html", + "type": "reference" }, { "name": "Reliable Transaction Submission", "md":"reliable_tx.md", - "html":"reliable_tx.html" + "html":"reliable_tx.html", + "type": "tutorial" }, { "name": "Gateway Guide", "md":"gateway_guide.md", - "html":"gateway_guide.html" + "html":"gateway_guide.html", + "type": "tutorial" }, { "name": "Historical Data API", "md": "historical_data.md", - "html": "historical_data.html" + "html": "historical_data.html", + "type": "reference" }, { "name": "Ripple Charts API", "md": "charts_api.md", - "html": "charts_api.html" + "html": "charts_api.html", + "type": "reference" }, { "name": "Ripple Data API v2", "md": "data_v2.md", - "html": "data_api_v2.html" - }, - { - "name": "Gateway Services", - "md":"gateway_services_spec.md", - "html":"gateway_services.html" - }, - { - "name": "Transfer Fees", - "md":"transferrate.md", - "html":"transfer_fees.html" + "html": "data_api_v2.html", + "type": "reference" }, { "name": "Paths", "md":"paths.md", - "html":"paths.html" + "html":"paths.html", + "type": "reference" }, { - "name": "Whitepapers", - "md":"whitepapers.md", - "html":"whitepapers.html" + "name": "Fees (Disambiguation)", + "md": "fees.md", + "html": "fees.html", + "type": "reference" + }, + { + "name": "Transfer Fees", + "md":"transferrate.md", + "html":"transfer_fees.html", + "type": "reference" + }, + { + "name": "Transaction Cost", + "md": "tx-cost.md", + "html": "tx-cost.html", + "type": "reference" }, { "name": "Overview", @@ -86,21 +100,21 @@ "name": "Historical Database API Tool", "template":"template-rest-api-tool.html", "methods_js": "js/apitool-methods-historical.js", - "is_apitool": true, + "type": "apitool", "rest_host": "https://history.ripple.com", "html": "historicaldb-api-tool.html" }, { "name": "WebSocket API Tool", "template":"template-ripple-api-tool.html", - "is_apitool": true, + "type": "apitool", "html": "ripple-api-tool.html" }, { "name": "Charts API Tool", "template":"template-rest-api-tool.html", "methods_js": "js/apitool-methods-charts.js", - "is_apitool": true, + "type": "apitool", "rest_host": "https://api.ripplecharts.com", "html": "charts-api-tool.html" }, @@ -108,7 +122,7 @@ "name": "Data API v2 Tool", "template":"template-rest-api-tool.html", "methods_js": "js/apitool-methods-data_v2.js", - "is_apitool": true, + "type": "apitool", "rest_host": "https://data.ripple.com", "html": "data-api-v2-tool.html" } diff --git a/tool/template-base.html b/tool/template-base.html index 9a17a01c39..4c799f2ca0 100644 --- a/tool/template-base.html +++ b/tool/template-base.html @@ -47,10 +47,20 @@