feat: MirrorNodeAccountBalanceQuery (#2895)

Signed-off-by: Mustafa Uzun <mustafa.uzun@limechain.tech>

Author: mustafauzunn

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

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: Apache-2.0
 package com.hedera.hashgraph.sdk.examples;
 
-import com.hedera.hashgraph.sdk.AccountBalanceQuery;
 import com.hedera.hashgraph.sdk.AccountId;
 import com.hedera.hashgraph.sdk.Client;
 import com.hedera.hashgraph.sdk.Hbar;
+import com.hedera.hashgraph.sdk.MirrorNodeAccountBalanceQuery;
 import com.hedera.hashgraph.sdk.logger.LogLevel;
 import com.hedera.hashgraph.sdk.logger.Logger;
 import io.github.cdimascio.dotenv.Dotenv;
@@ -49,18 +49,22 @@ public static void main(String[] args) throws Exception {
          * Step 0:
          * Create and configure the SDK Client.
          *
-         * Because AccountBalanceQuery is a free query, we can make it without setting an operator on the client.
+         * Because MirrorNodeAccountBalanceQuery is a free query, we can make it without setting an operator
+         * on the client.
          */
         Client client = ClientHelper.forName(HEDERA_NETWORK);
         // Attach logger to the SDK Client.
         client.setLogger(new Logger(LogLevel.valueOf(SDK_LOG_LEVEL)));
 
         /*
          * Step 1:
-         * Execute AccountBalanceQuery and output operator's account balance.
+         * Execute MirrorNodeAccountBalanceQuery and output operator's account balance.
+         *
+         * Note: the mirror node is eventually consistent, so a balance read immediately after a
+         * transaction may lag the network by a few seconds.
          */
         Hbar operatorsBalance =
-                new AccountBalanceQuery().setAccountId(OPERATOR_ID).execute(client).hbars;
+                new MirrorNodeAccountBalanceQuery().setAccountId(OPERATOR_ID).execute(client).hbars;
 
         System.out.println("Operator's Hbar account balance: " + operatorsBalance);
 

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

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: Apache-2.0
+package com.hedera.hashgraph.sdk;
+
+import com.google.common.base.MoreObjects;
+import com.google.gson.JsonArray;
+import com.google.gson.JsonObject;
+import java.util.Objects;
+import javax.annotation.Nullable;
+
+/**
+ * The HBAR balance of an account as reported by the mirror node REST API.
+ *
+ * <p>Returned by {@link MirrorNodeAccountBalanceQuery}. Token balances are not included.
+ */
+public final class MirrorNodeAccountBalance {
+    /**
+     * The HBAR balance of the account.
+     */
+    public final Hbar hbars;
+
+    /**
+     * Constructor.
+     *
+     * @param hbars the HBAR balance of the account
+     */
+    MirrorNodeAccountBalance(Hbar hbars) {
+        this.hbars = Objects.requireNonNull(hbars);
+    }
+
+    /**
+     * Create a balance from a mirror node REST JSON payload.
+     *
+     * <p>The mirror node reports an account it does not know with an empty {@code balances} array — not
+     * a 404. That case is signalled by returning {@code null}; the caller decides how to report it. An
+     * account that exists but holds no HBAR is a populated entry with {@code "balance": 0} and is parsed
+     * normally, so a genuine zero is never mistaken for a missing account.
+     *
+     * @param root the JSON object returned by {@code GET /api/v1/balances}
+     * @return the new balance, or {@code null} if the mirror node knows no such account
+     * @throws IllegalStateException if the payload is not a well-formed balances response
+     */
+    @Nullable
+    static MirrorNodeAccountBalance fromJson(JsonObject root) {
+        if (!root.has("balances") || root.get("balances").isJsonNull()) {
+            throw new IllegalStateException("Mirror Node returned a malformed response: no `balances` array");
+        }
+
+        JsonArray balances = root.getAsJsonArray("balances");
+        if (balances.isEmpty()) {
+            return null;
+        }
+
+        JsonObject balance = balances.get(0).getAsJsonObject();
+        if (!balance.has("balance") || balance.get("balance").isJsonNull()) {
+            throw new IllegalStateException(
+                    "Mirror Node returned a malformed response: balances entry has no `balance` field");
+        }
+
+        return new MirrorNodeAccountBalance(
+                Hbar.fromTinybars(balance.get("balance").getAsLong()));
+    }
+
+    /**
+     * Extract the HBAR balance.
+     *
+     * @return the HBAR balance of the account
+     */
+    public Hbar getHbars() {
+        return hbars;
+    }
+
+    @Override
+    public String toString() {
+        return MoreObjects.toStringHelper(this).add("hbars", hbars).toString();
+    }
+}