test(networking): add Discovery v5 routing distance test vectors (#632)

Extends NetworkingCodecTest with xor_distance and log2_distance codec
handlers. Adds 14 test vectors for the Kademlia distance functions that
underpin peer discovery and k-bucket assignment.

XOR distance vectors: self=0 (identity), symmetry, max distance
(inverted IDs), adjacent IDs, high bit difference.

Log2 distance vectors: self=0, spec nodes (bucket 253), max (bucket
256), and bucket boundary progression (1, 2, 8, 9, 256).

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: tcoratger

packages/testing/src/consensus_testing/test_fixtures/networking_codec.py

@@ -18,6 +18,7 @@
     TalkReq,
     TalkResp,
 )
+from lean_spec.subspecs.networking.discovery.routing import log2_distance, xor_distance
 from lean_spec.subspecs.networking.enr.enr import ENR
 from lean_spec.subspecs.networking.gossipsub.message import GossipsubMessage
 from lean_spec.subspecs.networking.gossipsub.rpc import (
@@ -40,7 +41,7 @@
     encode_request,
 )
 from lean_spec.subspecs.networking.transport.peer_id import KeyType, PeerId, PublicKeyProto
-from lean_spec.subspecs.networking.types import SeqNumber
+from lean_spec.subspecs.networking.types import NodeId, SeqNumber
 from lean_spec.subspecs.networking.varint import decode_varint, encode_varint
 
 from .base import BaseConsensusFixture
@@ -108,6 +109,10 @@ def make_fixture(self) -> "NetworkingCodecTest":
                 output = self._make_snappy_block()
             case "snappy_frame":
                 output = self._make_snappy_frame()
+            case "xor_distance":
+                output = self._make_xor_distance()
+            case "log2_distance":
+                output = self._make_log2_distance()
             case _:
                 raise ValueError(f"Unknown codec: {self.codec_name}")
         return self.model_copy(update={"output": output})
@@ -214,6 +219,20 @@ def _make_snappy_frame(self) -> dict[str, Any]:
             "uncompressedLength": len(data),
         }
 
+    def _make_xor_distance(self) -> dict[str, Any]:
+        """Compute XOR distance between two node IDs."""
+        node_a = NodeId(_from_hex(self.input["nodeA"]))
+        node_b = NodeId(_from_hex(self.input["nodeB"]))
+        distance = xor_distance(node_a, node_b)
+        return {"distance": hex(distance)}
+
+    def _make_log2_distance(self) -> dict[str, Any]:
+        """Compute log2 of XOR distance for k-bucket assignment."""
+        node_a = NodeId(_from_hex(self.input["nodeA"]))
+        node_b = NodeId(_from_hex(self.input["nodeB"]))
+        distance = int(log2_distance(node_a, node_b))
+        return {"distance": distance}
+
     def _make_enr(self) -> dict[str, Any]:
         """Parse an ENR string, re-serialize, assert roundtrip, extract properties."""
         enr_string = self.input["enrString"]

tests/consensus/devnet/networking/test_discovery_routing.py

