All non-XRP currency balances (issuances) in the Ripple Consensus Ledger (RCL) are tied to accounting relationships between two Ripple addresses. When a financial institution uses Ripple's recommended separation of roles, funds relating to that institution tend to flow in a cycle.
When the issuing address sends payments, it creates balances in the accounting relationships in the Ripple Consensus Ledger. Within the RCL, users can exchange balances across different accounting relationships, so we use the term issuances to describe any non-XRP balance. Issuances have positive value from the perspective of the counterparties. The same issuances are negative balances from the perspective of the issuing address, since they represent obligations. When the issuing address receives a payment, this reduces its obligations, erasing the issuances that were sent.
+When the issuing address sends payments, it creates balances in the accounting relationships in the Ripple Consensus Ledger. Within the RCL, users can exchange balances across different accounting relationships, so we use the term issuances to describe any non-XRP balance. Issuances have negative value from the perspective of the issuing address, since they represent obligations. The same issuances have positive value from the perspective of the issuing address's counterparties. When the issuing address receives a payment, this reduces its obligations, erasing the issuances that were sent.
The issuing address sends issuances to a standby address, or directly to an operational address. The standby addresses send those issuances to operational addresses. Operational addresses send payments to other counterparties, such as liquidity providers, partners, and other customers. Because all issuances are tied to accounting relationships with the issuing address, payments and exchanges of issuances "ripple through" the issuing address. The payment debits the sender's balance in its accounting relationship with the issuing address and credits the recipient's balance in the recipient's accounting relationship with the issuing address. The Ripple Consensus Ledger also supports more complicated paths that connect multiple issuers through order books and liquidity providers who allow their funds to ripple.
The issuing address is like a vault. Partners, customers, and operational addresses create accounting relationships (trust lines) to the issuing address, but this address sends as few transactions as possible. Periodically, a human operator creates and signs a transaction from the issuing address in order to refill the balances of a standby or operational address. Ideally, the secret key used to sign these transactions should never be accessible from any internet-connected computer.
diff --git a/content/reference-rippled.md b/content/reference-rippled.md index 5715460407..645e286559 100755 --- a/content/reference-rippled.md +++ b/content/reference-rippled.md @@ -7,7 +7,9 @@ The core peer-to-peer server that operates the Ripple Network is called `rippled * [Transaction Reference](reference-transaction-format.html) * JavaScript Client Library - [RippleAPI](reference-rippleapi.html) + # WebSocket and JSON-RPC APIs # + If you want to communicate directly with a `rippled` server, you can use either the WebSocket API or the JSON-RPC API. Both APIs use the same list of commands, with almost entirely the same parameters in each command. Alternatively, you can use [RippleAPI](reference-rippleapi.html), which is a simplified JavaScript client library, which communicates directly with a `rippled` server from [Node.js](http://nodejs.org/) or a web browser. * The WebSocket API uses the [WebSocket protocol](http://www.html5rocks.com/en/tutorials/websockets/basics/), available in most browsers and Javascript implementations, to achieve persistent two-way communication. There is not a 1:1 correlation between requests and responses. Some requests prompt the server to send multiple messages back asynchronously; other times, responses may arrive in a different order than the requests that prompted them. The `rippled` server can be configured to accept secured (wss:), unsecured (ws:) WebSocket connections, or both. @@ -24,7 +26,7 @@ The WebSocket and JSON-RPC APIs are still in development, and are subject to cha ## Connecting to rippled ## -Before you can run any commands against a `rippled` server, you must know which server you are connecting to. Most servers are configured not to accept requests directly from the outside network. +Before you can run any commands against a `rippled` server, you must know which server you are connecting to. Most servers are configured not to accept API requests directly from the outside network. Alternatively, you can [run your own local copy of `rippled`](tutorial-rippled-setup.html). This is required if you want to access any of the [Admin Commands](#list-of-admin-commands). In this case, you should use whatever IP and port you configured the server to bind. (For example, `127.0.0.1:54321`) Additionally, in order to access admin functionality, you must connect from a port/IP address marked as admin in the config file. @@ -10955,6 +10957,182 @@ The response follows the [standard format](#response-formatting), with a success * Any of the [universal error types](#universal-errors). + + + +# Peer Protocol # + +Servers in the Ripple Consensus Ledger communicate to each other using the Ripple peer protocol, also known as RTXP. Peer servers connect via HTTPS and then _upgrade_ to RTXP. (For more information, see the [Overlay Network article in the `rippled` repository](https://github.com/ripple/rippled/blob/906ef761bab95f80b0a7e0cab3b4c594b226cf57/src/ripple/overlay/README.md#handshake).) + +## Configuring the Peer Protocol ## + +In order to participate in the Ripple Consensus Ledger, `rippled` servers connects to arbitrary peers using the peer protocol. (All such peers are treated as untrusted.) + +Ideally, the server should be able to send _and_ receive connections on the peer port. You should forward the port used for the peer protocol through your firewall to the `rippled` server. The [default `rippled` configuration file](https://github.com/ripple/rippled/blob/develop/doc/rippled-example.cfg) listens for incoming peer protocol connections on port 51235 on all network interfaces. You can change the port used by editing the appropriate stanza in your `rippled.cfg` file. + +Example: + +``` +[port_peer] +port = 51235 +ip = 0.0.0.0 +protocol = peer +``` + +## Peer Crawler ## + +The Peer Crawler reports information about other servers a `rippled` server is connected to as peers. The [`peers` command](#peers) in the [WebSocket and JSON-RPC APIs](#websocket-and-json-rpc-apis) also returns a similar, more comprehensive set of information, but requires admin access to the server. The Peer Crawler response is available to other servers on a non-privileged basis through the Peer Protocol (RTXP) port. + +#### Request Format #### + +To request the Peer Crawler information, make the following HTTP request: + +* **Protocol:** https +* **HTTP Method:** GET +* **Host:** (any `rippled` server, by hostname or IP address) +* **Port:** (port number where the `rippled` server uses the Peer Protocol, typically 51235) +* **Path:** `/crawl` +* **Notes:** Most `rippled` servers use a self-signed certificate to respond to the request. By default, most tools (including web browsers) flag or block such responses for being untrusted. You must ignore the certificate checking (for example, if using cURL, add the `--insecure` flag) to display a response from those servers. + +#### Response Format #### + +The response has the status code **200 OK** and a JSON object in the message body. + +The JSON object has the following fields: + +| Field | Value | Description | +|----------------|--------|-------------| +| overlay.active | Array | Array of Peer Objects, where each member is a peer that is connected to this server. | + +Each member of the `active` array is a Peer Object with the following fields: + +| Field | Value | Description | +|-------------|--------|-------------| +| ip | String (IPv4 Address) | The IP address of this connected peer. | +| port | String (Number) | The port number on the peer server that serves RTXP. Typically 51235. | +| public\_key | String (Base-64 Encoded) | The public key of the ECDSA key pair used by this peer to sign RTXP messages. (This is the same data as the `pubkey_node` reported in the peer server's [`server_info` command](#server-info).) | +| type | String | The value `in` or `out`, indicating whether the TCP connection to the peer is incoming or outgoing. | +| uptime | Number | The number of seconds the server has been has been connected to this peer. | +| version | String | The `rippled` version number the peer reports to be using. | + +#### Example #### + +Request: + + + +*HTTP* + +``` +GET https://s1.ripple.com:51235/crawl +``` + +*cURL* + +``` +curl -k https://s1.ripple.com:51235/crawl +``` + + + +Response: + +```json +200 OK +{ + "overlay": { + "active": [{ + "ip": "208.43.252.243", + "port": "51235", + "public_key": "A2GayQNaj7qbqLFiCFW2UXtAnEPghP/KWVqix2gUa6dM", + "type": "out", + "uptime": 107926, + "version": "rippled-0.31.0-rc1" + }, { + "ip": "184.172.237.226", + "port": "51235", + "public_key": "Asv/wKq/dqMWbP2M4eR+QvkuojYMLRXhKhIPnW40bsaF", + "type": "out", + "uptime": 247376, + "version": "rippled-0.31.0-rc1" + }, { + "ip": "54.186.73.52", + "port": "51235", + "public_key": "AjikFnq0P2XybCyREr2KPiqXqJteqwPwVRVbVK+93+3o", + "type": "out", + "uptime": 328776, + "version": "rippled-0.31.0-rc1" + }, { + "ip": "169.53.155.59", + "port": "51235", + "public_key": "AyIcVhAhOGnP0vtfCt+HKUrx9B2fDvP/4XUkOtVQ37g/", + "type": "out", + "uptime": 328776, + "version": "rippled-0.31.1" + }, { + "ip": "169.53.155.44", + "port": "51235", + "public_key": "AuVZszWXgMgM8YuTVhQsGE9OciEeBD8aMVe1mFid3n63", + "type": "out", + "uptime": 328776, + "version": "rippled-0.32.0-b12" + }, { + "ip": "184.173.45.39", + "port": "51235", + "public_key": "Ao2GbGbp2QYQ2B4S9ckCtON7CsZdXqdK5Yon4x7qmWFm", + "type": "out", + "uptime": 63336, + "version": "rippled-0.31.0-rc1" + }, { + "ip": "169.53.155.34", + "port": "51235", + "public_key": "A3inNJsIQzO7z7SS7uB9DyvN0wsiS9it/RGY/kNx6KEG", + "type": "out", + "uptime": 328776, + "version": "rippled-0.31.0-rc1" + }, { + "ip": "169.53.155.45", + "port": "51235", + "public_key": "AglUUjwXTC2kUlK41WjDs2eAVN0SnlMpzYA9lEgB0UGP", + "type": "out", + "uptime": 65443, + "version": "rippled-0.31.0-rc1" + }, { + "ip": "99.110.49.91", + "port": "51301", + "public_key": "AuQDH0o+4fpl2n+pR5U0Y4FTj0oGr4iEKe0MObPcSYj9", + "type": "out", + "uptime": 328776, + "version": "rippled-0.32.0-b9" + }, { + "ip": "169.53.155.36", + "port": "51235", + "public_key": "AsR4xub7MLg2Zl5Fwd/n7dTz7mhbBoSyCc/v9bnubrVy", + "type": "out", + "uptime": 328776, + "version": "rippled-0.31.0-rc1" + }] + } +} +``` + +### Concealing Peer Information ### + +You can use the `[peer_private]` stanza of the `rippled` config file to request that peer servers do not report your IP address in the Peer Crawler response. You cannot force peers you do not control to follow this request, if they run custom software. However, you can use this to hide the IP addresses of `rippled` servers you control that _only_ connect to peers you control (using `[ips_fixed]` and a firewall). This can help to protect important [validating servers](tutorial-rippled-setup.html#types-of-rippled-servers). + +Example: + +``` +# Configuration on a private server that only connects through +# a second rippled server at IP address 10.1.10.55 +[ips_fixed] +10.1.10.55 + +[peer_private] +1 +``` + + [version 0.26.0]: https://wiki.ripple.com/Rippled-0.26.0 [version 0.26.4]: https://wiki.ripple.com/Rippled-0.26.4 diff --git a/reference-rippled.html b/reference-rippled.html index a3bcf8591a..05733cacc9 100644 --- a/reference-rippled.html +++ b/reference-rippled.html @@ -228,6 +228,10 @@The WebSocket and JSON-RPC APIs are still in development, and are subject to change. If you want to be notified of upcoming changes and future versions of rippled, subscribe to the Ripple Server mailing list:
https://groups.google.com/forum/#!forum/ripple-server
Before you can run any commands against a rippled server, you must know which server you are connecting to. Most servers are configured not to accept requests directly from the outside network.
Before you can run any commands against a rippled server, you must know which server you are connecting to. Most servers are configured not to accept API requests directly from the outside network.
Alternatively, you can run your own local copy of rippled. This is required if you want to access any of the Admin Commands. In this case, you should use whatever IP and port you configured the server to bind. (For example, 127.0.0.1:54321) Additionally, in order to access admin functionality, you must connect from a port/IP address marked as admin in the config file.
The example config file listens for connections on the local loopback network (127.0.0.1), with JSON-RPC (HTTP) on port 5005 and WebSocket (WS) on port 6006, and treats all connected clients as admin.
Servers in the Ripple Consensus Ledger communicate to each other using the Ripple peer protocol, also known as RTXP. Peer servers connect via HTTPS and then upgrade to RTXP. (For more information, see the Overlay Network article in the rippled repository.)
In order to participate in the Ripple Consensus Ledger, rippled servers connects to arbitrary peers using the peer protocol. (All such peers are treated as untrusted.)
Ideally, the server should be able to send and receive connections on the peer port. You should forward the port used for the peer protocol through your firewall to the rippled server. The default rippled configuration file listens for incoming peer protocol connections on port 51235 on all network interfaces. You can change the port used by editing the appropriate stanza in your rippled.cfg file.
Example:
+[port_peer]
+port = 51235
+ip = 0.0.0.0
+protocol = peer
+The Peer Crawler reports information about other servers a rippled server is connected to as peers. The peers command in the WebSocket and JSON-RPC APIs also returns a similar, more comprehensive set of information, but requires admin access to the server. The Peer Crawler response is available to other servers on a non-privileged basis through the Peer Protocol (RTXP) port.
To request the Peer Crawler information, make the following HTTP request:
+rippled server, by hostname or IP address)rippled server uses the Peer Protocol, typically 51235)/crawlrippled servers use a self-signed certificate to respond to the request. By default, most tools (including web browsers) flag or block such responses for being untrusted. You must ignore the certificate checking (for example, if using cURL, add the --insecure flag) to display a response from those servers.The response has the status code 200 OK and a JSON object in the message body.
+The JSON object has the following fields:
+| Field | +Value | +Description | +
|---|---|---|
| overlay.active | +Array | +Array of Peer Objects, where each member is a peer that is connected to this server. | +
Each member of the active array is a Peer Object with the following fields:
| Field | +Value | +Description | +
|---|---|---|
| ip | +String (IPv4 Address) | +The IP address of this connected peer. | +
| port | +String (Number) | +The port number on the peer server that serves RTXP. Typically 51235. | +
| public_key | +String (Base-64 Encoded) | +The public key of the ECDSA key pair used by this peer to sign RTXP messages. (This is the same data as the pubkey_node reported in the peer server's server_info command.) |
+
| type | +String | +The value in or out, indicating whether the TCP connection to the peer is incoming or outgoing. |
+
| uptime | +Number | +The number of seconds the server has been has been connected to this peer. | +
| version | +String | +The rippled version number the peer reports to be using. |
+
Request:
+GET https://s1.ripple.com:51235/crawl
+curl -k https://s1.ripple.com:51235/crawl
+Response:
+200 OK
+{
+ "overlay": {
+ "active": [{
+ "ip": "208.43.252.243",
+ "port": "51235",
+ "public_key": "A2GayQNaj7qbqLFiCFW2UXtAnEPghP/KWVqix2gUa6dM",
+ "type": "out",
+ "uptime": 107926,
+ "version": "rippled-0.31.0-rc1"
+ }, {
+ "ip": "184.172.237.226",
+ "port": "51235",
+ "public_key": "Asv/wKq/dqMWbP2M4eR+QvkuojYMLRXhKhIPnW40bsaF",
+ "type": "out",
+ "uptime": 247376,
+ "version": "rippled-0.31.0-rc1"
+ }, {
+ "ip": "54.186.73.52",
+ "port": "51235",
+ "public_key": "AjikFnq0P2XybCyREr2KPiqXqJteqwPwVRVbVK+93+3o",
+ "type": "out",
+ "uptime": 328776,
+ "version": "rippled-0.31.0-rc1"
+ }, {
+ "ip": "169.53.155.59",
+ "port": "51235",
+ "public_key": "AyIcVhAhOGnP0vtfCt+HKUrx9B2fDvP/4XUkOtVQ37g/",
+ "type": "out",
+ "uptime": 328776,
+ "version": "rippled-0.31.1"
+ }, {
+ "ip": "169.53.155.44",
+ "port": "51235",
+ "public_key": "AuVZszWXgMgM8YuTVhQsGE9OciEeBD8aMVe1mFid3n63",
+ "type": "out",
+ "uptime": 328776,
+ "version": "rippled-0.32.0-b12"
+ }, {
+ "ip": "184.173.45.39",
+ "port": "51235",
+ "public_key": "Ao2GbGbp2QYQ2B4S9ckCtON7CsZdXqdK5Yon4x7qmWFm",
+ "type": "out",
+ "uptime": 63336,
+ "version": "rippled-0.31.0-rc1"
+ }, {
+ "ip": "169.53.155.34",
+ "port": "51235",
+ "public_key": "A3inNJsIQzO7z7SS7uB9DyvN0wsiS9it/RGY/kNx6KEG",
+ "type": "out",
+ "uptime": 328776,
+ "version": "rippled-0.31.0-rc1"
+ }, {
+ "ip": "169.53.155.45",
+ "port": "51235",
+ "public_key": "AglUUjwXTC2kUlK41WjDs2eAVN0SnlMpzYA9lEgB0UGP",
+ "type": "out",
+ "uptime": 65443,
+ "version": "rippled-0.31.0-rc1"
+ }, {
+ "ip": "99.110.49.91",
+ "port": "51301",
+ "public_key": "AuQDH0o+4fpl2n+pR5U0Y4FTj0oGr4iEKe0MObPcSYj9",
+ "type": "out",
+ "uptime": 328776,
+ "version": "rippled-0.32.0-b9"
+ }, {
+ "ip": "169.53.155.36",
+ "port": "51235",
+ "public_key": "AsR4xub7MLg2Zl5Fwd/n7dTz7mhbBoSyCc/v9bnubrVy",
+ "type": "out",
+ "uptime": 328776,
+ "version": "rippled-0.31.0-rc1"
+ }]
+ }
+}
+You can use the [peer_private] stanza of the rippled config file to request that peer servers do not report your IP address in the Peer Crawler response. You cannot force peers you do not control to follow this request, if they run custom software. However, you can use this to hide the IP addresses of rippled servers you control that only connect to peers you control (using [ips_fixed] and a firewall). This can help to protect important validating servers.
Example:
+# Configuration on a private server that only connects through
+# a second rippled server at IP address 10.1.10.55
+[ips_fixed]
+10.1.10.55
+
+[peer_private]
+1
+