Skip to content

Querying Chain and Finalization Height⚓︎

BEGINNER

The /chain/info GET endpoint returns the current chain height and the latest finalization height. Comparing both values shows how far behind the finalized state is from the chain tip, which is useful for applications that need to confirm transactions are irreversible.

This tutorial shows how to poll chain state in a loop and display how long ago each height last changed.

Prerequisites⚓︎

This tutorial uses the Symbol REST API without requiring an SDK. You only need a way to make HTTP requests.

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
import json
import os
import time
import urllib.request

NODE_URL = os.getenv('NODE_URL', 'https://reference.symboltest.net:3001')
print(f'Using node {NODE_URL}')

prev_height = None
prev_finalized_height = None
height_changed_at = None
finalized_changed_at = None

try:
    while True:
        with urllib.request.urlopen(
            f'{NODE_URL}/chain/info') as response:
            chain_info = json.loads(response.read().decode())

        height = int(chain_info['height'])
        finalized = chain_info['latestFinalizedBlock']
        finalized_height = int(finalized['height'])

        now = time.time()

        if prev_height is not None and height != prev_height:
            height_changed_at = now
        if (
            prev_finalized_height is not None
            and finalized_height != prev_finalized_height
        ):
            finalized_changed_at = now

        if height_changed_at is not None:
            height_ago = f'{int(now - height_changed_at)}s ago'
        else:
            height_ago = '-'
        if finalized_changed_at is not None:
            finalized_ago = f'{int(now - finalized_changed_at)}s ago'
        else:
            finalized_ago = '-'

        print(
            f'Height: {height:>10,}'
            f'  (changed {height_ago})'
            f'  |  Finalized: {finalized_height:>10,}'
            f'  (changed {finalized_ago})'
        )

        prev_height = height
        prev_finalized_height = finalized_height
        time.sleep(1)

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
const NODE_URL = process.env.NODE_URL ||
    'https://reference.symboltest.net:3001';
console.log(`Using node ${NODE_URL}`);

let prevHeight = null;
let prevFinalizedHeight = null;
let heightChangedAt = null;
let finalizedChangedAt = null;

for (;;) {
    const response = await fetch(`${NODE_URL}/chain/info`);
    if (!response.ok)
        throw new Error(`HTTP error! status: ${response.status}`);

    const chainInfo = await response.json();

    const height = BigInt(chainInfo.height);
    const finalized = chainInfo.latestFinalizedBlock;
    const finalizedHeight = BigInt(finalized.height);

    const now = Date.now();

    if (null !== prevHeight && height !== prevHeight)
        heightChangedAt = now;
    if (null !== prevFinalizedHeight &&
        finalizedHeight !== prevFinalizedHeight)
        finalizedChangedAt = now;

    const heightAgo = null !== heightChangedAt ?
        `${Math.floor((now - heightChangedAt) / 1000)}s ago` :
        '-';
    const finalizedAgo = null !== finalizedChangedAt ?
        `${Math.floor((now - finalizedChangedAt) / 1000)}s ago` :
        '-';

    const heightLabel = height.toLocaleString().padStart(10);
    const finalizedHeightLabel =
        finalizedHeight.toLocaleString().padStart(10);
    console.log(
        `Height: ${heightLabel}  (changed ${heightAgo})` +
        `  |  Finalized: ${finalizedHeightLabel}` +
        `  (changed ${finalizedAgo})`
    );

    prevHeight = height;
    prevFinalizedHeight = finalizedHeight;
    await new Promise(resolve => { setTimeout(resolve, 1000); });
}

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
//JAVA 21+
//DEPS org.symbol:symbol-sdk:3.3.1

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

public final class ChainHeights {
    private static final ObjectMapper JSON_MAPPER = new ObjectMapper();

    private static final HttpClient HTTP_CLIENT =
        HttpClient.newHttpClient();

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

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

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

        Long prevHeight = null;
        Long prevFinalizedHeight = null;
        Long heightChangedAt = null;
        Long finalizedChangedAt = null;

