Signing Cross-network Payments


Our goal on the gatewayd team at Ripple Labs its to enable payments between any two financial networks through the Ripple exchange and payment infrastructure. From the perspective the end user or developer payments will move seamlessly from one account on one network, such as a bank account in…

Signing Cross-network Payments

Our goal on the gatewayd team at Ripple Labs its to enable payments between any two financial networks through the Ripple exchange and payment infrastructure. From the perspective the end user or developer payments will move seamlessly from one account on one network, such as a bank account in South America, to an account on another disparate network, such as bank account in New Zealand. Behind the scenes the payment is made from the bank in South America to a Ripple gateway, which transfers the funds across the ripple network to another Ripple gateway, which ultimately transfers the funds to the destination bank account.

With so many parties at play in cross-network payments we run the risk of part of the system breaking down and our payment not completing. As a result we must obtain cryptographically-signed agreements from both (or all) gateways that they will complete the desired payment before initiating the first funds transfer. We have developed a protocol for making such payments that we have named the Gateway Services Protocol. The protocol allows developers to ask gateways for quotes of payments through their gateway, and allows developers to obtain signed agreements from the gateways that a specific payment will be made upon receipt of a primary payment.

The digital signatures involved in such a cryptographic payment scheme must be able to be verified publicly by any auditing party, but must also be un-forgeable by anyone except the actual gateway operator, therefore an asymmetric key algorithm must be used. At Ripple Labs we have chosen to use signed JSON Web Tokens, a nascent industry standard, to communicate agreement between gateways on cross-network payments. Our signatures will use the RS512 algorithm, using RSA and 2048-bit keys to generate the signature.

Gateways agreeing to perform a secondary payment upon receipt of a corresponding primary payment will sign a standard JSON object that represents all the agreed-upon payments, with the hash of said signature being used as the invoice id for given payments. Ultimately an application developer will be able to obtain a signed agreement from a gateway to make a payment, and use the signature hash as input to a transaction they sign, therefore both agreeing to the transaction. Mutual agreement to payment terms finally constitutes a legally-binding agreement between the several parties.

Gatewayd Update

In accordance with the plan I set out to heighten transparency and confidence in the gatewayd ripple gateway software system, we built today a continuous integration gatewayd server that automatically processes payments of digital currency into and out of ripple.

The biggest win for transparency was by far the use of Loggly, the powerful logging service for software event logs. A few weeks ago we implemented in gatewayd the winston logging module for node.js, opening up gatewayd to a plethora of logging service options with a simple configuration change.

Quickly the whole integration engineering team was added to the loggly account as users, and with four lines of code thanks to the node.js winston-loggly module the logs from seven gateway processes were piped to indexed and searchable dashboards.

Watching together the logs stream on a television screen, we were able to pinpoint application errors in real time, and to spot confusing discrepancies in log naming. With our incredible new tooling we implemented several patches and design improvements to great impact.

Questions about Gatewayd from a Documentation Engineer

Q: What does gatewayd, technically speaking, do and not do? What’s not within the scope of the project? Obviously, it’s not rippled and it’s not a mobile app for managing customer money, but beyond that I’m a bit fuzzy. I think I heard there’s a skeleton web interface for handling customers?

A: At its core gatewayd is designed to simplify and automate interaction with the ripple network, specifically sending payments to other ripple addresses, and handling notification of the receipt of payments from other ripple address to the gateway’s ripple address. In order to maintain an audit-able record of ripple payments sent to and from the gateway’s ripple address, a relational database is included as part of the gatewayd software.

From the perspective of a gateway operator, interaction with gatewayd is achieved via its HTTP/JSON interface, allowing developers to create and monitor payments, and to query a record of transactions through their gateway.

Ripple Transactions

Two unix processes automate the sending and receiving of payments via ripple, by reading and writing to the ripple_transactions and ripple_addresses database tables, recording historical ripple transaction data for later use.

The process found in processes/outgoing.js periodically queries the ripple_transactions database table for records with the state column set to outgoing. When a ripple_transaction record in the outgoing state is found the unix process digitally signs and sends the payment to the ripple network for acceptance into the global ledger.

The process found in processes/incoming.js periodically queries the ripple network for new payments made to the gateway’s ripple address. When a new payment is discovered the process writes a record of the payment in the ripple_transactions database table and a record of the sender address in the ripple_addresses database table. In order to track its progress in processing incoming payments, the process saves and loads the hash of the last payment it has processed.

By using the database as a queue in this way gatewayd is able to process outgoing and incoming payments on ripple in an asynchronous fashion. If the gatewayd server loses connection with the ripple network, or if the server machine is restarted, or if the two unix processes simply crash, payment processing can still be resumed later when the processes are back online and proceed smoothly where it left off.

External Transactions

