feat: HIP-1137

.github/workflows/build.yml

@@ -176,7 +176,7 @@ jobs:
 
       - name: Prepare Hiero Solo
         id: solo
-        uses: hiero-ledger/hiero-solo-action@328bc84c3b00a990a151418144fd682a4eb76ea6 # v0.17
+        uses: hiero-ledger/hiero-solo-action@4d42a74e8e644a2753f3bb7a2afa429305375b14 # v0.16
         with:
           installMirrorNode: true
           soloVersion: v0.65.0
@@ -255,8 +255,8 @@ jobs:
           installMirrorNode: true
           soloVersion: v0.65.0
           dualMode: true
-          hieroVersion: v0.68.0
-          mirrorNodeVersion: v0.142.0
+          hieroVersion: v0.73.0
+          mirrorNodeVersion: v0.153.0
 
       - name: Build SDK
         run: ./gradlew assemble

examples/src/main/java/com/hedera/hashgraph/sdk/examples/RegisteredNodeLifeCycleExample.java

@@ -0,0 +1,173 @@
+// SPDX-License-Identifier: Apache-2.0
+package com.hedera.hashgraph.sdk.examples;
+
+import com.hedera.hashgraph.sdk.AccountId;
+import com.hedera.hashgraph.sdk.BlockNodeApi;
+import com.hedera.hashgraph.sdk.BlockNodeServiceEndpoint;
+import com.hedera.hashgraph.sdk.Client;
+import com.hedera.hashgraph.sdk.NodeUpdateTransaction;
+import com.hedera.hashgraph.sdk.PrivateKey;
+import com.hedera.hashgraph.sdk.RegisteredNodeCreateTransaction;
+import com.hedera.hashgraph.sdk.RegisteredNodeDeleteTransaction;
+import com.hedera.hashgraph.sdk.RegisteredNodeUpdateTransaction;
+import com.hedera.hashgraph.sdk.TransactionReceipt;
+import com.hedera.hashgraph.sdk.TransactionResponse;
+import com.hedera.hashgraph.sdk.logger.LogLevel;
+import com.hedera.hashgraph.sdk.logger.Logger;
+import io.github.cdimascio.dotenv.Dotenv;
+import java.util.List;
+import java.util.Objects;
+
+public class RegisteredNodeLifeCycleExample {
+    /*
+     * See .env.sample in the examples folder root for how to specify values below
+     * or set environment variables with the same names.
+     */
+
+    /**
+     * Operator's account ID.
+     * Used to sign and pay for operations on Hedera.
+     */
+    private static final AccountId OPERATOR_ID =
+            AccountId.fromString(Objects.requireNonNull(Dotenv.load().get("OPERATOR_ID")));
+
+    /**
+     * Operator's private key.
+     */
+    private static final PrivateKey OPERATOR_KEY =
+            PrivateKey.fromString(Objects.requireNonNull(Dotenv.load().get("OPERATOR_KEY")));
+
+    /**
+     * HEDERA_NETWORK defaults to testnet if not specified in dotenv file.
+     * Network can be: localhost, testnet, previewnet or mainnet.
+     */
+    private static final String HEDERA_NETWORK = Dotenv.load().get("HEDERA_NETWORK", "testnet");
+
+    /**
+     * SDK_LOG_LEVEL defaults to SILENT if not specified in dotenv file.
+     * Log levels can be: TRACE, DEBUG, INFO, WARN, ERROR, SILENT.
+     * <p>
+     * Important pre-requisite: set simple logger log level to same level as the SDK_LOG_LEVEL,
+     * for example via VM options: -Dorg.slf4j.simpleLogger.log.org.hiero=trace
+     */
+    private static final String SDK_LOG_LEVEL = Dotenv.load().get("SDK_LOG_LEVEL", "SILENT");
+
+    public static void main(String[] args) throws Exception {
+        System.out.println("Registered Node Lifecycle Example Start!");
+
+        /*
+         * Step 0:
+         * Create and configure the SDK Client.
+         */
+        Client client = ClientHelper.forName(HEDERA_NETWORK);
+        // All generated transactions will be paid by this account and signed by this key.
+        client.setOperator(OPERATOR_ID, OPERATOR_KEY);
+        // Attach logger to the SDK Client.
+        client.setLogger(new Logger(LogLevel.valueOf(SDK_LOG_LEVEL)));
+
+        /*
+         * Step 1:
+         * Generate an admin key pair and configure a BlockNodeServiceEndpoint
+         * for use in the RegisterNodeTransaction.
+         */
+        PrivateKey adminKey = PrivateKey.generateED25519();
+        BlockNodeServiceEndpoint initialEndpoint = new BlockNodeServiceEndpoint()
+                .setIpAddress(new byte[] {127, 0, 0, 1})
+                .setPort(443)
+                .setRequiresTls(true)
+                .addEndpointApi(BlockNodeApi.SUBSCRIBE_STREAM);
+
+        /*
+         * Step 2:
+         * Create Registered Node.
+         */
+        RegisteredNodeCreateTransaction registeredNodeCreateTx = new RegisteredNodeCreateTransaction()
+                .setDescription("My Block Node")
+                .setAdminKey(adminKey)
+                .addServiceEndpoint(initialEndpoint)
+                .freezeWith(client)
+                .sign(adminKey);
+
+        System.out.println("Creating Registered Node...");
+        TransactionResponse registeredNodeCreateTxResponse = registeredNodeCreateTx.execute(client);
+        TransactionReceipt registeredNodeCreateTxReceipt = registeredNodeCreateTxResponse.getReceipt(client);
+
+        if (registeredNodeCreateTxReceipt.registeredNodeId <= 0) {
+            throw new Exception("RegisteredNodeCreate transaction receipt was missing registeredNodeId. (Fail)");
+        }
+
+        long registeredNodeId = registeredNodeCreateTxReceipt.registeredNodeId;
+
+        /*
+         * Step 3:
+         * Execute a RegisteredNodeAddressBookQuery to verify the newly created
+         * registered node appears in the RegisteredNodeAddressBook.
+         */
+        System.out.println("Skipping registered node address book query because mirror node API is not available...");
+
+        /*
+         * Step 4:
+         * Update the RegisteredNode with new Block Node endpoint.
+         */
+        BlockNodeServiceEndpoint updateEndpoint = new BlockNodeServiceEndpoint()
+                .setDomainName("block-node.example.com")
+                .setPort(443)
+                .setRequiresTls(true)
+                .addEndpointApi(BlockNodeApi.STATUS);
+
+        RegisteredNodeUpdateTransaction registeredNodeUpdateTx = new RegisteredNodeUpdateTransaction()
+                .setRegisteredNodeId(registeredNodeId)
+                .setDescription("My Updated Block Node")
+                .setServiceEndpoints(List.of(initialEndpoint, updateEndpoint))
+                .freezeWith(client)
+                .sign(adminKey);
+
+        System.out.println("Updating Registered Node...");
+        TransactionResponse registeredNodeUpdateTxResponse = registeredNodeUpdateTx.execute(client);
+        registeredNodeUpdateTxResponse.getReceipt(client);
+
+        /*
+         * Step 5:
+         * Add the registeredNodeId as associatedRegisteredNodes to a Node.
+         */
+
+        NodeUpdateTransaction associateTx = new NodeUpdateTransaction()
+                .setNodeId(0)
+                .addAssociatedRegisteredNode(registeredNodeId)
+                .freezeWith(client);
+
+        System.out.println("Associating registered node " + registeredNodeId + " with consensus node...");
+        TransactionResponse associateTxResponse = associateTx.execute(client);
+        associateTxResponse.getReceipt(client);
+
+        /*
+         * Step 6:
+         * Remove the registeredNodeId as associatedRegisteredNodes from a Node.
+         */
+
+        NodeUpdateTransaction disassociateTx = new NodeUpdateTransaction()
+                .setNodeId(0)
+                .setAssociatedRegisteredNodes(List.of()) // Empty list clear associated registeredNode
+                .freezeWith(client);
+
+        System.out.println("Disassociating registered node " + registeredNodeId + " with consensus node...");
+        disassociateTx.execute(client);
+        associateTxResponse.getReceipt(client);
+
+        /*
+         * Step 7:
+         * Delete the Registered Node.
+         */
+        System.out.println("Deleting Registered Node...");
+        new RegisteredNodeDeleteTransaction()
+                .setRegisteredNodeId(registeredNodeCreateTxReceipt.registeredNodeId)
+                .freezeWith(client)
+                .sign(adminKey)
+                .execute(client)
+                .getReceipt(client);
+
+        client.close();
+
+        System.out.println("Registered Node Lifecycle Example Complete!");
+    }
+}

