feat: implement _from_protobuf for token association & airdrop transactions (from_bytes round-trip)

[exploreriii]

🧑‍💻 Intermediate Issue

Welcome! This is an Intermediate Issue touching core SDK architecture.

🏁 When this issue is complete, you will have:

✅ Researched across multiple files and modules
✅ Owned implementation decisions
✅ Written thorough, meaningful tests
✅ Delivered a clean, review-ready pull request

🐞 Problem Description

Transaction.from_bytes() returns a correctly-typed but empty instance for the transaction types below: they never override _from_protobuf, so every type-specific field is left at its default with no error or warning (common fields, signatures and the original body bytes are restored by the base class, so execution still works — inspection does not). Part of #2179; the dispatch-map fixes and the round-trip test harness land in #2614 first.

Affected classes:

• TokenAssociateTransaction (src/hiero_sdk_python/tokens/token_associate_transaction.py)
• TokenDissociateTransaction (src/hiero_sdk_python/tokens/token_dissociate_transaction.py)
• TokenRejectTransaction (src/hiero_sdk_python/tokens/token_reject_transaction.py)
• TokenAirdropTransaction (src/hiero_sdk_python/tokens/token_airdrop_transaction.py)
• TokenCancelAirdropTransaction (src/hiero_sdk_python/tokens/token_cancel_airdrop_transaction.py)
• TokenClaimAirdropTransaction (src/hiero_sdk_python/tokens/token_airdrop_claim.py)

💡 Expected Solution

Implement _from_protobuf for each affected class as the exact field-for-field inverse of its build_transaction_body(), then remove the xfail markers for these types in the round-trip harness from #2614.

• TokenAssociateTransaction._from_protobuf
• TokenDissociateTransaction._from_protobuf
• TokenRejectTransaction._from_protobuf
• TokenAirdropTransaction._from_protobuf
• TokenCancelAirdropTransaction._from_protobuf
• TokenClaimAirdropTransaction._from_protobuf
• Un-xfail these types in the fix: correct the from_bytes transaction-type dispatch map and add a round-trip test harness #2614 round-trip harness

🔍 Background Research

This is inverse-serialization contract work — please research the pattern before coding; do not code from this issue title alone, and do not ship the first AI-generated attempt that runs. Reviewers check inverse fidelity per field.

1. Issue Transaction.from_bytes() returns incomplete objects for most transaction types — missing _from_protobuf implementations #2179 (context) and fix: correct the from_bytes transaction-type dispatch map and add a round-trip test harness #2614 (the test harness your PR must satisfy — do not start before it is merged).
2. The reference implementations: FileCreateTransaction._from_protobuf (src/hiero_sdk_python/file/file_create_transaction.py) and TransferTransaction._from_protobuf (src/hiero_sdk_python/transaction/transfer_transaction.py). Your implementation must follow their structure exactly: call super()._from_protobuf(...), then restore type-specific fields from the body.
3. Each affected class's build_transaction_body() — your _from_protobuf is its exact inverse. Reuse the SDK's existing _from_proto converters (AccountId, TokenId, keys, …); never hand-parse a submessage that already has one.
4. The generated proto message for each body (src/hiero_sdk_python/hapi/services/) — learn which fields are optional (guard with HasField so unset stays None) versus plain scalars/repeated.
5. CONTRIBUTING.md for test and PR conventions.

🛠️ Implementation Notes

TokenAirdropTransaction reuses the TokenTransfer structures — research how TransferTransaction._from_protobuf (src/hiero_sdk_python/transaction/transfer_transaction.py) restores transfer lists and follow it. Cancel/claim restore repeated PendingAirdropId messages; reject distinguishes fungible token references from NFT references.

Constraints / acceptance criteria:

• For each class: build with all fields set → freeze → to_bytes() → from_bytes() → every type-specific field equals the original
• Unset optional fields come back as None/empty, not proto defaults
• restored.to_bytes() stays byte-identical to the original (no re-serialization of the body)
• No changes to public API signatures

Part of #2179. Blocked by #2614.

🔬 Technical Domains

• Intermediate to Advanced Programming (Object oriented design, inheritance, complex type systems)
• File Specific Knowledge (request → serialization → execution → response mapping)
• Backward Compatibility (preserving method signatures, defaults, and return types)
• Protobuf Alignment (reading .proto files, _to_proto() / _from_proto() correctness)
• Testing (unit, integration, mocking, test coverage for edge cases and failure modes)

🧠 Intermediate Contributors — Prerequisites & Expectations

Caution

Intermediate issues are high-risk. We expect more than just a 'working solution' and will recommend beginner issues if the PR does not meet these standards.

🏁 Concrete Prerequisites

• Advanced Programming Language: Higher level intermediate or advanced programming language.
• Expertise: Strong understanding of files related to this issue (research before claiming!).
• Proven History: Successfully completed ≥ 5 beginner issues in this repo.

If this feels like too big a step, that is completely fine — try a Beginner Issue first or a different Intermediate Issue. You can always come back when you are ready.

⚠️ AI Usage Policy

• Using AI to generate code for Intermediate issues is strictly discouraged
• Using AI as the main source of research is strictly discouraged, refer to language and library documentation, protobuf definitions and other SDKs.

⏱️ Timeline & Workflow

• Typical time: ~2 weeks / ~25 hours.
• 🔴 Completing an intermediate issue in 1–3 days is a red flag.

Tip

Suggested: share your proposed implementation approach as a comment before writing code to get early feedback and avoid wasted effort.

🧪 Testing Requirements

Important

At the intermediate level, testing is a major component.
Each _from_protobuf you implement must be verified field-by-field. Tests should cover happy paths, unset-optional edge cases, and error handling.

Source code changes (in src/):

• Un-xfail and pass the parametrized round-trip tests from fix: correct the from_bytes transaction-type dispatch map and add a round-trip test harness #2614 for your types (build with all fields set → freeze → to_bytes() → from_bytes() → assert every type-specific field equals the original)
• Add explicit unset-optional cases: fields not set must come back as None/empty, not proto defaults
• Run tests locally: uv run pytest tests/unit/<specific_file>_test.py -v
• Verify naming, types, and field ordering match protobuf definitions
• Check consistency with similar classes already in the SDK — use the same patterns
• Integration tests will run automatically when you push

🛡️ Quality & Review Standards

Intermediate PRs must be "working, maintainable, and aligned with SDK architecture."

1. Working: The implementation must solve the problem and meet the acceptance criteria.
2. Maintainable: Code should be clear and concise enough for others to understand and debug without your assistance.
3. SDK Alignment: The solution should fit well with existing SDK patterns and abstractions.
4. Backward Compatibility: Public API signatures must be preserved.
5. Comprehensive Testing: Must include unit and integration tests covering all new logic paths, edge cases, and failure modes. AI generated tests based on AI generated code is grounds for immediate rejection.

⚠️ Breaking changes

• Before changing any function signature, return type, or public API — stop and check
• If a breaking change is unavoidable: get explicit maintainer approval before implementing
• All existing tests should pass as-is.

✅ PR Quality Checklist

Before opening your PR, confirm:

• I have spent the majority of my time researching the problem and solution space extensively, including reviewing relevant code, documentation, and external resources.
• My implementation works but is also of high quality - including maintainability, readability, and architectural fit.
• I have checked for breaking changes - no public APIs regress.
• The system design fits with current Hiero SDK architectural approaches.
• Every line of code is personally understood and explainable.

Before requesting a review, confirm:

• I have reviewed the diff line by line.
• My implementation fully addresses the problem described above.
• I did not modify files unrelated to this issue
• Clean git history — no rebase artifacts, merge commits, or unrelated files
• My commits are signed: git commit -S -s -m "chore: description" — Signing guide
• I have verified naming, types, and field ordering against pinned Protobufs.
• I have applied appropriate linting, code quality, and formatting tools used in this repo.
• I have included appropriate tests and all CI checks pass.
• Double and triple check — intermediate PRs are time-consuming to review

📋 Workflow quick reference

You know the workflow — here are the links if you need them:

Step	Guide
Claim this issue	Comment /assign below
Sync with main	Rebasing guide
Open a PR and link this issue	PR guide · Linking guide
Resolve merge conflicts	Merge conflicts guide
Testing	Testing guide

📚 Resources & Support

🆘 Stuck?

Tip

Comment on this issue: and describe what you have tried. A maintainer will respond.

Project references:

• Project structure
• CONTRIBUTING.md
• Browse closed intermediate PRs — see how others did it
• Pylance guide

Protobuf references:

• Hedera Protobufs — source of truth for field names, types, and ordering
• Protobuf language guide

Community:

• Community Calls
• Discord

[github-actions]

Thanks for your submission.

This issue is awaiting approval from @hiero-ledger/hiero-sdk-python-triage and @hiero-ledger/hiero-sdk-python-committers and @hiero-ledger/hiero-sdk-python-maintainers.

[github-actions]

Approved by @hiero-ledger/hiero-sdk-python-triage and @hiero-ledger/hiero-sdk-python-committers and @hiero-ledger/hiero-sdk-python-maintainers.

[github-actions]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Add a _from_protobuf classmethod to each of the six token transaction classes. Each classmethod must call super()._from_protobuf(...) first, guard its oneof body with HasField, and restore type-specific fields as the exact inverse of build_transaction_body().
• Reuse existing nested converters (AccountId._from_proto, TokenId._from_proto, NftId._from_proto, PendingAirdropId._from_proto, TokenTransfer._from_proto, TokenNftTransfer._from_proto). Guard optional message fields so unset fields return as None.
• Correct the _get_transaction_class dispatch map so from_bytes() reaches the cancel-airdrop and claim-airdrop subclasses.
• Verify inverse fidelity and byte-identical re-serialization with round-trip unit tests. Remove the corresponding xfail markers.

Design Choices

Design Choice 1: Dependency `#2614` may not be present

Options Considered:

1. Assume #2614 is merged; only add _from_protobuf and remove xfail markers.
2. Include the dispatch-map corrections and add round-trip tests as part of this work, so the acceptance criteria (from_bytes() round-trip) hold regardless of #2614 state.

Chosen Option: 2

Rationale: The acceptance criteria require a working from_bytes() round-trip for all six types. This is not possible for tokenCancelAirdrop and tokenClaimAirdrop without the dispatch-map corrections. The plan includes these corrections as a precaution. Note: these corrections may already exist from #2614. Exploration shows the dispatch map for tokenCancelAirdrop points to a non-existent module (token_cancel_airdrop_transaction) instead of the real token_airdrop_transaction_cancel. The tokenClaimAirdrop entry has no dispatch entry at all. The round-trip harness with xfail markers is also not present in this snapshot. The ticket states these items land in #2614 first.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Implement inverse serialization for token association transactions

This phase adds the _from_protobuf classmethod to the two simplest classes. Both classes restore a single account and a list of token ids. This phase sets the exact structural pattern to mirror in later phases.

Task 1: Implement `TokenAssociateTransaction._from_protobuf`

Add the standard _from_protobuf classmethod as the inverse of build_transaction_body().

• Update src/hiero_sdk_python/tokens/token_associate_transaction.py.
• Add _from_protobuf(cls, transaction_body, body_bytes, sig_map) as a @classmethod.
• Call super()._from_protobuf(transaction_body, body_bytes, sig_map) first to restore common fields.
• Guard the type-specific body with transaction_body.HasField("tokenAssociate").
• Restore account_id via AccountId._from_proto, guarded by HasField("account") so an unset account stays None.
• Restore token_ids as a list built with TokenId._from_proto over the repeated tokens field.
• Reuse the field-mapping logic already present in the existing _from_proto helper. Keep or remove _from_proto for consistency with the other classes, as decided in Task 3.x.

Task 2: Implement `TokenDissociateTransaction._from_protobuf`

Add the standard _from_protobuf classmethod, symmetric to associate.

• Update src/hiero_sdk_python/tokens/token_dissociate_transaction.py.
• Add _from_protobuf(cls, transaction_body, body_bytes, sig_map) as a @classmethod.
• Call super()._from_protobuf(...) first.
• Guard with transaction_body.HasField("tokenDissociate").
• Restore account_id via AccountId._from_proto, guarded by HasField("account").
• Restore token_ids via TokenId._from_proto over the repeated tokens field.

🤖 Prompt for AI agents

Implement the `_from_protobuf` classmethod on `TokenAssociateTransaction` and
`TokenDissociateTransaction` so that `Transaction.from_bytes()` restores their
fields as the exact inverse of `build_transaction_body()`.

For `TokenAssociateTransaction` (in
`src/hiero_sdk_python/tokens/token_associate_transaction.py`):
- Add `_from_protobuf(cls, transaction_body, body_bytes, sig_map)` as a
`@classmethod`.
- Call `super()._from_protobuf(transaction_body, body_bytes, sig_map)` first to
restore common fields.
- Guard the type-specific body with
`transaction_body.HasField("tokenAssociate")`.
- Restore `account_id` via `AccountId._from_proto`, guarded by
`HasField("account")` so an unset account stays `None`.
- Restore `token_ids` as a list built with `TokenId._from_proto` over the
repeated `tokens` field.
- Reuse the field-mapping logic already present in the existing `_from_proto`
helper. Decide, consistent with Phase 3 decisions, whether to keep or remove
`_from_proto`.

For `TokenDissociateTransaction` (in
`src/hiero_sdk_python/tokens/token_dissociate_transaction.py`):
- Add `_from_protobuf(cls, transaction_body, body_bytes, sig_map)` as a
`@classmethod`.
- Call `super()._from_protobuf(...)` first.
- Guard with `transaction_body.HasField("tokenDissociate")`.
- Restore `account_id` via `AccountId._from_proto`, guarded by
`HasField("account")`.
- Restore `token_ids` via `TokenId._from_proto` over the repeated `tokens`
field.

Both implementations must follow the pattern used by
`TransferTransaction._from_protobuf`, which is the reference implementation.

Phase 2: Implement inverse serialization for reject and airdrop transactions

This phase covers the classes with more complex nested structures: token references with a fungible/NFT oneof, token transfer lists, and repeated pending airdrop ids.

Task 1: Implement `TokenRejectTransaction._from_protobuf`

Add the standard _from_protobuf classmethod and correct the malformed existing _from_proto.

• Update src/hiero_sdk_python/tokens/token_reject_transaction.py.
• Add _from_protobuf(cls, transaction_body, body_bytes, sig_map) as a @classmethod.
• Call super()._from_protobuf(...) first.
• Guard with transaction_body.HasField("tokenReject").
• Restore owner_id via AccountId._from_proto, guarded by HasField("owner") so an unset owner stays None.
• Iterate the repeated rejections field. For each TokenReference entry, use the oneof guard: append TokenId._from_proto(entry.fungible_token) to token_ids when entry.HasField("fungible_token"), and append NftId._from_proto(entry.nft) to nft_ids when entry.HasField("nft").
• Replace the current instance-method _from_proto(self, proto) with the classmethod pattern used by the other classes, so the code stays consistent and the reject logic is not duplicated incorrectly.

Task 2: Implement `TokenAirdropTransaction._from_protobuf`

Add the standard _from_protobuf classmethod that restores fungible and NFT transfer lists.

• Update src/hiero_sdk_python/tokens/token_airdrop_transaction.py.
• Add _from_protobuf(cls, transaction_body, body_bytes, sig_map) as a @classmethod.
• Call super()._from_protobuf(...) first.
• Guard with transaction_body.HasField("tokenAirdrop").
• Iterate the repeated token_transfers field. For each TokenTransferList entry, extend a fungible accumulator with TokenTransfer._from_proto(entry) when the entry has fungible transfers, and extend an NFT accumulator with TokenNftTransfer._from_proto(entry) when the entry has nftTransfers.
• Populate the restored transaction's token_transfers and nft_transfers dictionaries through the base-class initialization helpers (_init_token_transfers / _init_nft_transfers), matching how the constructor and the existing _from_proto do it.
• Follow the TransferTransaction._from_protobuf structure for transfer-list restoration, and reuse the existing per-list converters rather than hand-parsing AccountAmount/NftTransfer.

Task 3: Implement `TokenCancelAirdropTransaction._from_protobuf`

Add the missing deserialization support for cancel-airdrop.

• Update src/hiero_sdk_python/tokens/token_airdrop_transaction_cancel.py.
• Add _from_protobuf(cls, transaction_body, body_bytes, sig_map) as a @classmethod.
• Call super()._from_protobuf(...) first.
• Guard with transaction_body.HasField("tokenCancelAirdrop").
• Restore pending_airdrops as a list built with PendingAirdropId._from_proto over the repeated pending_airdrops field.
• Mirror the structure of TokenClaimAirdropTransaction for consistency.

Task 4: Implement `TokenClaimAirdropTransaction._from_protobuf`

Add the standard _from_protobuf classmethod that restores pending airdrop ids.

• Update src/hiero_sdk_python/tokens/token_airdrop_claim.py.
• Add _from_protobuf(cls, transaction_body, body_bytes, sig_map) as a @classmethod.
• Call super()._from_protobuf(...) first.
• Guard with transaction_body.HasField("tokenClaimAirdrop").
• Restore the private _pending_airdrop_ids list with PendingAirdropId._from_proto over the repeated pending_airdrops field.
• Reuse the existing _from_proto validation flow so restored objects still satisfy the min/max/duplicate rules.

🤖 Prompt for AI agents

Implement the `_from_protobuf` classmethod on `TokenRejectTransaction`,
`TokenAirdropTransaction`, `TokenCancelAirdropTransaction`, and
`TokenClaimAirdropTransaction` to restore their type-specific fields as the
exact inverse of `build_transaction_body()`.

For `TokenRejectTransaction` (in
`src/hiero_sdk_python/tokens/token_reject_transaction.py`):
- Add `_from_protobuf(cls, transaction_body, body_bytes, sig_map)` as a
`@classmethod`. Call `super()._from_protobuf(...)` first. Guard with
`transaction_body.HasField("tokenReject")`.
- Restore `owner_id` via `AccountId._from_proto`, guarded by `HasField("owner")`
so an unset owner stays `None`.
- Iterate the repeated `rejections` field. For each `TokenReference` entry, use
the oneof guard: append `TokenId._from_proto(entry.fungible_token)` to
`token_ids` when `entry.HasField("fungible_token")`, and append
`NftId._from_proto(entry.nft)` to `nft_ids` when `entry.HasField("nft")`.
- Replace the current instance-method `_from_proto(self, proto)` with the
classmethod pattern used by the other classes. Do not duplicate the reject logic
incorrectly.

For `TokenAirdropTransaction` (in
`src/hiero_sdk_python/tokens/token_airdrop_transaction.py`):
- Add `_from_protobuf(cls, transaction_body, body_bytes, sig_map)` as a
`@classmethod`. Call `super()._from_protobuf(...)` first. Guard with
`transaction_body.HasField("tokenAirdrop")`.
- Iterate the repeated `token_transfers` field. For each `TokenTransferList`
entry, extend a fungible accumulator with `TokenTransfer._from_proto(entry)`
when the entry has fungible `transfers`, and extend an NFT accumulator with
`TokenNftTransfer._from_proto(entry)` when the entry has `nftTransfers`.
- Populate the restored transaction's `token_transfers` and `nft_transfers`
dictionaries through the base-class initialization helpers
(`_init_token_transfers` / `_init_nft_transfers`), matching how the constructor
and the existing `_from_proto` do it.
- Follow the `TransferTransaction._from_protobuf` structure for transfer-list
restoration. Reuse the existing per-list converters instead of hand-parsing
`AccountAmount`/`NftTransfer`.

For `TokenCancelAirdropTransaction` (in
`src/hiero_sdk_python/tokens/token_airdrop_transaction_cancel.py`):
- Add `_from_protobuf(cls, transaction_body, body_bytes, sig_map)` as a
`@classmethod`. Call `super()._from_protobuf(...)` first. Guard with
`transaction_body.HasField("tokenCancelAirdrop")`.
- Restore `pending_airdrops` as a list built with `PendingAirdropId._from_proto`
over the repeated `pending_airdrops` field.
- Mirror the structure of `TokenClaimAirdropTransaction` for consistency, since
this class has no existing deserialization method.

For `TokenClaimAirdropTransaction` (in
`src/hiero_sdk_python/tokens/token_airdrop_claim.py`):
- Add `_from_protobuf(cls, transaction_body, body_bytes, sig_map)` as a
`@classmethod`. Call `super()._from_protobuf(...)` first. Guard with
`transaction_body.HasField("tokenClaimAirdrop")`.
- Restore the private `_pending_airdrop_ids` list with
`PendingAirdropId._from_proto` over the repeated `pending_airdrops` field.
- Reuse the existing `_from_proto` validation flow so restored objects still
satisfy the min/max/duplicate rules.

Phase 3: Wire the dispatch map, add tests, and remove xfail markers

This phase makes Transaction.from_bytes() reachable for all six types and confirms inverse fidelity. It also aligns test coverage with the project conventions.

Task 1: Correct the transaction dispatch map

Ensure from_bytes() resolves the correct subclass for cancel-airdrop and claim-airdrop.

• Update _get_transaction_class in src/hiero_sdk_python/transaction/transaction.py.
• Change the tokenCancelAirdrop entry to point to the real module hiero_sdk_python.tokens.token_airdrop_transaction_cancel.TokenCancelAirdropTransaction.
• Add the missing tokenClaimAirdrop entry pointing to hiero_sdk_python.tokens.token_airdrop_claim.TokenClaimAirdropTransaction.
• If #2614 already added these fixes, verify them and make no duplicate change.

Task 2: Add round-trip unit tests for the six transaction types

Verify inverse fidelity and byte-identical re-serialization.

• Add or extend the unit tests in tests/unit/token_associate_transaction_test.py, token_dissociate_transaction_test.py, token_reject_transaction_test.py, token_airdrop_transaction_test.py, token_airdrop_transaction_cancel_test.py, and token_airdrop_claim_test.py.
• Reuse the shared fixtures in tests/unit/conftest.py (mock_account_ids, nft_id, token_id, mock_client).
• For each class, build the transaction with all fields set, freeze it, call to_bytes(), then from_bytes(), and assert every type-specific field equals the original.
• Add a case that leaves optional fields unset and asserts they return as None/empty, not proto defaults.
• Assert restored.to_bytes() is byte-identical to the original bytes.
• Follow the assertion style used in tests/unit/transfer_transaction_test.py and tests/unit/transaction_freeze_and_bytes_test.py.

Task 3: Remove the xfail markers from the round-trip harness

Enable the previously skipped round-trip cases for the six types.

• If the #2614 round-trip harness is present, remove the pytest.mark.xfail markers for TokenAssociateTransaction, TokenDissociateTransaction, TokenRejectTransaction, TokenAirdropTransaction, TokenCancelAirdropTransaction, and TokenClaimAirdropTransaction.
• If the harness is not present, rely on the round-trip tests added in Task 3.2 and record this in the pull request description.
• Update CHANGELOG.md under UNRELEASED as required by the contribution conventions.

🤖 Prompt for AI agents

Wire the dispatch map so `Transaction.from_bytes()` can reach all six
transaction subclasses, add round-trip unit tests, and remove obsolete xfail
markers.

Dispatch map correction, in `_get_transaction_class`
(`src/hiero_sdk_python/transaction/transaction.py`):
- Change the `tokenCancelAirdrop` entry to point to the real module
`hiero_sdk_python.tokens.token_airdrop_transaction_cancel.TokenCancelAirdropTransaction`
(it currently points to a non-existent module
`token_cancel_airdrop_transaction`).
- Add the missing `tokenClaimAirdrop` entry pointing to
`hiero_sdk_python.tokens.token_airdrop_claim.TokenClaimAirdropTransaction`.
- If dependency `#2614` already applied these fixes, verify them and do not
duplicate the change.

Round-trip unit tests:
- Add or extend tests in `tests/unit/token_associate_transaction_test.py`,
`token_dissociate_transaction_test.py`, `token_reject_transaction_test.py`,
`token_airdrop_transaction_test.py`, `token_airdrop_transaction_cancel_test.py`,
and `token_airdrop_claim_test.py`.
- Reuse the shared fixtures in `tests/unit/conftest.py`: `mock_account_ids`,
`nft_id`, `token_id`, `mock_client`.
- For each class, build the transaction with all fields set, freeze it, call
`to_bytes()`, then call `from_bytes()`, and assert every type-specific field
equals the original.
- Add a test case that leaves optional fields unset and asserts they return as
`None` or empty, not as proto default values.
- Assert that `restored.to_bytes()` is byte-identical to the original bytes.
- Follow the assertion style used in `tests/unit/transfer_transaction_test.py`
and `tests/unit/transaction_freeze_and_bytes_test.py`.

Remove xfail markers:
- If the `#2614` round-trip harness is present, remove the `pytest.mark.xfail`
markers for `TokenAssociateTransaction`, `TokenDissociateTransaction`,
`TokenRejectTransaction`, `TokenAirdropTransaction`,
`TokenCancelAirdropTransaction`, and `TokenClaimAirdropTransaction`.
- If the harness is not present, rely on the round-trip tests added in this
phase and record this fact in the pull request description.
- Update `CHANGELOG.md` under `UNRELEASED` as required by the contribution
conventions.

Research

The SDK base class Transaction (src/hiero_sdk_python/transaction/transaction.py) provides a static from_bytes() method. This method parses the wire bytes. It resolves the transaction subclass through the _get_transaction_class dispatch map. It dispatches to subclass._from_protobuf(transaction_body, body_bytes, sig_map).

The base _from_protobuf classmethod restores common fields: transaction id, node account id, fee, memo, signatures, and frozen body bytes.

Subclasses must override _from_protobuf. Each subclass must call super()._from_protobuf(...) first. Each subclass must guard the type-specific oneof field with HasField. Each subclass must restore its own attributes.

TransferTransaction follows this contract correctly. Use it as the reference implementation.

The six target token transaction classes do not implement this contract. Instead, they carry non-standard _from_proto methods. The exception is TokenCancelAirdropTransaction, which has no deserialization method at all.

Nested converters already exist and must be reused:

• AccountId._from_proto
• TokenId._from_proto
• NftId._from_proto
• PendingAirdropId._from_proto
• TokenTransfer._from_proto
• TokenNftTransfer._from_proto

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the `_from_protobuf` classmethod on `TokenAssociateTransaction` and
`TokenDissociateTransaction` so that `Transaction.from_bytes()` restores their
fields as the exact inverse of `build_transaction_body()`.

For `TokenAssociateTransaction` (in
`src/hiero_sdk_python/tokens/token_associate_transaction.py`):
- Add `_from_protobuf(cls, transaction_body, body_bytes, sig_map)` as a
`@classmethod`.
- Call `super()._from_protobuf(transaction_body, body_bytes, sig_map)` first to
restore common fields.
- Guard the type-specific body with
`transaction_body.HasField("tokenAssociate")`.
- Restore `account_id` via `AccountId._from_proto`, guarded by
`HasField("account")` so an unset account stays `None`.
- Restore `token_ids` as a list built with `TokenId._from_proto` over the
repeated `tokens` field.
- Reuse the field-mapping logic already present in the existing `_from_proto`
helper. Decide, consistent with Phase 3 decisions, whether to keep or remove
`_from_proto`.

For `TokenDissociateTransaction` (in
`src/hiero_sdk_python/tokens/token_dissociate_transaction.py`):
- Add `_from_protobuf(cls, transaction_body, body_bytes, sig_map)` as a
`@classmethod`.
- Call `super()._from_protobuf(...)` first.
- Guard with `transaction_body.HasField("tokenDissociate")`.
- Restore `account_id` via `AccountId._from_proto`, guarded by
`HasField("account")`.
- Restore `token_ids` via `TokenId._from_proto` over the repeated `tokens`
field.

Both implementations must follow the pattern used by
`TransferTransaction._from_protobuf`, which is the reference implementation.
===============================================================================

Task: 2

Implement the `_from_protobuf` classmethod on `TokenRejectTransaction`,
`TokenAirdropTransaction`, `TokenCancelAirdropTransaction`, and
`TokenClaimAirdropTransaction` to restore their type-specific fields as the
exact inverse of `build_transaction_body()`.

For `TokenRejectTransaction` (in
`src/hiero_sdk_python/tokens/token_reject_transaction.py`):
- Add `_from_protobuf(cls, transaction_body, body_bytes, sig_map)` as a
`@classmethod`. Call `super()._from_protobuf(...)` first. Guard with
`transaction_body.HasField("tokenReject")`.
- Restore `owner_id` via `AccountId._from_proto`, guarded by `HasField("owner")`
so an unset owner stays `None`.
- Iterate the repeated `rejections` field. For each `TokenReference` entry, use
the oneof guard: append `TokenId._from_proto(entry.fungible_token)` to
`token_ids` when `entry.HasField("fungible_token")`, and append
`NftId._from_proto(entry.nft)` to `nft_ids` when `entry.HasField("nft")`.
- Replace the current instance-method `_from_proto(self, proto)` with the
classmethod pattern used by the other classes. Do not duplicate the reject logic
incorrectly.