        while (true) {

            final HttpRequest request = HttpRequest.newBuilder(
                URI.create(nodeUrl + "/chain/info")).GET().build();
            final HttpResponse<String> response = HTTP_CLIENT.send(
                request, BodyHandlers.ofString());
            final JsonNode chainInfo = JSON_MAPPER.readTree(
                response.body());

            final long height = chainInfo.get("height").asLong();
            final JsonNode finalized =
                chainInfo.get("latestFinalizedBlock");
            final long finalizedHeight =
                finalized.get("height").asLong();

            final long now = System.currentTimeMillis();

            if (null != prevHeight && height != prevHeight)
                heightChangedAt = now;
            if (null != prevFinalizedHeight
                && finalizedHeight != prevFinalizedHeight)
                finalizedChangedAt = now;

            final String heightAgo = null != heightChangedAt
                ? "%ds ago".formatted((now - heightChangedAt) / 1000)
                : "-";
            final String finalizedAgo = null != finalizedChangedAt
                ? "%ds ago".formatted((now - finalizedChangedAt) / 1000)
                : "-";

            System.out.printf(
                "Height: %,10d  (changed %s)"
                    + "  |  Finalized: %,10d  (changed %s)%n",
                height, heightAgo, finalizedHeight, finalizedAgo);

            prevHeight = height;
            prevFinalizedHeight = finalizedHeight;
            Thread.sleep(1000);

        }
    }
}

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 program runs in an infinite loop, printing a status line every second. A keyboard interrupt (Ctrl+C) stops the loop.

Code Explanation⚓︎

Fetching Chain Information⚓︎

16
17
18
19
20
21
22
        with urllib.request.urlopen(
            f'{NODE_URL}/chain/info') as response:
            chain_info = json.loads(response.read().decode())

        height = int(chain_info['height'])
        finalized = chain_info['latestFinalizedBlock']
        finalized_height = int(finalized['height'])

11
12
13
14
15
16
17
18
19
    const response = await fetch(`${NODE_URL}/chain/info`);
    if (!response.ok)
        throw new Error(`HTTP error! status: ${response.status}`);

    const chainInfo = await response.json();

    const height = BigInt(chainInfo.height);
    const finalized = chainInfo.latestFinalizedBlock;
    const finalizedHeight = BigInt(finalized.height);

43
44
45
46
47
48
49
50
51
52
53
54
            final HttpRequest request = HttpRequest.newBuilder(
                URI.create(nodeUrl + "/chain/info")).GET().build();
            final HttpResponse<String> response = HTTP_CLIENT.send(
                request, BodyHandlers.ofString());
            final JsonNode chainInfo = JSON_MAPPER.readTree(
                response.body());

            final long height = chainInfo.get("height").asLong();
            final JsonNode finalized =
                chainInfo.get("latestFinalizedBlock");
            final long finalizedHeight =
                finalized.get("height").asLong();

On each iteration, the code sends a GET request to the /chain/info GET endpoint. The response contains:

  • height: The current chain height (the latest block known to the node).
  • latestFinalizedBlock: An object with details about the most recently finalized block, including:
    • height: The finalized block height.
    • finalizationEpoch: The finalization epoch number.
    • finalizationPoint: The finalization point within the epoch.

    • hash: The hash of the finalized block.

      Prove That the Block Is Part of the Blockchain

      Finalization only proves that the network has agreed on a specific block hash. To fully verify finality, it should also be checked that this hash actually belongs to the current blockchain.

      This can be done by retrieving blocks around the reported finalized height and confirming that one of them contains the finalized hash in its header.

The chain height increases each time a new block is produced (approximately every 30 seconds).

The finalized height lags behind the chain tip because a block is typically finalized 10 to 20 minutes after it is produced. When a finalization round completes, the finalized height jumps forward by many blocks at once rather than advancing one block at a time. See the Consensus textbook section for details on how voting nodes drive this process.

Tracking Height Changes⚓︎

26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
        if prev_height is not None and height != prev_height:
            height_changed_at = now
        if (
            prev_finalized_height is not None
            and finalized_height != prev_finalized_height
        ):
            finalized_changed_at = now

        if height_changed_at is not None:
            height_ago = f'{int(now - height_changed_at)}s ago'
        else:
            height_ago = '-'
        if finalized_changed_at is not None:
            finalized_ago = f'{int(now - finalized_changed_at)}s ago'
        else:
            finalized_ago = '-'

