feat: Add support for include_children in TransactionGetReceiptQuery

[AntonioCeppellini]

Description:
This PR add support for include_children in TransactionGetReceiptQuery

• In TransactionGetReceiptQuery we have the new field include_children that is a bool.
• New setter set_include_children.
• In TransactionReceipt new property children
• internal setter _set_children used in the query
• Extended existing example
• Extended existing tests
• Created new tests

Related issue(s):

Fixes #1100

Checklist

• Documented (Code comments, README, etc.)
• Tested (unit, integration, etc.)

Summary by CodeRabbit

Release Notes

• New Features

  • Added support for retrieving child receipts when querying transaction receipts. Users can now access detailed child receipt information including status and counts.

• Documentation

  • Updated example to demonstrate child receipt retrieval functionality.

• Tests

  • Added comprehensive integration and unit tests for child receipt query functionality.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[github-actions]

Hi, this is MergeConflictBot.
Your pull request cannot be merged because it contains merge conflicts.

Please resolve these conflicts locally and push the changes.

To assist you, please read:

• Resolving Merge Conflicts
• Rebasing Guide

Thank you for contributing!

From the Hiero Python SDK Team

[manishdait]

Hi @AntonioCeppellini, Just some minor changes rest looks good to me.

[github-actions]

Hello, this is the Office Hour Bot.

This is a reminder that the Hiero Python SDK Office Hours are scheduled in approximately 4 hours (14:00 UTC).

This session provides an opportunity to ask questions regarding this Pull Request or receive assistance from a maintainer.

Details:

• Time: 14:00 UTC
• Join Link: Zoom Meeting

Disclaimer: This is an automated reminder. Please verify the schedule here to be notified of any changes.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@            Coverage Diff             @@
##             main    #1114      +/-   ##
==========================================
+ Coverage   91.08%   91.10%   +0.01%     
==========================================
  Files         139      139              
  Lines        8423     8441      +18     
==========================================
+ Hits         7672     7690      +18     
  Misses        751      751              

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[AntonioCeppellini]

@manishdait I've followed your advises :D

[exploreriii]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Walkthrough

This pull request adds support for querying child transaction receipts through a new include_children parameter in TransactionGetReceiptQuery. The implementation extends the query class with getter/setter methods, modifies TransactionReceipt to expose a children property, and includes unit and integration tests plus updated examples.

Changes

Cohort / File(s)	Summary
Core Query Enhancement src/hiero_sdk_python/query/transaction_get_receipt_query.py	Added include_children parameter to __init__, introduced set_include_children() setter, updated _make_request() to propagate the flag to the protobuf request, and enhanced execute() to construct and attach child receipts to the parent when requested.
Receipt Data Model src/hiero_sdk_python/transaction/transaction_receipt.py	Extended __init__ with optional children parameter, added _children field, exposed public children property, and introduced internal _set_children() setter for managing child receipt references.
Example Implementation examples/query/transaction_get_receipt_query.py	Added _print_receipt_with_children() helper for displaying receipt and child receipt details, enabled include_children in the query flow, and integrated the new printing function into the main example.
Unit Tests tests/unit/get_receipt_query_test.py, tests/unit/test_transaction_receipt.py	Added 4 unit tests validating request building, child receipt mapping, empty children handling, and scenarios where no children are present; plus tests for TransactionReceipt children property behavior.
Integration Tests tests/integration/transaction_get_receipt_query_children_e2e_test.py	New E2E test module with 3 tests: simple transfer without children, simple transfer with children, and contract execution with children; includes helper functions for transaction ID extraction and basic transfers.
Documentation CHANGELOG.md	Added changelog entry documenting the new include_children support for TransactionGetReceiptQuery (issue #1100).

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant Query as TransactionGetReceiptQuery
    participant Network as Hedera Network
    participant Receipt as TransactionReceipt
    
    Client->>Query: set_include_children(true)
    Client->>Query: execute(client)
    Query->>Query: _make_request()
    Note over Query: Build protobuf request<br/>with include_child_receipts=true
    Query->>Network: Send query request
    Network-->>Query: Response with receipt<br/>+ child_transaction_receipts[]
    Query->>Receipt: _from_proto(receipt)
    activate Receipt
    Receipt->>Receipt: __init__(...children=None)
    deactivate Receipt
    alt include_children is True
        Query->>Query: _map_receipt_list(children_protos)
        loop For each child_proto
            Query->>Receipt: _from_proto(child_proto)
        end
        Query->>Receipt: _set_children([child1, child2, ...])
    end
    Query-->>Client: Return parent Receipt<br/>with children attached
    Client->>Receipt: receipt.children
    Receipt-->>Client: list[TransactionReceipt]

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~40 minutes

• New public API surface: TransactionGetReceiptQuery.__init__() signature change, new set_include_children() method, TransactionReceipt.__init__() parameter addition, and new children property require careful validation.
• Response mapping logic: Verify correctness of child receipt extraction and attachment in TransactionGetReceiptQuery.execute(), especially the conditional logic when include_children is true.
• Cross-file dependencies: Changes span query execution, receipt construction, and protobuf message handling; ensure consistency across the flow and proper state management.
• Test coverage: Review both unit tests (mocking behavior) and E2E tests (network integration) to confirm all paths (with/without children, contract execution) are properly validated.

Poem

🐰 A query hops to fetch a receipt so fine,
With children in tow, they all align!
Each child receipt now tagged and collected,
The parent embraces them—perfectly connected.
Include them all with a flag set to true! ✨

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding include_children support to TransactionGetReceiptQuery.
Linked Issues check	✅ Passed	All coding objectives from issue #1100 are met: include_children field added with setter, TransactionReceipt children support added with property, proto integration, child receipt mapping, updated execute() method, and tests added.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with issue #1100 requirements: core feature implementation, example updates, and comprehensive test coverage for include_children functionality.
Docstring Coverage	✅ Passed	Docstring coverage is 94.12% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[exploreriii]

please rebase, i was just looking through this should nearly be reviewed soon

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (2)

tests/integration/transaction_get_receipt_query_children_e2e_test.py (1)

22-22: Consider removing or aliasing the unused import.

The static analysis tool flags F811: Redefinition of unused 'env' from line 22 because the env fixture parameter in each test function shadows this import. If this import is only for pytest fixture registration/discovery, consider either:

1. Removing it if the fixture is already available via conftest.py
2. Using a different pattern like from tests.integration.utils import env as _env to avoid shadowing

src/hiero_sdk_python/transaction/transaction_receipt.py (1)

37-53: Consider updating the docstring to document the children parameter.

The constructor now accepts an optional children parameter, but the docstring (lines 43-49) doesn't mention it. For API completeness, consider adding documentation for this parameter.

🔎 Suggested docstring update:

         """
         Initializes the TransactionReceipt with the provided protobuf receipt.

         Args:
             receipt_proto (transaction_receipt_pb2.TransactionReceiptProto, optional): The protobuf transaction receipt.
             transaction_id (TransactionId, optional): The transaction ID associated with this receipt.
+            children (list[TransactionReceipt], optional): Child receipts associated with this receipt.
         """

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a13fc0b and 4c9c407.

📒 Files selected for processing (7)

• CHANGELOG.md (1 hunks)
• examples/query/transaction_get_receipt_query.py (3 hunks)
• src/hiero_sdk_python/query/transaction_get_receipt_query.py (5 hunks)
• src/hiero_sdk_python/transaction/transaction_receipt.py (4 hunks)
• tests/integration/transaction_get_receipt_query_children_e2e_test.py (1 hunks)
• tests/unit/get_receipt_query_test.py (4 hunks)
• tests/unit/test_transaction_receipt.py (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (5)

tests/unit/test_transaction_receipt.py (1)

src/hiero_sdk_python/transaction/transaction_receipt.py (4)

• TransactionReceipt (24-248)
• transaction_id (123-130)
• children (211-218)
• _set_children (220-227)

src/hiero_sdk_python/query/transaction_get_receipt_query.py (4)

src/hiero_sdk_python/transaction/transaction_receipt.py (5)

• transaction_id (123-130)
• TransactionReceipt (24-248)
• _from_proto (239-248)
• children (211-218)
• _set_children (220-227)

tests/unit/conftest.py (1)

• transaction_id (42-44)

src/hiero_sdk_python/consensus/topic_message.py (1)

• _from_proto (145-176)

src/hiero_sdk_python/consensus/topic_info.py (1)

• _from_proto (79-123)

tests/integration/transaction_get_receipt_query_children_e2e_test.py (4)

tests/unit/query_test.py (1)

• query (15-17)

src/hiero_sdk_python/query/transaction_get_receipt_query.py (4)

• TransactionGetReceiptQuery (15-285)
• execute (226-259)
• set_transaction_id (53-68)
• set_include_children (70-87)

src/hiero_sdk_python/response_code.py (1)

• ResponseCode (4-387)

src/hiero_sdk_python/transaction/transaction_receipt.py (1)

• children (211-218)

tests/unit/get_receipt_query_test.py (3)

src/hiero_sdk_python/query/transaction_get_receipt_query.py (3)

• TransactionGetReceiptQuery (15-285)
• execute (226-259)
• _make_request (101-138)

src/hiero_sdk_python/transaction/transaction_receipt.py (3)

• transaction_id (123-130)
• TransactionReceipt (24-248)
• children (211-218)

src/hiero_sdk_python/response_code.py (1)

• ResponseCode (4-387)

src/hiero_sdk_python/transaction/transaction_receipt.py (2)

tests/unit/conftest.py (1)

• transaction_id (42-44)

src/hiero_sdk_python/transaction/transaction_id.py (1)

• TransactionId (8-156)

🪛 markdownlint-cli2 (0.18.1)

CHANGELOG.md

49-49: Bare URL used

(MD034, no-bare-urls)

🪛 Ruff (0.14.8)

tests/integration/transaction_get_receipt_query_children_e2e_test.py

45-47: Avoid specifying long messages outside the exception class

(TRY003)

---

50-50: Redefinition of unused env from line 22

(F811)

---

69-69: Redefinition of unused env from line 22

(F811)

---

87-87: Redefinition of unused env from line 22

(F811)

---

107-107: Redefinition of unused env from line 22

(F811)

tests/unit/get_receipt_query_test.py

43-43: Do not catch blind exception: Exception

(BLE001)

---

88-88: Do not catch blind exception: Exception

(BLE001)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (7)

• GitHub Check: Codacy Static Code Analysis
• GitHub Check: run-examples
• GitHub Check: build-and-test (3.12)
• GitHub Check: build-and-test (3.11)
• GitHub Check: build-and-test (3.13)
• GitHub Check: build-and-test (3.10)
• GitHub Check: StepSecurity Harden-Runner

🔇 Additional comments (19)

CHANGELOG.md (1)

49-49: LGTM!

The changelog entry correctly documents the new feature and follows the existing format used elsewhere in this file.

tests/unit/test_transaction_receipt.py (1)

1-30: LGTM!

The tests appropriately cover the children property default behavior and the _set_children internal setter. Using identity checks (is) correctly verifies that the exact child instances are preserved.

examples/query/transaction_get_receipt_query.py (2)

65-79: LGTM!

The helper function is well-structured and provides clear output for demonstrating the include_children feature.

---

111-119: LGTM!

Good demonstration of the new set_include_children(True) API, and the updated step description clearly indicates the feature being exercised.

src/hiero_sdk_python/query/transaction_get_receipt_query.py (4)

27-41: LGTM!

The constructor properly initializes include_children with a backward-compatible default of False.

---

70-87: LGTM!

The setter follows the established pattern with frozen-state validation and method chaining support.

---

127-128: LGTM!

Correctly propagates the include_children flag to the protobuf's include_child_receipts field.

---

248-259: Child receipts correctly mapped; verify transaction_id semantics.

The implementation correctly creates the parent receipt and conditionally attaches child receipts. Note that child receipts are constructed using the parent's transaction_id—this is acceptable since TransactionReceipt._from_proto treats transaction_id as optional context, and child receipts derive from the parent transaction.

Minor: Line 259 has trailing whitespace.

🔎 Apply this diff to remove trailing whitespace:

-        return parent 
+        return parent

tests/unit/get_receipt_query_test.py (3)

137-152: LGTM!

Good test coverage verifying that include_child_receipts is correctly set in the protobuf request.

---

155-195: LGTM!

Thorough test verifying end-to-end behavior: child receipts are mapped correctly with proper statuses when include_children is enabled.

---

198-229: LGTM!

Important backward-compatibility test ensuring children remains empty when include_children is not explicitly requested.

tests/integration/transaction_get_receipt_query_children_e2e_test.py (5)

25-47: LGTM!

The helper function provides robust fallback logic for extracting transaction IDs across different transaction types. The approach of checking multiple attributes is appropriate for E2E test flexibility.

---

50-65: LGTM!

The helper correctly implements the transfer pattern with Hbar().to_tinybars() as suggested in previous reviews.

---

68-83: LGTM!

Good test coverage for the default behavior. The assertion receipt.children == [] correctly validates that children defaults to an empty list when include_children is not set.

---

86-103: LGTM!

The test correctly validates that include_children=True results in a list response. The decision not to assert on list contents is appropriate since simple transfers typically don't produce child receipts.

---

106-184: LGTM!

Well-structured contract execution test that:

• Properly handles the non-deterministic nature of child receipts (as documented)
• Uses defensive pytest.skip for transaction ID extraction failures
• Validates child receipt integrity when children exist

The local imports are acceptable for test isolation.

src/hiero_sdk_python/transaction/transaction_receipt.py (3)

210-218: LGTM!

Clean property implementation with clear documentation explaining the return behavior.

---

220-227: LGTM!

The internal setter follows the appropriate pattern for post-construction modification by the query class. The underscore prefix correctly signals internal usage.

---

238-248: LGTM!

The _from_proto method correctly omits the children parameter since child receipts come from a separate field in the response (child_transaction_receipts) and are populated by the query class via _set_children.

[exploreriii]

thank you @AntonioCeppellini excellent work!