feat(token): Add getTokenInfo request and response models, including custom fee serialization

[danielmarv]

Description:
This pull request adds support for querying detailed token information through a new getTokenInfo endpoint in the TCK (Test Client Kit). It introduces new parameter and response classes, serialization helpers for token-related data, and updates the handler logic to process and return comprehensive token details, including custom fees and key metadata.

New endpoint and data structures:

• Added GetTokenInfoParams and GetTokenInfoResponse dataclasses to define the request and response payloads for the new getTokenInfo RPC method, including nested CustomFeeResponse for detailed custom fee information. [1] [2]

Handler logic and serialization:

• Implemented the get_token_info handler in tck/handlers/token.py, which uses TokenInfoQuery to fetch token details and serializes the result into the new response format, including comprehensive mapping and serialization of enums, keys, custom fees, and metadata.
• Added helper functions for serializing keys, mapping token types and statuses, and converting custom fees into response objects to ensure accurate and consistent output.

Dependency and import updates:

• Updated imports in tck/handlers/token.py to include all necessary classes and enums for token info querying and serialization, such as TokenInfo, TokenPauseStatus, TokenKycStatus, and TokenFreezeStatus. [1] [2] [3] [4]

These changes collectively enable the TCK to support rich token info queries, facilitating more thorough testing and validation of token-related features.

Related issue(s):

Fixes #2399

Notes for reviewer:

Checklist

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

[Copilot]

Pull request overview

Adds a new TCK JSON-RPC endpoint (getTokenInfo) to query token details via TokenInfoQuery, along with new request/response dataclasses and serialization helpers to return rich token metadata (keys, statuses, custom fees, etc.) in the TCK response shape.

Changes:

• Add GetTokenInfoParams request model for getTokenInfo query inputs.
• Add GetTokenInfoResponse (and nested CustomFeeResponse) response models for rich token info output.
• Implement get_token_info handler + serialization/mapping helpers for keys, enums, timestamps, and custom fees.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
tck/response/token.py	Adds response dataclasses for getTokenInfo, including nested custom fee representation.
tck/param/token.py	Adds GetTokenInfoParams for the new query endpoint.
tck/handlers/token.py	Implements the getTokenInfo RPC handler and serialization helpers to map SDK TokenInfo into TCK response fields.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Adds a getTokenInfo RPC endpoint to the TCK module, with request/response models, token-info query handling, nullable-result preservation, and serialization of Hedera token metadata into the TCK response shape.

Changes

getTokenInfo endpoint

Layer / File(s)	Summary
Request/response data shapes tck/param/token.py, tck/response/token.py	Adds GetTokenInfoParams parsing and the GetTokenInfoResponse/CustomFeeResponse dataclasses used by getTokenInfo.
TokenInfoQuery request building src/hiero_sdk_python/query/token_info_query.py, tests/unit/token_info_query_test.py	Allows TokenInfoQuery request construction without a token id and updates the unit test to assert the request proto is built with an unset token field.
RPC handler, response mapping, and nullable serialization tck/handlers/registry.py, tck/handlers/token.py, tests/tck/handlers_test.py	Preserves nullable dataclass fields during recursive result parsing, adds the get_token_info handler, wires query payments, serializes token metadata and fees, maps enums, and validates nested result handling.

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

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant get_token_info
  participant Hbar
  participant TokenInfoQuery
  participant HederaNetwork
  participant GetTokenInfoResponse

  Client->>get_token_info: GetTokenInfoParams(tokenId, queryPayment, maxQueryPayment)
  get_token_info->>Hbar: Convert tinybars to Hbar
  get_token_info->>TokenInfoQuery: Set token id and query-payment limits
  get_token_info->>TokenInfoQuery: Execute query
  TokenInfoQuery->>HederaNetwork: Request token information
  HederaNetwork-->>TokenInfoQuery: Return TokenInfo
  TokenInfoQuery-->>get_token_info: Return TokenInfo
  get_token_info->>GetTokenInfoResponse: Map metadata and custom fees
  get_token_info-->>Client: Return serialized response

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the new getTokenInfo endpoint and its token-info serialization work.
Description check	✅ Passed	The description matches the PR and describes the new endpoint, models, serializers, and handler updates.
Linked Issues check	✅ Passed	The PR adds get_token_info, the new request/response dataclasses, and tests covering the endpoint-related behavior.
Out of Scope Changes check	✅ Passed	The query and parsing changes support the new endpoint's optional tokenId and nullable nested response handling.
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: #2399

✨ 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: 8aea9b34-ce52-42c0-8f41-03962353ab03

📥 Commits

