1.0.3 • Published 7 years ago

gravity-protocoljs-ws v1.0.3

Weekly downloads
-
License
BSD-2-Clause-Free...
Repository
-
Last release
7 years ago

Gravity websocket interface (gravityjs-ws)

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

Credit for the original implementation goes to jcalfeee.

npm version npm downloads

Setup

This library can be obtained through npm:

npm install gravityjs-ws

Usage

Several examples are available in the /examples folder, and the tests in /test also show how to use the library.

Browser bundles are provided in /build/, for testing purposes you can access this from rawgit:

<script type="text/javascript" src="https://cdn.rawgit.com/grapheneLab/gravityjs-ws/build/gravityjs-ws.js" />

A variable gravity_ws will be available in window.

For use in a webpack/browserify context, see the example below for how to open a websocket connection to the Openledger API and subscribe to any object updates:

var {Apis} = require("gravityjs-ws");
Apis.instance("wss://gravity.graphenelab.org", true).init_promise.then((res) => {
    console.log("connected to:", res[0].network);
    Apis.instance().db_api().exec( "set_subscribe_callback", [ updateListener, true ] )
});

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

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.

Witness node endpoints

This is a non-exhaustive list of endpoints available from the witness_node executable, which provides the API server of Bitshares.

Usage examples Apis.instance().db_api().exec(method, params) Apis.instance().db_api().exec("get_objects, [["1.3.0", "2.0.0", "2.1.0"]])

Objects

Method NameParams
get_objectsarray object_ids

Subscriptions

Method NameParams
set_subscribe_callbackfunction callback, bool notify_remove_create
set_pending_transaction_callbackfunction callback
set_block_applied_callbackfunction callback
cancel_all_subscriptions[]

Blocks and transactions

Method NameParams
get_block_headerint block_num
get_block_header_batcharray block_nums
get_blockint block_num
get_transactionint block_num, int trx_in_block

Globals

Method NameParams
get_chain_properties[]
get_global_properties[]
get_config[]
get_chain_id[]
get_dynamic_global_properties[]

Keys

Method NameParams
get_key_referencesarray public_keys
is_public_key_registeredstring public_key

Accounts

Method NameParams
get_accountsarray account_ids
get_full_accountsarray account_names_or_ids, bool subscribe
get_account_by_namestring name
get_account_referencesstring account_id
lookup_account_namesarray account_names
lookup_accountsstring lower_bound_name, int limit
get_account_count[]

Assets

Method NameParams
get_assetsarray asset_ids
list_assetsstring lower_bound_symbol, int limit
lookup_asset_symbolsarray symbols_or_ids

Markets / feeds

Method NameParams
get_limit_ordersstring asset_id_a, string asset_id_b, int limit
get_call_ordersstring asset_id, int limit
get_settle_ordersstring asset_id, int limit
get_margin_positionsstring account_id
subscribe_to_marketfunction callback, string asset_id_a, string asset_id_b
unsubscribe_from_marketstring asset_id_a, string asset_id_b
get_tickerstring base, string quote
get_24_volumestring base, string quote
get_order_bookstring base, string quote, int limit
get_trade_historystring base, string quote, date start, date stop, int limit

Tests

The tests show several use cases, to run, simply type npm run test. The tests require a local witness node to be running, as well as an active internet connection.