How it works

From Ripple Wiki
Jump to: navigation, search

Technical Overview

This is a technical overview of the Ripple payment system.

Distributed Database

At its heart, Ripple is a distributed database. One of Ripple's goals is to provide distributed database services that other applications can build on top of. The first such application is the Ripple payment system.

The Ledger

The collection of information that comprises the state of the database is called the Ledger. Every few seconds a new version of the ledger computed. A ledger that is known to be accurate is considered validated.

Each version of the ledger has a hash which identifies it and contains the hash of the previous ledger. The implication is that once the hash of the current ledger is validated, all prior ledgers in the chain are also validated.

Ledger syncing

The ledger is a combination Radix tree and Merkle tree. This combination allows Ripple to quickly determine the differences between a local ledger and a remote ledger. Using this difference information ledgers can be quickly updated by only requesting the changes from other servers.

Merkle trees allow anyone to cryptographically verify entries in the ledger without having the whole ledger.

Ripple also uses a skip list to quickly verify that a past ledger was in fact a parent of the current ledger.


Changes to the database are controlled by accounts. Each account uses a public-private key pair to identify itself, and to cryptographically authorize changes to both its account, and information in the database controlled by its account.

Additionally, accounts can authorize the creation of other accounts. When the genesis ledger was created it contained a single account. All other accounts are derived from this first account.


Ripple has its own currency called XRP, aka ripples. 100 billion XRP were created when the genesis ledger was created and no more will ever be created. The scarcity of XRP is used to protect the Ripple network from abuse.

Each account has a balance of XRP. Accounts can spend XRP to authorize transactions and to reserve entries in the ledger. XRP spent on transaction fees are destroyed. Reserving entries in the ledger merely sequesters the XRP until the entries are released.

Unique Node List

Upon every ledger update, participating nodes cryptographically sign and distribute a declaration of their opinion of which ledger is correct.

Anyone can determine if a ledger is valid by collecting these declarations. When they have collected enough declarations from nodes on their own Unique Node List (UNL), they consider the ledger validated.

The UNL is created by choosing nodes which are unlikely to collude and that are unique in that they are not run by the same group or individual.


The method nodes use to determine the next valid ledger is called consensus. Every node participating in the consensus process replicates the ledger.

The contents of a ledger, plus the transaction set to be applied to the ledger, are all that is necessary to deterministically derive the next ledger. This principle is used to decide what information is kept in the ledger. To facilitate processing, ledger bloat is discouraged through the use of reserves.

Ledger cycle

Determining consensus requires a series of steps lasting 2-20 seconds called a ledger cycle.

The length of the ledger cycle is determined dynamically. Nodes automatically adjust the timing of the network to balance:

  1. The speed of a small network which excludes more nodes
  2. The security of a large network which includes more nodes


Processing nodes are constrained by the availability of resources like network speed, memory resources, disk speed, and computational resources. Based on the resources required and the resources available, nodes may participate at various levels in the consensus process.

If a node finds it cannot keep up, it will raise the fees it charges locally. Rather than allowing the network to shrink to a few super nodes, the network will raise fees globally. This puts transactions fees in line with the actual cost of processing transactions.

Protocol upgrades

The protocol can be upgraded by deploying the capability for a new feature or revised protocol. Validating nodes desiring to upgrade the protocol can broadcast their desire to upgrade. Every so often, a pseudo-transaction to upgrade can be submitted to the network. Validators vote to accept the transaction based upon if they want the feature and a super-majority of validators on their UNL want the feature. If the validators allow the transaction into the network, then the network upgrades.


Changes to the database are made through cryptographically signed messages from account holders. Transactions are first constructed and then submitted to the network. After transaction processing, meta data is associated with the transaction which itemizes the resulting changes to the ledger.

Transaction fees

Each node may require whatever fee it likes to accept and forward a transaction. If a node is heavily loaded, it is unlikely to accept or forward transactions below its minimum fee. However, if a transaction makes it into the ledger it must be processed regardless of the fee paid.

For operations that may do an varying amounts of work, the fee must be declared in the transaction to deterministically allocate the amount of processing.

To prevent abuse, any transaction that is distributed across the network must claim a fee regardless of whether or not it achieves the originator's desired effect.

If the network is under significant load from an attack, the network will rapidly increase transaction fees. This should rapidly bankrupt an attacker. Those with urgent transactions need only outspend the attacker for the urgent transaction. In contrast, the attacker must maintain a high fee for all their transaction. Non-urgent transactions can be delayed till the attack is over.

Transaction processing scalability

Transactions processing is highly scalable. The bulk of the work for transaction processing is cryptographic verification of signatures. This can be done in parallel.

Today, commodity hardware can cheaply hold vast amounts of memory and easily hold the entire ledger. The application of transactions to the ledger is done sequentially and lock free. This allows for efficient application of many transactions to ledger.


Payments are made by creating transactions authorizing the transfer of balances from one account to another.

Each payment can specify a source and destination tag. These tags facilitate identifying the purpose of payments and allow a single address to be utilized by multiple users. Additionally, these tags enable the return of payments.

Payment system

A first application for Ripple is that of being a federated payment system. To facilitate this, Ripple has built in support for fiat currencies and a distributed currency exchange.

Fiat currencies

Ripple allows accounts to maintain balances and trust limits in various currencies with other accounts. Balances can be changed to track real world transactions. A path of trust between accounts can allow payments between parties with no direct balance arrangement.

Distributed currency exchange

Ripple contains a distributed exchange that allows anyone to post offers to convert currencies. These offers are taken when a counter offer the same or better is made.

Cross currency payments

Ripple provides cross currency payments by finding a payment path through trust paths, the distributed exchange, and XRP payments.


Ripple nodes talk to each other using their own private peer protocol. Additionally, Ripple servers provide service so clients can utilize the network without tracking or participating in the ledger process.

Peer communications

The peers communicate to each other with packet create via Google's protocol buffers.

A custom serialization format is used to encode transactions and ledger entries.


The network must distribute validations from validators to interested parties. To prevent useless validations from spamming the network, peers subscribe to validation networks. A validation network is a sub-network of peers which delivers validations from a particular peer. Validation networks are not currently implemented.



For communications with clients and back end applications data is presented in a simple JSON format.


The RPC API provides a simple way for programs to communicate with a server, make queries on the ledger, and submit transactions. Trust clients may even provide a call back URL to subscribe to events.

Websocket API

For more interactive applications, a websocket API is provided which support the same methods as the RPC API.

Communications security

Abusive communications are punished by requiring a proof of work.


Ripple use the same kind of encryption as ECDSA to provide: signing, verification, encryption, and decryption.

Future features

This is the start of a detailed description of how Ripple works. We have additional descriptions of ripple: less detail or fundamental level!