sdk/src/main/java/com/hedera/hashgraph/sdk/BlockNodeApi.java

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+package com.hedera.hashgraph.sdk;
+
+import com.hedera.hashgraph.sdk.proto.RegisteredServiceEndpoint.BlockNodeEndpoint;
+
+/**
+ * An enumeration of well-known block node endpoint APIs.
+ */
+public enum BlockNodeApi {
+    /**
+     * Any other API type associated with a block node.
+     */
+    OTHER(BlockNodeEndpoint.BlockNodeApi.OTHER),
+
+    /**
+     * The Block Node Status API.
+     */
+    STATUS(BlockNodeEndpoint.BlockNodeApi.STATUS),
+
+    /**
+     * The Block Node Publish API.
+     */
+    PUBLISH(BlockNodeEndpoint.BlockNodeApi.PUBLISH),
+
+    /**
+     * The Block Node Subscribe Stream API.
+     */
+    SUBSCRIBE_STREAM(BlockNodeEndpoint.BlockNodeApi.SUBSCRIBE_STREAM),
+
+    /**
+     * The Block Node State Proof API.
+     */
+    STATE_PROOF(BlockNodeEndpoint.BlockNodeApi.STATE_PROOF);
+
+    final BlockNodeEndpoint.BlockNodeApi code;
+
+    BlockNodeApi(BlockNodeEndpoint.BlockNodeApi code) {
+        this.code = code;
+    }
+
+    static BlockNodeApi valueOf(BlockNodeEndpoint.BlockNodeApi code) {
+        return switch (code) {
+            case OTHER -> OTHER;
+            case STATUS -> STATUS;
+            case PUBLISH -> PUBLISH;
+            case SUBSCRIBE_STREAM -> SUBSCRIBE_STREAM;
+            case STATE_PROOF -> STATE_PROOF;
+            default -> throw new IllegalArgumentException("Unhandled BlockNodeApi code");
+        };
+    }
+
+    @Override
+    public String toString() {
+        return code.name();
+    }
+}

