Federation protocol

From Ripple Wiki
Jump to: navigation, search


Ripple's federation protocol makes sending money as easy as sending e-mail. Here is how it works:

Yesterday's e-mail

What makes computers powerful is software, but what makes software powerful is protocols. Protocols allow computers and the people who use them to communicate and collaborate in powerful ways.

For example, in the past there were disparate e-mail systems: Aol, Genie, and Compuserve. Users on these systems could only send e-mail to other users on the same system.

Federation 1.png

Federated e-mail

Then, SMTP (Simple Mail Transfer Protocol) came along and allowed these systems to federate into one large e-mail system. Federated e-mail soon became the standard.

Now users on each system could e-mail users on other systems by simply typing in the username of a foreign user followed by the foreign system’s domain. For example, someone on Compuserve could send e-mail to john@aol.com.

Federation 2.png

Today's payments

Banking today runs on a similar system to email in the 1980s. Moving money from one institution to another is expensive and slow because there are many systems involved.

Federation 3.png

Federated payments

Like SMTP, Ripple is a protocol that federates disparate systems on the Internet. Whereas SMTP federated e-mail systems, Ripple federates payment systems. Ripple is the new Internet protocol that allows payment systems to federate as easily as e-mail systems federate today.

In fact, with Ripple, a user at Wells Fargo could send a payment to a user at Facebook by addressing the payment to john@facebook.com. The Ripple protocol automatically performs currency conversion, provides a public ledger to verify and track payments, and provides security.

Internet e-mail has no single operator. Likewise, Ripple has no single operator. Each participant can run the software that implements the federation protocol. The software simply works with its peers to make the network function.

Federation 4.png


When a large payment system federates, the Ripple federation protocol allows millions of people to instantly become Ripple users without needing to get a Ripple wallet, or get XRP, or learn about trust lines.

The Protocol


Internet e-mail works by federating disparate e-mail systems into a single network. Each e-mail system has a domain name to identify itself, provides users a username to identify their mail, and federates over the Internet with other e-mail systems. The result is every user receives an e-mail address similar to user@mailsystem.com and mail can be seamlessly sent between users. The Ripple federation protocol does this for payment systems.

The federation protocol allows payment systems to federate in the Ripple network via the creation of gateways. Gateway users are provided a payment address similar to user@wallet.com which allows them to send and receive payments from any user on the Ripple network.

A payment system would choose to federate for any of the following reasons:

  1. To increase their value proposition to their users:
    • Users can send and receive instant, irreversible, cross currency payments to and from any other user reachable on the Ripple network.
  2. To increase their revenue:
    • The number of payments users send and receive should increase as they have a larger group of people to transact with.
  3. To retain users:
    • Users will have less incentive to move to another system that supports Ripple.
    • Users will be able to transact with a larger group.
  4. To have a competitive advantage over services that do not federate.

Sending payments

The payment system recognizes regular Ripple address and user@domain style address. For payments to these systems, the gateway allows the user to specify the destination currency.

Receiving payments

The payment system provides the user with user@domain style address and informs the user when payments arrive.


  1. The system provides each user with an 32 bit integer, or tag, to uniquely identify their account.
  2. The system provides each user with a user name to identify their account in conjunction with the system's domain name. For example, johndoe would be the user name and the full Ripple payment address would be johndoe@wallet.com.

Inbound payments

To accept inbound payments, the system provides an http service that converts between tags and user names. The system then accepts payments as normal.

Outbound payments

A sending federating system recognizes Ripple addresses in the raw style, like rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh, and e-mail style address, like johndoe@wallet.com.

When a user specifies a Ripple destination address, the send system then subscribes to rippled for the destination address. It then receives messages providing:

  • The status of the address (does it exist)
    • If the address does not exist, it can be created if the destination currency is XRP as per normal. See reserves.
  • The actual destination address, if an e-mail style address was provided.
  • The actual destination tag.
  • The list of currencies the destination system accepts.
  • Cost estimates for each source currency that the sending system supports.

The sending system:

  • Allows the user to choose from the list of destination currencies.
  • Provides the user with a maximum cost for the payment.

When the user confirms the payment, the sending system sends a normal Ripple Payment.


Users of the service API will need to make sure they are in fact communicating with the intended service and that their connections to the service provider are not hijacked or spoofed.

The primary security mechanism is SSL. All connections will use the HTTPS protocol and must verify the certificate against the intended host name. The certificate path must be valid and the root CA must be trusted.

Protection against corrupt CAs for ripple.txt.

Future feature: protection against corrupt CAs.

Only temporary protection against corrupt CAs is provided: 30 days. The rationale is that a site should be able re-establish control of their system or announce its compromise.

Because certificates change when they are renewed. They must be signed by the old certificate. The the hash of the new certificate can be signed by the old certificate can be placed in ripple.txt file.

Sites might collect request validators to verify their certificate as of a certain time. The site would then serve these verifications on demand. A checking site would use its UNL to determine if the validations are sufficient.


  1. Someone can assume that because a user has an address that person wants payment to that address.
    • People should be educated to ask the receiver in what form they will accept payment.
  2. E-mail system might not be set up for user to occupy same mailbox space that company uses for staff.
    • The system would need to figure out how they would initially resolve conflicts.
  3. For global Ripple names, we would likely map them to nickname@ripple.com
    • A federation API server would not be used to implemented this, instead the ledger would be consulted.


Service declaration

The gateway's ripple.txt indicates if and where the payment system makes the federation API is available:

Specifies the url where the federation API is provided.

Service request

A federation request parameters:

Always set to "federation".
Requests the tag for the destination user's account be returned.
The domain of payment system.

Example request:

GET /ripple_federation?type=federation&destination=johndoe&domain=wallet.com

Successful response JSON:

  "federation_json" : {
    "type" : "federation_record",           // All signed objects should have a type.
    "destination" : string,          // Required.
    "domain" : string,               // Required.

    "destination_address" : address, // Required. Destination Ripple address.
    "destination_tag" : string,      // Optional. Destination tag.
    "currencies" : [                        // Optional. Restrict to specific currencies.
          "currency" : currency,     // Can be XRP.
          "issuer" : issuer,         // Optional. (null is not valid)
    "expires" : date,                // Optional. (defaults to forever)
 "result" : "success"
The domain for the payment system as per ripple.txt. No leading "www.". Echoed from the request.
The UTF-8 string used to identify the recipient. Echoed from the request.
The account payment is to be sent to.
The 32 bit integer associated with the user. To be used when a payment is made.
If not provided, all payments are accepted. Specify "XRP" to enable XRP. To accept no payments and merely provide the historical mapping specify [].
When this entry is no longer valid. To allow compromised secrets to be replaced, expires should be set.

Error response JSON:

  "result" : "error",
  "error" : string,
  "error_message" : string,
  "request" : {
    request keys and values

Error messages:

The supplied user was not found.
Look up by tag is not supported.
The supplied domain is not served here.
Missing or conflicting parameters.
Service is temporarily unavailable.

Result verification

  1. From the signer obtain the associated Domain from the account's account_root entry.
  2. Securely obtain the ripple.txt from the specified Domain.
  3. Verify the signer and any specified issuer [address]es are listed in the rippled.txt.
  4. Verify the public key is associated with the signer in the last verified ledger.
  5. Verify the federation_json is signed by the supplied public key and signature.

Sample Implementations

Implementation notes

The responses are designed to be cachable. Sites may pre-generate the blob on a system disconnected from the webserver. This way, a short compromise of the server would result only in a temporary denial of service. Payment's could not be redirected.