hiero-ledger / hiero-ledger/hiero-sdk-java
Deprecate AccountBalanceQuery
- 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
Assessment
This issue has not been assessed yet.