rippled-ws-client-pool

rippled-ws-client-pool

Client side auto failover, health monitoring rippled (XRPL) client using websockets. A development GUI/debugging dashboard/implementation can be found here (the pool implementation here starting at line ~480).

Dependencies

• rippled-ws-client (npm)
• websocket when running in a non-browser environment

Can be used with

• rippled-ws-client-sign (npm)

To compile for the browser:

./node_modules/.bin/browserify -t  [ babelify --presets [ es2015 ] ] -r .:rippled-ws-client-pool -o dist/rippled-ws-client-pool.js

The output will be in the dist folder. You can use it in your project like this.

API

The pool offers an object with some getters and setters and events. Multiple pools can be configured simultaneously. All methods interacting with one of the configured rippled-servers return a Promise.

You create a new ConnectionPool using:

import RippledWsClientPool from 'rippled-ws-client-pool'

connectionPool = new RippledWsClientPool()

You call methods using:

connectionPool.addServer('wss://s1.ripple.com')

You send commands (returns Promise) using:

connectionPool.send({
  command: 'server_info'
}, {
  serverTimeout: 1500,
  overallTimeout: 10000
}).then(response => {
  console.log('Response', response)
}).catch(error => {
  console.log('Error', error.message)
})

You subscribe to events using:

connectionPool.on('ledger', (ledger) => {
  console.log('Ledger closed', ledger)
})

Events

• ledger One of the rippled servers in the pool reported a new closed ledger. Data: (int) ledger_index
• added A rippled host (websocket connection) is added to the pool. Note: the host may be down, you don't know the host status yet. Data: (string) hostname
• removed A rippled host (websocket connection) is removed and disconnected from the pool. Data: (string) hostname
• hostinfo Every ~2.5 seconds the pool will emit state information about hosts. You can use this data to plot health (if you'd like). All hosts will report hostinfo. Data: (object) hostinfo
• transaction When a transaction (in / out) hits one of the watched (subscribed) accounts. When you send a transaction, the account will automatically be watched (subscribed). - See: "Add and remove accounts to be watched"

Add and remove servers from the pool

Add (void) - emits added:

connectionPool.addServer('wss://s1.ripple.com')

If the protocol (ws:// / wss:// is omitted, wss:// will be assumed)

Remove (void) - emits removed:

connectionPool.removeServer('wss://s1.ripple.com')

Get Health Ranking

connectionPool.getRanking()

Add and remove accounts to be watched

This will send the { command: 'subscribe', account: 'rXXXXXX...' } under the hood (or unsubscribe, of course.

When a transaction is sent, the transaction account will be auto-watched (no need to subscribe for the account). After the transaction is sent and processed, the account will still be watched until the unsubscribeAccount method will be called.

Add account to be watched (void):

connectionPool.subscribeAccount('rXXXXXXX...')

If the account is already watched, it this command will be ignored.

Remove watched account (void):

connectionPool.unsubscribeAccount('rXXXXXXX...')

Get Transactions

connectionPool.getTransactions(account, Options)

eg. - with default Options

connectionPool.getTransactions('rXXXXXXX...', {
  ledger_index_min: -1,
  ledger_index_max: -1,
  limit: 100,
  forward: false,
  marker: null,
  ledger_hash: null,
  ledger_index: null
})

If you specify the account key in the Options object, this will overrule the first argument.

Specifing a marker is not required if you use the more() method on the response of a previous getTransactions call.

The getTransactions method will return an object with:

• account - The transaction account (string)
• transactions - The transactions (array)
• more() - Auto-marker: fetch the next page, auto-marker (method)

Sending commands

You can send a command to the pool using the send(Command, Options) method. The command may be sent to multiple rippled servers. The rippled servers connected to the pool will be queried in order (by health, waterfalled). The next server will be queried when the previous server timed out or responded with an error, except when the error is one of:

• unknownCmd
• invalidParams
• actMalformed
• lgrIdxsInvalid

... in which case querying another server will guarantee the same result.

The send(Command, Options) method will return a Promise;

• Command should be an object (see Ripple docs)
• Options are documented below ("Sending commands: Options")

Sample

connectionPool.send({
  command: 'account_info',
  account: 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59'
})

Sending commands: Options

You can specify options:

connectionPool.send({
  command: 'account_info',
  account: 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59'
}, {
  idempotency: 123,
  serverTimeout: 1500,
  overallTimeout: 10000
})

idempotency

If you allow a user to send another query while a previous query might still be in process, you can determine if you want to render results of an older request.

serverTimeout (ms)

Default: 1000 (1 sec.)

The timeout per server in the pool, after this timeout the next server will be queried. The first server to respond will resolve the promise, even if the next server has been queried already.

overallTimeout (ms)

Default: 5000 (5 sec.)

The overall timeout, after this timeout the promise will be rejected.

Submitting Transactions

You probably don't want to submit the transaction to multiple rippled, only to the healtiest server. You can get the connection object (with the websocket) for the healthiest server with:

connectionPool.getConnection()

The connection object you will receive is a rippled-ws-client object (Github) (npm)

You can then call the send() method on the connection object. This will return a Promise, resulting in the response returned by the rippled server.

This can easily be combined with rippled-ws-client-sign (npm) to sign and submit:

let Transaction = ... // XRPL Transaction Object
let SecretOrKey = ... // Family Seed (`sXXXX...`) or Keypair object (`privateKey` and `publicKey`)
let Connection = connectionPool.getConnection()

new RippledWsClientSign(Transaction, SecretOrKey, Connection)
  .then(TransactionSuccess => {
    // ...
  })
  .catch((SignSubmitError) => {
    // ...
  })

Getting all connection objects with state and preference

If you want to retrieve all connection objects to write your own filter to determine the server to submit your transaction to, you can use the getConnections() method:

let connections = connectionPool.getConnections()

An object will be returned with:

• connection with the connection object (rippled-ws-client - npm)

• hostname

• state the state object with all the health monitoring metrics

• preference the preference index in the pool (based on the server health)