feat(tck): implement executeContract JSON-RPC method

[danielmarv]

Description:

Implement the executeContract JSON-RPC method in the TCK server so the TCK driver's ContractExecuteTransaction suite can run against the Python SDK.

• Add ExecuteContractParams dataclass in tck/param/contract.py (contractId, gas, amount, functionParameters, commonTransactionParams).
• Add ExecuteContractResponse dataclass in tck/response/contract.py extending StatusOnlyResponse.
• Implement _build_execute_contract_transaction and the execute_contract handler in tck/handlers/contract.py, following the createContract pattern. Call data is hex-decoded and passed straight to set_function_parameters(); no ABI encoding in the handler.
• ContractExecuteTransaction now rejects negative gas with ValueError("Gas cannot be negative") in the constructor and set_gas, matching ContractCreateTransaction.
• ContractExecuteTransaction no longer raises ValueError("Missing required ContractID") when building the body; a missing contract ID is left unset for the network to reject with INVALID_CONTRACT_ID, matching ContractDeleteTransaction and the other SDKs.
• Add unit tests in tests/tck/contract_handler_test.py and tests/unit/contract_execute_transaction_test.py.

Related issue(s):

Fixes #2602

Notes for reviewer:

• Spec vs driver drift: the spec table names the call-data param parameters, but the TCK driver (src/tests/contract-service/test-contract-execute-transaction.ts) and the JS TCK server send functionParameters. The handler follows the driver.
• Missing contract ID: the spec says this succeeds, but the driver expects INVALID_CONTRACT_ID from the network. The SDK previously failed locally, so the request never reached the network; that check is removed (see above).
• Negative gas: the driver expects INTERNAL_ERROR for gas="-1" and int64 min values. The SDK previously sent negative gas to the network; the new SDK guard raises ValueError, which handle_sdk_errors maps to INTERNAL_ERROR.
• Negative amount is intentionally passed through so the network returns CONTRACT_NEGATIVE_VALUE, as the driver expects.
• Non-integer or out-of-int64-range gas/amount raise INVALID_PARAMS, reusing the module's existing _require_int64.
• Tests & Linters:
  • All unit and TCK tests pass (uv run --extra tck pytest tests/unit tests/tck: 3378 passed).
  • All pre-commit hooks (gitleaks, end-of-file-fixer, trailing-whitespace, ruff-check, ruff-format, bandit) pass.
  • The TCK driver's ContractExecuteTransaction suite has not been run locally yet.

Checklist

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@           Coverage Diff           @@
##             main    #2713   +/-   ##
=======================================
  Coverage   95.67%   95.67%           
=======================================
  Files         169      169           
  Lines       11078    11080    +2     
=======================================
+ Hits        10599    10601    +2     
  Misses        479      479           

🚀 New features to boost your workflow:

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

