[Advanced]: Add TCK server test for token associate transaction

[exploreriii]

🧠 Advanced Contributors

This issue is intended for contributors who are already very familiar with the
Hiero Python SDK codebase and its architectural patterns.

You should feel comfortable:

• navigating multiple modules across src/
• understanding and modifying core SDK abstractions
• reasoning about API design and backwards compatibility
• updating or extending tests, examples, and documentation as needed
• making changes that may affect public-facing behavior

New developers should start with
Good First Issues or Intermediate Issues first.

🐞 Problem Description

We have a new TCK server connection at the python sdk

We should write tests for it, to verify expected behaviour

💡 Proposed / Expected Solution

Write a test for Token associate transaction

Ensure it meets the TCK specifications:
https://hiero-ledger.github.io/hiero-sdk-tck/test-specifications/token-service/TokenAssociateTransaction.html

There are similar examples at
https://github.com/hiero-ledger/hiero-sdk-swift/blob/main/Sources/HieroTCK/token/params/AssociateTokenParams.swift
https://github.com/hiero-ledger/hiero-sdk-cpp/blob/main/src/tck/src/token/TokenService.cc
and perhaps the other SDKs

🧠 Implementation & Design Notes

Read:
https://hiero-ledger.github.io/hiero-sdk-tck/test-specifications/token-service/TokenAssociateTransaction.html

Write a test similar to the other SDKs to check the expected functionality

Run the test and see the results!

✅ Acceptance Criteria

To merge this issue, the pull request must:

• Fully address the problem and design goals described above
• Maintain backwards compatibility unless explicitly approved otherwise
• Follow existing architectural and coding conventions
• Include comprehensive tests covering new and existing behavior
• Update relevant examples and documentation
• Pass all CI checks
• Include a valid changelog entry
• be a DCO and GPG key signed as git commit -S -s -m "chore: my change" with a GPG key set up

📚 Additional Context, Links, or Prior Art

Optional.

[github-actions]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Establish a shared common.py module with apply_common_transaction_params() to create a reusable foundation for all future TCK transaction handlers
• Implement associateToken handler in token.py following the Swift/C++ SDK patterns: parse params, build transaction, apply common params, execute, return status
• Leverage existing error handling in registry.py dispatch layer which automatically converts PrecheckError and ReceiptStatusError to JsonRpcError.hiero_error()
• Create comprehensive unit tests using MagicMock patterns established in tests/unit/tck/ to verify handler behavior without requiring network connectivity

Design Choices

Design Choice 1: Handling of `commonTransactionParams` placement

Options Considered:

1. Implement commonTransactionParams logic directly in token.py handler
2. Create a shared common.py module with reusable utilities

Chosen Option: 2

Rationale: A shared module establishes a reusable pattern for all future transaction handlers (account, contract, file, etc.) and avoids code duplication.

Design Choice 2: Error handling for missing client

Options Considered:

1. Return a generic internal error
2. Raise a specific JsonRpcError with descriptive message

Chosen Option: 2

Rationale: Raise JsonRpcError.internal_error() with message indicating no client is configured, matching the pattern expected by TCK tests for missing setup.

💡 User Tips

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

Implementation Steps

Phase 1: Common Transaction Params Infrastructure

Create shared utilities for applying common transaction parameters that will be reused by all future transaction handlers. This establishes the foundation for TCK-compliant transaction handling.

Task 1: Create Common Params Utility Module

Establish a shared module for transaction parameter handling that all handlers can import.

• Create tck/handlers/common.py with an apply_common_transaction_params(transaction, common_params, client) function
• Handle pre-freeze fields: memo (via set_transaction_memo()), maxTransactionFee (direct assignment to transaction_fee), transactionValidDuration (via set_transaction_valid_duration())
• Handle transactionId parsing via TransactionId.from_string() if provided
• After freezing with client, iterate over signers list and apply each via PrivateKey.from_string() then transaction.sign()
• Return the frozen, signed transaction ready for execution

