WebSockets

WebSocket Support

Version 19.0+

The Nano node offers notification of confirmed blocks over WebSockets. This offers higher throughput over the HTTP callback, and uses a single ingoing connection instead of an outgoing connection for every block.

The HTTP callback is still available and both mechanisms can be used at the same time.

Example

A sample client is available at https://github.com/cryptocode/nano-websocket-sample-nodejs/blob/master/index.js

Configuration

A new "websocket" entry is added to config.json:

"node": {
    "websocket": {
        "enable": "true",
        "address": "::1",
        "port": "7078"
    },
}

With the above configuration, localhost clients should connect to ws://[::1]:7078

Subscribe and unsubscribe

To subscribe to all confirmed blocks:

{
	"action": "subscribe",
	"topic": "confirmation"
}

To unsubscribe:

{
	"action": "unsubscribe",
	"topic": "confirmation"
}

Future versions may include account filtering and additional topics.

Optional acknowledgement

All WebSocket actions can request an acknowledgement.

{
	"action": "subscribe", 
	"topic": "confirmation", 
	"ack": true,
	"id": "optional unique id"
}

If the subscription succeeds, the following message will be sent back (note that no message ordering is guaranteed):

{
	"ack": "subscribe",
	"time": "1552766057328",
	"id": "optional unique id"
}

Sample result

Confirmation

Note the differences from the HTTP callback:

• The "block" contains JSON instead of an escaped string. This makes parsing easier.
• The JSON received by the client contains a topic, event time (milliseconds since epoch) and the message itself. Future versions of the node may offer more topics, as well as filtering capabilities.
• Subtype is part of block (if it's a state block)
• There is no "is_send" property since "subtype" signifies the intent for state blocks.

{
	"topic": "confirmation",
	"time": "1552766057328",
	"message": {
	    "account": "xrb_16c4ush661bbn2hxc6iqrunwoyqt95in4hmw6uw7tk37yfyi77s7dyxaw8ce",
	    "amount": "1000000000000000000000000",
	    "hash": "3E746498A3DBF5DF9CB498E00B8C9B20769112498E35EF23B3C0EF46DCF192EA",
	    "block": {
	        "type": "state",
	        "subtype": "send",
	        "account": "xrb_16c4ush661bbn2hxc6iqrunwoyqt95in4hmw6uw7tk37yfyi77s7dyxaw8ce",
	        "previous": "21EE146C2EAD2CA30D84C43A5EEF4BCEC90F103E45905F254336E8CF591330D3",
	        "representative": "xrb_3dmtrrws3pocycmbqwawk6xs7446qxa36fcncush4s1pejk16ksbmakis32c",
	        "balance": "135902000000000000000000000000",
	        "link": "1942DE5E420129A193D51217C6E9CAFAFA38E1413E7C26F85D4825F37D029725",
	        "link_as_account": "xrb_16c4ush661bbn2hxc6iqrunwoyqt95in4hmw6uw7tk37yfyi77s7dyxaw8ce",
	        "signature": "CD585FC15C50BC589B9C41C5D632B26E1C66744E97DCEDA878342E10D2C219CD7BCF5F49117F29E94B6B1C8D85794DACE2CAE14D6E6C944167E7F381368CD208",
	        "work": "466ac84fc9edd4b3"
	    }
    }
}

Vote

{
  "topic": "vote",
  "time": "1554995525343",
  "message": {
    "account": "xrb_1n5aisgwmq1oibg8c7aerrubboccp3mfcjgm8jaas1fwhxmcndaf4jrt75fy",
    "signature": "1950700796914893705657789944906107642480343124305202910152471520450456881722545967829502369630995363643731706156278026749554294222131169148120786048025353",
    "sequence": "855471574",
    "blocks": [
      "6FB9DE5D7908DEB8A2EA391AEA95041587CBF3420EF8A606F1489FECEE75C869"
    ]
  }
}

Optional filters

Some topics support filters. Note that, if empty options are supplied (see examples below), an empty filter will be used and nothing will be broadcasted.

Confirmation filters

Filters for confirmation can be used to subscribe only to selected accounts. Once filters are given, blocks from accounts that do not match the options are not broadcasted.

Note that legacy blocks are never broadcasted if filters are given, even if they match the accounts.

{
	"action": "subscribe",
	"topic": "confirmation",
	"options": {
		"all_local_accounts": true,
		"accounts": [
			"xrb_16c4ush661bbn2hxc6iqrunwoyqt95in4hmw6uw7tk37yfyi77s7dyxaw8ce",
			"nano_3dmtrrws3pocycmbqwawk6xs7446qxa36fcncush4s1pejk16ksbmakis32c"
		]
	}
}

• When all_local_accounts is set to true, blocks that mention accounts in any wallet will be broadcasted.
• accounts is a list of additional accounts to subscribe to. Both prefixes are supported.

Vote filters

Filters for votes can be used to subscribe only to votes from selected representatives. Once filters are given, votes from representatives that do not match the options are not broadcasted.

{
	"action": "subscribe",
	"topic": "vote",
	"options": {
		"representatives": [
			"xrb_16c4ush661bbn2hxc6iqrunwoyqt95in4hmw6uw7tk37yfyi77s7dyxaw8ce",
			"nano_3dmtrrws3pocycmbqwawk6xs7446qxa36fcncush4s1pejk16ksbmakis32c"
		]
	}
}