[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.

• Last reviewed commit: fa3ba55

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

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: hiero-ledger/hiero-sdk-python/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 8391465a-63c9-4dd8-8cc4-23297de1a155

📥 Commits

Reviewing files that changed from the base of the PR and between c30fe4d and fa3ba55.

📒 Files selected for processing: 4

• src/hiero_sdk_python/contract/contract_execute_transaction.py
• tck/handlers/contract.py
• tck/param/contract.py
• tests/tck/contract_handler_test.py

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Walkthrough

The SDK now rejects negative contract execution gas and builds transaction bodies without a contract ID. The TCK server adds executeContract parameter parsing, transaction execution, and status responses.

Changes

Contract execution TCK support

Layer / File(s)	Summary
Contract execution transaction behavior src/hiero_sdk_python/contract/contract_execute_transaction.py, tests/unit/contract_execute_transaction_test.py	Construction and set_gas reject negative gas. Transaction body construction leaves contractID unset when no contract ID is supplied. Unit tests cover these behaviors.
executeContract request and execution flow tck/param/contract.py, tck/response/contract.py, tck/handlers/contract.py, tests/tck/contract_handler_test.py	ExecuteContractParams parses request fields, and ExecuteContractResponse defines a status-only response. The handler builds and executes a contract transaction, then returns the receipt status name. Tests cover parsing, field conversion, defaults, and invalid inputs.

Priority: ➖ Normal

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

Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant TCK as TCK caller
  participant Params as ExecuteContractParams
  participant Handler as execute_contract
  participant Transaction as ContractExecuteTransaction
  TCK->>Params: Parse executeContract parameters
  Params->>Handler: Supply parsed parameters
  Handler->>Transaction: Set contract ID, gas, amount, and function parameters
  Handler->>Transaction: Execute with status validation
  Transaction-->>Handler: Return receipt status
  Handler-->>TCK: Return status response

Loading

Merge Risk: 🟡 Moderate · up to fa3ba

Specification-form call data may be omitted, invalid numeric inputs may be accepted, and SDK callers see a changed missing-contract-ID failure. Resolve or explicitly accept these compatibility risks before merging.

Security architecture risk: 🔵 Low · up to fa3ba

The new operation reuses existing session selection, transaction signing, submission, and receipt validation. No new authorization bypass was established. Risk remains low rather than minimal because deployed access controls and network rejection behavior were not independently verified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — A caller able to reach the RPC and select a configured session can request contract calls and payable transfers using that session's transaction authority or supplied signers. Potential effects include payer expenditure, target-contract state changes, and downstream effects permitted by the invoked contract. This is not unrestricted network authority; effective exposure depends on session access, signatures, and contract/network rules.

Trust Boundaries and Controls

• inferred — The new RPC preserves the existing request-to-session-to-signer boundary rather than introducing a separate authorization path. Its integer, hex, and gas checks constrain transaction representation, not caller authority. Deployment isolation remains necessary to uphold the trusted-harness assumption and was not established by the available source.

Resilience and Maintainability Implications

• inferred — The handler retains inherited submission and receipt-error behavior and requests validated receipts before returning success. It does not introduce request-level deduplication or rollback: separate invocations create separate transactions and normally obtain new transaction IDs. Consequently, an interrupted RPC response is not evidence that a submitted contract call had no effect; network recovery and duplicate handling remain inherited dependencies.

Hardening Proposals

• proposed — Keep the TCK listener restricted to trusted test clients and dedicated test credentials. If remote or shared access is required, establish authenticated session ownership rather than treating possession of a sessionId as authorization.

Pre-merge checks: 3 · 2

Failed checks: 2 warnings

Check name	Status	Explanation	Resolution
Linked Issues check		Issue #2602 requires the executeContract request contract and behavior to match the TCK specification. The PR registers the handler and maps contractId, gas, amount, and hex-decoded `functionP…	Accept the specification field parameters, or support both parameters and functionParameters without losing call data. Run the TCK driver's ContractExecuteTransaction suite and resolve any remaining specification behavior difference…
Docstring Coverage		Docstring coverage is 45.83% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 24 functions across 6 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 3 passed

Check name	Status	Explanation
Description check		The description clearly explains the executeContract handler, transaction behavior changes, tests, and known TCK limitation.
Title check		The title clearly identifies the main change: implementing the executeContract JSON-RPC method in the TCK server.
Out of Scope Changes check		The changes stay within issue #2602. The handler, parameter and response models, SDK validation changes, and tests support executeContract dispatch and its required error handling. No unrelated chan…

Full details: Out of Scope Changes check

Explanation

The changes stay within issue #2602. The handler, parameter and response models, SDK validation changes, and tests support executeContract dispatch and its required error handling. No unrelated change is shown.

Full details: Linked Issues check

Explanation

Issue #2602 requires the executeContract request contract and behavior to match the TCK specification. The PR registers the handler and maps contractId, gas, amount, and hex-decoded functionParameters. However, ExecuteContractParams.parse_json_params() reads only functionParameters; it does not accept the specification field parameters. The PR description also states that the TCK driver's ContractExecuteTransaction suite was not run, so the required end-to-end acceptance cases are not established.

Resolution

Accept the specification field parameters, or support both parameters and functionParameters without losing call data. Run the TCK driver's ContractExecuteTransaction suite and resolve any remaining specification behavior differences.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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: 3

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Repository: hiero-ledger/hiero-sdk-python/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: c4395e04-0642-443a-bf9c-47d40b49cb37

📥 Commits

Reviewing files that changed from the base of the PR and between 7e112e9 and 9b7c41d.

📒 Files selected for processing (6)

• src/hiero_sdk_python/contract/contract_execute_transaction.py
• tck/handlers/contract.py
• tck/param/contract.py
• tck/response/contract.py
• tests/tck/contract_handler_test.py
• tests/unit/contract_execute_transaction_test.py

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Repository: hiero-ledger/hiero-sdk-python/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: e1904e62-ba59-4f2a-a4d2-dc4b03de30ae

📥 Commits

Reviewing files that changed from the base of the PR and between 9b7c41d and cee3e4c.

📒 Files selected for processing (4)

• src/hiero_sdk_python/contract/contract_execute_transaction.py
• tck/handlers/contract.py
• tck/param/contract.py
• tests/tck/contract_handler_test.py

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

[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

[manishdait]

lgtm!

[MonaaEid]

please update the branch @danielmarv

[manishdait]

@danielmarv, please update the branch

[github-actions]

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

Thanks for your contribution! 🚀

Here are some issues you might want to explore next:

• chore: deprecate accountbalancequery
• Document the qualifications or pre-requisites to qualify as triage/committer/maintainer
• feat(tck): implement getAddressBook JSON-RPC method
• feat: generate ResponseCode member list from proto in generate_proto.py
• feat: implement _from_protobuf for account transactions (from_bytes round-trip)

🌟 Stay connected:

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

Happy coding! 🚀
— Hiero Python SDK Team