tx cost - edits for FeeEscalation peer review; moved fee levels discussion out of api reference into tx cost concept article

concept-transaction-cost.html

@@ -152,7 +152,7 @@
 <p>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 <a href="https://ripple.com/knowledge_center/math-based-currency-2/">XRP</a>. This <em>transaction cost</em> is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network.</p>
 <p>Every transaction must <a href="#specifying-the-transaction-cost">specify how much XRP it will destroy</a> in order to pay the transaction cost.</p>
 <h2 id="current-transaction-cost">Current Transaction Cost</h2>
-<p>The current transaction cost required by the network for a standard transaction is typically <strong>0.01 XRP</strong> (10,000 drops), although it sometimes increases due to network load.</p>
+<p>The current transaction cost required by the network for a standard transaction is typically <strong>0.01 XRP</strong> (10,000 drops), after load scaling. It sometimes increases due to higher than usual load.</p>
 <p>You can also <a href="#querying-the-transaction-cost">query <code>rippled</code> for the current transaction cost</a>.</p>
 <h3 id="special-transaction-costs">Special Transaction Costs</h3>
 <p>Some transactions have different transaction costs:</p>
@@ -165,7 +165,7 @@
 </thead>
 <tbody>
 <tr>
-<td>Reference Transaction (Standard cost of most transactions)</td>
+<td><a href="#reference-transaction-cost">Reference Transaction</a> (Most transactions)</td>
 <td>10 drops</td>
 </tr>
 <tr>
@@ -193,11 +193,10 @@
 <li>Transactions in between, which get <a href="#queued-transactions">queued for a later ledger version</a>.</li>
 </ul>
 <h2 id="local-load-cost">Local Load Cost</h2>
-<p>Each <code>rippled</code> server maintains a cost threshold based on its current load. If you submit a transaction with a <code>Fee</code> value that is lower than current load-based transaction cost of the <code>rippled</code> server, that server neither applies nor relays the transaction. (<strong>Note:</strong> If you submit a transaction through an <a href="reference-rippled.html#connecting-to-rippled">admin connection</a>, the server applies and relays the transaction as long as the transaction cost meets the overall minimum.) A transaction is very unlikely to survive <a href="https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/">the consensus process</a> unless its <code>Fee</code> value meets the requirements of a majority of servers.</p>
+<p>Each <code>rippled</code> server maintains a cost threshold based on its current load. If you submit a transaction with a <code>Fee</code> value that is lower than current load-based transaction cost of the <code>rippled</code> server, that server neither applies nor relays the transaction. (<strong>Note:</strong> If you submit a transaction through an <a href="reference-rippled.html#connecting-to-rippled">admin connection</a>, the server applies and relays the transaction as long as the transaction cost meets the un-scaled minimum.) A transaction is very unlikely to survive <a href="https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/">the consensus process</a> unless its <code>Fee</code> value meets the requirements of a majority of servers.</p>
 <h2 id="open-ledger-cost">Open Ledger Cost</h2>
-<p>A <code>rippled</code> server with the <a href="concept-amendments.html#feeescalation">FeeEscalation amendment</a> enabled has a second mechanism for enforcing the transaction cost, called the <em>open ledger cost</em>. The open ledger cost starts out equal to the minimum transaction cost, but increases exponentially when an in-progress ledger has more transactions than the previous one. Only transactions which pay more than the open ledger cost can be included in the current open ledger.
+<p>A <code>rippled</code> server with the <a href="concept-amendments.html#feeescalation">FeeEscalation amendment</a> enabled has a second mechanism for enforcing the transaction cost, called the <em>open ledger cost</em>. The open ledger cost starts out equal to the un-scaled minimum transaction cost, but increases exponentially when an in-progress ledger has more transactions than the previous ledger. The open ledger cost also increases if consensus took longer than 5 seconds to approve the previous ledger. A transaction can only be included in the open ledger if it meets the open ledger cost requirement in XRP. Transactions that do not meet the open ledger cost are <a href="#queued-transactions">queued for a following ledger</a> instead.</p>
-Transactions that do not meet the open ledger cost are <a href="#queued-transactions">queued for a following ledger</a> instead.</p>
+<p>The open ledger cost requirement is <a href="#fee-levels">proportional to the normal cost of the transaction</a>, not the absolute transaction cost. Transaction types that have a higher-than-normal requirement, such as <a href="reference-transaction-format.html#multi-signing">multi-signed transactions</a> must pay more to meet the open ledger cost than transactions which have minimum transaction cost requirements.</p>
-<p>The open ledger cost requirement is proportional to the normal cost of the transaction, not the absolute transaction cost. Transaction types that have a higher-than-normal requirement, such as <a href="reference-transaction-format.html#multi-signing">multi-signed transactions</a> must pay more to meet the open ledger cost than transactions which have minimum transaction cost requirements.</p>
 <p>See also: <a href="https://github.com/ripple/rippled/blob/release/src/ripple/app/misc/FeeEscalation.md">Fee Escalation explanation in <code>rippled</code> repository</a>.</p>
 <h3 id="queued-transactions">Queued Transactions</h3>
 <p>(Requires the <a href="concept-amendments.html#feeescalation">FeeEscalation amendment</a>)</p>
