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.