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

Add validator RPC updates

Browse Source 
validator_list / validator_sites edits (now in 0.80.1)

Update Validator RPC docs to match 0.80.1 changes
This commit is contained in:
Brad Chase
2017-10-09 16:27:22 -04:00
committed by mDuo13
parent 973ee52f25
commit df621af60c
2 changed files with 332 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

345
content/reference-rippled.md
View File

@@ -573,6 +573,8 @@ Admin commands are only available if you [connect to `rippled`](#connecting-to-r
* [`stop` - Shut down the rippled server](#stop)
* [`validation_create` - Generate keys for a new rippled validator](#validation-create)
* [`validation_seed` - Temporarily set key to be used for validating](#validation-seed)
* [`validators` - Get information about the current validators](#validators)
* [`validator_list_sites` - Get information about sites that publish validator lists](#validator-list-sites)
* [`wallet_propose` - Generate keys for a new account](#wallet-propose)
The following admin commands are deprecated and may be removed without further notice:
@@ -8802,7 +8804,8 @@ An example of a successful response:
"reserve_inc_xrp": 5,
"seq": 18614732
},
"validation_quorum": 4
"validation_quorum": 4,
"validator_list_expires" : "2017-Oct-12 16:06:36"
}
}
}
@@ -8919,7 +8922,8 @@ An example of a successful response:
"reserve_inc_xrp" : 5,
"seq" : 24901185
},
"validation_quorum" : 4
"validation_quorum" : 4,
"validator_list_expires" : "2017-Oct-12 16:06:36"
},
"status" : "success"
}
@@ -8940,9 +8944,9 @@ The `info` object may have some arrangement of the following fields:
| `hostid` | String | On an admin request, returns the hostname of the server running the `rippled` instance; otherwise, returns a unique four letter word. |
| `io_latency_ms` | Number | Amount of time spent waiting for I/O operations, in milliseconds. If this number is not very, very low, then the `rippled` server is probably having serious load issues. |
| `last_close` | Object | Information about the last time the server closed a ledger, including the amount of time it took to reach a consensus and the number of trusted validators participating. |
| `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 the server is doing and how much time it spends on each. |
| `load.threads` | Number | *Admin only* The number of threads in the server's main job pool. |
| `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 the server is doing and how much time it spends on each. |
| `load.threads` | Number | _(Admin only)_ The number of threads in the server's main job pool. |
| `load_factor` | Number | The load-scaled open ledger transaction cost the server is currently enforcing, as a multiplier on the base transaction cost. For example, at `1000` load factor and a reference transaction cost of 10 drops of XRP, the load-scaled transaction cost is 10,000 drops (0.01 XRP). The load factor is determined by the highest of the [individual server's load factor](concept-transaction-cost.html#local-load-cost), the cluster's load factor, the [open ledger cost](concept-transaction-cost.html#open-ledger-cost) and the overall network's load factor. [Updated in: rippled 0.33.0][New in: rippled 0.33.0] |
| `load_factor_local` | Number | (May be omitted) Current multiplier to the [transaction cost][] based on load to this server. |
| `load_factor_net` | Number | (May be omitted) Current multiplier to the [transaction cost][] being used by the rest of the network (estimated from other servers' reported load values). |
@@ -8951,8 +8955,8 @@ The `info` object may have some arrangement of the following fields:
| `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. [New in: rippled 0.32.0][] |
| `load_factor_server` | Number | (May be omitted) The load factor the server is enforcing, not including the [open ledger cost](concept-transaction-cost.html#open-ledger-cost). [New in: rippled 0.33.0][] |
| `peers` | Number | How many other `rippled` servers this one is currently connected to. |
| `pubkey_node` | String | Public key used to verify this server for peer-to-peer communications; this key is automatically generated by the server the first time it starts up. (If deleted, the server can create a new pair of keys.) |
| `pubkey_validator` | String | *Admin only* Public key used by this server to sign ledger validations. |
| `pubkey_node` | String | Public key used to verify this server for peer-to-peer communications. This key is automatically generated by the server the first time it starts up. (If deleted, the server can 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. |
| `state_accounting` | Object | A map of various [server states](#possible-server-states) 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. [New in: rippled 0.30.1][] |
| `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.) [New in: rippled 0.30.1][] |
@@ -8966,6 +8970,7 @@ The `info` object may have some arrangement of the following fields:
| `validated_ledger.reserve_inc_xrp` | Unsigned Integer | Amount of XRP (not drops) added to the account reserve for each object an account owns in the ledger |
| `validated_ledger.seq` | Number - [Ledger Index][] | The ledger index of the latest validate ledger |
| `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 when the current validator list will expire, 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. [New in: rippled 0.80.1][] |
**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.
@@ -9116,7 +9121,8 @@ An example of a successful response:
"reserve_inc": 5000000,
"seq": 18615049
},
"validation_quorum": 4
"validation_quorum": 4,
"validator_list_expires": 561139596
}
}
}
@@ -9211,7 +9217,8 @@ An example of a successful response:
"reserve_inc" : 5000000,
"seq" : 18615037
},
"validation_quorum" : 4
"validation_quorum" : 4,
"validator_list_expires" : 561139596
},
"status" : "success"
}
@@ -9231,9 +9238,9 @@ The `state` object may have some arrangement of the following fields:
| `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". |
| `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. |
| `io_latency_ms` | Number | Amount of time spent waiting for I/O operations, 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 the server is doing and how much time it spends on each. |
| `load.threads` | Number | *Admin only* The number of threads in the server's main job pool. |
| `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 the server is doing and how much time it spends on each. |
| `load.threads` | Number | _(Admin only)_ The number of threads in the server's main job pool. |
| `load_base` | Integer | This is the baseline amount of server load used in [transaction cost](concept-transaction-cost.html) calculations. If the `load_factor` is equal to the `load_base` then only the base transaction cost is enforced. If the `load_factor` is higher than the `load_base`, then transaction costs are multiplied by the ratio between them. For example, if the `load_factor` is double the `load_base`, then transaction costs are doubled. |
| `load_factor` | Number | The load factor the server is currently enforcing. The ratio between this value and the `load_base` determines the multiplier for transaction costs. The load factor is determined by the highest of the individual server's load factor, cluster's load factor, the [open ledger cost](concept-transaction-cost.html#open-ledger-cost), and the overall network's load factor. [Updated in: rippled 0.33.0][New in: rippled 0.33.0] |
| `load_factor_fee_escalation` | Integer | (May be omitted) The current multiplier to the [transaction cost][] to get into the open ledger, in [fee levels][]. [New in: rippled 0.32.0][] |
@@ -9241,8 +9248,8 @@ The `state` object may have some arrangement of the following fields:
| `load_factor_fee_reference` | Integer | (May be omitted) The [transaction cost][] with no load scaling, in [fee levels][]. [New in: rippled 0.32.0][] |
| `load_factor_server` | Number | (May be omitted) The load factor the server is enforcing, not including the [open ledger cost](concept-transaction-cost.html#open-ledger-cost). [New in: rippled 0.33.0][] |
| `peers` | Number | How many other `rippled` servers this one is currently connected to. |
| `pubkey_node` | String | Public key used to verify this server for peer-to-peer communications; this 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.) |
| `pubkey_validator` | String | *Admin only* Public key of the keypair used by this server to sign proposed ledgers for validation. |
| `pubkey_node` | String | Public key used to verify this server for peer-to-peer communications. This 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.) |
| `pubkey_validator` | String | _(Admin only)_ Public key of the keypair used by this server 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. |
| `state_accounting` | Object | A map of various [server states](#possible-server-states) 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. [New in: rippled 0.30.1][] |
| `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.) [New in: rippled 0.30.1][] |
@@ -9256,6 +9263,7 @@ The `state` object may have some arrangement of the following fields:
| `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` | 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` | Number | _(Admin only)_ When the current validator list will expire, in seconds since the [Ripple Epoch](#specifying-time), or 0 if the server has yet to load a published validator list. [New in: rippled 0.80.1][] |
[fee levels]: concept-transaction-cost.html#fee-levels
@@ -10698,6 +10706,315 @@ The response follows the [standard format](#response-formatting), with a success
* Any of the [universal error types](#universal-errors).
* `badSeed` - The request provided an invalid secret value. This usually means that the secret value appears to be a valid string of a different format, such as an account address or validation public key.
## validators ##
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/Validators.cpp "Source")
The `validators` command returns human readable information about the current list of published and trusted validators used by the server. [New in: rippled 0.80.1][]
*The `validators` request is an [admin command](#connecting-to-rippled) that cannot be run by unprivileged users!*
#### Request Format ####
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```
{
"id": 1,
"command": "validators"
}
```
*JSON-RPC*
```
{
"method": "validators",
"params": [
{}
]
}
```
*Commandline*
```
#Syntax: validators
rippled validators
```
<!-- MULTICODE_BLOCK_END -->
The request includes no parameters.
#### Response Format ####
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```
{
"id":5,
"status":"success",
"type":"response",
"result":{
"local_static_keys": [],
"publisher_lists":[
{
"available":true,
"expiration":"2017-Oct-13 14:56:00",
"list":[
"n9Ltz6ZxPRWTkqwBbpvgbaXPgm6GYCxCJRqFgNXhWVUebgezo28H",
"n94D73ZKSUaTDCnUqYW5ugJ9fHPNxda9GQVoWA6BGtcKuuhozrD1"
],
"pubkey_publisher":"ED58ED4AA543B524F16771F6E1367BAA220D99DCF22CD8CF7A11309E9EAB1B647B",
"seq":1,
"version":1
}
],
"signing_keys":{},
"status":"success",
"trusted_validator_keys":[
"n94D73ZKSUaTDCnUqYW5ugJ9fHPNxda9GQVoWA6BGtcKuuhozrD1",
"n9Ltz6ZxPRWTkqwBbpvgbaXPgm6GYCxCJRqFgNXhWVUebgezo28H"
],
"validation_quorum":2,
"validator_list_expires":"2017-Oct-13 14:56:00"
}
}
```
*JSON-RPC*
```
200 OK
{
"result":{
"local_static_keys": [],
"publisher_lists":[
{
"available":true,
"expiration":"2017-Oct-13 14:56:00",
"list":[
"n9Ltz6ZxPRWTkqwBbpvgbaXPgm6GYCxCJRqFgNXhWVUebgezo28H",
"n94D73ZKSUaTDCnUqYW5ugJ9fHPNxda9GQVoWA6BGtcKuuhozrD1"
],
"pubkey_publisher":"ED58ED4AA543B524F16771F6E1367BAA220D99DCF22CD8CF7A11309E9EAB1B647B",
"seq":1,
"version":1
}
],
"signing_keys":{},
"status":"success",
"trusted_validator_keys":[
"n94D73ZKSUaTDCnUqYW5ugJ9fHPNxda9GQVoWA6BGtcKuuhozrD1",
"n9Ltz6ZxPRWTkqwBbpvgbaXPgm6GYCxCJRqFgNXhWVUebgezo28H"
],
"validation_quorum":2,
"validator_list_expires":"2017-Oct-13 14:56:00"
},
"status":"success"
}
```
*Commandline*
```
Loading: "/etc/rippled.cfg"
Connecting to 127.0.0.1:5005
{
"result":{
"local_static_keys": [],
"publisher_lists":[
{
"available":true,
"expiration":"2017-Oct-13 14:56:00",
"list":[
"n9Ltz6ZxPRWTkqwBbpvgbaXPgm6GYCxCJRqFgNXhWVUebgezo28H",
"n94D73ZKSUaTDCnUqYW5ugJ9fHPNxda9GQVoWA6BGtcKuuhozrD1"
],
"pubkey_publisher":"ED58ED4AA543B524F16771F6E1367BAA220D99DCF22CD8CF7A11309E9EAB1B647B",
"seq":1,
"version":1
}
],
"signing_keys":{},
"status":"success",
"trusted_validator_keys":[
"n94D73ZKSUaTDCnUqYW5ugJ9fHPNxda9GQVoWA6BGtcKuuhozrD1",
"n9Ltz6ZxPRWTkqwBbpvgbaXPgm6GYCxCJRqFgNXhWVUebgezo28H"
],
"validation_quorum":2,
"validator_list_expires":"2017-Oct-13 14:56:00"
},
"status":"success"
}
```
<!-- MULTICODE_BLOCK_END -->
The response follows the [standard format](#response-formatting), with a successful result containing the following fields:
| `Field` | Type | Description |
|:-------------------------|:-------|:-----------------------------------------|
| `listed_static_keys` | Array | Array of public keys for validators always eligible for inclusion in the trusted list. |
| `publisher_lists` | Array | Array of publisher list objects. |
| `signing_keys` | Object | Mapping from master public key to current signing key for listed validators that use validator manifests. |
| `trusted_validator_keys` | Array | Array of public keys for currently trusted validators. |
| `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 | Either the human readable time when the current validator list will expire, 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. |
Each member of the `publisher_lists` array is an object with the following fields:
| `Field` | Type | Description |
|:-------------------|:-----------------|:-------------------------------------|
| `available` | Boolean | If `false`, the validator keys in `list` may no longer be supported by this publisher. |
| `expiration` | String | The human readable time when this published list will expire. |
| `list` | Array | Array of published validator keys. |
| `pubkey_publisher` | String | Ed25519 or ECDSA public key of the list publisher, as hexadecimal. |
| `seq` | Unsigned Integer | The sequence number of this published list. |
| `version` | Unsigned Integer | The version of the list format. |
#### Possible Errors ####
* Any of the [universal error types](#universal-errors).
## validator_list_sites ##
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/ValidatorListSites.cpp "Source")
The `validator_list_sites` command returns status information of sites serving validator lists. [New in: rippled 0.80.1][]
*The `validator_list_sites` request is an [admin command](#connecting-to-rippled) that cannot be run by unprivileged users!*
#### Request Format ####
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```
{
"id": 1,
"command": "validator_list_sites"
}
```
*JSON-RPC*
```
{
"method": "validator_list_sites",
"params": [
{}
]
}
```
*Commandline*
```
#Syntax: validator_list_sites
rippled validator_list_sites
```
<!-- MULTICODE_BLOCK_END -->
The request includes no parameters.
#### Response Format ####
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```
{
"id":5,
"status":"success",
"type":"response",
"result": {
"validator_sites": [
{
"last_refresh_status": "accepted",
"last_refresh_time": "2017-Oct-13 21:26:37",
"refresh_interval_min": 5,
"uri": "http://127.0.0.1:51447/validators"
}
]
}
}
}
```
*JSON-RPC*
```
200 OK
{
"result": {
"status": "success",
"validator_sites": [
{
"last_refresh_status": "accepted",
"last_refresh_time": "2017-Oct-13 21:26:37",
"refresh_interval_min": 5,
"uri": "http://127.0.0.1:51447/validators"
}
]
}
}
```
*Commandline*
```
Loading: "/etc/rippled.cfg"
Connecting to 127.0.0.1:5005
{
"result": {
"status": "success",
"validator_sites": [
{
"last_refresh_status": "accepted",
"last_refresh_time": "2017-Oct-13 21:26:37",
"refresh_interval_min": 5,
"uri": "http://127.0.0.1:51447/validators"
}
]
}
}
```
<!-- MULTICODE_BLOCK_END -->
The response follows the [standard format](#response-formatting), with a successful result containing the following field:
| `Field` | Type | Description |
|:------------------|:------|----------------------------------|
| `validator_sites` | Array | Array of validator site objects. |
Each member of the `validator_sites` field array is an object with the following fields:
| `Field` | Type | Description |
|:-----------------------|:-----------------|:--------------------------------|
| `last_refresh_status` | String | If present, the[`ListDisposition`](https://github.com/ripple/rippled/blob/master/src/ripple/app/misc/ValidatorList.h) of the most recent refresh of the site. If missing, the site has not yet been succesfully queried. |
| `last_refresh_time` | String | Human readable time when the site was last queried. If missing, the site has not yet been succesfully queried. |
| `refresh_interval_min` | Unsigned Integer | The number of minutes between refresh attempts. |
| `uri` | String | The URI of the site. |
#### Possible Errors ####
* Any of the [universal error types](#universal-errors).
## peers ##
[[Source]<br>](https://github.com/ripple/rippled/blob/52f298f150fc1530d201d3140c80d3eaf781cb5f/src/ripple/rpc/handlers/Peers.cpp "Source")

1
content/snippets/rippled_versions.md
View File

@@ -28,3 +28,4 @@
[New in: rippled 0.50.0]: https://github.com/ripple/rippled/releases/tag/0.50.0 "BADGE_BLUE"
[New in: rippled 0.70.0]: https://github.com/ripple/rippled/releases/tag/0.70.0 "BADGE_BLUE"
[New in: rippled 0.70.2]: https://github.com/ripple/rippled/releases/tag/0.70.2 "BADGE_BLUE"
[New in: rippled 0.80.1]: https://github.com/ripple/rippled/releases/tag/0.80.1 "BADGE_BLUE"