For `TokenAirdropTransaction` (in
`src/hiero_sdk_python/tokens/token_airdrop_transaction.py`):
- Add `_from_protobuf(cls, transaction_body, body_bytes, sig_map)` as a
`@classmethod`. Call `super()._from_protobuf(...)` first. Guard with
`transaction_body.HasField("tokenAirdrop")`.
- Iterate the repeated `token_transfers` field. For each `TokenTransferList`
entry, extend a fungible accumulator with `TokenTransfer._from_proto(entry)`
when the entry has fungible `transfers`, and extend an NFT accumulator with
`TokenNftTransfer._from_proto(entry)` when the entry has `nftTransfers`.
- Populate the restored transaction's `token_transfers` and `nft_transfers`
dictionaries through the base-class initialization helpers
(`_init_token_transfers` / `_init_nft_transfers`), matching how the constructor
and the existing `_from_proto` do it.
- Follow the `TransferTransaction._from_protobuf` structure for transfer-list
restoration. Reuse the existing per-list converters instead of hand-parsing
`AccountAmount`/`NftTransfer`.

For `TokenCancelAirdropTransaction` (in
`src/hiero_sdk_python/tokens/token_airdrop_transaction_cancel.py`):
- Add `_from_protobuf(cls, transaction_body, body_bytes, sig_map)` as a
`@classmethod`. Call `super()._from_protobuf(...)` first. Guard with
`transaction_body.HasField("tokenCancelAirdrop")`.
- Restore `pending_airdrops` as a list built with `PendingAirdropId._from_proto`
over the repeated `pending_airdrops` field.
- Mirror the structure of `TokenClaimAirdropTransaction` for consistency, since
this class has no existing deserialization method.

For `TokenClaimAirdropTransaction` (in
`src/hiero_sdk_python/tokens/token_airdrop_claim.py`):
- Add `_from_protobuf(cls, transaction_body, body_bytes, sig_map)` as a
`@classmethod`. Call `super()._from_protobuf(...)` first. Guard with
`transaction_body.HasField("tokenClaimAirdrop")`.
- Restore the private `_pending_airdrop_ids` list with
`PendingAirdropId._from_proto` over the repeated `pending_airdrops` field.
- Reuse the existing `_from_proto` validation flow so restored objects still
satisfy the min/max/duplicate rules.
===============================================================================

Task: 3

Wire the dispatch map so `Transaction.from_bytes()` can reach all six
transaction subclasses, add round-trip unit tests, and remove obsolete xfail
markers.

Dispatch map correction, in `_get_transaction_class`
(`src/hiero_sdk_python/transaction/transaction.py`):
- Change the `tokenCancelAirdrop` entry to point to the real module
`hiero_sdk_python.tokens.token_airdrop_transaction_cancel.TokenCancelAirdropTransaction`
(it currently points to a non-existent module
`token_cancel_airdrop_transaction`).
- Add the missing `tokenClaimAirdrop` entry pointing to
`hiero_sdk_python.tokens.token_airdrop_claim.TokenClaimAirdropTransaction`.
- If dependency `#2614` already applied these fixes, verify them and do not
duplicate the change.

Round-trip unit tests:
- Add or extend tests in `tests/unit/token_associate_transaction_test.py`,
`token_dissociate_transaction_test.py`, `token_reject_transaction_test.py`,
`token_airdrop_transaction_test.py`, `token_airdrop_transaction_cancel_test.py`,
and `token_airdrop_claim_test.py`.
- Reuse the shared fixtures in `tests/unit/conftest.py`: `mock_account_ids`,
`nft_id`, `token_id`, `mock_client`.
- For each class, build the transaction with all fields set, freeze it, call
`to_bytes()`, then call `from_bytes()`, and assert every type-specific field
equals the original.
- Add a test case that leaves optional fields unset and asserts they return as
`None` or empty, not as proto default values.
- Assert that `restored.to_bytes()` is byte-identical to the original bytes.
- Follow the assertion style used in `tests/unit/transfer_transaction_test.py`
and `tests/unit/transaction_freeze_and_bytes_test.py`.

Remove xfail markers:
- If the `#2614` round-trip harness is present, remove the `pytest.mark.xfail`
markers for `TokenAssociateTransaction`, `TokenDissociateTransaction`,
`TokenRejectTransaction`, `TokenAirdropTransaction`,
`TokenCancelAirdropTransaction`, and `TokenClaimAirdropTransaction`.
- If the harness is not present, rely on the round-trip tests added in this
phase and record this fact in the pull request description.
- Update `CHANGELOG.md` under `UNRELEASED` as required by the contribution
conventions.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---