Skip to content

Update server_info and server_state methods #3252

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 2, 2025
Merged

Update server_info and server_state methods #3252

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8f3a31b
specify information about network_ledger field in server_info response
ckeshava Mar 7, 2025
85eec21
Clarify network_ledger field & remove reporting mode fields
mDuo13 Aug 20, 2025
eb1fa6c
Refactor server_info/server_state response formatting slightly
mDuo13 Aug 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 0 additions & 13 deletions docs/_snippets/etl-source-object.md
View file
Open in desktop

This file was deleted.

9 changes: 9 additions & 0 deletions docs/_snippets/state-accounting-object.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
### State Accounting Object
<!-- This nested object definition is identical across server_state and server_info -->

Each field in the `state_accounting` object has a key that refers to a specific [server state](/docs/references/http-websocket-apis/api-conventions/rippled-server-states), and a value that is an object with the following fields:

| Field | Value | Description |
|---------------|-----------------|-------------|
| `duration_us` | String - Number | The number of microseconds the server has spent in this state. (This is updated whenever the server transitions into another state.) |
| `transitions` | String - Number | The number of times the server has changed into this state. |
43 changes: 23 additions & 20 deletions ...ences/http-websocket-apis/public-api-methods/server-info-methods/server_info.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ The `info` object may have some arrangement of the following fields:
|:------------------------------------|:----------------|:---------------------|
| `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, this server is [amendment blocked](../../../../concepts/networks-and-servers/amendments.md#amendment-blocked-servers). If the server is not amendment blocked, the response omits this field. |
| `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, as a [Server Ledger Object](#server-ledger-object). If the most recently validated ledger is available, the response omits this field and includes `validated_ledger` instead. |
| `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`. |
| `git` | Object | _(Admin only)_ The Git details of your `rippled` build. |
| `git.branch` | String | _(Admin only)_ The Git branch used to build your version of `rippled`. |
Expand All @@ -104,38 +104,41 @@ The `info` object may have some arrangement of the following fields:
| `load_factor_fee_escalation` | Number | _(May be omitted)_ The current multiplier to the transaction cost that a transaction must pay to get into the open ledger. |
| `load_factor_fee_queue` | Number | _(May be omitted)_ The current multiplier to the transaction cost that a transaction must pay to get into the queue, if the queue is full. |
| `load_factor_server` | Number | _(May be omitted)_ The current multiplier to the transaction cost based on load to the server, cluster, and network, but not factoring in the open ledger cost. |
| `peers` | Number | _(Omitted by [reporting mode][Reporting mode] servers)_ How many other `rippled` servers this one is currently connected to. |
| `network_ledger` | String | _(May be omitted)_ When [starting the server with the `--net` parameter](../../../../infrastructure/commandline-usage.md), this field contains the string `waiting` while the server is syncing to the network. The field is omitted otherwise. |
| `peers` | Number | How many other `rippled` servers this one is currently connected to. |
| `ports` | Array | A list of ports where the server is listening for API commands. Each entry in the array is a [Port Descriptor object](#port-descriptor-object). {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.12.0" %}New in: rippled 1.12.0{% /badge %} |
| `pubkey_node` | String | Public key used to verify this server for peer-to-peer communications. This [_node key pair_](../../../../concepts/networks-and-servers/peer-protocol.md#node-key-pair) is automatically generated by the server the first time it starts up. (If deleted, the server can create a new pair of keys.) You can set a persistent value in the config file using the `[node_seed]` config option, which is useful for [clustering](../../../../concepts/networks-and-servers/clustering.md). |
| `pubkey_validator` | String | _(Admin only)_ Public key used by this node to sign ledger validations. This _validation key pair_ is derived from the `[validator_token]` or `[validation_seed]` config field. |
| `reporting` | Object | _([Reporting mode](../../../../concepts/networks-and-servers/rippled-server-modes.md) servers only)_ Information about this server's reporting-mode specific configurations. |
| `reporting.etl_sources` | Array | _([Reporting mode](../../../../concepts/networks-and-servers/rippled-server-modes.md) servers only)_ A list of P2P-mode servers this reporting mode is retrieving data from. Each entry in this array is an [ETL Source object](#etl-source-object). |
| `reporting.is_writer` | Boolean | _([Reporting mode](../../../../concepts/networks-and-servers/rippled-server-modes.md) servers only)_ If `true`, this server is writing to the external database with ledger data. If `false`, it is not currently writing, possibly because another reporting mode server is currently populating a shared database, or because it's configured as read-only. |
| `reporting.last_publish_time` | String | _([Reporting mode](../../../../concepts/networks-and-servers/rippled-server-modes.md) servers only)_ An ISO 8601 timestamp indicating when this server last published a validated ledger to its [subscription streams](../subscription-methods/subscribe.md). |
| `server_state` | String | A string indicating to what extent the server is participating in the network. See [Possible Server States](../../api-conventions/rippled-server-states.md) for more details. |
| `server_state_duration_us` | Number | The number of consecutive microseconds the server has been in the current state. |
| `state_accounting` | Object | A map of various [server states](../../api-conventions/rippled-server-states.md) with information about the time the server spends in each. This can be useful for tracking the long-term health of your server's connectivity to the network. |
| `state_accounting.*.duration_us` | String | The number of microseconds the server has spent in this state. (This is updated whenever the server transitions into another state.) |
| `state_accounting.*.transitions` | String | The number of times the server has changed into this state. |
| `time` | String | The current time in UTC, according to the server's clock. |
| `state_accounting` | Object | A map of various [server states](../../api-conventions/rippled-server-states.md) with information about the time the server spends in each. This can be useful for tracking the long-term health of your server's connectivity to the network. The contents of this field are formatted as [State Accounting Objects](#state-accounting-object). || `time` | String | The current time in UTC, according to the server's clock. |
| `uptime` | Number | Number of consecutive seconds that the server has been operational. |
| `validated_ledger` | Object | _(May be omitted)_ Information about the most recent fully-validated ledger. If the most recent validated ledger is not available, the response omits this field and includes `closed_ledger` instead. |
| `validated_ledger.age` | Number | The time since the ledger was closed, in seconds. |
| `validated_ledger.base_fee_xrp` | Number | Base fee, in XRP. This may be represented in scientific notation such as `1e-05` for 0.00001. |
| `validated_ledger.hash` | String | Unique hash for the ledger, as hexadecimal. |
| `validated_ledger.reserve_base_xrp` | Number | Minimum amount of XRP (not drops) necessary for every account to keep in reserve |
| `validated_ledger.reserve_inc_xrp` | Number | Amount of XRP (not drops) added to the account reserve for each object an account owns in the ledger. |
| `validated_ledger.seq` | Number | The [ledger index][] of the latest validated ledger. |
| `validated_ledger` | Object | _(May be omitted)_ Information about the most recent fully-validated ledger, as a [Server Ledger Object](#server-ledger-object). If the most recent validated ledger is not available, the response omits this field and includes `closed_ledger` instead. |
| `validation_quorum` | Number | Minimum number of trusted validations required to validate a ledger version. Some circumstances may cause the server to require more validations. |
| `validator_list_expires` | String | _(Admin only)_ Either the human readable time, in UTC, when the current validator list expires, the string `unknown` if the server has yet to load a published validator list or the string `never` if the server uses a static validator list. |
| `counters` | Object | This object contains performance metrics pertaining to the RPC calls (currently executing calls and completed calls) and the JobQueue. It also contains details of the nodestore like `node_writes`, `node_reads_total`, `node_reads_hit`, etc|
| `current_activity` | Object | This field lists the items currently being run in the job queue and contains two arrays for `jobs` and `methods`. |

{% admonition type="info" name="Note" %}If the `closed_ledger` field is present and has a small `seq` value (less than 8 digits), that indicates `rippled` does not currently have a copy of the validated ledger from the peer-to-peer network. This could mean your server is still syncing. Typically, it takes about 5 minutes to sync with the network, depending on your connection speed and hardware specs.{% /admonition %}
{% partial file="/docs/_snippets/port-descriptor-object.md" /%}

{% partial file="/docs/_snippets/etl-source-object.md" /%}
{% partial file="/docs/_snippets/state-accounting-object.md" /%}

{% partial file="/docs/_snippets/port-descriptor-object.md" /%}
### Server Ledger Object

The response provides either a `validated_ledger` field or a `closed_ledger` field. Either field contains an object with the following fields:

| Field | Value | Description |
|--------------------|-------------------|-------------|
| `age` | Number | The time since the ledger was closed, in seconds. |
| `base_fee_xrp` | Number | Base fee, in XRP (not drops). This may be represented in scientific notation such as `1e-05` for 0.00001. |
| `hash` | String - [Hash][] | Unique hash for the ledger, as hexadecimal. |
| `reserve_base_xrp` | Number | Minimum amount of XRP (not drops) necessary for every account to keep in reserve |
| `reserve_inc_xrp` | Number | Amount of XRP (not drops) added to the account reserve for each object an account owns in the ledger. |
| `seq` | Number | The [ledger index][] of the latest validated ledger. |

Note that the [server_state method][] provides a similar object with slightly different formatting (using drops of XRP instead of decimal XRP, for example).

{% admonition type="info" name="Note" %}If the `closed_ledger` field is present and has a small `seq` value (less than 8 digits), that indicates `rippled` does not currently have a copy of the validated ledger from the peer-to-peer network. This could mean your server is still syncing. Typically, it takes up to 15 minutes to sync with the network, depending on your connection speed and hardware specs. See [Server Doesn't Sync](/docs/infrastructure/troubleshooting/server-doesnt-sync.md) for troubleshooting information.{% /admonition %}

## Possible Errors

Expand Down
Loading