6.7.1 DGT Topology

Section 6.2 dealt with the installation of a single node. Each node is a set of services that interact with each other and are responsible for organizing the network, storing data, and processing transactions. Even a single node provides a significant service that supports client applications via an API (see section 3.9). At the same time, several the platform’s network capabilities can only be used if there are several nodes. A detailed overview of DGT networking features is provided in section 1.4, while below is a description of the practical setup of the DGT network. Basic concepts of topology include:

  • Node: an independent unit of the network, a set of services that support the functionality of the platform.

  • Cluster: a group of nodes that jointly process transactions. In the DGT network, all nodes are included in a certain cluster. One node cannot belong to two clusters simultaneously.

  • Node role: each cluster is supported by a variable leader (Leader role) that changes according to a certain rule. The nodes in the cluster perform the transaction validation (the roles of Peer, Validator). Outside the cluster, transactions are additionally checked by nodes of a special time – an Arbitrator. There are also other roles (see section 3.4).

  • The initial joining of a node to the network is done through a special node-gateway that performs the initial touring of messages.

  • The DGT network may contain additional divisions in terms of access. Such a division is organized into network segments, which may have limited access (closed or private segments) and free access (open, public segment). Only one public segment is allowed within the DGT network. Each cluster belongs to one and only one segment. The different between closed and open segments is in different access method: a closed segment requires certificate verification and an access point (cell), while the open segment uses a dynamic topology with random access to clusters.

  • To manage the level of trust, there are various mechanisms for monitoring the integrity of the network: signatures for topological transactions (verifies the public-private key pair), X.509 certificate mechanism, or the formation of a trusted seed-network. Seed-network is an initial set of nodes which can interact without the use of certificates. It is assumed that this initial configuration is provided by a trust contour (see 6.7.1.1.)

  • Expanding the network beyond the seed-network is carried out by connecting nodes to cells – reserved topological coordinates (cluster number / node number). Such cells are described in the preliminary system settings (see 6.7.1.1).

The DGT network configuration is described through one of the two notations:

  • System notation (node coordinates, metric notation): cluster number and node number. For example, the 1st node represented in the 1st cluster gets the name c1-1. Such a system does not take access segments into account, but has simple node addressing and is convenient for use in assembly commands.

  • Extended notation (mnemonic notation), which uses the following rules:

    • Network segments are denoted by capital letters: A (seed-network), B, C, D… Only one of these segments may be public.

    • Clusters are denoted by two small Latin letters, the first of which corresponds to the segment, the second to the cluster number, for example: aa, ab, …, bc, bd, be, …, da, db, …

    • Nodes are identified by name of the cluster with an additional numerical index, for example aa1, aa2, ab2, ab2

System notation is convenient when working with small or quasi-homogeneous networks. Large public access networks may accept mnemonic notation. Within the system, it is described by the JSON-specification «etc/dgt.net.static» The notation mapping is set in the «etc/dgt.net.map» JSON configuration file, see 6.7.1.1. Basic rules for describing network objects include:

  • Network objects accept types: NODE, CLUSTER, SEGMENT, MAP

  • Objects form a single hierarchy (tree), which describes each of the objects with its own attributes. The CLUSTER object contains a list of nodes located in the children list. The top-level object “genesis” is an abstract object that contains other objects. Clusters are attached to certain nodes that are the gateways into the network.

  • CLUSTER object attributes include:

    o name (reference to gateway system name, for example, Dgt4),

    o type (cluster),

    o segment (cluster name in mnemonic notation, for example, AE),

    o children (a set of node objects, each of which has a name in notation ae1, ae2, …),

    o maxpeer (optional attribute that limits the number of nodes in the cluster)

    o public (optional attribute. If present and set to true, the cluster supports the dynamic topology that is typical for open/public segments).

  • NODE object attributes include:

    o name (node name, usually related to system notation, e.g. 11)

    o type (peer): selects objects of type node

    o role (the role of the node, in the current version it can take the values of leader that coordinates the cluster and plink which is the validator)

    o genesis (optional attribute, present only for the first node in the network and taking the value of true)

    o delegate (optional attribute, a market for the node that acts as an arbitrator)

  • SEGMENT attributes include:

    o NETWORK_WIDTH – the number of clusters in the segment allowed at any one level

    o NETWORK_HEIGHT – the number of clusters allowed in any one segment in depth

    o NETWORK_ROLES – allowed roles

    o NETWORK_CA – requirement for valid certificates to join the segment (mode=true).

  • Attributes of the MAP object (not used, the map is moved to a separate specification of dgt.net.map type)

The platform works with topology descriptions in JSON format, which can be parsed in any suitable editor (we recommend using MiTec Json Viewer for viewing):

Designing the network topology is a time-consuming process that requires significant efforts in defining parameters and dependencies between network objects. In most cases, you can use ready-made network templates (see 6.7.1.1). For a short form text description, the following format can be used:

• Segment A:

o AA [# ] {aa1 [G L A],aa2,aa3,aa4,aa5,aa6}

o AB [#aa1 P M8] {ab1 [L A], ab2,ab3, ab4,ab5,ab6}

o AC [#ab1] {ac1 [L A], ac2,ac3, ac4,ac5,ac6}

o AD [#aa3] {ad1 [L A], ad2, ad3, ad4, ad5, ad6}

o AE [#aa2] {ae1 [L A], ae2,ae3, ae4,ae5,ae6}

• Segment B:

o BA [#aa4] {ba1 [L A], ba2, ba3, ba4,ba5, ba6}

TOTAL: 36 Nodes, 6 Clusters, 2 Segments

SEED: {aa1 (c1-1), aa2 (c1-2), aa3 (c1-3), ab1 (c2-1)}

Here:

- Segments are listed in the header before the list of clusters

- Clusters are described in mnemonic notation (AA,…) and the square brackets contain their attributes: #aa1 is a gateway for connecting the cluster, P is a cluster publicity flag, M8 is the maxpeers parameter, which overrides the default settings for the number of nodes in the cluster (see 6.7.1.1)

- Round brackets list the nodes. If a node has non-standard attributes, they are placed in square brackets: G is a genesis flag available only for the first node, L is for leader, A is for arbitrator (delegate=true)

- TOTAL states the number of nodes and segments

- SEED lists the nodes for a static core (the seed-network)

6.7.1.1 DGT Topology Settings

Topological settings are set in the following files located in the “etc” working directory of the current version of DGT (ex. DGT-Matagami/CORE/etc): «dgt.net.static», «dgt.net.dyn» and «dgt.net.map». When deploying a node or cluster, the corresponding container copies the data files for cluster n and node m to the directory «dgt_clust/c_n/dgt_m» (ex. DGT-Matagami/dgt_clust/c1/dgt1).

  • The «dgt.net.static» file contains a description of the topology (reserved cells of private segments in JSON format – a hierarchy of network objects):

#

Network Objects

Attributes

Sample

1

SEGMENT

NAME – segment name in mnemonic notation

NETWORK_WIDTH – (maximum) allowed width of cluster expressed in number of nodes

NETWORK_HEIGHT – (maximum) allowed depth of cluster expressed in number of nodes

NETWORK_ROLES – allowed roles in the cluster (optional)

NETWORK_CA – certificate requirements

2

CLUSTER

NAME – cluster name

PUBLIC – public if true

MAXPEER – maximum number of nodes in a cluster

TYPE – object type (default: cluster)

CHILDREN – component nodes

SEGMENT – parent segment

3

NODE

NAME – name in coordinate notation and in mnemonic notation

ROLE – node role, e.g. leader, plink (validator)

Type: peer (by default)

DELEGATE

  • The «dgt.net.map» file contains the rules for matching the coordinates of the node and the selected notation (for example, mnemonic), as well as a description of the seed-network:

    - Description of clusters in different notations, for example: «c2:{“dgt1”:”AB.ab1”,”dgt2”:AB.ab2}»;

    - Parameter «static_map» representing dedicated seed-network nodes (static core):

  • The «dgt.net.dyn» file defines the typical dynamic topology for nodes joining public segments. Attributes similar to «dgt.net.static» are used.

  • A typical configuration can be replaced with pre-made templates:

#

Configuration

Topology

How to use

1

dgt.net.static

dgt.net.map

• Segment A:

o AA [# ] {aa1 [G L A],aa2,aa3,aa4,aa5,aa6}

o AB [#aa1 P M8] {ab1 [L A], ab2,ab3, ab4,ab5,ab6}

o AC [#ab1] {ac1 [L A], ac2,ac3, ac4,ac5,ac6}

o AD [#aa3] {ad1 [L A], ad2, ad3, ad4, ad5, ad6}

o AE [#aa2] {ae1 [L A], ae2,ae3, ae4,ae5,ae6}

• Segment B:

o BA [#aa4] {ba1 [L A], ba2, ba3, ba4,ba5, ba6}

TOTAL: 36 Nodes, 6 Clusters, 2 Segments

SEED: {aa1 (c1-1), aa2 (c1-2), aa3 (c1-3), ab1 (c2-1)}

Set by default. Change if necessary:

• Edit before launch («nano dgt.net.static»)

• Replace with examples example12 and example36 – see below

2

dgt.net.static.example12

dgt.net.map.example12

• Segment A:

o AA [#] {aa1 [G L A],aa2,aa3,aa4

o AB [#aa1 P M8] {ab1 [L A], ab2,ab3, ab4 }

o AC [#ab1] {ac1 [L A], ac2,ac3, ac4}

TOTAL: 12 Nodes, 3 Clusters, 1 Segments

SEED: {aa1(c1-1), aa2(c1-2), aa3(c1-3), aa4(c1-4), ab1(c2-1), ac1(c3-1)}

Execute commands:

• cp -i dgt.net.static dgt.net.static.back

• cp -i dgt.net.map dgt.net.map.back

• cp -i dgt.net.static.example12 dgt.net.static

• cp -i dgt.net.map.example12 dgt.net.map

3

dgt.net.static.example36

dgt.net.map.example36

• Segment A:

o AA [# ] {aa1 [G L A],aa2,aa3,aa4,aa5,aa6}

o AB [#aa1 P M8] {ab1 [L A], ab2,ab3, ab4,ab5,ab6}

o AC [#ab1] {ac1 [L A], ac2,ac3, ac4,ac5,ac6}

o AD [#aa3] {ad1 [L A], ad2, ad3, ad4, ad5, ad6}

o AE [#aa2] {ae1 [L A], ae2,ae3, ae4,ae5,ae6}

• Segment B:

o BA [#aa4] {ba1 [L A], ba2, ba3, ba4,ba5, ba6}

TOTAL: 36 Nodes, 6 Clusters, 2 Segments

SEED: {aa1 (c1-1), aa2 (c1-2), aa3 (c1-3), ab1 (c2-1)}

Represents a copy of option #1, use if you need to replace a modified option #1 to return to the default option. Run commands:

• cp -i dgt.net.static dgt.net.static.back

• cp -i dgt.net.map dgt.net.map.back

• cp -i dgt.net.static.example36 dgt.net.static

• cp -i dgt.net.map.example36 dgt.net.map

  • If you need to change the topology, follow this algorithm:

    - Changing the topology requires a network restart (hard fork). Change the configuration prior to commercial exploitation of the network.

    - Save a backup copy of the dgt configuration files: dgt.net.static and dgt.net.map (copy with the .back extension).

    - Select the main network parameters: number of nodes, number of clusters, clusters with limits on the number of nodes, gateways for each of the clusters (connection points), initial leaders in each cluster, the number of arbitrators, clusters with public access.

    - Prepare a draft specification in mnemonic notation.

    - Open the previously saved dgt.net.static.back specification (for example, in Notepad++, Visual Studio Code or the online jsoneditoronle), edit it and save it with the desired name.

    - Open the dgt.net.map specification and enter the rules for correlating the mnemonic notation and system coordinates; describe the nodes included into the static core of the network (seed-network) and save under a new name.

    - Copy into the «DGT-Matagami/CORE/etc» directory and replace using the «cp» operation.

6.7.1.2 Port Configuration

Section 6.2.3 describes ports for a single node. Each DGT node is represented by a set of services that support the operation of the node:

#

VIRTUAL SERVICE

DESCRIPTION

DEFAULT PORT

1

NET

Support for low-level communication between nodes. This service supports direct work with ZMQ. The port must be open for the node to communicate with the network.

8800

2

CONS

Consensus support service. Has an inner meaning (Inner-Net)

5005

3

COMP

The REST-API transaction processor support service (from internal network), has an internal meaning (Inner-Net)

4004

4

API

Represents the node’s API accessed by other components, such as CLI, DASHBOARD, external applications. The port must be open when there are external applications.

8008

These ports can be overridden for a given node (such that each port works with its own set of ports). This port redefinition is necessary when launching a virtual cluster, the nodes share a single IP and the corresponding ports should not conflict. The bash batch file «upDgtUpCluster.sh» sets default ports according to cluster number and node number:

#

Cluster

Node

NET

CONS

COMP

API

Description

1

1

1

8101

5051

4104

8108

Part of the seed-network by default

2

1

2

8102

5052

4106

8109

3

1

3

8103

5053

4107

8110

4

1

4

8104

5054

4108

8111

5

1

5

8105

5055

4109

8112

6

1

6

8106

5056

4110

8113

7

2

1

8201

5251

4204

8208

Part of the seed-network by default

8

2

2

8202

5252

4206

8209

9

2

3

8203

5253

4207

8210

10

3

1

8301

5351

4304

8308

11

3

2

8302

5352

4306

8309

12

3

3

8303

5353

4307

8310

13

4

1

8401

5451

4404

8408

14

4

2

8402

5452

4406

8409

15

4

3

8403

5453

4407

8410

16

5

1

8501

5551

4504

8508

17

5

2

8502

5552

4506

8509

18

5

3

8503

5553

4507

8510

19

6

1

8601

5651

4604

8608

20

6

2

8602

5652

4606

8609

21

6

3

8603

5653

4607

8610

Notes:

- Real ports are used only for a static kernel, for example, to run a virtual cluster (see 6.3.2);

- When launching an external node, the NET service port can be overridden with the -P key (see 6.3.3.2)

Previous6.7 Adjust DGT settingsNext6.7.2 Manage local settings

Last updated