Add `add_custom_fee()` 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 SDK currently provides the following methods on TopicUpdateTransaction for managing custom fees:

• set_custom_fees()
• clear_custom_fees()

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

💡 Expected Solution

Add an add_custom_fee() method to TopicUpdateTransaction that appends a single CustomFixedFee to the transaction custom fee list.

🔍 Research Pointers

• Review hiero_sdk_python/topic/topic_update_transaction.py, where set_custom_fees() and clear_custom_fees() are currently implemented.
• Compare the implementation with the other SDK's TopicUpdateTransaction, specifically the addCustomFee() 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/Update unit tests under for the topic transaction to verify the new behavior.

🛠️ Implementation Notes

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

🧠 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_custom_fee() method to TopicUpdateTransaction that guards against a frozen transaction, validates the input type, lazily initializes the nullable custom_fees list, appends the fee, and returns self.
• Follow the SDK's established add_*()/set_*() idiom, specifically the None-guard variant used for nullable list attributes in *_update_transaction.py classes.
• Add focused unit tests covering the happy path, append/chaining behavior, type validation, and the frozen-state guard, modeled on existing sibling test files.

Design Choices

Design Choice 1: Should `add_custom_fee()` perform runtime `isinstance` type validation on its argument?

Options Considered:

1. No isinstance check — match the directly analogous custom-fee/consensus methods; treat _require_not_frozen() as the "validation" the ticket refers to.
2. Add an isinstance(custom_fee, CustomFixedFee) check raising TypeError — match the more rigorously validated add_*() methods and satisfy the "validate the input" note literally.

Chosen Option: 2

Rationale: Adding a lightweight isinstance check with a TypeError directly satisfies the ticket's explicit "validate the input" requirement while still following an established SDK pattern; it is low-risk and makes the method more robust for beginner-facing usage.

💡 User Tips

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

Implementation Steps

Phase 1: Add the add_custom_fee() method

This phase introduces the new convenience method on TopicUpdateTransaction, mirroring the existing custom-fee setters and the nullable-list add_*() pattern used elsewhere in the SDK.

Implement `add_custom_fee()` on TopicUpdateTransaction

Add a chainable method that appends a single CustomFixedFee to the transaction's custom fee list.

• Modify src/hiero_sdk_python/consensus/topic_update_transaction.py, placing the new method adjacent to set_custom_fees() / clear_custom_fees().
• Accept a single parameter custom_fee: CustomFixedFee and annotate the return type as TopicUpdateTransaction.
• Call self._require_not_frozen() as the first line, consistent with every other mutator in the class.
• Validate the argument with an isinstance(custom_fee, CustomFixedFee) check, raising TypeError with a descriptive message (e.g., "custom_fee must be a CustomFixedFee instance.") per the ticket's validation requirement.
• Apply the None-guard pattern before appending: since self.custom_fees defaults to None, initialize it to [] when it is None, then append() the fee. This mirrors NodeUpdateTransaction.add_associated_registered_node() and preserves the tri-state (None / [] / populated) semantics that _build_proto_body() relies on.
• Return self to support method chaining.
• Provide a Google-style docstring with Args:, Returns:, and Raises: sections matching the surrounding methods' conventions.
• No changes to imports are required (CustomFixedFee is already imported).

🤖 Prompt for AI agents

Implement a new `add_custom_fee()` convenience method on
`TopicUpdateTransaction` in
`src/hiero_sdk_python/consensus/topic_update_transaction.py`. Goal: allow
appending a single `CustomFixedFee` to the transaction's custom fee list
following existing SDK patterns.

- Place the new method adjacent to `set_custom_fees()` / `clear_custom_fees()`.
- Signature: accept a single parameter `custom_fee: CustomFixedFee`, and
annotate the return type as `TopicUpdateTransaction`.
- First line of the method body must call `self._require_not_frozen()`,
consistent with every other mutator in the class.
- Validate the argument with `isinstance(custom_fee, CustomFixedFee)`; if it
fails, raise `TypeError` with a descriptive message such as `"custom_fee must be
a CustomFixedFee instance."`.
- Since `self.custom_fees` defaults to `None`, apply a None-guard: if
`self.custom_fees` is `None`, initialize it to `[]` before appending, mirroring
`NodeUpdateTransaction.add_associated_registered_node()`. This preserves the
tri-state (`None` / `[]` / populated) semantics relied upon by
`_build_proto_body()`.
- Append `custom_fee` to `self.custom_fees`.
- Return `self` to support method chaining.
- Add a Google-style docstring with `Args:`, `Returns:`, and `Raises:` sections
matching the conventions of surrounding methods.
- No import changes are needed since `CustomFixedFee` is already imported in
this file.

Phase 2: Add unit test coverage

This phase verifies the new method's happy path, chaining behavior, None-initialization handling, validation, and frozen-state guard, using the established test conventions.

Add unit tests for `add_custom_fee()`

Add net-new tests to the existing topic update test module.

• Modify tests/unit/topic_update_transaction_test.py, following the direct-attribute-and-identity assertion style from tests/unit/topic_create_transaction_test.py and the structure of tests/unit/custom_fee_limit_test.py::test_add_custom_fee.
• Construct CustomFixedFee instances inline (as this file already does) or add a local fixture consistent with the sibling topic_create_transaction_test.py.
• Cover the following cases:
  • Adding a fee when custom_fees starts as None results in a single-element list and the returned value is the transaction instance (result is tx).
  • Adding a second fee appends rather than replaces (list length grows, order preserved).
  • Method chaining works across multiple add_custom_fee() calls.
  • Passing a non-CustomFixedFee argument raises TypeError.
  • Calling add_custom_fee() after freeze_with(mock_client) raises the immutability exception, using pytest.raises(Exception, match="Transaction is immutable; it has been frozen").
