HIP-1217: Important Updates to the Hedera /api/v1/contracts/call Endpoint

By: Michiel Mulders

HIP-1217 details significant enhancements to the Hedera Mirror Node API endpoint /api/v1/contracts/call. This update introduces a modularized execution flow, aligning closely with Hedera Consensus Nodes to offer a more accurate and reliable contract execution experience.

Why the Change?

Previously, Hedera’s EVM (Ethereum Virtual Machine) implementation operated as a monolithic system. This system occasionally leads to discrepancies between simulated mirror node calls and actual consensus node behavior. This update modularizes the EVM execution logic and integrates directly with the hedera-app library, resulting in:

• More accurate gas estimations
• Consistent behavior across consensus and mirror nodes
• Simplified debugging through improved error codes

What’s Changing?

Here are the key areas impacted by this update and what developers need to know:

1. Address Resolution

• Impact: Calls using Number Alias (0x0000…) will fail if a Keccak-256 alias exists. So, if it’s an ED25519 account, you would use the Number alias (long-zero). If it’s an ECDSA account that has a Keccak-256 alias, then you need to use that alias. For rare cases where an ECDSA account does not have a Keccak-256 alias, you could use the Number Alias.
• If in doubt on which Alias to use, please use the evm_address field from the Mirror Node account API (GET /api/v1/accounts/{id}) or the contractAccountId field from the Hedera SDK using GetAccountInfo.
• Action Needed: Use the public key derived Keccak-256 alias format (0xc5b7…) for ECDSA accounts.
• Deployment Date: December 1, 2025

2. Payer Balance Validation

• Impact: Calls previously successful might fail with INSUFFICIENT_PAYER_BALANCE if the payer lacks sufficient balance. The modularized execution flow enforces a stricter validation of the payer’s balance before executing contract calls.
• Action Needed: Ensure payer accounts have adequate balances even for simulations (eth_call).
• Deployment Date: December 1, 2025

3. Invalid Input Handling

• Impact: More specific and granular error statuses will now be returned, such as INVALID_CONTRACT_ID.
• Action Needed: Update client-side logic to handle a wider range of status codes and to expect HTTP 400 responses with more descriptive error messages. Ensure precompile calls like the exchange rate query are made with no value, or expect INVALID_CONTRACT_ID under modularized behavior.
• Deployment Date: September 1, 2025

4. Gas Estimation

• Impact: Slight variations in gas estimates are expected, particularly more significant and accurate changes for contract deployments.
• Action Needed: Adjust tests and applications to account for these refined estimates.
• Deployment Date: September 1, 2025

5. Default KYC Status

• Impact: Results from getDefaultKycStatus calls might differ, reflecting the true consensus node state.
• Action Needed: Review any tests or client logic that depend on the default KYC status returned by contract calls and adjust expectations to reflect the consensus-backed behavior in the modularized flow.
• Deployment Date: September 1, 2025

6. Return Values vs Exceptions

• Impact: Calls previously returning default values might now throw errors, or vice versa.
• Action Needed: Update client logic to handle exception-based and value-based responses appropriately.
• Deployment Date: September 1, 2025
• Examples:
• eth_call with a sender address that does not exist:
• Monolithic: Returns “0x”
• Modularized: Throws a PAYER_ACCOUNT_NOT_FOUND error
• Precompiled Hedera Token Service contract call (e.g., isToken) on a token that has not yet been persisted:
• Monolithic: reverts the call with CONTRACT_REVERT_EXECUTED
• Modularized: returns false or an empty result

7. Call to Nonexistent Contracts

• Impact: Previously returned INVALID_TRANSACTION, now returns INVALID_CONTRACT_ID.
• Action Needed: Modify error-handling logic to accept the new status code.
• Deployment Date: September 1, 2025

8. Redirect Call Errors

• Impact: Redirect errors previously showing specific codes (e.g., INVALID_TOKEN_ID) now standardize to CONTRACT_REVERT_EXECUTED.
• Action Needed: Update tests and error handling accordingly.
• Deployment Date: September 1, 2025

Backward Compatibility

Note that these changes are not backward compatible. Developers must update applications to handle new behaviors and avoid unexpected errors or failures.

Temporary Workarounds and Migration Support

For changes in Address Resolution and Payer Balance Validation, temporary workarounds are in place, delaying these behaviors until December 1, 2025.

If your team needs additional time beyond these dates, you can request temporary routing to the legacy logic by contacting Keith Kowal on Discord (handle: reccetech). We will collaborate directly with you to create a tailored migration plan with clear target dates.

Mirror Node Operator Instructions

Mirror node operators can enable the modularized flow for their instances by setting the following environment variables:

HIERO_MIRROR_WEB3_EVM_MODULARIZEDSERVICES="true"
HIERO_MIRROR_WEB3_EVM_MODULARIZEDTRAFFICPERCENT="1"

Adjust the HEDERA_MIRROR_WEB3_EVM_MODULARIZEDTRAFFICPERCENT value based on your testing and rollout plan.

Next Steps & Timeline

We strongly encourage developers to test their applications against the Previewnet and Testnet, where the modularized flow is currently live and serving 100% of traffic. This will ensure a smooth transition and help to identify any adjustments needed prior to mainnet rollout.

Timeline for changes 3 to 8

• Initial Month (July 1st): This is the communication phase only. 0% of traffic is routed to the new logic on mainnet mirror node.
• End of Month 1 (August 1st): 10% of all traffic routed to new logic on mainnet
• End of Month 2 (September 1st): 100% of traffic routed to new logic on mainnet.

Timeline for changes 1 and 2:

• December 1st:Address Resolution and Payer Balance Validation go live on mainnet.

For detailed technical information, review HIP-1217.

HIP-1217: Important Updates to the Hedera /api/v1/contracts/call Endpoint was originally published in Hedera Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.