Task 2: Create Client Retrieval Helper

Add a helper function that retrieves the client and raises an appropriate error if not found.

• Add get_client_or_error(session_id) function in tck/handlers/common.py
• Call client_manager.get_client(session_id) and if None, raise JsonRpcError.internal_error() with message indicating client not configured
• This standardizes error handling across all transaction handlers

🤖 Prompt for AI agents

Create a new shared utility module at `tck/handlers/common.py` that provides
reusable infrastructure for all TCK transaction handlers.

- Implement `apply_common_transaction_params(transaction, common_params,
client)` function:
  - Before freezing, apply pre-freeze fields if present in `common_params`:
    - `memo` → call `transaction.set_transaction_memo()`
    - `maxTransactionFee` → assign directly to `transaction.transaction_fee`
- `transactionValidDuration` → call
`transaction.set_transaction_valid_duration()`
    - `transactionId` → parse via `TransactionId.from_string()` if provided
  - Freeze the transaction with the client
- Iterate over `signers` list (if present): for each, call
`PrivateKey.from_string()` then `transaction.sign()`
  - Return the frozen, signed transaction
- Implement `get_client_or_error(session_id)` function:
  - Call `client_manager.get_client(session_id)`
- If the result is `None`, raise `JsonRpcError.internal_error()` with a
descriptive message indicating no client is configured
  - Otherwise return the client
  - This standardizes error handling across all transaction handlers

Phase 2: Token Associate Handler

Implement the associateToken JSON-RPC method following the TCK specification and patterns from other SDK implementations.

Task 1: Create Token Handler Module

Create the token service handler module with the associate transaction handler.

• Create tck/handlers/token.py with necessary imports: register_handler, validate_request_params, TokenAssociateTransaction, AccountId, TokenId, ResponseCode
• Define associate_token_handler(params, session_id) decorated with @register_handler("associateToken")
• Parse optional accountId via AccountId.from_string() if provided
• Parse optional tokenIds list, converting each to TokenId.from_string()
• Build TokenAssociateTransaction, set account ID and token IDs
• Apply commonTransactionParams using the utility from Phase 1
• Execute transaction and return {"status": ResponseCode(receipt.status).name}
• Wrap SDK errors appropriately (the dispatch layer handles PrecheckError and ReceiptStatusError conversion to JsonRpcError.hiero_error())

Task 2: Register Token Handler Module

Enable automatic handler registration on module import.

• Modify tck/handlers/__init__.py to add from . import token alongside the existing from . import sdk import
• This triggers the @register_handler decorator to register the associateToken method

🤖 Prompt for AI agents

Create the `associateToken` JSON-RPC handler in a new file
`tck/handlers/token.py`, then register it in the handler package.

**`tck/handlers/token.py`:**
- Import: `register_handler`, `validate_request_params`,
`TokenAssociateTransaction`, `AccountId`, `TokenId`, `ResponseCode`, and the
utilities from `common.py`
- Define `associate_token_handler(params, session_id)` decorated with
`@register_handler("associateToken")`:
- Parse optional `accountId` using `AccountId.from_string()` if present in
params
- Parse optional `tokenIds` list, converting each element via
`TokenId.from_string()`
- Build a `TokenAssociateTransaction`, calling `set_account_id()` and
`set_token_ids()` with the parsed values
  - Retrieve the client using `get_client_or_error(session_id)` from Phase 1
- Apply `commonTransactionParams` using `apply_common_transaction_params()` from
Phase 1 if present
- Execute the transaction and return `{"status":
ResponseCode(receipt.status).name}`
- SDK errors (`PrecheckError`, `ReceiptStatusError`) are handled automatically
by the dispatch layer in `registry.py`

**`tck/handlers/__init__.py`:**
- Add `from . import token` alongside the existing `from . import sdk` import to
trigger `@register_handler` decorator registration

Phase 3: Unit Tests

Create comprehensive unit tests for the token associate handler following existing TCK test patterns.

Task 1: Create Token Handler Test Module

