# Network module design document

# Overall description

# 1.1 Module Overview

# 1.1.1 Why do you have a Network Module?

The network module guarantees the communication between the decentralized nodes and provides the lowest level of network communication, node discovery and other services for one of the NULS basic modules.The network foundation of the blockchain is Peer to Peer, or P2P.All participants in the P2P network can be either a service server or a resource user.Features of P2P networks: decentralization, scalability, robustness, cost-effectiveness, privacy protection, and load balancing.

# 1.1.2 What to do with Network Module

The network module is the basic module of the entire system, which is used to manage the connection between nodes, nodes and connections, and the transmission and reception of data.Network modules do not involve complex business logic.

Received network messages, according to the instruction service mapping relationship in the kernel module, push the corresponding processing module of the message.
The open interface is used to push the message calls encapsulated by other modules to the specified peer node and broadcast to the specified network group.

# 1.1.3 Positioning of the Network Module in the system

The network module is the underlying application module. Any module that needs network communication must send and receive messages through the network module.
The network module relies on the core module for governance of the service interface.
The network module builds different networks by network id (magic parameter).
When the nodes of the network module in the main network chain are configured for cross-chain networking, the chain management module is required to provide cross-chain configuration information.
When a node in a parallel chain of a network module is configured for a cross-chain network, cross-chain configuration information is required for the cross-chain module.

# 1.2 Architecture

# Functional design

# 2.1 Functional Architecture

The network module has functions in the business: node management, node group management, p2p network connection management, and message transmission and management.

The internal infrastructure functions include: state management of the module (including startup and shutdown management), and management of external interfaces.

Thread task management, data storage management, etc.

Node management

Manage all connectable, connected node information, status, and provide node operation interfaces
- Node discovery
- Node storage
Node Group Management

Manage different network nodes, divide nodes into different collections, and manage each collection separately.The magic parameters of the nodes connected in each set are the same and different from the magic parameters of other sets.

Each NodeGroup is initialized according to the information registered in the chain or the network information configured by itself (magic parameters, number of nodes, etc.)

Each time a NodeGroup is initialized, the network service listens for a MagicNumber.
Connector Management Connection management
- Initialize the connection
  - Intra-chain node: Initially connect through the seed node, request the peer address through the protocol or receive the shared peer address, and then cache.
  - Cross-chain nodes: The primary network passively waits for the connection of parallel chain nodes.
- Connection management: Need to perform node availability detection, heartbeat maintenance, and disconnect the seed node when there are redundant nodes available.
- Disconnect
Messaging management

1>Message receiving Message receiver

Receiving the message sent by the network node, judging the message (determining cmd), and transparently transmitting the message to the corresponding module service according to the message cmd field.

2> Message Sending Message sender

a> Broadcast messages to the network group (NodeGroup)

b> Specify the peer node to send messages

Module status management

a> start, close the logic processing

b>Maintenance and management of the status of its own module: management module operation status, internal function status, etc.

Interface management

a>Register your own interface to the NUSTAR module

b> Synchronize module information and status to the NUSTAR module

c>Get the service list to the local module

d> open external interface call
Thread task management

a>Manage heartbeat threads

b> management node discovery / elimination mechanism thread

# 2.2 Module Service

# 2.2.1 Network Message Reception

Function Description:

Receiving the message sent by the (external) network node, making a simple judgment on the message (determining the magic parameter), and sending the message to the module service of interest according to the command field contained in the message header.
Process description
Message verification part:

Payload check

magicNumber check

Interface parameter constraints provided by external modules
- method : *** // Same CMD instruction in the message header, constraining 12 bytes
- params

    0: chainId //chain id
    1:nodeId //nodeId
    2: message // hexadecimal network sequence message body
    ......

Dependent service

Parsing the command parameter in the message header, relying on the remote service interface data provided by the kernel module when calling the remote interface processing.

# 2.2.2 Network Message Sending

Forwards messages encapsulated by other or own modules, including broadcast messages and designated nodes to send messages.

# 2.2.2.1, Broadcast Network Message

Function Description:

Forwarding messages encapsulated by other or own modules, the interface that provides forwarding calls to external modules has the following two cases:

a> Broadcast a message to a NodeGroup (specify a network).

b> Broadcast messages to the NodeGroup (specify a network) and exclude certain nodes.