A gateway’s role in ripple is to accept possession of assets and issue corresponding ripple IOU currency to the depositor. Gatewayd includes a relational database, and in order to maintain a complete account of transactions in and out of the gateway, grants the ability to record transactions and accounts that occur externally to the ripple network. For instance a gateway often receives inter-bank payments from another bank account, and needs to make a record of inter-bank transaction in their database.

Two unix processes automate the handling of transactions of value received via networks external to ripple, by reading and writing to the external_transactions and external_accounts database tables, recording historical external transaction data for later use.

The process found in processes/deposits reads the external transactions table for any transaction of type deposit with a state of queued, and then applies some business logic to that external transaction record to ultimately submit some ripple transaction. The business logic in the file located at processes/deposits is designed to be modified to suit your custom business needs. By default the deposits process queries the database for the destination ripple address associated with the queued external transaction by way of a users table that joins them, however such behavior is often modified per business rules.

The process found in processes/withdrawals reads the ripple transactions table for any transaction in the state of incoming, and then applies some business logic to that ripple transaction record to ultimately record some pending external transaction to an account in some network external to ripple. The business logic in the file located at processes/withdrawals is designed to be modified to suit your custom business needs. By default the withdrawals process queries the database for an external account associated with the incoming queued ripple transaction by way of its destination tag, however such behavior is often modified per business rules.

By using the database as a queue in this way gatewayd is able to asynchronously handle incoming deposits of value receive from networks and accounts external to Ripple. The HTTP / JSON API interface is used to record such transactions, and can be used to asynchronously process pending withdrawal transactions.

Q: Is there a difference between “Ripple Gateway Framework” and “gatewayd”? Which term do we prefer to use most often?

A: Gatewayd is the official name of the software, which provides a framework for building an automated gateway on ripple. What makes Gatewayd a framework is that pieces of it are meant to be customized depending on your unique banking and payments systems integration effort.

Q: The setup process includes setting up hot and cold wallets. Can you explain a bit about the best practices in this regard and how the software ties into it? Especially in the case of a gateway, where I expect main transactions to be mostly in IOUs, I don’t really see what risks the hot wallet is mitigating.

If you are issuing IOUs on Ripple your IOUs become real liabilities that must be covered, and thus you want to prevent at all costs having the account that issues your currency be compromised. The most basic and widely-used strategy for preventing your issuing ripple account from being compromised is to keep that ripple account secret off of any servers that could be hacked or compromised. However at the same time an automated ripple gateway needs to be able to sign and send payments automatically to its users, presenting a dilemma since the secret key used for signing must also be stored offline, away from the server. Thus the “hot wallet” comes into play, enabling the issuing ripple account, now known as the “cold wallet” to be kept offline, while still sending automated payments. The hot wallet secret is stored on the server, and a limited amount of currency is issued into the hot wallet from the cold wallet manually by the gateway operator. If the server is then compromised, the balance of the hot wallet can be stolen, but the attacker will not have access to the gateway’s issuing account, thus greatly limiting liability. Remember a gateway establishes lines of trust from its users to its ripple account, and if the account “cold wallet” is compromised the attacker can issue unlimited fraudulent funds from the gateway’s account without recourse.

Q: Are incoming payments to the gateway always linked to withdrawals? What other cases could there be? For users, is just sending any payment to the gateway sufficient to qualify for a withdrawal?

A: No incoming payments are not always linked to withdrawals of asserts. For instance an incoming payment could be intended for making a payment for a e-commerce shopping cart. In gatewayd the default policy to be applied to in incoming transaction is to treat it is a “withdrawal”, but this policy is designed to be customized or overridden with custom business logic.

Q What are hosted wallets? Do they exist in the Ripple ledger / in rippled’s database whatsoever?

A A ripple address can be divided into “hosted” wallets by taking a single ripple address and appending a new “destination tag” for each user to construct a “hosted” address. In the ledger only the base ripple address is part of an account entry, so a hosted wallet with five thousand destination tags would still have only a single ledger entry for the base ripple address. A hosted wallet service theoretically accepts payments to such an address / destination tag pair, to which the service provider controls the private key. They would then display the balance of payments they received on behalf of the user, but the service provider would have control of the funds and be able to send them.

Anonymous: Hi Steven. In a video you introduce your gateway for exchanging StroopWafels. I understand the gatewayd with its REST interface is open source. Would you be willing to share your StroopWafel / UI source code as a starting point to save some time in figuring out how to setup a gateway website?

The webapp for is available on NPM as a node module name “ripple-gateway-webapp-example”, and also on my person github

Rippled Install Script

The following is a complete script compiled from the Ripple Wiki that will install rippled, the free crypto-currency payment platform.

## Ubuntu 14.04 on AWS

sudo apt-get update
sudo -y apt-get upgrade

## Git
sudo apt-get -y install git

## Scons
sudo apt-get -y install scons