Establish the test file with proper fixtures and isolation.

• Create tests/unit/tck/token_test.py with pytestmark = pytest.mark.unit
• Add autouse=True fixture to clear handler registry before/after each test (same pattern as handlers_test.py)
• Add fixtures for mock client and mock transaction objects using MagicMock()

Task 2: Implement Happy Path Tests

Test successful token association scenarios.

• Test associateToken with valid accountId and single tokenId returns {"status": "SUCCESS"}
• Test with multiple tokenIds in the list
• Test with commonTransactionParams including memo and signers
• Mock TokenAssociateTransaction, get_client, and transaction execution
• Use the raise AssertionError(...) pattern for assertions (not bare assert)

Task 3: Implement Error Path Tests

Test error handling for invalid inputs and SDK errors.

• Test missing accountId raises appropriate error or SDK handles gracefully
• Test invalid accountId format raises JsonRpcError
• Test invalid tokenId format raises JsonRpcError
• Test when client not configured (no setup called) raises JsonRpcError.internal_error()
• Test PrecheckError from SDK is converted to JsonRpcError.hiero_error() with correct status
• Test ReceiptStatusError (e.g., TOKEN_ALREADY_ASSOCIATED_TO_ACCOUNT) is converted to JsonRpcError.hiero_error()

Task 4: Implement Common Params Tests

Test the commonTransactionParams utility independently.

• Test applying memo sets transaction.memo correctly
• Test applying maxTransactionFee sets transaction.transaction_fee
• Test applying signers calls transaction.sign() with each private key
• Test that transaction is frozen before signing

🤖 Prompt for AI agents

Create comprehensive unit tests in `tests/unit/tck/token_test.py` following the
patterns established in `tests/unit/tck/handlers_test.py`.

**Test file setup:**
- Set `pytestmark = pytest.mark.unit` at module level
- Add an `autouse=True` fixture that clears the handler registry before and
after each test (same pattern as `handlers_test.py`)
- Add fixtures for mock client and mock transaction objects using `MagicMock()`
- Use `raise AssertionError(...)` for all assertions (not bare `assert`)

**Happy path tests:**
- Test `associateToken` with a valid `accountId` and a single `tokenId` returns
`{"status": "SUCCESS"}`
- Test `associateToken` with multiple `tokenIds` in the list
- Test `associateToken` with `commonTransactionParams` including memo and
signers
- Mock `TokenAssociateTransaction`, `get_client`, and transaction execution as
needed

**Error path tests:**
- Test missing `accountId` raises appropriate error or is handled gracefully by
the SDK
- Test invalid `accountId` format raises `JsonRpcError`
- Test invalid `tokenId` format raises `JsonRpcError`
- Test when no client is configured (no setup called) raises
`JsonRpcError.internal_error()`
- Test that `PrecheckError` from the SDK is converted to
`JsonRpcError.hiero_error()` with the correct status
- Test that `ReceiptStatusError` (e.g., `TOKEN_ALREADY_ASSOCIATED_TO_ACCOUNT`)
is converted to `JsonRpcError.hiero_error()`

**Common params unit tests:**
- Test applying `memo` sets `transaction.memo` correctly
- Test applying `maxTransactionFee` sets `transaction.transaction_fee`
- Test applying `signers` calls `transaction.sign()` with each private key
- Test that the transaction is frozen before signing occurs

Research

The TCK is a minimal JSON-RPC 2.0 server built with Flask (tck/server.py). Handler modules are located in tck/handlers/, where registry.py provides the @register_handler decorator and dispatch machinery, and sdk.py contains the only current handlers (setup and reset). The TokenAssociateTransaction class in src/hiero_sdk_python/tokens/token_associate_transaction.py provides set_account_id(), set_token_ids(), and standard transaction lifecycle methods. Tests follow the pattern in tests/unit/tck/ using MagicMock and explicit raise AssertionError(...) assertions.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Create a new shared utility module at `tck/handlers/common.py` that provides
reusable infrastructure for all TCK transaction handlers.

