To get live updates when an event occurs on the blockchain, Catapult REST publishes WebSockets.
Client applications can open a WebSocket connection and get a unique identifier.
With this identifier, applications qualify to subscribe to the available channels instead of constantly polling the API for updates.
When an event occurs in a channel, the REST Gateway sends a notification to every subscribed client in real-time.
WebSocket URIs share the same host and port as the HTTP requests URIs, but use the ws://
protocol:
ws://localhost:3000/ws
Response format
All channels share the same response format, which is:
{
"topic": "{subscribed-channel}",
"data": {}
}
topic
contains the name of the subscribed channel, so the same websocket can be used to monitor multiple channels (topic
matches thesubscribe
field provided in the request body when subscribing).data
is a channel-specific object. Each channel listed below describes the data object it returns.
Channels
block
The block
channel notifies subscribed clients every time a new block is harvested.
Each returned message contains information about a harvested block.
Request body
{
"uid": "{uid}",
"subscribe": "block"
}
Response data
finalizedBlock
The finalizedBlock
channel notifies subscribed clients every time a set of blocks is finalized.
Each returned message contains information about the highest block in the finalization round. All blocks with a smaller height are assumed finalized.
Request body
{
"uid": "{uid}",
"subscribe": "finalizedBlock"
}
Response data
confirmedAdded/{address}
The confirmedAdded
channel notifies subscribed clients when a transaction related to the given address is included in a block.
Each returned message contains information about a confirmed transaction.
Request body
{
"uid": "{uid}",
"subscribe": "confirmedAdded/{address}"
}
Response data
unconfirmedAdded/{address}
The unconfirmedAdded
channel notifies subscribed clients when a transaction related to the given address enters the unconfirmed state, waiting to be included in a block.
Each returned message contains information about an unconfirmed transaction.
Possible scenarios when this message is received are: the transaction is announced to the network via the PUT /transaction
HTTP endpoint or an :ref:AggregateBondedTransaction <aggregate-bonded>
has all required cosigners and changes its state from partial to unconfirmed.
Request body
{
"uid": "{uid}",
"subscribe": "unconfirmedAdded/{address}"
}
Response data
unconfirmedRemoved/{address}
The unconfirmedRemoved
channel notifies subscribed clients when a transaction related to the given address exits the unconfirmed state.
Each returned message contains a no-longer-unconfirmed transaction hash.
Possible scenarios when this message is received are: the transaction is now confirmed, or the deadline was reached and the transaction was not included in a block.
Request body
{
"uid":"{uid}",
"subscribe":"unconfirmedRemoved/{address}"
}
Response data
- Hash
partialAdded/{address}
The partialAdded
channel notifies subscribed clients when an AggregateBondedTransaction related to the given address enters the partial state, waiting for all required cosignatures to complete.
Each returned message contains information about an added partial transaction.
Request body
{
"uid": "{uid}",
"subscribe": "partialAdded/{address}"
}
Response data
partialRemoved/{address}
The partialRemoved
channel notifies subscribed clients when a transaction related to the given address exits the partial state.
Each returned message contains a removed partial transaction hash.
Possible scenarios when this message is emitted are: all required cosignatures were received and the transaction is now unconfirmed, or the deadline was reached and the transaction was not included in a block.
Request body
{
"uid": "{uid}",
"subscribe": "partialRemoved/{address}"
}
Response data
- Hash
cosignature/{address}
The cosignature
channel notifies subscribed clients when a cosignature-signed transaction related to the given address is added to an :ref:AggregateBondedTransaction <aggregate-bonded>
in the partial state.
Each returned message contains a cosignature-signed transaction.
Request body
{
"uid": "{uid}",
"subscribe": "cosignature/{address}"
}
Response data
status/{address}
The status
channel notifies subscribed clients when a transaction related to the given address signals an error.
Each returned message contains an error message and a transaction hash.
Request body
{
"uid": "{uid}",
"subscribe": "status/{address}"
}
Response data