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

Peer reservations: API, etc.

Browse Source
This commit is contained in:
mDuo13
2019-12-27 17:38:55 -08:00
parent c4d2019894
commit 0254c803aa
9 changed files with 193 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
content/_snippets/peer_reservation_object.md Normal file
View File

@@ -0,0 +1,4 @@
| `Field` | Type | Description |
|:--------------|:-------|:----------------------------------------------------|
| `node` | String | The [node public key][] of the peer server this reservation is for, as [base58][]. |
| `description` | String | _(May be omitted)_ The description provided with this peer reservation, if any. |

3
content/_snippets/rippled-api-links.md
View File

@@ -23,6 +23,9 @@
[ledger format]: ledger-data-formats.html
[Marker]: markers-and-pagination.html
[マーカー]: markers-and-pagination.html
[node public key]: peer-protocol.html#node-key-pair
[peer reservation]: peer-protocol.html#fixed-peers-and-peer-reservations
[peer reservations]: peer-protocol.html#fixed-peers-and-peer-reservations
[result code]: transaction-results.html
[seconds since the Ripple Epoch]: basic-data-types.html#specifying-time
[Rippleエポック以降の経過秒数]: basic-data-types.html#時間の指定

2
content/concepts/the-rippled-server/peer-protocol.md
View File

