6.7.1 DGT Topology
Last updated
Last updated
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
- 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)
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.
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
- 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 )
