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.
| Interface | For | Encoding | Enabled by |
|---|---|---|---|
WebSocket /api/v1/ws | Browsers, wallets, web apps | JSON text messages | -wslisten or -stratumwslisten |
GET /api/v1/events | Simple polling clients | JSON | Always on |
| NNG | Indexers and pool software on the same host or network | FlatBuffers | -nngrpc, -nngpub, -nngpublic |
| ZeroMQ | Existing ZeroMQ tooling | Raw 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:
wslisten=127.0.0.1:10650A 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.
wscat -c ws://127.0.0.1:10650/api/v1/ws -s lotus-push.v1
> {"op":"subscribe","id":1,"subs":[{"type":"blocks"}]}function lotusPush(url, subs, onEvent) {
let ws, delay = 1000;
const open = () => {
ws = new WebSocket(url, 'lotus-push.v1');
ws.onopen = () => {
delay = 1000;
ws.send(JSON.stringify({op: 'subscribe', id: 1, subs}));
};
ws.onmessage = (m) => {
const msg = JSON.parse(m.data);
if (msg.op === 'event' || msg.op === 'resync') onEvent(msg);
};
// Subscriptions belong to the connection: reconnect and resubscribe.
ws.onclose = () => setTimeout(open, delay = Math.min(delay * 2, 30000));
};
open();
}
lotusPush('ws://127.0.0.1:10650/api/v1/ws',
[{type: 'blocks'}, {type: 'address', value: 'lotus_...'}],
(msg) => console.log(msg));The node greets every connection, then answers the subscription:
{"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 #
type | value | Matches |
|---|---|---|
address | Any address format the node accepts | The address's script, as an output or a spent input |
script | scriptPubKey in hex | Same as address. Replies always use this form |
txid | 64 hex characters | That transaction |
token | Token id, 64 hex characters | SLP and ALP transactions naming it |
lokad | 8 hex digits or 4 ASCII characters (RANK) | Transactions carrying that protocol id |
blocks | none | Every block connected or disconnected |
topic | rank | Transactions carrying a RANK vote |
topic | pool | Blocks the node's pool found. Operator data: refused unless the client is on loopback |
Client messages #
{"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 #
{"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}}event | Sent when | Extra fields |
|---|---|---|
tx_added_to_mempool | A matching transaction enters the mempool | tx |
tx_removed_from_mempool | It leaves the mempool other than by confirmation | tx, reason: conflict, expiry, size, reorg, replaced |
tx_confirmed | It is included in a block | tx, block |
tx_unconfirmed | Its block was disconnected (reorg) | tx, block |
block_connected, block_disconnected | With a blocks subscription | block: hash, height, time, n_tx |
topic | A topic event | topic, 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:
{"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 #
| Limit | Default | Option |
|---|---|---|
| Connections | 1000 | -wsmaxconnections |
| Connections per client address | 16 | -wsmaxconnperip |
| Handshakes per minute per address | 30 | -wsconnrate |
| Subscriptions per connection | 1000 | -wsmaxsubs |
| Queued events per connection | 2000 | -wsqueue |
| Message size | 16 KiB | |
| Messages per second | 10 |
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:
curl -s 'http://127.0.0.1:10604/api/v1/events?since_seq=0&limit=50'let since = 0;
setInterval(async () => {
const r = await fetch(`http://127.0.0.1:10604/api/v1/events?since_seq=${since}`);
const {events, latest_seq} = await r.json();
events.forEach((e) => console.log(e.type, e.data));
since = latest_seq;
}, 5000);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 #
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, andRestCall, 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://.
| Topic | Published when |
|---|---|
updateblktip | The chain tip moved |
blkconnected, blkdisconctd | A block was connected or disconnected |
mempooltxadd, mempooltxrem | A transaction entered or left the mempool |
chainstflush | The chain state was flushed to disk |
miningwrkchg | Mining work changed (for external stratum coordinators) |
pushevent | Every mempool and block event of the push bus, with the JSON of the WebSocket event |
pushblock | Block 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.
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.
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=1 | Also push sessions (public chain data, the pool topic refused) and the pushblock topic |
With -poolnngbridge=1 | Also 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:
zmqpubhashblock=tcp://127.0.0.1:13604
zmqpubhashtx=tcp://127.0.0.1:13604| Option | Topic | Body |
|---|---|---|
-zmqpubhashblock=<address> | hashblock | Block hash (32 bytes) |
-zmqpubhashtx=<address> | hashtx | Transaction hash (32 bytes) |
-zmqpubrawblock=<address> | rawblock | The serialized block |
-zmqpubrawtx=<address> | rawtx | The serialized transaction |
-zmqpubsequence=<address> | sequence | Hash 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.
