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
In general, there are two types of users who would benefit from using this library:
- 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.
- 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(
{
server: 'wss://testnet.xrpl-labs.com',
},
{
clearCache: true,
queueType: "hash",
hash: {}
}
).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(
{
server: 'wss://testnet.xrpl-labs.com',
},
{
clearCache: true,
queueType: 'redis',
redis: {
}
}).connect();
}
);
Note: When using a redis queue, you must have an active redis server which the transactional handler can connect.
Using LedgerDevice as SigningMechanism
The LedgerDevice signing mechanism implements the feature to sign transactions with a Ledger Nano S or Nano X. The LedgerDeviceSigner is initialized by passing a signingMechanism
parameter to the SologenicTxHandler constructor. As with the other SigningMechanism on Sologenic XRPL stream, the library will handle all the signing process.
The initialization of this SigningMechanism HAS to be triggered by the user, otherwise the library will throw an exception.
Set SigningMechanism AFTER SologenicTxHandler initialization.
'use-strict';
import * as s from 'sologenic-xrpl-stream-js';
async () => {
try {
const sologenic = await new ƨ.SologenicTxHandler(
{
server: 'wss://testnet.xrpl-labs.com'
},
{
clearCache: true,
queueType: 'hash',
hash: {}
}
).connect();
}
};
establishConnection().then(async () => {
await sologenic.setSigningMechanism(
new s.LedgerDeviceSigner({
ripple_server: RIPPLE_SERVER_WEBSOCKET
})
);
const { accounts } = await sologenic.connectSigner();
});
Using D'CENT Wallet as SigningMechanism
The D'CENT Wallet signing mechanism implements the feature to sign transactions with a D'CENT wallet. The DcentSigner is initialized by passing a signingMechanism
parameter to the SologenicTxHandler after initialization. As with the other SigningMechanism on Sologenic XRPL stream, the library will handle all the signing process/requests.
The initialization of this SigningMechanism HAS to be triggered by the user. Here are the steps:
'use-strict';
const ƨ = require('sologenic-xrpl-stream-js');
(async () => {
try {
const sologenic = await new ƨ.SologenicTxHandler(
{
server: 'wss://testnet.xrpl-labs.com',
},
{
clearCache: true,
queueType: "hash",
hash: {}
}
)
}
}).connect();
const establishConnection = () => {
try {
await sologenic.setSigningMechanism(new ƨ.DcentSigner());
const { address } = await sologenic.connectSigner();
} catch(e) {
console.log(e);
}
}
Using SOLO Wallet as SigningMechanism
The SOLO Wallet signing mechanism implements the feature to sign transactions with a SOLO Wallet. (Available for Android and iOS). The SOLO Wallet signer is initialized by passing a signingMechanism
parameter to the SologenicTxHandler after initialization. As with the other SigningMechanism on Sologenic XRPL Stream, the library will handle the signing process/requests.
new ƨ.SoloWalletSigner({
server: 'https://api.sologenic.org/api/v1/',
container_id: HTML_ELEMENT_ID,
fallback_container_id: HTML_ELEMENT_ID,
deeplink_url: DEEPLINK_URL,
is_mobile: true || false
});
The initialization of this SigningMechanism HAS to be triggered by the user. Here are the steps:
'use-strict';
const ƨ = require('sologenic-xrpl-stream-js');
(async () => {
try {
const sologenic = await new ƨ.SologenicTxHandler(
{
server: 'wss://testnet.xrpl-labs.com',
},
{
clearCache: true,
queueType: 'hash',
hash: {},
}
)
}
}).connect();
const establishConnection = () => {
await sologenic.setSigningMechanism(
new ƨ.SoloWalletSigner({
server: 'https://api.sologenic.org/api/v1/',
container_id: 'container_id',
fallback_container_id: 'fallback_container_id',
})
);
const { address } = await sologenic.connectSigner();
}
Using Xumm Wallet as SigningMechanism
The XUMM Wallet signing mechanim implements the feature to sign transactions with a XUMM Wallet. The XUMM Wallet signer is initialized by passing a signingMechanism
parameter to the SologenicTxHandler after initialization. As with the other SigningMechanism on Sologenic XRPL Stream, the library will handle the signing process/requests.
This SigningMechanism requires the next arguments to be passed on its constructor.
new ƨ.XummWalletSigner({
server: 'https://api.sologenic.org/api/v1/',
container_id: HTML_ELEMENT_ID,
fallback_container_id: HTML_ELEMENT_ID,
is_mobile: true || false
});
The initialization of this SigningMechanism HAS to be triggered by the user. Here are the steps:
'use-strict';
const ƨ = require('sologenic-xrpl-stream-js');
(async () => {
try {
const sologenic = await new ƨ.SologenicTxHandler(
{
server: 'wss://testnet.xrpl-labs.com',
},
{
clearCache: true,
queueType: 'hash',
hash: {},
}
)
}
}).connect();
const establishConnection = () => {
await sologenic.setSigningMechanism(
new ƨ.XummWalletSigner({
server: 'https://api.sologenic.org/api/v1/',
container_id: 'container_id',
fallback_container_id: 'fallback_container_id'
})
);
const { address } = await sologenic.connectSigner();
}
Sending a Payment with any of the Sologenic XRPL SigningMechanism
'use strict';
const ƨ = require('sologenic-xrpl-stream-js');
(async () => {
try {
const sologenic = await new ƨ.SologenicTxHandler(
{
server: 'wss://testnet.xrpl-labs.com',
},
{
clearCache: true,
queueType: "hash",
hash: {}
}
)
}
).connect();
const establishConnection = () => {
await sologenic.setSigningMechanism(new ƨ.SoloWalletSigner({
server: 'https://api.sologenic.org/api/v1/',
container_id: 'qr_container',
fallback_container_id: 'qr_container_fallback'
}));
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);
});
const { address } = await sologenic.connectSigner();
await sologenic.setAccount({
address: address
});
const tx = sologenic.submit({
TransactionType: 'Payment',
Account: address,
Destination: 'rUwty6Pf4gzUmCLVuKwrRWPYaUiUiku8Rg',
Amount: {
currency: '534F4C4F00000000000000000000000000000000',
issuer: 'rNbe8nh1K6nDC5XNsdAzHMtgYDXHZB486G',
value: '100000000'
}
});
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);
})();
Sending a Payment with XRPL account and secret
'use strict';
const ƨ = require('sologenic-xrpl-stream-js');
(async () => {
try {
const sologenic = await new ƨ.SologenicTxHandler(
{
server: 'wss://testnet.xrpl-labs.com',
},
{
clearCache: true,
queueType: "hash",
hash: {}
}
).connect();
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'
}
});
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
(async () => {
try {
const sologenic = await new ƨ.SologenicTxHandler(
{
server: 'wss://testnet.xrpl-labs.com',
},
{
clearCache: true,
queueType: "hash",
hash: {}
}
).connect();
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'
}
});
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.
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'
}
});
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 {
const id = uuid();
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.