Network Structure

Network Structure Work Page

The Ripple network consists of user agents, or nodes, connected pairwise by abstract mutual-credit accounts which allow searching for paths in the network, and sending and tracking of obligations between the two parties through the passing of messages. Payers must also be able to establish messaging connections to the recipients of their payments.

In reality, messaging connections must be established between node host machines, which may each host multiple nodes, and those connections must be used to transfer messages between nodes. The nature of the host-level connections and how messages are passed depends on the particular message transport system being used.

Binding to a Transport Layer

A Ripple transport layer binding must specify the following:

  • how hosts open and close connections to each other
  • how the connection is secured
  • how nodes are identified (preferably user@host email-style identifiers)
  • how connected hosts address host-level messages to each other, and how nodes on those hosts address node-level messages to each other
  • how Ripple messaging semantics are implemented (see Messaging Semantics below).

Messaging Semantics

A message transport layer must distinguish between three message types: message, reply, and error. Each Ripple message has a unique ID within the host-level connection, and must be immediately responded to by either a reply or an error with the same ID upon receipt. This serves to establish that the message was received and was either understood (reply), or deemed somehow malformed or otherwise inappropriate as detailed by an error code and message (error). The ID may consist of one or more fields.

Replies and errors may carry any data that a regular message may carry. In addition, error messages must carry an error code.

In general, nodes need not wait for the reply or error to send another message.

Message Syntax

Ripple messages carried within the transport layer are JSON format. For example:

  "account-request": {
    "request_id": 16504,
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "nodes": [
        "node_id": "",
        "limit": 500

The indentation and line breaks are for readability in this document only. The actual messages themselves do not have significant whitespace other than described in the JSON specification.

Network Structure Work Page