[Intermediate]: Implement opt-in receipt/record query failover to other nodes

[venilinvasilev]

🧩 Intermediate Friendly

This issue is a good fit for contributors who are already familiar with the
Hiero Swift SDK and feel comfortable navigating the codebase.

Intermediate Issues often involve:

• Exploring existing implementations
• Understanding how different components work together
• Making thoughtful changes that follow established patterns

The goal is to support deeper problem-solving while keeping the task clear,
focused, and enjoyable to work on.

🐞 Problem Description

Under high concurrency, the submitting node for a transaction can become temporarily unavailable or overloaded. Currently, getReceiptQuery and getRecordQuery are pinned to the submitting node, which preserves strict correctness but may lead to repeated timeouts when that node is unhealthy.

The SDK does not currently provide a way to opt into advancing receipt/record queries to other nodes when the submitting node is unresponsive.

This makes it difficult for high-throughput users (e.g., relay providers) to balance correctness and availability.

Relevant areas of the codebase include:

• TransactionResponse
• TransactionReceiptQuery
• TransactionRecordQuery
• Retry handling logic in executable/query infrastructure

💡 Expected Outcome

Introduce opt-in receipt/record query failover controlled by a client-level configuration flag.

The solution should:

• Add a allowReceiptNodeFailover flag to Client (default: false)
• Preserve existing behavior when the flag is not enabled
• When enabled:
  • Always start receipt/record queries with the submitting node
  • Advance to other eligible nodes if the submitting node is unavailable
  • Maintain deterministic node ordering
• Apply identical behavior to:
  • getReceiptQuery / getReceipt
  • getRecordQuery / getRecord

The public API must remain backward compatible.

🧠 Implementation Notes

Suggested approach:

• Review current implementation of getReceiptQuery and getRecordQuery
• Identify where node pinning is applied
• Introduce client-level configuration check
• Adjust retry logic so:
  • Single-node queries retry the same node (default)
  • Multi-node queries advance when failover is enabled
• Follow existing patterns for node iteration and backoff handling
• Ensure behavior matches the design proposal:
  feat: opt in receipt query failover sdk-collaboration-hub#123

✅ Acceptance Criteria

To help get this change merged smoothly:

• Add client-level allowReceiptNodeFailover configuration
• Preserve strict pinned behavior by default
• Enable multi-node iteration only when flag is true
• Apply changes consistently to receipt and record queries
• Follow existing project conventions
• Avoid breaking public APIs
• Include tests covering default and opt-in behavior
• Pass all CI checks

📋 Contribution Guide

To help your contribution go as smoothly as possible, we recommend following these steps:

• Comment /assign to request the issue
• Wait for assignment
• Fork the repository and create a branch
• Set up the project using the instructions in README.md
• Make the requested changes
• Sign each commit using -s -S
• Push your branch and open a pull request

Read Workflow Guide for step-by-step workflow guidance.
Read README.md for setup instructions.

❗ Pull requests cannot be merged without S and s signed commits.
See the Signing Guide.

📚 Additional Context or Resources

Design proposal:
hiero-ledger/sdk-collaboration-hub#123

If you have questions, the community is happy to help:

https://discord.com/channels/905194001349627914/1337424839761465364