Reviewing files that changed from the base of the PR and between 07be7f6 and ed76db3.

📒 Files selected for processing (3)

• tck/handlers/token.py
• tck/param/token.py
• tck/response/token.py

[github-actions]

Hi, this is WorkflowBot.
Your pull request cannot be merged as it is not passing all our workflow checks.
Please click on each check to review the logs and resolve issues so all checks pass.
To help you:

• DCO signing guide
• Merge conflicts guide
• Rebase guide
• Testing guide
• Discord
• Community Calls
  Thank you for contributing!
  From the Hiero Python SDK Team

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/hiero_sdk_python/query/token_info_query.py (1)

55-65: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Stale docstring: _make_request no longer raises ValueError for missing token_id.

The docstring still states Raises: ValueError: If the token ID is not set. (Line 56), but the implementation now silently skips setting token when self.token_id is None (Line 64-65). Per the TokenGetInfoQuery proto contract, an unset/invalid token results in a server-side INVALID_TOKEN_ID response, so allowing the request through is protocol-aligned — just update the docstring to match.

📝 Suggested docstring fix

         Returns:
             query_pb2.Query: The protobuf query message.

         Raises:
-            ValueError: If the token ID is not set.
             Exception: If any other error occurs during request construction.

As per path instructions for src/hiero_sdk_python/query/**/*.py, "_make_request() MUST: Validate all required identifiers"; here validation is intentionally deferred to the network per hedera-protobufs/services/token_get_info.proto, but the docstring should reflect the actual behavior.

Source: Path instructions

♻️ Duplicate comments (1)

tck/handlers/token.py (1)

622-639: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Missing session-not-found guard persists.

get_client(params.sessionId) at Line 625 can return None; there's still no check before it's used to execute the query at Line 638. This was already flagged in a prior review round for this same handler.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 97949b8c-d09d-4d6c-a98f-96a4ac67a2c7

📥 Commits

Reviewing files that changed from the base of the PR and between ed76db3 and c9b8013.

📒 Files selected for processing (3)

• src/hiero_sdk_python/query/token_info_query.py
• tck/handlers/token.py
• tck/response/token.py

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@            Coverage Diff             @@
##             main    #2400      +/-   ##
==========================================
- Coverage   95.01%   94.98%   -0.03%     
==========================================
  Files         163      163              
  Lines       10465    10464       -1     
==========================================
- Hits         9943     9939       -4     
- Misses        522      525       +3     

🚀 New features to boost your workflow:

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

[aceppaluni]

GIven the amount of mapping helpers _map_pause_status(), _map_token_type()
and _map_supply_type(), and having default_freeze = ... and default_kyc = ... handled inline,

Should we move freeze/KYC into _map_freeze_status() and _map_kyc_status()

[manishdait]

lgtm

[exploreriii]

Might be a couple inconsistencies in the spec still
https://hiero-ledger.github.io/hiero-sdk-tck/test-specifications/token-service

[coderabbitai]

♻️ Duplicate comments (1)

tck/handlers/token.py (1)

626-643: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Guard against None client before executing the query.

get_client(params.sessionId) can return None, and query.execute(None) will raise an AttributeError that dispatch turns into a generic internal_error instead of a clear "session not found" response. This was flagged in a previous review and remains unaddressed.

🛡️ Proposed fix

 `@rpc_method`("getTokenInfo")
 def get_token_info(params: GetTokenInfoParams) -> GetTokenInfoResponse:
     """Query token info using TCK getTokenInfo parameters."""
     client = get_client(params.sessionId)
+    if client is None:
+        raise JsonRpcError.invalid_params_error(data=f"Session not found: {params.sessionId}")

     query = TokenInfoQuery().set_grpc_deadline(DEFAULT_GRPC_TIMEOUT)

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: fb819046-b3ba-433e-af7b-feebc671724b

📥 Commits

Reviewing files that changed from the base of the PR and between d600576 and 8d4680c.

📒 Files selected for processing (3)

• tck/handlers/registry.py
• tck/handlers/token.py
• tests/tck/handlers_test.py

[exploreriii]

is this ready to review @danielmarv ?

[danielmarv]

Yeah

outdated

[github-actions]

👋 Hi @danielmarv! Great work completing a Advanced issue! 🎉

Thanks for your contribution! 🚀

Here are some issues you might want to explore next:

• [Advanced]: Add CI Pipeline for Example Validation
• [Advanced]: Integrate Code Coverage for C++ SDK
• [Advanced]: Upgrade gRPC and protobuf dependencies

🌟 Stay connected:

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

Happy coding! 🚀
— Hiero Python SDK Team