feat(tck): add token grant/revoke KYC handlers

[iron-prog]

Description:

Add TCK JSON-RPC support for grantTokenKyc and revokeTokenKyc.

• Add grantTokenKyc TCK handler
• Add revokeTokenKyc TCK handler
• Add request parameter models
• Add response models
• Follow the existing token handler implementation pattern

Related issue(s):

Fixes #2422

Notes for reviewer:

Both TokenGrantKycTransaction and TokenRevokeKycTransaction are already implemented in the Python SDK. This PR wires them into the TCK by adding the corresponding JSON-RPC handlers, request parameter models, and response models, following the existing implementation used by other token operations.

Checklist

• Documented (Code comments, README, etc.)
• Tested (unit, integration, etc.)

[iron-prog]

While working on this issue, I noticed both handlers were missing from the TCK. Since the implementations are analogous and the SDK support already exists, I included both to keep the TCK handlers consistent.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 648d5723-4858-4d3c-9e43-138e1dfd7477

📥 Commits

Reviewing files that changed from the base of the PR and between 5d01e66 and 205a8e8.

📒 Files selected for processing (7)

• src/hiero_sdk_python/tokens/token_grant_kyc_transaction.py
• src/hiero_sdk_python/tokens/token_revoke_kyc_transaction.py
• tck/handlers/token.py
• tck/param/token.py
• tck/response/token.py
• tests/unit/token_grant_kyc_transaction_test.py
• tests/unit/token_revoke_kyc_transaction_test.py

---

Walkthrough

Adds grantTokenKyc and revokeTokenKyc TCK RPC operations, request and response models, optional identifier handling in SDK transaction bodies, token handler execution, and unit tests for missing identifiers.

Changes

Token KYC Operations

Layer / File(s)	Summary
KYC request and response contracts tck/param/token.py, tck/response/token.py	Adds parameter dataclasses for token and account identifiers and status-only response models for both operations.
Optional KYC transaction identifiers src/hiero_sdk_python/tokens/token_*_kyc_transaction.py, tests/unit/token_*_kyc_transaction_test.py	Builds grant and revoke KYC protobuf bodies with only present identifiers, with tests covering omitted fields.
KYC transaction handlers tck/handlers/token.py	Adds transaction builders and RPC handlers, applies common transaction parameters, executes transactions, validates receipt statuses, and returns responses.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant JSONRPC
  participant TokenHandlers
  participant HederaSDK
  participant Receipt
  JSONRPC->>TokenHandlers: grantTokenKyc or revokeTokenKyc parameters
  TokenHandlers->>HederaSDK: build transaction with optional tokenId and accountId
  TokenHandlers->>HederaSDK: execute transaction
  HederaSDK->>Receipt: obtain receipt
  Receipt-->>TokenHandlers: transaction status
  TokenHandlers-->>JSONRPC: status-only response

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding token KYC grant/revoke handlers.
Description check	✅ Passed	The description matches the changeset by describing the new TCK grant/revoke KYC handlers, params, and responses.
Linked Issues check	✅ Passed	The PR implements revokeTokenKyc via a new JSON-RPC handler and supporting models, satisfying issue #2422.
Out of Scope Changes check	✅ Passed	The SDK and test changes support the new KYC handlers and do not appear unrelated to the issue scope.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

📋 Issue Planner

Built with CodeRabbit's Coding Plans for faster development and fewer bugs.

View plan used: #2422

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: f211aad9-41fc-47b3-9c96-27e75b43d186

📥 Commits

Reviewing files that changed from the base of the PR and between aa45186 and a436cb8.

📒 Files selected for processing (1)

• tests/tck/token_kyc_handlers_test.py

[iron-prog]

While testing, I noticed two pre-existing issues unrelated to this PR: (1) get_client() silently returns None for an unknown sessionId, leading to a misleading downstream error, and (2) the clear_handlers test fixture can affect other tests depending on collection order. I kept this PR focused on the KYC handlers, but I'm happy to open follow-up issues for these if that would be helpful

[Mounil2005]

Thanks for wiring these up, the param/response models and builder pattern look correct and match the existing freezeToken/pauseToken handlers.

Before moving ahead, could you confirm whether you ran the hiero-sdk-tck conformance suite locally against this server for grantTokenKyc/revokeTokenKyc? Per the test spec, each method has 17 test cases....13 covering tokenId (invalid, empty, missing, deleted token, unsigned/wrong-key signatures, no KYC key, not associated, paused token, frozen account) and 4 covering accountId (nonexistent, empty, missing, deleted account). Matching the existing pattern and passing type checks doesn't guarantee those pass.

[iron-prog]

thanks for the thorough review and for pointing out the distinction. I only ran the repository's local pytest suite , which covers parameter parsing, transaction building, mocked end-to-end dispatch, and error handling. I haven't yet run the full hiero-sdk-tck conformance suite against a local node or testnet, so I can't yet confirm all 17 TCK scenarios pass. I'll set up hiero-local-node, run the TCK client for grantTokenKyc and revokeTokenKyc, and update this thread with the results. If any scenarios fail, I'll address them in this PR. One possible issue is that the JSON-RPC layer currently wraps some exceptions into a generic internal error, which could affect TCK expectations even if the underlying transaction is correct. I'll note whether that's the cause in my follow-up.

