• ƨ Sologenic XRPL Stream
  • Purpose
  • How to Participate
  • Install
  • Node Package Manager Scripts
    • Creating a packagable distribution
    • Testing
      • One-time execution of the unit tests
      • Persistent execution of unit tests (watching for changes)
    • Generating documentation
      • Generating HTML documentation only
      • Generating markdown documentation only
  • Typescript Example
    • Intializing the Sologenic XRPL stream with a hash-based queue
    • Intializing the Sologenic XRPL stream with a redis-based queue
    • Sending a Payment with XRPL account and secret
    • Sending a Payment with XRPL account and keypair
  • Event Emitter and Listeners
  • Transactions

ƨ Sologenic XRPL Stream

Purpose

The sologenic-xrpl-stream-js enables clients to communicate and submit transactions to the XRP Ledger seamlessly and reliably.

This library provides reliable transaction handling following the guide provided by XRPL.org reliable transaction submissions.

Once a transaction is submitted, it is queued either using a Hash-based in-memory queue (non-persistent, ideal for front-end) or a Redis (persistent, ideal for backend). Transactions are queued and dispatched in sequence. Account sequence numbers, ledgerVersions and fees are also handled for each transaction that is being dispatched.

Events are reported back to the client using a global EventEmitter and transaction-specific EventEmitter. This allows clients to track the statuses of their transactions and take actions based on the results.

Production uses

• SOLO ReactNative Wallet
• SOLO React Electron Wallet

In general, there are two types of users who would benefit from using this library:

1. Exchanges or users with large volumes of transactions who want to ensure they receive reliable delivery and can receive event notifications throughout the transactions validation process.

2. Users who do not want to deal with transaction dispatching, validations and errors on the XRPL.

How to Participate

We have a community for questions and support at sologenic-dev.slack.com. To receive an invite for the community please fill out the form and we'll send you your invite link.

Install

$ npm install sologenic-xrpl-stream-js

Node Package Manager Scripts

Each npm script defined in package.json can be run by simply running the command npm run-script <script name>

For example, notably the following scripts are frequently used when creating a packagable distribution, testing, and generating documentation.

Creating a packagable distribution

npm run-s build

Testing

One-time execution of the unit tests

The following command will iterate over all test cases (files with .spec.ts) as their suffix.

npm run-s test

Persistent execution of unit tests (watching for changes)

The following command will iterate over all test cases (files with .spec.ts) as their suffix. But it will also watch for changes to the .spec.ts and .ts scripts and run tests on change.

npm run-s watch

Generating documentation

The following command will generate both HTML and markdown documentation in the docs/ folder.

npm run-s doc

Generating HTML documentation only

The following command will generate HTML only documentation.

npm run-s doc:html

Generating markdown documentation only

The following command will generate markdown only documentation.

npm run-s doc:markdown

Typescript Example

When using the sologenic-xrpl-stream-js library on the server side, we recommend using redis as the queue storage mechanism, whereas when using the library on the client side, we recommend using hash as on the client side you will most likely not have a redis server accessible to you.

Intializing the Sologenic XRPL stream with a hash-based queue

Initialization of the Sologenic XRPL stream with the offline signer

The offline signing mechanism uses the standard sign() method included within the ripple-lib library. In previous versions of the library, ripple-lib signing was the only supported mechanism.

'use strict';
const ƨ = require('sologenic-xrpl-stream-js');

