@dfuse/eosws-js
v0.11.12
Published
`eosws` JavaScript/TypeScript bindings (from the [dfuse API](https://dfuse.io/))
Downloads
5
Readme
eosws
JavaScript/TypeScript bindings (from the dfuse API)
WebSocket consumer for the https://dfuse.io API on EOS networks.
Deprecated
IMPORTANT This library is now deprecated and is not actively maintained anymore.
We transform it into a full blown dfuse API Client Library. We highly recommend to upgrade, to profit from automatic authentication handling, full dfuse REST API, automatic re-connect and stream restart, streamlined overall usage of the library and all the latest goodies of dfuse API. We have prepared an extensive Migration Guide so you can migrate from this library to the latest version like a breeze.
The development now occurs at https://github.com/dfuse-io/client-js.
Installation
Using Yarn:
yarn add @dfuse/eosws-js
or using NPM:
npm install --save @dfuse/eosws-js
Quick Start
When targeting a browser (you will need a bundler like Webpack since we only ship ES5 modules files for now):
const { EoswsClient, createEoswsSocket, InboundMessageType } = require("@dfuse/eosws-js")
const endpoint = "mainnet.eos.dfuse.io"
const token = "<Paste your API token here>"
const client = new EoswsClient(
createEoswsSocket(() => new WebSocket(`wss://${endpoint}/v1/stream?token=${token}`))
)
client
.connect()
.then(() => {
client
.getActionTraces({ account: "eosio.token", action_name: "transfer" })
.onMessage((message) => {
if (message.type === InboundMessageType.ACTION_TRACE) {
const { from, to, quantity, memo } = message.data.trace.act.data
console.log(from, to, quantity, memo)
}
})
})
.catch((error) => {
console.log("Unable to connect to dfuse endpoint.", error)
})
Use Cases
You can see various examples in the examples folder. Here the reference list:
- Get Action Traces
- Get Action Traces From Multiple Contracts
- Get Table Rows
- Get Table Snapshot Only
- Get Transaction Lifecycle
- Multi Listen
- Socket Notifications
Endpoints
Here are the currently available endpoints:
- Mainnet
mainnet.eos.dfuse.io
- Jungle
jungle.eos.dfuse.io
- Kylin
kylin.eos.dfuse.io
Node.js
If you target a Node.js
environment instead, import a proper WebSocket
client
implementation.
For now, the library only accepts a WebSocket
that follows the WebSocket Web API
interface. We will provide adapter for the most used packages in the near feature.
For now, the preferred method in Node.js
is to use the ws.
This package is compatible with the WebSocket Web API.
Package ws
Ensure the you added ws as a dependency of your project. Then, do the following:
const WebSocket = require("ws")
// ... rest as the browser example above
Package websocket
The client of this package does not follow WebSocket Web API specification. As such, it's currently not supported by this library.
We might provide an adapter in the future, but nothing is planned yet, pull request welcome!
Note It can be used standalone (i.e. without this library), if you really need it, but won't be able to leverage all the goodies this library provides for you.
API
Protocol
For the low-level communication protocol, heads down to dfuse WebSocket API Documentation.
Library
Here the API reference for this actual library.
SocketFactory
A type representing a function taking no parameters and that must return a WebSocket
object that will be
used to connect to the remote endpoint.
Example
const socketFactory: SocketFactory = () =>
new WebSocket(`wss://${endpoint}/v1/stream?token=${token}`, { origin })))
createEoswsSocket
A factory method responsible of creating a EoswsSocket
object that is consumed by the EoswsClient
.
Parameters
socketFactory
SocketFactory The factory function that will be used to construct the underlying socket.options
SocketOptions The options object to pass to theEoswsSocket
interface.
SocketOptions
Properties
id
string An id to identify the actual socket for debugging purposes. (Optional,undefined
by default)keepAlive
boolean Determine if if apong
message should be sent at regular interval to ensure the connection is healthy. (Optional,true
by default).keepAliveIntervalInMs
number The amount of time in milliseconds to wait between each keep alive message sending. (Optional,30000
(30s) by default).autoReconnect
boolean Determine if the socket should auto-reconnect to the remote endpoint when connection is closed abnormally. (Optional,true
by default).reconnectDelayInMs
number The amount of time in milliseconds to wait before trying a second reconnection attempt. (Optional,5000
(5s) by default).onInvalidMessage
(message: object) => void A function that is invoked back when a message of an unknowntype
is returned to the client. (Optional,undefined
by default)onReconnect
() => void A function that is invoked back when a successful reconnection happen. (Optional,undefined
by default)onError
(event: object) => void A function that is invoked back when socket receive anErrorEvent
according to the WebSocket protocol. (Optional,undefined
by default)onClose
(event: object) => void A function that is invoked back when socket receives aCloseEvent
according to the WebSocket protocol. (Optional,undefined
by default)
EoswsClient
A class handling the communication with the remote endpoint dealing with all the details of the Eosws
protocol.
constructor
Constructs an EoswsClient
instance.
Parameters
EoswsSocket
EoswsSocket AEoswsSocket
instance as returned by createEoswsClient.
connect
Parameters
None
Return
Returns a Promise<void>
resolving correctly once connected initially on the remote endpoint.
disconnect
Returns a Promise<void>
resolving correctly once disconnection has completed with the client.
getActionTraces
Parameters
data
GetActionTracesData Data Parameters for receiving action traces.account
string Contract account targeted by the action.receiver
string? Specify the receiving account executing its smart contract. If left blank, defaults to the same value asaccount
.action_name
string? Name of the action called within the account contract.with_ramops
boolean? Stream RAM billing changes and reasons for costs of storage produced by each action.with_inline_traces
boolean? Stream the inline actions produced by each action.with_deferred
boolean? Stream the modifications to deferred transactions produced by each action.
options
StreamOptions Optional common stream options (optional, default{}
)
Return
A ListenerObject on which you can start listening for message related to the stream by calling listen
on it
and stop listening by calling unlisten
on it.
getTableRows
Parameters
data
GetTableRows Data Parameterscode
string Contract account which wrote to tables.scope
string Table scope where table is stored.table
string Table name, shown in the contract ABI.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
)
options
StreamOptions Optional common stream options (optional, default{}
)
Return
A ListenerObject on which you can start listening for message related to the stream by calling listen
on it
and stop listening by calling unlisten
on it.
getTransactionLifecycle
Parameters
id
string The transaction id to get transaction info.options
StreamOptions Optional common stream options (optional, default{}
)
Return
A ListenerObject on which you can start listening for message related to the stream by calling listen
on it
and stop listening by calling unlisten
on it.
ListenerObject
The object returned when calling one of the main stream handler so that you can then listen
and unlisten
on the stream.
Properties
listen
(listener: (message: InboundMessage) => void) A function that when called, send the starting message to the server and route back all specific stream message for this request back to thelistener
parameter of the project.reqId
string The request id used to map back messages from socket to this specific stream.unlisten
() A function that when called, stop listening from the stream. Theunlisten
message is sent to the remote endpoint to stop it.
StreamOptions
An object containing the various common properties for the Eosws base messaging system.
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.listen
boolean Whether to listen for new events upcoming for this type of stream.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).
Development
The best way to develop this library is through modifying and adding examples to the project.
To run the examples, it's quite simple, follow these instructions:
Install project dependencies so that you get development tools at the same time:
yarn install
Link the project inside itself, that will be necessary to correct run the examples which import
@dfuse/eosws-js
:yarn link yarn link @dfuse/eosws-js
Start the build watcher so distribution files are always up-to-date. Forgetting to do that will prevent examples from picking latest changes you've made to source files!
yarn build:watch
Last step is to add
.env
file containing the dfuse API key required to run the examples. Create a file.env
at the root of the project with the following content:DFUSE_IO_API_KEY=Replace this with API key!
Final check, let's run an example to ensure everything is working:
yarn run ts-node examples/get-action-traces.ts
Publishing
First, ensure you have a pristine state of your working directory, and check tests & compilation:
rm -rf dist
yarn build
yarn test
Assuming you have been granted access rights to publish this package, the command to perform is simply:
yarn publish --access public
Pre-release
If you want to publish a pre-release version not flagged as the latest so that people still pulls the current stable version unless they opt-in explicitly, use the following invocation:
yarn publish --access public --tag next
Credits / Acknowledgement
A big thanks (and hug) to our dear friend Denis Carriere from EOS Nation for creating the initial version of this project.
License
MIT