Merge pull request #968 from mDuo13/reporting_mode_api

Reporting mode api
2025-11-17 02:05:50 +00:00 · 2021-02-18 18:14:03 -08:00
parent edf4eafc79 9fa6dc6811
commit 55fb729f38
23 changed files with 92 additions and 37 deletions
--- a/content/_snippets/rippled-api-links.md
+++ b/content/_snippets/rippled-api-links.md
@@ -34,6 +34,7 @@
 [ピアリザベーション]: peer-protocol.html#固定ピアとピアリザベーション
 [result code]: transaction-results.html
 [seconds since the Ripple Epoch]: basic-data-types.html#specifying-time
+[Reporting Mode]: rippled-server-modes.html#reporting-mode
 [Rippleエポック以降の経過秒数]: basic-data-types.html#時間の指定
 [Sequence Number]: basic-data-types.html#account-sequence
 [シーケンス番号]: basic-data-types.html#アカウントシーケンス
--- a/content/references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/can_delete.md
+++ b/content/references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/can_delete.md
@@ -66,6 +66,7 @@ Use this command with no parameter to query the existing `can_delete` setting.
 - `lgrNotFound` - The ledger specified by the `can_delete` field of the request does not exist, or it does exist but the server does not have it.
 - `notEnabled` - If either online deletion or advisory deletion are not enabled in the server's configuration.
 - `notReady` - The server is not ready to run online deletion at the moment. This usually means the server has recently started up and has not yet acquired a validated ledger.
+- `reportingUnsupported` - ([Reporting Mode][] servers only) This method is not available in Reporting Mode.

 ## See Also

--- a/content/references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/crawl_shards.md
+++ b/content/references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/crawl_shards.md
@@ -129,6 +129,7 @@ Each member of the `peers` array of the response is an object that describes one

 - Any of the [universal error types][].
 - `invalidParams` - One or more required fields were omitted from the request, or a provided field was specified as the wrong data type.