@@ -206,6 +205,44 @@ Transactions that do not meet the open ledger cost are <a href="#queued-transact
 <p>When the current open ledger closes and the server starts a new open ledger, the server starts taking transactions from the queue to include in the new open ledger. The transaction queue is sorted with the transactions that would pay the highest transaction cost first, proportional to the un-scaled cost of those transactions. Transactions that pay the same transaction cost are queued in the order the server receives them.</p>
 <p><strong>Note:</strong> As of <code>rippled</code> <strong>version 0.31.0</strong>, the transaction queue supports at most 1 transaction per sending address. This is expected to change in later versions.</p>
 <p><strong>Caution:</strong> The current implementation does not allow transactions with an <code>AccountTxnID</code> field in the transaction queue.</p>
+<h2 id="reference-transaction-cost">Reference Transaction Cost</h2>
+<p>The "Reference Transaction" is the cheapest (non-free) transaction, in terms of the necessary <a href="concept-transaction-cost.html">transaction cost</a> before load scaling. Most transactions have the same cost as the reference transaction. Some transactions, such as <a href="reference-transaction-format.html#multi-signing">multi-signed transactions</a>, require a multiple of this cost instead. When the open ledger cost escalates, the requirement is proportional to the basic cost of the transaction.</p>
+<h3 id="fee-levels">Fee Levels</h3>
+<p><em>Fee levels</em> represent the proportional difference between the minimum cost and the actual cost of a transaction. The <a href="#open-ledger-cost">Open Ledger Cost</a> is measured in fee levels instead of absolute cost. See the following table for a comparison:</p>
+<table>
+<thead>
+<tr>
+<th>Transaction</th>
+<th>Minimum cost in drops</th>
+<th>Minimum cost in Fee levels</th>
+<th>Double cost in drops</th>
+<th>Double cost in fee levels</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Reference transaction (most transactions)</td>
+<td>10</td>
+<td>256</td>
+<td>20</td>
+<td>512</td>
+</tr>
+<tr>
+<td><a href="reference-transaction-format.html#multi-signing">Multi-signed transaction</a> with 4 signatures</td>
+<td>50</td>
+<td>256</td>
+<td>100</td>
+<td>512</td>
+</tr>
+<tr>
+<td><a href="concept-transaction-cost.html#key-reset-transaction">Key reset transaction</a></td>
+<td>0</td>
+<td>(Effectively infinite)</td>
+<td>N/A</td>
+<td>(Effectively infinite)</td>
+</tr>
+</tbody>
+</table>
 <h2 id="querying-the-transaction-cost">Querying the Transaction Cost</h2>
 <p>The <code>rippled</code> APIs have two ways to query the local load-based transaction cost: the <code>server_info</code> command (intended for humans) and the <code>server_state</code> command (intended for machines).</p>
 <p>If the <a href="concept-amendments.html#feeescalation">FeeEscalation amendment</a> is enabled, you can use the <a href="reference-rippled.html#fee"><code>fee</code> command</a> to check the open ledger cost.</p>

content/concept-transaction-cost.md

