eosws Js/Ts bindings (from the dfuse API)

WebSocket consumer for the https://dfuse.io API on EOS networks.

Acknowledgement

A big thanks (and hug) to our dear friend Denis Carriere from EOS Nation for creating the initial version of this project.

Quickstart

Available endpoints:

• Mainnet wss://mainnet.eos.dfuse.io/v1/stream?token=[API TOKEN]
• Kylin wss://kylin.eos.dfuse.io/v1/stream?token=[API TOKEN]

Get Actions

import WebSocket from "ws"
import { get_actions, parse_actions } from "eosws"

// Get started with a free dfuse streaming API account.
// https://dfuse.io/#subscribe
const API_TOKEN = "eyJ...IBg"
const origin = "https://example.com"
const ws = new WebSocket(`wss://<SERVER>/v1/stream?token=${API_TOKEN}`, { origin })

ws.onopen = () => {
  ws.send(get_actions({ account: "eosio.token", action_name: "transfer" }))
}

ws.onmessage = (message) => {
  const actions = parse_actions(message.data)

  if (actions) {
    const { from, to, quantity, memo } = actions.data.trace.act.data
    console.log(from, to, quantity, memo)
  }
}

Get Table Rows

import { get_table_rows, parse_table_rows } from "eosws"

ws.onopen = () => {
  ws.send(get_table_rows({ code: "eosio", scope: "eosio", table_name: "voters" }))
}

ws.onmessage = (message) => {
  const table = parse_table_rows<Voters>(message.data, voters_req_id)

  if (table) {
    const { owner, producers, last_vote_weight } = table.data.row
    console.log(owner, producers, last_vote_weight)
  }
}

Related Javascript

• WebSockets (https://github.com/websockets/ws)
• Socket.io (https://github.com/socketio/socket.io)

Related Video

• Push Irreversible Transaction (https://youtu.be/dO-Le3TTim0?t=34m6s)

API

Table of Contents

• OptionalParams
  • Properties
• get_actions
  • Parameters
  • Examples
• get_transaction
  • Parameters
  • Examples
• get_table_rows
  • Parameters
  • Examples
• unlisten
  • Parameters
  • Examples
• generateReqId
  • Examples
• parse_actions
  • Parameters
  • Examples
• parse_table_rows
  • Parameters
  • Examples
• parse_ping
  • Parameters
  • Examples

OptionalParams

Type: Object

Properties

• req_id string An ID that you want sent back to you for any responses related to this request.
• start_block number Block at which you want to start processing. It can be an absolute block number, or a negative value, meaning how many blocks from the current head block on the chain. Ex: -2500 means 2500 blocks in the past, relative to the head block.
• fetch boolean Whether to fetch an initial snapshot of the requested entity.
• with_progress number Frequency of the progress of blocks processing (within the scope of a req_id). You will, at a maximum, receive one notification each 250 milliseconds (when processing large amounts of blocks), and when blockNum % frequency == 0. When you receive a progress notification associated with a stream (again, identified by its req_id), you are guaranteed to have seen all messages produced by that stream, between the previous progress notification and the one received (inclusively).

get_actions

Get Actions

Parameters

• data object Data Parameters
  • data.account string Contract account targeted by the action.
  • data.receiver string? Specify the receiving account executing its smart contract. If left blank, defaults to the same value as account.
  • data.action_name string? Name of the action called within the account contract.
  • data.with_ramops boolean? Stream RAM billing changes and reasons for costs of storage produced by each action.
  • data.with_inline_traces boolean? Stream the inline actions produced by each action.
  • data.with_deferred boolean? Stream the modifications to deferred transactions produced by each action.
• options OptionalParams Optional Parameters (optional, default {})

Examples

ws.send(get_actions({ account: "eosio.token", action_name: "transfer" }))

Returns string Message for ws.send

get_transaction

Get Transaction

Retrieve a transaction and follow its life-cycle. BETA: some life-cycle events are still being rolled out.

Parameters

• id string The transaction ID you're looking to track.
• options OptionalParams Optional Parameters (optional, default {})

Examples

ws.send(get_transaction("517...86d"))

Returns string Message for ws.send

get_table_rows

Get Table Rows

Retrieve a stream of changes to the tables, as a side effect of transactions/actions being executed.

Parameters

• data object Data Parameters
  • data.code string Contract account which wrote to tables.
  • data.scope string Table scope where table is stored.
  • data.table_name string Table name, shown in the contract ABI.
  • data.json boolean With json=true (or 1), table rows will be decoded to JSON, using the ABIs active on the queried block. This endpoint will thus automatically adapt to upgrades to the ABIs on chain. (optional, default true)
  • data.verbose boolean? Return the code, table_name, scope and key alongside each row.
• options OptionalParams Optional parameters (optional, default {})

Examples

ws.send(get_table_rows({ code: "eosio", scope: "eosio", table_name: "global" }))

Returns string Message for ws.send

unlisten

Unlisten

To interrupt a stream, you can unlisten with the original req_id

Parameters

• req_id string Request ID

Examples

ws.send(unlisten("original-request-id"))

generateReqId

Generate Req ID

Examples

generateReqId() // => req123

Returns string Request ID

parse_actions

Parse Actions from get_actions from WebSocket onmessage listener

Parameters

• data WebSocketData WebSocket Data from message event
• req_id string? Request ID

Examples

const actions = parse_actions < any > message

Returns ActionTrace Action Trace

parse_table_rows

Parse Table Deltas from get_table_rows from WebSocket onmessage listener

Parameters

• data WebSocketData WebSocket Data from message event
• req_id string? Request ID

Examples

const table_deltas = parse_table_rows < any > message

Returns ActionTrace Action Trace

parse_ping

Parse Ping from WebSocket onmessage listener

Parameters

• data WebSocketData WebSocket Data from message event

Examples

const ping = parse_ping(message)

Returns Ping Ping