sdk/src/main/java/com/hedera/hashgraph/sdk/BlockNodeServiceEndpoint.java

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: Apache-2.0
+package com.hedera.hashgraph.sdk;
+
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.protobuf.ByteString;
+import com.hedera.hashgraph.sdk.proto.RegisteredServiceEndpoint;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+import java.util.stream.Collectors;
+
+/**
+ * Represent a Registered Block Node
+ */
+public class BlockNodeServiceEndpoint extends RegisteredServiceEndpointBase<BlockNodeServiceEndpoint> {
+    /**
+     * An indicator of what API this endpoint supports.
+     */
+    private List<BlockNodeApi> endpointApis = new ArrayList<>();
+
+    /**
+     * Constructor.
+     */
+    public BlockNodeServiceEndpoint() {}
+
+    /**
+     * Returns the list of APIs supported by this endpoint.
+     *
+     * @return the list of supported block node APIs
+     */
+    public List<BlockNodeApi> getEndpointApis() {
+        return endpointApis;
+    }
+
+    /**
+     * Sets the list of APIs supported by this endpoint.
+     *
+     * @param endpointApis the list of APIs to support; must not be null
+     * @return {@code this}
+     */
+    public BlockNodeServiceEndpoint setEndpointApis(List<BlockNodeApi> endpointApis) {
+        Objects.requireNonNull(endpointApis, "endpointApis must not be null");
+        this.endpointApis = new ArrayList<>(endpointApis);
+        return this;
+    }
+
+    /**
+     * Adds a single API to the list of supported APIs for this endpoint.
+     *
+     * @param endpointApi the API to add; must not be null
+     * @return {@code this}
+     */
+    public BlockNodeServiceEndpoint addEndpointApi(BlockNodeApi endpointApi) {
+        Objects.requireNonNull(endpointApi, "endpointApi must not be null");
+        this.endpointApis.add(endpointApi);
+        return this;
+    }
+
+    /**
+     * Create a BlockNodeServiceEndpoint object from protobuf
+     *
+     * @param serviceEndpoint the protobuf object
+     * @return the new instance of BlockNodeServiceEndpoint
+     */
+    static BlockNodeServiceEndpoint fromProtobuf(
+            com.hedera.hashgraph.sdk.proto.RegisteredServiceEndpoint serviceEndpoint) {
+        Objects.requireNonNull(serviceEndpoint, "serviceEndpoint must not be null");
+
+        var blockNodeEndpoint = new BlockNodeServiceEndpoint()
+                .setPort(serviceEndpoint.getPort())
+                .setRequiresTls(serviceEndpoint.getRequiresTls());
+
+        if (serviceEndpoint.hasBlockNode()) {
+            for (var apiProto : serviceEndpoint.getBlockNode().getEndpointApiList()) {
+                blockNodeEndpoint.addEndpointApi(BlockNodeApi.valueOf(apiProto));
+            }
+        }
+
+        if (serviceEndpoint.hasIpAddress()) {
+            blockNodeEndpoint.setIpAddress(serviceEndpoint.getIpAddress().toByteArray());
+        }
+
+        if (serviceEndpoint.hasDomainName()) {
+            blockNodeEndpoint.setDomainName(serviceEndpoint.getDomainName());
+        }
+
+        return blockNodeEndpoint;
+    }
+
+    @Override
+    com.hedera.hashgraph.sdk.proto.RegisteredServiceEndpoint toProtobuf() {
+        if (ipAddress == null && domainName == null) {
+            throw new IllegalArgumentException(
+                    "RegisterServiceEndpoint must define either an ipAddress or  domainName");
+        }
+
+        var blockNodeBuilder = RegisteredServiceEndpoint.BlockNodeEndpoint.newBuilder()
+                .addAllEndpointApi(endpointApis.stream().map(api -> api.code).toList());
+
+        var registeredServiceEndpoint = com.hedera.hashgraph.sdk.proto.RegisteredServiceEndpoint.newBuilder()
+                .setPort(port)
+                .setRequiresTls(requiresTls)
+                .setBlockNode(blockNodeBuilder);
+
+        if (ipAddress != null) {
+            registeredServiceEndpoint.setIpAddress(ByteString.copyFrom(this.ipAddress));
+        }
+
+        if (domainName != null) {
+            registeredServiceEndpoint.setDomainName(this.domainName);
+        }
+
+        return registeredServiceEndpoint.build();
+    }
+
+    /**
+     * Parses BlockNodeServiceEndpoint from the type-specific JSON object the MirrorNode.
+     *
+     * @param json the json containing block node specific data
+     * @return {@code this}
+     */
+    static BlockNodeServiceEndpoint fromJson(JsonObject json) {
+        Objects.requireNonNull(json, "json must not be null");
+
+        List<String> apis = new ArrayList<>();
+        if (json.has("endpoint_apis")) {
+            for (JsonElement api : json.getAsJsonArray("endpoint_apis")) {
+                apis.add(api.getAsString());
+            }
+        }
+
+        return new BlockNodeServiceEndpoint()
+                .setEndpointApis(
+                        apis.stream().map(a -> BlockNodeApi.valueOf(a)).collect(Collectors.toUnmodifiableList()));
+    }
+
+    @Override
+    public String toString() {
+        return toStringHelper().add("endpointApis", endpointApis).toString();
+    }
+}