Push interfaces
API12.4.15+

Push interfaces

Get chain events as they happen: the WebSocket at /api/v1/ws, the polled events route, the NNG sockets and ZeroMQ.

Instead of polling the REST API, a client can subscribe to what it cares about and let the node push events: a transaction entering the mempool, a confirmation, a new block.

InterfaceForEncodingEnabled by
WebSocket /api/v1/wsBrowsers, wallets, web appsJSON text messages-wslisten or -stratumwslisten
GET /api/v1/eventsSimple polling clientsJSONAlways on
NNGIndexers and pool software on the same host or networkFlatBuffers-nngrpc, -nngpub, -nngpublic
ZeroMQExisting ZeroMQ toolingRaw bytes-zmqpub...

Push notifications are not consensus code. They only report what validation already decided.

WebSocket #

Enable it #

The WebSocket is not served by the RPC port: it has its own listener. On a node without stratum, open a push-only listener:

Config
wslisten=127.0.0.1:10650

A node that already runs the browser miner (stratum=1 with stratumwslisten=..., port 3335 by default) serves the push endpoint on that same port, on the path /api/v1/ws. wspush=0 turns it off.

Bind the listener to loopback or to the interface your reverse proxy reaches. To publish it, proxy /api/v1/ws with the WebSocket upgrade headers; see Security.

Connect and subscribe #

The subprotocol name is lotus-push.v1.

Shell
wscat -c ws://127.0.0.1:10650/api/v1/ws -s lotus-push.v1
> {"op":"subscribe","id":1,"subs":[{"type":"blocks"}]}

The node greets every connection, then answers the subscription:

JSON
{"op":"hello","protocol":"lotus-push.v1","tip":{"hash":"...","height":1427139},"limits":{"max_subs":1000,"max_subs_per_ip":20000,"max_subs_per_message":100,"max_message_bytes":16384,"queue_events":2000,"messages_per_second":10},"sub_types":["address","script","txid","token","lokad","blocks","topic"],"topics":["pool","rank"]}
{"op":"result","id":1,"ok":true,"results":[{"ok":true,"sub":{"type":"blocks"}}],"subscriptions":1}

Subscriptions #

typevalueMatches
addressAny address format the node acceptsThe address's script, as an output or a spent input
scriptscriptPubKey in hexSame as address. Replies always use this form
txid64 hex charactersThat transaction
tokenToken id, 64 hex charactersSLP and ALP transactions naming it
lokad8 hex digits or 4 ASCII characters (RANK)Transactions carrying that protocol id
blocksnoneEvery block connected or disconnected
topicrankTransactions carrying a RANK vote
topicpoolBlocks the node's pool found. Operator data: refused unless the client is on loopback

Client messages #

JSON
{"op":"subscribe",   "id":1, "subs":[{"type":"txid","value":"..."}]}
{"op":"unsubscribe", "id":2, "subs":[{"type":"blocks"}]}
{"op":"unsubscribe", "id":3, "all":true}
{"op":"list",        "id":4}
{"op":"ping",        "id":5}

id is optional and echoed in the reply. A result has one entry per subscription, in order; a failed entry carries an error such as invalid_address, unknown_type or too_many_subscriptions. ping is answered by {"op":"pong",...}. An unusable message gets {"op":"error","error":"invalid_json"} (or unknown_op, rate_limited, ...).

Events #

JSON
{"op":"event",
 "matched":[{"type":"script","value":"76a914...88ac"}],
 "event":"tx_added_to_mempool",
 "seq":812, "time":1763200000,
 "tx":{"txid":"...","size":225,"coinbase":false,
       "inputs":[{"prev_txid":"...","prev_n":0,"value":5000000,"script":"76a9...","address":"lotus_..."}],
       "n_inputs":1,"inputs_known":true,
       "outputs":[{"n":0,"value":1000000,"script":"76a9...","address":"lotus_..."}],
       "n_outputs":2}}
eventSent whenExtra fields
tx_added_to_mempoolA matching transaction enters the mempooltx
tx_removed_from_mempoolIt leaves the mempool other than by confirmationtx, reason: conflict, expiry, size, reorg, replaced
tx_confirmedIt is included in a blocktx, block
tx_unconfirmedIts block was disconnected (reorg)tx, block
block_connected, block_disconnectedWith a blocks subscriptionblock: hash, height, time, n_tx
topicA topic eventtopic, data

Amounts are integers in satoshis. Token amounts are strings. An event lists at most 64 inputs and 64 outputs; n_inputs and n_outputs give the real counts. seq increases over all events of the node, so gaps are normal.

Lost events #

If a client reads too slowly, its queue overflows and the node sends:

JSON
{"op":"resync","reason":"queue_overflow","dropped":12,"last_seq":830}

Refetch your state over REST, then carry on. Do the same after every reconnect: events that happened while you were away are not replayed. tx_confirmed is not sent during the initial block download.

Limits #

LimitDefaultOption
Connections1000-wsmaxconnections
Connections per client address16-wsmaxconnperip
Handshakes per minute per address30-wsconnrate
Subscriptions per connection1000-wsmaxsubs
Queued events per connection2000-wsqueue
Message size16 KiB
Messages per second10

