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.