feat(tck): implement updateTokenFeeSchedule JSON-RPC method

[exploreriii]

Problem updateTokenFeeSchedule is missing; the driver's TokenFeeScheduleUpdateTransaction suites cannot run.

Solution New handler taking tokenId + customFees. Reuse the existing CustomFeeParams parsing from tck/param/custom_fee.py (already used by createToken) — fixed, fractional, and royalty fees with fallback.

Spec: https://github.com/hiero-ledger/hiero-sdk-tck/blob/main/docs/test-specifications/token-service/TokenFeeScheduleUpdateTransaction.md
JS reference: https://github.com/hiero-ledger/hiero-sdk-js/blob/main/tck/methods/token.ts (updateTokenFeeSchedule)
SDK class: TokenFeeScheduleUpdateTransaction

[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 spec-aligned UpdateTokenFeeScheduleParams and a status-only UpdateTokenFeeScheduleResponse, reusing the existing CustomFeeParams parsing already used by createToken.
• Implement update_token_fee_schedule in tck/handlers/token.py, reusing _build_custom_fee to configure a TokenFeeScheduleUpdateTransaction and following the established execute/receipt/response pattern.
• Register the method via @rpc_method("updateTokenFeeSchedule") (auto-discovered through existing imports) and add a mocked handler test validating parsing, transaction construction, and response shape.

Design Choices

Design Choice 1: Response shape for `updateTokenFeeSchedule`

Options Considered:

1. Reuse the shared StatusOnlyResponse from tck/response/base.py directly.
2. Define a dedicated UpdateTokenFeeScheduleResponse subclass of StatusOnlyResponse in tck/response/token.py.

Chosen Option: 2

Rationale: The operation is an update (not a creation), so it does not need to return a tokenId — only a transaction status. A thin dedicated subclass keeps naming consistent with other token responses (e.g., DeleteTokenResponse, PauseTokenResponse) and aids discoverability, while still inheriting the status-only shape.

💡 User Tips

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

Implementation Steps

Phase 1: Define request/response contracts for the new method

Establish the data contract for the JSON-RPC method so parsing and serialization match the TCK spec (tokenId, customFees, commonTransactionParams in; status out). This phase focuses on the parameter and response dataclasses, deliberately reusing the existing custom-fee parsing machinery rather than duplicating it.

Task 1: Add the `UpdateTokenFeeScheduleParams` dataclass

Introduce a param type that mirrors the spec fields and reuses existing fee parsing.

• Add an UpdateTokenFeeScheduleParams dataclass in tck/param/token.py, modeled on the existing DeleteTokenParams/CreateTokenParams conventions.
• Declare a required tokenId field, an optional customFees list, and an optional commonTransactionParams field, matching the naming and typing style already used in the module.
• Implement its parse_json_params classmethod to convert the raw customFees JSON list into CustomFeeParams objects using the same parsing path CreateTokenParams already uses (from tck/param/custom_fee.py), and to parse commonTransactionParams identically to other token params.
• If tck/param/__init__.py re-exports param classes, add UpdateTokenFeeScheduleParams there for consistency.

Task 2: Add the `UpdateTokenFeeScheduleResponse` dataclass

Provide a status-only response type consistent with sibling token endpoints.

• Add UpdateTokenFeeScheduleResponse in tck/response/token.py as a subclass of StatusOnlyResponse (from tck/response/base.py), following the pattern of DeleteTokenResponse/PauseTokenResponse.
• If tck/response/__init__.py re-exports response classes, add the new class there.

🤖 Prompt for AI agents

Implement the data contract (param and response dataclasses) for the new
`updateTokenFeeSchedule` JSON-RPC method.

- In `tck/param/token.py`, add an `UpdateTokenFeeScheduleParams` dataclass
modeled on the existing `DeleteTokenParams`/`CreateTokenParams` conventions:
- Fields: required `tokenId`, optional `customFees` list, optional
`commonTransactionParams`, matching naming/typing style already used in the
module.
- Implement `parse_json_params` classmethod to convert raw `customFees` JSON
list into `CustomFeeParams` objects, reusing the exact parsing path already used
by `CreateTokenParams` (from `tck/param/custom_fee.py`); parse
`commonTransactionParams` identically to other token params.
- If `tck/param/__init__.py` re-exports param classes, add
`UpdateTokenFeeScheduleParams` there too.
- In `tck/response/token.py`, add `UpdateTokenFeeScheduleResponse` as a subclass
of `StatusOnlyResponse` (from `tck/response/base.py`), following the pattern of
`DeleteTokenResponse`/`PauseTokenResponse`.
- If `tck/response/__init__.py` re-exports response classes, add the new
response class there too.
- Do not introduce any new fee-conversion logic; reuse existing helpers
verbatim.

Phase 2: Implement and register the handler

Wire the new method into the token handler module so it builds, executes, and reports the transaction result, reusing existing custom-fee construction helpers.

Task 1: Add the transaction-builder helper

Create a private builder that translates parsed params into a configured SDK transaction.

• Add a _build_update_token_fee_schedule_transaction helper in tck/handlers/token.py, placed alongside create_token and its fee helpers.
• Construct a TokenFeeScheduleUpdateTransaction, set the token via set_token_id, and set the fee list via set_custom_fees, building each fee by reusing the existing _build_custom_fee helper per CustomFeeParams entry (no new fee-conversion logic).
• Handle the empty/absent customFees case by passing an empty list, which the SDK treats as clearing the fee schedule.

Task 2: Add and register the `updateTokenFeeSchedule` handler

Expose the JSON-RPC method following the established execute/receipt/response flow.

• Add an update_token_fee_schedule handler in tck/handlers/token.py decorated with @rpc_method("updateTokenFeeSchedule").
• Follow the existing token-handler flow: obtain the client (as create_token/delete_token do), build the transaction via the new helper, apply CommonTransactionParams (freeze/sign) when present, execute, retrieve the receipt with status validation, and return an UpdateTokenFeeScheduleResponse populated with ResponseCode(receipt.status).name.
• No change is required in tck/handlers/__init__.py since token.py is already imported for decorator-based registration; confirm this holds.

🤖 Prompt for AI agents

Implement and register the `updateTokenFeeSchedule` JSON-RPC handler in
`tck/handlers/token.py`, reusing existing fee-building and transaction-execution
machinery.

- Add a `_build_update_token_fee_schedule_transaction` private helper alongside
`create_token` and its fee helpers:
  - Construct a `TokenFeeScheduleUpdateTransaction`.
  - Set the token via `set_token_id`.
- Set the fee list via `set_custom_fees`, building each fee by reusing the
existing `_build_custom_fee` helper per `CustomFeeParams` entry — do not
introduce new fee-conversion logic.
- Handle the empty/absent `customFees` case by passing an empty list (the SDK
treats this as clearing the fee schedule).
- Add an `update_token_fee_schedule` handler function decorated with
`@rpc_method("updateTokenFeeSchedule")`, following the existing token-handler
flow used by `create_token`/`delete_token`:
  - Obtain the client.
  - Build the transaction via the new helper.
  - Apply `CommonTransactionParams` (freeze/sign) when present.
  - Execute the transaction.
  - Retrieve the receipt with status validation.
- Return an `UpdateTokenFeeScheduleResponse` populated with
`ResponseCode(receipt.status).name`.
- Confirm no change is needed in `tck/handlers/__init__.py` since `token.py` is
already imported for decorator-based registration.
- Before coding, re-read `tck/handlers/token.py`, `tck/util/`,
`tck/param/token.py`, `tck/param/custom_fee.py`, and
`tck/param/common_transaction_params.py` to mirror exact signatures and the
client/receipt idiom used by `create_token`/`delete_token`.

Phase 3: Testing

Add coverage validating that the method parses params correctly, builds the right transaction, and returns the expected status-only response.

Add a handler-level test for `updateTokenFeeSchedule`

Verify dispatch, param application, and response shape without hitting a live network.

• Add a new test (e.g., under tests/tck/) that mocks the client and the transaction's execute/get_receipt, following the mocking approach in tests/tck/common_params_test.py and the SDK usage patterns in tests/unit/token_fee_schedule_update_transaction_test.py.
• Assert that the handler builds a TokenFeeScheduleUpdateTransaction with the expected token_id and custom_fees (covering at least a fixed fee and a royalty fee with fallback), and that it returns a {"status": ...}-shaped result.

🤖 Prompt for AI agents

Add test coverage for the new `updateTokenFeeSchedule` handler.

- Add a new test file (e.g., under `tests/tck/`) that mocks the client and the
transaction's `execute`/`get_receipt`, following the mocking approach used in
`tests/tck/common_params_test.py` and the SDK usage patterns in
`tests/unit/token_fee_schedule_update_transaction_test.py`.
- Assert that the handler builds a `TokenFeeScheduleUpdateTransaction` with the
expected `token_id` and `custom_fees`, covering at least a fixed fee and a
royalty fee with fallback.
- Assert that the handler returns a `{"status": ...}`-shaped result.

Research

The TCK layer lives under tck/ and mirrors the Hiero SDK's JSON-RPC test-driver contract. Token endpoints are consolidated in a single module tck/handlers/token.py, where each JSON-RPC method is a snake_case function registered via the @rpc_method("camelCase") decorator from tck/handlers/registry.py; tck/handlers/__init__.py imports every handler module to trigger registration. Each handler parses a param dataclass (from tck/param/), builds an SDK transaction (often through a private _build_*_transaction helper), applies CommonTransactionParams (freeze/sign), executes it, reads the receipt, and returns a response dataclass (from tck/response/), which the dispatcher serializes to JSON. The SDK class TokenFeeScheduleUpdateTransaction (src/hiero_sdk_python/tokens/token_fee_schedule_update_transaction.py) exposes set_token_id() and set_custom_fees() and accepts the same CustomFixedFee/CustomFractionalFee/CustomRoyaltyFee objects that the existing _build_custom_fee helper (currently used by create_token) already produces from CustomFeeParams.

Follow-up Agent Notes

• The exact bodies of _build_custom_fee, _apply_custom_fee_common_fields, create_token's client-acquisition/execute/receipt flow, get_client(), and CommonTransactionParams.apply_common_params could not be read during exploration (transient tooling failures). Before coding, re-read tck/handlers/token.py, tck/util/, tck/param/token.py, tck/param/custom_fee.py, and tck/param/common_transaction_params.py to mirror exact signatures and the client/receipt idiom used by create_token/delete_token.
• Reuse existing helpers verbatim; do not introduce new fee-conversion abstractions.

File-Level Change Summary

• tck/param/token.py: add UpdateTokenFeeScheduleParams (fields tokenId, customFees, commonTransactionParams) with parse_json_params reusing custom_fee.py parsing.
• tck/param/__init__.py: re-export the new param class if the module follows a re-export pattern.
• tck/response/token.py: add UpdateTokenFeeScheduleResponse(StatusOnlyResponse).
• tck/response/__init__.py: re-export the new response class if applicable.
• tck/handlers/token.py: add _build_update_token_fee_schedule_transaction (reusing _build_custom_fee) and the update_token_fee_schedule handler registered as "updateTokenFeeSchedule".
• tests/tck/: add a new test file exercising the handler with mocked client/transaction.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the data contract (param and response dataclasses) for the new
`updateTokenFeeSchedule` JSON-RPC method.

- In `tck/param/token.py`, add an `UpdateTokenFeeScheduleParams` dataclass
modeled on the existing `DeleteTokenParams`/`CreateTokenParams` conventions:
- Fields: required `tokenId`, optional `customFees` list, optional
`commonTransactionParams`, matching naming/typing style already used in the
module.
- Implement `parse_json_params` classmethod to convert raw `customFees` JSON
list into `CustomFeeParams` objects, reusing the exact parsing path already used
by `CreateTokenParams` (from `tck/param/custom_fee.py`); parse
`commonTransactionParams` identically to other token params.
- If `tck/param/__init__.py` re-exports param classes, add
`UpdateTokenFeeScheduleParams` there too.
- In `tck/response/token.py`, add `UpdateTokenFeeScheduleResponse` as a subclass
of `StatusOnlyResponse` (from `tck/response/base.py`), following the pattern of
`DeleteTokenResponse`/`PauseTokenResponse`.
- If `tck/response/__init__.py` re-exports response classes, add the new
response class there too.
- Do not introduce any new fee-conversion logic; reuse existing helpers
verbatim.
===============================================================================

Task: 2

Implement and register the `updateTokenFeeSchedule` JSON-RPC handler in
`tck/handlers/token.py`, reusing existing fee-building and transaction-execution
machinery.

- Add a `_build_update_token_fee_schedule_transaction` private helper alongside
`create_token` and its fee helpers:
  - Construct a `TokenFeeScheduleUpdateTransaction`.
  - Set the token via `set_token_id`.
- Set the fee list via `set_custom_fees`, building each fee by reusing the
existing `_build_custom_fee` helper per `CustomFeeParams` entry — do not
introduce new fee-conversion logic.
- Handle the empty/absent `customFees` case by passing an empty list (the SDK
treats this as clearing the fee schedule).
- Add an `update_token_fee_schedule` handler function decorated with
`@rpc_method("updateTokenFeeSchedule")`, following the existing token-handler
flow used by `create_token`/`delete_token`:
  - Obtain the client.
  - Build the transaction via the new helper.
  - Apply `CommonTransactionParams` (freeze/sign) when present.
  - Execute the transaction.
  - Retrieve the receipt with status validation.
- Return an `UpdateTokenFeeScheduleResponse` populated with
`ResponseCode(receipt.status).name`.
- Confirm no change is needed in `tck/handlers/__init__.py` since `token.py` is
already imported for decorator-based registration.
- Before coding, re-read `tck/handlers/token.py`, `tck/util/`,
`tck/param/token.py`, `tck/param/custom_fee.py`, and
`tck/param/common_transaction_params.py` to mirror exact signatures and the
client/receipt idiom used by `create_token`/`delete_token`.
===============================================================================

Task: 3

Add test coverage for the new `updateTokenFeeSchedule` handler.

- Add a new test file (e.g., under `tests/tck/`) that mocks the client and the
transaction's `execute`/`get_receipt`, following the mocking approach used in
`tests/tck/common_params_test.py` and the SDK usage patterns in
`tests/unit/token_fee_schedule_update_transaction_test.py`.
- Assert that the handler builds a `TokenFeeScheduleUpdateTransaction` with the
expected `token_id` and `custom_fees`, covering at least a fixed fee and a
royalty fee with fallback.
- Assert that the handler returns a `{"status": ...}`-shaped result.

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

[github-actions]

Hi @Adityarya11 👋

This issue has been assigned but no pull request has been created yet.
Are you still planning on working on it?
If you are, please create a draft PR linked to this issue or comment /working to let us know.
If you're no longer able to work on this issue, you can comment /unassign to release it.

From the Python SDK Team

[Adityarya11]

/working