This document outlines the units of functionality that comprise a full featured client for the state network component of the overall portal network.
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 code.
The ability to send a TALKREQ with a specific request_id
and receive the corresponding TALKRESP.
Support for the various message types in the sub 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
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
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 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, ACCEPT, and STORE 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
Support for the STORE message type
The ability to send a STORE message
The ability to receive STORE 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 the overlay routing table
The routing table is able to use the custom distance function.
MODULO = 2**256
MID = 2**255
def distance(node_id: int, content_id: int) -> int:
"""
A distance function for determining proximity between a node and content.
Treats the keyspace as if it wraps around on both ends and
returns the minimum distance needed to traverse between two
different keys.
"""
delta = (node_id - content_id + MID) % MODULO - MID
if delta < -MID:
return abs(diff + MID)
else:
return abs(diff)
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
node_id
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.
The client has access to a set of bootnodes ENR records. 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.
Management of stored content.
Content can be stored in the database
content_id
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
.
Retrieval of the total number of bytes stored.
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.
The ability to take a merkle proof against the hexary patricia trie and serialize it to a stream of bytes suitable for transmission.
The ability to take a stream of bytes representing a merkle proof against the hexary patricia trie and deserialize it into a native representation.
The ability to validate that a given merkle proof is well formed against a known state root.
For each proof, the client should be able to store the proof for later retrieval.
Efficient storage will require the ability to merge multiple proofs into a single proof, and then to extract a minimal sub-proof from the merged proofs.
A simple model for storage would be simply to store the serialized versions which will result in larger storage overhead, but side-steps the need for merging proofs.
Support for the base gossip protocol implemented on top of OFFER/ACCEPT/STORE messages.
Client can listen for incoming OFFER messages, responding with an ACCEPT message for any offered content which is of interest to the client. The client would then listen for the corresponding STORE request which will either contain the full payload in the case that it fits within the packet, or extract the connection_id
for use with a uTP based data stream between the two nodes.
Upon receiving the content payload which should be a merkle proof against a leaf of the trie, the proof should be verified, the content stored.
Upon receiving and validating content from an OFFER/ACCEPT/STORE set of messages, the content should then be gossiped to some set of neighboring peers using the same mechanism.
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 state access
eth_balance
TODO
eth_getTransactionCount
TODO
eth_getCode
TODO
eth_getStorage
TODO
eth_call
TODO
eth_estimateGas
TODO