The server pings every 30 seconds. A browser page on another site than the node's must be allowed with -wsorigin=<origin>; clients that send no Origin (non-browser) are accepted.

GET /api/v1/push/info shows the listeners, open connections and counters.

Polled events #

Without a WebSocket, poll the node's ring of recent events:

Shell
curl -s 'http://127.0.0.1:10604/api/v1/events?since_seq=0&limit=50'

Each entry has seq, type (for example mempool_tx, block_connected) and data. Pass the latest_seq of the last answer as since_seq. limit is at most 200.

NNG #

NNG is the binary interface for indexers, explorer backends and pool software. Messages are FlatBuffers; the schema is src/nng_interface/nng_interface.fbs in the source tree.

Private sockets #

Config
nngrpc=ipc:///var/lib/lotus/nngrpc.pipe
nngpub=ipc:///var/lib/lotus/nngpub.pipe
nngpubmsg=blkconnected
nngpubmsg=blkdisconctd
nngpubmsg=mempooltxadd
nngpubmsg=mempooltxrem
  • -nngrpc=<url> is a request/reply socket: blocks and block ranges, raw slices of block and undo files, the mempool, mining templates, typed mirrors of common REST routes, and RestCall, a tunnel to the REST API with the same read-only policy (bodies up to -maxapibodysize, 1 MiB by default).
  • -nngpub=<url> is a publish/subscribe socket. Enable each topic with -nngpubmsg=<topic>.

URLs start with ipc:// or tcp://.

TopicPublished when
updateblktipThe chain tip moved
blkconnected, blkdisconctdA block was connected or disconnected
mempooltxadd, mempooltxremA transaction entered or left the mempool
chainstflushThe chain state was flushed to disk
miningwrkchgMining work changed (for external stratum coordinators)
pusheventEvery mempool and block event of the push bus, with the JSON of the WebSocket event
pushblockBlock events of the push bus only

Each message starts with its topic in 12 bytes (zero-padded), followed by the FlatBuffers payload.

A request/reply client can also receive push events by polling a session (PushPollRequest): same subscriptions and queue as a WebSocket connection, dropped after 60 seconds without a poll.

Warning

The private sockets are unauthenticated and expose everything they serve. Use ipc://, or tcp:// on a private address behind a firewall.

Public listener #

A second, separate endpoint is built to face the internet. It is open to anyone and safe because of what it serves and what each call may cost.

Config
nngpublic=tls+tcp://0.0.0.0:10610
nngpublicpub=tls+tcp://0.0.0.0:10611
nngpubliccert=/var/lib/lotus/nngpublic.crt
nngpublickey=/var/lib/lotus/nngpublic.key
Public listener
Request/reply (-nngpublic, port 10610)Mining templates from a shared cache, and block submission (RestCall POST rpc/submitblock). Every other call is refused
Publish (-nngpublicpub, port 10611)miningwrkchg, blkconnected, blkdisconctd only
With -nngpublicpush=1Also push sessions (public chain data, the pool topic refused) and the pushblock topic
With -poolnngbridge=1Also pool templates and share reports from external pool coordinators

Each client address is limited (20 requests per second, 5 template requests per second, 1 submission per second, 4 connections by default) and banned for 10 minutes when it keeps misbehaving. lotus-cli getnngpublicinfo shows endpoints, limits, connections and bans; clearnngpublicbans lifts the bans. See Pool.

ZeroMQ #

ZeroMQ notifications are compiled into the release binaries and off until you set an address:

Config
zmqpubhashblock=tcp://127.0.0.1:13604
zmqpubhashtx=tcp://127.0.0.1:13604
OptionTopicBody
-zmqpubhashblock=<address>hashblockBlock hash (32 bytes)
-zmqpubhashtx=<address>hashtxTransaction hash (32 bytes)
-zmqpubrawblock=<address>rawblockThe serialized block
-zmqpubrawtx=<address>rawtxThe serialized transaction
-zmqpubsequence=<address>sequenceHash plus C (block connected), D (block disconnected), A (added to mempool) or R (removed from mempool); A and R carry the mempool sequence number

The socket type is PUB. A subscriber must set a subscription prefix (for example hash) or it receives nothing. Each option has a matching high-water-mark option (-zmqpubhashtxhwm=<n>, ...). lotus-cli getzmqnotifications lists what is active.

ZeroMQ does no authentication: expose its ports to trusted hosts only. Unlike the WebSocket, it does not filter per address or token, and a subscriber is not told when it missed messages.

Source share/www/docs/push.md in the lotusd repository
Checked against doc/push-notifications.md doc/nng.md doc/nng-public.md doc/zmq.md src/push/wsserver.cpp src/push/wsserver.h src/push/subscription.cpp src/api/events_handler.cpp src/api/api_server.cpp src/nng_interface/nng_interface.h src/init.cpp src/stratum/stratumconfig.cpp src/chainparamsbase.cpp src/zmq/zmqrpc.cpp dockerfiles/cross-build.sh