23
24
25
26
27
28
29
30
31
32
33
34
    if (null !== prevHeight && height !== prevHeight)
        heightChangedAt = now;
    if (null !== prevFinalizedHeight &&
        finalizedHeight !== prevFinalizedHeight)
        finalizedChangedAt = now;

    const heightAgo = null !== heightChangedAt ?
        `${Math.floor((now - heightChangedAt) / 1000)}s ago` :
        '-';
    const finalizedAgo = null !== finalizedChangedAt ?
        `${Math.floor((now - finalizedChangedAt) / 1000)}s ago` :
        '-';

58
59
60
61
62
63
64
65
66
67
68
69
            if (null != prevHeight && height != prevHeight)
                heightChangedAt = now;
            if (null != prevFinalizedHeight
                && finalizedHeight != prevFinalizedHeight)
                finalizedChangedAt = now;

            final String heightAgo = null != heightChangedAt
                ? "%ds ago".formatted((now - heightChangedAt) / 1000)
                : "-";
            final String finalizedAgo = null != finalizedChangedAt
                ? "%ds ago".formatted((now - finalizedChangedAt) / 1000)
                : "-";

To show how long ago each height last changed, the code stores the previous values and their timestamps. When a height differs from the previous value, the timestamp is updated to the current time.

Until a change is observed, the timestamp remains unset and the output displays - instead of a number. Once a change occurs, the counter starts from 0s ago and increments each second until the next change.

Polling Loop⚓︎

43
44
45
46
47
48
49
50
51
52
        print(
            f'Height: {height:>10,}'
            f'  (changed {height_ago})'
            f'  |  Finalized: {finalized_height:>10,}'
            f'  (changed {finalized_ago})'
        )

        prev_height = height
        prev_finalized_height = finalized_height
        time.sleep(1)

36
37
38
39
40
41
42
43
44
45
46
47
    const heightLabel = height.toLocaleString().padStart(10);
    const finalizedHeightLabel =
        finalizedHeight.toLocaleString().padStart(10);
    console.log(
        `Height: ${heightLabel}  (changed ${heightAgo})` +
        `  |  Finalized: ${finalizedHeightLabel}` +
        `  (changed ${finalizedAgo})`
    );

    prevHeight = height;
    prevFinalizedHeight = finalizedHeight;
    await new Promise(resolve => { setTimeout(resolve, 1000); });

71
72
73
74
75
76
77
78
            System.out.printf(
                "Height: %,10d  (changed %s)"
                    + "  |  Finalized: %,10d  (changed %s)%n",
                height, heightAgo, finalizedHeight, finalizedAgo);

            prevHeight = height;
            prevFinalizedHeight = finalizedHeight;
            Thread.sleep(1000);

Each iteration prints a single status line showing:

  • The current chain height and how many seconds have elapsed since it last changed.
  • The finalized height and how many seconds have elapsed since it last changed.

The loop then sleeps for one second between iterations.

Output⚓︎

The following output shows a typical run monitoring the chain and finalization heights:

1
2
3
4
5
6
7
8
Using node https://reference.symboltest.net:3001
Height:  3,159,411  (changed -)  |  Finalized:  3,159,388  (changed -)
Height:  3,159,411  (changed -)  |  Finalized:  3,159,388  (changed -)
Height:  3,159,411  (changed -)  |  Finalized:  3,159,388  (changed -)
Height:  3,159,412  (changed 0s ago)  |  Finalized:  3,159,388  (changed -)
Height:  3,159,412  (changed 1s ago)  |  Finalized:  3,159,388  (changed -)
Height:  3,159,412  (changed 2s ago)  |  Finalized:  3,159,411  (changed 0s ago)
Height:  3,159,412  (changed 3s ago)  |  Finalized:  3,159,411  (changed 1s ago)

Some highlights from the output:

  • Before any change (lines 2-4): Both counters show - because no change has been observed yet.

  • A new block confirms (line 5): The chain height advances from 3,159,411 to 3,159,412 and its change counter starts from 0s.

  • A finalization round completes (line 7): The finalized height jumps 23 blocks from 3,159,388 to 3,159,411, and its change counter starts from 0s.

The gap between the chain height and the finalized height is normal. A transaction included in a block at the chain tip is confirmed but not yet irreversible. Once the finalized height reaches or exceeds that block, the transaction is guaranteed to remain in the chain.

Conclusion⚓︎

This tutorial showed how to:

Step Related documentation
Fetch chain information /chain/info GET

Next steps⚓︎

For an event-driven approach to monitoring new blocks and finalization, see the Listening to New Blocks WebSocket tutorial.