Portal Network: State Network Client Functionality

This document outlines the units of functionality that comprise a full featured client for the state network component of the overall portal network.

A - Base Protocol

Support for the base discovery v5 protocol functionality

A.1 - Base Protocol TALKREQ and TALKRESP

Base protocol support for the TALKREQ and TALKRESP messages

A.2 - TALKREQ/TALKRESP message routing

The ability to route incoming TALKREQ/TALKRESP messages to custom code.

A.3 - TALKREQ/TALKRESP request and response handling

The ability to send a TALKREQ with a specific request_id and receive the corresponding TALKRESP.

B - Sub Protocol Messages

Support for the various message types in the sub protocol

B.1 - PING & PONG

Support for the PING and PONG message types

B.1.a - PING message support

Support for the PING message type

B.1.a.1 - PING sending

The ability to send a PING message

B.1.a.2 - PING receiving

The ability to receive PING messages

B.1.b - PONG message support

Support for the PONG message type

B.1.b.1 - PONG message support

Support for the PONG message type

B.1.b.1 - PONG sending

The ability to send a PONG message

B.1.b.2 - PONG receiving

The ability to receive PONG messages

B.1.c - PONG when PING’d

When a PING message is received a PONG response is sent.

B.2 - FINDNODES & FOUNDNODES

Support for the FINDNODES and FOUNDNODES message types

B.2.a - FINDNODES message support

Support for the FINDNODES message type

B.2.a.1 - FINDNODES sending

The ability to send a FINDNODES message

B.2.a.2 - FINDNODES receiving

The ability to receive FINDNODES messages

B.2.b - FOUNDNODES message support

Support for the FOUNDNODES message type

B.2.b.1 - FOUNDNODES message support

Support for the FOUNDNODES message type

B.2.b.1 - FOUNDNODES sending

The ability to send a FOUNDNODES message

B.2.b.2 - FOUNDNODES receiving

The ability to receive FOUNDNODES messages

B.2.c - Serving FINDNODES

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.

B.3 - FINDCONTENT & FOUNDCONTENT

Support for the FINDCONTENT and FOUNDCONTENT message types

B.3.a - FINDCONTENT message support

Support for the FINDCONTENT message type

B.3.a.1 - FINDCONTENT sending

The ability to send a FINDCONTENT message

B.3.a.2 - FINDCONTENT receiving

The ability to receive FINDCONTENT messages

B.3.b - FOUNDCONTENT message support

Support for the FOUNDCONTENT message type

B.3.b.1 - FOUNDCONTENT sending

The ability to send a FOUNDCONTENT message

B.3.b.2 - FOUNDCONTENT receiving

The ability to receive FOUNDCONTENT messages

B.4 - OFFER/ACCEPT/STORE

Support for the OFFER, ACCEPT, and STORE messages

B.4.a - OFFER message support

Support for the OFFER message type

B.4.a.1 - OFFER sending

The ability to send a OFFER message

B.4.a.2 - OFFER receiving

The ability to receive OFFER messages

B.4.b - ACCEPT message support

Support for the ACCEPT message type

B.4.b.1 - ACCEPT sending

The ability to send a ACCEPT message

B.4.b.2 - ACCEPT receiving

The ability to receive ACCEPT messages

B.4.c - STORE message support

Support for the STORE message type

B.4.c.1 - STORE sending

The ability to send a STORE message

B.4.c.2 - STORE receiving

The ability to receive STORE messages

C - ENR Database

Management of known ENR records

C.1 - ENR handling

Support for encoding, decoding, and validating ENR records according to EIPTODO

C.1.a - Extraction of IP address and port

IP address and port information can be extracted from ENR records.

C.2 - Store ENR record

ENR records can be saved for later retrieval.

C.2.a - Tracking highest sequence number

Storage of ENR records respects or tracks sequence numbers, preserving and tracking the record with the highest sequence number.

C.3 - Retrieve ENR Record

ENR records can be retrieved by their node_id.

D - Overlay Routing Table

Management of the overlay routing table

D.1 - Distance Function

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)

D.2 - Manage K-Buckets

The routing table manages the K-buckets

D.2.a - Insertion of new nodes

Nodes can be inserted into the routing table into the appropriate bucket, ensuring that buckets do not end up containing duplicate records.

D.2.b - Removal of nodes

Nodes can be removed from the routing table.

D.2.c - Maximum of K nodes per bucket

Each bucket is limited to K total members

D.2.d - Replacement cache

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.

D.3 - Retrieve nodes at specified log-distance

The routing table can return nodes at a requested log-distance

D.4 - Retrieval of nodes ordered by distance to a specified node_id

The routing table can return the nodes closest to a provided node_id.

E - Overlay Network Management

Functionality related to managing a node’s view of the overlay network.

E.1 - Bootstrapping via bootnodes

The client uses a set of bootnodes to acquire an initial view of the network.

E.1.a - Bootnodes

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.

E.2 - Population of routing table

The client actively seeks to populate its routing table by performing RFN lookups to discover new nodes for the routing table

E.3 - Liveliness checks

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.

F - Content Database

Management of stored content.

F.1 - Content can be stored

Content can be stored in the database

F.2 - Content can be retrieved by content_id

Given a known content_id the corresponding content payload can be retrieved.

F.3 - Content can be removed

Content can be removed.

F.3 - Query furthest by distance

Retrieval of the content from the database which is furthest from a provided node_id.

F.4 - Total size of stored content

Retrieval of the total number of bytes stored.

G - Content Management

G.1 - Enforcement of maximum stored content size

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.

G.2 - Proof handling

G.2.a - Proof Transmission

G.2.a.1 - Proof Encoding and Serialization

The ability to take a merkle proof against the hexary patricia trie and serialize it to a stream of bytes suitable for transmission.

G.2.a.2 - Proof Decoding and Deserialization

The ability to take a stream of bytes representing a merkle proof against the hexary patricia trie and deserialize it into a native representation.

G.2.b - Proof validation

The ability to validate that a given merkle proof is well formed against a known state root.

G.2.c - Proof storage

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.

G.3 - Gossip via OFFER/ACCEPT/STORE

Support for the base gossip protocol implemented on top of OFFER/ACCEPT/STORE messages.

G.3.a - Handle incoming gossip

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.

G.3.b - Propogate incoming gossip

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.

G.4 - Serving Content

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.

H - JSON-RPC

Endpoints that require state access

H.1 - eth_balance

TODO

H.2 - eth_getTransactionCount

TODO

H.3 - eth_getCode

TODO

H.4 - eth_getStorage

TODO

H.5 - eth_call

TODO

H.6 - eth_estimateGas

TODO

Select a repo