c> Broadcast a message to the NodeGroup (specify a network) in a specified proportion and exclude certain nodes.

Process description

Interface definition

Interface Description

method : nw_broadcast

External modules can broadcast messages through this interface

Request example

{
   "chainId":1234，
   "excludeNodes": "10.13.25.36:5003,20.30.25.65:8009",
   "messageBody":     "03847ABDFF303847ABDFF303847ABDFF303847ABDFF303847ABDFF303847ABDFF3"，
   "command":"block"，
   "isCross":"false"，
   "percent":"50"，
    }

Request parameter description

index	parameter	required	type	description
0	chainId	true	int
1	excludeNodes	true	String	Exclude nodes, comma split
2	messageBody	true	String	Object hexadecimal characters
3	command	true	String	Message Protocol Instructions
4	isCross	true	boolean	Whether it is a cross-chain
5	percent	false	int	Broadcast transmission ratio, do not fill, default 100

Return to example

Failed

{
   "version": 1.2,
    "code":1,
    "msg" :"xxxxxxxxxxxxxxxxxx",
    "result":{
        "value":false
    }
}

Success

{
 "version": 1.2,
    "code":0,
    "result":{
       "value":true
    }
}

Dependent service

no

# 2.2.2.2, the specified node sends a network message

Function Description:

Forwarding messages encapsulated by other or own modules, you can specify that certain nodes (which can be 1 node) send messages.

Process description

Interface definition

Interface Description

External modules can broadcast messages through this interface

method : nw_sendPeersMsg

@Parameter(parameterName = "chainId", requestType = @TypeDescriptor(value = int.class), parameterValidRange = "[1-65535]", parameterDes = "linked chain Id, value range [1-65535]"),
@Parameter(parameterName = "nodes", requestType = @TypeDescriptor(value = String.class), parameterDes = "specify the send peer node Id, a comma-separated string"),
@Parameter(parameterName = "messageBody", requestType = @TypeDescriptor(value = String.class), parameterDes = "message body Hex"),
@Parameter(parameterName = "command", requestType = @TypeDescriptor(value = String.class), parameterDes = "message protocol directive")

Request example

{
"chainId":  1234，
"nodes":  "10.13.25.36:5003,20.30.25.65:8009",
"messageBody":"03847ABDFF303847ABDFF303847ABDFF303847ABDFF303847ABDFF303847ABDFF3"，
"command":  "block"
    }

Request parameter description

index parameter required type description

0 chainId true int

1 nodes true String Send node, comma split

2 messageBody true String hexadecimal characters

command true String

Return to example

Failed

{
   "version": 1.2,
    "code":1,
    "msg" :"xxxxxxxxxxxxxxxxxx",
    "result":{}
}

Success

{
 "version": 1.2,
    "code":0,
    "result":{
       
    }
}

Return field description

parameter type description

Dependent service

no

# 2.2.3 Creating a Node Group

In addition to its own network, the main network chain also has n cross-chain networks, and its own network and cross-chain network use different magicNumber.

In addition to its own network, the parallel chain can also register the cross-chain network on the main network, and its own network and the cross-chain network use the same magicNumber.

Node groups are used to manage different network information.The network module isolates and maintains different networks through node groups.

Node group type: 1> own network 2> cross-chain network (main network chain cross-chain network & parallel chain cross-chain network)

Create a node group for the network module:

1> The own configuration file is loaded to create its own network group.

2> Cross-chain network:

As the main network link node, after the parallel chain registers with the chain management module, the system generates a transaction verification confirmation and then calls the network module to generate a cross-chain network group, and then stores the configuration, and the subsequent modules start automatic loading.

As a parallel chain node, when started by the cross-chain protocol module, the cross-chain protocol module obtains cross-chain configuration information from the module configuration, and invokes the network module.

The network module triggers a cross-chain connection.

# 2.2.3.1 Creating a Node Group from Your Own Network

Function Description:

The own network corresponds to its own chainId, and a magic parameter, through the configuration initialization to create a node group

Process description

Create a node group by configuration file loading
Interface definition

Created internally, no external interface.

Dependent service

# 2.2.3.2 Creating a cross-chain node group

Function Description:

The cross-chain node group on the main network chain is triggered by the parallel chain registration in the main network chain.The parallel chain obtains cross-chain configuration information, and the cross-chain status of the own network group is updated by the cross-chain protocol.