(async () => {
  try {
    const sologenic = await new ƨ.SologenicTxHandler(
      // RippleAPI Options
      {
        server: 'wss://testnet.xrpl-labs.com', // Kudos to Wietse Wind
      },
      // Sologenic Options, hash or redis (see SologenicOptions in documentation)
      {
        // Clear the cache before accessing the queue, since this is a hash-based 
        // queue it will be initialized empty, so this will have no effect.
        clearCache: true,
        queueType: "hash",
        hash: {}
      }
    ).connect();
);

Initialization of the Sologenic XRPL stream with the xumm signer

The xumm signing mechanism implements xumm signing within the sologenic-xrpl-stream-js library. The xumm signing is initialized by passing a signingMechansim parameter to the sologenic TX handler constructor. At the current point in time, the xumm integration requires user interaction between the xumm application and sologenic-xrpl-stream-js. When the xumm functionality is enabled, the sologenic-xrpl-stream-js prints out the next_url parameter that the user should follow within their web browser to sign the transaction. The signing of the transaction should happen before the maximumExecutionTime times out, otherwise the promise object will be rejected and the transaction will need to be retried with a new xumm transaction URL.

All existing transaction submission functionality remains the same in this library, the only difference is the signing mechanism requires third-party confirmation.

'use strict';
const ƨ = require('sologenic-xrpl-stream-js');

(async () => {
  try {
    const sologenic = await new ƨ.SologenicTxHandler(
      // RippleAPI Options
      {
        server: 'wss://testnet.xrpl-labs.com', // Kudos to Wietse Wind
      },
      // Sologenic Options, hash or redis (see SologenicOptions in documentation)
      {
        // Clear the cache before accessing the queue, since this is a hash-based 
        // queue it will be initialized empty, so this will have no effect.
        clearCache: true,
        queueType: "hash",
        hash: {},
        signingMechanism: new XummSigner({
          // Xumm API key and secret, inherited by the XUMM_API_KEY and XUMM_API_SECRET environment variables
          xummApiKey: process.env.XUMM_API_KEY,
          xummApiSecret: process.env.XUMM_API_SECRET,

          // The maximum execution time is the time in milliseconds that a TX
          // will wait for the transaction
          maximumExecutionTime: 10000
        })
      }
    ).connect();
);

Intializing the Sologenic XRPL stream with a redis-based queue

'use strict';
const ƨ = require('sologenic-xrpl-stream-js');

(async () => {
  try {
    const sologenic = await new ƨ.SologenicTxHandler(
      // RippleAPI Options
      {
        server: 'wss://testnet.xrpl-labs.com', // Kudos to Wietse Wind
      },
      // Sologenic Options, hash or redis
      {
        // Clear the cache before accessing the queue, since this is a redis-based 
        // queue it will be emptied before after connecting.  Please make sure there
        // is no data in the database you're accessing you want to preserve.
        clearCache: true,
        queueType: 'redis',
        redis: {          
          // The IP address or hostname of the redis queue
          // host: '127.0.0.1',

          // The port of the redis queue
          // port: 6379,

          // The password to access the redis queue
          // password: 'password',

          // The database number of the redis queue (if multiple database support is active)
          // database: 1
        }
      }
    ).connect();
);

Note: When using a redis queue, you must have an active redis server which the transactional handler can connect.

Sending a Payment with XRPL account and secret

'use strict';
const ƨ = require('sologenic-xrpl-stream-js');

(async () => {
  try {
    const sologenic = await new ƨ.SologenicTxHandler(
      // RippleAPI Options
      {
        server: 'wss://testnet.xrpl-labs.com', // Kudos to Wietse Wind
      },
      // Sologenic Options, hash or redis
      {
        clearCache: true,
        queueType: "hash",
        hash: {}
      }
    ).connect();
   
    // Events have their own types now.
    sologenic.on('queued', (event: SologenicTypes.QueuedEvent) => {
      console.log('GLOBAL QUEUED: ', event);
    });
    sologenic.on('dispatched', (event: SologenicTypes.DispatchedEvent) => {
      console.log('GLOBAL DISPATCHED:', event);
    });
    sologenic.on('requeued', (event: SologenicTypes.RequeuedEvent) => {
      console.log('GLOBAL REQUEUED:', event);
    });
    sologenic.on('warning', (event: SologenicTypes.WarningEvent) => {
      console.log('GLOBAL WARNING:', event);
    });
    sologenic.on('validated', (event: SologenicTypes.ValidatedEvent) => {
      console.log('GLOBAL VALIDATED:', event);
    });
    sologenic.on('failed', (event: SologenicTypes.FailedEvent) => {
      console.log('GLOBAL FAILED:', event);
    });

    await sologenic.setAccount({
      address: 'rNbe8nh1K6nDC5XNsdAzHMtgYDXHZB486G',
      secret: 'ssH5SSKYvHBynnrYoCnmvsbxrNGEv'
    });

    const tx = sologenic.submit({
      TransactionType: 'Payment',
      Account: 'rNbe8nh1K6nDC5XNsdAzHMtgYDXHZB486G',
      Destination: 'rUwty6Pf4gzUmCLVuKwrRWPYaUiUiku8Rg',
      Amount: {
        currency: '534F4C4F00000000000000000000000000000000',
        issuer: 'rNbe8nh1K6nDC5XNsdAzHMtgYDXHZB486G',
        value: '100000000'
      }
    });

    // Events have their own types now.
    tx.events.on('queued', (event: SologenicTypes.QueuedEvent) => {
      console.log('TX QUEUED: ', event);
    }).on('dispatched', (event: SologenicTypes.DispatchedEvent) => {
      console.log('TX DISPATCHED:', event);
    }).on('requeued', (event: SologenicTypes.RequeuedEvent) => {
      console.log('TX REQUEUED:', event);
    }).on('warning', (event: SologenicTypes.WarningEvent) => {
      console.log('TX WARNING:', event);
    }).on('validated', (event: SologenicTypes.ValidatedEvent) => {
      console.log('TX VALIDATED:', event);
    });.on('failed', (event: SologenicTypes.FailedEvent) => {
      console.log('TX FAILED:', event);
    });

    console.log(await tx.promise);
  } catch (error) {
    console.log('Error:', error);
  }
})();

Sending a Payment with XRPL account and keypair

'use strict';
const ƨ = require('sologenic-xrpl-stream-js');

(async () => {
  try {
    const sologenic = await new ƨ.SologenicTxHandler(
      // RippleAPI Options
      {
        server: 'wss://testnet.xrpl-labs.com', // Kudos to Wietse Wind
      },
      // Sologenic Options, hash or redis
      {
        clearCache: true,
        queueType: "hash",
        hash: {}
      }
    ).connect();
   
    // Events have their own types now.
    sologenic.on('queued', (event: SologenicTypes.QueuedEvent) => {
      console.log('GLOBAL QUEUED: ', event);
    });
    sologenic.on('dispatched', (event: SologenicTypes.DispatchedEvent) => {
      console.log('GLOBAL DISPATCHED:', event);
    });
    sologenic.on('requeued', (event: SologenicTypes.RequeuedEvent) => {
      console.log('GLOBAL REQUEUED:', event);
    });
    sologenic.on('warning', (event: SologenicTypes.WarningEvent) => {
      console.log('GLOBAL WARNING:', event);
    });
    sologenic.on('validated', (event: SologenicTypes.ValidatedEvent) => {
      console.log('GLOBAL VALIDATED:', event);
    });
    sologenic.on('failed', (event: SologenicTypes.FailedEvent) => {
      console.log('GLOBAL FAILED:', event);
    });

    await sologenic.setAccount({
      address: 'rNbe8nh1K6nDC5XNsdAzHMtgYDXHZB486G',
      keypair: {
        publicKey: 'my public key with permission to sign transaction for address',
        privateKey: 'my private key with permission to sign transactions for address'
      }
    });

    const tx = sologenic.submit({
      TransactionType: 'Payment',
      Account: 'rNbe8nh1K6nDC5XNsdAzHMtgYDXHZB486G',
      Destination: 'rUwty6Pf4gzUmCLVuKwrRWPYaUiUiku8Rg',
      Amount: {
        currency: '534F4C4F00000000000000000000000000000000',
        issuer: 'rNbe8nh1K6nDC5XNsdAzHMtgYDXHZB486G',
        value: '100000000'
      }
    });

    // Events have their own types now.
    tx.events.on('queued', (event: SologenicTypes.QueuedEvent) => {
      console.log('TX QUEUED: ', event);
    }).on('dispatched', (event: SologenicTypes.DispatchedEvent) => {
      console.log('TX DISPATCHED:', event);
    }).on('requeued', (event: SologenicTypes.RequeuedEvent) => {
      console.log('TX REQUEUED:', event);
    }).on('warning', (event: SologenicTypes.WarningEvent) => {
      console.log('TX WARNING:', event);
    }).on('validated', (event: SologenicTypes.ValidatedEvent) => {
      console.log('TX VALIDATED:', event);
    });.on('failed', (event: SologenicTypes.FailedEvent) => {
      console.log('TX FAILED:', event);
    });

    console.log(await tx.promise);
  } catch (error) {
    console.log('Error:', error);
  }
})();

Event Emitter and Listeners

There are 6 different events that you'll receive while a transaction is being processed by the library. Each event has its own type associated with it as you can see in the src/types/sologenicoptions.d.ts. See below for a list of events and the emitted objects.

• Event (validated): SologenicTypes.ValidatedEvent
• Event (warning): SologenicTypes.WarningEvent
• Event (requeued): SologenicTypes.RequeuedEvent
• Event (queued): SologenicTypes.QueuedEvent
• Event (failed): SologenicTypes.FailedEvent
• Event (dispatched): SologenicTypes.DispatchedEvent

As you can see below in the transactions section there is a snippet of code there. The reason we added this is because we wanted to outline that we have two separate event emitters that emit events based on the transactions. One of the event emitters being a global emitter that receives all events, and then a transaction based event emitter which receives events for only the transaction it has subscribed to.

For example, the sologenic.on() subscriptions (event listeners) to events are global, meaning you'll receive events for every transaction you submit. Whereas, the tx.events.on() subscriptions (event listeners) are specific to the transactions themselves, once the transaction has been validated or failed you will no longer receive transactions as the listeners are all unsubscribed automatically.

// Events have their own types now.
sologenic.on('queued', (event: SologenicTypes.QueuedEvent) => {
  console.log('GLOBAL QUEUED: ', event);
});
sologenic.on('dispatched', (event: SologenicTypes.DispatchedEvent) => {
  console.log('GLOBAL DISPATCHED:', event);
});
sologenic.on('requeued', (event: SologenicTypes.RequeuedEvent) => {
  console.log('GLOBAL REQUEUED:', event);
});
sologenic.on('warning', (event: SologenicTypes.WarningEvent) => {
  console.log('GLOBAL WARNING:', event);
});
sologenic.on('validated', (event: SologenicTypes.ValidatedEvent) => {
  console.log('GLOBAL VALIDATED:', event);
});
sologenic.on('failed', (event: SologenicTypes.FailedEvent) => {
  console.log('GLOBAL FAILED:', event);
});

await sologenic.setAccount({
  address: 'rNbe8nh1K6nDC5XNsdAzHMtgYDXHZB486G',
  keypair: {
    publicKey: 'my public key with permission to sign transaction for address',
    privateKey: 'my private key with permission to sign transactions for address'
  }
});

const tx = sologenic.submit({
  TransactionType: 'Payment',
  Account: 'rNbe8nh1K6nDC5XNsdAzHMtgYDXHZB486G',
  Destination: 'rUwty6Pf4gzUmCLVuKwrRWPYaUiUiku8Rg',
  Amount: {
    currency: '534F4C4F00000000000000000000000000000000',
    issuer: 'rNbe8nh1K6nDC5XNsdAzHMtgYDXHZB486G',
    value: '100000000'
  }
});

// Events have their own types now.
tx.events.on('queued', (event: SologenicTypes.QueuedEvent) => {
  console.log('TX QUEUED: ', event);
}).on('dispatched', (event: SologenicTypes.DispatchedEvent) => {
  console.log('TX DISPATCHED:', event);
}).on('requeued', (event: SologenicTypes.RequeuedEvent) => {
  console.log('TX REQUEUED:', event);
}).on('warning', (event: SologenicTypes.WarningEvent) => {
  console.log('TX WARNING:', event);
}).on('validated', (event: SologenicTypes.ValidatedEvent) => {
  console.log('TX VALIDATED:', event);
});.on('failed', (event: SologenicTypes.FailedEvent) => {
  console.log('TX FAILED:', event);
});

Transactions

Each transaction that is created by the sologenic-xrpl-stream-js library will have a unique uuidv4 that is used for tracking purposes in the queue system. The tx.id is not the same as the XRPL ledger hash.

Example snippet from src/lib/sologenictxhandler.ts

public submit(tx: SologenicTypes.TX): SologenicTypes.TransactionObject {
  try {
    // Generate a unique ID using the uuid library
    const id = uuid();

    // Add a new EventEmitter to txEvents array identifiable with the generated id.
    this.txEvents![id] = new EventEmitter();
    this._initiateTx(id, tx);

When you are receiving events while the transaction is undergoing processing in the XRPL, you'll receive your transaction ID which can be then used to verify your transaction has been completed. In addition, once the transaction has been validated in the XRPL, you will notice that the tx.id is appended to a memo-field within the transaction itself.

The tx.id field is non-async and does not change if the transaction is requeued or failed so that you have the option of going back to check the state.