This document outlines the units of functionality that are necessary for an implementation of the portal wire protocol
Note that in some places the exact functionality may not be strictly necessary and may be influenced by the implementation details of individual clients. There are alternative ways to implement the protocol and this is merely intended to serve as a guide.
Support for the base Discovery v5 protocol functionality
Base protocol support for the TALKREQ and TALKRESP messages
The ability to route incoming TALKREQ/TALKRESP messages to custom handlers.
The ability to send a TALKREQ with a specific request_id and receive the corresponding TALKRESP message.
Support for the message types that are part of the portal wire protocol
Support for the PING and PONG message types
Support for the PING message type
The ability to send a PING message
The ability to receive PING messages
Support for the PONG message type
The ability to send a PONG message
The ability to receive PONG messages
When a PING message is received a PONG response is sent.
Support for the FINDNODES and FOUNDNODES message types
Support for the FINDNODES message type
The ability to send a FINDNODES message
The ability to receive FINDNODES messages
Support for the FOUNDNODES message type
The ability to send a FOUNDNODES message
The ability to receive FOUNDNODES messages
When a FINDNODES message is received the appropriate node_id records are pulled from the sub protocol routing table and a FOUNDNODES response is sent with the ENR records.
Support for the FINDCONTENT and FOUNDCONTENT message types
Support for the FINDCONTENT message type
The ability to send a FINDCONTENT message
The ability to receive FINDCONTENT messages
Support for the FOUNDCONTENT message type
The ability to send a FOUNDCONTENT message
The ability to receive FOUNDCONTENT messages
Support for the OFFER and ACCEPT messages
Support for the OFFER message type
The ability to send a OFFER message
The ability to receive OFFER messages
Support for the ACCEPT message type
The ability to send a ACCEPT message
The ability to receive ACCEPT messages
Management of known ENR records
Support for encoding, decoding, and validating ENR records according to EIPTODO
IP address and port information can be extracted from ENR records.
ENR records can be saved for later retrieval.
Storage of ENR records respects or tracks sequence numbers, preserving and tracking the record with the highest sequence number.
ENR records can be retrieved by their node_id.
Management of routing tables
Separate routing tables for each supported sub protocol.
The routing table is able to use the custom distance function.
The routing table manages the K-buckets
Nodes can be inserted into the routing table into the appropriate bucket, ensuring that buckets do not end up containing duplicate records.
Nodes can be removed from the routing table.
Each bucket is limited to K total members
Each bucket maintains a set of additional nodes known to be at the appropriate distance. When a node is removed from the routing table it is replaced by a node from the replacement cache when one is available. The cache is managed such that it remains disjoint from the nodes in the corresponding bucket.
The routing table can return nodes at a requested log-distance
The routing table can return the nodes closest to a provided node_id.
Functionality related to managing a node's view of the overlay network.
The client uses a set of bootnodes to acquire an initial view of the network.
Each supported sub protocol can have its own set of bootnodes. These records can be either hard coded into the client or provided via client configuration.
The client actively seeks to populate its routing table by performing RFN lookups to discover new nodes for the routing table
The client tracks liveliness of nodes in its routing table and periodically checks the liveliness of the node in its routing table which was least recently checked.
The liveliness checks for any individual node are rate limited as to not spam individual nodes with lots of PING messages when the routing table is sparse.
Management of stored content.
Content can be stored in a persistent database. Databases are segmented by sub protocol.
Given a known content_id the corresponding content payload can be retrieved.
Content can be removed.
Retrieval of the content from the database which is furthest from a provided node_id using the custom distance function.
Retrieval of the total number of bytes stored.
Support for sending and receiving streams of data using the uTP sub protocol.
The ability to establish a new outbound connection with another node with a specified connection-id
The ability to listening for an inbound connection from another node with a connection-id that is known in advance.
When the total size of stored content exceeds the configured maximum content storage size the content which is furthest from the local node_id is evicted in a timely manner. This should also result in any "data radius" values relevant to this network being adjusted.
Support for retrieving content using the FINDCONTENT, FOUNDCONTENT, and uTP sub protocol.
The client can use the FINDCONTENT and FOUNDCONTENT messages to traverse the DHT until they encounter a node that has the desired content.
Upon encountering a FOUNDCONTENT response that contains the actual content payload, the client can return the payload.
Upon encountering a FOUNDCONTENT response that contains a uTP connection-id, the client should initiate a uTP stream with the provided connection-id and receive the full data payload over that stream.
Support for receipt of content using the OFFER/ACCEPT messages and uTP sub protocol.
Client can listen for incoming OFFER messages, responding with an ACCEPT message for any offered content which is of interest to the client.
After sending an ACCEPT response to an OFFER request the client listens for an inbound uTP stream with the connection-id that was sent with the ACCEPT response.
Upon receiving and validating gossip content, the content should then be gossiped to some set of interested nearby peers.
Upon receiving an ACCEPT message in response to our own OFFER message the client can initiate a uTP stream with the other node and can send the content payload across the stream.
The client should listen for FINDCONTENT messages.
When a FINDCONTENT message is received either the requested content or the nodes known to be closest to the content are returned via a FOUNDCONTENT message.
Endpoints that require for the portal network wire protocol.
TODO