network_protocol.md

Network Protocol

For the network protocol, there are lots of existing solution. However, the Nebulas Team finally decides to define our own wire protocol, ensures the following principles to design the protocol:

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

Protocol

In Nebulas, we define our own wire protocol, as the following:

 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 magic number, A constant numerical or text value used to identify protocol.
  • Default: 0x4e, 0x45, 0x42, 0x31

• Chain ID: 32 bits

  • The Chain ID is used to distinguish the test network and 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 in message protocol.

Handshaking Messages

• Hello

the handshaking message when peer connect to others.

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 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.