Skip to content

Listening to New Blocks⚓︎

BEGINNER

The block WS and finalizedBlock WS WebSocket channels send real-time notifications when a new block is produced or finalized. Compared to polling the /chain/info GET endpoint, WebSockets push updates as they happen without the overhead of repeated API calls.

This tutorial shows how to subscribe to both channels and display each update as it arrives.

Alternative: Polling

For a polling-based approach, see the Querying Chain and Finalization Height tutorial.

Prerequisites⚓︎

Install the websockets library:

pip install websockets

This tutorial uses the native WebSocket API available in Node.js 22 or later. No additional packages are required.

This tutorial uses the Tyrus WebSocket client, which is loaded by the JBang dependency line in the snippet.

See the WebSocket reference for details on the connection protocol.

Full Code⚓︎

The following is the complete code listing for this tutorial. A detailed, step-by-step explanation follows in the next section.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
import asyncio
import json
import os

from websockets import connect

NODE_URL = os.getenv('NODE_URL', 'https://reference.symboltest.net:3001')
WS_URL = NODE_URL.replace('http', 'ws', 1) + '/ws'
print(f'Using node {NODE_URL}')


async def main():
    async with connect(WS_URL) as websocket:
        # Connect to websocket endpoint
        response = json.loads(await websocket.recv())
        uid = response['uid']
        print(f'Connected to {WS_URL} with uid {uid}')

        # Subscribe to block channel
        await websocket.send(json.dumps(
            {'uid': uid, 'subscribe': 'block'}))
        print('Subscribed to block channel')

        # Subscribe to finalizedBlock channel
        await websocket.send(json.dumps(
            {'uid': uid, 'subscribe': 'finalizedBlock'}))
        print('Subscribed to finalizedBlock channel')

        # Handle incoming messages
        try:
            async for raw_message in websocket:
                message = json.loads(raw_message)
                topic = message['topic']

                if topic == 'block':
                    block = message['data']['block']
                    block_meta = message['data']['meta']
                    print(
                        f'New block: height={int(block["height"]):,}'
                        f' hash={block_meta["hash"][:16]}...'
                    )

                if topic == 'finalizedBlock':
                    finalized = message['data']
                    print(
                        f'Finalized: height={int(finalized["height"]):,}'
                        f' hash={finalized["hash"][:16]}...'
                    )

        # Unsubscribe on exit
        finally:
            await websocket.send(json.dumps(
                {'uid': uid, 'unsubscribe': 'block'}))
            await websocket.send(json.dumps(
                {'uid': uid, 'unsubscribe': 'finalizedBlock'}))
            print('Unsubscribed from all channels')


try:
    asyncio.run(main())
except KeyboardInterrupt:
    pass
except Exception as error:
    print(error)

Download source

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
const NODE_URL = process.env.NODE_URL ||
    'https://reference.symboltest.net:3001';
const WS_URL = `${NODE_URL.replace('http', 'ws')}/ws`;
console.log(`Using node ${NODE_URL}`);

try {
    const websocket = new WebSocket(WS_URL);

    // Connect to websocket endpoint
    const uid = await new Promise(resolve => {
        websocket.addEventListener('message', event => {
            const message = JSON.parse(event.data);
            resolve(message.uid);
        }, { once: true });
    });
    console.log(`Connected to ${WS_URL} with uid ${uid}`);

    // Subscribe to block channel
    websocket.send(JSON.stringify({ uid, subscribe: 'block' }));
    console.log('Subscribed to block channel');

    // Subscribe to finalizedBlock channel
    websocket.send(JSON.stringify({ uid, subscribe: 'finalizedBlock' }));
    console.log('Subscribed to finalizedBlock channel');

    // Handle incoming messages
    websocket.addEventListener('message', event => {
        const message = JSON.parse(event.data);
        const topic = message.topic;

        if ('block' === topic) {
            const block = message.data.block;
            const blockMeta = message.data.meta;
            console.log(
                `New block: height=${
                    BigInt(block.height).toLocaleString()}` +
                ` hash=${blockMeta.hash.substring(0, 16)}...`);
        }

        if ('finalizedBlock' === topic) {
            const finalized = message.data;
            console.log(
                `Finalized: height=${
                    BigInt(finalized.height).toLocaleString()}` +
                ` hash=${finalized.hash.substring(0, 16)}...`);
        }
    });

    // Unsubscribe on exit
    process.on('SIGINT', () => {
        websocket.send(JSON.stringify({ uid, unsubscribe: 'block' }));
        websocket.send(
            JSON.stringify({ uid, unsubscribe: 'finalizedBlock' }));
        console.log('Unsubscribed from all channels');
        websocket.close();
        process.exit(0);
    });
} catch (error) {
    console.error(error);
}