+- `reportingUnsupported` - ([Reporting Mode][] servers only) This method is not available in Reporting Mode.


 <!--{# common link defs #}-->
--- a/content/references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/download_shard.md
+++ b/content/references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/download_shard.md
@@ -132,6 +132,7 @@ The response follows the [standard format][], with a successful result containin
 - `notEnabled` - The server is not configured with a shard store.
 - `tooBusy` - The server is already downloading the shard, either from the peer-to-peer network or as the result of a previous `download_shard` request.
 - `invalidParams` - One or more required fields were omitted from the request, or a provided field was specified as the wrong data type.
+- `reportingUnsupported` - ([Reporting Mode][] servers only) This method is not available in Reporting Mode.



--- a/content/references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/ledger_request.md
+++ b/content/references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/ledger_request.md
@@ -176,9 +176,10 @@ When the server is in the progress of fetching a ledger, but has not yet finishe

 ### Possible Errors

-* Any of the [universal error types][].
-* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. This error can also occur if you specify a ledger index equal or higher than the current in-progress ledger.
-* `lgrNotFound` - If the ledger is not yet available. This indicates that the server has started fetching the ledger, although it may fail if none of its connected peers have the requested ledger. (Previously, this error used the code `ledgerNotFound` instead.) [Updated in: rippled 0.30.1][]
+- Any of the [universal error types][].
+- `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. This error can also occur if you specify a ledger index equal or higher than the current in-progress ledger.
+- `lgrNotFound` - If the ledger is not yet available. This indicates that the server has started fetching the ledger, although it may fail if none of its connected peers have the requested ledger. (Previously, this error used the code `ledgerNotFound` instead.) [Updated in: rippled 0.30.1][]
+- `reportingUnsupported` - ([Reporting Mode][] servers only) This method is not available in Reporting Mode.

 <!--{# common link defs #}-->
 {% include '_snippets/rippled-api-links.md' %}
--- a/content/references/rippled-api/admin-rippled-methods/peer-management-methods/connect.md
+++ b/content/references/rippled-api/admin-rippled-methods/peer-management-methods/connect.md
@@ -92,9 +92,10 @@ The response follows the [standard format][], with a successful result containin

 ### Possible Errors

-* Any of the [universal error types][].
-* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
-* Cannot connect in standalone mode - Network-related commands are disabled in stand-alone mode.
+- Any of the [universal error types][].
+- `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
+- Cannot connect in standalone mode - Network-related commands are disabled in stand-alone mode.
+- `reportingUnsupported` - ([Reporting Mode][] servers only) This method is not available in Reporting Mode.

 <!--{# common link defs #}-->
 {% include '_snippets/rippled-api-links.md' %}
--- a/content/references/rippled-api/admin-rippled-methods/peer-management-methods/peer_reservations_add.md
+++ b/content/references/rippled-api/admin-rippled-methods/peer-management-methods/peer_reservations_add.md
@@ -129,6 +129,7 @@ If the `previous` field is provided, it shows the previous status of this peer r
 - Any of the [universal error types][].
 - `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
 - `publicMalformed` - The `public_key` field of the request is not valid. It must be a valid node public key in [base58][] format.
+- `reportingUnsupported` - ([Reporting Mode][] servers only) This method is not available in Reporting Mode.

 <!--{# common link defs #}-->
 {% include '_snippets/rippled-api-links.md' %}
--- a/content/references/rippled-api/admin-rippled-methods/peer-management-methods/peer_reservations_del.md
+++ b/content/references/rippled-api/admin-rippled-methods/peer-management-methods/peer_reservations_del.md
@@ -125,6 +125,7 @@ If the `previous` field is provided, it shows the previous status of this peer r
 - Any of the [universal error types][].
 - `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
 - `publicMalformed` - The `public_key` field of the request is not valid. It must be a valid node public key in [base58][] format.
+- `reportingUnsupported` - ([Reporting Mode][] servers only) This method is not available in Reporting Mode.

 <!--{# common link defs #}-->
 {% include '_snippets/rippled-api-links.md' %}
--- a/content/references/rippled-api/admin-rippled-methods/peer-management-methods/peer_reservations_list.md
+++ b/content/references/rippled-api/admin-rippled-methods/peer-management-methods/peer_reservations_list.md
@@ -127,6 +127,7 @@ Each member of the `reservations` array is a JSON object describing one [peer re
 ### Possible Errors

 - Any of the [universal error types][].
+- `reportingUnsupported` - ([Reporting Mode][] servers only) This method is not available in Reporting Mode.

 <!--{# common link defs #}-->
 {% include '_snippets/rippled-api-links.md' %}
--- a/content/references/rippled-api/admin-rippled-methods/peer-management-methods/peers.md
+++ b/content/references/rippled-api/admin-rippled-methods/peer-management-methods/peers.md
@@ -408,7 +408,8 @@ The `metrics` object contains the following fields:

 ### Possible Errors

-* Any of the [universal error types][].
+- Any of the [universal error types][].
+- `reportingUnsupported` - ([Reporting Mode][] servers only) This method is not available in Reporting Mode.

 <!--{# common link defs #}-->
 {% include '_snippets/rippled-api-links.md' %}
--- a/content/references/rippled-api/admin-rippled-methods/status-and-debugging-methods/consensus_info.md
+++ b/content/references/rippled-api/admin-rippled-methods/status-and-debugging-methods/consensus_info.md
@@ -226,7 +226,8 @@ The results of the `consensus_info` command can vary dramatically if you run it

 ### Possible Errors

-* Any of the [universal error types][].
+- Any of the [universal error types][].
+- `reportingUnsupported` - ([Reporting Mode][] servers only) This method is not available in Reporting Mode.

 <!--{# common link defs #}-->
 {% include '_snippets/rippled-api-links.md' %}
--- a/content/references/rippled-api/admin-rippled-methods/status-and-debugging-methods/feature.md
+++ b/content/references/rippled-api/admin-rippled-methods/status-and-debugging-methods/feature.md
@@ -186,8 +186,9 @@ The response follows the [standard format][], with a successful result containin

 ### Possible Errors

-* Any of the [universal error types][].
-* `badFeature` - The `feature` specified was invalidly formatted, or the server does not know an amendment with that name.
+- Any of the [universal error types][].
+- `badFeature` - The `feature` specified was invalidly formatted, or the server does not know an amendment with that name.
+- `reportingUnsupported` - ([Reporting Mode][] servers only) This method is not available in Reporting Mode.

 <!--{# common link defs #}-->
 {% include '_snippets/rippled-api-links.md' %}
--- a/content/references/rippled-api/admin-rippled-methods/status-and-debugging-methods/fetch_info.md
+++ b/content/references/rippled-api/admin-rippled-methods/status-and-debugging-methods/fetch_info.md
@@ -154,7 +154,8 @@ The fields describing a fetch in progress are subject to change without notice.

 ### Possible Errors

-* Any of the [universal error types][].
+- Any of the [universal error types][].
+- `reportingUnsupported` - ([Reporting Mode][] servers only) This method is not available in Reporting Mode.

 <!--{# common link defs #}-->
 {% include '_snippets/rippled-api-links.md' %}
--- a/content/references/rippled-api/admin-rippled-methods/status-and-debugging-methods/manifest.md
+++ b/content/references/rippled-api/admin-rippled-methods/status-and-debugging-methods/manifest.md
@@ -143,6 +143,7 @@ If provided, the `details` object contains the following fields:

 - Any of the [universal error types][].
 - `invalidParams` - The `public_key` field was missing or specified incorrectly.
+- `reportingUnsupported` - ([Reporting Mode][] servers only) This method is not available in Reporting Mode.

 <!--{# common link defs #}-->
 {% include '_snippets/rippled-api-links.md' %}
--- a/content/references/rippled-api/admin-rippled-methods/status-and-debugging-methods/validator_list_sites.md
+++ b/content/references/rippled-api/admin-rippled-methods/status-and-debugging-methods/validator_list_sites.md
@@ -141,7 +141,8 @@ The `last_refresh_status` field can have the following values:

 ### Possible Errors

-* Any of the [universal error types][].
+- Any of the [universal error types][].
+- `reportingUnsupported` - ([Reporting Mode][] servers only) This method is not available in Reporting Mode.

 <!--{# common link defs #}-->
 {% include '_snippets/rippled-api-links.md' %}
--- a/content/references/rippled-api/admin-rippled-methods/status-and-debugging-methods/validators.md
+++ b/content/references/rippled-api/admin-rippled-methods/status-and-debugging-methods/validators.md
@@ -176,7 +176,8 @@ Each member of the `publisher_lists` array is an object with the following field

 ### Possible Errors

-* Any of the [universal error types][].
+- Any of the [universal error types][].
+- `reportingUnsupported` - ([Reporting Mode][] servers only) This method is not available in Reporting Mode.

 <!--{# common link defs #}-->
 {% include '_snippets/rippled-api-links.md' %}
--- a/content/references/rippled-api/api-conventions/basic-data-types.md
+++ b/content/references/rippled-api/api-conventions/basic-data-types.md
@@ -68,17 +68,30 @@ Some types of hash appear in API requests and responses. Others are only calcula
 Many API methods require you to specify an instance of the ledger, with the data retrieved being considered up-to-date as of that particular version of the shared ledger. The commands that accept a ledger version all work the same way. There are three ways you can specify which ledger you want to use:

 1. Specify a ledger by its [Ledger Index][] in the `ledger_index` parameter. Each closed ledger has a ledger index that is 1 higher than the previous ledger. (The very first ledger had ledger index 1.)
+
+        "ledger_index": 61546724
+
 2. Specify a ledger by its [Hash][] value in the `ledger_hash` parameter.
+
+        "ledger_hash": "8BB204CE37CFA7A021A16B5F6143400831C4D1779E6FE538D9AC561ABBF4A929"
+
 3. Specify a ledger by one of the following shortcuts, in the `ledger_index` parameter:
-    * `validated` for the most recent ledger that has been validated by the whole network
+
+    * `validated` for the most recent ledger that has been [validated by consensus](consensus.html#validation)
+
+            "ledger_index": "validated"
+
    * `closed` for the most recent ledger that has been closed for modifications and proposed for validation
+
    * `current` for the server's current working version of the ledger.

 There is also a deprecated `ledger` parameter which accepts any of the above three formats. *Do not* use this parameter; it may be removed without further notice.

-If you do not specify a ledger, the `current` (in-progress) ledger is chosen by default. If you provide more than one field specifying ledgers, the deprecated `ledger` field is used first if it exists, falling back to `ledger_hash`. The `ledger_index` field is ignored unless neither of the other two are present.
+If you do not specify a ledger, the server decides which ledger to use to serve the request. By default, the server chooses the `current` (in-progress) ledger. In [Reporting Mode](rippled-server-modes.html#reporting-mode), the server uses the most recent validated ledger instead. Do not provide more than one field specifying ledgers.

-**Note:** Do not rely on this default behavior for specifying a ledger; it is subject to change. Always specify a ledger version in the request if you can.
+**Note:** Do not rely on the default behavior for specifying a ledger; it is subject to change. Always specify a ledger version in the request if you can.
+
+Reporting Mode does not record ledger data until it has been validated. If you make a request to a Reporting Mode server for the `current` or `closed` ledger, the server forwards the request to a P2P Mode server. If you request a ledger index or hash that is not validated, a Reporting Mode server responds with a `lgrNotFound` error.


 ## Specifying Currency Amounts
--- a/content/references/rippled-api/api-conventions/error-formatting.md
+++ b/content/references/rippled-api/api-conventions/error-formatting.md
@@ -101,15 +101,16 @@ 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:

-* `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) 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.
 - `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.
-    * JSON-RPC returns a 400 Bad Request HTTP error in this case instead.
-* `missingCommand` - (WebSocket only) The request did not specify a `command` field.
-    * JSON-RPC returns a 400 Bad Request HTTP error in this case instead.
-* `noClosed` - The server does not have a closed ledger, typically because it has not finished starting up.
-* `noCurrent` - The server does not know what the current ledger is, due to high load, network problems, validator failures, incorrect configuration, or some other problem.
-* `noNetwork` - The server is having trouble connecting to the rest of the XRP Ledger peer-to-peer network (and is not running in stand-alone mode).
-* `tooBusy` - The server is under too much load to do this command right now. Generally not returned if you are connected as an admin.
-* `unknownCmd` - The request does not contain a [command](rippled-api.html) that the `rippled` server recognizes.
-* `wsTextRequired` - (WebSocket only) The request's [opcode](https://tools.ietf.org/html/rfc6455#section-5.2) is not text. <!-- SPELLING_IGNORE: opcode -->
+- `jsonInvalid` - (WebSocket only) The request is not a proper JSON object.
+    - JSON-RPC returns a 400 Bad Request HTTP error in this case instead.
+- `missingCommand` - (WebSocket only) The request did not specify a `command` field.
+    - JSON-RPC returns a 400 Bad Request HTTP error in this case instead.
+- `noClosed` - The server does not have a closed ledger, typically because it has not finished starting up.
+- `noCurrent` - The server does not know what the current ledger is, due to high load, network problems, validator failures, incorrect configuration, or some other problem.
+- `noNetwork` - The server is having trouble connecting to the rest of the XRP Ledger peer-to-peer network (and is not running in stand-alone mode).
+- `tooBusy` - The server is under too much load to do this command right now. Generally not returned if you are connected as an admin.
+- `unknownCmd` - The request does not contain a [command](rippled-api.html) that the `rippled` server recognizes.
+- `wsTextRequired` - (WebSocket only) The request's [opcode](https://tools.ietf.org/html/rfc6455#section-5.2) is not text. <!-- SPELLING_IGNORE: opcode -->
--- a/content/references/rippled-api/api-conventions/response-formatting.md
+++ b/content/references/rippled-api/api-conventions/response-formatting.md
@@ -13,6 +13,7 @@ The fields of a successful response include:
 | `result`        | Object   | The result of the query; contents vary depending on the command. |
 | `warning`       | String   | _(May be omitted)_ If this field is provided, the value is the string `load`. This means the client is approaching the [rate limiting](rate-limiting.html) threshold where the server will disconnect this client. |
 | `warnings`      | Array    | _(May be omitted)_ If this field is provided, it contains one or more **Warnings Objects** with important warnings. For details, see [API Warnings](#api-warnings). [New in: rippled 1.5.0][] |
+| `forwarded`     | Boolean  | _(May be omitted)_ If `true`, this request and response have been forwarded from a [Reporting Mode][] server to a P2P Mode server (and back) because the request requires data that is not available in Reporting Mode. The default is `false`. |


 ## Example Successful Response
@@ -151,6 +152,27 @@ This warning indicates that the server is [amendment blocked](amendments.html#am

 The server administrator must [upgrade `rippled`](install-rippled.html) to a version that supports the activated amendments.

+### 1003. This is a reporting server
+[New in: rippled 1.7.0][]
+
+Example warning:
+
+```json
+"warnings" : [
+  {
+    "id" : 1003,
+    "message" : "This is a reporting server. The default behavior of a reporting server is to only return validated data. If you are looking for not yet validated data, include \"ledger_index : current\" in your request, which will cause this server to forward the request to a p2p node. If the forward is successful the response will include \"forwarded\" : \"true\""
+  }
+]
+```
+
+This warning indicates that the server answering the request is running [Reporting Mode][]. Certain API methods are not available or behave differently because Reporting Mode does not connect to the peer-to-peer network and does not track ledger data that has not yet been validated.
+
+It is generally safe to ignore this warning.
+
+**Caution:** If you request ledger data without explicitly [specifying a ledger version][Specifying Ledgers], Reporting Mode uses the latest validated ledger by default instead of the current in-progress ledger.
+
+
 ## See Also

 - **Concepts:**
--- a/content/references/rippled-api/public-rippled-methods/account-methods/account_info.md
+++ b/content/references/rippled-api/public-rippled-methods/account-methods/account_info.md
@@ -56,7 +56,7 @@ The request contains the following parameters:
 | `account`      | String                     | A unique identifier for the account, most commonly the account's [Address][]. |
 | `ledger_hash`  | String                     | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) |
 | `ledger_index` | String or Unsigned Integer | _(Optional)_ The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
-| `queue`        | Boolean                    | _(Optional)_ If `true`, and the [FeeEscalation amendment][] is enabled, also returns stats about queued transactions associated with this account. Can only be used when querying for the data from the current open ledger. [New in: rippled 0.33.0][] |
+| `queue`        | Boolean                    | _(Optional)_ If `true`, and the [FeeEscalation amendment][] is enabled, also returns stats about queued transactions associated with this account. Can only be used when querying for the data from the current open ledger. [New in: rippled 0.33.0][] Not available from servers in [Reporting Mode][]. |
 | `signer_lists` | Boolean                    | _(Optional)_ If `true`, and the [MultiSign amendment][] is enabled, also returns any [SignerList objects](signerlist.html) associated with this account. [New in: rippled 0.31.0][] |
 | `strict`       | Boolean                    | _(Optional)_ If `true`, then the `account` field only accepts a public key or XRP Ledger address. Otherwise, `account` can be a secret or passphrase (not recommended). The default is `false`. |

--- a/content/references/rippled-api/public-rippled-methods/server-info-methods/fee.md
+++ b/content/references/rippled-api/public-rippled-methods/server-info-methods/fee.md
@@ -157,7 +157,7 @@ The response follows the [standard format][], with a successful result containin

 ## Possible Errors

-* Any of the [universal error types][].
+- Any of the [universal error types][].


 <!--{# common link defs #}-->
--- a/content/references/rippled-api/public-rippled-methods/subscription-methods/subscribe.md
+++ b/content/references/rippled-api/public-rippled-methods/subscription-methods/subscribe.md
@@ -69,14 +69,17 @@ The following parameters are deprecated and may be removed without further notic

 The `streams` parameter provides access to the following default streams of information:

-* `server` - Sends a message whenever the status of the `rippled` server (for example, network connectivity) changes
-* `ledger` - Sends a message whenever the consensus process declares a new validated ledger
-* `transactions` - Sends a message whenever a transaction is included in a closed ledger
-* `transactions_proposed` - Sends a message whenever a transaction is included in a closed ledger, as well as some transactions that have not yet been included in a validated ledger and may never be. Not all proposed transactions appear before validation.
+- `consensus` - Sends a message whenever the server changes phase in the consensus cycle (open, establish, accepted, and so forth)
+- `ledger` - Sends a message whenever the consensus process declares a new validated ledger
+- `manifests` - Sends a message whenever the server receives an update to a validator's ephemeral signing key.
+- `peer_status` - **(Admin only)** Information about connected peer `rippled` servers, especially with regards to the consensus process.
+- `transactions` - Sends a message whenever a transaction is included in a closed ledger
+- `transactions_proposed` - Sends a message whenever a transaction is included in a closed ledger, as well as some transactions that have not yet been included in a validated ledger and may never be. Not all proposed transactions appear before validation.
    **Note:** [Even some transactions that don't succeed are included](transaction-results.html) in validated ledgers, because they take the anti-spam transaction fee.
-* `validations` - Sends a message whenever the server receives a validation message, regardless of if the server trusts the validator. (An individual `rippled` declares a ledger validated when the server receives validation messages from at least a quorum of trusted validators.)
-* `consensus` - Sends a message whenever the server changes phase in the consensus cycle (open, establish, accepted, and so forth)
-* `peer_status` - **(Admin only)** Information about connected peer `rippled` servers, especially with regards to the consensus process.
+- `server` - Sends a message whenever the status of the `rippled` server (for example, network connectivity) changes
+- `validations` - Sends a message whenever the server receives a validation message, regardless of if the server trusts the validator. (An individual `rippled` declares a ledger validated when the server receives validation messages from at least a quorum of trusted validators.)
+
+**Note:** The following streams are not available from servers in [Reporting Mode][]: `server`, `manifests`, `validations`, `peer_status`, `consensus`. Reporting Mode servers return the error `reportingUnsupported` if you request one of these streams.

 Each member of the `books` array, if provided, is an object with the following fields:

--- a/content/tutorials/get-started/get-started-with-the-rippled-api.md
+++ b/content/tutorials/get-started/get-started-with-the-rippled-api.md
@@ -20,7 +20,7 @@ Ripple provides several public servers for the benefit of the XRP Ledger communi

 [Network]: parallel-networks.html

-¹Ripple's public servers are not for sustained or business use, and they may become unavailable at any time. For regular use, you should run your own `rippled` server or contract someone you trust to do so.
+¹Ripple's public servers are not for sustained or business use, and they may become unavailable at any time. For regular use, you should run your own `rippled` server or contract someone you trust to do so. Ripple includes [Reporting Mode][] servers in its public clusters.


 ## Admin Access