WebSockets for EOS-based on-chain exchange

With the launch of eosfinex right around the corner, we’re pleased to give a sneak peek into the mechanics powering the exchange.

eosfinex is a decentralised exchange built on EOS which will run fully on-chain — custody, order book, and matching engine are all part of the EOS contracts.

In the below article, we will take a look at the additional WebSocket protocols which we are offering to traders, as well as using the gateway in practise.

EOS On WebSockets

Usually, EOS contracts offer an HTTP-based API, which will be one way of trading on eosfinex. In addition to this, we will also support low latency WebSockets. WebSockets allow users to react quickly to drastic market movements and are at the same time a web standard.

The WebSocket protocol for eosfinex is based on the v2 protocol that is in use at Bitfinex. To make trading in the decentralised environment possible, we added a few changes.

We’ve designed the gateway to be capable of high-performance, and to make it simple for existing Bitfinex users to use it.

The following section shows a trade update message from the eosfinex WebSocket gateway.

Looks pretty familiar to our API v2 messages, doesn’t it?

[ '0', 
'tu',
[ '10',
'EOS.USD',
1549888790502,
'26195',
-10.99,
3,
'LIMIT',
0,
6594000,
'USD',
15498887884290,
1 ] ]

Auth & Pre-Signing

To be able to trade via WebSockets, we have to connect to the WebSocket gateway. The gateway itself runs as a native EOS plugin, on an EOS node next to the contract. The trader presigns the orders with their private key before sending it to the gateway.

The gateway then applies it to the contract. This way, no private keys ever leave the traders machine.

Our WebSocket library currently supports private key based signing and Scatter. In the future, we will add hardware wallet support.

Below is a sample message, sent from the client to the gateway, which would submit a trade:

[0,"on",null,{"meta":{"expiration":"2019-02-11T13:59:55","ref_block_num":53303,"ref_block_prefix":3288141905,"max_net_usage_words":0,"max_cpu_usage_ms":0,"delay_sec":0,"context_free_actions":[],"actions":[{"account":"exchgcntract","name":"place","authorization":[{"actor":"testuser4321","permission":"active"}],"data":"10c42057619db1ca620c6d9e180e000000003020610d305510270000000000004cad01000000000000"}],"transaction_extensions":[],"signatures":["SIG_K1_KfW7wg125Rc9Jt7HWTu3gzfXZqw24PjE4boTvYHuu1u3CTLeQGnz2xv2LLcWvBD1Paff7mV8qFUpnN4ttyp2jCpUGT8LaF"]}}]

By nature, all updates are public for an on-chain exchange. But how can one decide which trade update message belongs to the right user? This is an important question required for sending the right message to their socket.

For this reason we have added a special endpoint to our contract. The name of the EOS action is validate. Sunbeam, our WebSocket library uses it as part of an auth process.

By calling auth(), Sunbeam sends a locally signed message to the websocket gateway. The message sent to the validate action itself is empty and does not trigger anything.

The gateway only uses it to verify the user by comparing the signed message with their public keys on-chain. With an successful auth, we receive “private” wallet messages, trades and order updates.


Below you will find a brief demonstration of Scatter:


If you are curious as to how Sunbeam functions, feel free to take a look below. It is fully open-sourced under Apache License 2.0.


We hope you enjoyed this quick preview and are excited as us about the upcoming launch of eosfinex.


Leave your email address here to stay up-to-date with eosfinex developments as we approach our launch.

Join us on our mission to create the most innovative & industry-leading cryptocurrency exchange!

We’ve recently open-sourced a number of the development libraries most essential to us. To learn more about these, refer to the Bitfinex Github.