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
- get_actions
- get_transaction
- get_table_rows
- unlisten
- generateReqId
- parse_actions
- parse_table_rows
- parse_ping
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 asaccount
. -
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, defaulttrue
) -
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