Process description

1> The main network chain is triggered by the chain management module to trigger the creation of a cross-link node group.

2> Parallel chains update the cross-chain status of their own network groups through the cross-chain protocol module.

Interface definition

Interface Description

Receive a call to an external module to create a node group

method : nw_createNodeGroup

Request example

{
      "chainId":  1234,
      "magicNumber": 232342,
      "maxOut":  10,
      "maxIn":  100,
      "minAvailableCount":  20，
      "seedIps":  "10.20.30.10:8002,48.25.32.12:8003,52.23.25.32:9003",
      "isCrossGroup":  0
    }

Request parameter description

index	parameter	required	type	description
0	chainId	true	int
1	magicNumber	true	long	Magic Parameters
2	maxOut	true	int	Maximum active connections
3	maxIn	true	int	Maximum Passive Connections
4	minAvailableCount	true	int	Minimum number of connections in the friend chain
5	seedIps	true	String	seed node, comma split
6	isMoonNode	true	boolean	Whether to create a cross-chain connection group: true cross-chain connection, false normal connection

Return to example

Failed

{
   "version": 1.2,
    "code":1,
    "msg" :"xxxxxxxxxxxxxxxxxx",
    "result":{}
}

Success

{
 "version": 1.2,
    "code":0,
    "result":{
       
    }
}

Return field description

parameter type description

Dependent service

Relies on remote service interface data provided by the kernel module.

# 2.2.4 Logging out the node group

Function Description:

Receive calls from external modules, unregistering cross-chain node groups.

As the main network link node, the chain management module performs deregistration, and the system generates a transaction verification confirmation and then calls it.
Process description
Interface definition
- Interface Description
  
  Receive calls from external modules, delete node groups
  
  method : nw_delNodeGroup
- Request example
```
{
    "chainId": 1234
    }
```
- Request parameter description
  
  index parameter required type description
  
  0 chainId true int
- Return to example
  
  Failed
```
{
   "version": 1.2,
    "code":1,
    "msg" :"xxxxxxxxxxxxxxxxxx",
    "result":{}
}
```
  Success
```
{
 "version": 1.2,
    "code":0,
    "result":{
       
    }
}
```
- Return field description
  
  parameter type description
Dependent service

Relies on remote service interface data provided by the kernel module.

# 2.2.5 Cross-chain seed node provides

Function Description:

The seed node is a node used to provide peer connection information when the network is initialized.When performing chain registration, the chain management module needs to obtain information about the cross-chain seed nodes on the primary network chain for initializing the connection.
Process description

no
Interface definition
- Interface Description
  
  Obtain satellite chain seed node
  
  method : nw_getSeeds
- Request example
```
{
    "chainId": 1234
    }
```
- Request parameter description
  
  index parameter required type description
  
  0 chainId true int
- Return to example
  
  Failed
```
{
   "version": 1.2,
    "code":1,
    "msg" :"xxxxxxxxxxxxxxxxxx",
    "result":{}
}
```
  Success
```
{
 "version": 1.2,
    "code":0,
    "result":{
      seedsIps:"101.132.33.140:8003,116.62.135.185:8003,47.90.243.131:8003" 
    }
}
```
- Return field description
  
  parameter type description
  
  seedsIps String Seed Node Information Comma Separation
Dependent service

Relies on remote service interface data provided by the kernel module.

parameter	type	description
seedsIps	String	Seed Node Information Comma Separation

# 2.2.6 Adding a connection node

Function Description:

Under the cmd command, add peer connection information to a network.
Process description

The added node triggers the network connection process.
Interface definition
- Interface Description
  
  Add network peer node
  
  method : nw_addNodes
- Request example
```
{
    "chainId":455，
    "isCross":0,
    "nodes":"10.20.23.02:5006,53.26.65.58:8003"
       }
```
- Request parameter description
  
  index parameter required type description
  
  0 chainId true int
  
  1 isCross true int Whether cross-chain: 0 non-cross-chain, 1 cross-chain
  
  2 nodes true String Node Group
- Return to example
  
  Failed
```
{
   "version": 1.2,
    "code":1,
    "msg" :"xxxxxxxxxxxxxxxxxx",
    "result":{}
}
```
  Success
```
{
 "version": 1.2,
    "code":0,
    "result":{
       
    }
}
```
- Return field description
  
  parameter type description
