From 5454c58e5529fb28d77540ba68caa89a4548e8a0 Mon Sep 17 00:00:00 2001
From: Harshit Nayan <harshitacademia@gmail.com>
Date: Sun, 7 Sep 2025 12:11:56 +0530
Subject: [PATCH] refactor: update metadata handling to use MetadataValue type
 alias

---
 libp2p/abc.py            | 24 ++++++++++++++----------
 libp2p/peer/peerdata.py  |  7 ++++---
 libp2p/peer/peerstore.py |  5 +++--
 3 files changed, 21 insertions(+), 15 deletions(-)

diff --git a/libp2p/abc.py b/libp2p/abc.py
index 964c74546..22ae6af31 100644
--- a/libp2p/abc.py
+++ b/libp2p/abc.py
@@ -17,6 +17,7 @@
     Any,
     AsyncContextManager,
     Optional,
+    Union,
 )
 
 from multiaddr import (
@@ -62,6 +63,9 @@
     ServiceAPI,
 )
 
+# Type alias for metadata values - JSON-serializable types
+MetadataValue = Union[str, int, float, bool, list, dict, None]
+
 # -------------------------- raw_connection interface.py --------------------------
 
 
@@ -377,7 +381,7 @@ class IPeerMetadata(ABC):
     """
 
     @abstractmethod
-    def get(self, peer_id: ID, key: str) -> Any:
+    def get(self, peer_id: ID, key: str) -> MetadataValue:
         """
         Retrieve metadata for a specified peer.
 
@@ -388,7 +392,7 @@ def get(self, peer_id: ID, key: str) -> Any:
         """
 
     @abstractmethod
-    def put(self, peer_id: ID, key: str, val: Any) -> None:
+    def put(self, peer_id: ID, key: str, val: MetadataValue) -> None:
         """
         Store metadata for a specified peer.
 
@@ -843,7 +847,7 @@ class IPeerStore(
 
     # -------METADATA---------
     @abstractmethod
-    def get(self, peer_id: ID, key: str) -> Any:
+    def get(self, peer_id: ID, key: str) -> MetadataValue:
         """
         Retrieve the value associated with a key for a specified peer.
 
@@ -856,7 +860,7 @@ def get(self, peer_id: ID, key: str) -> Any:
 
         Returns
         -------
-        Any
+        MetadataValue
             The value corresponding to the specified key.
 
         Raises
@@ -867,7 +871,7 @@ def get(self, peer_id: ID, key: str) -> Any:
         """
 
     @abstractmethod
-    def put(self, peer_id: ID, key: str, val: Any) -> None:
+    def put(self, peer_id: ID, key: str, val: MetadataValue) -> None:
         """
         Store a key-value pair for the specified peer.
 
@@ -877,7 +881,7 @@ def put(self, peer_id: ID, key: str, val: Any) -> None:
             The identifier of the peer.
         key : str
             The key for the data.
-        val : Any
+        val : MetadataValue
             The value to store.
 
         """
@@ -2132,7 +2136,7 @@ def clear_addrs(self) -> None:
         """
 
     @abstractmethod
-    def put_metadata(self, key: str, val: Any) -> None:
+    def put_metadata(self, key: str, val: MetadataValue) -> None:
         """
         Store a metadata key-value pair for the peer.
 
@@ -2140,13 +2144,13 @@ def put_metadata(self, key: str, val: Any) -> None:
         ----------
         key : str
             The metadata key.
-        val : Any
+        val : MetadataValue
             The value to associate with the key.
 
         """
 
     @abstractmethod
-    def get_metadata(self, key: str) -> IPeerMetadata:
+    def get_metadata(self, key: str) -> MetadataValue:
         """
         Retrieve metadata for a given key.
 
@@ -2157,7 +2161,7 @@ def get_metadata(self, key: str) -> IPeerMetadata:
 
         Returns
         -------
-        IPeerMetadata
+        MetadataValue
             The metadata value for the given key.
 
         Raises
diff --git a/libp2p/peer/peerdata.py b/libp2p/peer/peerdata.py
index 0d1a2f35b..27214671a 100644
--- a/libp2p/peer/peerdata.py
+++ b/libp2p/peer/peerdata.py
@@ -12,6 +12,7 @@
 
 from libp2p.abc import (
     IPeerData,
+    MetadataValue,
 )
 from libp2p.crypto.keys import (
     PrivateKey,
@@ -29,7 +30,7 @@
 class PeerData(IPeerData):
     pubkey: PublicKey | None
     privkey: PrivateKey | None
-    metadata: dict[Any, Any]
+    metadata: dict[str, MetadataValue]
     protocols: list[str]
     addrs: list[Multiaddr]
     last_identified: int
@@ -116,14 +117,14 @@ def clear_addrs(self) -> None:
         self.addrs = []
 
     # -------METADATA-----------
-    def put_metadata(self, key: str, val: Any) -> None:
+    def put_metadata(self, key: str, val: MetadataValue) -> None:
         """
         :param key: key in KV pair
         :param val: val to associate with key
         """
         self.metadata[key] = val
 
-    def get_metadata(self, key: str) -> Any:
+    def get_metadata(self, key: str) -> MetadataValue:
         """
         :param key: key in KV pair
         :return: val for key
diff --git a/libp2p/peer/peerstore.py b/libp2p/peer/peerstore.py
index ddf1af1f2..cf450a5b6 100644
--- a/libp2p/peer/peerstore.py
+++ b/libp2p/peer/peerstore.py
@@ -18,6 +18,7 @@
 from libp2p.abc import (
     IHost,
     IPeerStore,
+    MetadataValue,
 )
 from libp2p.crypto.keys import (
     KeyPair,
@@ -275,7 +276,7 @@ def clear_protocol_data(self, peer_id: ID) -> None:
 
     # ------METADATA---------
 
-    def get(self, peer_id: ID, key: str) -> Any:
+    def get(self, peer_id: ID, key: str) -> MetadataValue:
         """
         :param peer_id: peer ID to get peer data for
         :param key: the key to search value for
@@ -290,7 +291,7 @@ def get(self, peer_id: ID, key: str) -> Any:
             return val
         raise PeerStoreError("peer ID not found")
 
-    def put(self, peer_id: ID, key: str, val: Any) -> None:
+    def put(self, peer_id: ID, key: str, val: MetadataValue) -> None:
         """
         :param peer_id: peer ID to put peer data for
         :param key: