feat: add HIP-1137 registered node address book models

Signed-off-by: Ntege Daniel <danientege785@gmail.com>

Author: danielmarv

src/hiero_sdk_python/__init__.py

@@ -15,6 +15,9 @@
 from .address_book.general_service_endpoint import GeneralServiceEndpoint
 from .address_book.mirror_node_service_endpoint import MirrorNodeServiceEndpoint
 from .address_book.node_address import NodeAddress
+from .address_book.registered_node import RegisteredNode
+from .address_book.registered_node_address_book import RegisteredNodeAddressBook
+from .address_book.registered_node_address_book_query import RegisteredNodeAddressBookQuery
 from .address_book.registered_service_endpoint import RegisteredServiceEndpoint
 from .address_book.rpc_relay_service_endpoint import RpcRelayServiceEndpoint
 
@@ -247,6 +250,9 @@
     # Address book
     "Endpoint",
     "NodeAddress",
+    "RegisteredNode",
+    "RegisteredNodeAddressBook",
+    "RegisteredNodeAddressBookQuery",
     # Logger
     "Logger",
     "LogLevel",

src/hiero_sdk_python/address_book/registered_node.py

@@ -0,0 +1,80 @@
+"""Read-side model for a HIP-1137 registered node."""
+
+from __future__ import annotations
+
+from hiero_sdk_python.address_book.registered_service_endpoint import RegisteredServiceEndpoint
+from hiero_sdk_python.crypto.public_key import PublicKey
+from hiero_sdk_python.hapi.services.state.addressbook.registered_node_pb2 import (
+    RegisteredNode as RegisteredNodeProto,
+)
+
+
+class RegisteredNode:
+    """Immutable model representing a registered node from network/mirror state."""
+
+    def __init__(
+        self,
+        registered_node_id: int,
+        admin_key: PublicKey | None = None,
+        description: str | None = None,
+        service_endpoints: tuple[RegisteredServiceEndpoint, ...] = (),
+    ) -> None:
+        if not isinstance(registered_node_id, int) or isinstance(registered_node_id, bool):
+            raise ValueError("registered_node_id must be a positive integer")
+        if registered_node_id <= 0:
+            raise ValueError("registered_node_id must be a positive integer")
+
+        self._registered_node_id = registered_node_id
+        self._admin_key = admin_key
+        self._description = description
+        self._service_endpoints = tuple(service_endpoints)
+
+    @property
+    def registered_node_id(self) -> int:
+        return self._registered_node_id
+
+    @property
+    def admin_key(self) -> PublicKey | None:
+        return self._admin_key
+
+    @property
+    def description(self) -> str | None:
+        return self._description
+
+    @property
+    def service_endpoints(self) -> tuple[RegisteredServiceEndpoint, ...]:
+        return self._service_endpoints
+
+    @classmethod
+    def _from_proto(cls, proto: RegisteredNodeProto) -> RegisteredNode:
+        """Create a RegisteredNode from a protobuf RegisteredNode state message."""
+        admin_key: PublicKey | None = None
+        if proto.HasField("admin_key"):
+            admin_key = PublicKey._from_proto(proto.admin_key)
+
+        description: str | None = proto.description if proto.description else None
+
+        endpoints = tuple(RegisteredServiceEndpoint._from_proto(ep) for ep in proto.service_endpoint)
+
+        return cls(
+            registered_node_id=proto.registered_node_id,
+            admin_key=admin_key,
+            description=description,
+            service_endpoints=endpoints,
+        )
+
+    def _to_proto(self) -> RegisteredNodeProto:
+        """Convert this RegisteredNode to a protobuf RegisteredNode."""
+        proto = RegisteredNodeProto(
+            registered_node_id=self._registered_node_id,
+        )
+        if self._admin_key is not None:
+            proto.admin_key.CopyFrom(self._admin_key._to_proto())
+        if self._description is not None:
+            proto.description = self._description
+        for ep in self._service_endpoints:
+            proto.service_endpoint.append(ep._to_proto())
+        return proto
+
+    def __repr__(self) -> str:
+        return f"RegisteredNode(registered_node_id={self._registered_node_id}, description={self._description!r})"

src/hiero_sdk_python/address_book/registered_node_address_book.py

@@ -0,0 +1,35 @@
+"""Read-side container for a collection of HIP-1137 registered nodes."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from hiero_sdk_python.address_book.registered_node import RegisteredNode
+
+
+class RegisteredNodeAddressBook:
+    """Immutable container of :class:`RegisteredNode` entries.
+
+    No protobuf ``RegisteredNodeAddressBook`` message exists in the current
+    protobufs, so this is a pure SDK-side convenience wrapper that mirrors
+    the role of the legacy ``NodeAddressBook`` model.
+    """
+
+    def __init__(self, nodes: tuple[RegisteredNode, ...] = ()) -> None:
+        self._nodes = tuple(nodes)
+
+    @property
+    def nodes(self) -> tuple[RegisteredNode, ...]:
+        return self._nodes
+
+    def __len__(self) -> int:
+        return len(self._nodes)
+
+    def __iter__(self) -> Iterator[RegisteredNode]:
+        return iter(self._nodes)
+
+    def __getitem__(self, index: int) -> RegisteredNode:
+        return self._nodes[index]
+
+    def __repr__(self) -> str:
+        return f"RegisteredNodeAddressBook(nodes={len(self._nodes)})"

src/hiero_sdk_python/address_book/registered_node_address_book_query.py

@@ -0,0 +1,45 @@
+"""Skeleton query for fetching the registered-node address book (HIP-1137)."""
+
+from __future__ import annotations
+
+from hiero_sdk_python.address_book.registered_node_address_book import RegisteredNodeAddressBook
+
+
+class RegisteredNodeAddressBookQuery:
+    """Query to retrieve the registered-node address book from the network.
+
+    .. warning::
+
+        Query execution is **not yet available**. The mirror-node API endpoint
+        required by this query has not been implemented in this SDK release.
+        Calling :meth:`execute` will raise :class:`NotImplementedError`.
+    """
+
+    def __init__(self) -> None:
+        self._max_registered_node_count: int | None = None
+
+    def set_max_registered_node_count(self, count: int) -> RegisteredNodeAddressBookQuery:
+        """Limit the number of registered nodes returned.
+
+        Args:
+            count: Maximum number of nodes. Must be positive.
+
+        Returns:
+            This query instance for method chaining.
+        """
+        if not isinstance(count, int) or isinstance(count, bool) or count <= 0:
+            raise ValueError("count must be a positive integer")
+        self._max_registered_node_count = count
+        return self
+
+    def execute(self, client: object = None) -> RegisteredNodeAddressBook:
+        """Execute the query against the network.
+
+        Raises:
+            NotImplementedError: Always. Mirror-node API support for
+                registered-node queries is not yet available in this SDK.
+        """
+        raise NotImplementedError(
+            "RegisteredNodeAddressBookQuery requires HIP-1137 mirror node API support, "
+            "which is not yet available in this SDK."
+        )