_images/network2.png

Networking

Network Topology

A peer to peer network (P2P) is a broadcast system across a network of computers either private or public. In order to discover peers to build the network, every single Uplink client connects to one of several bootnodes. Bootnodes have static IP addresses and are known to all clients. A client connects to a bootnode to gather peer information that are used to connect to other nodes forming the P2P network.

Bootnodes (among other information) are specified in the config file. Among others are the ports to be used for remote procedure calls (RPC) and the port clients use to connect to each other. By standard config, RPC listens on port 8545 while port 8001 is used for peer to peer communication.

_images/Graph.png

FCL Format

The binary encoding for FCL scripts is a typed representation of the abstract syntax tree and the initial memory state storage.:

+-------------------+
| Header            |
+-------------------+
|                   |
| Storage           |
|                   |
+-------------------+
|                   |
| Script            |
|                   |
+-------------------+

It is encoded in binary form on the ledger as the following binary representation of the logical AST tree structure. The maximum size of a contract is a network configurable setting. The preamble is the magic byte sequence:

0x2e 0x46 0x55 0x4e 0x43

The given script:

global int x = 0;

transition initial -> set;
transition set -> terminal;

@set
end () {
  terminate("Bye");
}

@initial
setX () {
  x = 42;
  transitionTo(:set);
}

The binary form of the above contract is:

0000:   2e 46 55 4e  43 00 00 00  00 00 00 00  00 00 00 00   .FUNC...........
0010:   00 00 00 00  01 00 07 00  00 00 00 00  00 00 01 78   ...............x
0020:   01 00 00 00  00 00 00 00  01 00 00 00  00 00 00 00   ................
0030:   10 00 00 00  00 00 00 00  00 00 00 00  00 00 00 00   ................
0040:   00 02 02 00  01 00 00 00  00 00 00 00  03 73 65 74   .............set
0050:   02 01 00 00  00 00 00 00  00 03 73 65  74 03 00 00   ..........set...
0060:   00 00 00 00  00 02 00 00  00 00 00 00  00 00 03 73   ...............s
0070:   65 74 00 00  00 00 00 00  00 03 65 6e  64 00 00 00   et........end...
0080:   00 00 00 00  00 01 00 00  00 00 00 00  00 08 00 00   ................
0090:   00 00 00 00  00 03 0b 00  00 00 00 00  00 00 09 74   ...............t
00a0:   65 72 6d 69  6e 61 74 65  00 00 00 00  00 00 00 01   erminate........
00b0:   01 00 00 00  00 00 00 00  08 00 00 00  00 00 00 00   ................
00c0:   0d 01 01 00  00 00 00 00  00 00 08 00  00 00 00 00   ................
00d0:   00 00 0d 09  00 03 42 79  65 00 00 00  00 00 00 00   ......Bye.......
00e0:   00 07 69 6e  69 74 69 61  6c 00 00 00  00 00 00 00   ..initial.......
00f0:   04 73 65 74  58 00 00 00  00 00 00 00  00 01 00 00   .setX...........
0100:   00 00 00 00  00 0d 00 00  00 00 00 00  00 03 00 01   ................
0110:   00 00 00 00  00 00 00 0d  00 00 00 00  00 00 00 03   ................
0120:   0a 00 00 00  00 00 00 00  01 78 01 00  00 00 00 00   .........x......
0130:   00 00 0d 00  00 00 00 00  00 00 07 01  01 00 00 00   ................
0140:   00 00 00 00  0d 00 00 00  00 00 00 00  07 00 00 00   ................
0150:   00 00 00 00  00 2a 01 00  00 00 00 00  00 00 0e 00   .....*..........
0160:   00 00 00 00  00 00 03 0b  00 00 00 00  00 00 00 0c   ................
0170:   74 72 61 6e  73 69 74 69  6f 6e 54 6f  00 00 00 00   transitionTo....
0180:   00 00 00 01  01 00 00 00  00 00 00 00  0e 00 00 00   ................
0190:   00 00 00 00  10 01 01 00  00 00 00 00  00 00 0e 00   ................
01a0:   00 00 00 00  00 00 10 04  00 00 00 00  00 00 00 03   ................
01b0:   73 65 74                                             set

Network Configuration

The network configuration for Uplink can be found along with the distribution package and is often found at config/node.config. It is structured as a JSON file. When Uplink is started, it will look to find the bootnodes in the corresponding setting in the following table. A flag can be used when starting Uplink to target a custom config file location: uplink chain -c /path/to/custom.config

Config option Description Type Example
port Networking port that will be exposed integer 8001
bootnodes List of bootnodes array of strings [“10.132.0.2:8001”,”10.135.0.3:8001” ]
max-peers Maximmum number of peers that will be allowed (-1 for infinity) integer 210
min-peers Minimum number of peers allowed integer 2
closed Only allow the peers specified in bootnodes boolean false
nonetwork Disable networking boolean false
preallocated Directory containing the preallocated account files string “/config/validators”
access-token Filepath to the network access token (ECDSA private key) string “/config/access-token/key”
transport What transport layer should be used string “tcp”

Network Transport Layer

There are currently three available transport layer options:

In Memory:Used for testing (A node will not connect to the Uplink network)
TCP:The default, reliable tranport-layer communication protocol. Communication over the network is fast, reliable, but visible by all other members in the network within which the network packets sent between two nodes are leaving or entering. This protocol is best used in local networks where the network is known to be secure from malcious entities.
TLS:A reliable, secure transport-layer communication protocol. Communication over the network is reliable but slower than just a TCP connection; However, all communication over the network between two specific nodes is encrypted and protected from a man-in-the-middle attack. This transport layer protocol is best used when uplink nodes exist on different networks and must traverse an insecure network.
Transport String Rep
In Memory “in-memory”
TCP “tcp”
TLS “tls”

The only transport option with configurable parameters is TLS. Since each Uplink node process is effectively running a copy of a node specific TLS server, such that network traffic over TCP connections on any process running in an uplink node is encrypted. Within the TLS standard, TLS servers are required to have certain credentials to supply to the client at the initiation of TLS handshake (after a successful TCP handshake). Each TLS server must supply a TLS certificate to the client wishing to connect for verification, and a private key from which the certificate was derived used for message encryption. The form in which they those two required parameters should appear in the config are:

tls {
    server-certificate = <filepath>
    server-key = <filepath>
}

If the TLS parameters are supplied but a non-TLS transport layer is chosen, the parameters will be ignored.

Example public network configuration:

network
{
  port = 8001
  bootnodes = [
      "10.132.0.2:8001"
      "10.132.0.3:8001"
    ]
  max-peers = 100
  min-peers = 2
  closed = true
  nonetwork = false
  preallocated = "config/validators"
  access-token = "config/access-token/key"
  transport = "tls"
  tls {
      server-certificate = "ssl/server/ssl_cert_path.pem"
      server-key = "ssl/server/ssl_key.pem
  }
}

Example local network configuration:

network
{
  port = 8001
  bootnodes = [
      "127.0.0.1:8001",
      "127.0.0.1:8002",
      "127.0.0.1:8003"
    ]
  max-peers = 10
  min-peers = 1
  closed = false
  nonetwork = false
  preallocated = "config/validators"
  access-token = "config/access-token/key"
  transport = "tcp"
}

Bootstrapping

Bootnodes are named participants involved in a chain that assist in bootstrapping the peer network for entities just joining. They maintain a list of active nodes and send their peer list to other peers on demand to construct the network overlay. Any node can act as a bootnode, but at least one bootnode is needed to begin network membership. The bootnodes are specified as a list of IP addresses and ports in the chain configuration file:

bootnodes = [
    "10.132.0.2:8001"
  , "10.132.0.4:8001"
  ]

Network Access Token

When a network is initialized and access token must be provided; The network access token is an ECDSA private key from which a public key can be derived. An Uplink node will communicate with other nodes in the network by signing all of it’s messages with the access token, and will not accept nor respond to messages from nodes that do not send signed messages of a particular form, nor messages that have invalid signatures. The network messages signatures are verified by using the public key corresponding to the private key that is the network access token.

The network access token serves the main purpose of preventing anyone who possesses knowledge of the bootnode network addresses to connect to the network, to send and receive messages to and from other Uplink nodes in the network, unless they have possession of the network access token, The token should be kept secret by network participants and preshard during network initialization.

If a network access token is compromised, it can easily be exchanged for a new one. The non-malicious network participants can agree off-chain on a new ECSDA private key to replace the existing, compromised network access token. By definition, two Uplink nodes will only communicate if they possess the same network access token. If the compromised network access token is swapped out for a new access token by all benevolent network participants at the same time, the network can continue with only minor downtime. It is important to note that even if the network access token is compromised, the only result is that Uplink nodes will accept communication from the potentially malicious node: This does not compromise the security guarantees of the consensus algorithm, nor the ledger rules that dictate valid transactions in the newtork. The network access token is only one out of several layers of security that Uplink provides.