Dependent service

No

# 2.2.7 Deleting Connection Nodes

Function Description:

Under the cmd command, delete the peers connection information under a certain network.
Process description

Deleting a node triggers the disconnection of the network node.
Interface definition
- Interface Description
  
  Delete network peer node
  
  method : nw_delNodes
- Request example
```
{
    "chainId":234,
    "nodes": "10.20.23.02:5006,53.26.65.58:8003"
    }
```
- Request parameter description
  
  index parameter required type description
  
  0 chainId true int
  
  1 nodes true String Node Group
- Return to example
  
  Failed
```
{
   "version": 1.2,
    "code":1,
    "msg" :"xxxxxxxxxxxxxxxxxx",
    "result":{}
}
```
  Success
```
{
 "version": 1.2,
    "code":0,
    "result":{
       
    }
}
```
- Return field description
  
  parameter type description
Dependent service

no

# 2.2.8 Reconnecting the specified network

Function Description:

Network reconnection of the specified nodeGroup under the cmd command
Process description

After receiving the command, disconnect all the peers under the specified nodeGroup and reconnect to the network.

Refresh the peer connection address under nodegroup and restart the network connection.

If the peer connection is owned by multiple network services, you only need to cancel the association. If only the service is used, you can disconnect.
Interface definition
- Interface Description
  
  Refresh and connect to the network node
  
  method : nw_reconnect
- Request example
```
{
    "chainId":1234
    }
```
- Request parameter description
  
  index parameter required type description
  
  0 chainId true int
- Return to example
  
  Failed
```
{
   "version": 1.2,
    "code":1,
    "msg" :"xxxxxxxxxxxxxxxxxx",
    "result":{}
}
```
  Success
```
{
 "version": 1.2,
    "code":0,
    "result":{
       
    }
}
```
- Return field description
  
  parameter type description
Dependent service

no

# 2.2.9 Get the list of nodeGroup

Function Description:

Get a list of all networks managed by the node.
Process description

no

Interface definition

Interface Description

Get node group information

method : nw_getGroups

Request example

{
    "startPage":1,
    "pageSize":10
 }

Request parameter description

index parameter required type description

0 startPage true int Start Pages

1 pageSize true int Number of records per page

index	parameter	required	type	description
0	startPage	true	int	Start Pages
1	pageSize	true	int	Number of records per page

Return to example

Failed

{
   "version": 1.2,
    "code":1,
    "msg" :"xxxxxxxxxxxxxxxxxx",
    "result":{}
}

Success

{
 "version": 1.2,
    "code":0,
    "result":{
        list:[{
            chainId: 1212, //chain id
            magicNumber: 324234, / / magic parameters
            totalCount: 2323, // total number of connections
            inCount: 22, //passive connections
            outCount: 33, //active connections
            isActive: 1, / / 0 is not activated, 1 is activated
            isCrossChain: 1 //0 is not a cross-chain network, 1 cross-chain network
            },{}
            ]
    }
}

Return field description

parameter	type	description
chainId	int	chain id
magicNumber	int	Magic Parameters
totalCount	int	Total connections
inCount	int	Passive Connections
outCount	int	Active Connections
isActive	int	0 is inactive, 1 is activated
isCrossChain	int	0 is not a cross-chain network, 1 cross-chain network

Dependent service

# 2.2.10 Get the connection information under the specified nodeGroup

Function Description:

Get information about all nodes under the specified network id
Process description

no

Interface definition

Interface Description

Get node information

method : nw_getNodes
Request example

{
    "chainId":125,
    "state":1,
    "isCross":1,
    "startPage":1,
    "pageSize":5
}

Request parameter description

index	parameter	required	type	description
0	chainId	true	int	network id
1	state	true	int	0 all links, 1 connected, 2 not connected
2	isCross	true	int	0 Normal Connection 1 Cross-Chain Connection
3	startPage	true	int	Start Pages
4	pageSize	true	int	Number of records per page

Return to example

Failed

{
   "minVersion": 1.2,
    "code":1,
    "msg" :"xxxxxxxxxxxxxxxxxx",
    "result":{}
}

Success

