Ripple Protocol Requirements

Introduction

Ripple is a currency and payment system within a decentralized peer-to-peer trust network. A trust relationship or connection in Ripple is an agreement to accept IOUs up to a certain limit from another party.

Ripple keeps track of the IOU balances between trusted parties and uses these private credit arrangements to enable payments between untrusted strangers without the recipient having to rely on the payer's or any other untrusted party's creditworthiness. It does this by finding a chain of intermediary nodes connecting the payer to the recipient, and propagating IOUs along that chain. Once a payment is completed, the payer actually owes the first link in the chain, and the recipient is owed by the last link.

This document lays out the requirements for a system of communication between Ripple nodes.

1. Nodes

1.1. Nodes are software agents for parties participating in Ripple. Nodes may act automatically on behalf of their owners.

1.2. Nodes exist on internet-connected servers.

1.3. A node must have an address where other nodes can send communications (or at least discover how to send communications).

1.4. Nodes must be active (on) at all times, barring external circumstances.

1.5. Ripple nodes must be able to immediately acknowledge and, where possible, act upon communications from other nodes.

1.6. Nodes must be capable of performing all Ripple functions with any node on the same server or a different server.

1.7. The owner of a node may be a person or a group of people.

1.8. There must be a way for a node to prove the identity of its owner.

1.9. A node must be able to authenticate and encrypt its communications to other nodes.

1.10. A node must be able to move to a different server.

2. Accounts

2.1. An account is a trust connection between two nodes formed when one or both nodes agree to accept IOUs from the other. This is also called a mutual credit account.

Account Creation

2.2. Account creation begins by one node offering credit to another node, meaning that the offering node indicates that it will accept IOUs from the other node, measured in certain value units, and possibly only up to a certain limit.

2.3. A node can accept or reject an offer of credit.

2.4. If a node accepts an offer of credit, it may indicate that it will also accept IOUs from the offering node, measured in the same value units, and possibly only up to a certain limit.

Account Usage & Maintenance

2.5. Both partners to an account may unilaterally limit the amount of IOUs they issue to the other partner. This limit must be communicated to the other partner.

2.6. Once an offer of credit is accepted, partners may pass IOUs to each other in accordance with the IOU acceptance and issuance limits of each partner node.

2.7. The IOU balance of an account is specified either by zero at both nodes, or by a positive number at one node, and an equal negative number at the other.

2.8. Either node may change the amount of IOUs it will accept or the amount of IOUs it will issue on an account at any time by informing its partner node. If the current balance of the account is outside the new limits, it remains the same, but its value cannot move any further from the new limits.

2.9. In case of disagreement between two account-partner nodes on IOU acceptance or issuance limits, each node's version of its own limits is authoritative.

2.10. In case of disagreement over the balance of an account, the account will continue to function, keeping both versions of the balance within the authoritative limits of the account.

Conversion to Other Units

2.11. One account partner node may propose to the other to permanently convert all outstanding account IOUs and limits to different value units at a certain exchange rate. A node receiving such a proposal may accept or decline.

2.12. One account partner node may propose to the other to allow temporary conversions, for the purposes of single transactions, of account IOUs and limits to different value units, either at a fixed exchange rate, or at a floating exchange rate whose value at any given time can be found by asking a certain authority specified in the proposal. The other node may accept or decline.

2.13. One account partner may propose to allow temporary conversions, for the purposes of single transactions, of account IOUs and limits to any of a whole set of different value units, at rates given at any time by a certain authority specified in the proposal. The other node may accept or decline.

2.14. In case any conversion authorities for an account provide overlapping exchange rate information that might be contradictory, each conversion authority must be assigned a priority when it is proposed.

2.15. Either partner may propose to change a standing conversion authority's priority assignment. The other node may accept or decline.

Account Termination

2.16. Either node may terminate the account at any time by informing the other node. (Note that while it seems like extremely bad form for one party to unilaterally terminate an account on which they are owing, Ripple does not try to encourage good behaviour by prohibiting bad behaviour. Ripple implementations may prohibit their users from behaving badly, but must technically accept this behaviour from owners of nodes on other servers.)

3. Payments

3.1. The payment process can be initiated either by the payer node or by the recipient node holding an electronic token of value previously issued by the payer node.

3.2. The amount of IOUs to be received by the recipient node and the units in which those IOUs will be measured must be agreed upon by both payer and recipient. This amount may be specified as an exact value, a minimum, or a maximum to be received.

3.3. The amount of IOUs to be paid by the payer node and the units in which they will be measured is decided by the payer node. This amount may be specified as an exact value, a minimum, or a maximum.

3.4. If the amount to be received is specified as a minimum, the amount to be paid must not be specified as a minimum. If the amount to be received is specified as a maximum, the amount to be paid must not be specified as a maximum. (Generally, the amount to be received will be given exactly or as a minimum and the amount to be paid will be given exactly or as a maximum.)

3.5. Nodes must be permitted to choose from a wide variety of schemes for issuing electronic value-tokens.

3.6. The payment process must allow nodes and their owners to remain anonymous to parties with whom they do not share an account. This means that it should be extremely difficult to use the payment process to discover the address or the mutual credit connections of a node with whom one does not share an account. If possible, it should also be difficult to discover connections between nodes with which one does share accounts.

Searching for Paths & Passing IOUs

3.7. Once the terms of the payment are agreed, the payer node or the recipient node, or both working in concert, search for a chain or chains of intermediary nodes connecting them through the network of mutual trust connections that allow the payer's IOUs to be converted into IOUs acceptable to the recipient.

3.8. The search method should be fast, accurate, simple, decentralized, low bandwidth, and scalable. See http://ripple.sourceforge.net/search.html.

3.9. A node may collect percentage and flat fees for acting as an intermediary, and convert units as it deems necessary at rates it determines, but the payer must be informed of the details during the search process. (Good manners dictate that if a node makes charging fees a matter of policy, account partners be notified.)

3.10. The payer node selects which of these paths to use for payment. If none are deemed suitable or if no paths are found, the payer node should be able to search for more paths, or cancel the payment altogether.

3.11. The payer node begins actual payment along a path by passing IOUs to the first intermediary node in that path, with which it shares an account. The first intermediary node then passes IOUs to the second via their shared mutual-credit account, and so on, until payment reaches the recipient. The amount of IOUs to be passed at each step is determined during the search process.

3.12. If payments along one path does not reach the recipient, they must be rolled back.

3.13. Payment along all the paths betweem payer and recipient together make up an atomic transaction and must all be rolled back if for some reason the payment can't be completed to the satisfaction of the payer.

3.14. Only the payer node must be able to issue commit or roll back directives.


Ryan Fugger, October 2004