# 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](#TODO) 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](#TODO) ### 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. ```python 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](#TODO) 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