hiero-ledger / hiero-ledger/hiero-sdk-java

Deprecate AccountBalanceQuery

Open
#2,851 1 comment 0 reactions 1 assignee Claimed by @mustafauzunn View on GitHub
Dominant language
Java
Stars
264
Forks
192
Avg merge
2d
Merged PRs (30d)
39

Description

# Deprecate `AccountBalanceQuery`

## Background

The consensus node is removing the `CryptoService/cryptoGetBalance` endpoint in release **0.77** (decision final). The query has **already been removed from the previewnet, testnet, and mainnet throttle configurations**, and [hiero-consensus-node#26457](https://github.com/hiero-ledger/hiero-consensus-node/issues/26457) removes it from the genesis throttle config, test-clients/yahcli, and marks it deprecated in the protobufs.

This issue implements the SDK side per the collaboration hub proposal:
- [AccountBalanceQuery Deprecation](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/proposals/account-balance-query-deprecation.md)
- Companion: [AccountBalanceQuery Mirror Node Migration](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/proposals/account-balance-query-mirror-node-migration.md) (replacement class — tracked in #2852)

> **Note — corrections to the proposals (do not follow the proposal verbatim on these points):**
> 1. The two proposals describe themselves as "mutually exclusive." In practice **both** are being implemented: `AccountBalanceQuery` gets the hard-error behavior from the deprecation proposal, **and** `MirrorNodeAccountBalanceQuery` is added as the replacement (#2852). There is no functional "migration window" — the network throttle configs already reject the query.
> 2. **Update (Aug 2026):** the proposal now ships in **two stages**. Replacing the `Client.ping()` / `pingAsync()` / `pingAll()` probe is **Stage 1**, tracked separately in #2867, and must land **before the release 77 testnet rollout (est. August 13, 2026)** using `getAccountInfo(0.0.2)` with `ResponseType = COST_ANSWER` — the previously discussed gRPC health/connectivity check was evaluated and is **not implemented** on Hedera consensus nodes. This issue is **Stage 2** (deprecation only), targeted **at or before the mainnet rollout (est. September 9, 2026)**; Stage 1 must complete first. The Solo-readiness dependency now hangs on #2867, not this issue.
> 3. The proposal's error message points generically to "the mirror node REST API." Since `MirrorNodeAccountBalanceQuery` is being implemented, the message should point to it (text below).

## Scope

### 1. Deprecate `AccountBalanceQuery`

- Annotate the class with `@Deprecated` and add a Javadoc `@deprecated` tag pointing to `MirrorNodeAccountBalanceQuery`, so IDEs and linters flag every call site.
- On construction, log a warning once via the SDK logger:
```
Deprecated: AccountBalanceQuery is no longer supported. Use MirrorNodeAccountBalanceQuery or the mirror node REST API (GET /api/v1/accounts/{id}) to retrieve account balances.
```
- Override the internal execution path so `execute()` / `executeAsync()` **throw immediately without making any network call**, with the same message. No public fields or methods are added or removed.

### 2. Audit remaining internal usages

Grep the repo for all other `AccountBalanceQuery` usages (examples, integration tests, docs, internal helpers) and migrate or remove them — the `Client.ping()` / `pingAsync()` / `pingAll()` path itself is migrated in #2867 (Stage 1). The XTS dry run on the CN side surfaced hidden dependencies — assume there are more.

## Acceptance criteria

1. Constructing an `AccountBalanceQuery` logs the deprecation warning.
2. `execute()` / `executeAsync()` throw the deprecation error **without any network call to a consensus node**.
3. No remaining internal code path constructs or executes `AccountBalanceQuery` (examples/docs updated; ping path handled in #2867).
4. Unit tests for 1–2; the no-network-call check (2) is the critical one.

## References

- CN issue: https://github.com/hiero-ledger/hiero-consensus-node/issues/26457
- Stage 1 (ping replacement): #2867
- TCK coverage is tracked separately in `hiero-ledger/hiero-sdk-tck` per the proposal's test plan.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.