Download source

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
//JAVA 21+
//DEPS com.fasterxml.jackson.core:jackson-databind:2.17.1
//DEPS org.glassfish.tyrus.bundles:tyrus-standalone-client:2.2.0

import java.io.IOException;
import java.net.URI;
import java.util.concurrent.CompletableFuture;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import jakarta.websocket.ClientEndpoint;
import jakarta.websocket.ContainerProvider;
import jakarta.websocket.OnMessage;
import jakarta.websocket.RemoteEndpoint;
import jakarta.websocket.Session;
import jakarta.websocket.WebSocketContainer;

@ClientEndpoint
public final class ListenNewBlocks {
    private static final ObjectMapper JSON_MAPPER = new ObjectMapper();

    private final CompletableFuture<String> uidFuture =
        new CompletableFuture<>();

    private final String nodeUrl = System.getenv().getOrDefault(
        "NODE_URL", "https://reference.symboltest.net:3001");

    private final String wsUrl = nodeUrl.replaceFirst("http", "ws")
        + "/ws";

    public static void main(final String[] args) {
        try {
            new ListenNewBlocks().run();
        } catch (final Exception ex) {
            System.out.println(null == ex.getMessage()
                ? ex.toString()
                : ex.getMessage());
        }
    }

    private void run() throws Exception {
        System.out.printf("Using node %s%n", nodeUrl);


        final WebSocketContainer container =
            ContainerProvider.getWebSocketContainer();
        final Session session = container.connectToServer(
            this, URI.create(wsUrl));
        final RemoteEndpoint.Basic remote = session.getBasicRemote();

        // Connect to websocket endpoint
        final String uid = uidFuture.join();
        System.out.printf("Connected to %s with uid %s%n", wsUrl, uid);

        // Subscribe to block channel
        remote.sendText(JSON_MAPPER.createObjectNode()
            .put("uid", uid).put("subscribe", "block")
            .toString());
        System.out.println("Subscribed to block channel");

        // Subscribe to finalizedBlock channel
        remote.sendText(JSON_MAPPER.createObjectNode()
            .put("uid", uid).put("subscribe", "finalizedBlock")
            .toString());
        System.out.println("Subscribed to finalizedBlock channel");

        // Unsubscribe on exit
        Runtime.getRuntime().addShutdownHook(new Thread(() -> {
            try {
                remote.sendText(JSON_MAPPER.createObjectNode()
                    .put("uid", uid).put("unsubscribe", "block")
                    .toString());
                remote.sendText(JSON_MAPPER.createObjectNode()
                    .put("uid", uid).put("unsubscribe", "finalizedBlock")
                    .toString());
                System.out.println("Unsubscribed from all channels");
                session.close();
            } catch (final IOException ex) {
                throw new IllegalStateException(ex);
            }
        }));

        // Wait forever
        Thread.currentThread().join();
    }

    // Handle incoming messages
    @OnMessage
    public void onMessage(final String payload) throws IOException {
        final JsonNode message = JSON_MAPPER.readTree(payload);

        // Special case for the initial handshake message
        if (message.has("uid")) {
            uidFuture.complete(message.get("uid").asText());
            return;
        }

        final String topic = message.get("topic").asText();

        if ("block".equals(topic)) {
            final JsonNode block = message.get("data").get("block");
            final JsonNode blockMeta = message.get("data").get("meta");
            System.out.printf("New block: height=%,d hash=%s...%n",
                block.get("height").asLong(),
                blockMeta.get("hash").asText().substring(0, 16));
        }

        if ("finalizedBlock".equals(topic)) {
            final JsonNode finalized = message.get("data");
            System.out.printf("Finalized: height=%,d hash=%s...%n",
                finalized.get("height").asLong(),
                finalized.get("hash").asText().substring(0, 16));
        }
    }

}

Download source

The snippet uses the NODE_URL environment variable to set the Symbol API node. If no value is provided, a default one is used. The WebSocket URL is derived from NODE_URL by replacing the HTTP protocol with the WebSocket protocol and appending /ws.

The program runs until interrupted with Ctrl+C, which triggers the unsubscribe step before closing the connection.

Code Explanation⚓︎