[Mounil2005]

thanks for the thorough review and for pointing out the distinction. I only ran the repository's local pytest suite , which covers parameter parsing, transaction building, mocked end-to-end dispatch, and error handling. I haven't yet run the full hiero-sdk-tck conformance suite against a local node or testnet, so I can't yet confirm all 17 TCK scenarios pass. I'll set up hiero-local-node, run the TCK client for grantTokenKyc and revokeTokenKyc, and update this thread with the results. If any scenarios fail, I'll address them in this PR. One possible issue is that the JSON-RPC layer currently wraps some exceptions into a generic internal error, which could affect TCK expectations even if the underlying transaction is correct. I'll note whether that's the cause in my follow-up.

Thanks for contributing this, @iron-prog

And appreciate the honest update on testing that's exactly the right way to handle it. Thanks for being upfront about where things stand instead of just checking the box, and for taking the extra step to spin up hiero-local-node and run the actual TCK client rather than stopping at the unit tests.

Your hunch about the generic internal-error wrapping is worth chasing, if the TCK driver expects a specific response code back and the JSON-RPC layer is flattening it to a generic internal error, that would explain a failure even when the underlying transaction logic is correct. Good instinct to check that first.

No rush take the time you need to run it properly, and just ping the thread when you've got results.

[iron-prog]

Quick update: I managed to get the TCK running locally against testnet (I tried with Docker but due limited hardware it's becomes problem to me /local-node setup since I was running into unrelated environment issues).
While testing, I found two things that seem unrelated to this PR:

1. setup/setOperator in tck/handlers/sdk.py currently uses PrivateKey.from_string(). With an ECDSA testnet account, that resulted in INVALID_SIGNATURE on every transaction until I switched to PrivateKey.from_string_ecdsa() locally. I'll open a separate issue with a minimal repro.

2. Network-level errors (ReceiptStatusError/PrecheckError) correctly propagate the Hedera status via error.data.status, but locally raised validation errors (for example, a empty tokenId) are still wrapped as a generic Internal error. That also looks like a separate issue rather than something introduced by this PR.

With the ECDSA workaround applied locally, I was able to verify that grantTokenKyc behaves as expected against testnet (for example, returning INVALID_TOKEN_ID for an invalid token).
I'm still working through the full 13+4 TCK scenario run. Right now I'm hitting what looks like an unrelated stability issue in my local setup, so I didn't want to wait before posting an update. I'll keep digging and update this thread once I have a clean run or identify the root cause.

[aceppaluni]

@iron-prog Thank you for the update!

Going to convert this to draft while the work is still going.

[manishdait]

@iron-prog, Thanks for the PR. added some requested changes :)

[iron-prog]

@manishdait I managed to run the full TokenGrantKycTransaction/TokenRevokeKycTransaction TCK suite against testnet.
28/32 scenarios are passing, including all of the cases this change is meant to address. In particular, missing tokenId/accountId now return INVALID_TOKEN_ID/INVALID_ACCOUNT_ID from the network instead of a generic internal error. The deleted token, wrong signature, paused, and frozen scenarios are all passing as well.
The remaining 4 failures are all in verifyTokenKyc. They appear to be timing out while waiting for mirror-node confirmation (30s Mocha timeout vs. ~20s retry budget). I saw the same behavior with two different testnet accounts, including a brand-new one, which makes me think this is related to testnet mirror-node propagation rather than this change itself. I also queried the mirror node directly and confirmed the KYC status is updated correctly (kyc_status:GRANTED).
I'll keep looking into it if it's useful, but It did looks like an external timing issue.

[manishdait]

@iron-prog, that happen when we use the testnet for the tck test. I can verify the changes against solo. once you address the changes.

[github-actions]

Hello, this is the OfficeHourBot.

This is a reminder that the Hiero Python SDK Office Hours will begin in approximately 3 hours and 28 minutes (14:00 UTC).

This session provides an opportunity to ask questions regarding this Pull Request.

Details:

• Time: 14:00 UTC
• Join Link: Zoom Meeting

Disclaimer: This is an automated reminder. Please verify the schedule here for any changes.

From,
The Python SDK Team

[danielmarv]

LGTM!

[manishdait]

lgtm

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@           Coverage Diff           @@
##             main    #2433   +/-   ##
=======================================
  Coverage   94.99%   94.99%           
=======================================
  Files         164      164           
  Lines       10447    10449    +2     
=======================================
+ Hits         9924     9926    +2     
  Misses        523      523           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

👋 Hi @iron-prog! Great work completing a Good First Issue issue! 🎉

Thanks for your contribution! 🚀

Here are some issues you might want to explore next:

• Explore read-only review status evaluator for PRs
• feat(tck): implement burnToken JSON-RPC method
• feat(tck): implement dissociateToken JSON-RPC method
• feat(tck): implement unfreezeToken JSON-RPC method
• feat(tck): implement unpauseToken JSON-RPC method

🌟 Stay connected:

• ⭐ Star this repository
• 👀 Watch for new issues
• 💬 Join us on Discord

Happy coding! 🚀
— Hiero Python SDK Team