From 0a4f11b3eb5f803b6c3a45604d55c428742074dc Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa Date: Tue, 29 Jan 2019 17:39:26 -0800 Subject: [PATCH 1/4] first draft --- .../introduction/xrp-ledger-overview.md | 2 + .../transaction-censorship-detection.md | 42 +++++++++++++++++++ dactyl-config.yml | 9 ++++ 3 files changed, 53 insertions(+) create mode 100644 content/concepts/the-rippled-server/transaction-censorship-detection.md diff --git a/content/concepts/introduction/xrp-ledger-overview.md b/content/concepts/introduction/xrp-ledger-overview.md index 6f2a0ea8b5..4c05b3529a 100644 --- a/content/concepts/introduction/xrp-ledger-overview.md +++ b/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). ***TODO: appropriate here?*** + ## Fast, Efficient Consensus Algorithm [Fast, Efficient Consensus Algorithm]: #fast-efficient-consensus-algorithm diff --git a/content/concepts/the-rippled-server/transaction-censorship-detection.md b/content/concepts/the-rippled-server/transaction-censorship-detection.md new file mode 100644 index 0000000000..1ddaef1f4e --- /dev/null +++ b/content/concepts/the-rippled-server/transaction-censorship-detection.md @@ -0,0 +1,42 @@ +# Transaction Censorship Detection + +The XRP Ledger is designed to be [censorship resistant](xrp-ledger-overview.html#censorship-resistant-transaction-processing). Any attempt to censor transactions requires coordinated action by a majority of the XRP Ledger network's validators. + +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. + +A `rippled` server is considered to be in sync if it meets the following criteria: ***TODO: Is this info useful or overkill?*** + +- It has a `server_state` of `full` or `proposing`. +- It has the network's last fully validated ledger. +- It has good connectivity. +- It is tracking the current consensus round. + +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 may want to investigate, off-ledger, why other `rippled` servers are failing to include the transaction. + + + +## 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. + + 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. + + Potential Censorship: Eligible tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7, which we are tracking since ledger 18851530 has not been included as of ledger 18851605. Additional warnings suppressed. diff --git a/dactyl-config.yml b/dactyl-config.yml index 12fbfa5a1f..20c7109326 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -586,6 +586,15 @@ pages: targets: - local + - md: concepts/the-rippled-server/transaction-censorship-detection.md + html: transaction-censorship-detection.html + funnel: Docs + doc_type: Concepts + category: The rippled Server + blurb: XRP Ledger provides an automated transaction censorship detector that is available on all rippled servers. + targets: + - local + # Tutorials -------------------------------------------------------------------- - name: Tutorials From f6fc7bbfb000b4931d9693cfc9b636ecc3431a7d Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa Date: Wed, 30 Jan 2019 14:36:51 -0800 Subject: [PATCH 2/4] inc'd feedback --- .../introduction/xrp-ledger-overview.md | 2 +- .../transaction-censorship-detection.md | 34 +++++++++++++------ .../understanding-log-messages.md | 4 +++ 3 files changed, 29 insertions(+), 11 deletions(-) diff --git a/content/concepts/introduction/xrp-ledger-overview.md b/content/concepts/introduction/xrp-ledger-overview.md index 4c05b3529a..4ad95e8a09 100644 --- a/content/concepts/introduction/xrp-ledger-overview.md +++ b/content/concepts/introduction/xrp-ledger-overview.md @@ -30,7 +30,7 @@ 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). ***TODO: appropriate here?*** +For more information about the XRP Ledger's ability to detect censorship, see [Transaction Censorship Detection](transaction-censorship-detection.html). ## Fast, Efficient Consensus Algorithm diff --git a/content/concepts/the-rippled-server/transaction-censorship-detection.md b/content/concepts/the-rippled-server/transaction-censorship-detection.md index 1ddaef1f4e..d0f0500cab 100644 --- a/content/concepts/the-rippled-server/transaction-censorship-detection.md +++ b/content/concepts/the-rippled-server/transaction-censorship-detection.md @@ -1,17 +1,14 @@ # Transaction Censorship Detection -The XRP Ledger is designed to be [censorship resistant](xrp-ledger-overview.html#censorship-resistant-transaction-processing). Any attempt to censor transactions requires coordinated action by a majority of the XRP Ledger network's validators. +[New in: rippled 1.2.0][] -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. +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. -A `rippled` server is considered to be in sync if it meets the following criteria: ***TODO: Is this info useful or overkill?*** -- It has a `server_state` of `full` or `proposing`. -- It has the network's last fully validated ledger. -- It has good connectivity. -- It is tracking the current consensus round. + +## How It Works At a high-level, here’s how the transaction censorship detector works: @@ -23,7 +20,7 @@ At a high-level, here’s how the transaction censorship detector works: 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 may want to investigate, off-ledger, why other `rippled` servers are failing to include the transaction. + If you see these messages in your `rippled` server log, first verify that the messages are not [false positives](#potential-false-positives). If they are not false positives, you may want to investigate, off-ledger, why other `rippled` servers are failing to include the transaction. @@ -31,7 +28,7 @@ At a high-level, here’s how the transaction censorship detector works: 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. - Potential Censorship: Eligible tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7, which we are tracking since ledger 18851530 has not been included as of ledger 18851545. + LedgerConsensus:WRN Potential Censorship: Eligible tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7, which we are tracking since ledger 18851530 has not been included as of ledger 18851545. @@ -39,4 +36,21 @@ This is an example warning message issued by the transaction censorship detector 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. - Potential Censorship: Eligible tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7, which we are tracking since ledger 18851530 has not been included as of ledger 18851605. Additional warnings suppressed. + 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. + +- Your `rippled` server is being impacted by a class of bug that causes `rippled` servers to inconsistently relay transactions to other `rippled` servers in the network. + + +{% include '_snippets/rippled_versions.md' %} diff --git a/content/tutorials/manage-the-rippled-server/troubleshooting/understanding-log-messages.md b/content/tutorials/manage-the-rippled-server/troubleshooting/understanding-log-messages.md index 9e79c7218f..f7d4826063 100644 --- a/content/tutorials/manage-the-rippled-server/troubleshooting/understanding-log-messages.md +++ b/content/tutorials/manage-the-rippled-server/troubleshooting/understanding-log-messages.md @@ -154,6 +154,10 @@ This is not strictly a problem, but if you want to acquire ledger history faster s2.ripple.com 51235 ``` +## Potential Censorship + +The transaction censorship detector issues log messages when it detects potential transaction censorship. For more information about the detector and these log messages, see [Transaction Censorship Detection](transaction-censorship-detection.html). + From ae75451d5a1b5a15afbd1986272f2761fbfe688d Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa Date: Wed, 30 Jan 2019 21:26:13 -0800 Subject: [PATCH 3/4] inc'd feedback --- .../transaction-censorship-detection.md | 14 ++++++++------ .../troubleshooting/understanding-log-messages.md | 14 +++++++++++++- 2 files changed, 21 insertions(+), 7 deletions(-) diff --git a/content/concepts/the-rippled-server/transaction-censorship-detection.md b/content/concepts/the-rippled-server/transaction-censorship-detection.md index d0f0500cab..c13caa3b35 100644 --- a/content/concepts/the-rippled-server/transaction-censorship-detection.md +++ b/content/concepts/the-rippled-server/transaction-censorship-detection.md @@ -20,7 +20,7 @@ At a high-level, here’s how the transaction censorship detector works: 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, first verify that the messages are not [false positives](#potential-false-positives). If they are not false positives, you may want to investigate, off-ledger, why other `rippled` servers are failing to include the transaction. + 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. @@ -28,16 +28,18 @@ At a high-level, here’s how the transaction censorship detector works: 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. - LedgerConsensus:WRN Potential Censorship: Eligible tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7, which we are tracking since ledger 18851530 has not been included as of 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. - 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. - +```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 @@ -50,7 +52,7 @@ Here are some scenarios that could cause the detector to issue false positive me - Your `rippled` server is out of sync with the network and has not yet realized it. -- Your `rippled` server is being impacted by a class of bug that causes `rippled` servers to inconsistently relay transactions to other `rippled` servers in the network. +- `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. {% include '_snippets/rippled_versions.md' %} diff --git a/content/tutorials/manage-the-rippled-server/troubleshooting/understanding-log-messages.md b/content/tutorials/manage-the-rippled-server/troubleshooting/understanding-log-messages.md index f7d4826063..af9bd7cc09 100644 --- a/content/tutorials/manage-the-rippled-server/troubleshooting/understanding-log-messages.md +++ b/content/tutorials/manage-the-rippled-server/troubleshooting/understanding-log-messages.md @@ -154,10 +154,22 @@ This is not strictly a problem, but if you want to acquire ledger history faster s2.ripple.com 51235 ``` + ## Potential Censorship -The transaction censorship detector issues log messages when it detects potential transaction censorship. For more information about the detector and these log messages, see [Transaction Censorship Detection](transaction-censorship-detection.html). +Log messages such as the following are issued when the XRP Ledger detects potential transaction censorship. For more information about these log messages and the transaction censorship detector, see [Transaction Censorship Detection](transaction-censorship-detection.html). +**Warning Message** + +```text +LedgerConsensus:WRN Potential Censorship: Eligible tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7, which we are tracking since ledger 18851530 has not been included as of ledger 18851545. +``` + +**Error Message** + +```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. +``` From 5b8924af6446796203d24d0ebd0830ac96fcf5ad Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa Date: Mon, 4 Feb 2019 14:01:38 -0800 Subject: [PATCH 4/4] bug bounty ref --- .../the-rippled-server/transaction-censorship-detection.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/content/concepts/the-rippled-server/transaction-censorship-detection.md b/content/concepts/the-rippled-server/transaction-censorship-detection.md index c13caa3b35..1431dcf6f2 100644 --- a/content/concepts/the-rippled-server/transaction-censorship-detection.md +++ b/content/concepts/the-rippled-server/transaction-censorship-detection.md @@ -54,5 +54,8 @@ Here are some scenarios that could cause the detector to issue false positive me - `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' %}