Show / Hide Table of Contents

Network Structure: P2P

NEO uses P2P network structure and TCP/IP protocol for transmission.

There are 2 types of node in the network, ordinary node and consensus node. The former can perform transaction/block broadcasting, receiving and relaying, while the latter can furthermore perform block construction.

NEO's network protocol standard is similiar to Bitcoin's, but varies a lot in block / transaction data structure.

  • In NEO network, seed node is not equal to consensus node. It's a kind of ordinary node which provides node list query service to other nodes.

  • NEO network also supports WebSocket connection and supports constructing node in a LAN by using UPnP protocol (Optional).

Transmission Protocol and Port

ProtocolPort (Main net)Port (Test net)

The ports mentioned above can be set to any unused ones when constructing a NEO private chain. Ports of the nodes in a private chain can also be different.


Message's basic format is as follows:

uintMagicMagic number to avoid network conflict
string(12)CommandString message name (Fill with zeros if shorter than 12 byte)
intPayload lengthPayload length
uintPayload ChecksumPayload verification to avoid falsification and transmission errors
byte[]PayloadMessage text, varying by message type

Command List

NameUniquenessHigh priorityReservedDescription
getaddrQueries address and port numer of other nodes.
addrAnswers getaddr message with at most 200 records of succesfully connected node addresses and port numbers.
filteraddAdds data to bloom_filter for SPV wallet.
filterclearRemove bloom_filter for SPV wallet.
filterloadInitialize bloom_filter for SPV wallet.
getblocksSpecify the start and end hash values to get the details of several consecutive blocks.
getdataQueries other nodes for Inventory objects of specified type and hash.
Current usage:
1)Sending get-transaction query during consensus process.
2)Sending getdata message upon receiving inv message.
blockAnswers getdata message with Block of specified hash.
consensusAnswers getdata message with consensus data of specified hash.
txAnswering getdata message for a transaction with specified hash.
getheadersNode with fewer information queries for block head after two nodes establish connection.
headersAnswers getheaders message with at most 2000 block header items.
invSend Inventory hash array of specified type and hash (only hash value rather than complete information). Inventory types include Block, Transaction, and Consensus). Currently inv message is used in these scenarios:
1)Sending transaction in consensus process.
2)Replying getblocks message with no more than 500 blocks.
3) Replying mempool message with all transactions in memory pool.
4) Relaying an Inventory.
5) Relaying a batch of transactions.
mempoolQuery for all transactions in the memory pool of the connected node.
version--First instruction: with information like block header height, etc.
verack--Sencond instruction: handshake Version
merkleblockSending process is implemented while receiving is not. It's for SPV wallet.
pingStandard ping message
pongResponse to ping message
  • Uniqueness:only one such message in message queue at the same time.

  • High priority:the system needs to guarantee that higher priority messages are transmitted and processed first.

Conversation protocol

  1. Firstly a NEO node tries to connect to those seed nodes.

  2. The node firstly sends version message upon connecting successfully and waits for version message. Local block height is contained in version message.

  3. The node sends verack message and waits for verack message to complete handshake.

  4. If the local block height is lower than the other side's height, the node sends getheaders message.

  5. The other side sends headers message which contains no more than 2000 block headers upon receiving getheaders message.

  6. If block header information has been synchronized and local block height is lower than the other side's, send getblocks message.

  7. The other side will send inv message which contains no more than 500 block hashes upon receiving getblocks message.

  8. The node determines whether the complete block information is needed based on each block hash upon receiving the inv message. If so, the node sends getdata message querying for complete block information.

  9. The other side sends block message which contains complete block information upon receiving getdata message.

  10. NEO nodes check the number of connections every 5 seconds. The node connects to backup nodes initiatively if connection count is less than 10. The node sends getaddr message to connected nodes to query information about other nodes in the network if backup nodes are not enough.

  11. The other side sends addr message which contains address and port information of no more than 200 nodes upon receiving getaddr message.

  12. The node uses hash to manage relatively large data like consensus messages / block / transaction data, to avoid receiving duplicate messages from different nodes.

  13. The node is responsible for relaying received consensus messages / block / transaction data to other nodes by inv message.

Conversation Sequence Instance

Message directionMessage typeDescription
sendversionSend version to perform 1st handshake
receiveversionReceive version to perform 1st handshake
sendverackSend verack to perform 2nd handshake
receiveverackReceive verack to perform 2nd handshake
sendgetheadersSend getheaders to retrieve block head
receiveheadersReceive block headers
sendgetblocksSend getblocks to get blocks
receiveinv(blocks)Receive inv hash of some blocks
sendgetdata(blocks)Send getdata to retrieve complete block
receiveinv(consensus)Receive inv hash of consensus data
sendgetdata(consensus)Send getdata to retrieve consensus data of specified hash
receiveconsensusReceive complete consensus data
sendinv(consensus)Relay received consensus data's hash to other nodes
receiveblockReceive a complete block
sendinv(block)Relay block hash
receiveblockReceive a complete block
sendinv(block)Relay block hash
receiveblockReceive a complete block
sendinv(block)Relay block hash