Skip to content

Network Time⚓︎

BEGINNER

Time in the Symbol blockchain is measured in network time, defined as the number of milliseconds elapsed since the chain's first block.

This quick tutorial shows how to convert the network time returned by API calls to standard timestamps like UTC.

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

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

try:
    # Fetch Nemesis timestamp
    properties_path = '/network/properties'
    print(f'Fetching network properties from {properties_path}')
    with urllib.request.urlopen(
        f'{NODE_URL}{properties_path}') as response:
        response_json = json.loads(response.read().decode())
        nemesis_datetime = datetime.datetime.fromtimestamp(
            int(response_json['network']['epochAdjustment'].rstrip('s')),
            tz=datetime.timezone.utc)

    # Fetch current network timestamp
    time_path = '/node/time'
    print(f'Fetching current network time from {time_path}')
    with urllib.request.urlopen(f'{NODE_URL}{time_path}') as response:
        response_json = json.loads(response.read().decode())
        network_ms = int(
            response_json['communicationTimestamps']['receiveTimestamp'])

    network_datetime = nemesis_datetime + datetime.timedelta(
        milliseconds=network_ms)

    print(f'\nNemesis time (UTC): {nemesis_datetime}')
    print(f'Network time (ms since Nemesis): {network_ms}')
    print(f'Network time (UTC): {network_datetime}')
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
const NODE_URL = process.env.NODE_URL ||
    'https://whydah.symbolmain.net:3001';
console.log(`Using node ${NODE_URL}`);

try {
    // Fetch Nemesis timestamp
    const propertiesPath = '/network/properties';
    console.log(`Fetching network properties from ${propertiesPath}`);
    const propertiesResponse =
        await fetch(`${NODE_URL}${propertiesPath}`);
    const propertiesJson = await propertiesResponse.json();
    const nemesisStr = propertiesJson.network.epochAdjustment;
    const nemesisSeconds = parseInt(nemesisStr.replace('s', ''), 10);
    const nemesisDatetime = new Date(nemesisSeconds * 1000);

    // Fetch current network timestamp
    const timePath = '/node/time';
    console.log(`Fetching current network time from ${timePath}`);
    const timeResponse = await fetch(`${NODE_URL}${timePath}`);
    const timeJson = await timeResponse.json();
    const networkMs = BigInt(
        timeJson.communicationTimestamps.receiveTimestamp);

    const networkDatetime = new Date(
        nemesisDatetime.getTime() + Number(networkMs));

    console.log(
        `\nNemesis time (UTC): ${nemesisDatetime.toISOString()}`);
    console.log(`Network time (ms since Nemesis): ${networkMs}`);
    console.log(`Network time (UTC): ${networkDatetime.toISOString()}`);
} catch (error) {
    console.error(`Error: ${error.message}`);
}

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
//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 java.time.Instant;

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

public final class NetworkTime {
    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://whydah.symbolmain.net:3001");

    public static void main(final String[] args) {
        try {
            new NetworkTime().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);

        // Fetch Nemesis timestamp
        final String propertiesPath = "/network/properties";
        System.out.printf(
            "Fetching network properties from %s%n", propertiesPath);
        final HttpRequest propertiesRequest = HttpRequest.newBuilder(
            URI.create(nodeUrl + propertiesPath)).GET().build();
        final HttpResponse<String> propertiesResponse =
            HTTP_CLIENT.send(
                propertiesRequest, BodyHandlers.ofString());
        final JsonNode propertiesJson = JSON_MAPPER.readTree(
            propertiesResponse.body());
        final String nemesisStr = propertiesJson.get("network")
            .get("epochAdjustment").asText();
        final long nemesisSeconds =
            Long.parseLong(nemesisStr.replace("s", ""));
        final Instant nemesisDatetime =
            Instant.ofEpochSecond(nemesisSeconds);

        // Fetch current network timestamp
        final String timePath = "/node/time";
        System.out.printf(
            "Fetching current network time from %s%n", timePath);
        final HttpRequest timeRequest = HttpRequest.newBuilder(
            URI.create(nodeUrl + timePath)).GET().build();
        final HttpResponse<String> timeResponse = HTTP_CLIENT.send(
            timeRequest, BodyHandlers.ofString());
        final JsonNode timeJson = JSON_MAPPER.readTree(
            timeResponse.body());
        final long networkMs = timeJson
            .get("communicationTimestamps")
            .get("receiveTimestamp").asLong();

        final Instant networkDatetime =
            nemesisDatetime.plusMillis(networkMs);

        System.out.printf("%nNemesis time (UTC): %s%n",
            nemesisDatetime);
        System.out.printf("Network time (ms since Nemesis): %d%n",
            networkMs);
        System.out.printf("Network time (UTC): %s%n",
            networkDatetime);
    }
}

Download source

Code Explanation⚓︎

The code retrieves the Nemesis block timestamp and the current network time. Then it adds them together to obtain the current time in standard UTC.

Fetch Nemesis Timestamp⚓︎

11
12
13
14
15
16
17
18
    properties_path = '/network/properties'
    print(f'Fetching network properties from {properties_path}')
    with urllib.request.urlopen(
        f'{NODE_URL}{properties_path}') as response:
        response_json = json.loads(response.read().decode())
        nemesis_datetime = datetime.datetime.fromtimestamp(
            int(response_json['network']['epochAdjustment'].rstrip('s')),
            tz=datetime.timezone.utc)

 7
 8
 9
