Problem

Under high concurrency, the submitting node for a transaction can become temporarily unavailable or overloaded, leading to repeated timeouts when retrieving transaction receipts or records—even though other nodes are capable of serving the data.

A cross-SDK design proposal introduces an opt-in client-level configuration that allows getReceipt and getRecord queries to fail over to other nodes when the submitting node is unresponsive, while preserving strict correctness by default.

This issue tracks implementing that opt-in failover behavior in the SDK.

Design Proposal

hiero-ledger/sdk-collaboration-hub#123

Expected Behavior

• Default behavior remains unchanged:
  • Receipt and record queries are pinned to the submitting node only.
• When opt-in failover is enabled:
  • Queries always start with the submitting node.
  • If the submitting node is unavailable, queries may advance to other eligible nodes.
  • Node iteration order is deterministic, with duplicates removed.
• The opt-in explicitly trades strict correctness guarantees for improved availability.

Scope

• Add support for client-level opt-in receipt/record query failover.
• Apply the same failover semantics to:
  • getReceiptQuery / getReceipt
  • getRecordQuery / getRecord
• Ensure retry logic advances nodes only when failover is enabled.
• Maintain backward compatibility and existing default semantics.

Notes

• This work assumes the SDK has (or will have) a baseline behavior where receipt/record queries are pinned to the submitting node by default.
• The goal is consistent, explicit, and user-controlled behavior across SDKs.