Add `add_fee_exempt_key()` to TopicUpdateTransaction class

[manishdait]

🧑‍🎓 Beginner Issue

Welcome! This is a Beginner Issue designed to help you learn the codebase.

🏁 When this issue is complete, you will have:

✅ Researched a file or method in detail
✅ Followed SDK patterns to implement a solution
✅ Researched and identified appropriate programming constructs to solve the problem
✅ Created basic tests
✅ Delivered a clean, review-ready pull request

🐞 Problem Description

The Python SDK currently provides the following methods on TopicUpdateTransaction for managing fee exempt keys:

• set_fee_exempt_keys()
• clear_fee_exempt_keys()

However, it is missing an add_fee_exempt_key() convenience method that exists in the other SDKs.

💡 Expected Solution

Implement add_fee_exempt_key() in TopicUpdateTransaction to provide API parity with the other SDK. The method should append a single Key to the transaction's fee exempt key list.

🔍 Research Pointers

• Review hiero_sdk_python/topic/topic_update_transaction.py, where set_fee_exempt_keys() and clear_fee_exempt_keys() are currently implemented.
• Compare the implementation with the other SDK's TopicUpdateTransaction, specifically the addFeeExemptKey() method, to maintain API consistency across SDKs. For Reference
• Look at other transaction classes in the Python SDK that provide both set_*() and add_*() methods to follow existing conventions for validation, frozen-state checks, and method chaining.
• Add or update unit tests under the topic transaction test suite to verify the new method's behavior.

🛠️ Implementation Notes

• Add an add_fee_exempt_key() method to TopicUpdateTransaction.
• Ensure the method validates the input and calls _require_not_frozen() before modifying the transaction.
• Method should return self to support method chaining.
• Add unit tests covering the changes made

🧠 Beginner Contributors — Prerequisites & Expectations

Caution

Beginner issues are low-risk but we expect a working solution.

Important

We recommend completing at least 3 Good First Issues before attempting a beginner issue.

Difficulty:

• Requires building knowledge of the specific file(s)
• Beginner to intermediate Coding skills

Tip

You should be comfortable with:

• Forking, branching, committing (with DCO + GPG signing), and opening a pull request without a tutorial
• Reading beginner to intermediate code you did not write and following its patterns
• Handling simple merge conflicts
• Keeping your fork up to date with main by rebasing
• Looking things up on your own before asking for help

If any of that feels unfamiliar, Good First Issues might still be the most rewarding path for you right now — find one here.
You can always come back when you are ready.

⚠️ AI Usage Policy

• AI can help you understand the codebase and the problem
• Using AI to generate code for beginner 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: ~1 Week / ~8 hours.
  🧩 Difficulty: Manageable but requires investigation and testing
  🎓 Best for: Beginner contributors

• 🔴 Completing a beginner issue in 1–3 hours 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 beginner level, testing will be necessary but a small component.
The methods you implement should be verified (happy path at least)

How you test depends on the type of change.

Source code changes (e.g. in src/):

• Write basic unit tests
• Run tests locally: uv run pytest tests/unit/<specific_file>_test.py -v
• Integration tests will run automatically when you push

GitHub Actions / workflow changes (e.g. in .github/): Guide

• Test by merging to your fork's main and simulating the scenario

Example script changes (e.g. in examples/):

• Run the example script and confirm output matches expected behavior
• You will need a Hedera Portal account for testnet credentials

🛡️ Quality & Review Standards

Beginner PRs must be working and follow best practices.

1. Working: The implementation must solve the problem and meet the acceptance criteria.
2. SDK Best Practices: The solution should fit well with existing SDK patterns and abstractions.
3. Testing: basic unit and possibly integration tests to demonstrate the implementation works as expected.

⚠️ Breaking changes

• Watch for any changes that could impact existing users, even if they seem small.

🤖 AI notes

• AI has gaps or incorrect understanding of repo-specific patterns, logic, and protobuf schemes.

✅ PR Quality Checklist

Before opening your PR, confirm:

• I have spent the majority of my time researching the problem and building my understanding of the codebase and methods.
• My implementation works and is tested (if applicable).
• Every line of code is personally understood and explainable.
• My changes address what the issue asked for — nothing more, nothing less
• I have applied appropriate linting, code quality, and formatting tools used in this repo.

Before requesting a review, confirm:

• 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 included appropriate tests and all CI checks pass.

📋 Workflow quick reference

You have done this before — 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
Resolve merge conflicts	Merge conflicts guide

📚 Resources & Support

🆘 Stuck?

