Merge pull request #952 from fjl/eip-868-updates

EIP-868: add sequence number to ping and pong

EIPS/eip-868.md

@@ -18,35 +18,66 @@ resolution of Ethereum Node Records (ENR).
 
 To bridge current and future discovery networks and to aid the implementation of other
 relay mechanisms for ENR such as DNS, we need a way to request the most up-to-date version
-of a node record.
+of a node record. This EIP provides a way to request it using the existing discovery
+protocol.
 
 # Specification
 
-Implementations of Node Discovery Protocol v4 should support two new packet types, a request
-and reply of the node record. The new packets are:
+Implementations of Node Discovery Protocol v4 should support two new packet types, a
+request and reply of the node record. The existing ping and pong packets are extended with
+a new field containing the sequence number of the ENR.
 
-### enrRequest (0x05)
+### Ping Packet (0x01)
 
-RLP: `[ expiration ]`
+```text
+packet-data = [version, from, to, expiration, enr-seq]
+```
 
-When a packet of this type is received, the node should reply with an enrResponse packet
+`enr-seq` is the current sequence number of the sending node's record. All other fields
+retain their existing meaning.
+
+### Pong Packet (0x02)
+
+```text
+packet-data = [to, ping-hash, expiration, enr-seq]
+```
+
+`enr-seq` is the current sequence number of the sending node's record. All other fields
+retain their existing meaning.
+
+### ENRRequest Packet (0x05)
+
+```text
+packet-data = [ expiration ]
+```
+
+When a packet of this type is received, the node should reply with an ENRResponse packet
 containing the current version of its record.
 
-To guard against amplification attacks, the sender of enrRequest should have replied to a
-ping packet recently. The expiration field, a UNIX timestamp, should be handled as for all
-other existing packets, i.e. no reply should be sent if it refers to a time in the past.
+To guard against amplification attacks, the sender of ENRRequest should have replied to a
+ping packet recently (just like for FindNode). The `expiration` field, a UNIX timestamp,
+should be handled as for all other existing packets i.e. no reply should be sent if it
+refers to a time in the past.
 
-### enrResponse (0x06)
+### ENRResponse Packet (0x06)
 
-RLP: `[ requestHash, ENR ]`
+```text
+packet-data = [ request-hash, ENR ]
+```
 
-This packet is the response to enrRequest.
+This packet is the response to ENRRequest.
 
-- `requestHash` is the hash of the entire enrRequest packet being replied to.
+- `request-hash` is the hash of the entire ENRRequest packet being replied to.
 - `ENR` is the node record.
 
-The recipient of the packet should verify that the node record is signed by node who
-sent enrResponse.
+The recipient of the packet should verify that the node record is signed by node who sent
+ENRResponse.
+
+## Resolving Records
+
+To resolve the current record of a node public key, perform a recursive Kademlia lookup
+using the FindNode, Neighbors packets. When the node is found, send ENRRequest to it and
+return the record from the response.
 
 # Copyright