@@ -7,7 +7,7 @@ Every transaction must [specify how much XRP it will destroy](#specifying-the-tr
 
 ## Current Transaction Cost ##
 
-The current transaction cost required by the network for a standard transaction is typically **0.01 XRP** (10,000 drops), although it sometimes increases due to network load.
+The current transaction cost required by the network for a standard transaction is typically **0.01 XRP** (10,000 drops), after load scaling. It sometimes increases due to higher than usual load.
 
 You can also [query `rippled` for the current transaction cost](#querying-the-transaction-cost).
 
@@ -17,7 +17,7 @@ Some transactions have different transaction costs:
 
 | Transaction           | Cost Before Load Scaling |
 |-----------------------|--------------------------|
-| Reference Transaction (Standard cost of most transactions) | 10 drops |
+| [Reference Transaction](#reference-transaction-cost) (Most transactions) | 10 drops |
 | [Key Reset Transaction](#key-reset-transaction) | 0 |
 | [Multi-signed transaction](reference-transaction-format.html#multi-signing) | 10 drops × (1 + Number of Signatures Provided) |
 
@@ -43,14 +43,13 @@ This divides transactions into roughly three categories:
 
 ## Local Load Cost ##
 
-Each `rippled` server maintains a cost threshold 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 neither applies nor relays the transaction. (**Note:** If you submit a transaction through an [admin connection](reference-rippled.html#connecting-to-rippled), the server applies and relays the transaction as long as the transaction cost meets the overall minimum.) A transaction is very unlikely to survive [the consensus process](https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/) unless its `Fee` value meets the requirements of a majority of servers.
+Each `rippled` server maintains a cost threshold 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 neither applies nor relays the transaction. (**Note:** If you submit a transaction through an [admin connection](reference-rippled.html#connecting-to-rippled), the server applies and relays the transaction as long as the transaction cost meets the un-scaled minimum.) A transaction is very unlikely to survive [the consensus process](https://ripple.com/knowledge_center/the-ripple-ledger-consensus-process/) unless its `Fee` value meets the requirements of a majority of servers.
 
 ## Open Ledger Cost ##
 
-A `rippled` server with the [FeeEscalation amendment](concept-amendments.html#feeescalation) enabled has a second mechanism for enforcing the transaction cost, called the _open ledger cost_. The open ledger cost starts out equal to the minimum transaction cost, but increases exponentially when an in-progress ledger has more transactions than the previous one. Only transactions which pay more than the open ledger cost can be included in the current open ledger.
+A `rippled` server with the [FeeEscalation amendment](concept-amendments.html#feeescalation) enabled has a second mechanism for enforcing the transaction cost, called the _open ledger cost_. The open ledger cost starts out equal to the un-scaled minimum transaction cost, but increases exponentially when an in-progress ledger has more transactions than the previous ledger. The open ledger cost also increases if consensus took longer than 5 seconds to approve the previous ledger. A transaction can only be included in the open ledger if it meets the open ledger cost requirement in XRP. Transactions that do not meet the open ledger cost are [queued for a following ledger](#queued-transactions) instead.
-Transactions that do not meet the open ledger cost are [queued for a following ledger](#queued-transactions) instead.
 
-The open ledger cost requirement is proportional to the normal cost of the transaction, not the absolute transaction cost. Transaction types that have a higher-than-normal requirement, such as [multi-signed transactions](reference-transaction-format.html#multi-signing) must pay more to meet the open ledger cost than transactions which have minimum transaction cost requirements.
+The open ledger cost requirement is [proportional to the normal cost of the transaction](#fee-levels), not the absolute transaction cost. Transaction types that have a higher-than-normal requirement, such as [multi-signed transactions](reference-transaction-format.html#multi-signing) must pay more to meet the open ledger cost than transactions which have minimum transaction cost requirements.
 
 See also: [Fee Escalation explanation in `rippled` repository](https://github.com/ripple/rippled/blob/release/src/ripple/app/misc/FeeEscalation.md).
 
@@ -68,6 +67,19 @@ When the current open ledger closes and the server starts a new open ledger, the
 
 **Caution:** The current implementation does not allow transactions with an `AccountTxnID` field in the transaction queue.
 
+## Reference Transaction Cost ##
+
+The "Reference Transaction" is the cheapest (non-free) transaction, in terms of the necessary [transaction cost](concept-transaction-cost.html) before load scaling. Most transactions have the same cost as the reference transaction. Some transactions, such as [multi-signed transactions](reference-transaction-format.html#multi-signing), require a multiple of this cost instead. When the open ledger cost escalates, the requirement is proportional to the basic cost of the transaction.
+
+### Fee Levels ###
+
+_Fee levels_ represent the proportional difference between the minimum cost and the actual cost of a transaction. The [Open Ledger Cost](#open-ledger-cost) is measured in fee levels instead of absolute cost. See the following table for a comparison:
+
+| Transaction | Minimum cost in drops | Minimum cost in Fee levels | Double cost in drops | Double cost in fee levels |
+|-------------|-----------------------|----------------------------|----------------------|---------------------------|
+| Reference transaction (most transactions) | 10 | 256 | 20 | 512 |
+| [Multi-signed transaction](reference-transaction-format.html#multi-signing) with 4 signatures | 50 | 256 | 100 | 512 |
+| [Key reset transaction](concept-transaction-cost.html#key-reset-transaction) | 0 | (Effectively infinite) | N/A | (Effectively infinite) |
 
 
 ## Querying the Transaction Cost ##

content/reference-rippled.md

@@ -9158,10 +9158,10 @@ The response follows the [standard format](#response-formatting), with a success
 | current\_ledger\_size      | String (Integer) | Number of transactions provisionally included in the in-progress ledger. |
 | current\_queue\_size       | String (Integer) | Number of transactions currently queued for the next ledger. |
 | drops                      | Object | Various information about the transaction cost (the `Fee` field of a transaction), in [drops of xrp](#specifying-currency-amounts). |
-| drops.base\_fee            | String (Integer) | The transaction cost required for a [reference transaction](#reference-transaction-cost) to be included in a ledger under minimum load, represented in drops of XRP. |
+| drops.base\_fee            | String (Integer) | The transaction cost required for a [reference transaction](concept-transaction-cost.html#reference-transaction-cost) to be included in a ledger under minimum load, represented in drops of XRP. |
 | drops.median\_fee          | String (Integer) | An approximation of the median transaction cost among transactions included in the previous validated ledger, represented in drops of XRP. |
-| drops.minimum\_fee         | String (Integer) | The minimum transaction cost for a [reference transaction](#reference-transaction-cost) to be queued for a later ledger, represented in drops of XRP. If greater than `base_fee`, the transaction queue is full. |
+| drops.minimum\_fee         | String (Integer) | The minimum transaction cost for a [reference transaction](concept-transaction-cost.html#reference-transaction-cost) to be queued for a later ledger, represented in drops of XRP. If greater than `base_fee`, the transaction queue is full. |
-| drops.open\_ledger\_fee    | String (Integer) | The minimum transaction cost that a [reference transaction](#reference-transaction-cost) must pay to be included in the current open ledger, represented in drops of XRP. |
+| drops.open\_ledger\_fee    | String (Integer) | The minimum transaction cost that a [reference transaction](concept-transaction-cost.html#reference-transaction-cost) must pay to be included in the current open ledger, represented in drops of XRP. |
 | expected\_ledger\_size     | String (Integer) | The approximate number of transactions expected to be included in the current ledger. This is based on the number of transactions in the previous ledger. |
 | levels                     | Object | Various information about the transaction cost, in _fee levels_. The ratio in fee levels applies to any transaction relative to the minimum cost of that particular transaction. |
 | levels.median\_level       | String (Integer) | The median transaction cost among transactions in the previous validated ledger, represented in fee levels. |
@@ -9170,20 +9170,6 @@ The response follows the [standard format](#response-formatting), with a success
 | levels.reference\_level    | String (Integer) | The equivalent of the minimum transaction cost, represented in fee levels. |
 | max\_queue\_size           | String (Integer) | The maximum number of transactions that the [transaction queue](concept-transaction-cost.html#queued-transactions) can currently hold. |
 
-### Reference Transaction Cost ###
-
-The "Reference Transaction" is the cheapest possible transaction, in terms of the necessary [transaction cost](concept-transaction-cost.html). Most transactions have the same cost as the reference transaction. Some transactions, such as [multi-signed transactions](reference-transaction-format.html#multi-signing) require a multiple of this cost instead. When the open ledger cost escalates, the requirement is proportional to the basic cost of the transaction.
-
-### Fee Levels ###
-
-_Fee levels_ represent the proportional difference between the minimum cost and the actual cost of a transaction. See the following table for a comparison:
-
-| Transaction | Minimum cost in drops | Minimum cost in Fee levels | Double cost in drops | Double cost in fee levels |
-|-------------|-----------------------|----------------------------|----------------------|---------------------------|
-| Reference transaction (most transactions) | 10 | 256 | 20 | 512 |
-| [Multi-signed transaction](reference-transaction-format.html#multi-signing) with 4 signatures | 50 | 256 | 100 | 512 |
-| [Key reset transaction](concept-transaction-cost.html#key-reset-transaction) | 0 | (Effectively infinite) | N/A | (Effectively infinite) |
-
 #### Possible Errors ####
 
 * Any of the [universal error types](#universal-errors).

reference-rippled.html

@@ -10713,7 +10713,7 @@ Connecting to 127.0.0.1:5005
 <tr>
 <td>drops.base_fee</td>
 <td>String (Integer)</td>
-<td>The transaction cost required for a <a href="#reference-transaction-cost">reference transaction</a> to be included in a ledger under minimum load, represented in drops of XRP.</td>
+<td>The transaction cost required for a <a href="concept-transaction-cost.html#reference-transaction-cost">reference transaction</a> to be included in a ledger under minimum load, represented in drops of XRP.</td>
 </tr>
 <tr>
 <td>drops.median_fee</td>
@@ -10723,12 +10723,12 @@ Connecting to 127.0.0.1:5005
 <tr>
 <td>drops.minimum_fee</td>
 <td>String (Integer)</td>
-<td>The minimum transaction cost for a <a href="#reference-transaction-cost">reference transaction</a> to be queued for a later ledger, represented in drops of XRP. If greater than <code>base_fee</code>, the transaction queue is full.</td>
+<td>The minimum transaction cost for a <a href="concept-transaction-cost.html#reference-transaction-cost">reference transaction</a> to be queued for a later ledger, represented in drops of XRP. If greater than <code>base_fee</code>, the transaction queue is full.</td>
 </tr>
 <tr>
 <td>drops.open_ledger_fee</td>
 <td>String (Integer)</td>
-<td>The minimum transaction cost that a <a href="#reference-transaction-cost">reference transaction</a> must pay to be included in the current open ledger, represented in drops of XRP.</td>
+<td>The minimum transaction cost that a <a href="concept-transaction-cost.html#reference-transaction-cost">reference transaction</a> must pay to be included in the current open ledger, represented in drops of XRP.</td>
 </tr>
 <tr>
 <td>expected_ledger_size</td>
@@ -10767,44 +10767,6 @@ Connecting to 127.0.0.1:5005
 </tr>
 </tbody>
 </table>
-<h3 id="reference-transaction-cost">Reference Transaction Cost</h3>
-<p>The "Reference Transaction" is the cheapest possible transaction, in terms of the necessary <a href="concept-transaction-cost.html">transaction cost</a>. Most transactions have the same cost as the reference transaction. Some transactions, such as <a href="reference-transaction-format.html#multi-signing">multi-signed transactions</a> require a multiple of this cost instead. When the open ledger cost escalates, the requirement is proportional to the basic cost of the transaction.</p>
-<h3 id="fee-levels">Fee Levels</h3>
-<p><em>Fee levels</em> represent the proportional difference between the minimum cost and the actual cost of a transaction. See the following table for a comparison:</p>
-<table>
-<thead>
-<tr>
-<th>Transaction</th>
-<th>Minimum cost in drops</th>
-<th>Minimum cost in Fee levels</th>
-<th>Double cost in drops</th>
-<th>Double cost in fee levels</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>Reference transaction (most transactions)</td>
-<td>10</td>
-<td>256</td>
-<td>20</td>
-<td>512</td>
-</tr>
-<tr>
-<td><a href="reference-transaction-format.html#multi-signing">Multi-signed transaction</a> with 4 signatures</td>
-<td>50</td>
-<td>256</td>
-<td>100</td>
-<td>512</td>
-</tr>
-<tr>
-<td><a href="concept-transaction-cost.html#key-reset-transaction">Key reset transaction</a></td>
-<td>0</td>
-<td>(Effectively infinite)</td>
-<td>N/A</td>
-<td>(Effectively infinite)</td>
-</tr>
-</tbody>
-</table>
 <h4 id="possible-errors-36">Possible Errors</h4>
 <ul>
 <li>Any of the <a href="#universal-errors">universal error types</a>.</li>