diff --git a/websocket_api.md b/websocket_api.md index 22c1327007..ee8b6578ab 100644 --- a/websocket_api.md +++ b/websocket_api.md @@ -335,6 +335,23 @@ If you are specifying XRP without an amount -- also typically for defining an or Finally, if you are specifying a non-currency for a payment or path definition, and the recipient account of the payment trusts multiple gateways that issue the same currency, you can indicate that the payment should be made in any combination of issuers that the recipient accepts. To do this, specify the recipient account's address as the `issuer` value in the JSON object. +## Possible Server States ## + +Depending on how the `rippled` server is configured, how long it has been running, and other factors, a server may be participating in the global Ripple Network to different degrees. This is represented as the `server_state` field in the responses to the [`server_info`](#server-info) and [`server_state`](#server-state) commands. The possible responses follow a range of ascending interaction, with each subsequent value superseding the previous one. Their definitions are as follows (in order of increasing priority): + +PLEASE CONFIRM THE CONTENTS OF THIS TABLE + +| Value | Description | +|-------|-------------| +| disconnected | The server is not connected to the Ripple Network whatsoever. It may be running in offline mode, or it may not be able to access the network for whatever reason. | +| connected | The server believes it is connected to the network. | +| syncing | The server is currently behind on ledger versions. (It is normal for a server to spend a few minutes catching up after you start it.) | +| tracking | The server is in agreement with the network | +| full | The server is fully caught-up with the network and could participate in validation, but is not doing so (probably because it has not been configured as a validator). | +| validating | The server is participating in validation of the ledger | +| proposing | The server is participating in validation of the ledger and even proposing its own versions. | + + # API Methods # API methods for the Websocket and JSON-RPC APIs are defined by command names, and are divided into Public Commands and Admin Commands. Public Commands are not necessarily meant for the general public, but they are used by any client attached to the server. (Think of Public Commands as being for members or customers of the organization running the server, while the Admin Commands are for the personnel in charge of keeping the server operational.) Public Commands include the general operations for Ripple use, including checking the state of the ledger, finding a path to connecting users, and submitting a transaction, among others. Admin Commands, on the other hand, are meant only for the operators of the server, and include commands for managing the state of the server, the nodes it uses for validation, and other administrative features. @@ -4689,9 +4706,9 @@ The `info` object may have some arrangement of the following fields: | load.threads | Number | *Admin only* The number of threads in the server's main job pool, performing various Ripple Network operations. | | load_factor | Number | The load factor the server is currently enforcing, which affects transaction fees. The load factor is determined by the highest of the individual server's load factor, cluster's load factor, and the overall network's load factor. | | peers | Number | How many other `rippled` servers the node is currently connected to. | -| pubkey_node | String | Public key used to verify this node's signatures? | -| pubkey_validator | String | *Admin only* ??? | -| server_state | String | "full"??? | +| pubkey_node | String | Public key used to verify this node for internal communications; this key is automatically generated by the server the first time it starts up. (If deleted, the node can just create a new pair of keys.) | +| pubkey_validator | String | *Admin only* Public key used by this node to sign ledger validations; . | +| server_state | String | A string indicating to what extent the server is participating in the network. See [Possible Server States](#possible-server-states) for more details. | | validated_ledger | Object | Information about the fully-validated ledger with the highest sequence number (the most recent) | | validated_ledger.age | Unsigned Integer | 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.00005 | @@ -4767,26 +4784,25 @@ The `state` object may have some arrangement of the following fields: | Field | Type | Description | |-------|------|-------------| | build_version | String | The version number of the running `rippled` version. | -| complete_ledgers | String | Range expression indicating the sequence numbers of the ledger versions available. It is also possible to be a disjoint sequence, e.g. "2500-5000,32570-7695432" (I'd love confirmation on that disjoint sequence thing.) | -| io_latency_ms | Number | Amount of time the server is waiting for I/O devices (to do what exactly?), in milliseconds. | +| 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". | +| io_latency_ms | Number | Amount of time spent waiting for I/O operations to be performed, in milliseconds. If this number is not very, very low, then the `rippled` server is probably having serious load issues. | | load | Object | *Admin only* Detailed information about the current load state of the server | | load.job_types | Array | *Admin only* Information about the rate of different types of jobs being performed by the server and how much time it spends on each. | -| load.threads | Number | *Admin only* Number of threads running at all in the server? | -| peers | Number | How many other `rippled` servers the node is currently connected to. | +| load.threads | Number | *Admin only* The number of threads in the server's main job pool, performing various Ripple Network operations. | | load_base | Number | Something to do with load? | -| load_factor | Number | Something to do with load? | +| load_factor | Number | The load factor the server is currently enforcing, which affects transaction fees. The load factor is determined by the highest of the individual server's load factor, cluster's load factor, and the overall network's load factor. | | peers | Number | How many other `rippled` servers the node is currently connected to. | -| pubkey_node | String | Public key used to verify this node's signatures? | -| pubkey_validator | String | *Admin only* ??? | -| server_state | String | "full"??? | -| validated_ledger | Object | Information about the most recently(?) validated ledger version | +| pubkey_node | String | Public key used by this server (along with the corresponding private key) for secure communications between nodes. This key pair is automatically created and stored in rippled's local database the first time it starts up; if lost or deleted, a new key pair can be generated with no ill effects. | +| pubkey_validator | String | *Admin only* Public key used by this server (along with the corresponding private key) to sign proposed ledgers for validation. | +| server_state | String | A string indicating to what extent the server is participating in the network. See [Possible Server States](#possible-server-states) for more details. | +| validated_ledger | Object | Information about the fully-validated ledger with the highest sequence number (the most recent) | | validated_ledger.base_fee | Unsigned Integer | Base fee, in drops of XRP, for propagating a transaction to the network. -| validated_ledger.close_time | Number | Time this ledger was closed, in seconds since the Ripple Epoch? | +| validated_ledger.close_time | Number | Time this ledger was closed, in seconds since the Ripple Epoch | | validated_ledger.hash | String | Unique hash of this ledger version, as hex | | validated_ledger.reserve_base | Unsigned Integer | Minimum amount, in drops of XRP, necessary for every account to keep in reserve | | validated_ledger.reserve_inc | Unsigned Integer | Amount, in drops of XRP, that is added to the account reserve for each item the account owns in the ledger. | | validated_ledger.seq | Unsigned Integer | Unique sequence number of this ledger -| validation_quorum | Unsigned Integer | Number of peer nodes required in order to validate a ledger version? | +| validation_quorum | Number | Minimum number of trusted validations required in order to validate a ledger version. Some circumstances may cause the server to require more validations. | # Convenience Functions #