Fee Voting revisions

Author: mDuo13

docs/concepts/consensus-protocol/fee-voting.md

@@ -1,6 +1,4 @@
 ---
-html: fee-voting.html
-parent: consensus.html
 seo:
     description: How validators vote on fees (transaction cost and reserve requirements).
 labels:
@@ -9,27 +7,38 @@ labels:
 ---
 # Fee Voting
 
-Validators can vote for changes to basic [transaction cost](../transactions/transaction-cost.md) as well as [reserve requirements](../accounts/reserves.md). If the preferences in a validator's configuration are different than the network's current settings, the validator expresses its preferences to the network periodically. If a quorum of validators agrees on a change, they can apply a change that takes effect thereafter. Validators may do this for various reasons, especially to adjust to long-term changes in the value of XRP.
+Fee voting is a system for adjusting the fees of using the XRP Ledger, specifically the base [transaction cost](../transactions/transaction-cost.md) and [reserve requirements](../accounts/reserves.md). The purpose of the fees is to protect the network from spam, so fee voting decisions must weigh competing priorities of making the network accessible to more users and use cases versus protecting the network from misuse or overuse. Changes must be made periodically to adjust to long-term changes in the value of XRP and the costs and capabilities of network nodes.
 
-Operators of [`rippled` validators](../../infrastructure/configuration/server-modes/run-rippled-as-a-validator.md) can set their preferences for the transaction cost and reserve requirements in the `[voting]` stanza of the `rippled.cfg` file.
+[Validator](../../infrastructure/configuration/server-modes/run-rippled-as-a-validator.md) operators can set their preferred fee settings in the `[voting]` stanza of the `rippled.cfg` file. Each validator periodically expresses its preferences to the network, about once every 15 minutes. The network automatically adjusts the fee settings to the median of trusted validators' preferences.
 
 {% admonition type="warning" name="Caution" %}Insufficient requirements, if adopted by a consensus of trusted validators (>50%), could expose the XRP Ledger peer-to-peer network to denial-of-service attacks.{% /admonition %}
 
 The parameters you can set are as follows:
 
 | Parameter | Description | Recommended Value |
 |-----------|-------------|-------------------|
