Merge pull request #515 from ripple/rippled_1.2.0

rippled 1.2.0 docs

content/concepts/consensus-network/transaction-queue.md

@@ -28,11 +28,15 @@ The transaction queue plays an important role in selecting the transactions that
 
 The `rippled` server uses a variety of heuristics to estimate which transactions are "likely to be included in a ledger." The current implementation uses the following rules to decide which transactions to queue:
 
-* Transactions must be properly-formed and [authorized](transaction-basics.html#authorizing-transactions) with valid signatures.
-* Transactions with an `AccountTxnID` field cannot be queued.
-* A single sending address can have at most 10 transactions queued at the same time. In order for a transaction to be queued, the sender must have enough XRP to pay all the XRP costs of all the sender's queued transactions including both the `Fee` fields and the sum of the XRP that each transaction could send. [New in: rippled 0.32.0][]
-* If a transaction affects how the sending address authorizes transactions, no other transactions from the same address can be queued behind it. [New in: rippled 0.32.0][]
-* If a transaction includes a `LastLedgerSequence` field, the value of that field must be at least **the current ledger index + 2**.
+- Transactions must be properly-formed and [authorized](transaction-basics.html#authorizing-transactions) with valid signatures.
+- Transactions with an `AccountTxnID` field cannot be queued.
+- A single sending address can have at most 10 transactions queued at the same time.
+- To queue a transaction, the sender must have enough XRP for all of the following: [Updated in: rippled 1.2.0][New in: rippled 1.2.0]
+    - Destroying the XRP [transaction cost](transaction-cost.html) as specified in the `Fee` fields of all the sender's queued transactions. The total amount among queued transactions cannot be more than the base account reserve (currently 20 XRP). (Transactions paying significantly more than the minimum transaction cost of 0.00001 XRP typically skip the queue and go straight into the open ledger.)
+    - Sending the maximum sum of XRP that all the sender's queued transactions could send.
+    - Keeping enough XRP to meet the account's [reserve requirements](reserves.html).
+- If a transaction affects how the sending address authorizes transactions, no other transactions from the same address can be queued behind it. [New in: rippled 0.32.0][]
+- If a transaction includes a `LastLedgerSequence` field, the value of that field must be at least **the current ledger index + 2**.
 
 ### Fee Averaging
 

content/concepts/decentralized-exchange/offers.md

@@ -15,6 +15,8 @@ An offer in the ledger can be fulfilled either by additional OfferCreate transac
 
 You can create an offer so long as you have at least some (any positive, nonzero amount) of the currency specified by the `TakerGets` parameter of the offer. The offer sells as much of the currency as you have, up to the `TakerGets` amount, until the `TakerPays` amount is satisfied. An offer cannot place anyone in debt.
 
+If you place an offer that crosses any offers you have existing in the ledger, the old offers are automatically canceled regardless of the amounts involved.
+
 It is possible for an offer to become temporarily or permanently _unfunded_:
 
 * If the creator no longer has any of the `TakerGets` currency.

content/concepts/introduction/xrp-ledger-overview.md

@@ -30,6 +30,8 @@ This combines qualities of physical and centralized digital money. Prior to the
 
 The XRP Ledger's system of trusted validators uses a small amount of human interaction to achieve better distribution of authority than other decentralized systems. Fully-automated systems for reaching consensus from an unknown set of participants are vulnerable to concentrations of voting power. For example, Bitcoin mining is disproportionately concentrated in places with cheap electricity. As Ripple curates a list of distinct validators operated by different entities in different jurisdictions, the XRP Ledger can become more resistant to censorship and outside pressures than proof-of-work mining. For more information on Ripple's plan to decentralize the recommended set of validators, see the  [Decentralization Strategy Update](https://ripple.com/dev-blog/decentralization-strategy-update/).
 
+For more information about the XRP Ledger's ability to detect censorship, see [Transaction Censorship Detection](transaction-censorship-detection.html).
+
 
 ## Fast, Efficient Consensus Algorithm
 [Fast, Efficient Consensus Algorithm]: #fast-efficient-consensus-algorithm

content/concepts/issued-currencies/rippling.md

@@ -4,8 +4,9 @@ In the XRP Ledger, "rippling" describes a process of atomic net settlement betwe
 
 Rippling only occurs along the [paths](paths.html) of a payment.
 
-For non-issuing accounts, rippling can be undesirable because it lets other users shift obligations between issuers of the same currency. Thus, the [NoRipple Flag](#the-noripple-flag) disables rippling on all trust lines by default, unless the account enables rippling by default by enabling the [DefaultRipple flag](#the-defaultripple-flag).
+For non-issuing accounts, rippling can be undesirable because it lets other users shift obligations between issuers of the same currency. Thus, the [NoRipple Flag](#the-noripple-flag) disables rippling on incoming trust lines by default, unless the account enables rippling by default by enabling the [DefaultRipple flag](#the-defaultripple-flag).
 
+**Caution:** If you create a trust line to another address, you must explicitly enable the tfSetNoRipple flag to block rippling on your side of that trust line.
 
 ## Example of Rippling
 
@@ -25,7 +26,7 @@ Non-issuing accounts, especially liquidity providers who may hold balances from
 
 The "NoRipple" flag is a setting on a trust line. When two trust lines both have NoRipple enabled by the same address, payments from third parties cannot "ripple" through that address on those trust lines. This protects liquidity providers from having balances shift unexpectedly between different issuers of the same currency.
 
-An account can disable NoRipple on a single trust line, which can allow rippling through any pair that includes that trust line. The account can also enable rippling globally by enabling the [DefaultRipple flag](#the-defaultripple-flag).
+An account can disable NoRipple on a single trust line, which can allow rippling through any pair that includes that trust line. The account can also enable rippling by default by enabling the [DefaultRipple flag](#the-defaultripple-flag).
 
 For example, imagine Emily has money issued by two different financial institutions, like so
 
@@ -52,7 +53,9 @@ The NoRipple flag makes certain paths invalid, so that they cannot be used to ma
 
 ## The DefaultRipple Flag
 
-The DefaultRipple flag is an account setting that enables rippling on all trust lines by default. Gateways and other currency issuers MUST enable this flag for other addresses to be able to send those the currencies among themselves.
+The DefaultRipple flag is an account setting that enables rippling on all incoming trust lines by default. Gateways and other currency issuers MUST enable this flag for their customers to be able to send those currencies to each other.
+
+The DefaultRipple setting of your account does not affect trust lines that you create; only trust lines that others open to you. If you change the DefaultRipple setting of your account, trust lines that were created before the change keep their existing NoRipple settings. You can use a [TrustSet transaction][] to change the NoRipple setting of a trust line to match your address's new default.
 
 For more information, see [DefaultRipple in 'Becoming an XRP Ledger Gateway'](become-an-xrp-ledger-gateway.html#defaultripple).
 

content/concepts/payment-system-basics/accounts/reserves.md

@@ -21,7 +21,7 @@ Many objects in the ledger are owned by a particular address, and count toward t
 
 - [Offers](offer.html) are owned by the address that placed them. Transaction processing automatically removes Offers that are fully consumed or found to be unfunded. Alternatively, the owner can cancel an Offer by sending an [OfferCancel transaction][], or by sending an [OfferCreate transaction][] that contains an `OfferSequence` parameter.
 - [Trust lines](ripplestate.html) are shared between two addresses. The owner reserve can apply to one or both of the addresses, depending on whether the fields that address controls are in their default state. See [Contributing to the Owner Reserve](ripplestate.html#contributing-to-the-owner-reserve) for details.
-- A single [SignerList](signerlist.html) counts as 3 to 10 objects for purposes of the owner reserve, depending on how many members it has. See also: [SignerLists and Reserves](signerlist.html#signerlists-and-reserves).
+- Without the [MultiSignReserve amendment](known-amendments.html#multisignreserve), a single [SignerList](signerlist.html) counts as 3 to 10 objects for purposes of the owner reserve, depending on how many members it has. With the [MultiSignReserve amendment](known-amendments.html#multisignreserve) enabled, a single SignerList counts as 1 object for purposes of the owner reserve, regardless of the number of members it has. See also: [SignerLists and Reserves](signerlist.html#signerlists-and-reserves).
 - [Held Payments (Escrow)](escrow-object.html) are owned by the address that placed them.
 - [Payment Channels](use-payment-channels.html) are owned by the address that created them.
 - [Owner directories](directorynode.html) list all the ledger objects that contribute to an address's owner reserve. However, the owner directory itself does not count towards the reserve.

content/concepts/the-rippled-server/ledger-history/history-sharding.md

@@ -27,7 +27,8 @@ The history of all ledgers is shared by servers agreeing to keep particular rang
 ## See Also
 
 - [Configure History Sharding](configure-history-sharding.html)
-<!--{# - [download_shard method][] #}-->
+- [download_shard method][]
+- [crawl_shards method][]
 
 <!--{# common link defs #}-->
 {% include '_snippets/rippled-api-links.md' %}			

content/concepts/the-rippled-server/transaction-censorship-detection.md

@@ -0,0 +1,61 @@
+# Transaction Censorship Detection
+
+[New in: rippled 1.2.0][]
+
+The XRP Ledger is designed to be [censorship resistant](xrp-ledger-overview.html#censorship-resistant-transaction-processing). In support of this design, the XRP Ledger provides an automated transaction censorship detector that is available on all `rippled` servers, enabling all participants to see if censorship is affecting the network.
+
+While a `rippled` server is in sync with the network, the detector tracks all transactions that, in the view of the `rippled` server, should have been accepted in the last round of [consensus](intro-to-consensus.html) and included in the last validated ledger. The detector issues log messages of increasing severity for transactions that have not been included in a validated ledger after several rounds of consensus.
+
+
+
+## How It Works
+
+At a high-level, here’s how the transaction censorship detector works:
+
+1. The detector adds all transactions in a `rippled` server's initial consensus proposal to the tracker.
+
+2. At the close of the consensus round, the detector removes all transactions included in the resulting validated ledger from the tracker.
+
+3. The detector issues a [warning message](#example-warning-message) in the log for any transaction that remains in the tracker for 15 ledgers, surfacing it as a potentially censored transaction. The transaction's presence in the tracker at this time means that is has not been included in a validated ledger after 15 rounds of consensus. If the transaction remains in the tracker for another 15 ledgers, the detector issues another warning message in the log.
+
+    For as long as the transaction remains in the tracker, the detector continues to issue a warning message in the log every 15 ledgers, for up to five warning messages. After the fifth warning message, the detector issues a final [error message](#example-error-message) in the log and then stops issuing warning and error messages.
+
+    If you see these messages in your `rippled` server log, you should investigate why other servers are failing to include the transaction, starting with the assumption that the cause is more likely to be a [false positive](#potential-false-positives) (innocent bug) than malicious censorship.
+
+
+
+## Example Warning Message
+
+This is an example warning message issued by the transaction censorship detector after transaction E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7 remained in the tracker for 15 ledgers, from ledger 18851530 to ledger 18851545.
+
+```text
+LedgerConsensus:WRN Potential Censorship: Eligible tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7, which we are tracking since ledger 18851530 has not been included as of ledger 18851545.
+```
+
+
+## Example Error Message
+
+This is an example error message issued by the transaction censorship detector after transaction E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7 remained in the tracker for 75 ledgers (5 sets of 15 ledgers), from ledger 18851530 to ledger 18851605.
+
+```text
+LedgerConsensus:ERR Potential Censorship: Eligible tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7, which we are tracking since ledger 18851530 has not been included as of ledger 18851605. Additional warnings suppressed.
+```
+
+
+## Potential False Positives
+
+The transaction censorship detector may issue false positives in certain scenarios. In this case, a false positive means that the detector has flagged a transaction that has remained in the tracker for 15 ledgers or more, but for innocent reasons.
+
+Here are some scenarios that could cause the detector to issue false positive messages:
+
+- Your `rippled` server is running a build with code that is different from the rest of the network. This may cause your `rippled` server to apply transactions differently, resulting in false positives. While this type of false positive is unlikely, in general, it is crucial that you run the correct version of `rippled`.
+
+- Your `rippled` server is out of sync with the network and has not yet realized it.
+
+- `rippled` servers in the network, including possibly your own server, are being impacted by a class of bug that causes `rippled` servers to inconsistently relay transactions to other `rippled` servers in the network.
+
+    Currently, there are no known bugs that cause this unexpected behavior. However, if you see the impact of what you suspect is a bug, consider reporting it to the [Ripple Bug Bounty](https://ripple.com/bug-bounty/) program.
+
+
+
+{% include '_snippets/rippled_versions.md' %}