{
 "minVersion": 1.2,
 "code":0,
 "msg" :"xxxxxxxxxxxxxxxxxx",
 "result":{
       list:[{
                chainId: 122, / / chain id
                nodeId:"20.20.30.10:9902"
                magicNumber: 134124, / / magic parameters
                blockHeight: 6000, //block height
                blockHash："0020ba3f3f637ef53d025d3a8972462c00e84d9
                     Ea1a960f207778150ffb9f2c173ff", //block hash value
                Ip: "200.25.36.41", / / ip address
                port：54,//
                State: "connected",
                isOut: "1", //0 passive connection, 1 active connection
                Time: "6449878789", // recent connection time
	     },{}
	     ]
    }
}

Return field description

parameter	type	description
chainId	int	chain id
nodeId	String	node id
magicNumber	int	Magic Parameters
blockHeight	long	Latest block height
blockHash	String	Latest block hash
ip	String	ip address
port	int	port number
state	int	connection state 1 connection 0 not connected
isOut	int	0 passive connection, 1 active connection
time	long	Recent connection time

Dependent service

# 2.2.11 Get the specified chain network summary information

Function Description:

Get the network information of the specified chainId.
Process description

no

Interface definition

Interface Description

Get chain network information

method : nw_getGroupByChainId
Request example
```
{
    "chainId":142
 }
```
Request parameter description

index parameter required type description

0 chainId true int Chain Id

index	parameter	required	type	description
0	chainId	true	int	Chain Id

Return to example

Failed

{
   "version": 1.2,
    "code":1,
    "msg" :"xxxxxxxxxxxxxxxxxx",
    "result":{}
}

Success

{
 "version": 1.2,
    "code":0,
    "result":{
            "chainId": 1212, //chain id
            "magicNumber": 324234, / / magic parameters
            "totalCount": 2323, // total number of connections
            "connectCount": 44, / / connected number
            "disConnectCount": 32, / / unconnected quantity
            "inCount": 22, //passive connections
            "outCount": 33, //active connections
            "connectCrossCount": 44, / / connected cross-chain number
            "disConnectCrossCount": 32, / / unconnected quantity
            "inCrossCount": 22, // cross-chain passive connections
            "outCrossCount": 33, / / cross-chain active connections
            "isActive": 1, / / 0 is not activated, 1 is activated
            "isCrossActive": 1, //0 cross-chain network is not activated, 1 cross-chain activation
            "isMoonNet": 0 //0 friend chain, 1 satellite chain
            }
}

Return field description

parameter	type	description
chainId	int	chain id
magicNumber	int	Magic Parameters
totalCount	int	Total connections
connectCount	int	Connected Quantity
disConnectCount	int	Unconnected Quantity
inCount	int	Passive Connections
outCount	int	Active Connections
connectCrossCount	int	Cross-chain connected number
disConnectCrossCount	int	Cross-chain unconnected quantity
inCrossCount	int	Cross-chain passive connections
outCrossCount	int	Cross-chain active connections
isActive	int	0 is inactive, 1 is activated
isCrossActive	int	0 cross-chain network not activated, 1 cross-chain activation
isMoonNet	int	0Friend Chain, 1 Satellite Chain

Dependent service

# 2.2.12 Updating the information of the peer connection node (height & Hash)

Function Description:

The network connection has the height and hash value of the peer node when the handshake connection is made, and the height and hash value of the subsequent peer connection node are called and updated by the external module (block management module).
Process description

1> Wait for the block management interface to be initialized when the node starts, and then call the block management interface to get the latest block height and hash value.

2> When the handshake is performed, the node related information is put into the Verion protocol message and sent to the peer.

3> After the connection is established, the block management module will call the interface to update the latest block height and hash value.
Interface definition
- Interface Description
  
  The block management module calls to update the height of the node and the hash value.
  
  method : nw_updateNodeInfo
- Request example
```
{
    "method":"nw_reconnect",
    "minVersion":1.1,
    "params":[
        1598,
        "10.20.30.20:8856",
        10,
        "0020ba3f3f637ef53d025d3a8972462c00e84d9ea1a960f207778150ffb9f2c173ff"
    ]
}
```
- Request parameter description
index parameter required type description

0 chainId true int network id

1 nodeId true String Network Node id

2 blockHeight true long Start Pages

