feat: add invalid account check when querying account balance

Signed-off-by: dosi <dosi.kolev@limechain.tech>

Author: Dosik13

examples/mirror_node_account_balance/main.go

@@ -33,8 +33,8 @@ func main() {
 	// Setting the client operator ID and key
 	client.SetOperator(operatorAccountID, operatorKey)
 
-	// MirrorNodeAccountBalanceQuery replaces the deprecated AccountBalanceQuery, which the
-	// consensus node stops serving in release 0.77. It reads from the mirror node REST API, so it
+	// MirrorNodeAccountBalanceQuery replaces AccountBalanceQuery, which the consensus node stops
+	// serving in release 0.77. It reads from the mirror node REST API, so it
 	// is free and needs no query payment.
 	balance, err := hiero.NewMirrorNodeAccountBalanceQuery().
 		SetAccountID(operatorAccountID).

sdk/errors.go

@@ -116,7 +116,8 @@ func (e ErrHederaNetwork) Error() string {
 }
 
 // ErrHederaPreCheckStatus is returned by Transaction.Execute and QueryBuilder.Execute if an exceptional status is
-// returned during _Network side validation of the sent transaction.
+// returned during _Network side validation of the sent transaction. MirrorNodeAccountBalanceQuery
+// also returns it, mapping an unknown account onto StatusInvalidAccountID.
 type ErrHederaPreCheckStatus struct {
 	TxID   TransactionID
 	Status Status

sdk/mirror_node_account_balance_query.go

@@ -4,13 +4,16 @@ package hiero
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
 	"net/url"
 )
 
 // MirrorNodeAccountBalanceQuery retrieves an account's or contract's hbar balance from the mirror
-// node REST API, replacing AccountBalanceQuery. It is free and requires no operator. The mirror node
-// trails the network by a few seconds, so results are not read-after-write consistent.
+// node REST API, replacing AccountBalanceQuery. It is free and requires no operator.
+//
+// The mirror node trails the network by a few seconds, so results are not read-after-write
+// consistent: a freshly created account fails with StatusInvalidAccountID until it is ingested.
 type MirrorNodeAccountBalanceQuery struct {
 	accountID   *AccountID
 	maxAttempts uint64
@@ -48,7 +51,7 @@ func (q *MirrorNodeAccountBalanceQuery) GetMaxAttempts() uint64 {
 	return q.maxAttempts
 }
 
-// Execute executes the Query with the provided client
+// Execute executes the query with the provided client
 func (q *MirrorNodeAccountBalanceQuery) Execute(client *Client) (MirrorNodeAccountBalance, error) {
 	if client == nil {
 		return MirrorNodeAccountBalance{}, errNoClientProvided
@@ -96,7 +99,6 @@ func (q *MirrorNodeAccountBalanceQuery) resolveAttempts(client *Client) uint64 {
 	return maxAttempts
 }
 
-// buildURL escapes the filter: an alias is opaque bytes and must not alter the query string.
 func (q *MirrorNodeAccountBalanceQuery) buildURL(mirrorBaseURL string) string {
 	params := url.Values{}
 	params.Set("account.id", q.accountID._MirrorNodePathID())
@@ -118,7 +120,6 @@ func (q *MirrorNodeAccountBalanceQuery) validateNetworkOnIDs(client *Client) err
 	return nil
 }
 
-// fetchAccountBalances GETs the balances endpoint through the shared retry core.
 func fetchAccountBalances(client *Client, endpoint string, attempts uint64) ([]byte, error) {
 	resp, err := mirrorNodeGetWithRetry(client, endpoint, attempts, mirrorNodeDefaultTimeout)
 	if err != nil {
@@ -128,16 +129,21 @@ func fetchAccountBalances(client *Client, endpoint string, attempts uint64) ([]b
 	return mirrorNodeReadBody(resp)
 }
 
-// parseAccountBalances reads an empty list as a zero balance: the endpoint returns one for an
-// unknown account rather than a 404, so zero is not proof the account exists.
+// parseAccountBalances maps an empty balances list onto StatusInvalidAccountID, the status
+// AccountBalanceQuery returned for an unknown account. The endpoint reports one as 200 with no rows.
 func parseAccountBalances(body []byte) (MirrorNodeAccountBalance, error) {
 	var raw accountBalancesResponseJSON
 	if err := json.Unmarshal(body, &raw); err != nil {
 		return MirrorNodeAccountBalance{}, fmt.Errorf("failed to unmarshal response: %w", err)
 	}
 
+	if raw.Balances == nil {
+		return MirrorNodeAccountBalance{}, errors.New("mirror node response has no balances array")
+	}
+
+	// An existing account with no hbar returns "balance": 0, so an empty list only means unknown.
 	if len(raw.Balances) == 0 {
-		return MirrorNodeAccountBalance{Hbars: HbarFromTinybar(0)}, nil
+		return MirrorNodeAccountBalance{}, ErrHederaPreCheckStatus{Status: StatusInvalidAccountID}
 	}
 
 	return MirrorNodeAccountBalance{Hbars: HbarFromTinybar(raw.Balances[0].Balance)}, nil
@@ -149,6 +155,5 @@ type accountBalancesResponseJSON struct {
 }
 
 type accountBalanceJSON struct {
-	Account string `json:"account"`
-	Balance int64  `json:"balance"`
+	Balance int64 `json:"balance"`
 }

sdk/mirror_node_account_balance_query_e2e_test.go

@@ -5,6 +5,7 @@ package hiero
 // SPDX-License-Identifier: Apache-2.0
 
 import (
+	"fmt"
 	"testing"
 	"time"
 
@@ -32,6 +33,10 @@ func mirrorHbarBalanceEventually(env *IntegrationTestEnv, query *MirrorNodeAccou
 		}
 	}
 
+	if err == nil {
+		err = fmt.Errorf("mirror node did not reach the expected state within %d attempts", mirrorHbarBalanceRetryAttempts)
+	}
+
 	return balance, err
 }
 
@@ -160,6 +165,16 @@ func TestIntegrationMirrorNodeAccountBalanceQueryCanGetContractBalance(t *testin
 	require.NoError(t, err)
 	contractID := *receipt.ContractID
 
+	defer func() {
+		_, err := NewContractDeleteTransaction().
+			SetContractID(contractID).
+			SetTransferAccountID(env.Client.GetOperatorAccountID()).
+			Execute(env.Client)
+		require.NoError(t, err)
+		_, err = NewFileDeleteTransaction().SetFileID(fileID).Execute(env.Client)
+		require.NoError(t, err)
+	}()
+
 	contractAccountID := AccountID{Shard: contractID.Shard, Realm: contractID.Realm, Account: contractID.Contract}
 
 	tx, err := NewTransferTransaction().
@@ -178,26 +193,18 @@ func TestIntegrationMirrorNodeAccountBalanceQueryCanGetContractBalance(t *testin
 	require.NoError(t, err)
 	assert.Equal(t, NewHbar(1).AsTinybar(), balance.Hbars.AsTinybar())
 
-	_, err = NewContractDeleteTransaction().
-		SetContractID(contractID).
-		SetTransferAccountID(env.Client.GetOperatorAccountID()).
-		Execute(env.Client)
-	require.NoError(t, err)
-	_, err = NewFileDeleteTransaction().
-		SetFileID(fileID).
-		Execute(env.Client)
-	require.NoError(t, err)
 }
 
-func TestIntegrationMirrorNodeAccountBalanceQueryNonExistentAccountIsZero(t *testing.T) {
+func TestIntegrationMirrorNodeAccountBalanceQueryNonExistentAccountErrors(t *testing.T) {
 	t.Parallel()
 	env := NewIntegrationTestEnv(t)
 	defer CloseIntegrationTestEnv(env, nil)
 
-	balance, err := NewMirrorNodeAccountBalanceQuery().
+	_, err := NewMirrorNodeAccountBalanceQuery().
 		SetAccountID(AccountID{Account: 999999999}).
 		Execute(env.Client)
 
-	require.NoError(t, err, "an unknown account is an empty balances array, not an error")
-	assert.Zero(t, balance.Hbars.AsTinybar())
+	var status ErrHederaPreCheckStatus
+	require.ErrorAs(t, err, &status)
+	assert.Equal(t, StatusInvalidAccountID, status.Status)
 }

sdk/mirror_node_account_balance_query_unit_test.go

@@ -5,6 +5,7 @@ package hiero
 // SPDX-License-Identifier: Apache-2.0
 
 import (
+	"errors"
 	"fmt"
 	"net/http"
 	"net/url"
@@ -116,32 +117,47 @@ func TestUnitMirrorNodeAccountBalanceQueryResolvesPublicKeyAlias(t *testing.T) {
 	assert.Equal(t, gotAccountID, url.QueryEscape(gotAccountID), "alias must need no escaping")
 }
 
-func TestUnitMirrorNodeAccountBalanceQueryResolvesContractID(t *testing.T) {
+func TestUnitMirrorNodeAccountBalanceQueryNonExistentAccountErrors(t *testing.T) {
 	var gotAccountID string
-	client := newMockMirrorClient(t, "contract.example.com:443", balancesHandler(t, &gotAccountID,
-		`{"balances":[{"account":"0.0.98765","balance":777}]}`))
+	client := newMockMirrorClient(t, "missing.example.com:443", balancesHandler(t, &gotAccountID,
+		`{"timestamp":null,"balances":[],"links":{"next":null}}`))
+
+	_, err := NewMirrorNodeAccountBalanceQuery().
+		SetAccountID(AccountID{Account: 999999999}).
+		Execute(client)
+
+	var status ErrHederaPreCheckStatus
+	require.ErrorAs(t, err, &status)
+	assert.Equal(t, StatusInvalidAccountID, status.Status)
+	assert.Contains(t, err.Error(), "INVALID_ACCOUNT_ID")
+}
+
+func TestUnitMirrorNodeAccountBalanceQueryZeroBalanceIsNotMissing(t *testing.T) {
+	var gotAccountID string
+	client := newMockMirrorClient(t, "zerobalance.example.com:443", balancesHandler(t, &gotAccountID,
+		`{"balances":[{"account":"0.0.42","balance":0}]}`))
 
-	contractID := ContractID{Shard: 0, Realm: 0, Contract: 98765}
 	balance, err := NewMirrorNodeAccountBalanceQuery().
-		SetAccountID(AccountID{Shard: contractID.Shard, Realm: contractID.Realm, Account: contractID.Contract}).
+		SetAccountID(AccountID{Account: 42}).
 		Execute(client)
 
 	require.NoError(t, err)
-	assert.Equal(t, HbarFromTinybar(777), balance.Hbars)
-	assert.Equal(t, "0.0.98765", gotAccountID)
+	assert.Zero(t, balance.Hbars.AsTinybar())
 }
 
-func TestUnitMirrorNodeAccountBalanceQueryNonExistentAccountIsZero(t *testing.T) {
+func TestUnitMirrorNodeAccountBalanceQueryMissingBalancesArrayIsMalformed(t *testing.T) {
 	var gotAccountID string
-	client := newMockMirrorClient(t, "missing.example.com:443", balancesHandler(t, &gotAccountID,
-		`{"timestamp":null,"balances":[],"links":{"next":null}}`))
+	client := newMockMirrorClient(t, "nobalances.example.com:443", balancesHandler(t, &gotAccountID,
+		`{"timestamp":null,"links":{"next":null}}`))
 
-	balance, err := NewMirrorNodeAccountBalanceQuery().
-		SetAccountID(AccountID{Account: 999999999}).
+	_, err := NewMirrorNodeAccountBalanceQuery().
+		SetAccountID(AccountID{Account: 7}).
 		Execute(client)
 
-	require.NoError(t, err, "an empty balances array is a zero balance, not an error")
-	assert.Equal(t, HbarFromTinybar(0), balance.Hbars)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "no balances array")
+	var status ErrHederaPreCheckStatus
+	assert.False(t, errors.As(err, &status), "a malformed payload must not read as a missing account")
 }
 
 func TestUnitMirrorNodeAccountBalanceQueryNoAccountIDErrorsBeforeRequest(t *testing.T) {

sdk/mirror_node_rest_helpers.go

@@ -25,8 +25,7 @@ const (
 )
 
 // mirrorNodeRestBaseURL returns the client's mirror node REST API base URL, erroring when no
-// mirror network is configured. A caller whose endpoint is served on a different port against a
-// local node overrides it afterwards.
+// mirror network is configured.
 func mirrorNodeRestBaseURL(client *Client) (string, error) {
 	if client == nil {
 		return "", errNoClientProvided

sdk/mirror_node_rest_helpers_unit_test.go

@@ -176,7 +176,7 @@ func TestUnitMirrorNodeValidateURL(t *testing.T) {
 }
 
 // A URL no request could satisfy must fail before the retry loop spends its budget on it.
-func TestUnitMirrorNodeGetAndPostRejectInvalidURLWithoutRequesting(t *testing.T) {
+func TestUnitMirrorNodeGetAndPostRejectInvalidURL(t *testing.T) {
 	client, err := _NewMockClient()
 	require.NoError(t, err)
 
@@ -285,18 +285,18 @@ func TestUnitMirrorNodeWalkPagesFollowsNextAcrossPages(t *testing.T) {
 func TestUnitMirrorNodeWalkPagesStopsAtPageCap(t *testing.T) {
 	t.Parallel()
 
-	const cap = 3
+	const maxPages = 3
 	pages := 0
 	forever := "/api/v1/things?page=next"
 
-	err := mirrorNodeWalkPages("https://mirror.example.com/api/v1/things", cap,
+	err := mirrorNodeWalkPages("https://mirror.example.com/api/v1/things", maxPages,
 		func(pageURL string) ([]byte, error) { pages++; return []byte(`{}`), nil },
 		func(body []byte) (*string, error) { return &forever, nil },
 	)
 
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "exceeded pagination cap of 3 pages")
-	assert.Equal(t, cap, pages, "no more than the cap may be fetched")
+	assert.Equal(t, maxPages, pages, "no more than the cap may be fetched")
 }
 
 func TestUnitMirrorNodeWalkPagesPropagatesErrors(t *testing.T) {

sdk/registered_node_address_book_query.go

@@ -93,9 +93,8 @@ func (q *RegisteredNodeAddressBookQuery) Execute(client *Client) (RegisteredNode
 	return q.walkPages(endpoint, q.resolveAttempts(client))
 }
 
-// resolveEndpoint discovers the mirror node REST base URL on the client and
-// returns the initial query URL. A local node serves this endpoint on 8084
-// rather than the default mirrorNodeRestBaseURL port.
+// resolveEndpoint returns the initial query URL. A local node serves this
+// endpoint on 8084 rather than on the client's mirror REST port.
 func (q *RegisteredNodeAddressBookQuery) resolveEndpoint(client *Client) (string, error) {
 	mirrorUrl, err := mirrorNodeRestBaseURL(client)
 	if err != nil {