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!

Bevo Bucks on the Ripple Network

Bevo Bucks on the Ripple Network
My university in Austin used to have its own private money that it would issue and that businesses around town and on campus would accept in place of Federal Reserve notes. The digital currency was tied to one’s university student ID, but merchants often had trouble processing the student cards and had to employ special, expensive and clunky machines to make the system work. The last I hear the Bevo Bucks payment system collapsed and was discontinued.
Though the experiment didn’t work out I think there is a great desire for institutions to be as to issue their own digital money for various reasons. The University of Texas next time could create its own currency on the ripple network, issuing currency units to its students. That way the students could hold the funds in theur ripple wallet. This arrangement would be advantageous to merchants because the new ripple Bevo Bucks would be sellable on the open market. It would be trivially easy for the university to maintain liquidity of its Bevo bucks by constantly maintaining bids on the ripple exchange system between Bevo Bucks and more liquid USD from Bitstamp or another popular issuer of dollars. In that scenario the merchants could choose to hold bevo bucks in their account, or turn them into dollars or any other currency in seconds using ripple.
I love to imagine and invent new ideas for money and uses for cryptographic payment systems like ripple. If you have any ideas please send them my way, and we can have a geeky discussion. Until next time I will be thinking about how to store concert tickets and other “non-monies” in your ripple wallet.

Inside the code of Ripple’s newest mobile payment app for iOS

The Ripple Labs team recently announced their first iphone app that runs on the ripple network, the revolutionary distributed payment system. I have been following the development of the app over the past few weeks and want to discuss the design of the app and how others can build similar ios apps using the same open source frameworks.

Before beginning check out the source code for the Ripple iOS app, which is freely available on github:

Inside the ripple network users communicate using real-time websocket connections to quickly propagate transactions through the network for confirmation. The official ripple reference client uses websocket communication to send and receive money in any currency in seconds. In this post I will explain how to make an iOS native client to the ripple network communicate securely with servers that validate transactions and broadcast messages to other interested clients.

The Javascript Ripple Library

The most fully developed client library for ripple is written in javascript and includes websockets for communication and powerful client-side cryptography using Stanford’s Javascript Crypto Library (SJCL). The ripple-lib javascript library can run in web browsers, on servers with node.js, and any javascript environment that impements a websockets interface.

To get started with ripple-lib.js include the library in your web browser or in node.js using npm install ripple-lib. Every client in ripple-lib must establish a connection to the network by connecting to a remote server running the ripple network daemon, rippled. Here is an example of establishing a connection to the ripple network.

var remote = ripple.Remote.from_config({
        "trusted" : true,
        "websocket_ip" : "",
        "websocket_port" : 443,
        "websocket_ssl" : true,
        "local_signing" : true

When creating a new ripple.Remote object we establish a persisent websocket connection to a public ripple server at using encrypted SSL (https). The option for local signing means our client is going to use its secret key and ripple’s elliptic curve digital signature algorithm to create transactions securely and locally without divulging its secret key to the server.

Once a connection to the network is established the ripple-lib can register listeners for transactions and events related to your account. It can build transactions, cryptographically sign them, and send balances to the remote server over websockets. Ripple-lib includes objects for Ripple Addresses, Amounts based in various currncies, Transactions, and more. Together these objects make up the ripple javascript api, and will be your primary means of access to the network. The following is an example usage of the JS api, building, signing, and submitting a transaction, and registering callbacks

Constructing a transaction:

function sendTransaction(data) {
  remote.set_secret(data.account, data.secret);

A ripple transaction generally requires a sender account, a recipient address, an amount, a currency to send from, and a currency to send to.

  var currency = data.to_currency.slice(0, 3).toUpperCase();
  var from_currency = data.from_currency.slice(0, 3).toUpperCase();
  var amount = ripple.Amount.from_human(""+data.amount+" "+currency);
  var recipient = data.recipient_address;

Use the remote to ensure the recipient is valid, then set them as the issuer of trust. To make a transaction happen a path must be discovered that connects the various buys and asks on the network ledgers between two currencies:

  paths = remote.request_ripple_path_find(data.account, data.recipient_address, amount);

Once you have found a path between the sending currency and the destination currency, construct a transactions with that path and submit it to the network.

  var tx = remote.transaction()
  tx.payment(account, addr, amount)

Integrating Ripple Lib JS into a Native iOS app

The Ripple Lib JS is a powerful tool and by far the best client library for ripple, but historically using javascript to build iOS apps was not acceptable. Designers and engineers cringe at the idea of using tools like phonegap to build javascript and html apps for ios and android. Native mobile applications using iOS’s Cocoa Touch framework are almost always more performant, striking and effective that their javascript, html counterparts.

The Ripple iOS app uses an innovative solution to leverage both the beauty of Native Cocoa Touch while using the ripple-lib javascript library for interaction with the ripple transaction and account APIs. The app uses a webview javascript bridge between objective-c and javascript, running the open-source library at

@class WebViewJavascriptBridge;
@interface RippleJSManager : NSObject {
    UIWebView               * _webView;
    WebViewJavascriptBridge * _bridge;


The bridge allows Objective-C to send messages to javascript and register listeners for messages coming from javascript, allowing the app to use native data structures and hardware-accelerated UI graphics while interacting with the ripple-lib js library.

On the javascript side the webview listens for a custom event triggered when the bridge to Objective-C is ready

document.addEventListener('WebViewJavascriptBridgeReady', onBridgeReady, false)
function onBridgeReady(event) {
    var bridge = event.bridge
    bridge.init(function(message, responseCallback) {
        var data = { 'Javascript Responds':'Wee!' }

Once the bridge is established both ways the javascript library can listen for messages from Obj-C and proxy them to the ripple API. The following listener will get the user’s account balances in its various currencies:

bridge.registerHandler('account_lines', function(data, responseCallback) {
    remote.set_secret(data.account, data.secret);
    .on('success', function (result) {
    .on('error', function (result) {

Sending a transaction is a multi-step affair, and the iOS app handles it gracefully by exposing a single API call that performs robust transaction submission:

bridge.registerHandler('send_transaction', function(data, responseCallback) {
    // send a transaction and report back the status

The above code would involve several different steps depending on what type of transaction and account you are interacting with, but the basic idea is that a transaction object is constructed from user input, then the JS library asks the network for a ledger path to use for the transaction. Once a path is found the JS library cryptographically signs the transaction and submits it to the network. Finally upon successful acceptance of the transaction a callback message is passed across the bridge to Obj-C for the UI to update accordingly. All of these calls are part of the set of publicly available APIs that you can leverage to easily build you own distributed payment apps.

Future Ripple Apps

Hundreds of valuable applications could be built using the Ripple payment and value network, which is why Ripple Labs releases all of the source code for their various appliations freely on github. The iOS app is no exception, and its source is released to the public in an attempt to help others build native mobile apps on the ripple network. Ripple Labs gladly supports efforts to build on its platform and intends to grow the value of the ripple network by building a vast ecosystem of applications and systems on top of its community’s open-source tools. Check out to get started with Ripple’s open-code goodness.