ECHO websocket interface (echojs-ws)

Pure JavaScript ECHO websocket library for node.js and browsers. Can be used to easily connect to and obtain data from the ECHO blockchain via public apis or local nodes.

Setup

This library can be obtained through npm:

npm install echojs-ws

Usage

Basic usage

Tests are available in the /test folder and show how to use the library.

import * as EchoJSWS from 'echojs-ws';
const address = 'wss://test-address.io/ws';

const updateListener = (object) => {
	console.log("set_subscribe_callback:\n", object);
};

EchoJSWS.Apis.instance(address, true).init_promise.then((res) => {
	console.log("connected to:", res[0].network);
	EchoJSWS.Apis.instance().dbApi().exec('set_subscribe_callback', [updateListener, true]);
});

The set_subscribe_callback callback (updateListener) will be called whenever an object on the blockchain changes or is removed. This is very powerful and can be used to listen to updates for specific accounts, assets or most anything else, as all state changes happen through object updates. Be aware though that you will receive quite a lot of data this way.

Let's look deeper to find operations for connection and execution of socket.

Apis

To manage connection you need to use Apis methods:

• setRpcConnectionStatusCallback(callback) - set callback on socket close
• setAutoReconnect(callback) - set callback on auto reconnect
• reset(cs, connect, connectTimeout, optionalApis, closeCb) - reset connection
• instance(cs, connect, connectTimeout, optionalApis, closeCb) - create new socket instance or reconnect by passed parameters
• chainId() - get chain id
• close() - close socket

Instance create example:

import { Apis } from 'echojs-ws';

const address = 'wss://test-address.io/ws';
const connect = true;
const connectTimeout = 5000;
const optionalApis = { enableCrypto: false };
const closeCb = () => console.log('Socket disconnected.');

Apis.instance(
	address, connect, connectTimeout, optionalApis, closeCb,
 ).init_promise.then((res) => {
	...
});

Created instance, provide connect/disconnect operations as well:

• connect(cs, connectTimeout, optionalApis = { enableCrypto: false }) - to connect
• close() - to disconnect

also some APIs can be used to execute different methods of block chain:

• dbApi() - to use db API
• networkApi() - to use network API
• historyApi() - to use history API
• cryptoApi() - to use crypto API

Here is example of usage:

import { Apis } from 'echojs-ws';

const address = 'wss://test-address.io/ws';
Apis.instance(address, true).init_promise.then(() => {
	 Apis.instance().dbApi();
	 Apis.instance().networkApi();
	 Apis.instance().historyApi();
	 Apis.instance().cryptoApi();
});

To execute an operation, use exec method through one of the APIs, for example via dbApi:

const method = 'get_objects';
const params = [['1.3.0', '2.1.0']];
Apis.instance().dbApi().exec(method, params);

• methode - it is a string name of operation you wanna to execute
• params - array of parameters for executable method

List of dbApi and others endpoints you can find here: http://docs.bitshares.org/api/database.html

ChainConfig

Watch and change chain configuration vai ChainConfig:

functions

• setChainId(chainId) - set chain id
• reset - set default options
• setPrefix(prefix) - set prefix

parameters

• core_asset - ECHO
• address_prefix - ECHO
• expire_in_secs - 15
• expire_in_secs_proposal - 24 * 60 * 60
• review_in_secs_committee - 24 * 60 * 60
• networks - { EchoDev: { core_asset, address_prefix, chain_id } }

Usage example:

import { ChainConfig } from 'echojs-ws';

console.log(ChainConfig.core_asset); // ECHO
ChainConfig.setPrefix('NEW_PREFIX');
ChainConfig.reset();
...
ChainConfig.setChainId(chainId)

Manager

Manager provide function to check connection.

• constructor(url, urls, autoFallback, closeCb, optionalApis, urlChangeCallback) - class constructor
• setCloseCb(cb) - set close callback
• close() - close socket
• logFailure(method, url, err) - log failure
• connect(connect, url) - connect to url
• connectWithFallback(connect, url, index, resolveFallback, rejectFallback) - connect to url with fallback
• checkConnections(rpc_user, rpc_password, resolveFB, rejectFB) - check and estimate latency for url passed through constructor, by creating new socket each time
• checkSingleUrlConnection(ws_rpc, rpc_user, rpc_password) - check and estimate latency for socket passed through parameters, if 10 sec timeout expires, throw an error

Usage example:

import { Manager, Apis } from 'echojs-ws';

const address = 'wss://test-address.io/ws';
const manager = new Manager({ url: , urls: [] });

Apis.instance(address, true).init_promise.then(() => {
	const ws_rpc = Apis.instance().ws_rpc;
	manager.checkSingleUrlConnection(ws_rpc)
		.then(console.log) // latency
		.catch(console.warn); // error
});

Tests

The tests show several use cases, to run, simply type npm run test.