-| `reference_fee` | Amount of XRP, in _drops_ (1 XRP = 1 million drops.), that must be destroyed to send the reference transaction, the cheapest possible transaction. The actual transaction cost is a multiple of this value, scaled dynamically based on the load of individual servers. | `10` (0.00001 XRP) |
-| `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. | `10000000` (10 XRP) |
-| `owner_reserve` | How much more XRP, in _drops_, that an address must hold for _each_ object it owns in the ledger. | `2000000` (2 XRP) |
+| `reference_fee` | The **reference transaction cost.** This is the amount of XRP, in _drops_ (1 XRP = 1 million drops.), that must be destroyed to send the reference transaction, the cheapest possible transaction. The actual transaction cost is a multiple of this value, scaled dynamically based on the load of individual servers. | `10` (0.00001 XRP) |
+| `account_reserve` | The **base account reserve.** This is the minimum amount of XRP, in _drops_, that an account must hold in reserve, which is also the minimum requirement to fund a new account. | `10000000` (10 XRP) |
+| `owner_reserve` | The **owner reserve increment.** This is how much more XRP, in _drops_, that an account must hold for _each_ object it owns in the ledger. | `2000000` (2 XRP) |
+
+## Precautions
+
+Fee preferences should be set carefully. Insufficient fees, if adopted by more than half of trusted validators, could expose the ledger to various denial-of-service attacks. More specifically:
+
+- The reference transaction cost protects the network from excessive _processing and relaying_ of transactions. This is important because every server in the network independently verifies and processes every transaction, and those transactions need to be relayed to every server. If the reference transaction cost is too low, malicious users can overload the network by spamming it with too many transactions. This setting mostly protects servers' CPU and bandwidth usage.
+- The reserve settings protect the network from excessive _data storage_. This is important because every server in the network needs a full copy of the most recent ledger state, including all accounts and other ledger entry types. Unused accounts and data cannot be automatically pruned, so the reserves provide an incentive for users to delete data they are not actively using. If the reserves are too low, malicious users can overload the network by creating too many ledger entries. These settings mostly protect servers' RAM and disk space.
+
+Generally speaking, raising the reserve requirements is more disruptive than lowering them. When reserves go down, some users have access to money that was previous locked up; when reserves go up, some users no longer have enough money to send many types of transactions. To minimize disruption, it's generally recommended to be conservative about lowering reserves, instead of aggressively adjusting the settings to respond to volatility in the price of XRP.
 
 ## Voting Process
 
-Every 256th ledger is called a "flag" ledger. (A flag ledger is defined such that the `ledger_index` [modulo](https://en.wikipedia.org/wiki/Modulo_operation) `256` is equal to `0`.) In the ledger immediately before the flag ledger, each validator whose account reserve or transaction cost preferences are different than the current network setting distributes a "vote" message alongside its ledger validation, indicating the values that validator prefers.
+Every 256th ledger is called a "flag" ledger. (A flag ledger is defined such that the `ledger_index` [modulo](https://en.wikipedia.org/wiki/Modulo_operation) `256` is equal to `0`.) Since ledgers typically take 3-4 seconds to close, there is usually a new flag ledger every 15 minutes.
+
+In the ledger immediately before the flag ledger, each validator whose account reserve or transaction cost preferences are different than the current network setting distributes a "vote" message alongside its ledger validation, indicating the values that validator prefers.
 
 In the flag ledger itself, nothing happens, but validators receive and take note of the votes from other validators they trust.
 
-After counting the votes of other validators, each validator attempts to compromise between its own preferences and the preferences of a majority of validators it trusts. (For example, if one validator wants to raise the minimum transaction cost 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 cost to 20. However, the one validator never settles on a value lower than 10 or higher than 100.) If a compromise is possible, the validator inserts a [SetFee pseudo-transaction](../../references/protocol/transactions/pseudo-transaction-types/setfee.md) into its proposal for the ledger following the flag ledger. Other validators who want the same change insert the same SetFee pseudo-transaction into their proposals for the same ledger. (Validators whose preferences match the existing network settings do nothing.) If a SetFee pseudo-transaction survives the consensus process to be included in a validated ledger, then the new transaction cost and reserve settings denoted by the SetFee pseudo-transaction take effect starting with the following ledger.
+After counting the votes of other validators, each validator attempts to compromise between its own preferences and the preferences of a majority of validators it trusts (the members of its UNL) by taking the median vote for each setting. If the median is _between_ two votes, it chooses the option that is closer to the current setting. If any of the chosen settings are different than what is currently defined in the ledger, the validator inserts a [SetFee pseudo-transaction](../../references/protocol/transactions/pseudo-transaction-types/setfee.md) into its proposal for the ledger following the flag ledger. Other validators also insert a SetFee pseudo-transaction into their proposals based on their preferences and the votes in their UNLs. Validators whose preferences match the existing network settings do nothing. If any SetFee pseudo-transaction has a majority and survives the consensus process to be included in a validated ledger, then the new transaction cost and reserve settings take effect starting with the following ledger.
 
 In short:
 
@@ -40,14 +49,15 @@ In short:
 
 ## Maximum Fee Values
 
-The maximum possible values for the fees are limited by the internal data types stored in the [FeeSettings ledger object](../../references/protocol/ledger-data/ledger-entry-types/feesettings.md). These values are as follows:
+Before the [XRPFees amendment][], the maximum possible values for the fees was limited based on the internal data type of the legacy [FeeSettings ledger entry](../../references/protocol/ledger-data/ledger-entry-types/feesettings.md) format. These values are as follows:
 
 | Parameter | Maximum Value (drops) | Maximum Value (XRP)
 |-----------|-----------------------|----|
 | `reference_fee` | 2<sup>64</sup> | (More XRP than has ever existed.) |
 | `account_reserve` | 2<sup>32</sup> drops | Approximately 4294 XRP |
 | `owner_reserve` | 2<sup>32</sup> drops | Approximately 4294 XRP |
 
+On Mainnet and any other networks with the XRPFees amendment enabled, all three fees can now be set to any valid amount of XRP.
 
 ## See Also