- Implement `apply_common_transaction_params(transaction, common_params,
client)` function:
  - Before freezing, apply pre-freeze fields if present in `common_params`:
    - `memo` → call `transaction.set_transaction_memo()`
    - `maxTransactionFee` → assign directly to `transaction.transaction_fee`
- `transactionValidDuration` → call
`transaction.set_transaction_valid_duration()`
    - `transactionId` → parse via `TransactionId.from_string()` if provided
  - Freeze the transaction with the client
- Iterate over `signers` list (if present): for each, call
`PrivateKey.from_string()` then `transaction.sign()`
  - Return the frozen, signed transaction
- Implement `get_client_or_error(session_id)` function:
  - Call `client_manager.get_client(session_id)`
- If the result is `None`, raise `JsonRpcError.internal_error()` with a
descriptive message indicating no client is configured
  - Otherwise return the client
  - This standardizes error handling across all transaction handlers
===============================================================================

Task: 2

Create the `associateToken` JSON-RPC handler in a new file
`tck/handlers/token.py`, then register it in the handler package.

**`tck/handlers/token.py`:**
- Import: `register_handler`, `validate_request_params`,
`TokenAssociateTransaction`, `AccountId`, `TokenId`, `ResponseCode`, and the
utilities from `common.py`
- Define `associate_token_handler(params, session_id)` decorated with
`@register_handler("associateToken")`:
- Parse optional `accountId` using `AccountId.from_string()` if present in
params
- Parse optional `tokenIds` list, converting each element via
`TokenId.from_string()`
- Build a `TokenAssociateTransaction`, calling `set_account_id()` and
`set_token_ids()` with the parsed values
  - Retrieve the client using `get_client_or_error(session_id)` from Phase 1
- Apply `commonTransactionParams` using `apply_common_transaction_params()` from
Phase 1 if present
- Execute the transaction and return `{"status":
ResponseCode(receipt.status).name}`
- SDK errors (`PrecheckError`, `ReceiptStatusError`) are handled automatically
by the dispatch layer in `registry.py`

**`tck/handlers/__init__.py`:**
- Add `from . import token` alongside the existing `from . import sdk` import to
trigger `@register_handler` decorator registration
===============================================================================

Task: 3

Create comprehensive unit tests in `tests/unit/tck/token_test.py` following the
patterns established in `tests/unit/tck/handlers_test.py`.

**Test file setup:**
- Set `pytestmark = pytest.mark.unit` at module level
- Add an `autouse=True` fixture that clears the handler registry before and
after each test (same pattern as `handlers_test.py`)
- Add fixtures for mock client and mock transaction objects using `MagicMock()`
- Use `raise AssertionError(...)` for all assertions (not bare `assert`)

**Happy path tests:**
- Test `associateToken` with a valid `accountId` and a single `tokenId` returns
`{"status": "SUCCESS"}`
- Test `associateToken` with multiple `tokenIds` in the list
- Test `associateToken` with `commonTransactionParams` including memo and
signers
- Mock `TokenAssociateTransaction`, `get_client`, and transaction execution as
needed

**Error path tests:**
- Test missing `accountId` raises appropriate error or is handled gracefully by
the SDK
- Test invalid `accountId` format raises `JsonRpcError`
- Test invalid `tokenId` format raises `JsonRpcError`
- Test when no client is configured (no setup called) raises
`JsonRpcError.internal_error()`
- Test that `PrecheckError` from the SDK is converted to
`JsonRpcError.hiero_error()` with the correct status
- Test that `ReceiptStatusError` (e.g., `TOKEN_ALREADY_ASSOCIATED_TO_ACCOUNT`)
is converted to `JsonRpcError.hiero_error()`

**Common params unit tests:**
- Test applying `memo` sets `transaction.memo` correctly
- Test applying `maxTransactionFee` sets `transaction.transaction_fee`
- Test applying `signers` calls `transaction.sign()` with each private key
- Test that the transaction is frozen before signing occurs

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