ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-21 12:15:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1677 from XRPLF/update-amendments-concept

Browse Source 
Update Amendments Concept Info
This commit is contained in:
oeggert
2023-01-18 12:47:23 -08:00
committed by GitHub
parent ec5f87fb5d bcb28a3b58
commit af68722548
18 changed files with 354 additions and 252 deletions
Download Patch File Download Diff File Expand all files Collapse all files

237
content/concepts/consensus-network/amendments/amendments.md
View File

@@ -7,246 +7,71 @@ labels:
--- ---
# Amendments # Amendments
[Introduced in: rippled 0.31.0][] The amendment system uses the consensus process to approve any changes that affect transaction processing on the XRP Ledger. Fully-functional, transaction process changes are introduced as amendments; validators then vote on these changes. If an amendment receives more than 80% support for two weeks, the amendment passes and the change applies permanently to all subsequent ledger versions. Disabling a passed amendment requires a new amendment to do so.
The Amendments system provides a means of introducing new features to the decentralized XRP Ledger network without causing disruptions. The amendments system works by utilizing the core consensus process of the network to approve any changes by showing continuous support before those changes go into effect. An amendment normally requires **more than 80% support for two weeks** before it can apply. **Note:** Bug fixes that change transaction processes also require amendments.
When an Amendment has been enabled, it applies permanently to all ledger versions after the one that included it. You cannot disable an Amendment, unless you introduce a new Amendment to do so.
For a complete list of known amendments, their statuses, and IDs, see: [Known Amendments](known-amendments.html).
## Background
Any changes to transaction processing could cause servers to build a different ledger with the same set of transactions. If some _validators_ (`rippled` servers [participating in consensus](rippled-server-modes.html#validators)) have upgraded to a new version of the software while other validators use the old version, this could cause anything from minor inconveniences to full outages. In the minor case, a minority of servers spend more time and bandwidth fetching the actual consensus ledger because they cannot build it using the transaction processing rules they already know. In the worst case, [the consensus process][] might be unable to validate new ledger versions because servers with different rules could not reach a consensus on the exact ledger to build.
Amendments solve this problem, so that new features can be enabled only when enough validators support those features.
Users and businesses who rely on the XRP Ledger can also use Amendments to provide advance notice of changes in transaction processing that might affect their business. However, API changes that do not impact transaction processing or [the consensus process][] do not need Amendments.
[the consensus process]: consensus.html
## About Amendments
An amendment is a fully-functional feature or change, waiting to be enabled by the peer-to-peer network as a part of the consensus process. A `rippled` server that wants to use an amendment has code for two modes: without the amendment (old behavior) and with the amendment (new behavior).
Every amendment has a unique identifying hex value and a short name. The short name is for human use, and is not used in the amendment process. Two servers can support the same amendment ID while using different names to describe it. An amendment's name is not guaranteed to be unique.
By convention, an amendment's ID should be the SHA-512Half hash of the amendment's short name.
<!-- TODO: Move this to an amendment tutorial.
Every amendment has a unique identifying hex value and a short name. The short name is for readability only; servers can use different names to describe the same amendement ID, and the names aren't guaranteed to be unique. The amendment ID should be the SHA-512Half hash of the amendment's short name.
-->
## Amendment Process ## Amendment Process
Every 256th ledger is called a "flag" ledger. The process of approving an amendment starts in the ledger version immediately before the flag ledger. When `rippled` validator servers send validation messages for that ledger, those servers also submit votes in favor of specific amendments. If a validator does not vote in favor of an amendment, that is the same as voting against the amendment. However, the `rippled` reference implementation has a default vote for each known amendment, which determines how a validator votes on any amendment for which that validator does not have an explicit configuration. ([Fee Voting](fee-voting.html) also occurs around flag ledgers.) [Updated in: rippled 1.8.1][] Every 256th ledger is called a **flag** ledger. The flag ledger doesn't have special contents, but the amendment process happens around it.
The flag ledger itself has no special contents. However, during that time, the servers look at the votes of the validators they trust, and decide whether to insert an [`EnableAmendment` pseudo-transaction](enableamendment.html) into the following ledger. The flags of an EnableAmendment pseudo-transaction show what the server thinks happened: 1. **Flag Ledger -1:** When `rippled` validators send validation messages, they also submit their amendment votes.
2. **Flag Ledger:** Servers interpret the votes from trusted validators.
3. **Flag Ledger +1:** Servers insert an `EnableAmendment` pseudo-transaction and flag based on what they think happened:
* The `tfGotMajority` flag means the amendment has more than 80% support.
* The `tfLostMajority` flag means support for the amendment has decreased to 80% or less.
* No flag means the amendment is enabled.
* The `tfGotMajority` flag means that support for the amendment has increased to more than 80% of trusted validators. **Note:** It's possible for an amendment to lose 80% support on the same ledger it reaches the required two-week period to be enabled. In these cases, an `EnableAmendment` pseudo-transactions is added for both scenarios, but the amendment is ultimately enabled.
* The `tfLostMajority` flag means that support for the amendment has decreased to 80% of trusted validators or less.
* An EnableAmendment pseudo-transaction with no flags means that support for the amendment has been enabled. (The change in transaction processing applies to every ledger after this one.)
A server only inserts the pseudo-transaction to enable an amendment if all of the following conditions are met: 4. **Flag Ledger +2:** Enabled amendments apply to transactions on this ledger onwards.
* The amendment has not already been enabled.
* A previous ledger includes an EnableAmendment pseudo-transaction for this amendment with the `tfGotMajority` flag enabled.
* The previous ledger in question is an ancestor of the current ledger.
* The previous ledger in question has a close time that is at least **two weeks** before the close time of the latest flag ledger.
* There are no EnableAmendment pseudo-transactions for this amendment with the `tfLostMajority` flag enabled in the consensus ledgers between the `tfGotMajority` pseudo-transaction and the current ledger.
Theoretically, a `tfLostMajority` EnableAmendment pseudo-transaction could be included in the same ledger as the pseudo-transaction to enable an amendment. In this case, the pseudo-transaction with the `tfLostMajority` pseudo-transaction has no effect.
## Amendment Voting ## Amendment Voting
Each version of `rippled` is compiled with a list of known amendments and the code to implement those amendments. Operators of `rippled` validators [configure their servers](configure-amendment-voting.html) to vote in favor or against each inactive amendment. Server operators can change their votes at any time. If the operator does not choose a setting for a particular amendment, the server uses a default vote which is defined in the source code. The default can change in new software releases. For example, version 2.0 of the server might understand a new amendment but vote against it by default; then version 2.1 of the server might vote in favor of the same amendment by default. [Updated in: rippled 1.8.1][] Each version of `rippled` is compiled with a list of known amendments and the code to implement those amendments. Operators of `rippled` validators configure their servers to vote on each amendment and can change it at any time. If the operator doesn't choose a vote, the server uses a default vote defined by the source code.
To become enabled, an amendment must be supported by more than 80% of trusted validators continuously for two weeks. If support for an amendment goes below 80% of trusted validators, the amendment is temporarily rejected. The two week period starts over if the amendment regains support of more than 80% of trusted validators. (This can occur if validators vote differently, or if there is a change in which validators are trusted.) An amendment can gain and lose a majority any number of times before it becomes permanently enabled. **Note:** The default vote can change between software releases. [Updated in: rippled 1.8.1][]
An amendment cannot be permanently rejected, but it becomes very unlikely for an amendment to become enabled if new versions of `rippled` do not have the amendment in their known amendments list. Amendments that have had their source code removed without becoming enabled are considered "Vetoed" by the network. Amendments must maintain two weeks of support from more than 80% of trusted validators to be enabled. If support drops below 80%, the amendment is temporarily rejected, and the two week period restarts. Amendments can gain and lose a majority any number of times before it becomes permanently enabled.
As with all aspects of the consensus process, amendment votes are only taken into account by servers that trust the validators sending those votes. <!-- TODO: link an explanation of validator list publishers when one's ready --> Amendments that have had their source code removed without being enabled are considered **Vetoed** by the network.
For information on how to configure your server's amendment votes, see [Configure Amendment Voting](configure-amendment-voting.html). [Updated in: rippled 1.7.0][]
## Amendment Blocked ## Amendment Blocked Servers
When an amendment gets enabled for the network after the voting process, servers running earlier versions of `rippled` that do not know about the amendment become "amendment blocked" because they no longer understand the rules of the network. Servers that are amendment blocked: Amendment blocking is a security feature to protect the accuracy of XRP Ledger data. When an amendment is enabled, servers running earlier versions of `rippled` without the amendment's source code no longer understand the rules of the network. Rather than guess and misinterpret ledger data, these servers become **amendment blocked** and can't:
* Cannot determine the validity of a ledger * Determine the validity of a ledger.
* Cannot submit or process transactions * Submit or process transactions.
* Do not participate in the consensus process * Participate in the consensus process.
* Do not vote on future amendments * Vote on future amendments.
Becoming amendment blocked is a security feature to protect applications that depend on XRP Ledger data. Rather than guessing and maybe misinterpreting a ledger after new rules have been applied, `rippled` reports that it does not know the state of the ledger because it does not know how the amendment works. The voting configuration of a `rippled` server has no impact on it becoming amendment blocked. A `rippled` server always follows the amendments enabled by the rest of the network, so blockages are based solely on having the code to understand rule changes. This means you can also become amendment blocked if you connect your server to a parallel network with different amendments enabled. For example, the XRP Ledger Devnet typically has experimental amendments enabled. If you are using the latest production release, your server likely won't have the code for those experimental amendments.
The amendments that a `rippled` server is configured to vote for or against have no impact on whether the server becomes amendment blocked. A `rippled` server always follows the set of amendments enabled by the rest of the network, to the extent possible. A server only becomes amendment blocked if an enabled amendment is not included in the amendment definitions compiled into the server's source code -- in other words, if the amendment is newer than the server. You can unblock amendment blocked servers by upgrading to the newest version of `rippled`.
If your server is amendment blocked, you must [upgrade to a new version](install-rippled.html) to sync with the network.
It is also possible to be amendment blocked because you connected your server to a [parallel network](parallel-networks.html) that has different amendments enabled. For example, the XRP Ledger Devnet typically has upcoming and experimental amendments enabled. If you are using the latest production release, your server is likely to be amendment blocked when connecting to Devnet. You could resolve this issue by upgrading to an unstable pre-release or nightly build, or you could [connect to a different network such as Testnet](connect-your-rippled-to-the-xrp-test-net.html) instead.
### How to Tell If Your `rippled` Server Is Amendment Blocked ## Retiring Amendments
One of the first signs that your `rippled` server is amendment blocked is an `amendmentBlocked` error that is returned [when you submit a transaction](submit.html). Here's an example `amendmentBlocked` error: When amendments are enabled, the source code for pre-amendment behaviors remain in `rippled`. While there are use-cases for keeping old code, such as reconstructing ledger outcomes for verification, tracking amendments and legacy code adds complexity over time.
```json The [XRP Ledger Standard 11d](https://github.com/XRPLF/XRPL-Standards/discussions/19) defines a process for retiring old amendments and associated pre-amendment code. After an amendment has been enabled on the Mainnet for two years, it can be retired. Retiring an amendment makes it part of the core protocol unconditionally; it's no longer tracked or treated as an amendment, and all pre-amendment code is removed.
{
"result":{
"error":"amendmentBlocked",
"error_code":14,
"error_message":"Amendment blocked, need upgrade.",
"request":{
"command":"submit",
"tx_blob":"479H0KQ4LUUXIHL48WCVN0C9VD7HWSX0MG1UPYNXK6PI9HLGBU2U10K3HPFJSROFEG5VD749WDPHWSHXXO72BOSY2G8TWUDOJNLRTR9LTT8PSOB9NNZ485EY2RD9D80FLDFRBVMP1RKMELILD7I922D6TBCAZK30CSV6KDEDUMYABE0XB9EH8C4LE98LMU91I9ZV2APETJD4AYFEN0VNMIT1XQ122Y2OOXO45GJ737HHM5XX88RY7CXHVWJ5JJ7NYW6T1EEBW9UE0NLB2497YBP9V1XVAEK8JJYVRVW0L03ZDXFY8BBHP6UBU7ZNR0JU9GJQPNHG0DK86S4LLYDN0BTCF4KWV2J4DEB6DAX4BDLNPT87MM75G70DFE9W0R6HRNWCH0X075WHAXPSH7S3CSNXPPA6PDO6UA1RCCZOVZ99H7968Q37HACMD8EZ8SU81V4KNRXM46N520S4FVZNSJHA"
},
"status":"error"
}
}
```
The following `rippled` log message also indicates that your server is amendment blocked:
```
2018-Feb-12 19:38:30 LedgerMaster:ERR One or more unsupported amendments activated: server blocked.
```
If you are on `rippled` version 0.80.0+, you can verify that your `rippled` server is amendment blocked using the [`server_info`](server_info.html) command. In the response, look for `result.info.amendment_blocked`. If `amendment_blocked` is set to `true`, your server is amendment blocked.
**Example JSON-RPC Response:**
```json
{
"result": {
"info": {
"amendment_blocked": true,
"build_version": "0.80.1",
"complete_ledgers": "6658438-6658596",
"hostid": "ip-10-30-96-212.us-west-2.compute.internal",
"io_latency_ms": 1,
"last_close": {
"converge_time_s": 2,
"proposers": 10
},
...
},
"status": "success"
}
}
```
If your server is not amendment blocked, the `amendment_blocked` field is not returned in the response.
**Caution:** `rippled` versions older than 0.80.0 do not include the `amendment_blocked` field, even if your server is amendment blocked.
### How to Unblock an Amendment-Blocked `rippled` Server
Upgrade to the `rippled` version that supports the amendments that are causing your server to be amendment blocked. Ripple recommends that you [upgrade to the newest `rippled` version](install-rippled.html) to unblock your server and enable it to sync with the network again.
Depending on the scenario, you may be able to (and want to) unblock your server by upgrading to a `rippled` version that is older than the newest version. This is possible if the older version supports the amendments that are blocking your `rippled` server.
**Warning:** If the newest `rippled` version provides security or other urgent fixes, you should upgrade to the newest version as soon as possible.
To determine if you can unblock your `rippled` server by upgrading to a version older than the newest version, find out which features are blocking your server and then look up the `rippled` version that supports the blocking features.
To find out which features are blocking your `rippled` server, use the [`feature`](feature.html) admin command. Look for features that have `"enabled" : true` and `"supported" : false`. These values for a feature mean that the amendment is currently enabled (required) in the latest ledger, but your server does not know how to support, or apply, the amendment.
**Example JSON-RPC Response:**
```json
{
"result": {
"features": {
"07D43DCE529B15A10827E5E04943B496762F9A88E3268269D69C44BE49E21104": {
"enabled": true,
"name": "Escrow",
"supported": true,
"vetoed": false
},
"08DE7D96082187F6E6578530258C77FAABABE4C20474BDB82F04B021F1A68647": {
"enabled": true,
"name": "PayChan",
"supported": true,
"vetoed": false
},
"1562511F573A19AE9BD103B5D6B9E01B3B46805AEC5D3C4805C902B514399146": {
"enabled": false,
"name": "CryptoConditions",
"supported": true,
"vetoed": false
},
"157D2D480E006395B76F948E3E07A45A05FE10230D88A7993C71F97AE4B1F2D1": {
"enabled": true,
"supported": false,
"vetoed": false
},
...
"67A34F2CF55BFC0F93AACD5B281413176FEE195269FA6D95219A2DF738671172": {
"enabled": true,
"supported": false,
"vetoed": false
},
...
"F64E1EABBE79D55B3BB82020516CEC2C582A98A6BFE20FBE9BB6A0D233418064": {
"enabled": true,
"supported": false,
"vetoed": false
}
},
"status": "success"
}
}
```
In this example, conflicts with the following features are causing your `rippled` server to be amendment blocked:
* `157D2D480E006395B76F948E3E07A45A05FE10230D88A7993C71F97AE4B1F2D1`
* `67A34F2CF55BFC0F93AACD5B281413176FEE195269FA6D95219A2DF738671172`
* `F64E1EABBE79D55B3BB82020516CEC2C582A98A6BFE20FBE9BB6A0D233418064`
To look up which `rippled` version supports these features, see [Known Amendments](known-amendments.html).
## Testing Amendments
If you want to see how `rippled` behaves with an amendment enabled, before that amendment gets enabled on the production network, you can run use `rippled`'s config file to forcibly enable a feature. This is intended for development purposes only.
Because other members of the consensus network probably do not have the feature enabled, you should not use this feature while connecting to the production network. While testing with features forcibly enabled, you should run `rippled` in [stand-alone mode][].
To forcibly enable a feature, add a `[features]` stanza to your `rippled.cfg` file. In this stanza, add the short names of the features to enable, one per line. For example:
```
[features]
MultiSign
TrustSetAuth
```
## Retiring Legacy Code
After an amendment has become enabled, it can never be disabled. (To reverse protocol changes, it would be necessary to create a new amendment.) However, separate ledger chains, such as [test networks](parallel-networks.html) or [stand-alone mode](rippled-server-modes.html#stand-alone-mode) can have different sets of amendments applied. The pre-amendment code may continue to run in those cases, and the software must work with an increasing number of combinations of amendments that may or may not be enabled on any given test network.
Rather than maintain the source code for all old behavior indefinitely, [XRP Ledger Standard 11d](https://github.com/XRPLF/XRPL-Standards/discussions/19) defines a process for retiring the pre-amendment code. In this process, amendments that have been enabled on the XRP Ledger Mainnet can have the pre-amendment code removed, making them apply unconditionally as part of the XRP Ledger protocol. For the XRP Ledger's [reference server implementation](xrpl-servers.html), the developers periodically chooses a cutoff date **at least 2 years** in the past, and retire pre-amendment source code for amendments that were enabled on the network before the cutoff date. <!-- SPELLING_IGNORE: 11d -->
When pre-amendment code has been retired, the server follows the amended logic for all transactions at all times. As a result, the server is no longer guaranteed to produce historically-accurate results if you try to replay ledgers older than the cutoff date. The server prints a warning if you try to [load and replay a ledger](load-a-saved-ledger-in-stand-alone-mode.html) that is older than the cutoff date. To produce historically-accurate results, you must compile or download an old server binary that has the legacy code. <!-- STYLE_OVERRIDE: accurate -->
## See Also ## See Also
- **Concepts:** - **Concepts:**
- [Known Amendments List](known-amendments.html)
- [Introduction to Consensus](intro-to-consensus.html) - [Introduction to Consensus](intro-to-consensus.html)
- **Tutorials:** - **Tutorials:**
- [Run rippled as a Validator](run-rippled-as-a-validator.html) - [Run rippled as a Validator](run-rippled-as-a-validator.html)
- [Configure Amendment Voting](configure-amendment-voting.html)
- [Contribute Code to the XRP Ledger](contribute-code.html) - [Contribute Code to the XRP Ledger](contribute-code.html)
- **References:**
- [Amendments ledger object](amendments-object.html)
- [EnableAmendment pseudo-transaction][]
- [feature method][]
- [server_info method][]
<!--{# common link defs #}--> <!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %} {% include '_snippets/rippled-api-links.md' %}

16
content/concepts/xrpl-servers/rippled-server-modes.md
View File

@@ -81,28 +81,18 @@ Most notably, reporting mode servers do not report pending, non-validated ledger
## Stand-Alone Mode ## Stand-Alone Mode
In stand-alone mode, the server operates without attempting to connect to the peer-to-peer network or follow the consensus process. The server still provides API access as normal and uses the same transaction processing engine, so you can test `rippled` behavior without being tied to the live network. For example, you can: In stand-alone mode, the server operates without connecting to the network and participating in the consensus process. Without the consensus process, you have to manually advance the ledger and no distinction is made between "closed" and "validated" ledgers. However, the server still provides API access and processes transactions the same. This enables you to:
- [Test the effects of Amendments](amendments.html#testing-amendments) before those Amendments have gone into effect across the decentralized network. - [Test the effects of Amendments](test-amendments.html) before those Amendments have gone into effect across the decentralized network.
- [Create a new genesis ledger](start-a-new-genesis-ledger-in-stand-alone-mode.html) from scratch. - [Create a new genesis ledger](start-a-new-genesis-ledger-in-stand-alone-mode.html) from scratch.
- [Load an existing ledger version](load-a-saved-ledger-in-stand-alone-mode.html) from disk, then replay specific transactions to re-create their outcomes or test other possibilities. - [Load an existing ledger version](load-a-saved-ledger-in-stand-alone-mode.html) from disk, then replay specific transactions to re-create their outcomes or test other possibilities.
**Caution:** In stand-alone mode, you must [manually advance the ledger](advance-the-ledger-in-stand-alone-mode.html).
## See Also ## See Also
- **References:**
- [Commandline Usage Reference](commandline-usage.html) - Detailed information on command-line options for all `rippled` server modes.
- [ledger_accept method][] - Manually advance the ledger in stand-alone mode.
- [feature method][] - Check [amendments](amendments.html) currently known and enabled.
- **Tutorials:** - **Tutorials:**
- [Configure `rippled`](configure-rippled.html) - [Configure `rippled`](configure-rippled.html)
- [Run `rippled` as a Validator](run-rippled-as-a-validator.html) - [Use rippled in Stand-Alone Mode](use-stand-alone-mode.html)
- [Use rippled in Stand-Alone Mode](use-stand-alone-mode.html):
- [Start a New Genesis Ledger in Stand-Alone Mode](start-a-new-genesis-ledger-in-stand-alone-mode.html)
- [Load a Saved Ledger in Stand-Alone Mode](load-a-saved-ledger-in-stand-alone-mode.html)
- [Advance the Ledger in Stand-Alone Mode](advance-the-ledger-in-stand-alone-mode.html)
<!--{# common link defs #}--> <!--{# common link defs #}-->

2
content/references/http-websocket-apis/admin-api-methods/status-and-debugging-methods/feature.md
View File

@@ -187,7 +187,7 @@ The response follows the [standard format][], with a successful result containin
|:------------|:--------|:-----------------------------------------------------| |:------------|:--------|:-----------------------------------------------------|
| `enabled` | Boolean | Whether this amendment is currently enabled in the latest ledger. | | `enabled` | Boolean | Whether this amendment is currently enabled in the latest ledger. |
| `name` | String | (May be omitted) The human-readable name for this amendment, if known. | | `name` | String | (May be omitted) The human-readable name for this amendment, if known. |
| `supported` | Boolean | Whether the server knows how to apply this amendment. If this field is set to `false` (the server does not know how to apply this amendment) and `enabled` is set to `true` (this amendment is enabled in the latest ledger), this amendment may cause your server to be [amendment blocked](amendments.html#amendment-blocked). | | `supported` | Boolean | Whether the server knows how to apply this amendment. If this field is set to `false` (the server does not know how to apply this amendment) and `enabled` is set to `true` (this amendment is enabled in the latest ledger), this amendment may cause your server to be [amendment blocked](amendments.html#amendment-blocked-servers). |
| `vetoed` | Boolean | Whether the server has been instructed to vote against this amendment. | | `vetoed` | Boolean | Whether the server has been instructed to vote against this amendment. |
**Caution:** The `name` for an amendment does not strictly indicate what that amendment does. The name is not guaranteed to be unique or consistent across servers. **Caution:** The `name` for an amendment does not strictly indicate what that amendment does. The name is not guaranteed to be unique or consistent across servers.

2
content/references/http-websocket-apis/api-conventions/error-formatting.md
View File

@@ -108,7 +108,7 @@ For other errors that returned with HTTP status code 200 OK, the responses are f
All methods can potentially return any of the following values for the `error` code: All methods can potentially return any of the following values for the `error` code:
- `amendmentBlocked` - The server is [amendment blocked](amendments.html#amendment-blocked) and needs to be updated to the latest version to stay synced with the XRP Ledger network. - `amendmentBlocked` - The server is [amendment blocked](amendments.html#amendment-blocked-servers) and needs to be updated to the latest version to stay synced with the XRP Ledger network.
- `failedToForward` - ([Reporting Mode][] servers only) The server tried to forward this request to a P2P Mode server, but the connection failed. - `failedToForward` - ([Reporting Mode][] servers only) The server tried to forward this request to a P2P Mode server, but the connection failed.
- `invalid_API_version` - The server does not support the [API version number](request-formatting.html#api-versioning) from the request. - `invalid_API_version` - The server does not support the [API version number](request-formatting.html#api-versioning) from the request.
- `jsonInvalid` - (WebSocket only) The request is not a proper JSON object. - `jsonInvalid` - (WebSocket only) The request is not a proper JSON object.

4
content/references/http-websocket-apis/api-conventions/response-formatting.md
View File

@@ -126,7 +126,7 @@ Example warning:
] ]
``` ```
This warning indicates that the one or more [amendments](amendments.html) to the XRP Ledger protocol are scheduled to become enabled, but the current server does not have an implementation for those amendments. If those amendments become enabled, the current server will become [amendment blocked](amendments.html#amendment-blocked), so you should [upgrade to the latest `rippled` version](install-rippled.html) as soon as possible. <!-- STYLE_OVERRIDE: will --> This warning indicates that the one or more [amendments](amendments.html) to the XRP Ledger protocol are scheduled to become enabled, but the current server does not have an implementation for those amendments. If those amendments become enabled, the current server will become [amendment blocked](amendments.html#amendment-blocked-servers), so you should [upgrade to the latest `rippled` version](install-rippled.html) as soon as possible. <!-- STYLE_OVERRIDE: will -->
The server only sends this warning if the client is [connected as an admin](get-started-using-http-websocket-apis.html#admin-access). The server only sends this warning if the client is [connected as an admin](get-started-using-http-websocket-apis.html#admin-access).
@@ -153,7 +153,7 @@ Example warning:
] ]
``` ```
This warning indicates that the server is [amendment blocked](amendments.html#amendment-blocked) and can no longer remain synced with the XRP Ledger. This warning indicates that the server is [amendment blocked](amendments.html#amendment-blocked-servers) and can no longer remain synced with the XRP Ledger.
The server administrator must [upgrade `rippled`](install-rippled.html) to a version that supports the activated amendments. The server administrator must [upgrade `rippled`](install-rippled.html) to a version that supports the activated amendments.

116
content/references/http-websocket-apis/peer-port-methods/health-check.ja.md Normal file
View File

@@ -0,0 +1,116 @@
---
html: health-check.html
parent: peer-port-methods.html
blurb: Special API method for reporting server health.
labels:
- Core Server
---
# Health Check
[[Source]](https://github.com/ripple/rippled/blob/de0c52738785de8bf837f9124da65c7905e7bb5a/src/ripple/overlay/impl/OverlayImpl.cpp#L1084-L1168 "Source")
The Health Check is a special [peer port method](peer-port-methods.html) for reporting on the health of an individual `rippled` server. This method is intended for use in automated monitoring to recognize outages and prompt automated or manual interventions such as restarting the server. [New in: rippled 1.6.0][]
This method checks several metrics to see if they are in ranges generally considered healthy. If all metrics are in normal ranges, this method reports that the server is healthy. If any metric is outside normal ranges, this method reports that the server is unhealthy and reports the metric(s) that are unhealthy. Since some metrics may rapidly fluctuate into and out of unhealthy ranges, you should not raise alerts unless the health check fails multiple times in a row.
**Note:** Since the health check is a [peer port method](peer-port-methods.html), it is not available when testing the server in [stand-alone mode][].
## Request Format
To request the Health Check information, make the following HTTP request:
- **Protocol:** https
- **HTTP Method:** GET
- **Host:** (any `rippled` server, by hostname or IP address)
- **Port:** (the port number where the `rippled` server uses the Peer Protocol, typically 51235)
- **Path:** `/health`
- **Security:** Most `rippled` servers use a self-signed certificate to respond to the request. By default, most tools (including web browsers) flag or block such responses for being untrusted. You must ignore the certificate checking (for example, if using cURL, add the `--insecure` flag) to display a response from those servers.
<!-- TODO: link a tutorial for how to run rippled with a non-self-signed TLS cert -->
## Example Response
<!-- MULTICODE_BLOCK_START -->
*Healthy*
```json
HTTP/1.1 200 OK
Server: rippled-1.6.0-b8
Content-Type: application/json
Connection: close
Transfer-Encoding: chunked
{
"info": {}
}
```
*Warning*
```json
HTTP/1.1 503 Service Unavailable
Server: rippled-1.6.0
Content-Type: application/json
Connection: close
Transfer-Encoding: chunked
{
"info": {
"server_state": "connected",
"validated_ledger": -1
}
}
```
*Critical*
```json
HTTP/1.1 500 Internal Server Error
Server: rippled-1.6.0
Content-Type: application/json
Connection: close
Transfer-Encoding: chunked
{
"info": {
"peers": 0,
"server_state": "disconnected",
"validated_ledger":-1
}
}
```
<!-- MULTICODE_BLOCK_END -->
## Response Format
The response's HTTP status code indicates the health of the server:
| Status Code | Health Status | Description |
|:------------------------------|:--------------|:-----------------------------|
| **200 OK** | Healthy | All health metrics are within acceptable ranges. |
| **503 Service Unavailable** | Warning | One or more metrics are in the warning range. Manual intervention may or may not be necessary. |
| **500 Internal Server Error** | Critical | One or more metrics are in the critical range. There is a serious problem that probably needs manual intervention to fix. |
The response body is a JSON object with a single `info` object at the top level. The `info` object contains values for each metric that is in a warning or critical range. The response omits metrics that are in a healthy range, so a fully healthy server has an empty object.
The `info` object may contain the following fields:
| `Field` | Value | Description |
|:--------------------|:--------|:---------------------------------------------|
| `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, the server is [amendment blocked](amendments.html#amendment-blocked) and must be upgraded to remain synced with the network; this state is critical. If the server is not amendment blocked, this field is omitted. |
| `load_factor` | Number | _(May be omitted)_ A measure of the overall load the server is under. This reflects I/O, CPU, and memory limitations. This is a warning if the load factor is over 100, or critical if the load factor is 1000 or higher. |
| `peers` | Number | _(May be omitted)_ The number of [peer servers](peer-protocol.html) this server is connected to. This is a warning if connected to 7 or fewer peers, and critical if connected to zero peers. |
| `server_state` | String | _(May be omitted)_ The current [server state](rippled-server-states.html). This is a warning if the server is in the `tracking`, `syncing`, or `connected` states. This is critical if the server is in the `disconnected` state. |
| `validated_ledger` | Number | _(May be omitted)_ The number of seconds since the last time a ledger was validated by [consensus](intro-to-consensus.html). If there is no validated ledger available ([as during the initial sync period when starting the server](server-doesnt-sync.html#normal-syncing-behavior)), this is the value `-1` and is considered a warning. This metric is also a warning if the last validated ledger was at least 7 seconds ago, or critical if the last validated ledger was at least 20 seconds ago. |
## See Also
For guidance interpreting the results of the health check, see [Health Check Interventions](health-check-interventions.html).
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

6
content/references/http-websocket-apis/peer-port-methods/health-check.md
View File

@@ -90,8 +90,8 @@ The response's HTTP status code indicates the health of the server:
| Status Code | Health Status | Description | | Status Code | Health Status | Description |
|:------------------------------|:--------------|:-----------------------------| |:------------------------------|:--------------|:-----------------------------|
| **200 OK** | Healthy | All health metrics are within acceptable ranges. | | **200 OK** | Healthy | All health metrics are within acceptable ranges. |
| **503 Service Unavailable** | Warning | One or more metric is in the warning range. Manual intervention may or may not be necessary. | | **503 Service Unavailable** | Warning | One or more metrics are in the warning range. Manual intervention may or may not be necessary. |
| **500 Internal Server Error** | Critical | One or more metric is in the critical range. There is a serious problem that probably needs manual intervention to fix. | | **500 Internal Server Error** | Critical | One or more metrics are in the critical range. There is a serious problem that probably needs manual intervention to fix. |
The response body is a JSON object with a single `info` object at the top level. The `info` object contains values for each metric that is in a warning or critical range. The response omits metrics that are in a healthy range, so a fully healthy server has an empty object. The response body is a JSON object with a single `info` object at the top level. The `info` object contains values for each metric that is in a warning or critical range. The response omits metrics that are in a healthy range, so a fully healthy server has an empty object.
@@ -99,7 +99,7 @@ The `info` object may contain the following fields:
| `Field` | Value | Description | | `Field` | Value | Description |
|:--------------------|:--------|:---------------------------------------------| |:--------------------|:--------|:---------------------------------------------|
| `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, the server is [amendment blocked](amendments.html#amendment-blocked) and must be upgraded to remain synced with the network; this state is critical. If the server is not amendment blocked, this field is omitted. | | `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, the server is [amendment blocked](amendments.html#amendment-blocked-servers) and must be upgraded to remain synced with the network; this state is critical. If the server is not amendment blocked, this field is omitted. |
| `load_factor` | Number | _(May be omitted)_ A measure of the overall load the server is under. This reflects I/O, CPU, and memory limitations. This is a warning if the load factor is over 100, or critical if the load factor is 1000 or higher. | | `load_factor` | Number | _(May be omitted)_ A measure of the overall load the server is under. This reflects I/O, CPU, and memory limitations. This is a warning if the load factor is over 100, or critical if the load factor is 1000 or higher. |
| `peers` | Number | _(May be omitted)_ The number of [peer servers](peer-protocol.html) this server is connected to. This is a warning if connected to 7 or fewer peers, and critical if connected to zero peers. | | `peers` | Number | _(May be omitted)_ The number of [peer servers](peer-protocol.html) this server is connected to. This is a warning if connected to 7 or fewer peers, and critical if connected to zero peers. |
| `server_state` | String | _(May be omitted)_ The current [server state](rippled-server-states.html). This is a warning if the server is in the `tracking`, `syncing`, or `connected` states. This is critical if the server is in the `disconnected` state. | | `server_state` | String | _(May be omitted)_ The current [server state](rippled-server-states.html). This is a warning if the server is in the `tracking`, `syncing`, or `connected` states. This is critical if the server is in the `disconnected` state. |

2
content/references/http-websocket-apis/public-api-methods/server-info-methods/server_info.md
View File

@@ -258,7 +258,7 @@ The `info` object may have some arrangement of the following fields:
| `Field` | Type | Description | | `Field` | Type | Description |
|:------------------------------------|:----------------|:---------------------| |:------------------------------------|:----------------|:---------------------|
| `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, this server is [amendment blocked](amendments.html#amendment-blocked). If the server is not amendment blocked, the response omits this field. [New in: rippled 0.80.0][] | | `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, this server is [amendment blocked](amendments.html#amendment-blocked-servers). If the server is not amendment blocked, the response omits this field. [New in: rippled 0.80.0][] |
| `build_version` | String | The version number of the running `rippled` server. | | `build_version` | String | The version number of the running `rippled` server. |
| `closed_ledger` | Object | _(May be omitted)_ Information on the most recently closed ledger that has not been validated by consensus. If the most recently validated ledger is available, the response omits this field and includes `validated_ledger` instead. The member fields are the same as the `validated_ledger` field. | | `closed_ledger` | Object | _(May be omitted)_ Information on the most recently closed ledger that has not been validated by consensus. If the most recently validated ledger is available, the response omits this field and includes `validated_ledger` instead. The member fields are the same as the `validated_ledger` field. |
| `complete_ledgers` | String | Range expression indicating the sequence numbers of the ledger versions the local `rippled` has in its database. This may be a disjoint sequence such as `24900901-24900984,24901116-24901158`. If the server does not have any complete ledgers (for example, it recently started syncing with the network), this is the string `empty`. | | `complete_ledgers` | String | Range expression indicating the sequence numbers of the ledger versions the local `rippled` has in its database. This may be a disjoint sequence such as `24900901-24900984,24901116-24901158`. If the server does not have any complete ledgers (for example, it recently started syncing with the network), this is the string `empty`. |

2
content/references/http-websocket-apis/public-api-methods/server-info-methods/server_state.md
View File

@@ -268,7 +268,7 @@ The `state` object may have some arrangement of the following fields:
| `Field` | Type | Description | | `Field` | Type | Description |
|:---------------------------------|:----------------|:------------------------| |:---------------------------------|:----------------|:------------------------|
| `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, this server is [amendment blocked](amendments.html#amendment-blocked). If the server is not amendment blocked, the response omits this field. [New in: rippled 0.80.0][] | | `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, this server is [amendment blocked](amendments.html#amendment-blocked-servers). If the server is not amendment blocked, the response omits this field. [New in: rippled 0.80.0][] |
| `build_version` | String | The version number of the running `rippled` version. | | `build_version` | String | The version number of the running `rippled` version. |
| `complete_ledgers` | String | Range expression indicating the sequence numbers of the ledger versions the local `rippled` has in its database. It is possible to be a disjoint sequence, e.g. "2500-5000,32570-7695432". If the server does not have any complete ledgers (for example, it recently started syncing with the network), this is the string `empty`. | | `complete_ledgers` | String | Range expression indicating the sequence numbers of the ledger versions the local `rippled` has in its database. It is possible to be a disjoint sequence, e.g. "2500-5000,32570-7695432". If the server does not have any complete ledgers (for example, it recently started syncing with the network), this is the string `empty`. |
| `closed_ledger` | Object | _(May be omitted)_ Information on the most recently closed ledger that has not been validated by consensus. If the most recently validated ledger is available, the response omits this field and includes `validated_ledger` instead. The member fields are the same as the `validated_ledger` field. | | `closed_ledger` | Object | _(May be omitted)_ Information on the most recently closed ledger that has not been validated by consensus. If the most recently validated ledger is available, the response omits this field and includes `validated_ledger` instead. The member fields are the same as the `validated_ledger` field. |

2
content/references/http-websocket-apis/public-api-methods/transaction-methods/submit.md
View File

@@ -319,7 +319,7 @@ The response follows the [standard format][], with a successful result containin
## Possible Errors ## Possible Errors
* Any of the [universal error types][]. * Any of the [universal error types][].
* `amendmentBlocked` - The transaction cannot be submitted to the network because the `rippled` server is [amendment blocked](amendments.html#amendment-blocked). * `amendmentBlocked` - The transaction cannot be submitted to the network because the `rippled` server is [amendment blocked](amendments.html#amendment-blocked-servers).
* `highFee` - The `fee_mult_max` parameter was specified, but the server's current fee multiplier exceeds the specified one. (Sign-and-Submit mode only) * `highFee` - The `fee_mult_max` parameter was specified, but the server's current fee multiplier exceeds the specified one. (Sign-and-Submit mode only)
* `internalJson` - An internal error occurred when serializing the transaction to JSON. This could be caused by many aspects of the transaction, including a bad signature or some fields being malformed. * `internalJson` - An internal error occurred when serializing the transaction to JSON. This could be caused by many aspects of the transaction, including a bad signature or some fields being malformed.
* `internalSubmit` - An internal error occurred when submitting the transaction. This could be caused by many aspects of the transaction, including a bad signature or some fields being malformed. * `internalSubmit` - An internal error occurred when submitting the transaction. This could be caused by many aspects of the transaction, including a bad signature or some fields being malformed.

2
content/references/protocol-reference/ledger-data/ledger-object-types/amendments.md
View File

@@ -38,7 +38,7 @@ The `Amendments` object type contains a list of [Amendments](amendments.html) th
| Name | JSON Type | [Internal Type][] | Required? | Description | | Name | JSON Type | [Internal Type][] | Required? | Description |
|-------------------|-----------|-------------------|-----------|-------------| |-------------------|-----------|-------------------|-----------|-------------|
| `Amendments` | Array | Vector256 | No | Array of 256-bit [amendment IDs](amendments.html#about-amendments) for all currently-enabled amendments. If omitted, there are no enabled amendments. | | `Amendments` | Array | Vector256 | No | Array of 256-bit [amendment IDs](amendments.html) for all currently enabled amendments. If omitted, there are no enabled amendments. |
| `Flags` | Number | UInt32 | Yes | A bit-map of boolean flags enabled for this object. Currently, the protocol defines no flags for `Amendments` objects. The value is always `0`. | | `Flags` | Number | UInt32 | Yes | A bit-map of boolean flags enabled for this object. Currently, the protocol defines no flags for `Amendments` objects. The value is always `0`. |
| `LedgerEntryType` | String | UInt16 | Yes | The value `0x0066`, mapped to the string `Amendments`, indicates that this object describes the status of amendments to the XRP Ledger. | | `LedgerEntryType` | String | UInt16 | Yes | The value `0x0066`, mapped to the string `Amendments`, indicates that this object describes the status of amendments to the XRP Ledger. |
| `Majorities` | Array | STArray | No | Array of objects describing the status of amendments that have majority support but are not yet enabled. If omitted, there are no pending amendments with majority support. | | `Majorities` | Array | STArray | No | Array of objects describing the status of amendments that have majority support but are not yet enabled. If omitted, there are no pending amendments with majority support. |

18
content/references/protocol-reference/transactions/pseudo-transaction-types/enableamendment.md
View File

@@ -7,14 +7,22 @@ labels:
--- ---
# EnableAmendment # EnableAmendment
An `EnableAmendment` [pseudo-transaction](pseudo-transaction-types.html) marks a change in status of an [amendment](amendments.html) to the XRP Ledger protocol, including: An `EnableAmendment` pseudo-transaction marks a change in the status of a proposed amendment when it:
- A proposed amendment gained supermajority approval from validators. - Gains supermajority approval from validators.
- A proposed amendment lost supermajority approval. - Loses supermajority approval.
- A proposed amendment has been enabled. - Is enabled on the XRP Ledger protocol.
**Note:** You cannot send a pseudo-transaction, but you may find one when processing ledgers. <!-- TODO: Move to propose amendments tutorial.
A server only enables amendments when these conditions are met:
- A previous ledger includes an `EnableAmendment` pseudo-transaction with the `tfGotMajority` flag enabled.
- The previous ledger in question is an ancestor of the current ledger.
- The previous ledger in question has a close time that is at least two weeks before the close time of the latest flag ledger.
- There are no `EnableAmendment` pseudo-transactions for this amendment with the `tfLostMajority` flag enabled in the consensus ledgers between the `tfGotMajority` pseudo-transaction and the current ledger.
-->
## Example {{currentpage.name}} JSON ## Example {{currentpage.name}} JSON

26
content/tutorials/manage-the-rippled-server/configuration/test-amendments.md Normal file
View File

@@ -0,0 +1,26 @@
---
html: test-amendments.html
parent: configure-rippled.html
blurb: You can test proposed amendments before they're enabled on the network.
labels:
- Blockchain
---
# Test Amendments
You can test how `rippled` behaves before proposed amendments are fully enabled on the production network. Since other members of the consensus network won't have the feature enabled, run your server in stand-alone mode.
**Caution:** This is intended for development purposes only.
To forcibly enable a feature, add a `[features]` stanza with amendment short names to your `rippled.cfg` file. Each amendment needs its own line.
<!-- MULTICODE_BLOCK_START -->
_Example_
```
[features]
MultiSign
TrustSetAuth
```
<!-- MULTICODE_BLOCK_END -->

11
content/tutorials/manage-the-rippled-server/stand-alone-mode/advance-the-ledger-in-stand-alone-mode.md
View File

@@ -15,22 +15,17 @@ rippled ledger_accept --conf=/path/to/rippled.cfg
In stand-alone mode, `rippled` makes no distinction between a "closed" ledger version and a "validated" ledger version. (For more information about the difference, see [The XRP Ledger Consensus Process](consensus.html).) In stand-alone mode, `rippled` makes no distinction between a "closed" ledger version and a "validated" ledger version. (For more information about the difference, see [The XRP Ledger Consensus Process](consensus.html).)
Whenever `rippled` closes a ledger, it reorders the transactions according to a deterministic but hard-to-game algorithm. (This is an important part of consensus, since transactions may arrive at different parts of the network in different order.) When using `rippled` in stand-alone mode, you should manually advance the ledger before submitting a transaction that depends on the result of a transaction from a different address. Otherwise, the two transactions might be executed in reverse order when the ledger is closed. **Note:** You can safely submit multiple transactions from a single address to a single ledger, because `rippled` sorts transactions from the same address in ascending order by [`Sequence` number](transaction-common-fields.html). Whenever `rippled` closes a ledger, it reorders the transactions according to a deterministic but hard-to-game algorithm. (This is an important part of consensus, since transactions may arrive at different parts of the network in different order.) When using `rippled` in stand-alone mode, you should manually advance the ledger before submitting a transaction that depends on the result of a transaction from a different address. Otherwise, the two transactions might be executed in reverse order when the ledger is closed.
**Note:** You can safely submit multiple transactions from a single address to a single ledger, because `rippled` sorts transactions from the same address in ascending order by [`Sequence` number](transaction-common-fields.html).
## See Also ## See Also
- **Concepts:**
- [The `rippled` Server](xrpl-servers.html)
- [`rippled` Server Modes](rippled-server-modes.html)
- [Introduction to Consensus](intro-to-consensus.html)
- [Amendments](amendments.html)
- **References:** - **References:**
- [ledger_accept method][] - [ledger_accept method][]
- [server_info method][] - [server_info method][]
- [`rippled` Commandline Usage](commandline-usage.html) - [`rippled` Commandline Usage](commandline-usage.html)
- **Use Cases:**
- [Contribute Code to the XRP Ledger](contribute-code.html)
<!--{# common link defs #}--> <!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %} {% include '_snippets/rippled-api-links.md' %}

13
content/tutorials/manage-the-rippled-server/stand-alone-mode/load-a-saved-ledger-in-stand-alone-mode.md
View File

@@ -9,7 +9,9 @@ labels:
You can start a `rippled` server in [Stand-Alone Mode](rippled-server-modes.html) using a [historical ledger version](ledgers.html) that was previously saved to disk. For example, if your `rippled` server was previously synced with any XRP Ledger peer-to-peer network including [the production Mainnet, the Testnet, or the Devnet](parallel-networks.html), you can load any ledger version your server had available. You can start a `rippled` server in [Stand-Alone Mode](rippled-server-modes.html) using a [historical ledger version](ledgers.html) that was previously saved to disk. For example, if your `rippled` server was previously synced with any XRP Ledger peer-to-peer network including [the production Mainnet, the Testnet, or the Devnet](parallel-networks.html), you can load any ledger version your server had available.
Loading a historical ledger version so may be useful for "replaying" a ledger to verify that transactions were processed according to the rules of the network, or to compare the results of processing transaction sets with different [amendments](amendments.html) enabled. In the unlikely event that [an attack against the XRP Ledger's consensus mechanism](consensus-protections.html) caused unwanted effects to the shared ledger state, a consensus of validators could "roll back" to a previous, known-good network state starting with this process. Loading a historical ledger version is useful for "replaying" a ledger to verify that transactions were processed according to the rules of the network, or to compare the results of processing transaction sets with different [amendments](amendments.html) enabled. In the unlikely event that [an attack against the XRP Ledger's consensus mechanism](consensus-protections.html) caused unwanted effects to the shared ledger state, a consensus of validators could "roll back" to a known-good network state starting with this process.
**Caution:** As `rippled` is updated to newer versions, amendments are retired and become core functions of the ledger, which can affect how transactions are processed. To produce historically accurate results, you need to replay ledgers using the version of `rippled` the transaction was processed in.
## 1. Start `rippled` normally. ## 1. Start `rippled` normally.
@@ -63,20 +65,17 @@ For more information on the options you can use when starting `rippled` in stand
## 6. Manually advance the ledger. ## 6. Manually advance the ledger.
When you load a ledger with `--ledger` in stand-alone mode, it goes to the current open ledger, so you must [manually advance the ledger](advance-the-ledger-in-stand-alone-mode.html): In stand-alone mode, you must manually advance the ledger with the `ledger_accept` method:
``` ```
rippled ledger_accept --conf=/path/to/rippled.cfg rippled ledger_accept --conf=/path/to/rippled.cfg
``` ```
If a transaction depends on the result of a transaction from a different address, advance the ledger to ensure they are processed in the correct order. Otherwise, you can submit multiple transactions from a single address `rippled` sorts transactions from the same address by ascending `Sequence` number.
## See Also ## See Also
- **Concepts:**
- [The `rippled` Server](xrpl-servers.html)
- [`rippled` Server Modes](rippled-server-modes.html)
- [Introduction to Consensus](intro-to-consensus.html)
- [Amendments](amendments.html)
- **References:** - **References:**
- [ledger_accept method][] - [ledger_accept method][]
- [server_info method][] - [server_info method][]

130
content/tutorials/manage-the-rippled-server/troubleshooting/server-is-amendment-blocked.md Normal file
View File

@@ -0,0 +1,130 @@
---
html: server-is-amendment-blocked.html
parent: troubleshoot-the-rippled-server.html
blurb: Troubleshoot a server that can't implement amendment changes.
labels:
- Core Server
---
# rippled Server is Amendment Blocked
One of the first signs that your `rippled` server is amendment blocked is an `amendmentBlocked` error that is returned when you submit a transaction. Here's an example `amendmentBlocked` error:
```json
{
"result":{
"error":"amendmentBlocked",
"error_code":14,
"error_message":"Amendment blocked, need upgrade.",
"request":{
"command":"submit",
"tx_blob":"479H0KQ4LUUXIHL48WCVN0C9VD7HWSX0MG1UPYNXK6PI9HLGBU2U10K3HPFJSROFEG5VD749WDPHWSHXXO72BOSY2G8TWUDOJNLRTR9LTT8PSOB9NNZ485EY2RD9D80FLDFRBVMP1RKMELILD7I922D6TBCAZK30CSV6KDEDUMYABE0XB9EH8C4LE98LMU91I9ZV2APETJD4AYFEN0VNMIT1XQ122Y2OOXO45GJ737HHM5XX88RY7CXHVWJ5JJ7NYW6T1EEBW9UE0NLB2497YBP9V1XVAEK8JJYVRVW0L03ZDXFY8BBHP6UBU7ZNR0JU9GJQPNHG0DK86S4LLYDN0BTCF4KWV2J4DEB6DAX4BDLNPT87MM75G70DFE9W0R6HRNWCH0X075WHAXPSH7S3CSNXPPA6PDO6UA1RCCZOVZ99H7968Q37HACMD8EZ8SU81V4KNRXM46N520S4FVZNSJHA"
},
"status":"error"
}
}
```
The following `rippled` log message also indicates that your server is amendment blocked:
```
2018-Feb-12 19:38:30 LedgerMaster:ERR One or more unsupported amendments activated: server blocked.
```
You can verify that your `rippled` server is amendment blocked using the `server_info` command. In the response, look for `result.info.amendment_blocked`. If `amendment_blocked` is set to `true`, your server is amendment blocked.
**Example JSON-RPC Response:**
```json
{
"result": {
"info": {
"amendment_blocked": true,
"build_version": "0.80.1",
"complete_ledgers": "6658438-6658596",
"hostid": "ip-10-30-96-212.us-west-2.compute.internal",
"io_latency_ms": 1,
"last_close": {
"converge_time_s": 2,
"proposers": 10
},
...
},
"status": "success"
}
}
```
## Unblock Servers
The easiest solution is to update to the latest version of `rippled`, but depending on the scenario, you may want to update to an older version with the amendment blocking your server.
**Warning:** If the newest `rippled` version provides security or other urgent fixes, you should upgrade to the newest version as soon as possible.
To determine if you can unblock your `rippled` server by upgrading to a version older than the newest version, find out which features are blocking your server and then look up the `rippled` version that supports the blocking features.
To find out which features are blocking your `rippled` server, use the [`feature`](feature.html) admin command. Look for features that have:
```
"enabled" : true
"supported" : false
```
These values mean the amendment is required in the latest ledger, but your server doesn't support the implementation.
**Example JSON-RPC Response:**
```json
{
"result": {
"features": {
"07D43DCE529B15A10827E5E04943B496762F9A88E3268269D69C44BE49E21104": {
"enabled": true,
"name": "Escrow",
"supported": true,
"vetoed": false
},
"08DE7D96082187F6E6578530258C77FAABABE4C20474BDB82F04B021F1A68647": {
"enabled": true,
"name": "PayChan",
"supported": true,
"vetoed": false
},
"1562511F573A19AE9BD103B5D6B9E01B3B46805AEC5D3C4805C902B514399146": {
"enabled": false,
"name": "CryptoConditions",
"supported": true,
"vetoed": false
},
"157D2D480E006395B76F948E3E07A45A05FE10230D88A7993C71F97AE4B1F2D1": {
"enabled": true,
"supported": false,
"vetoed": false
},
...
"67A34F2CF55BFC0F93AACD5B281413176FEE195269FA6D95219A2DF738671172": {
"enabled": true,
"supported": false,
"vetoed": false
},
...
"F64E1EABBE79D55B3BB82020516CEC2C582A98A6BFE20FBE9BB6A0D233418064": {
"enabled": true,
"supported": false,
"vetoed": false
}
},
"status": "success"
}
}
```
In this example, conflicts with the following features are causing your `rippled` server to be amendment blocked:
* `157D2D480E006395B76F948E3E07A45A05FE10230D88A7993C71F97AE4B1F2D1`
* `67A34F2CF55BFC0F93AACD5B281413176FEE195269FA6D95219A2DF738671172`
* `F64E1EABBE79D55B3BB82020516CEC2C582A98A6BFE20FBE9BB6A0D233418064`
To look up which `rippled` version supports these features, see [Known Amendments](known-amendments.html).

2
content/tutorials/manage-the-rippled-server/troubleshooting/understanding-log-messages.md
View File

@@ -97,7 +97,7 @@ The following message indicates that the server has detected that it is running
LedgerMaster:ERR Check for upgrade: A majority of trusted validators are running a newer version. LedgerMaster:ERR Check for upgrade: A majority of trusted validators are running a newer version.
``` ```
This is not strictly a problem, but an old server version is likely to become [amendment blocked](amendments.html#amendment-blocked). You should [update `rippled`](install-rippled.html) to the latest stable version. (If you are connected to [devnet](parallel-networks.html), update to the latest nightly version instead.) This is not strictly a problem, but an old server version is likely to become [amendment blocked](amendments.html#amendment-blocked-servers). You should [update `rippled`](install-rippled.html) to the latest stable version. (If you are connected to [devnet](parallel-networks.html), update to the latest nightly version instead.)
## Connection reset by peer ## Connection reset by peer

15
dactyl-config.yml
View File

@@ -1860,6 +1860,11 @@ pages:
targets: targets:
- ja - ja
- md: tutorials/manage-the-rippled-server/configuration/test-amendments.md
targets:
- en
- ja
# TODO: translate this page & blurb # TODO: translate this page & blurb
- md: tutorials/manage-the-rippled-server/configuration/configure-statsd.md - md: tutorials/manage-the-rippled-server/configuration/configure-statsd.md
targets: targets:
@@ -2057,7 +2062,6 @@ pages:
targets: targets:
- ja - ja
# TODO: translate page and blurb
- md: tutorials/manage-the-rippled-server/troubleshooting/health-check-interventions.md - md: tutorials/manage-the-rippled-server/troubleshooting/health-check-interventions.md
targets: targets:
- en - en
@@ -2080,6 +2084,11 @@ pages:
targets: targets:
- ja - ja
- md: tutorials/manage-the-rippled-server/troubleshooting/server-is-amendment-blocked.md
targets:
- en
- ja
- md: tutorials/manage-the-rippled-server/troubleshooting/server-wont-start.md - md: tutorials/manage-the-rippled-server/troubleshooting/server-wont-start.md
targets: targets:
- en - en
@@ -3695,6 +3704,10 @@ pages:
- md: references/http-websocket-apis/peer-port-methods/health-check.md - md: references/http-websocket-apis/peer-port-methods/health-check.md
targets: targets:
- en - en
# TODO: translate page and blurb
- md: references/http-websocket-apis/peer-port-methods/health-check.ja.md
targets:
- ja - ja
- md: references/http-websocket-apis/peer-port-methods/peer-crawler.md - md: references/http-websocket-apis/peer-port-methods/peer-crawler.md