gatewayd_4.0_spec.md

Gatewayd Improvement Proposal

Gatewayd is a transaction processing engine designed by engineers at Ripple Labs in order to build bridges in and out of the Ripple network.

The following is intended to be a complete proposal for version 4.0 of gatewayd, which is currently in use in several places as version 3.x. This proposal includes breaking changes but the spirit and many design features of gatewayd 3.x remain.

**** Please leave thoughts and suggestions in the comments below as we design the spec ****

Database

In order to track transaction history and process payments gatewayd uses a relational database that is persitent throughout the life of the gateway.

• sqlite
• mysql
• postgres

For simplicity gatewayd will use Sqlite by default, with Mysql and Postgres support out of the box.

It has been generally propsed that the node.js database ORM be Bookshelf.js on top of the Kinex.js query builder.

Database Tables

gatewayd.Address

An Address identifies the sender or the recipient of a transaction, and can represent the address of any account on any type of network.

• type
• address
• sub_address

gatewayd.Transaction

Transactions are the raison d'être of gatewayd. One transaction made inbound to gatewayd will be recorded, after which an outbound transaction is made according to a set of rules called policies.

• uid
• invoice
• in address id
• in amount
• in currency
• in issuer
• out address id
• out amount
• out currency
• out issuer
• state
• error

State Machine

• invoice
• inbound
• outbound
• success
• failed

gatewayd.Bridge

A Bridge connects an input address to an output address, and applies the bridge-specific policy to a transaction between the two bridged addresses.

• policy_name
• in address id
• out address id

gatewayd.GatewayTransaction

A GatewayTransaction records the history of payments made through the gateway, and what policy was applied to the input transaction to derive the output transaction.

• policy_name
• in transaction id
• out transaction id

gatewayd.Config

Configuration items are needed to create any type of integration with gatewayd and payment networks. The config is a key-value store that supports valid json, strings, or numbers as the value and strings for keys.

• key
• value

gatewayd.Policy

A Policy is piece of behavior that is applied to an incoming transaction, which runs a block of code and records a gateway transaction and an outgoing transaction.

• name
• function

Application

gatewayd.Server

The Server exposes an HTTP / JSON interface to interact with gatewayd. It can be modified to use additional REST routes and middleware including authentication and custom behavior.

Gatewayd uses Express JS 4 to serve json apis and static web content.

• use

gatewayd.Process

As a daemon software Gatewayd runs one or more unix processes, which by default include server.js which runs an http server and inbound.js which is a worker that processes gateway transactions. A process can be added to and removed from the process set given the path to the process executable.

• add
• remove

Installation

Gatewayd is a node.js command line application and is distributed via the NPM community package manager.

npm install -g gatewayd

Command Line Interface

• start
• stop
• restart
• reload
• config:get
• config:set
• migrate:up
• migrate:down

Configuration

~/.gatewayd directory

Custom configuration including variables and behavior is made in the ~/.gatewayd directory on the user's system.

config.json

Values in ~/.gatewayd/config.json will be applied to the gatewayd's configuration at boot up time.

initializers

Javascript files in ~/.gatewayd/initializers/ will each be run on startup. Each file must export a function, that takes the gatewayd global interface object as its first argument, and an optional callback as the second argument.

An example initializer might add middleware and processes to gatewayd before run time:

const RipplePlugin = require('gatewayd-ripple-plugin');

module.exports = function(gatewayd, next) {
  var ripplePlugin = new RipplePlugin({
    gatewayd: gatewayd
  });
  gatewayd.server.use('/ripple-simple', ripplePlugin.router);
  gatewayd.processes.add('~/.gatewayd/processes/ripple_inbound.js');
  gatewayd.processes.add('~/.gatewayd/processes/ripple_outbound.js');
  gatewayd.policies.insertBefore('default', 'ripple');
  next();
}

File Structure

The above initializer would have a ~/.gatewayd directory structured as follows:

~/.gatewayd
    config.json
    /initializers
        ripple.js
    /processes
        ripple_inbound.js
        ripple_outbound.js
    /policies
        ripple.js