Implement ping and pingAll JSON-RPC methods

[aceppaluni]

Problem

The TCK server does not implement ping / pingAll, so the TCK driver's ClientPing suite cannot run against the Python SDK.

This one has an SDK prerequisite and a deprecation constraint. The Python SDK currently has no Client.ping() / Client.ping_all(). Per the AccountBalanceQuery deprecation proposal (Stage 1), the ping probe must be a CryptoService/getAccountInfo query for account 0.0.2 with ResponseType = COST_ANSWER. Do not implement ping on top of AccountBalanceQuery — that was the historical approach in other SDKs, and its consensus endpoint (CryptoService/cryptoGetBalance) is being shut down in consensus node release 0.77 (testnet ~Aug 13, 2026; mainnet ~Sept 9, 2026). The TCK spec enforces this: the driver runs a gRPC-aware proxy in front of the consensus node and asserts the probe is getAccountInfo COST_ANSWER and that no cryptoGetBalance call is ever sent.

The spec also tests node-health bookkeeping, not just the probe: a failed ping must open backoff for that node, and a successful ping must reset it so the node selector considers the node again immediately. Read the spec's test table (including the proxy-based assertions) in full before designing anything.

Ordering: the spec requires the ClientPing suite to pass before the Stage 2 AccountBalanceQuery deprecation tests may run — so this issue is effectively a prerequisite of hiero-ledger#2525.

Before you start — required reading

TCK handlers are contract work: the TCK driver validates exact parameter names, optionality, defaults, and error semantics against the published spec. Please do not code from this issue title alone (or paste it into an AI tool and ship the first thing that runs) — read these first:

1. The spec page linked below, in full — especially the parameter table, the expected response shape, and the error/edge-case tests. If your handler's behavior differs from the spec table, the TCK suite will fail even if the happy path works.
2. The deprecation proposal linked above — it defines what the probe must be.
3. tck/README.md — how the JSON-RPC server, param dataclasses, handler registry, and responses fit together, and how to run the TCK driver locally against your handler. Run the actual TCK suite before opening a PR; unit tests alone are not enough.
4. An existing handler as your pattern — pick the closest one in tck/handlers/ with its matching tck/param/ dataclass and follow its structure, naming, and error handling exactly. Do not invent a new style, and do not re-implement SDK logic in the handler — handlers only wire validated params onto the existing SDK transaction/query.
5. Other SDKs' post-Stage-1 Client.ping() implementations — match their semantics (probe form, backoff reset behavior), don't improvise.
6. CONTRIBUTING.md — test and PR conventions.

Solution

• (SDK) Add Client.ping(node_account_id) / Client.ping_all() implemented as a getAccountInfo COST_ANSWER probe of 0.0.2 pinned to the target node, wired into the SDK's node-health/backoff bookkeeping — possibly as its own issue/PR.
• Add PingParams (node account ID / node ID per the spec table) to a suitable tck/param/ module.
• Add ping and pingAll handlers registered via @rpc_method("ping") / @rpc_method("pingAll").
• Add unit tests under tests/tck/, then run the TCK driver's ClientPing suite locally (it uses the driver's gRPC proxy via the setup nodeIp parameter — no extra per-SDK introspection surface is needed).

Acceptance criteria

• ping and pingAll registered and dispatchable
• Proxy capture shows a CryptoService/getAccountInfo COST_ANSWER probe of 0.0.2 and no cryptoGetBalance call
• ping targets exactly the requested node; pingAll probes every node in the network map exactly once
• Failed ping opens node backoff; successful ping resets it (spec tests 4–5)
• Spec error cases behave as specified (unreachable/invalid node)
• Unit tests added and the TCK ClientPing suite passes

Spec: https://github.com/hiero-ledger/hiero-sdk-tck/blob/main/docs/test-specifications/crypto-service/ClientPing.md
Deprecation proposal: https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/proposals/account-balance-query-deprecation.md

[aceppaluni]

@learnmore Can you help me understand this issue?

[codecoach-learning]

Understanding Issue #21: Implement ping and pingAll JSON-RPC Methods

This issue has two main parts: an SDK addition and a TCK handler addition. Let me break it down.

---

Why does this exist?

The TCK (Technology Compatibility Kit) is a test suite that validates the Python SDK behaves correctly. It has a ClientPing test suite that currently cannot run because the Python SDK and its TCK server don't implement ping/pingAll at all.

---

The Critical Constraint: How to Ping

This is the most important part to understand. The old way to ping a node was using AccountBalanceQuery (which hits the cryptoGetBalance gRPC endpoint). You must NOT do this. That endpoint is being shut down in consensus node v0.77.

Instead, the ping probe must be an AccountInfoQuery for account 0.0.2 with ResponseType = COST_ANSWER. This is a "cost answer" query — it asks "how much would this cost?" without actually executing it, making it a lightweight health check.