10
11
12
13
14
    const propertiesPath = '/network/properties';
    console.log(`Fetching network properties from ${propertiesPath}`);
    const propertiesResponse =
        await fetch(`${NODE_URL}${propertiesPath}`);
    const propertiesJson = await propertiesResponse.json();
    const nemesisStr = propertiesJson.network.epochAdjustment;
    const nemesisSeconds = parseInt(nemesisStr.replace('s', ''), 10);
    const nemesisDatetime = new Date(nemesisSeconds * 1000);

38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
        final String propertiesPath = "/network/properties";
        System.out.printf(
            "Fetching network properties from %s%n", propertiesPath);
        final HttpRequest propertiesRequest = HttpRequest.newBuilder(
            URI.create(nodeUrl + propertiesPath)).GET().build();
        final HttpResponse<String> propertiesResponse =
            HTTP_CLIENT.send(
                propertiesRequest, BodyHandlers.ofString());
        final JsonNode propertiesJson = JSON_MAPPER.readTree(
            propertiesResponse.body());
        final String nemesisStr = propertiesJson.get("network")
            .get("epochAdjustment").asText();
        final long nemesisSeconds =
            Long.parseLong(nemesisStr.replace("s", ""));
        final Instant nemesisDatetime =
            Instant.ofEpochSecond(nemesisSeconds);

The Nemesis block creation time is a fixed network property and can be retrieved using the /network/properties GET endpoint. The returned value (epochAdjustment), after removing the s suffix and converting it to an integer, is a UNIX timestamp. That is, the number of non-leap seconds that have elapsed since the Unix epoch (00:00:00 UTC on 1 January 1970).

This tutorial retrieves it from the network for illustration purposes, but this is a fixed value and can be treated as a constant and hardcoded if desired. For Symbol's main network, the value is 1615853185 which corresponds to 2021-03-16T00:06:25Z (March 16, 2021 at 12:06:25 AM UTC).

Note that the Symbol protocol and client are open source and can therefore be used to deploy networks other than the Symbol main network. Such networks might use different nemesis creation times or represent time values in different formats.

Fetch Current Network Time⚓︎

21
22
23
24
25
26
    time_path = '/node/time'
    print(f'Fetching current network time from {time_path}')
    with urllib.request.urlopen(f'{NODE_URL}{time_path}') as response:
        response_json = json.loads(response.read().decode())
        network_ms = int(
            response_json['communicationTimestamps']['receiveTimestamp'])

17
18
19
20
21
22
    const timePath = '/node/time';
    console.log(`Fetching current network time from ${timePath}`);
    const timeResponse = await fetch(`${NODE_URL}${timePath}`);
    const timeJson = await timeResponse.json();
    const networkMs = BigInt(
        timeJson.communicationTimestamps.receiveTimestamp);

56
57
58
59
60
61
62
63
64
65
66
67
        final String timePath = "/node/time";
        System.out.printf(
            "Fetching current network time from %s%n", timePath);
        final HttpRequest timeRequest = HttpRequest.newBuilder(
            URI.create(nodeUrl + timePath)).GET().build();
        final HttpResponse<String> timeResponse = HTTP_CLIENT.send(
            timeRequest, BodyHandlers.ofString());
        final JsonNode timeJson = JSON_MAPPER.readTree(
            timeResponse.body());
        final long networkMs = timeJson
            .get("communicationTimestamps")
            .get("receiveTimestamp").asLong();

The current network time, as understood by the queried node, is obtained using the /node/time GET endpoint. Nodes in the network are typically synchronized, so they return similar times.

The actual property queried is communicationTimestamps.receiveTimestamp, which represents the time at which the request was received by the node.

This value is expressed in network time, that is, milliseconds elapsed since the Nemesis block was created.

Conversion⚓︎

The conversion from the current network time to UTC only requires adding the two numbers together, taking care to use consistent units (seconds or milliseconds).

28
29
30
31
32
33
    network_datetime = nemesis_datetime + datetime.timedelta(
        milliseconds=network_ms)

    print(f'\nNemesis time (UTC): {nemesis_datetime}')
    print(f'Network time (ms since Nemesis): {network_ms}')
    print(f'Network time (UTC): {network_datetime}')

24
25
26
27
28
29
30
    const networkDatetime = new Date(
        nemesisDatetime.getTime() + Number(networkMs));

    console.log(
        `\nNemesis time (UTC): ${nemesisDatetime.toISOString()}`);
    console.log(`Network time (ms since Nemesis): ${networkMs}`);
    console.log(`Network time (UTC): ${networkDatetime.toISOString()}`);

69
70
71
72
73
74
75
76
77
        final Instant networkDatetime =
            nemesisDatetime.plusMillis(networkMs);

        System.out.printf("%nNemesis time (UTC): %s%n",
            nemesisDatetime);
        System.out.printf("Network time (ms since Nemesis): %d%n",
            networkMs);
        System.out.printf("Network time (UTC): %s%n",
            networkDatetime);

This tutorial makes the addition manually to show the process. If you are using the Symbol SDK, provides a more convenient abstraction.

Output⚓︎

The output shown below corresponds to a typical run of the program.

1
2
3
4
5
6
7
Using node https://whydah.symbolmain.net:3001
Fetching network properties from /network/properties
Fetching current network time from /node/time

Nemesis time (UTC): 2021-03-16T00:06:25.000Z
Network time (ms since Nemesis): 159102619442
Network time (UTC): 2026-03-31T11:16:44.442Z

Line 5 shows the Nemesis block timestamp, and always displays the same value.

Line 7 shows the current network time converted to UTC.

Conclusion⚓︎

This tutorial showed how to:

Step Related documentation
Obtain the Nemesis timestamp /network/properties GET
Obtain the current network time /node/time GET
Combine both (optional)