Implement HIP-1137 — Block Node discoverability via on-chain registry

[rwalworth]

Summary

The Hiero Java SDK does not currently support the registered node registry introduced by HIP-1137. This issue tracks the implementation of full SDK support for creating, updating, deleting, and discovering registered nodes (Block Nodes, mirror nodes, and RPC relays) via on-chain data.

The implementation should follow the SDK design document and align with the patterns established by the existing consensus node transactions (NodeCreateTransaction, NodeUpdateTransaction, NodeDeleteTransaction).

Problem

HIP-1137 adds three new transactions to the AddressBookService and extends several existing types. Without SDK support, developers must resort to raw protobuf construction to interact with the registered node registry.

Key gaps:

• No RegisteredNodeCreateTransaction, RegisteredNodeUpdateTransaction, or RegisteredNodeDeleteTransaction classes
• No RegisteredServiceEndpoint hierarchy (BlockNodeServiceEndpoint, MirrorNodeServiceEndpoint, RpcRelayServiceEndpoint)
• No BlockNodeApi enum
• TransactionReceipt does not expose the registeredNodeId field
• NodeCreateTransaction and NodeUpdateTransaction do not support the new associatedRegisteredNodes field
• No RegisteredNode, RegisteredNodeAddressBook, or RegisteredNodeAddressBookQuery types

Scope of Work

New transaction types

• RegisteredNodeCreateTransaction — creates a registered node with an adminKey, optional description, optional nodeAccountId, and a list of service endpoints (1–50). On success the receipt contains the network-assigned registeredNodeId.
• RegisteredNodeUpdateTransaction — updates an existing registered node by registeredNodeId. Supports changing adminKey (requires both old and new key signatures), description, nodeAccountId, and replacing the service endpoint list.
• RegisteredNodeDeleteTransaction — removes a registered node by registeredNodeId. Must be signed by the node's adminKey or authorized by network governance.

All three transactions must be schedulable via ScheduleCreateTransaction.

New data types

• BlockNodeApi enum — OTHER, STATUS, PUBLISH, SUBSCRIBE_STREAM, STATE_PROOF.
• RegisteredServiceEndpoint — abstract base with ipAddress (bytes) or domainName (string), port, and requiresTls. Three concrete subtypes:
  • BlockNodeServiceEndpoint — adds endpointApi: BlockNodeApi
  • MirrorNodeServiceEndpoint — empty subtype (future-proofing)
  • RpcRelayServiceEndpoint — empty subtype (future-proofing)
• RegisteredNode — immutable representation of a registered node as stored in network state.
• RegisteredNodeAddressBook — collection of RegisteredNode objects.

New query type

• RegisteredNodeAddressBookQuery — queries the mirror node for registered nodes and returns a RegisteredNodeAddressBook. Implementation should be deferred until the mirror node API is available, but the class skeleton should be defined.

Updates to existing types

• TransactionReceipt — add nullable registeredNodeId field.
• NodeCreateTransaction — add associatedRegisteredNodes list and addAssociatedRegisteredNode(long registeredNodeId).
• NodeUpdateTransaction — add nullable associatedRegisteredNodes list, addAssociatedRegisteredNode(long registeredNodeId), and clearAssociatedRegisteredNodes(). The protobuf uses a wrapper message for three-state semantics (not set / empty list / non-empty list).

Wiring

• Register the new transaction types in the Transaction dispatch logic (Transaction.java) for fromBytes() deserialization.
• Map to protobuf DataCase values and schedulable body fields.

Implementation Notes

Patterns to follow

The existing NodeCreateTransaction / NodeUpdateTransaction / NodeDeleteTransaction in sdk/src/main/java/com/hedera/hashgraph/sdk/ serve as the primary reference. Each new registered node transaction should:

• Extend the base Transaction<T> class
• Implement onFreeze(TransactionBody.Builder) and fromProtobuf(TransactionBody) methods
• Support scheduling via ScheduleCreateTransaction

Endpoint hierarchy

The design document specifies inheritance-based endpoints. In Java this maps to:

• An abstract RegisteredServiceEndpoint class holding shared fields (ipAddress, domainName, port, requiresTls)
• BlockNodeServiceEndpoint extending the base with endpointApi
• MirrorNodeServiceEndpoint and RpcRelayServiceEndpoint as currently empty subtypes

Each subtype needs fromProtobuf() / toProtobuf() round-trip support, following the pattern in Endpoint.java.

Key files to create or modify

New files (under sdk/src/main/java/com/hedera/hashgraph/sdk/):

• RegisteredNodeCreateTransaction.java
• RegisteredNodeUpdateTransaction.java
• RegisteredNodeDeleteTransaction.java
• RegisteredServiceEndpoint.java
• BlockNodeServiceEndpoint.java
• MirrorNodeServiceEndpoint.java
• RpcRelayServiceEndpoint.java
• BlockNodeApi.java
• RegisteredNode.java
• RegisteredNodeAddressBook.java
• RegisteredNodeAddressBookQuery.java

Existing files to update:

• TransactionReceipt.java — add registeredNodeId
• NodeCreateTransaction.java — add associatedRegisteredNodes
• NodeUpdateTransaction.java — add associatedRegisteredNodes with three-state wrapper semantics
• Transaction.java — register new types in the deserialization dispatch
• Proto definitions in sdk/src/main/proto/

Protobuf dependencies

The implementation depends on new protobuf definitions from HIP-1137:

• registered_node_create.proto
• registered_node_update.proto
• registered_node_delete.proto
• registered_service_endpoint.proto (or equivalent)
• Updated transaction_body.proto (fields 78–80)
• Updated schedulable_transaction_body.proto (fields 49–51)
• Updated transaction_receipt.proto (field 16)

Testing strategy

1. Unit tests — verify serialization round-trips for all new types, field validation, and getter/setter correctness.
2. Integration tests — execute the full registered node lifecycle against a test network:
   • Create a registered node with various endpoint types and verify the receipt contains a registeredNodeId
   • Update the node's description, endpoints, and admin key
   • Associate a registered node with a consensus node
   • Delete the registered node
   • Verify failure cases (missing admin key, empty endpoints, non-existent node ID, already-deleted node)
3. TCK alignment — corresponding test cases should be defined in the TCK repository per the design document's 18-point test plan.

Acceptance Criteria

• Implement RegisteredNodeCreateTransaction, RegisteredNodeUpdateTransaction, and RegisteredNodeDeleteTransaction following existing transaction patterns
• Implement the RegisteredServiceEndpoint hierarchy (BlockNodeServiceEndpoint, MirrorNodeServiceEndpoint, RpcRelayServiceEndpoint) and the BlockNodeApi enum
• Implement RegisteredNode and RegisteredNodeAddressBook data types
• Define the RegisteredNodeAddressBookQuery class skeleton
• Update TransactionReceipt to expose registeredNodeId
• Update NodeCreateTransaction and NodeUpdateTransaction with associatedRegisteredNodes support
• Register new transaction types in Transaction dispatch
• Ensure all three new transactions are schedulable
• Include unit tests for serialization, field validation, and getter/setter correctness
• Include integration tests covering the registered node lifecycle
• Maintain backwards compatibility with existing APIs
• Pass all CI checks

References

• HIP-1137 specification: https://github.com/hiero-ledger/hiero-improvement-proposals/blob/main/HIP/hip-1137.md
• SDK design document: https://github.com/hiero-ledger/sdk-collaboration-hub/blob/hip-1137/proposals/hips/hip-1137.md
• HIP discussion: HIP-1137: Block Node Discoverability hiero-improvement-proposals#1137
• Existing consensus node transaction patterns:
  • sdk/src/main/java/com/hedera/hashgraph/sdk/NodeCreateTransaction.java
  • sdk/src/main/java/com/hedera/hashgraph/sdk/NodeUpdateTransaction.java
  • sdk/src/main/java/com/hedera/hashgraph/sdk/NodeDeleteTransaction.java
• Existing endpoint pattern:
  • sdk/src/main/java/com/hedera/hashgraph/sdk/Endpoint.java

[manishdait]

@0xivanov, could you assign this to me