Tip

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

Python SDK References:

• Windows Setup Guide — platform-specific installation steps
• Pylance guide — inline type checking during development
• Running examples
• Browse closed beginner PRs — see how others did it

References:

• Hedera Protobufs
• 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 single add_fee_exempt_key() method to TopicUpdateTransaction that lazily initializes the nullable fee_exempt_keys list, appends one Key, guards with _require_not_frozen(), and returns self.
• Follow the existing update-style nullable-list add_* convention (as in NodeUpdateTransaction/RegisteredNodeUpdateTransaction) to preserve the established None vs. [] semantics used by _build_proto_body.
• Cover the new method with focused unit tests for append behavior, chaining, and frozen-state validation, mirroring existing patterns in the topic transaction test suite.

Implementation Steps

Phase 1: Implement add_fee_exempt_key() Method

This phase adds the new convenience method to the transaction class, mirroring the established nullable-list "add" convention already used by update-style transactions in the SDK so it integrates naturally with existing set/clear semantics.

Add `add_fee_exempt_key()` to TopicUpdateTransaction

Introduce a single-item append method consistent with sibling add_* methods and the existing fee exempt key handling.

• Modify src/hiero_sdk_python/consensus/topic_update_transaction.py, placing the new method alongside the existing set_fee_exempt_keys() / clear_fee_exempt_keys() methods.
• Method signature should accept a single Key parameter and return the TopicUpdateTransaction instance for chaining.
• Call self._require_not_frozen() first, matching every other mutator in the file.
• Because fee_exempt_keys defaults to None (with meaningful "untouched" semantics preserved in _build_proto_body), lazily initialize the list when None before appending — mirroring the add_service_endpoint / add_associated_registered_node pattern rather than the always-initialized style.
• Append the key to self.fee_exempt_keys and return self.
• Use a Google-style docstring with Args: and Returns: sections consistent with neighboring methods. Follow the lightweight validation style of the existing sibling key setters in this file (which defer type enforcement to key_to_proto() at build time) unless team convention favors an explicit isinstance check.

🤖 Prompt for AI agents

Implement a new `add_fee_exempt_key()` convenience method on
`TopicUpdateTransaction` to provide API parity with other Hiero SDKs.

- Modify `src/hiero_sdk_python/consensus/topic_update_transaction.py`, placing
the new method alongside the existing `set_fee_exempt_keys()` and
`clear_fee_exempt_keys()` methods.
- The method should accept a single `Key` parameter and return the
`TopicUpdateTransaction` instance (`self`) to support method chaining.
- Call `self._require_not_frozen()` first, matching every other mutator in the
file.
- Since `fee_exempt_keys` defaults to `None` (with `None` meaning "leave
untouched" and `[]` meaning "explicitly clear", semantics preserved in
`_build_proto_body`), lazily initialize the list to an empty list when it is
`None` before appending — mirror the pattern used by `add_service_endpoint` /
`add_associated_registered_node` (nullable-list "add" convention) rather than
always initializing upfront.
- Append the given key to `self.fee_exempt_keys` and `return self`.
- Write a Google-style docstring with `Args:` and `Returns:` sections consistent
with neighboring methods.
- Follow the lightweight validation style of the existing sibling key setters in
this file, which defer type enforcement to `key_to_proto()` at build time,
unless team convention favors an explicit `isinstance` check.

Phase 2: Add Unit Test Coverage

This phase verifies the new method's happy path, chaining behavior, lazy list initialization, and frozen-state guarding, following the established test conventions for this class.

Add unit tests for `add_fee_exempt_key()`

Extend the existing test suite to cover the new method.

• Modify tests/unit/topic_update_transaction_test.py, reusing the existing create_key helper and conftest fixtures (topic_id, mock_account_ids, mock_client).
• Add a test verifying that calling add_fee_exempt_key(key) on a fresh transaction (with fee_exempt_keys initially None) initializes the list and appends the key, and that the method returns self (following the add_custom_fee_limit test template).
• Add a test verifying that multiple add_fee_exempt_key() calls accumulate keys, and optionally that combining set_fee_exempt_keys([...]) followed by add_fee_exempt_key(...) appends correctly.
• Extend or add a frozen-state test (following the test_set_methods_require_not_frozen pattern) asserting that calling add_fee_exempt_key() after freeze_with(mock_client) raises Exception matching "Transaction is immutable; it has been frozen".
• Run locally with uv run pytest tests/unit/topic_update_transaction_test.py -v.

🤖 Prompt for AI agents

