feat(tck): implement cancelAirdrop JSON-RPC method

[exploreriii]

Problem cancelAirdrop is missing; the driver's TokenAirdropCancelTransaction suites cannot run.

Solution Mirror the existing claimToken handler (PendingAirdropId construction from sender/receiver/token/serials).

Spec: https://github.com/hiero-ledger/hiero-sdk-tck/blob/main/docs/test-specifications/token-service/TokenAirdropCancelTransaction.md (note the filename)
JS reference: https://github.com/hiero-ledger/hiero-sdk-js/blob/main/tck/methods/token.ts (cancelAirdrop)
SDK class: TokenCancelAirdropTransaction

[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

• Mirror the existing claimToken implementation to add a new cancelAirdrop JSON-RPC method, reusing the sender/receiver/token/serials → PendingAirdropId construction pattern.
• Add CancelAirdropParams, CancelAirdropResponse, and a cancel_airdrop handler with a _build_cancel_airdrop_transaction helper, wrapping the already-existing SDK TokenCancelAirdropTransaction (using its cancel-specific add_pending_airdrop method).
• Rely on the generic registry/dispatch/error-handling machinery so no server, protocol, or registration changes are needed.

Design Choices

Design Choice 1: What parameter shape should `cancelAirdrop` accept?

Options Considered:

1. Flat fields — senderAccountId, receiverAccountId, tokenId, serialNumbers — identical to ClaimTokenParams, building one or more PendingAirdropId from a single sender/receiver/token plus optional serials.
2. Array form — a pendingAirdrops list where each entry carries its own sender/receiver/token/serial.

Chosen Option: 1

Rationale: The ticket explicitly says "Mirror the existing claimToken handler (PendingAirdropId construction from sender/receiver/token/serials)," keeping the TCK surface consistent with the sibling claimToken method already in the repo. The ticket instructs mirroring claimToken (flat sender/receiver/token/serials), while some external Go SDK docs describe a pendingAirdrops array of PendingAirdropParams.

💡 User Tips

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

Implementation Steps

Expose cancelAirdrop as a TCK JSON-RPC method

This phase adds the parameter model, response model, and request handler that together register and serve a new cancelAirdrop method, reusing the established airdrop patterns end-to-end. All work stays within the token TCK modules; no changes are required to dispatch, registration plumbing, protocol, or server code because those are generic.

Task 1: Add the `CancelAirdropParams` parameter model

Introduce a params dataclass that captures the sender, receiver, token, and optional NFT serials for a cancel operation.

• Add CancelAirdropParams to tck/param/token.py, structurally identical to ClaimTokenParams (senderAccountId, receiverAccountId, tokenId, serialNumbers: list[str] | None, all optional), extending BaseTransactionParams.
• Implement its parse_json_params classmethod mirroring ClaimTokenParams: read fields via params.get(...), validate that serialNumbers is a list of strings (raising ValueError on bad types so dispatch surfaces INVALID_PARAMS), and populate sessionId/commonTransactionParams via the shared parse_session_id/parse_common_transaction_params helpers.

Task 2: Add the `CancelAirdropResponse` response model

Provide a status-only response payload consistent with sibling airdrop responses.

• Add CancelAirdropResponse(StatusOnlyResponse) to tck/response/token.py as a trivial subclass with only a docstring, matching ClaimTokenResponse.

Task 3: Add the `cancelAirdrop` handler and transaction builder

Wire the new method to the existing SDK TokenCancelAirdropTransaction, following the exact claimToken execution flow.

• In tck/handlers/token.py, import TokenCancelAirdropTransaction (from hiero_sdk_python.tokens.token_airdrop_transaction_cancel) plus the new CancelAirdropParams/CancelAirdropResponse.
• Add a _build_cancel_airdrop_transaction(params) -> TokenCancelAirdropTransaction helper mirroring _build_claim_token_transaction: construct AccountId/TokenId from params, build one PendingAirdropId per serial (via NftId) when serialNumbers is present, otherwise a single fungible PendingAirdropId. Note the key API difference — use transaction.add_pending_airdrop(...) (singular, cancel-specific) rather than claim's add_pending_airdrop_id(...). Set the gRPC deadline as claimToken does.
• Add @rpc_method("cancelAirdrop") def cancel_airdrop(params: CancelAirdropParams) -> CancelAirdropResponse, following claim_token exactly: get client, build transaction, apply commonTransactionParams when present, execute with wait_for_receipt=False, fetch receipt with validate_status=True, and return CancelAirdropResponse(status=ResponseCode(receipt.status).name).
• No edits to tck/handlers/__init__.py, tck/handlers/registry.py, tck/protocol.py, or tck/server.py — the token module is already auto-imported and registration/dispatch/error mapping is generic.

Task 4: Add a focused unit test for the builder (optional but recommended)

Guard the new builder's PendingAirdropId construction logic without requiring network access.

• Add a test (e.g. tests/tck/token_handlers_test.py, referencing dispatch/error-assertion patterns in tests/tck/handlers_test.py) that calls _build_cancel_airdrop_transaction with fungible-only and NFT-serial params, asserting the resulting pending_airdrops list contents (correct sender/receiver, token_id vs nft_id/serial) and that the method is registered under cancelAirdrop.

🤖 Prompt for AI agents

Implement a new `cancelAirdrop` JSON-RPC TCK method by mirroring the existing
`claimToken` handler pattern. All changes stay within the token TCK modules; no
dispatch, registration, protocol, or server changes are needed since that
machinery is generic.

1. Params model: In `tck/param/token.py`, add `CancelAirdropParams` extending
`BaseTransactionParams`, structurally identical to `ClaimTokenParams` with
fields `senderAccountId`, `receiverAccountId`, `tokenId`, and `serialNumbers:
list[str] | None` (all optional). Implement `parse_json_params` classmethod
mirroring `ClaimTokenParams`: read fields via `params.get(...)`, validate
`serialNumbers` is a list of strings (raise `ValueError` on bad types so
dispatch surfaces `INVALID_PARAMS`), and populate
`sessionId`/`commonTransactionParams` using the shared
`parse_session_id`/`parse_common_transaction_params` helpers.

2. Response model: In `tck/response/token.py`, add
`CancelAirdropResponse(StatusOnlyResponse)` as a trivial subclass with only a
docstring, matching `ClaimTokenResponse`.

3. Handler and builder: In `tck/handlers/token.py`:
- Import `TokenCancelAirdropTransaction` from
`hiero_sdk_python.tokens.token_airdrop_transaction_cancel`, plus the new
`CancelAirdropParams`/`CancelAirdropResponse`.
- Add `_build_cancel_airdrop_transaction(params) ->
TokenCancelAirdropTransaction` mirroring `_build_claim_token_transaction`:
construct `AccountId`/`TokenId` from params; build one `PendingAirdropId` per
serial (via `NftId`) when `serialNumbers` is present, otherwise a single
fungible `PendingAirdropId`. Use `transaction.add_pending_airdrop(...)`
(singular, cancel-specific) rather than the claim flow's
`add_pending_airdrop_id(...)`. Set the gRPC deadline the same way `claimToken`
does.
- Add `@rpc_method("cancelAirdrop") def cancel_airdrop(params:
CancelAirdropParams) -> CancelAirdropResponse`, following `claim_token` exactly:
get client, build the transaction, apply `commonTransactionParams` when present,
execute with `wait_for_receipt=False`, fetch the receipt with
`validate_status=True`, and return
`CancelAirdropResponse(status=ResponseCode(receipt.status).name)`.
- Do not modify `tck/handlers/__init__.py`, `tck/handlers/registry.py`,
`tck/protocol.py`, or `tck/server.py`.

4. Optional unit test: Add a test (e.g. `tests/tck/token_handlers_test.py`,
referencing patterns from `tests/tck/handlers_test.py`) that calls
`_build_cancel_airdrop_transaction` with fungible-only and NFT-serial params,
asserting the resulting `pending_airdrops` list contents (correct
sender/receiver, `token_id` vs `nft_id`/serial) and confirming the method is
registered under `cancelAirdrop`.

Research

The TCK layer (tck/) exposes SDK operations as JSON-RPC 2.0 methods. Handlers live in tck/handlers/<domain>.py, are registered via a @rpc_method("methodName") decorator into a global registry (tck/handlers/registry.py), and are auto-imported through tck/handlers/__init__.py. Each handler pairs a param dataclass (tck/param/<domain>.py, extending BaseTransactionParams) with a response dataclass (tck/response/<domain>.py, typically a trivial StatusOnlyResponse subclass). Dispatch, param parsing, error mapping, and response formatting are all generic — new methods require no server/protocol/registry changes. The SDK already provides TokenCancelAirdropTransaction and PendingAirdropId; only the TCK wrapper is missing. The claimToken handler (tck/handlers/token.py) is the direct structural template.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Implement a new `cancelAirdrop` JSON-RPC TCK method by mirroring the existing
`claimToken` handler pattern. All changes stay within the token TCK modules; no
dispatch, registration, protocol, or server changes are needed since that
machinery is generic.

1. Params model: In `tck/param/token.py`, add `CancelAirdropParams` extending
`BaseTransactionParams`, structurally identical to `ClaimTokenParams` with
fields `senderAccountId`, `receiverAccountId`, `tokenId`, and `serialNumbers:
list[str] | None` (all optional). Implement `parse_json_params` classmethod
mirroring `ClaimTokenParams`: read fields via `params.get(...)`, validate
`serialNumbers` is a list of strings (raise `ValueError` on bad types so
dispatch surfaces `INVALID_PARAMS`), and populate
`sessionId`/`commonTransactionParams` using the shared
`parse_session_id`/`parse_common_transaction_params` helpers.

2. Response model: In `tck/response/token.py`, add
`CancelAirdropResponse(StatusOnlyResponse)` as a trivial subclass with only a
docstring, matching `ClaimTokenResponse`.

3. Handler and builder: In `tck/handlers/token.py`:
- Import `TokenCancelAirdropTransaction` from
`hiero_sdk_python.tokens.token_airdrop_transaction_cancel`, plus the new
`CancelAirdropParams`/`CancelAirdropResponse`.
- Add `_build_cancel_airdrop_transaction(params) ->
TokenCancelAirdropTransaction` mirroring `_build_claim_token_transaction`:
construct `AccountId`/`TokenId` from params; build one `PendingAirdropId` per
serial (via `NftId`) when `serialNumbers` is present, otherwise a single
fungible `PendingAirdropId`. Use `transaction.add_pending_airdrop(...)`
(singular, cancel-specific) rather than the claim flow's
`add_pending_airdrop_id(...)`. Set the gRPC deadline the same way `claimToken`
does.
- Add `@rpc_method("cancelAirdrop") def cancel_airdrop(params:
CancelAirdropParams) -> CancelAirdropResponse`, following `claim_token` exactly:
get client, build the transaction, apply `commonTransactionParams` when present,
execute with `wait_for_receipt=False`, fetch the receipt with
`validate_status=True`, and return
`CancelAirdropResponse(status=ResponseCode(receipt.status).name)`.
- Do not modify `tck/handlers/__init__.py`, `tck/handlers/registry.py`,
`tck/protocol.py`, or `tck/server.py`.

4. Optional unit test: Add a test (e.g. `tests/tck/token_handlers_test.py`,
referencing patterns from `tests/tck/handlers_test.py`) that calls
`_build_cancel_airdrop_transaction` with fungible-only and NFT-serial params,
asserting the resulting `pending_airdrops` list contents (correct
sender/receiver, `token_id` vs `nft_id`/serial) and confirming the method is
registered under `cancelAirdrop`.

💡 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 @aceppaluni 👋

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