The TCK driver actually runs a gRPC proxy that inspects traffic and will fail your tests if it sees a cryptoGetBalance call.

---

What Needs to Be Built

1. SDK Layer (src/hiero_sdk_python/client/client.py)

Add two new methods:

• Client.ping(node_account_id) — probe a specific node
• Client.ping_all() — probe every node in the network map

Each ping must:

• Send an AccountInfoQuery for 0.0.2 with COST_ANSWER response type, pinned to the target node
• On failure: open backoff for that node (mark it unhealthy)
• On success: reset backoff so the node is immediately available again

2. TCK Param Dataclass (tck/param/)

Add a PingParams dataclass (following the pattern of existing files like tck/param/account.py) with the fields defined in the spec (e.g., a node account ID or node ID).

3. TCK Handlers (tck/handlers/)

Register two JSON-RPC methods following the pattern of existing handlers:

@rpc_method("ping")
def ping(params: PingParams): ...

@rpc_method("pingAll")
def ping_all(params: ...): ...

4. Tests (tests/tck/)

Add unit tests, and run the actual TCK driver's ClientPing suite locally before submitting a PR.

---

Key Files to Study First

Purpose	File(s)
Existing handler pattern	tck/handlers/account.py, tck/handlers/sdk.py
Existing param pattern	tck/param/account.py, tck/param/sdk.py
Client network logic	src/hiero_sdk_python/client/client.py, src/hiero_sdk_python/client/network.py
How TCK server works	tck/README.md
Node health/backoff	src/hiero_sdk_python/node.py

---

Summary of Acceptance Criteria

1. ✅ ping targets exactly one node; pingAll targets all nodes
2. ✅ The gRPC probe is getAccountInfo COST_ANSWER on 0.0.2 — never cryptoGetBalance
3. ✅ Failed ping → node goes into backoff; successful ping → backoff resets
4. ✅ Error cases (unreachable/invalid node) behave per spec
5. ✅ Unit tests + TCK ClientPing suite passes locally

[aceppaluni]

@learnmore should the issue description include a note or warning?

[codecoach-learning]

Yes, the issue description would benefit from a prominent warning — it already contains critical constraints, but they're written in prose paragraphs that are easy to skim past.

Specifically, this part deserves a callout block:

Do not implement ping on top of AccountBalanceQuery

This is the single most likely mistake a contributor could make (it was the historical approach in other SDKs), and the consequences are non-obvious — the tests will fail not because of a logic error but because a gRPC proxy actively inspects traffic and rejects cryptoGetBalance calls. That's a surprising gotcha.

A warning like this at the top of the "Solution" section would help:

> [!WARNING]
> Do NOT implement ping using `AccountBalanceQuery` (`cryptoGetBalance`).
> The TCK driver runs a gRPC proxy that will fail your tests if it detects
> that endpoint. The probe MUST be `AccountInfoQuery` for `0.0.2` with
> `ResponseType = COST_ANSWER` (`getAccountInfo`).

The issue is well-written overall, but the deprecation constraint is buried in the second paragraph. Given that it's a hard requirement with an active enforcement mechanism (the proxy), surfacing it as a warning at the very top — before the reading list — would prevent contributors from going down the wrong path entirely.

[aceppaluni]

@learnmore what is the purpose of getAccountInfo?

[codecoach-learning]

Purpose of getAccountInfo in This Context

getAccountInfo serves two distinct roles here — its general purpose and its specific purpose as a ping probe.

General Purpose

getAccountInfo is a gRPC call on the CryptoService that retrieves metadata about a Hedera account (balance, keys, memo, etc.).

Why It's Used as a Ping Probe Here

The key is ResponseType = COST_ANSWER. When you send any query with COST_ANSWER, you're asking the node:

"How much would it cost to execute this query?"

The node responds with just a fee estimate — it doesn't actually execute the query. This makes it a lightweight, low-cost way to check if a node is reachable and healthy.

So getAccountInfo with COST_ANSWER on account 0.0.2 is essentially:

1. A health check — if the node responds, it's alive
2. Effectively free — COST_ANSWER doesn't charge or do real work
3. The right endpoint — uses CryptoService/getAccountInfo, not CryptoService/cryptoGetBalance

Why Not AccountBalanceQuery?

AccountBalanceQuery hits cryptoGetBalance, which is being shut down in consensus node v0.77. The TCK driver's gRPC proxy actively watches for that call and will fail the test suite if it appears. getAccountInfo is the approved replacement probe per the deprecation proposal.

In short: getAccountInfo + COST_ANSWER = a cheap, future-proof way to ask "are you there?" without doing real work or hitting a deprecated endpoint.