• Ensure the module-level pytestmark = pytest.mark.unit tag and per-test docstrings are respected, consistent with existing tests.

🤖 Prompt for AI agents

Add unit tests for the new `add_custom_fee()` method in
`tests/unit/topic_update_transaction_test.py`. Goal: verify happy path,
append/chaining behavior, None-initialization handling, type validation, and the
frozen-state guard.

- Follow the direct-attribute-and-identity assertion style from
`tests/unit/topic_create_transaction_test.py` and the structure of
`tests/unit/custom_fee_limit_test.py::test_add_custom_fee`.
- Construct `CustomFixedFee` instances inline (as the file already does) or add
a local fixture consistent with the sibling `topic_create_transaction_test.py`.
- Add tests covering:
- Adding a fee when `custom_fees` starts as `None` results in a single-element
list, and the returned value is the same transaction instance (`result is tx`).
- Adding a second fee appends rather than replaces (list length grows, order
preserved).
  - Method chaining works correctly across multiple `add_custom_fee()` calls.
  - Passing a non-`CustomFixedFee` argument raises `TypeError`.
- Calling `add_custom_fee()` after `freeze_with(mock_client)` raises the
immutability exception, verified via `pytest.raises(Exception,
match="Transaction is immutable; it has been frozen")`.
- Respect the module-level `pytestmark = pytest.mark.unit` tag and include
per-test docstrings, consistent with existing tests in the file.

Research

The Hiero Python SDK organizes transaction classes under src/hiero_sdk_python/, with consensus/topic transactions under consensus/. TopicUpdateTransaction (src/hiero_sdk_python/consensus/topic_update_transaction.py) extends the base Transaction and manages a nullable custom_fees: list[CustomFixedFee] | None attribute (defaulting to None), currently mutated only via set_custom_fees() and clear_custom_fees(). CustomFixedFee lives in src/hiero_sdk_python/tokens/custom_fixed_fee.py. The SDK has a well-established add_*()/set_*() pairing idiom across many transaction classes, where add_*() methods call _require_not_frozen() first, append to the list, and return self. For nullable list attributes, methods use a None-guard before appending (as in NodeUpdateTransaction.add_associated_registered_node()). Unit tests live in tests/unit/, with topic_update_transaction_test.py being the target file and topic_create_transaction_test.py serving as the closest template.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement a new `add_custom_fee()` convenience method on
`TopicUpdateTransaction` in
`src/hiero_sdk_python/consensus/topic_update_transaction.py`. Goal: allow
appending a single `CustomFixedFee` to the transaction's custom fee list
following existing SDK patterns.

- Place the new method adjacent to `set_custom_fees()` / `clear_custom_fees()`.
- Signature: accept a single parameter `custom_fee: CustomFixedFee`, and
annotate the return type as `TopicUpdateTransaction`.
- First line of the method body must call `self._require_not_frozen()`,
consistent with every other mutator in the class.
- Validate the argument with `isinstance(custom_fee, CustomFixedFee)`; if it
fails, raise `TypeError` with a descriptive message such as `"custom_fee must be
a CustomFixedFee instance."`.
- Since `self.custom_fees` defaults to `None`, apply a None-guard: if
`self.custom_fees` is `None`, initialize it to `[]` before appending, mirroring
`NodeUpdateTransaction.add_associated_registered_node()`. This preserves the
tri-state (`None` / `[]` / populated) semantics relied upon by
`_build_proto_body()`.
- Append `custom_fee` to `self.custom_fees`.
- Return `self` to support method chaining.
- Add a Google-style docstring with `Args:`, `Returns:`, and `Raises:` sections
matching the conventions of surrounding methods.
- No import changes are needed since `CustomFixedFee` is already imported in
this file.
===============================================================================

Task: 2

Add unit tests for the new `add_custom_fee()` method in
`tests/unit/topic_update_transaction_test.py`. Goal: verify happy path,
append/chaining behavior, None-initialization handling, type validation, and the
frozen-state guard.

- Follow the direct-attribute-and-identity assertion style from
`tests/unit/topic_create_transaction_test.py` and the structure of
`tests/unit/custom_fee_limit_test.py::test_add_custom_fee`.
- Construct `CustomFixedFee` instances inline (as the file already does) or add
a local fixture consistent with the sibling `topic_create_transaction_test.py`.
- Add tests covering:
- Adding a fee when `custom_fees` starts as `None` results in a single-element
list, and the returned value is the same transaction instance (`result is tx`).
- Adding a second fee appends rather than replaces (list length grows, order
preserved).
  - Method chaining works correctly across multiple `add_custom_fee()` calls.
  - Passing a non-`CustomFixedFee` argument raises `TypeError`.
- Calling `add_custom_fee()` after `freeze_with(mock_client)` raises the
immutability exception, verified via `pytest.raises(Exception,
match="Transaction is immutable; it has been frozen")`.
- Respect the module-level `pytestmark = pytest.mark.unit` tag and include
per-test docstrings, consistent with existing tests in the file.

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