@@ -0,0 +1,105 @@
+"""Test vectors for Discovery v5 distance computations.
+
+XOR distance and log2 distance are the foundation of Kademlia routing.
+Every client must compute identical distances for correct peer discovery
+and k-bucket assignment.
+"""
+
+import pytest
+from consensus_testing import NetworkingCodecTestFiller
+
+pytestmark = pytest.mark.valid_until("Devnet")
+
+# Official devp2p spec node IDs.
+NODE_A = "0xaaaa8419e9f49d0083561b48287df592939a8d19947d8c0ef88f2a4856a69fbb"
+NODE_B = "0xbbbb9d047f0488c0b5a93c1c3f2d8bafc7c8ff337024a55434a0d0555de64db9"
+
+ZERO = "0x" + "00" * 32
+MAX = "0x" + "ff" * 32
+ONE = "0x" + "00" * 31 + "01"
+TWO = "0x" + "00" * 31 + "02"
+HIGH_BIT = "0x80" + "00" * 31
+LOW_BYTE_80 = "0x" + "00" * 31 + "80"
+BUCKET_9 = "0x" + "00" * 30 + "0100"
+
+
+# --- XOR distance ---
+
+
+def test_xor_distance_self(networking_codec: NetworkingCodecTestFiller) -> None:
+    """XOR distance to self is always zero (identity property)."""
+    networking_codec(codec_name="xor_distance", input={"nodeA": NODE_A, "nodeB": NODE_A})
+
+
+def test_xor_distance_symmetric(networking_codec: NetworkingCodecTestFiller) -> None:
+    """d(A, B) == d(B, A) (symmetry property)."""
+    networking_codec(codec_name="xor_distance", input={"nodeA": NODE_A, "nodeB": NODE_B})
+
+
+def test_xor_distance_symmetric_reverse(
+    networking_codec: NetworkingCodecTestFiller,
+) -> None:
+    """Reverse order produces identical distance."""
+    networking_codec(codec_name="xor_distance", input={"nodeA": NODE_B, "nodeB": NODE_A})
+
+
+def test_xor_distance_max(networking_codec: NetworkingCodecTestFiller) -> None:
+    """XOR of zero and all-ones produces maximum distance (2^256 - 1)."""
+    networking_codec(codec_name="xor_distance", input={"nodeA": ZERO, "nodeB": MAX})
+
+
+def test_xor_distance_adjacent(networking_codec: NetworkingCodecTestFiller) -> None:
+    """XOR of 0x01 and 0x02 is 0x03 (lowest bits)."""
+    networking_codec(codec_name="xor_distance", input={"nodeA": ONE, "nodeB": TWO})
+
+
+def test_xor_distance_high_bit(networking_codec: NetworkingCodecTestFiller) -> None:
+    """Single high bit difference. Distance = 2^255."""
+    networking_codec(codec_name="xor_distance", input={"nodeA": HIGH_BIT, "nodeB": ZERO})
+
+
+# --- Log2 distance (k-bucket assignment) ---
+
+
+def test_log2_distance_self(networking_codec: NetworkingCodecTestFiller) -> None:
+    """Log2 distance to self is 0."""
+    networking_codec(codec_name="log2_distance", input={"nodeA": NODE_A, "nodeB": NODE_A})
+
+
+def test_log2_distance_spec_nodes(
+    networking_codec: NetworkingCodecTestFiller,
+) -> None:
+    """Log2 distance between official spec nodes A and B is 253."""
+    networking_codec(codec_name="log2_distance", input={"nodeA": NODE_A, "nodeB": NODE_B})
+
+
+def test_log2_distance_max(networking_codec: NetworkingCodecTestFiller) -> None:
+    """Maximum log2 distance is 256 (all bits differ)."""
+    networking_codec(codec_name="log2_distance", input={"nodeA": ZERO, "nodeB": MAX})
+
+
+def test_log2_distance_bucket_1(networking_codec: NetworkingCodecTestFiller) -> None:
+    """Single lowest bit difference lands in bucket 1."""
+    networking_codec(codec_name="log2_distance", input={"nodeA": ZERO, "nodeB": ONE})
+
+
+def test_log2_distance_bucket_2(networking_codec: NetworkingCodecTestFiller) -> None:
+    """Bit 1 set lands in bucket 2."""
+    networking_codec(codec_name="log2_distance", input={"nodeA": ZERO, "nodeB": TWO})
+
+
+def test_log2_distance_bucket_8(networking_codec: NetworkingCodecTestFiller) -> None:
+    """Byte boundary: 0x80 in last byte lands in bucket 8."""
+    networking_codec(codec_name="log2_distance", input={"nodeA": ZERO, "nodeB": LOW_BYTE_80})
+
+
+def test_log2_distance_bucket_9(networking_codec: NetworkingCodecTestFiller) -> None:
+    """0x0100 in last two bytes lands in bucket 9."""
+    networking_codec(codec_name="log2_distance", input={"nodeA": ZERO, "nodeB": BUCKET_9})
+
+
+def test_log2_distance_bucket_256(
+    networking_codec: NetworkingCodecTestFiller,
+) -> None:
+    """Highest bit only (0x80 in first byte) lands in bucket 256."""
+    networking_codec(codec_name="log2_distance", input={"nodeA": ZERO, "nodeB": HIGH_BIT})