feat: implement GeneralServiceEndpoint and add lifecycle example for HIP-1137

danielmarv · danielmarv · commit e6e6a16bea9d · 2026-04-23T12:21:44.000+03:00
Signed-off-by: Ntege Daniel &lt;danientege785@gmail.com&gt;
diff --git a/docs/sdk_developers/hip_1137_coverage.md b/docs/sdk_developers/hip_1137_coverage.md
@@ -0,0 +1,51 @@
+# HIP-1137 Coverage in hiero-sdk-python
+
+This document maps HIP-1137 concepts to current SDK implementation status.
+
+## Covered Concepts
+
+- `BlockNodeApi` enum: [src/hiero_sdk_python/address_book/block_node_api.py](../../src/hiero_sdk_python/address_book/block_node_api.py)
+- `RegisteredServiceEndpoint` base type with IP/FQDN one-of validation:
+  [src/hiero_sdk_python/address_book/registered_service_endpoint.py](../../src/hiero_sdk_python/address_book/registered_service_endpoint.py)
+- Endpoint subtypes:
+  - Block: [src/hiero_sdk_python/address_book/block_node_service_endpoint.py](../../src/hiero_sdk_python/address_book/block_node_service_endpoint.py)
+  - Mirror: [src/hiero_sdk_python/address_book/mirror_node_service_endpoint.py](../../src/hiero_sdk_python/address_book/mirror_node_service_endpoint.py)
+  - RPC relay: [src/hiero_sdk_python/address_book/rpc_relay_service_endpoint.py](../../src/hiero_sdk_python/address_book/rpc_relay_service_endpoint.py)
+  - General service (deferred/public API not exposed yet): [src/hiero_sdk_python/address_book/general_service_endpoint.py](../../src/hiero_sdk_python/address_book/general_service_endpoint.py)
+- Registered node transactions:
+  - Create: [src/hiero_sdk_python/nodes/registered_node_create_transaction.py](../../src/hiero_sdk_python/nodes/registered_node_create_transaction.py)
+  - Update: [src/hiero_sdk_python/nodes/registered_node_update_transaction.py](../../src/hiero_sdk_python/nodes/registered_node_update_transaction.py)
+  - Delete: [src/hiero_sdk_python/nodes/registered_node_delete_transaction.py](../../src/hiero_sdk_python/nodes/registered_node_delete_transaction.py)
+- `TransactionReceipt.registered_node_id`:
+  [src/hiero_sdk_python/transaction/transaction_receipt.py](../../src/hiero_sdk_python/transaction/transaction_receipt.py)
+- Consensus node association fields:
+  - Create: [src/hiero_sdk_python/nodes/node_create_transaction.py](../../src/hiero_sdk_python/nodes/node_create_transaction.py)
+  - Update (including clear semantics): [src/hiero_sdk_python/nodes/node_update_transaction.py](../../src/hiero_sdk_python/nodes/node_update_transaction.py)
+- Registered node read models:
+  - [src/hiero_sdk_python/address_book/registered_node.py](../../src/hiero_sdk_python/address_book/registered_node.py)
+  - [src/hiero_sdk_python/address_book/registered_node_address_book.py](../../src/hiero_sdk_python/address_book/registered_node_address_book.py)
+
+## Deferred Concept (Intentional)
+
+- `RegisteredNodeAddressBookQuery` execution is intentionally deferred until mirror-node API support is defined, matching HIP guidance:
+  [src/hiero_sdk_python/address_book/registered_node_address_book_query.py](../../src/hiero_sdk_python/address_book/registered_node_address_book_query.py)
+- `GeneralServiceEndpoint` protobuf subtype is not present in the currently generated schema for this repository. The SDK includes internal forward-compatible handling, but it is not a stable public top-level API until protobuf support lands.
+
+## Tests
+
+- Endpoint tests (including general subtype when protobuf supports it):
+  [tests/unit/registered_service_endpoint_test.py](../../tests/unit/registered_service_endpoint_test.py)
+- Registered-node transaction tests:
+  - [tests/unit/registered_node_create_transaction_test.py](../../tests/unit/registered_node_create_transaction_test.py)
+  - [tests/unit/registered_node_update_transaction_test.py](../../tests/unit/registered_node_update_transaction_test.py)
+  - [tests/unit/registered_node_delete_transaction_test.py](../../tests/unit/registered_node_delete_transaction_test.py)
+- Node association tests:
+  - [tests/unit/node_create_transaction_test.py](../../tests/unit/node_create_transaction_test.py)
+  - [tests/unit/node_update_transaction_test.py](../../tests/unit/node_update_transaction_test.py)
+- Receipt field test:
+  [tests/unit/test_transaction_receipt.py](../../tests/unit/test_transaction_receipt.py)
+
+## Example
+
+- Registered node lifecycle example:
+  [examples/nodes/registered_node_lifecycle.py](../../examples/nodes/registered_node_lifecycle.py)
diff --git a/examples/nodes/registered_node_lifecycle.py b/examples/nodes/registered_node_lifecycle.py
@@ -0,0 +1,130 @@
+"""
+Demonstrates a HIP-1137 registered-node lifecycle.
+
+This example shows:
+1. Create a registered node with one or more service endpoints.
+2. Read the registered_node_id from the transaction receipt.
+3. Update the registered node metadata.
+4. Associate the registered node with an existing consensus node.
+5. Delete the registered node.
+
+Notes:
+- This flow needs network support for HIP-1137 features.
+- GeneralServiceEndpoint is deferred until protobuf support is available.
+- RegisteredNodeAddressBookQuery remains unavailable until mirror-node APIs are defined.
+"""
+
+from __future__ import annotations
+
+import os
+
+from dotenv import load_dotenv
+
+from hiero_sdk_python import (
+    AccountId,
+    BlockNodeApi,
+    BlockNodeServiceEndpoint,
+    Client,
+    NodeUpdateTransaction,
+    PrivateKey,
+    RegisteredNodeCreateTransaction,
+    RegisteredNodeDeleteTransaction,
+    RegisteredNodeUpdateTransaction,
+    ResponseCode,
+)
+from hiero_sdk_python.address_book.general_service_endpoint import (
+    GeneralServiceEndpoint,
+)
+
+
+def _must_env(key: str) -> str:
+    value = os.getenv(key)
+    if not value:
+        raise ValueError(f"Missing environment variable: {key}")
+    return value
+
+
+def registered_node_lifecycle() -> None:
+    load_dotenv()
+
+    operator_id = AccountId.from_string(_must_env("OPERATOR_ID"))
+    operator_key = PrivateKey.from_string(_must_env("OPERATOR_KEY"))
+    node_id_to_update = int(_must_env("CONSENSUS_NODE_ID"))
+
+    client = Client.for_testnet()
+    client.set_operator(operator_id, operator_key)
+
+    registered_node_admin_key = PrivateKey.generate_ed25519()
+
+    block_endpoint = BlockNodeServiceEndpoint(
+        domain_name="block.example.com",
+        port=443,
+        requires_tls=True,
+        endpoint_api=BlockNodeApi.SUBSCRIBE_STREAM,
+    )
+
+    create_tx = (
+        RegisteredNodeCreateTransaction()
+        .set_admin_key(registered_node_admin_key.public_key())
+        .set_description("Example block node")
+        .add_service_endpoint(block_endpoint)
+        .freeze_with(client)
+        .sign(registered_node_admin_key)
+    )
+
+    create_receipt = create_tx.execute(client)
+    if create_receipt.status != ResponseCode.SUCCESS:
+        raise RuntimeError(f"Create failed with status: {ResponseCode(create_receipt.status).name}")
+
+    registered_node_id = create_receipt.registered_node_id
+    if registered_node_id is None:
+        raise RuntimeError("Create succeeded but no registered_node_id was returned.")
+
+    update_tx = (
+        RegisteredNodeUpdateTransaction()
+        .set_registered_node_id(registered_node_id)
+        .set_description("Updated block node")
+        .add_service_endpoint(block_endpoint)
+    )
+
+    try:
+        update_tx = update_tx.add_service_endpoint(
+            GeneralServiceEndpoint(
+                domain_name="general.example.com",
+                port=443,
+                requires_tls=True,
+                description="General endpoint",
+            )
+        )
+    except NotImplementedError:
+        # Current protobuf/network does not support this subtype yet.
+        print("Skipping GeneralServiceEndpoint: unavailable in current protobuf schema.")
+
+    update_receipt = update_tx.freeze_with(client).sign(registered_node_admin_key).execute(client)
+    if update_receipt.status != ResponseCode.SUCCESS:
+        raise RuntimeError(f"Update failed with status: {ResponseCode(update_receipt.status).name}")
+
+    associate_receipt = (
+        NodeUpdateTransaction()
+        .set_node_id(node_id_to_update)
+        .add_associated_registered_node(registered_node_id)
+        .execute(client)
+    )
+    if associate_receipt.status != ResponseCode.SUCCESS:
+        raise RuntimeError(f"Node association failed with status: {ResponseCode(associate_receipt.status).name}")
+
+    delete_receipt = (
+        RegisteredNodeDeleteTransaction()
+        .set_registered_node_id(registered_node_id)
+        .freeze_with(client)
+        .sign(registered_node_admin_key)
+        .execute(client)
+    )
+    if delete_receipt.status != ResponseCode.SUCCESS:
+        raise RuntimeError(f"Delete failed with status: {ResponseCode(delete_receipt.status).name}")
+
+    print(f"Lifecycle complete for registered node id: {registered_node_id}")
+
+
+if __name__ == "__main__":
+    registered_node_lifecycle()
diff --git a/src/hiero_sdk_python/address_book/general_service_endpoint.py b/src/hiero_sdk_python/address_book/general_service_endpoint.py
@@ -0,0 +1,73 @@
+"""Registered general service endpoint."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from hiero_sdk_python.address_book.registered_service_endpoint import (
+    RegisteredServiceEndpoint,
+)
+from hiero_sdk_python.hapi.services.registered_service_endpoint_pb2 import (
+    RegisteredServiceEndpoint as RegisteredServiceEndpointProto,
+)
+
+
+@dataclass(eq=True)
+class GeneralServiceEndpoint(RegisteredServiceEndpoint):
+    """A registered endpoint for a general-purpose service."""
+
+    description: str | None = None
+    MAX_DESCRIPTION_BYTES = 100
+
+    def __post_init__(self) -> None:
+        """Run base endpoint validation and validate optional description."""
+        super().__post_init__()
+        if self.description is not None and len(self.description.encode("utf-8")) > self.MAX_DESCRIPTION_BYTES:
+            raise ValueError("description must not exceed 100 UTF-8 bytes.")
+
+    @classmethod
+    def _resolve_general_endpoint_descriptor(
+        cls,
+    ) -> tuple[str, type[Any]]:
+        """Resolve the endpoint_type oneof entry and nested protobuf message for general endpoints."""
+        endpoint_type_oneof = RegisteredServiceEndpointProto.DESCRIPTOR.oneofs_by_name.get("endpoint_type")
+        if endpoint_type_oneof is None:
+            raise NotImplementedError("RegisteredServiceEndpoint endpoint_type oneof is unavailable in this protobuf.")
+
+        for field in endpoint_type_oneof.fields:
+            message_type = field.message_type
+            if message_type is not None and "General" in message_type.name:
+                nested_type = getattr(RegisteredServiceEndpointProto, message_type.name, None)
+                if nested_type is None:
+                    raise NotImplementedError(
+                        "General service endpoint nested protobuf type is unavailable in this protobuf."
+                    )
+                return field.name, nested_type
+
+        raise NotImplementedError("General service endpoints are unavailable in this protobuf version.")
+
+    def _endpoint_type_proto(self) -> dict[str, Any]:
+        """Return the protobuf general-service subtype."""
+        field_name, nested_type = self._resolve_general_endpoint_descriptor()
+        endpoint_proto = nested_type()
+
+        if self.description is not None:
+            if not hasattr(endpoint_proto, "description"):
+                raise NotImplementedError(
+                    "General service endpoint descriptions are unavailable in this protobuf version."
+                )
+            endpoint_proto.description = self.description
+
+        return {field_name: endpoint_proto}
+
+    @classmethod
+    def _from_proto(cls, proto: RegisteredServiceEndpointProto) -> GeneralServiceEndpoint:
+        """Build a general service endpoint from protobuf."""
+        field_name, _ = cls._resolve_general_endpoint_descriptor()
+        endpoint_proto = getattr(proto, field_name)
+        description = endpoint_proto.description if hasattr(endpoint_proto, "description") else None
+        return cls(
+            description=description or None,
+            **cls._base_kwargs_from_proto(proto),
+        )
diff --git a/src/hiero_sdk_python/address_book/registered_service_endpoint.py b/src/hiero_sdk_python/address_book/registered_service_endpoint.py
@@ -159,4 +159,17 @@ def _from_proto(cls, proto: RegisteredServiceEndpointProto) -> RegisteredService
 
             return RpcRelayServiceEndpoint._from_proto(proto)
 
+        if endpoint_type is not None:
+            field_descriptor = proto.DESCRIPTOR.fields_by_name.get(endpoint_type)
+            if (
+                field_descriptor is not None
+                and field_descriptor.message_type is not None
+                and "General" in field_descriptor.message_type.name
+            ):
+                from hiero_sdk_python.address_book.general_service_endpoint import (
+                    GeneralServiceEndpoint,
+                )
+
+                return GeneralServiceEndpoint._from_proto(proto)
+
         raise ValueError("Registered service endpoint type is required.")
diff --git a/tests/unit/registered_service_endpoint_test.py b/tests/unit/registered_service_endpoint_test.py
@@ -6,6 +6,9 @@
 from hiero_sdk_python.address_book.block_node_service_endpoint import (
     BlockNodeServiceEndpoint,
 )
+from hiero_sdk_python.address_book.general_service_endpoint import (
+    GeneralServiceEndpoint,
+)
 from hiero_sdk_python.address_book.mirror_node_service_endpoint import (
     MirrorNodeServiceEndpoint,
 )
@@ -15,10 +18,24 @@
 from hiero_sdk_python.address_book.rpc_relay_service_endpoint import (
     RpcRelayServiceEndpoint,
 )
+from hiero_sdk_python.hapi.services.registered_service_endpoint_pb2 import (
+    RegisteredServiceEndpoint as RegisteredServiceEndpointProto,
+)
 
 pytestmark = pytest.mark.unit
 
 
+def _supports_general_service_endpoint() -> bool:
+    """Return whether this protobuf build includes the general endpoint subtype."""
+    endpoint_type_oneof = RegisteredServiceEndpointProto.DESCRIPTOR.oneofs_by_name.get("endpoint_type")
+    if endpoint_type_oneof is None:
+        return False
+
+    return any(
+        field.message_type is not None and "General" in field.message_type.name for field in endpoint_type_oneof.fields
+    )
+
+
 def test_block_node_service_endpoint_roundtrip():
     """Block node endpoints should round-trip through protobuf."""
     endpoint = BlockNodeServiceEndpoint(
@@ -57,6 +74,25 @@ def test_rpc_relay_service_endpoint_roundtrip():
     assert roundtrip == endpoint
 
 
+def test_general_service_endpoint_roundtrip():
+    """General service endpoints should round-trip when supported by protobuf."""
+    if not _supports_general_service_endpoint():
+        pytest.skip("General service endpoint is unavailable in this protobuf version.")
+
+    endpoint = GeneralServiceEndpoint(
+        domain_name="general.example.com",
+        port=443,
+        requires_tls=True,
+        description="General node service",
+    )
+
+    proto = endpoint._to_proto()
+    roundtrip = RegisteredServiceEndpoint._from_proto(proto)
+
+    assert isinstance(roundtrip, GeneralServiceEndpoint)
+    assert roundtrip == endpoint
+
+
 def test_registered_service_endpoint_requires_exactly_one_address():
     """Endpoints must use either an IP address or a domain name."""
     with pytest.raises(ValueError, match="Exactly one of ip_address or domain_name must be set."):