3 blockHash true String Block Latest Hash
- Return to example
Failed
```
{
   "version": 1.2,
    "code":1,
    "msg" :"xxxxxxxxxxxxxxxxxx",
    "result":{}
}
```
Success
```
{
 "version": 1.2,
 "code":0,
 "msg" :"xxxxxxxxxxxxxxxxxx",
 "result":{
   
    }
}
```
- Return field description

parameter	type	description

Dependent service

# 2.2.13 Registering Network Protocol Processor

Function Description:

After receiving the message sent by the peer end, the network module needs to call the corresponding module according to the cmd in the message protocol header.

The mapping relationship between cmd and module requires each module to submit registration at startup.
Process description

slightly
Interface definition
- Interface Description
  
  Registering a message invocation command between remote nodes
  
  method : nw_protocolRegister
- Request example
```
{
  "role": "bl",
  "protocolCmds": [
   "getBlockRequest",
    "downLoadBlock"
  ]
}
```
- Request parameter description
index parameter required type description

0 role true String Module Role

1 protocolCmds true array Protocol Instruction Array
- Return to example
Failed
```
{
  
}
```
Success
```
{
   
}
```
- Return field description
Dependent service

index	parameter	required	type	description
0	role	true	String	Module Role
1	protocolCmds	true	array	Protocol Instruction Array

# 2.2.14 Network time acquisition

Function Description:

Get network time for local time offset synchronization.

Process description

The network module obtains the time of several servers on the network and performs offset calculation adjustment.If the network time acquisition fails, the time-acquisition protocol is sent to the 10 peer nodes to obtain the peer node time for the deviation calculation. If it is not available, the local time is directly returned.

Description: Deviation correction is performed periodically.

Interface definition
- Interface Description
  
  Get network time
  
  method : nw_currentTimeMillis
- Request example
```
Rpc unified format
```
- Request parameter description
index parameter required type description
- Return to example
Failed
```
Rpc unified format
```
Success
```
{
   "currentTimeMillis":11544545466 
}
```
- Return field description

parameter	type	description
currentTimeMillis	long	1970-01-01 The difference so far, in milliseconds

Dependent service

# 2.3 Module internal function

# 2.3.1 Module startup

Function Description:

When the module is started, the configuration information is initialized, the registration service is initialized, and the initialization of each internal function management database information is performed.

Process description

  ![](./image/network-module/start.png)

1> Local configuration data loading, database node group and node information data loading.

2> The state of the listening block management module enters the initialization completion, and the interface can be called, and then the block height and the hash value of the latest local node are acquired.

3> Initialization is complete, enter the peer node connection.

4> After the network connection module is stable, it can be sent out as an event.

The network module initiates the connection stability determination condition: no new handshake connection occurs in x seconds, and there is no height increase in x seconds.x=10

Dependent service

Dependent on core module, block management module

# 2.3.2 Module is off

Function Description:

When the module is closed, the connection is closed, the thread management is closed, the resources are released, and the status is notified to the core interface.
Process description

Dependent service

no

# 2.3.3 peer node discovery

Function Description:

After the network module is started, the peer node is managed.

The ways for node acquisition are:

1> Connect to the seed node and request address acquisition.

2> Receive the broadcasted node message.

2> The connection of the cross-chain network, for example, as a connection between a node on the main network chain and a parallel chain, or a connection between a node on the parallel chain and the main network chain.
Process description

Dependent service

# 2.3.4 Network Connection

Function Description:

A node acts as the client and actively connects to the known peer node. It is also the server and waits for the peer node to connect.

A connection can work normally, and it needs to pass the handshake protocol, that is, send each version protocol message. The specific definition of the protocol is as follows.

"Protocol - Network Communication Protocol Part".
Process description

After the TCP connection is complete with the server, the client needs to handshake through the service version protocol. Only the connection with successful handshake can forward the service.The state in the connection cannot be transitioned to connected after X minutes, and the connection is actively disconnected.

The version protocol is sent in the process (see the version structure of the protocol):

1> The protocol carries the information of the node, including: version information of the protocol, the highest block height of the port, the block hash value,

The external network ip, port, and cross-chain service port of the other node, as well as the external network ip, port, and cross-chain service port of the node.

2> The service connection can be established only through the version protocol, otherwise it will be disconnected after waiting for X=1 minutes.

Dependent service

# 2.3.5 Heartbeat Detection

Function Description:

Check if the connection is still connected.The keep-alive is maintained by the ping-pong message of the client and the server.Refer to the "Protocol - Network Communication Protocol" section for the definition of the ping-pong protocol involved.
Process description

Dependent service

# 2.3.6 Connection Quantity Verification

Function Description:

When a node connection is established, the number of connections is made, and if the maximum is reached, the connection is actively disconnected.

Process description
```
![](./image/network-module/connet-validate.png)
```
Dependent service

# 2.3.7 External ip storage of nodes

Function Description:

A node may have multiple network cards, or it may be in a local area network. Therefore, when establishing a connection, it does not know its own external network ip address.

The node needs to know its own external network IP address to broadcast its own address for the external network peers to connect.In our design, the external network of the node is carried by the version protocol message.

Process description

When the client receives the version message, it can know its own IP address information.

Dependent service

# 2.3.8 Node's external network connection detection

Function Description:

When a node establishes a connection, it can broadcast its own external network IP+port to other nodes.However, if a node is in a local area network, the IP address of its external network cannot be directly connected.Therefore, in order to detect whether the external IP address of the node is available, you can connect to your own server to determine whether the IP address can be used for broadcast. If the connection is successful, the external IP address of the node cannot be broadcast to other nodes.

Process description

Self-connection may succeed or fail. If it is successful, the external network ip is reachable, and it can be broadcasted to other nodes in the network when the connection is established. If it is unreachable, the connection cannot be established without processing.

Dependent service

# 2.3.9 Broadcasting of the peer node

Function Description:

Broadcast its own node to other nodes in the network. In the design, we will promote the broadcast of its external network ip after the network is stabilized.
Process description

Dependent service

# 2.3.10 Request/Reply getaddr Protocol Message

Function Description:

Request an address protocol message for more network connections
Process description

Request getaddr:

1> After the network is stable, broadcast to the peer connection node to request a list of connectable addresses.

Reply getaddr

1>peer cross-chain connection, the main network chain replies to the address list of the main network nodeGroup (IP+cross-chain port), and the parallel chain replies with its own chain address list (IP+cross-chain port)

2>peer own network connection, the node will reply to the address list (IP+ own chain port)

Dependent service

# 2.3.11 Send/Receive Address Logic

Function Description:

Receiver protocol message processing logic for receiving network transmission
Process description

Send addr:

1> When a new node is accessed, an addr message is broadcast to other peers of the same nodegroup.

2> When the getaddr message is requested, the addr message will be replied.

Receive addr:

1> Determine whether the address is already owned locally. If you do not forward it, get the new addr.

2> The received node can be forwarded only after it has been authenticated by the connection.

Dependent service

# 2.3.12 Cross-chain server port delivery

Function Description:

A node can have two roles, one is to maintain its own internal chain network.The other is to maintain a cross-chain network as a cross-chain role.

Therefore, in the server definition, we distinguish the port listeners of the two networks so that they are relatively independent.The own chain defines a serverPort1, and the cross-chain part defines a serverPort2.
Process description

As shown in the figure below, our main network chain network and the parallel chain network generate a cross-chain connection. When there is a node 2 in the main network chain connected to node 1, the connection is established through the internal service Port1, and node 1 can be the node 2 The node A sent to the friend chain and the node B are connected, and the information sent to the friend chain at this time should be serverPort2, so the serverPort2 needs to be transferred in the internal interaction of the main network chain.We define this part of the data in the version protocol for delivery.
```
![](./image/network-module/crossPortDeliver.png)
```

Dependent service

# Description of the event

# 3.1 Published events

# Agreement

# 4.1 Network Communication Protocol

# version

Used to establish a connection (handshake)

Length	Fields	Type	Remark
4	version	uint32	Protocol version identifier used by the node
20	addr_you	byte[20]	The other party's network address [IP+PORT1+PORT2] PORT2 is a cross-chain server port such as: [10.32.12.25 8003 9003] 16byte+2byte+2byte
20	addr_me	byte[20]	The network address of this node [IP+PORT1+PORT2] PORT2 is a cross-chain server port such as: [20.32.12.25 7003 6003] 16byte+2byte+2byte
4	block_height	uint32	Node Height
?	block_hash	varInt	Block hash
??	extend	VarByte	Extended field, no more than 10 bytes?

# verack

Used to answer version

Length	Fields	Type	Remark
1	ack_code	uint8	Return code, 1 for normal, 2 for connection is full

