Network Protocol

For the network protocol, there were a lot of existing solutions. However, the Nebulas Team decided to define their own wire protocol, and ensure the use of the following principles to design it:

• the protocol should be simple and straight.
• the messages can be verified before receiving all the packets, and fail early.
• the protocol should be debugging friendly, so that the developer can easily understand the raw message.

Protocol

In Nebulas, we define our own wire protocol as follows:

 0               1               2               3              (bytes)
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                         Magic Number                          |
+---------------------------------------------------------------+
|                         Chain ID                              |
+-----------------------------------------------+---------------+
|                         Reserved              |   Version     |
+-----------------------------------------------+---------------+
|                                                               |
+                                                               +
|                         Message Name                          |
+                                                               +
|                                                               |
+---------------------------------------------------------------+
|                         Data Length                           |
+---------------------------------------------------------------+
|                         Data Checksum                         |
+---------------------------------------------------------------+
|                         Header Checksum                       |
|---------------------------------------------------------------+
|                                                               |
+                         Data                                  +
.                                                               .
.                                                               .
|                                                               |
+---------------------------------------------------------------+

• Magic Number: 32 bits (4 chars)
  • The protocol‘s magic number, a numerical constant or text value used to identify the protocol.
  • Default: 0x4e, 0x45, 0x42, 0x31
• Chain ID: 32 bits
  • The Chain ID is used to distinguish the test network from the main network.
• Reserved: 24 bits
  • reserved field.
  • The first bit indicates whether the network message is compressed.
  • compressed: {0x80, 0x0, 0x0}; uncompressed: {0x0, 0x0, 0x0}
• Version: 8 bits
  • The version of the Message Name.
• Message Name: 96 bits (12 chars)
  • The identification or the name of the Message.
• Data Length: 32 bits
  • The total length of the Data.
• Data Checksum: 32 bits
  • The CRC32 checksum of the Data.
• Header Checksum: 32 bits
  • The CRC32 checksum of the fields from Magic Number to Data Checksum, totally 256 bits.
• Data: variable length, max 512M.
  • The message data.

We always use Big-Endian on the message protocol.

Handshaking Messages

• Hello

the handshaking message when a peer connects to another.

version: 0x1

data: struct {
    string node_id  // the node id, generated by underlying libp2p.
    string client_version // the client version, x.y.z schema, eg. 0.1.0.
}

• OK

the response message for handshaking.

version: 0x1

data: struct {
    string node_id // the node id, generated by underlying libp2p.
    string node_version // the client version, x.y.z schema, eg. 0.1.0.
}

• Bye

the message to close the connection.

version: 0x1
data: struct {
    string reason
}

Networking Messages

• NetSyncRoutes

request peers to sync route tables.

version: 0x1

• NetRoutes

contains the local route tables.

version: 0x1
data: struct {
    PeerID[] peer_ids // router tables.
}

struct PeerID {
    string node_id  // the node id.
}

Nebulas Messages

TBD.