@@ -37,7 +37,7 @@ The node key pair is saved in the database and reused when the server restarts.
The node key pair also identifies other servers for purposes of [clustering](clustering.html) or [reserving peer slots](#fixed-and-reserved-peers). If you have a cluster of servers, you should configure each server in the cluster with a unique `[node_seed]` setting. For more information on setting up a cluster, see [Cluster `rippled` Servers](cluster-rippled-servers.html).
## Fixed and Reserved Peers
## Fixed Peers and Peer Reservations
Normally, a `rippled` server attempts to maintain a healthy number of peers, and automatically connects to untrusted peers up to a maximum number. You can configure a `rippled` server to remain connected to specific peer servers in several ways:

76
content/references/rippled-api/admin-rippled-methods/peer-management-methods/peer_reservations_add.md
View File

@@ -1,7 +1,7 @@
# peer_reservations_add
[[Source]](TODO "Source")
[[Source]](https://github.com/ripple/rippled/blob/4a1148eb2849513dd1e7ae080288fd47ab57a376/src/ripple/rpc/handlers/Reservations.cpp#L36 "Source")
The `{{currentpage.name}}` method adds a reserved slot for a specific peer server in the XRP Ledger [peer-to-peer network](peer-protocol.html).
The `{{currentpage.name}}` method adds or updates a reserved slot for a specific peer server in the XRP Ledger [peer-to-peer network](peer-protocol.html).
_The `{{currentpage.name}}` method is an [admin method](admin-rippled-methods.html) that cannot be run by unprivileged users._
@@ -16,7 +16,10 @@ An example of the request format:
```json
{
TODO
"id": "peer_reservations_add_example_1",
"command": "{{currentpage.name}}",
"public_key": "n9Jt8awsPzWLjBCNKVEEDQnw4bQEPjezfcQ4gttD1UzbLT1FoG99",
"description": "Ripple s1 server 'WOOL'"
}
```
@@ -25,26 +28,28 @@ An example of the request format:
```json
{
"method": "{{currentpage.name}}",
"params": [
TODO
]
"params": [{
"public_key": "n9Jt8awsPzWLjBCNKVEEDQnw4bQEPjezfcQ4gttD1UzbLT1FoG99",
"description": "Ripple s1 server 'WOOL'"
}]
}
```
*Commandline*
```sh
#Syntax: {{currentpage.name}} TODO
rippled {{currentpage.name}}
#Syntax: {{currentpage.name}} <public_key> [<description>]
rippled {{currentpage.name}} n9Jt8awsPzWLjBCNKVEEDQnw4bQEPjezfcQ4gttD1UzbLT1FoG99 "Ripple s1 server 'WOOL'"
```
<!-- MULTICODE_BLOCK_END -->
The request includes the following parameters:
| `Field` | Type | Description |
|:------------|:--------------------------|:-----------------------------------|
TODO_request_params
| `Field` | Type | Description |
|:--------------|:-------|:----------------------------------------------------|
| `public_key` | String | The [node public key][] of the peer reservation to add a reservation for, in [base58][]. |
| `description` | String | _(Optional)_ A custom description for the peer reservation. There is no specific length limit on this field. |
@@ -54,11 +59,33 @@ An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```json
{
"id": "peer_reservations_add_example_1",
"result": {
"previous": {
"description": "Maecenas atavis edite regibus, O et praesidium et dulce decus meum, Sunt quos curriculo pulverem Olympicum Collegisse iuvat metaque fervidis Evitata rotis palmaque nobilis Terrarum dominos evehit ad deos; Hunc, si mobilium turba Quiritium Certat tergeminis tollere honoribus; Illum, si proprio condidit horreo, Quidquid de Libycis verritur areis.",
"node": "n9Jt8awsPzWLjBCNKVEEDQnw4bQEPjezfcQ4gttD1UzbLT1FoG99"
}
},
"status": "success",
"type": "response"
}
```
*JSON-RPC*
```json
{
TODO
"result": {
"previous": {
"description": "Maecenas atavis edite regibus, O et praesidium et dulce decus meum, Sunt quos curriculo pulverem Olympicum Collegisse iuvat metaque fervidis Evitata rotis palmaque nobilis Terrarum dominos evehit ad deos; Hunc, si mobilium turba Quiritium Certat tergeminis tollere honoribus; Illum, si proprio condidit horreo, Quidquid de Libycis verritur areis.",
"node": "n9Jt8awsPzWLjBCNKVEEDQnw4bQEPjezfcQ4gttD1UzbLT1FoG99"
},
"status": "success"
}
}
```
@@ -69,7 +96,13 @@ Loading: "/etc/rippled.cfg"
Connecting to 127.0.0.1:5005
{
TODO
"result": {
"previous": {
"description": "Maecenas atavis edite regibus, O et praesidium et dulce decus meum, Sunt quos curriculo pulverem Olympicum Collegisse iuvat metaque fervidis Evitata rotis palmaque nobilis Terrarum dominos evehit ad deos; Hunc, si mobilium turba Quiritium Certat tergeminis tollere honoribus; Illum, si proprio condidit horreo, Quidquid de Libycis verritur areis.",
"node": "n9Jt8awsPzWLjBCNKVEEDQnw4bQEPjezfcQ4gttD1UzbLT1FoG99"
},
"status": "success"
}
}
```
@@ -77,16 +110,25 @@ Connecting to 127.0.0.1:5005
The response follows the [standard format][], with a successful result containing the following fields:
| `Field` | Type | Description |
|:--------|:-------|:----------------------------------------------------------|
TODO_params
| `Field` | Type | Description |
|:-----------|:-------|:-------------------------------------------------------|
| `previous` | Object | _(May be omitted)_ The previous entry for the same [node public key][], if there was already a reservation with the same node public key. This object is formatted as a **Peer Reservation Object**, as described below. |
If there was not a previous entry for the same [node public key][], the `result` object is empty.
#### Peer Reservation Object
If the `previous` field is provided, it shows the previous status of this peer reservation, with the following fields:
{% include '_snippets/peer_reservation_object.md' %}
<!--_ -->
### Possible Errors
- Any of the [universal error types][].
- TODO_errors
- `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.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}

61
content/references/rippled-api/admin-rippled-methods/peer-management-methods/peer_reservations_del.md
View File

@@ -1,10 +1,12 @@
# peer_reservations_del
[[Source]](TODO_URL "Source")
[[Source]](https://github.com/ripple/rippled/blob/4a1148eb2849513dd1e7ae080288fd47ab57a376/src/ripple/rpc/handlers/Reservations.cpp#L89 "Source")
The `{{currentpage.name}}` method removes a reserved peer slot.
The `{{currentpage.name}}` method removes a specific [peer reservation][], if one exists.
_The `{{currentpage.name}}` method is an [admin method](admin-rippled-methods.html) that cannot be run by unprivileged users._
**Note:** Removing a peer reservation does not automatically disconnect the corresponding peer, if that peer is connected.
### Request Format
An example of the request format:
@@ -15,7 +17,9 @@ An example of the request format:
```json
{
TODO
"id": "peer_reservations_del_example_1",
"command": "{{currentpage.name}}",
"public_key": "n9Jt8awsPzWLjBCNKVEEDQnw4bQEPjezfcQ4gttD1UzbLT1FoG99"
}
```
@@ -24,26 +28,26 @@ An example of the request format:
```json
{
"method": "{{currentpage.name}}",
"params": [
TODO
]
"params": [{
"public_key": "n9Jt8awsPzWLjBCNKVEEDQnw4bQEPjezfcQ4gttD1UzbLT1FoG99"
}]
}
```
*Commandline*
```sh
#Syntax: {{currentpage.name}} TODO
rippled {{currentpage.name}}
#Syntax: {{currentpage.name}} <public_key>
rippled {{currentpage.name}} n9Jt8awsPzWLjBCNKVEEDQnw4bQEPjezfcQ4gttD1UzbLT1FoG99
```
<!-- MULTICODE_BLOCK_END -->
The request includes the following parameters:
The request includes the following parameter:
| `Field` | Type | Description |
|:------------|:--------------------------|:-----------------------------------|
TODO_request_params
| `public_key` | String | The [node public key][] of the [peer reservation][] to remove, in [base58][] format. |
### Response Format
@@ -52,11 +56,33 @@ An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```json
{
"id": "peer_reservations_del_example_1",
"result": {
"previous": {
"description": "Ripple s1 server 'WOOL'",
"node": "n9Jt8awsPzWLjBCNKVEEDQnw4bQEPjezfcQ4gttD1UzbLT1FoG99"
}
},
"status": "success",
"type": "response"
}
```
*JSON-RPC*
```json
{
TODO
"result" : {
"previous" : {
"description" : "Ripple s1 server 'WOOL'",
"node" : "n9Jt8awsPzWLjBCNKVEEDQnw4bQEPjezfcQ4gttD1UzbLT1FoG99"
},
"status" : "success"
}
}
```
@@ -67,7 +93,13 @@ Loading: "/etc/rippled.cfg"
Connecting to 127.0.0.1:5005
{
TODO
"result" : {
"previous" : {
"description" : "Ripple s1 server 'WOOL'",
"node" : "n9Jt8awsPzWLjBCNKVEEDQnw4bQEPjezfcQ4gttD1UzbLT1FoG99"
},
"status" : "success"
}
}
```
@@ -77,14 +109,15 @@ The response follows the [standard format][], with a successful result containin
| `Field` | Type | Description |
|:--------|:-------|:----------------------------------------------------------|
TODO_params
| `previous` | Object | _(May be omitted)_ A **peer reservation object** with the last state of the peer reservation before deleting it. This field is always provided if a peer reservation was successfully deleted. |
**Note:** If the specified reservation did not exist, this command returns success with an empty result object. In this case, the `previous` field is omitted.
### Possible Errors
- Any of the [universal error types][].
- TODO_errors
- `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.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}

82
content/references/rippled-api/admin-rippled-methods/peer-management-methods/peer_reservations_list.md
View File

@@ -1,6 +1,7 @@
# peer_reservations_list
[[Source]](https://github.com/ripple/rippled/blob/4a1148eb2849513dd1e7ae080288fd47ab57a376/src/ripple/rpc/handlers/Reservations.cpp#L116 "Source")
The `{{currentpage.name}}` method lists reserved peer slots.
The `{{currentpage.name}}` method lists [peer reservations][].
_The `{{currentpage.name}}` method is an [admin method](admin-rippled-methods.html) that cannot be run by unprivileged users._
@@ -15,7 +16,8 @@ An example of the request format:
```json
{
TODO
"id": "peer_reservations_list_example_1",
"command": "{{currentpage.name}}"
}
```
@@ -23,27 +25,20 @@ An example of the request format:
```json
{
"method": "{{currentpage.name}}",
"params": [
TODO
]
"method": "{{currentpage.name}}"
}
```
*Commandline*
```sh
#Syntax: {{currentpage.name}} TODO
#Syntax: {{currentpage.name}}
rippled {{currentpage.name}}
```
<!-- MULTICODE_BLOCK_END -->
The request includes the following parameters:
| `Field` | Type | Description |
|:------------|:--------------------------|:-----------------------------------|
TODO_request_params
This request does not take any parameters.
### Response Format
@@ -52,11 +47,43 @@ An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```json
{
"id": "peer_reservations_list_example_1",
"result": {
"reservations": [
{
"description": "Ripple s1 server 'WOOL'",
"node": "n9Jt8awsPzWLjBCNKVEEDQnw4bQEPjezfcQ4gttD1UzbLT1FoG99"
},
{
"node": "n9MZRo92mzYjjsa5XcqnPC7GFYAnENo9VfJzKmpcS9EFZvw5fgwz"
}
]
},
"status": "success",
"type": "response"
}
```
*JSON-RPC*
```json
{
TODO
"result" : {
"reservations" : [
{
"description" : "Ripple s1 server 'WOOL'",
"node" : "n9Jt8awsPzWLjBCNKVEEDQnw4bQEPjezfcQ4gttD1UzbLT1FoG99"
},
{
"node" : "n9MZRo92mzYjjsa5XcqnPC7GFYAnENo9VfJzKmpcS9EFZvw5fgwz"
}
],
"status" : "success"
}
}
```
@@ -64,10 +91,21 @@ An example of a successful response:
```json
Loading: "/etc/rippled.cfg"
Connecting to 127.0.0.1:5005
2019-Dec-27 21:56:07.253260422 HTTPClient:NFO Connecting to 127.0.0.1:5005
{
TODO
"result" : {
"reservations" : [
{
"description" : "Ripple s1 server 'WOOL'",
"node" : "n9Jt8awsPzWLjBCNKVEEDQnw4bQEPjezfcQ4gttD1UzbLT1FoG99"
},
{
"node" : "n9MZRo92mzYjjsa5XcqnPC7GFYAnENo9VfJzKmpcS9EFZvw5fgwz"
}
],
"status" : "success"
}
}
```
@@ -75,16 +113,20 @@ Connecting to 127.0.0.1:5005
The response follows the [standard format][], with a successful result containing the following fields:
| `Field` | Type | Description |
|:--------|:-------|:----------------------------------------------------------|
TODO_params
| `Field` | Type | Description |
|:---------------|:------|:----------------------------------------------------|
| `reservations` | Array | List of existing [peer reservations][]. Each member is a peer reservation object, as described below. |
#### Peer Reservation Object
Each member of the `reservations` array is a JSON object describing one [peer reservation][]. This object has the following fields:
{% include '_snippets/peer_reservation_object.md' %}
<!--_ -->
### Possible Errors
- Any of the [universal error types][].
- TODO_errors
- `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}

12
content/references/rippled-api/admin-rippled-methods/template-admin-rippled-method.md
View File

@@ -25,9 +25,9 @@ An example of the request format:
```json
{
"method": "{{currentpage.name}}",
"params": [
"params": [{
TODO
]
}]
}
```
@@ -53,6 +53,14 @@ An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```json
{
TODO
}
```
*JSON-RPC*
```json

12
content/references/rippled-api/api-conventions/base58-encodings.md
View File

@@ -6,12 +6,12 @@ The XRP Ledger prefixes different types of values with a specific 8-bit number b
The following table lists all the encodings the XRP Ledger uses:
| Data Type | Starts With | Type Prefix | Content size¹ | Maximum characters |
|:-----------------------------|:------------|:---------------|:--------------|:--|
| [Account][] address | r | `0x00` | 20 bytes | 35 |
| Account public key | a | `0x23` | 33 bytes | 53 |
| Seed value (for secret keys) | s | `0x21` | 16 bytes | 29 |
| Validation public key | n | `0x1C` | 33 bytes | 53 |
| Data Type | Starts With | Type Prefix | Content size¹ | Maximum characters |
|:-----------------------------------------|:------------|:------------|:--------------|:--|
| [Account][] address | r | `0x00` | 20 bytes | 35 |
| Account public key | a | `0x23` | 33 bytes | 53 |
| Seed value (for secret keys) | s | `0x21` | 16 bytes | 29 |
| Validation public key or node public key | n | `0x1C` | 33 bytes | 53 |
¹ Content size excludes the 1-byte type prefix.

2
content/tutorials/manage-the-rippled-server/configure-peering/configure-peer-reservations.md
View File

@@ -1,6 +1,6 @@
# Configure Peer Reservations
A [peer reservation](peer-protocol.html#fixed-and-reserved-peers) is a setting that makes a `rippled` server always accept connections from a peer matching the reservation.
A [peer reservation][] is a setting that makes a `rippled` server always accept connections from a peer matching the reservation.
***TODO: steps for the tasks below***