Add unit test coverage for the new `add_fee_exempt_key()` method in
`TopicUpdateTransaction`, following existing conventions in the test suite.

- Modify `tests/unit/topic_update_transaction_test.py`, reusing the existing
`create_key` helper and conftest fixtures (`topic_id`, `mock_account_ids`,
`mock_client`).
- Add a test verifying that calling `add_fee_exempt_key(key)` on a fresh
transaction (where `fee_exempt_keys` is initially `None`) initializes the list,
appends the key, and that the method returns `self` — following the
`add_custom_fee_limit` test template.
- Add a test verifying that multiple `add_fee_exempt_key()` calls accumulate
keys correctly, and optionally verify that combining
`set_fee_exempt_keys([...])` followed by `add_fee_exempt_key(...)` appends
correctly.
- Extend or add a frozen-state test, following the
`test_set_methods_require_not_frozen` pattern, asserting that calling
`add_fee_exempt_key()` after `freeze_with(mock_client)` raises an `Exception`
matching "Transaction is immutable; it has been frozen".
- Run the tests locally with `uv run pytest
tests/unit/topic_update_transaction_test.py -v` to confirm correctness.

Research

The Hiero Python SDK organizes transaction types under src/hiero_sdk_python/, with consensus/topic transactions in consensus/. TopicUpdateTransaction (in consensus/topic_update_transaction.py) already exposes set_fee_exempt_keys() and clear_fee_exempt_keys(), backed by a nullable fee_exempt_keys: list[Key] | None attribute where None means "leave untouched" and [] means "explicitly clear". All mutators call the inherited _require_not_frozen() guard (from the base Transaction class) and return self for chaining. The SDK has a well-established set_*()/add_*() pairing convention (e.g., RegisteredNodeUpdateTransaction.add_service_endpoint, NodeUpdateTransaction.add_associated_registered_node) that lazily initializes nullable lists before appending. Unit tests for this class live in tests/unit/topic_update_transaction_test.py, using shared conftest fixtures and local key-generation helpers.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement a new `add_fee_exempt_key()` convenience method on
`TopicUpdateTransaction` to provide API parity with other Hiero SDKs.

- Modify `src/hiero_sdk_python/consensus/topic_update_transaction.py`, placing
the new method alongside the existing `set_fee_exempt_keys()` and
`clear_fee_exempt_keys()` methods.
- The method should accept a single `Key` parameter and return the
`TopicUpdateTransaction` instance (`self`) to support method chaining.
- Call `self._require_not_frozen()` first, matching every other mutator in the
file.
- Since `fee_exempt_keys` defaults to `None` (with `None` meaning "leave
untouched" and `[]` meaning "explicitly clear", semantics preserved in
`_build_proto_body`), lazily initialize the list to an empty list when it is
`None` before appending — mirror the pattern used by `add_service_endpoint` /
`add_associated_registered_node` (nullable-list "add" convention) rather than
always initializing upfront.
- Append the given key to `self.fee_exempt_keys` and `return self`.
- Write a Google-style docstring with `Args:` and `Returns:` sections consistent
with neighboring methods.
- Follow the lightweight validation style of the existing sibling key setters in
this file, which defer type enforcement to `key_to_proto()` at build time,
unless team convention favors an explicit `isinstance` check.
===============================================================================

Task: 2

Add unit test coverage for the new `add_fee_exempt_key()` method in
`TopicUpdateTransaction`, following existing conventions in the test suite.

- Modify `tests/unit/topic_update_transaction_test.py`, reusing the existing
`create_key` helper and conftest fixtures (`topic_id`, `mock_account_ids`,
`mock_client`).
- Add a test verifying that calling `add_fee_exempt_key(key)` on a fresh
transaction (where `fee_exempt_keys` is initially `None`) initializes the list,
appends the key, and that the method returns `self` — following the
`add_custom_fee_limit` test template.
- Add a test verifying that multiple `add_fee_exempt_key()` calls accumulate
keys correctly, and optionally verify that combining
`set_fee_exempt_keys([...])` followed by `add_fee_exempt_key(...)` appends
correctly.
- Extend or add a frozen-state test, following the
`test_set_methods_require_not_frozen` pattern, asserting that calling
`add_fee_exempt_key()` after `freeze_with(mock_client)` raises an `Exception`
matching "Transaction is immutable; it has been frozen".
- Run the tests locally with `uv run pytest
tests/unit/topic_update_transaction_test.py -v` to confirm correctness.

💡 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.

---

💬 Have feedback or questions? Drop into our discord!

[rayank906]

/assign