feat(tck): implement burnToken JSON-RPC method

[exploreriii]

Problem The TCK server does not implement burnToken, so the TCK driver's TokenBurnTransaction suites cannot run against the Python SDK.

Solution
Add a burnToken handler similar to the existing mintToken handler in tck/handlers/token.py.

Spec: https://github.com/hiero-ledger/hiero-sdk-tck/blob/main/docs/test-specifications/token-service/TokenBurnTransaction.md

JS reference: https://github.com/hiero-ledger/hiero-sdk-js/blob/main/tck/methods/token.ts (burnToken)

[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 BurnTokenParams and BurnTokenResponse models following the existing MintTokenParams/ClaimTokenParams and MintTokenResponse patterns.
• Implement a self-registering @rpc_method("burnToken") handler plus a transaction builder that branches between fungible (amount) and NFT (serials) burns to respect the SDK's mutual-exclusivity constraint.
• Reuse all shared infrastructure (client resolution, common-transaction-params application, dispatch/registry, result serialization) with no changes to registry or server wiring.
• Add a flat unit test module under tests/tck/ covering params parsing, transaction construction, and handler response, using existing MagicMock-based mocking conventions.

Implementation Steps

Phase 1: Add burnToken request/response models and handler

This phase introduces the data contract and business logic for the new JSON-RPC method, closely following the established mintToken and claimToken patterns. The goal is a fully functional burnToken endpoint that self-registers with the dispatch registry and correctly handles both fungible and NFT burn semantics.

Task 1: Define the burnToken request params model

Introduce a BurnTokenParams dataclass to capture the burnToken JSON-RPC inputs.

• Add BurnTokenParams(BaseTransactionParams) to tck/param/token.py, modeled on MintTokenParams/ClaimTokenParams.
• Fields: tokenId: str | None, amount: str | None, serialNumbers: list[str] | None, plus inherited sessionId and commonTransactionParams.
• Implement parse_json_params following the standard idiom: pull optional fields via params.get(...), validate that serialNumbers (when present) is a list of strings (raise ValueError otherwise), and resolve sessionId/commonTransactionParams via the shared param_utils helpers.
• Keep tokenId/amount as raw optional strings (no required-field enforcement at parse time, matching mint), deferring coercion/validation to the handler and SDK layers.

Task 2: Define the burnToken response model

Introduce a BurnTokenResponse dataclass to shape the endpoint output.

• Add BurnTokenResponse to tck/response/token.py, mirroring MintTokenResponse but without serial numbers.
• Fields: newTotalSupply: str | None and status: str | None (burn receipts return an updated total supply; no serial numbers are returned by a burn).

Task 3: Implement the burnToken handler and transaction builder

Add the handler logic that constructs, executes, and reports on a TokenBurnTransaction.

• In tck/handlers/token.py, add a private _build_burn_token_transaction(params: BurnTokenParams) -> TokenBurnTransaction helper modeled on _build_mint_token_transaction.
• Set the gRPC deadline, set the token id via TokenId.from_string when provided, and branch cleanly between the FT path (set_amount(to_int(params.amount))) and the NFT path (set_serials([...]) from serialNumbers converted to ints) to respect the SDK's mutual-exclusivity constraint — avoid setting both.
• Add a @rpc_method("burnToken")-decorated burn_token(params: BurnTokenParams) -> BurnTokenResponse handler mirroring mint_token: resolve the client via get_client(params.sessionId), build the transaction, apply commonTransactionParams, execute with wait_for_receipt=False, fetch the receipt with validate_status=True, and return BurnTokenResponse(newTotalSupply=str(receipt.new_total_supply), status=ResponseCode(receipt.status).name).
• Import TokenBurnTransaction, BurnTokenParams, and BurnTokenResponse as needed. No registry edits are required since tck/handlers/__init__.py already imports the token module, so the decorator self-registers.

🤖 Prompt for AI agents

Implement the `burnToken` JSON-RPC method for the TCK server, mirroring the
existing `mintToken` implementation, and supporting both fungible-token (amount)
and NFT (serial numbers) burns.

1. Add `BurnTokenParams(BaseTransactionParams)` to `tck/param/token.py`, modeled
on `MintTokenParams`/`ClaimTokenParams`:
- Fields: `tokenId: str | None`, `amount: str | None`, `serialNumbers: list[str]
| None`, plus inherited `sessionId` and `commonTransactionParams`.
- Implement `parse_json_params` following the standard idiom: pull optional
fields via `params.get(...)`, validate that `serialNumbers` (when present) is a
list of strings (raise `ValueError` otherwise), and resolve
`sessionId`/`commonTransactionParams` via the shared `param_utils` helpers.
- Keep `tokenId`/`amount` as raw optional strings (no required-field enforcement
at parse time, matching mint), deferring coercion/validation to the handler and
SDK layers.

2. Add `BurnTokenResponse` to `tck/response/token.py`, mirroring
`MintTokenResponse` but without serial numbers:
   - Fields: `newTotalSupply: str | None` and `status: str | None`.

3. In `tck/handlers/token.py`:
- Add a private `_build_burn_token_transaction(params: BurnTokenParams) ->
TokenBurnTransaction` helper modeled on `_build_mint_token_transaction`. Set the
gRPC deadline, set the token id via `TokenId.from_string` when provided, and
branch cleanly between the FT path (`set_amount(to_int(params.amount))`) and the
NFT path (`set_serials([...])` from `serialNumbers` converted to ints) — avoid
setting both to respect the SDK's mutual-exclusivity constraint.
- Add a `@rpc_method("burnToken")`-decorated `burn_token(params:
BurnTokenParams) -> BurnTokenResponse` handler mirroring `mint_token`: resolve
the client via `get_client(params.sessionId)`, build the transaction, apply
`commonTransactionParams`, execute with `wait_for_receipt=False`, fetch the
receipt with `validate_status=True`, and return
`BurnTokenResponse(newTotalSupply=str(receipt.new_total_supply),
status=ResponseCode(receipt.status).name)`.
- Import `TokenBurnTransaction`, `BurnTokenParams`, and `BurnTokenResponse` as
needed.
- No registry edits are required since `tck/handlers/__init__.py` already
imports the `token` module, so the decorator self-registers.

Phase 2: Add test coverage for burnToken

This phase validates the new handler and params model in isolation from the network, following the existing TCK test conventions (flat file under tests/tck/, MagicMock-based stubbing, pytest.mark.unit).

Add burnToken handler and params tests

Create a test module verifying request parsing and transaction construction for both burn modes.

• Create tests/tck/burn_token_test.py (flat, matching the existing <module>_test.py convention) with pytestmark = pytest.mark.unit.
• Cover BurnTokenParams.parse_json_params: valid FT params, valid NFT params, and the serialNumbers shape-validation error cases.
• Cover _build_burn_token_transaction: assert token id and amount are set for the FT case, and serials are set for the NFT case, confirming both are not set simultaneously.
• Cover the burn_token handler by mocking the client (via get_client/MagicMock) and the transaction's execute/get_receipt to return a stubbed receipt, then assert the resulting BurnTokenResponse fields (newTotalSupply, status) — mirroring the mocking patterns in client_utils_test.py/common_params_test.py.

🤖 Prompt for AI agents

Add unit test coverage for the new `burnToken` handler and params model,
following existing TCK test conventions (flat file under `tests/tck/`,
`MagicMock`-based stubbing, `pytest.mark.unit`).

1. Create `tests/tck/burn_token_test.py` (flat, matching the existing
`<module>_test.py` convention) with `pytestmark = pytest.mark.unit`.
2. Cover `BurnTokenParams.parse_json_params`: test valid FT params, valid NFT
params, and the `serialNumbers` shape-validation error cases.
3. Cover `_build_burn_token_transaction`: assert token id and amount are set for
the FT case, and serials are set for the NFT case, confirming both are not set
simultaneously.
4. Cover the `burn_token` handler: mock the client (via
`get_client`/`MagicMock`) and the transaction's `execute`/`get_receipt` to
return a stubbed receipt, then assert the resulting `BurnTokenResponse` fields
(`newTotalSupply`, `status`) — mirroring the mocking patterns in
`client_utils_test.py`/`common_params_test.py`.

Research

The TCK layer exposes SDK functionality over JSON-RPC. Request params are parsed by *Params dataclasses (each implementing a parse_json_params classmethod) under tck/param/, handlers live in tck/handlers/ and self-register via the @rpc_method("methodName") decorator (tck/handlers/registry.py), and responses are @dataclass types under tck/response/ that are serialized (None-stripped) back to the client. The dispatch mechanism resolves the params type from the handler's first-parameter type hint and applies shared common-transaction-params logic (memo, transaction id, fees, signers/freeze/sign) via CommonTransactionParams.apply_common_params. The underlying TokenBurnTransaction SDK class already exists at src/hiero_sdk_python/tokens/token_burn_transaction.py and enforces mutual exclusivity between amount (FT) and serials (NFT). The TCK burnToken handler, its params, and its response do not yet exist.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the `burnToken` JSON-RPC method for the TCK server, mirroring the
existing `mintToken` implementation, and supporting both fungible-token (amount)
and NFT (serial numbers) burns.

1. Add `BurnTokenParams(BaseTransactionParams)` to `tck/param/token.py`, modeled
on `MintTokenParams`/`ClaimTokenParams`:
- Fields: `tokenId: str | None`, `amount: str | None`, `serialNumbers: list[str]
| None`, plus inherited `sessionId` and `commonTransactionParams`.
- Implement `parse_json_params` following the standard idiom: pull optional
fields via `params.get(...)`, validate that `serialNumbers` (when present) is a
list of strings (raise `ValueError` otherwise), and resolve
`sessionId`/`commonTransactionParams` via the shared `param_utils` helpers.
- Keep `tokenId`/`amount` as raw optional strings (no required-field enforcement
at parse time, matching mint), deferring coercion/validation to the handler and
SDK layers.

2. Add `BurnTokenResponse` to `tck/response/token.py`, mirroring
`MintTokenResponse` but without serial numbers:
   - Fields: `newTotalSupply: str | None` and `status: str | None`.

3. In `tck/handlers/token.py`:
- Add a private `_build_burn_token_transaction(params: BurnTokenParams) ->
TokenBurnTransaction` helper modeled on `_build_mint_token_transaction`. Set the
gRPC deadline, set the token id via `TokenId.from_string` when provided, and
branch cleanly between the FT path (`set_amount(to_int(params.amount))`) and the
NFT path (`set_serials([...])` from `serialNumbers` converted to ints) — avoid
setting both to respect the SDK's mutual-exclusivity constraint.
- Add a `@rpc_method("burnToken")`-decorated `burn_token(params:
BurnTokenParams) -> BurnTokenResponse` handler mirroring `mint_token`: resolve
the client via `get_client(params.sessionId)`, build the transaction, apply
`commonTransactionParams`, execute with `wait_for_receipt=False`, fetch the
receipt with `validate_status=True`, and return
`BurnTokenResponse(newTotalSupply=str(receipt.new_total_supply),
status=ResponseCode(receipt.status).name)`.
- Import `TokenBurnTransaction`, `BurnTokenParams`, and `BurnTokenResponse` as
needed.
- No registry edits are required since `tck/handlers/__init__.py` already
imports the `token` module, so the decorator self-registers.
===============================================================================

Task: 2

Add unit test coverage for the new `burnToken` handler and params model,
following existing TCK test conventions (flat file under `tests/tck/`,
`MagicMock`-based stubbing, `pytest.mark.unit`).

1. Create `tests/tck/burn_token_test.py` (flat, matching the existing
`<module>_test.py` convention) with `pytestmark = pytest.mark.unit`.
2. Cover `BurnTokenParams.parse_json_params`: test valid FT params, valid NFT
params, and the `serialNumbers` shape-validation error cases.
3. Cover `_build_burn_token_transaction`: assert token id and amount are set for
the FT case, and serials are set for the NFT case, confirming both are not set
simultaneously.
4. Cover the `burn_token` handler: mock the client (via
`get_client`/`MagicMock`) and the transaction's `execute`/`get_receipt` to
return a stubbed receipt, then assert the resulting `BurnTokenResponse` fields
(`newTotalSupply`, `status`) — mirroring the mocking patterns in
`client_utils_test.py`/`common_params_test.py`.

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