Fluffy: Update ping endpoints to correctly support ping extensions (#3185)

* Update ping endpoint to conform to ping extensions/json rpc spec.

Author: bhartnett

fluffy/docs/the_fluffy_book/mkdocs.yml

@@ -1,5 +1,5 @@
 # Nimbus Fluffy book
-# Copyright (c) 2023-2024 Status Research & Development GmbH
+# Copyright (c) 2023-2025 Status Research & Development GmbH
 # Licensed and distributed under either of
 #   * MIT license (license terms in the root directory or at https://opensource.org/licenses/MIT).
 #   * Apache v2 license (license terms in the root directory or at https://www.apache.org/licenses/LICENSE-2.0).

fluffy/network/wire/portal_protocol.nim

@@ -779,7 +779,7 @@ proc recordsFromBytes(rawRecords: List[ByteList[2048], 32]): PortalResult[seq[Re
 
 proc ping*(
     p: PortalProtocol, dst: Node
-): Future[PortalResult[(uint64, CapabilitiesPayload)]] {.
+): Future[PortalResult[(uint64, uint16, CapabilitiesPayload)]] {.
     async: (raises: [CancelledError])
 .} =
   if p.isBanned(dst.id):
@@ -800,7 +800,7 @@ proc ping*(
 
   p.radiusCache.put(dst.id, payload.data_radius)
 
-  ok((pong.enrSeq, payload))
+  ok((pong.enrSeq, pong.payload_type, payload))
 
 proc findNodes*(
     p: PortalProtocol, dst: Node, distances: seq[uint16]
@@ -1774,7 +1774,7 @@ proc revalidateNode*(p: PortalProtocol, n: Node) {.async: (raises: [CancelledErr
   let pong = await p.ping(n)
 
   if pong.isOk():
-    let (enrSeq, _) = pong.get()
+    let (enrSeq, _, _) = pong.get()
     if enrSeq > n.record.seqNum:
       # Request new ENR
       let nodesMessage = await p.findNodes(n, @[0'u16])

fluffy/rpc/rpc_portal_common_api.nim

@@ -11,7 +11,8 @@ import
   std/[sequtils, json],
   json_rpc/rpcserver,
   stew/byteutils,
-  ../network/wire/[portal_protocol, portal_protocol_config],
+  results,
+  ../network/wire/[portal_protocol, portal_protocol_config, ping_extensions],
   ./rpc_types
 
 {.warning[UnusedImport]: off.}
@@ -75,16 +76,37 @@ proc installPortalCommonApiHandlers*(
     else:
       raise newException(ValueError, "Record not found in DHT lookup.")
 
-  rpcServer.rpc("portal_" & networkStr & "Ping") do(enr: Record) -> PingResult:
+  rpcServer.rpc("portal_" & networkStr & "Ping") do(
+    enr: Record, payloadType: Opt[uint16], payload: Opt[UnknownPayload]
+  ) -> PingResult:
+    if payloadType.isSome() and payloadType.get() != CapabilitiesType:
+      # We only support sending the default CapabilitiesPayload for now.
+      # This is fine because according to the spec clients are only required
+      # to support the standard extensions.
+      raise payloadTypeNotSupportedError()
+
+    if payload.isSome():
+      # We don't support passing in a custom payload. In order to implement
+      # this we use the empty UnknownPayload type which is defined in the spec
+      # as a json object with no required fields. Just using it here to indicate
+      # if an object was supplied or not and then throw the correct error if so.
+      raise userSpecifiedPayloadBlockedByClientError()
+
     let
       node = toNodeWithAddress(enr)
-      pong = await p.ping(node)
+      pong = (await p.ping(node)).valueOr:
+        raise newException(ValueError, $error)
 
-    if pong.isErr():
-      raise newException(ValueError, $pong.error)
-    else:
-      let (enrSeq, pongPayload) = pong.get()
-      return (enrSeq, pongPayload.data_radius)
+    let
+      (enrSeq, payloadType, capabilitiesPayload) = pong
+      clientInfo = capabilitiesPayload.client_info.asSeq()
+      payload = (
+        string.fromBytes(clientInfo),
+        capabilitiesPayload.data_radius,
+        capabilitiesPayload.capabilities.asSeq(),
+      )
+
+    return PingResult(enrSeq: enrSeq, payloadType: payloadType, payload: payload)
 
   rpcServer.rpc("portal_" & networkStr & "FindNodes") do(
     enr: Record, distances: seq[uint16]

fluffy/rpc/rpc_types.nim

@@ -17,16 +17,29 @@ import
 export jsonmarshal, routing_table, enr, node
 
 # Portal Network JSON-RPC errors
+
 const
   # These errors are defined in the portal jsonrpc spec: https://github.com/ethereum/portal-network-specs/tree/master/jsonrpc
   ContentNotFoundError* = (code: -39001, msg: "Content not found")
   ContentNotFoundErrorWithTrace* = (code: -39002, msg: "Content not found")
+  PayloadTypeNotSupportedError* = (code: -39004, msg: "Payload type not supported")
+  FailedToDecodePayloadError* = (code: -39005, msg: "Failed to decode payload")
+  PayloadTypeRequiredError* =
+    (code: -39006, msg: "Payload type is required if payload is specified")
+  UserSpecifiedPayloadBlockedByClientError* = (
+    code: -39007,
+    msg: "The client has blocked users from specifying the payload for this extension",
+  )
+
   # These errors are used by Fluffy but are not yet in the spec
   InvalidContentKeyError* = (code: -32602, msg: "Invalid content key")
   InvalidContentValueError* = (code: -32602, msg: "Invalid content value")
 
+template applicationError(error: (int, string)): auto =
+  (ref ApplicationError)(code: error.code, msg: error.msg)
+
 template contentNotFoundErr*(): auto =
-  (ref ApplicationError)(code: ContentNotFoundError.code, msg: ContentNotFoundError.msg)
+  ContentNotFoundError.applicationError()
 
 template contentNotFoundErrWithTrace*(data: typed): auto =
   (ref ApplicationError)(
@@ -35,15 +48,30 @@ template contentNotFoundErrWithTrace*(data: typed): auto =
     data: data,
   )
 
-template invalidKeyErr*(): auto =
-  (ref errors.InvalidRequest)(
-    code: InvalidContentKeyError.code, msg: InvalidContentKeyError.msg
+template payloadTypeNotSupportedError*(): auto =
+  (ref ApplicationError)(
+    code: PayloadTypeNotSupportedError.code,
+    msg: PayloadTypeNotSupportedError.msg,
+    data: Opt.some(JsonString("{ \"reason\" : \"client\" }")),
   )
 
+template failedToDecodePayloadError*(): auto =
+  FailedToDecodePayloadError.applicationError()
+
+template payloadTypeRequiredError*(): auto =
+  PayloadTypeRequiredError.applicationError()
+
+template userSpecifiedPayloadBlockedByClientError*(): auto =
+  UserSpecifiedPayloadBlockedByClientError.applicationError()
+
+template invalidRequest(error: (int, string)): auto =
+  (ref errors.InvalidRequest)(code: error.code, msg: error.msg)
+
+template invalidKeyErr*(): auto =
+  InvalidContentKeyError.invalidRequest()
+
 template invalidValueErr*(): auto =
-  (ref errors.InvalidRequest)(
-    code: InvalidContentValueError.code, msg: InvalidContentValueError.msg
-  )
+  InvalidContentValueError.invalidRequest()
 
 type
   NodeInfo* = object
@@ -54,7 +82,15 @@ type
     localNodeId*: NodeId
     buckets*: seq[seq[NodeId]]
 
-  PingResult* = tuple[enrSeq: uint64, dataRadius: UInt256]
+  UnknownPayload* = tuple[]
+
+  CapabilitiesPayload* =
+    tuple[clientInfo: string, dataRadius: UInt256, capabilities: seq[uint16]]
+
+  PingResult* = object
+    enrSeq*: uint64
+    payloadType*: uint16
+    payload*: CapabilitiesPayload
 
   ContentInfo* = object
     content*: string
@@ -68,6 +104,7 @@ type
 
 NodeInfo.useDefaultSerializationIn JrpcConv
 RoutingTableInfo.useDefaultSerializationIn JrpcConv
+PingResult.useDefaultSerializationIn JrpcConv
 (string, string).useDefaultSerializationIn JrpcConv
 ContentInfo.useDefaultSerializationIn JrpcConv
 PutContentResult.useDefaultSerializationIn JrpcConv
@@ -140,24 +177,30 @@ proc readValue*(
     r.raiseUnexpectedValue("seq[byte] parser error: " & exc.msg)
 
 proc writeValue*(
-    w: var JsonWriter[JrpcConv], v: PingResult
+    w: var JsonWriter[JrpcConv], v: CapabilitiesPayload
 ) {.gcsafe, raises: [IOError].} =
   w.beginRecord()
-  w.writeField("enrSeq", v.enrSeq)
+
+  w.writeField("clientInfo", v.clientInfo)
   # Portal json-rpc specifications allows for dropping leading zeroes.
   w.writeField("dataRadius", "0x" & v.dataRadius.toHex())
+  w.writeField("capabilities", v.capabilities)
+
   w.endRecord()
 
 proc readValue*(
-    r: var JsonReader[JrpcConv], val: var PingResult
+    r: var JsonReader[JrpcConv], val: var CapabilitiesPayload
 ) {.gcsafe, raises: [IOError, SerializationError].} =
   try:
     for field in r.readObjectFields():
       case field
-      of "enrSeq":
-        val.enrSeq = r.parseInt(uint64)
+      of "clientInfo":
+        val.clientInfo = r.parseString()
       of "dataRadius":
         val.dataRadius = UInt256.fromHex(r.parseString())
+      of "capabilities":
+        r.parseArray:
+          val.capabilities.add(r.parseInt(uint16))
       else:
         discard
   except ValueError as exc:
@@ -181,3 +224,21 @@ proc readValue*(
 
   if count != value.len():
     r.raiseUnexpectedValue("Array length mismatch")
+
+proc readValue*(
+    r: var JsonReader[JrpcConv], val: var Opt[uint16]
+) {.gcsafe, raises: [IOError, SerializationError].} =
+  if r.tokKind == JsonValueKind.Null:
+    reset val
+    r.parseNull()
+  else:
+    val.ok r.readValue(uint16)
+
+proc readValue*(
+    r: var JsonReader[JrpcConv], val: var Opt[UnknownPayload]
+) {.gcsafe, raises: [IOError, SerializationError].} =
+  if r.tokKind == JsonValueKind.Null:
+    reset val
+    r.parseNull()
+  else:
+    val.ok default(UnknownPayload)

fluffy/tests/wire_protocol_tests/test_portal_wire_protocol.nim

@@ -92,9 +92,10 @@ procSuite "Portal Wire Protocol Tests":
 
     check pong.isOk()
 
-    let (enrSeq, payload) = pong.value()
+    let (enrSeq, payloadType, payload) = pong.value()
     check:
       enrSeq == 1'u64
+      payloadType == 0
       payload == customPayload
 
     await proto1.stopPortalProtocol()