# ping

Used to maintain the connection. After receiving a message for a certain node for a period of time, the message is sent. If the pong message is received, the node remains connected. Otherwise, the connection is closed and the node is deleted.

Length	Fields	Type	Remark
4	randomCode	uint32	Random Numbers

# pong

Used to respond to ping

Length	Fields	Type	Remark
4	randomCode	uint32	Random Numbers

# getaddr

Used to request connection information for available nodes in the network.

Length	Fields	Type	Remark
2	chainId	uint16	Chain id
1	isCrossAddress	uint8	Whether to request a cross-chain address

# addr

It is used to answer getaddr, or announce its existence to the network. After receiving the message, the node determines whether the node is known. If it is an unknown node, it saves it and propagates the address to the network after it passes the verification.

Length	Fields	Type	Remark
??	addr_list	network address	18 bytes per node (16 bytes IP + 2 bytes port)

# bye

Used for peer-to-peer connection to actively disconnect, denial of service peer message service

Length	Fields	Type	Remark
1	byeCode	uint8	Reserved Fields

# getTime

Used to get time from the peer node

Length	Fields	Type	Remark
4	messageId	uint32	Request id

# responseTime

Reply to peer node time

Length	Fields	Type	Remark
4	messageId	uint32	Request id
4	time	uint32	Time Value

# 4.2 Trading Agreement

# Module configuration

[network]
port=18001
crossPort=18002
#魔法参
packetMagic=20190807
#籽点
selfSeedIps=39.98.226.51:18001,47.244.186.65:18001,47.254.234.223:18001,47.74.86.85:18001
#Main-network cross-chain seed connection node for initial connection of parallel chain
moonSeedIps=39.98.226.51:18002,47.244.186.65:18002,47.254.234.223:18002,47.74.86.85:18002
#Maximum number of network connections
maxInCount=100
#Maximum number of outgoing connections
maxOutCount=20

# Java-specific design

[^Description]: Core object class definition, storage data structure, ...

# Supplementary content

[^Description]: Required content not covered above

index	parameter	required	type	description
0	chainId	true	int
1	nodes	true	String	Send node, comma split
2	messageBody	true	String	hexadecimal characters
	command	true	String

# Network module design document

# Overall description

# 1.1 Module Overview

# 1.1.1 Why do you have a Network Module?

# 1.1.2 What to do with Network Module

# 1.1.3 Positioning of the Network Module in the system

# 1.2 Architecture

# Functional design

# 2.1 Functional Architecture

# 2.2 Module Service

# 2.2.1 Network Message Reception

# 2.2.2 Network Message Sending

# 2.2.2.1, Broadcast Network Message

# 2.2.2.2, the specified node sends a network message

# 2.2.3 Creating a Node Group

# 2.2.3.1 Creating a Node Group from Your Own Network

# 2.2.3.2 Creating a cross-chain node group

# 2.2.4 Logging out the node group

# 2.2.5 Cross-chain seed node provides

# 2.2.6 Adding a connection node

# 2.2.7 Deleting Connection Nodes

# 2.2.8 Reconnecting the specified network

# 2.2.9 Get the list of nodeGroup

# 2.2.10 Get the connection information under the specified nodeGroup

# 2.2.11 Get the specified chain network summary information

# 2.2.12 Updating the information of the peer connection node (height & Hash)

# 2.2.13 Registering Network Protocol Processor

# 2.2.14 Network time acquisition

# 2.3 Module internal function

# 2.3.1 Module startup

# 2.3.2 Module is off

# 2.3.3 peer node discovery

# 2.3.4 Network Connection

# 2.3.5 Heartbeat Detection

# 2.3.6 Connection Quantity Verification

# 2.3.7 External ip storage of nodes

# 2.3.8 Node's external network connection detection

# 2.3.9 Broadcasting of the peer node

# 2.3.10 Request/Reply getaddr Protocol Message

# 2.3.11 Send/Receive Address Logic

# 2.3.12 Cross-chain server port delivery

# Description of the event

# 3.1 Published events

# 3.2 Subscribe to events

# Agreement

# 4.1 Network Communication Protocol

# version

# verack

# ping

# pong

# getaddr

# addr

# bye

# getTime

# responseTime

# 4.2 Trading Agreement

# Module configuration

# Java-specific design

# Supplementary content