Connecting to the WebSocket⚓︎

13
14
15
16
17
    async with connect(WS_URL) as websocket:
        # Connect to websocket endpoint
        response = json.loads(await websocket.recv())
        uid = response['uid']
        print(f'Connected to {WS_URL} with uid {uid}')

 7
 8
 9
10
11
12
13
14
15
16
    const websocket = new WebSocket(WS_URL);

    // Connect to websocket endpoint
    const uid = await new Promise(resolve => {
        websocket.addEventListener('message', event => {
            const message = JSON.parse(event.data);
            resolve(message.uid);
        }, { once: true });
    });
    console.log(`Connected to ${WS_URL} with uid ${uid}`);

45
46
47
48
49
50
51
52
53
        final WebSocketContainer container =
            ContainerProvider.getWebSocketContainer();
        final Session session = container.connectToServer(
            this, URI.create(wsUrl));
        final RemoteEndpoint.Basic remote = session.getBasicRemote();

        // Connect to websocket endpoint
        final String uid = uidFuture.join();
        System.out.printf("Connected to %s with uid %s%n", wsUrl, uid);

The first step is to open a WebSocket connection to the node's /ws endpoint. Upon connecting, the server sends a message containing a unique identifier (uid) that must be included in all subsequent subscription requests.

Subscribing to Channels⚓︎

19
20
21
22
23
24
25
26
27
        # Subscribe to block channel
        await websocket.send(json.dumps(
            {'uid': uid, 'subscribe': 'block'}))
        print('Subscribed to block channel')

        # Subscribe to finalizedBlock channel
        await websocket.send(json.dumps(
            {'uid': uid, 'subscribe': 'finalizedBlock'}))
        print('Subscribed to finalizedBlock channel')

18
19
20
21
22
23
24
    // Subscribe to block channel
    websocket.send(JSON.stringify({ uid, subscribe: 'block' }));
    console.log('Subscribed to block channel');

    // Subscribe to finalizedBlock channel
    websocket.send(JSON.stringify({ uid, subscribe: 'finalizedBlock' }));
    console.log('Subscribed to finalizedBlock channel');

55
56
57
58
59
60
61
62
63
64
65
        // Subscribe to block channel
        remote.sendText(JSON_MAPPER.createObjectNode()
            .put("uid", uid).put("subscribe", "block")
            .toString());
        System.out.println("Subscribed to block channel");

        // Subscribe to finalizedBlock channel
        remote.sendText(JSON_MAPPER.createObjectNode()
            .put("uid", uid).put("subscribe", "finalizedBlock")
            .toString());
        System.out.println("Subscribed to finalizedBlock channel");

The code subscribes to two channels:

  • block WS: Notifies every time a new block is produced (approximately every 30 seconds).
  • finalizedBlock WS: Notifies every time a finalization round completes (approximately every 10 to 20 minutes).

Each subscription message includes the uid received during the connection step and the name of the channel.

Handling Messages⚓︎

29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
        # Handle incoming messages
        try:
            async for raw_message in websocket:
                message = json.loads(raw_message)
                topic = message['topic']

                if topic == 'block':
                    block = message['data']['block']
                    block_meta = message['data']['meta']
                    print(
                        f'New block: height={int(block["height"]):,}'
                        f' hash={block_meta["hash"][:16]}...'
                    )

                if topic == 'finalizedBlock':
                    finalized = message['data']
                    print(
                        f'Finalized: height={int(finalized["height"]):,}'
                        f' hash={finalized["hash"][:16]}...'
                    )

26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
    // Handle incoming messages
    websocket.addEventListener('message', event => {
        const message = JSON.parse(event.data);
        const topic = message.topic;

        if ('block' === topic) {
            const block = message.data.block;
            const blockMeta = message.data.meta;
            console.log(
                `New block: height=${
                    BigInt(block.height).toLocaleString()}` +
                ` hash=${blockMeta.hash.substring(0, 16)}...`);
        }

        if ('finalizedBlock' === topic) {
            const finalized = message.data;
            console.log(
                `Finalized: height=${
                    BigInt(finalized.height).toLocaleString()}` +
                ` hash=${finalized.hash.substring(0, 16)}...`);
        }
    });

 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
    // Handle incoming messages
    @OnMessage
    public void onMessage(final String payload) throws IOException {
        final JsonNode message = JSON_MAPPER.readTree(payload);

        // Special case for the initial handshake message
        if (message.has("uid")) {
            uidFuture.complete(message.get("uid").asText());
            return;
        }

        final String topic = message.get("topic").asText();

        if ("block".equals(topic)) {
            final JsonNode block = message.get("data").get("block");
            final JsonNode blockMeta = message.get("data").get("meta");
            System.out.printf("New block: height=%,d hash=%s...%n",
                block.get("height").asLong(),
                blockMeta.get("hash").asText().substring(0, 16));
        }

        if ("finalizedBlock".equals(topic)) {
            final JsonNode finalized = message.get("data");
            System.out.printf("Finalized: height=%,d hash=%s...%n",
                finalized.get("height").asLong(),
                finalized.get("hash").asText().substring(0, 16));
        }
    }

