Add a `getTokenInfo` endpoint to tck module

[manishdait]

Add the getTokenInfo endpoint to the tck module, Following the GetTokenInfo Specification

Chnages To Made

• Add the get_token_info method to the handler/token.py
• Create the dataclass representing params/response for token info transaction
• Test the endpoint against hiero-sdk-tck

[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

Treat getTokenInfo as a read-only query and implement it by directly cloning the proven getAccountInfo structure across param, response, and handler layers.

Add a GetTokenInfoParams (tokenId only) and a comprehensive GetTokenInfoResponse with nested custom-fee dataclasses whose camelCase naming mirrors the existing createToken custom-fee input contract.

Build/execute TokenInfoQuery and map TokenInfo field-by-field, reusing shared serialize_key/enum_name helpers (extracted from account.py) and a new _serialize_custom_fee inverting existing _build_custom_fee logic.

Validate functionally by running the standalone TCK server against the external hiero-sdk-tck TokenInfoQuery spec, adjusting formatting only as conformance requires.

Design Choices

Design Choice 1: Serialization format for enum-valued TokenInfo fields

Options Considered:

1. Serialize using the SDK enum member name (e.g. "FUNGIBLE_COMMON", "FROZEN", "FINITE") via the existing _enum_name helper.
2. Serialize using lower-case tokens matching the createToken input side (e.g. "ft", "infinite", "inclusive").

Chosen Option: 1

Rationale: It matches the established getAccountInfo output convention (_enum_name → .name) already used for kycStatus/freezeStatus, keeping query-response serialization consistent across the module. (Adjust only if the external TCK conformance run reports a mismatch.)

Design Choice 2: Whether key/enum serialization helpers should be shared or duplicated

Options Considered:

1. Extract both helpers into a shared tck/util/ module and reuse from account.py and token.py.
2. Duplicate the two small helpers locally in token.py.

Chosen Option: 1

Rationale: Given getTokenInfo serializes ~8 key fields and ~5 enum fields, a single shared util avoids drift and is a low-risk, contained change; account.py is updated to import from it without behavior change.

💡 User Tips

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

Implementation Steps

Phase 1: Define the getTokenInfo Data Contract

Establish the request and response shapes for the endpoint before wiring behavior, so the mapping target is explicit. This phase adds the param dataclass and the response dataclass hierarchy (including custom-fee representations) that mirror both the existing getAccountInfo query contract and the camelCase field naming already used on the createToken input side.

Task 1: Add `GetTokenInfoParams`

Define the request parameters for the query endpoint.

• Add GetTokenInfoParams to tck/param/token.py, extending BaseParams (not BaseTransactionParams, since a query has no commonTransactionParams).
• Include a single optional tokenId: str | None = None field.
• Implement parse_json_params to read tokenId and sessionId (via parse_session_id), mirroring GetAccountInfoParams in tck/param/account.py.

Task 2: Add `GetTokenInfoResponse` and nested custom-fee response dataclasses

Define the response contract mapping every relevant TokenInfo field.

• Add GetTokenInfoResponse to tck/response/token.py as a plain @dataclass, all fields optional with sensible defaults (None, or field(default_factory=list) for customFees).
• Cover the full TokenInfo surface using camelCase keys: tokenId, name, symbol, decimals, totalSupply, treasury, adminKey, kycKey, freezeKey, wipeKey, supplyKey, feeScheduleKey, pauseKey, metadataKey, defaultFreezeStatus, defaultKycStatus, deleted, autoRenewAccount, autoRenewPeriod, expirationTime/expiry, memo, tokenType, supplyType, maxSupply, pauseStatus, metadata, ledgerId, and customFees.
• Add nested response dataclasses mirroring the reverse of tck/param/custom_fee.py: a CustomFeeResponse wrapper (feeCollectorAccountId, feeCollectorsExempt, fixedFee, fractionalFee, royaltyFee) with inner FixedFeeResponse, FractionalFeeResponse, RoyaltyFeeResponse (the latter carrying a nested fallbackFee).
• Follow the flat-string convention used by GetAccountInfoResponse (stringify numerics/timestamps/durations; use str(...) guards for optional SDK fields).

🤖 Prompt for AI agents

Implement the request and response data contract for the new `getTokenInfo`
endpoint, mirroring the existing `getAccountInfo` query pattern.

- In `tck/param/token.py`, add `GetTokenInfoParams` extending `BaseParams` (not
`BaseTransactionParams`, since this is a query with no
`commonTransactionParams`). Include a single optional `tokenId: str | None =
None` field. Implement `parse_json_params` to read `tokenId` and `sessionId`
(via `parse_session_id`), mirroring `GetAccountInfoParams` in
`tck/param/account.py`.

- In `tck/response/token.py`, add `GetTokenInfoResponse` as a plain `@dataclass`
with all fields optional (default `None`, or `field(default_factory=list)` for
`customFees`). Cover the full `TokenInfo` surface with camelCase keys:
`tokenId`, `name`, `symbol`, `decimals`, `totalSupply`, `treasury`, `adminKey`,
`kycKey`, `freezeKey`, `wipeKey`, `supplyKey`, `feeScheduleKey`, `pauseKey`,
`metadataKey`, `defaultFreezeStatus`, `defaultKycStatus`, `deleted`,
`autoRenewAccount`, `autoRenewPeriod`, `expirationTime`/`expiry`, `memo`,
`tokenType`, `supplyType`, `maxSupply`, `pauseStatus`, `metadata`, `ledgerId`,
and `customFees`.

- Add nested response dataclasses that mirror the reverse of
`tck/param/custom_fee.py`: a `CustomFeeResponse` wrapper
(`feeCollectorAccountId`, `feeCollectorsExempt`, `fixedFee`, `fractionalFee`,
`royaltyFee`) with inner `FixedFeeResponse`, `FractionalFeeResponse`, and
`RoyaltyFeeResponse` (the latter carrying a nested `fallbackFee`).

- Follow the flat-string convention used by `GetAccountInfoResponse`: stringify
numerics/timestamps/durations, and use `str(...)` guards for optional SDK
fields.

Phase 2: Implement the Query Handler and Serialization

Wire the endpoint end-to-end: build and execute the TokenInfoQuery, then map the SDK TokenInfo (including its heterogeneous custom-fee list) into the response contract. Registration is automatic once the @rpc_method-decorated handler is added to the already-imported token.py module.

Task 1: Extract shared serialization helpers into `tck/util/`

Provide reusable key/enum serializers for query responses.

• Create a shared helper module under tck/util/ (e.g. serialize_utils.py) exposing serialize_key(key) (DER string if available, else hex bytes) and enum_name(value) (.name or None), lifted from the local helpers in tck/handlers/account.py.
• Update tck/handlers/account.py to import and use these shared helpers in place of its local _serialize_key/_enum_name, preserving existing behavior.

Task 2: Add the `get_token_info` handler and `TokenInfo` mapper

Implement the query execution and field mapping.

• Add @rpc_method("getTokenInfo") def get_token_info(params: GetTokenInfoParams) -> GetTokenInfoResponse to tck/handlers/token.py, mirroring get_account_info: get the client, build TokenInfoQuery().set_grpc_deadline(DEFAULT_GRPC_TIMEOUT), conditionally set_token_id(TokenId.from_string(params.tokenId)), execute(client), then delegate to a _build_token_info_response mapper.
• Import TokenInfoQuery from hiero_sdk_python.query.token_info_query.
• Implement _build_token_info_response(info: TokenInfo) -> GetTokenInfoResponse doing field-by-field mapping: keys via serialize_key, enum fields (token_type, default_freeze_status, default_kyc_status, pause_status, supply_type) via enum_name, numerics/timestamps/durations stringified, IDs via str(...) guards.

Task 3: Implement custom-fee reverse serialization

Convert the SDK's heterogeneous custom_fees list into the response representation.

• Add a _serialize_custom_fee(fee) helper in tck/handlers/token.py that dispatches via isinstance on CustomFixedFee/CustomFractionalFee/CustomRoyaltyFee — inverting the existing _build_custom_fee logic.
• Reuse the base fields (fee_collector_account_id → feeCollectorAccountId, all_collectors_are_exempt → feeCollectorsExempt) and per-type fields with the same camelCase names as tck/param/custom_fee.py (fixed: amount/denominatingTokenId; fractional: numerator/denominator/minimumAmount/maximumAmount/assessmentMethod; royalty: numerator/denominator/fallbackFee).
• Populate customFees in _build_token_info_response via a list comprehension over info.custom_fees.

🤖 Prompt for AI agents

Wire the `getTokenInfo` endpoint end-to-end: build and execute a
`TokenInfoQuery`, then map the SDK `TokenInfo` (including its heterogeneous
custom-fee list) into the response contract defined in Phase 1. Registration is
automatic once the `@rpc_method`-decorated handler is added to the
already-imported `token.py` module.

- Create a shared helper module under `tck/util/` (e.g. `serialize_utils.py`)
exposing `serialize_key(key)` (DER string if available, else hex bytes) and
`enum_name(value)` (`.name` or `None`), lifted from the local helpers currently
in `tck/handlers/account.py`. Update `tck/handlers/account.py` to import and use
these shared helpers in place of its local `_serialize_key`/`_enum_name`,
preserving existing behavior.

- In `tck/handlers/token.py`, add `@rpc_method("getTokenInfo") def
get_token_info(params: GetTokenInfoParams) -> GetTokenInfoResponse`, mirroring
`get_account_info`: get the client, build
`TokenInfoQuery().set_grpc_deadline(DEFAULT_GRPC_TIMEOUT)`, conditionally
`set_token_id(TokenId.from_string(params.tokenId))`, call `execute(client)`,
then delegate to a `_build_token_info_response` mapper. Import `TokenInfoQuery`
from `hiero_sdk_python.query.token_info_query`.

- Implement `_build_token_info_response(info: TokenInfo) ->
GetTokenInfoResponse` doing field-by-field mapping: keys via `serialize_key`,
enum fields (`token_type`, `default_freeze_status`, `default_kyc_status`,
`pause_status`, `supply_type`) via `enum_name`, numerics/timestamps/durations
stringified, IDs via `str(...)` guards.

- Add a `_serialize_custom_fee(fee)` helper in `tck/handlers/token.py` that
dispatches via `isinstance` on
`CustomFixedFee`/`CustomFractionalFee`/`CustomRoyaltyFee`, inverting the
existing `_build_custom_fee` logic. Reuse base fields
(`fee_collector_account_id` → `feeCollectorAccountId`,
`all_collectors_are_exempt` → `feeCollectorsExempt`) and per-type fields with
the same camelCase names as `tck/param/custom_fee.py` (fixed:
`amount`/`denominatingTokenId`; fractional:
`numerator`/`denominator`/`minimumAmount`/`maximumAmount`/`assessmentMethod`;
royalty: `numerator`/`denominator`/`fallbackFee`). Populate `customFees` in
`_build_token_info_response` via a list comprehension over `info.custom_fees`.

Phase 3: Validation Against hiero-sdk-tck

Confirm the endpoint behaves per specification. The repo's internal tests/tck suite only covers generic plumbing, so functional validation is driven by the external conformance suite as the ticket requires.

Run the TCK server against the hiero-sdk-tck TokenInfoQuery suite

Verify conformance and reconcile any field-name/casing discrepancies.

• Start the standalone server (python -m tck) and run the external hiero-sdk-tck TokenInfoQuery test spec against it.
• If the suite reports mismatches (notably enum casing per Assumption 1, timestamp/duration formatting, or key encoding), adjust the mapping in _build_token_info_response/_serialize_custom_fee and response field names accordingly.
• Optionally, if per-handler unit coverage is desired, add a new test mocking get_client/TokenInfoQuery.execute under tests/tck/ (no existing per-endpoint precedent to copy).

🤖 Prompt for AI agents

Validate the newly implemented `getTokenInfo` endpoint against the external
conformance suite, since the repo's internal `tests/tck` suite only covers
generic plumbing.

- Start the standalone server via `python -m tck` and run the external
`hiero-sdk-tck` TokenInfoQuery test spec against it.
- If the suite reports mismatches (notably enum casing per the
enum-serialization assumption, timestamp/duration formatting, or key encoding),
adjust the mapping in `_build_token_info_response`/`_serialize_custom_fee` and
response field names accordingly.
- Optionally, if per-handler unit coverage is desired, add a new test mocking
`get_client`/`TokenInfoQuery.execute` under `tests/tck/` (there is no existing
per-endpoint precedent to copy).

Research

The tck/ package is a standalone JSON-RPC 2.0 server (Flask, tck/server.py) that dispatches methods registered via the @rpc_method decorator in tck/handlers/registry.py. Each domain has a handler module (tck/handlers/*.py), a param module with parse_json_params dataclasses (tck/param/*.py), and a plain response dataclass module (tck/response/*.py); responses are auto-serialized with dataclasses.asdict() (dropping Nones).

Query-style endpoints already exist — getAccountInfo/getAccountBalance in tck/handlers/account.py build a Query, call .execute(client), and map the SDK result field-by-field.

The SDK already provides TokenInfoQuery (src/hiero_sdk_python/query/token_info_query.py) returning a fully-populated TokenInfo (src/hiero_sdk_python/tokens/token_info.py).

No getTokenInfo currently exists anywhere in tck/.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the request and response data contract for the new `getTokenInfo`
endpoint, mirroring the existing `getAccountInfo` query pattern.

- In `tck/param/token.py`, add `GetTokenInfoParams` extending `BaseParams` (not
`BaseTransactionParams`, since this is a query with no
`commonTransactionParams`). Include a single optional `tokenId: str | None =
None` field. Implement `parse_json_params` to read `tokenId` and `sessionId`
(via `parse_session_id`), mirroring `GetAccountInfoParams` in
`tck/param/account.py`.

- In `tck/response/token.py`, add `GetTokenInfoResponse` as a plain `@dataclass`
with all fields optional (default `None`, or `field(default_factory=list)` for
`customFees`). Cover the full `TokenInfo` surface with camelCase keys:
`tokenId`, `name`, `symbol`, `decimals`, `totalSupply`, `treasury`, `adminKey`,
`kycKey`, `freezeKey`, `wipeKey`, `supplyKey`, `feeScheduleKey`, `pauseKey`,
`metadataKey`, `defaultFreezeStatus`, `defaultKycStatus`, `deleted`,
`autoRenewAccount`, `autoRenewPeriod`, `expirationTime`/`expiry`, `memo`,
`tokenType`, `supplyType`, `maxSupply`, `pauseStatus`, `metadata`, `ledgerId`,
and `customFees`.

- Add nested response dataclasses that mirror the reverse of
`tck/param/custom_fee.py`: a `CustomFeeResponse` wrapper
(`feeCollectorAccountId`, `feeCollectorsExempt`, `fixedFee`, `fractionalFee`,
`royaltyFee`) with inner `FixedFeeResponse`, `FractionalFeeResponse`, and
`RoyaltyFeeResponse` (the latter carrying a nested `fallbackFee`).

- Follow the flat-string convention used by `GetAccountInfoResponse`: stringify
numerics/timestamps/durations, and use `str(...)` guards for optional SDK
fields.
===============================================================================

Task: 2

Wire the `getTokenInfo` endpoint end-to-end: build and execute a
`TokenInfoQuery`, then map the SDK `TokenInfo` (including its heterogeneous
custom-fee list) into the response contract defined in Phase 1. Registration is
automatic once the `@rpc_method`-decorated handler is added to the
already-imported `token.py` module.

- Create a shared helper module under `tck/util/` (e.g. `serialize_utils.py`)
exposing `serialize_key(key)` (DER string if available, else hex bytes) and
`enum_name(value)` (`.name` or `None`), lifted from the local helpers currently
in `tck/handlers/account.py`. Update `tck/handlers/account.py` to import and use
these shared helpers in place of its local `_serialize_key`/`_enum_name`,
preserving existing behavior.

- In `tck/handlers/token.py`, add `@rpc_method("getTokenInfo") def
get_token_info(params: GetTokenInfoParams) -> GetTokenInfoResponse`, mirroring
`get_account_info`: get the client, build
`TokenInfoQuery().set_grpc_deadline(DEFAULT_GRPC_TIMEOUT)`, conditionally
`set_token_id(TokenId.from_string(params.tokenId))`, call `execute(client)`,
then delegate to a `_build_token_info_response` mapper. Import `TokenInfoQuery`
from `hiero_sdk_python.query.token_info_query`.

- Implement `_build_token_info_response(info: TokenInfo) ->
GetTokenInfoResponse` doing field-by-field mapping: keys via `serialize_key`,
enum fields (`token_type`, `default_freeze_status`, `default_kyc_status`,
`pause_status`, `supply_type`) via `enum_name`, numerics/timestamps/durations
stringified, IDs via `str(...)` guards.

- Add a `_serialize_custom_fee(fee)` helper in `tck/handlers/token.py` that
dispatches via `isinstance` on
`CustomFixedFee`/`CustomFractionalFee`/`CustomRoyaltyFee`, inverting the
existing `_build_custom_fee` logic. Reuse base fields
(`fee_collector_account_id` → `feeCollectorAccountId`,
`all_collectors_are_exempt` → `feeCollectorsExempt`) and per-type fields with
the same camelCase names as `tck/param/custom_fee.py` (fixed:
`amount`/`denominatingTokenId`; fractional:
`numerator`/`denominator`/`minimumAmount`/`maximumAmount`/`assessmentMethod`;
royalty: `numerator`/`denominator`/`fallbackFee`). Populate `customFees` in
`_build_token_info_response` via a list comprehension over `info.custom_fees`.
===============================================================================

Task: 3

Validate the newly implemented `getTokenInfo` endpoint against the external
conformance suite, since the repo's internal `tests/tck` suite only covers
generic plumbing.

- Start the standalone server via `python -m tck` and run the external
`hiero-sdk-tck` TokenInfoQuery test spec against it.
- If the suite reports mismatches (notably enum casing per the
enum-serialization assumption, timestamp/duration formatting, or key encoding),
adjust the mapping in `_build_token_info_response`/`_serialize_custom_fee` and
response field names accordingly.
- Optionally, if per-handler unit coverage is desired, add a new test mocking
`get_client`/`TokenInfoQuery.execute` under `tests/tck/` (there is no existing
per-endpoint precedent to copy).

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