## Ctags
sudo apt-get -y install ctags

## Pkg-config
sudo apt-get -y install pkg-config

## Protobuf
sudo apt-get -y install protobuf-compiler libprotobuf-dev

## SSL
sudo apt-get -y install libssl-dev

## Boost
sudo apt-get install -y python-software-properties
sudo add-apt-repository -y ppa:boost-latest/ppa
sudo apt-get -y update
sudo apt-get install -y libboost1.55-all-dev

## Rippled
git clone
cd rippled/
git checkout master

Anonymous: Hi Steven, I just saw your analysis on Schiff vs Molyneaux. Thought you might be interested in ripple singapore? please feel free to reply - james.

Yes I am very interested in Ripple Singapore. In fact I already own 0.0012 ounces of gold at the Ripple Singapore gateway. Do you own their IOUs? Want to trade gold for silver or platinum?

Smart Contracts and Central Banking

I want to write a contract that enables me to the be Head of the Banco Nacional de Argentina, the Argentine Central Bank.

The central bank will accept trust in the argentine peso, currency code ARS, from any individual on the network, and it will issue i% new currency every week. the contract specifies to disburse the new funds evenly among all the users who trust the central bank, up to the amount that each individual user trusts.

The second stipulation of the system is that the creator of the contract becomes the central banker and is able to arbitrarily adjust i, the rate of inflation, to any weekly compounded rate above 0.

A command to change i would be represented by an entry in the distributed ledger, which the contract would read every time it runs to determine how much new currency to issue. I imagine an elegant solution would be for the creator of the central bank, the central banker, to have a special rule for trust lines from him to the central bank. For the central banker the amount of the trust line for ARS to the bank would determine the rate of inflation i for the next currency payout cycle.

The central bank distributed contract system is designed to work with Ripple as the provider of trust, the distributed ledger, network consensus and currency exchange. To establish trust for pesos to the Banco sign and submit a Trust transaction to the Riple ledger, specifiying the central bank’s Ripple account address as the issuer of ARS.

Currently in progress is an implementation of contracts in Ripple that allow turing-complete programs to be executed in a sandboxed environment using Google’s Native Client, or NaCl. From the NaCl sandbox your code has access to a limited API to the Ripple network ledger, namely querying and submitting transactions.

To use the central bank program outside of the Ripple network contracts system create a software application with your preferred technology stack and integrate with Ripple using Websockets, HTTP, or one of several Ripple client language libraries. Such a program may even be possible using the native Bitcoin scripting language, or built into the Bitcoin blockchain with Ethereum.

Once the Argentine Central Bank is running it would be awesome to simulate all of the major world money producers and affect an “international” virtualized exchange on Ripple.

Anonymous: I want to know if you could touch on how to make a Quora or Reddit type of feature app using rails 4?Enabling voting on user submitted post,content is becoming a popular feature in most apps but there is not a lot of training material out there showing exactly how to implement,configure voting on post or user submitted links and which gems would be best for the job. I was wondering since you where good at explain these untouched topics, if you could make a video showing exactly how to do this?

Hello, thanks for the question. I have an idea how a simple voting system might work, and it uses the Active Record gem, one of the most powerful sequel database tools out there. It looks like you goal is for users to be able to vote on any type of content on your site, so since we don’t know all the types of content that will one day receive votes I would create a polymophic database table that enables tracking of votes for any other type of object. Polymorphic means that a given record can be associated with many different types of database records. Here are some example Active Record classes that enable polymorphism. After I will explain what they do behind the scenes:

    class Vote < ActiveRecord::Base

      belongs_to :votable, polymorphic: true


    class Post < ActiveRecord::Base

      has_many :votes, as: :votable


    class UserLink < ActiveRecord::Base

      has_many :votes, as: :votable


The polymorphic setting will create two database columns in your Vote table, one called votable_type and one called votable_id. Now every time you want to add a vote for a particular UserLink you create create a new Vote record, setting the votable_id as and votable_type as ‘user_links’.

    user_link = UserLink.find(1212)

    vote = user_link.votes.create

    puts [vote.votable_type, vote.votable_id]

    => [‘user_links’, 1212]

    post = Post.find(999)

    vote = post.votes.create

    puts [vote.votable_type, vote.votable_id]

    => [‘posts’, 999]

Ryan Bates has done two Railscasts on polymorphism and there is a good explanation in the rails guides.

I hope this helps!

Anonymous: Hey Steven I loved your video on YouTube about playing around and working with bootstrap templates "Refactor HTML Site Template to Ruby on Rails 1 of 3" are you going to release part 2 and 3 and make more videos on this topic? me an many beginning developers would find it amazing if you did!...learned so much from it can't wait until others are released!

Hello I did recently release part two of refactoring rails to my YouTube channel.

Watch the video here

Expect part three within a few weeks. Thanks for watching and all the great feedback!