The code listens for incoming messages until the program is interrupted. Each message includes a topic field identifying the channel and a data object with the event payload.

For block messages, the payload follows the BlockInfoDTO schema. This tutorial uses two of them to identify each block:

  • data.block.height: The height of the new block.
  • data.meta.hash: The hash of the new block.

For finalizedBlock messages, the payload follows the FinalizedBlockDTO schema. This tutorial uses:

  • data.height: The finalized block height.
  • data.hash: The hash of the finalized block.

The chain height increases each time a new block is produced. The finalized height lags behind the chain tip because finalization typically occurs 10 to 20 minutes after block production.

See the Consensus section in the textbook for details on how voting nodes drive this process.

Unsubscribing on Exit⚓︎

50
51
52
53
54
55
56
        # Unsubscribe on exit
        finally:
            await websocket.send(json.dumps(
                {'uid': uid, 'unsubscribe': 'block'}))
            await websocket.send(json.dumps(
                {'uid': uid, 'unsubscribe': 'finalizedBlock'}))
            print('Unsubscribed from all channels')

49
50
51
52
53
54
55
56
57
    // Unsubscribe on exit
    process.on('SIGINT', () => {
        websocket.send(JSON.stringify({ uid, unsubscribe: 'block' }));
        websocket.send(
            JSON.stringify({ uid, unsubscribe: 'finalizedBlock' }));
        console.log('Unsubscribed from all channels');
        websocket.close();
        process.exit(0);
    });

67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
        // Unsubscribe on exit
        Runtime.getRuntime().addShutdownHook(new Thread(() -> {
            try {
                remote.sendText(JSON_MAPPER.createObjectNode()
                    .put("uid", uid).put("unsubscribe", "block")
                    .toString());
                remote.sendText(JSON_MAPPER.createObjectNode()
                    .put("uid", uid).put("unsubscribe", "finalizedBlock")
                    .toString());
                System.out.println("Unsubscribed from all channels");
                session.close();
            } catch (final IOException ex) {
                throw new IllegalStateException(ex);
            }
        }));

When the program is interrupted (Ctrl+C), the code sends unsubscribe messages for both channels before closing the connection. This ensures a clean disconnection from the node.

Output⚓︎

The following output shows a typical run listening to new blocks and finalization events:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
Using node https://reference.symboltest.net:3001
Connected to wss://reference.symboltest.net:3001/ws with uid 9AQEv+DFuCuddfrJlNh7ERf8Zlg=
Subscribed to block channel
Subscribed to finalizedBlock channel
New block: height=3,176,948 hash=EDD1ED4C92E29655...
New block: height=3,176,949 hash=18DBF7E75B2CC003...
New block: height=3,176,950 hash=A3409E1951E8FC8C...
Finalized: height=3,176,948 hash=EDD1ED4C92E29655...
New block: height=3,176,951 hash=A7D80AFD75C4C918...
New block: height=3,176,952 hash=027D939F6E9D0DAE...
Unsubscribed from all channels

The output shows:

  • Connection (line 2): The WebSocket connection is established to the wss:// URL and the server returns a unique uid.
  • Subscriptions (lines 3-4): Both the block and finalizedBlock channels are subscribed.
  • New blocks (lines 5-7, 9-10): New block notifications arrive approximately every 30 seconds.
  • Finalization (line 8): A finalization notification arrives when a finalization round completes, covering multiple blocks at once.
  • Unsubscribe (line 11): On Ctrl+C, the code unsubscribes from both channels.

Conclusion⚓︎

This tutorial showed how to:

Step Related documentation
Subscribe to block channel block WS
Subscribe to finalized channel finalizedBlock WS
Handle block messages BlockInfoDTO
Handle finalized messages FinalizedBlockDTO