github hiero-ledger/hiero-json-rpc-relay v0.82.0

2 hours ago

Overview

v0.82.0 turns on nonce ordering and the txpool_* API by default, so with the default config the relay now orders transactions per sender and serves the newPendingTransactions WebSocket subscription. eth_getLogs gets byte limits: one per Mirror Node page, one per call, and one shared by all calls on the relay, so a single large query can no longer exhaust memory. The WebSocket poller has been rewritten around one shared polling loop. prestateTracer now supports geth's diffMode, disableCode, disableStorage and includeEmpty options. Contract-create transactions now return to: null in block and by-index lookups. On the operations side, Mirror Node timeouts and retries get their own counters, aborted requests no longer log errors, writing every block of a range to the cache can be switched off, and the WebSocket Grafana dashboard has new poller panels.

Before upgrading, review the breaking changes below. Defaults for nonce ordering and the txpool API have changed, eth_getLogs can now fail with -32005 on very large results, and prestateTracer drops empty accounts by default.

⚠️ Breaking Changes

Review all items below and update your configuration, clients and tracing consumers before upgrading.

Item Before After Notes
ENABLE_NONCE_ORDERING default false true eth_sendRawTransaction takes a per-sender lock so transactions from the same address are processed in FIFO order. Together with ENABLE_TX_POOL (already true) this also enables the newPendingTransactions subscription. Set ENABLE_NONCE_ORDERING=false to keep the old behaviour. (#6002, #6008)
TXPOOL_API_ENABLED default false true txpool_* methods are now served by default. Set TXPOOL_API_ENABLED=false to disable them. (#6002, #6008)
Pending-pool cleanup after eth_sendRawTransaction Mirror Node polling ran whenever nonce ordering and the tx pool were on Polling also requires DISABLE_MN_PRECHECKS_ON_TX_SENDING=false; otherwise the pooled transaction is removed as confirmed right away A transaction the Mirror Node shows as rejected before consensus (non-SUCCESS with no block) is now removed from the pool as rejected, not counted as confirmed, because the sender's nonce did not move. (#6002, #6008)
Large eth_getLogs results Every Mirror Node page held in memory with no byte limit Fails with -32005 when a Mirror Node page exceeds ETH_GET_LOGS_MAX_PAGE_SIZE (8 MiB), when the call's logs exceed ETH_GET_LOGS_MAX_RESPONSE_SIZE (25 MiB), or when all running calls together exceed ETH_GET_LOGS_RELAY_MAX_RESPONSE_SIZE (50 MiB) The 25 MiB default fits a block with 30,000 ERC20 Transfer logs. Clients that hit the limit should narrow the block range or filter by address or topics. The relay-wide error ("eth_getLogs memory limit reached on the relay, try again later") is transient and can be retried. (#5994, #5999, #6007, #6010)
prestateTracer empty accounts Accounts with no nonce, no code and no balance were returned Dropped by default, as in geth Pass includeEmpty: true to get them back. (#5954)
prestateTracer diffMode Rejected on its own, silently ignored next to another known key Supported by debug_traceTransaction; rejected with -32610 by debug_traceBlockByNumber / debug_traceBlockByHash Needs the Mirror Node prestate endpoint (Mirror Node v0.165.0+ with hiero.mirror.web3.api.prestate.enabled). There is no fallback: if the endpoint is disabled the call fails with -32610. (#5985)
to for contract-create transactions in eth_getBlockByHash / eth_getBlockByNumber (full transactions) and eth_getTransactionByBlockHashAndIndex / eth_getTransactionByBlockNumberAndIndex Address of the new contract null Matches eth_getTransactionByHash and eth_getBlockReceipts. Clients that re-encode the transaction now get a hash that matches hash. (#5982)

New configuration

  • ETH_GET_LOGS_MAX_PAGE_SIZE (default 8388608, 8 MiB, must be 1 or greater) - maximum size in bytes of one Mirror Node log page fetched for eth_getLogs. The download stops once the page grows past the limit, the page is not retried, and the call fails with -32005. (#5994, #6007)
  • ETH_GET_LOGS_MAX_RESPONSE_SIZE (default 26214400, 25 MiB, must be 1 or greater) - maximum estimated JSON size in bytes of the logs returned by one eth_getLogs call. Shared by all timestamp slices and addresses of the call; once it is exceeded, the call's remaining Mirror Node requests are cancelled. (#5994, #6007)
  • ETH_GET_LOGS_RELAY_MAX_RESPONSE_SIZE (default 52428800, 50 MiB, integer of 1 or greater) - maximum bytes of log data that all eth_getLogs calls on the relay may hold at the same time, shared by the HTTP and WebSocket servers. A request gives its bytes back once its response has been written. (#5999, #6010)
  • MIRROR_NODE_BLOCK_RANGE_CACHE_ENABLED (default true) - whether blocks fetched as a range (for example by eth_getLogs and eth_feeHistory) are also written to the per-block cache. Since v0.80.0 one eth_getLogs call can write up to 1000 getBlock.<n> keys; set this to false if those writes put pressure on Redis memory. (#5996, #6009)

The changed defaults of ENABLE_NONCE_ORDERING and TXPOOL_API_ENABLED are listed under Breaking Changes.

Highlights

  • Nonce ordering and txpool API on by default - transactions from one sender are processed in order, and txpool_* methods and the newPendingTransactions subscription work without extra configuration. (#6002, #6008)
  • Bounded eth_getLogs memory - per-page, per-call and relay-wide byte limits keep a single large query, or many at once, from exhausting the relay's memory. (#5994, #5999, #6007, #6010)
  • Reworked WebSocket poller - all subscriptions share one polling loop. Polls never overlap, each block range is fetched with one unfiltered Mirror Node logs query and matched to subscriptions in memory, and newHeads is built once per block. No block is skipped or sent twice: after an outage the poller catches up 10 blocks per poll and halves the range when a query would return too many logs. Failed polls retry with a growing delay capped at 10 s. (#5981)
  • prestateTracer options - diffMode returns geth's { pre, post } shape, with only the changed fields in post. disableCode, disableStorage and includeEmpty are supported on both the Mirror Node endpoint and the fallback path. (#5954, #5985)

Bug fixes

  • Contract-create transactions returned the new contract's address as to instead of null in full-transaction block lookups and in eth_getTransactionByBlock*AndIndex. On block-stream Mirror Nodes the deployment check falls back to transaction-record lookups, which adds Mirror Node calls to full-transaction block fetches, the same cost eth_getBlockReceipts already pays. (#5982)
  • Requests abandoned by the client still logged AbortError at warn/error from fallback catch blocks in eth_feeHistory, eth_getLogs, prestateTracer and debug_traceBlockByNumber, and kept making Mirror Node calls. The abort is now rethrown and logged once at debug. This also stops an empty eth_feeHistory result (cached for 15 minutes) and a partial prestate from being cached. (#5992, #5993)

Security & operations

  • New Mirror Node counters, labelled by method, so a slow Mirror Node can be told apart from real upstream 504s: rpc_relay_mirror_node_request_count, rpc_relay_mirror_node_retry_count, rpc_relay_mirror_node_timeout_count and rpc_relay_mirror_node_timeout_retry_count. With MIRROR_NODE_RETRIES above 0, the timeout retry count is the better alerting signal. Existing metrics are unchanged. (#5997, #6006)
  • New WebSocket poller metrics rpc_websocket_poller_lag_blocks and rpc_websocket_poller_failed_polls_total, with matching panels on the WebSocket Grafana dashboard. (#5981, #5988)
  • Writing every block of a range to the cache can be turned off with MIRROR_NODE_BLOCK_RANGE_CACHE_ENABLED. (#5996, #6009)
  • npm package metadata: removed a duplicate bin key and used the canonical repository.url. (#5978)
  • Notable dependency bumps: fast-uri 3.1.7 → 3.1.9 (#5938), follow-redirects 1.16.1 → 1.16.2 (#5962), step-security/harden-runner 2.22.2 → 2.22.3 (#5958).

What's Changed

  • chore(release): Bump versions for v0.82.0-SNAPSHOT by @swirlds-automation in #5961
  • build(deps): bump step-security/harden-runner from 2.22.2 to 2.22.3 in the actions-weekly group across 1 directory by @dependabot[bot] in #5958
  • build(deps): bump follow-redirects from 1.16.1 to 1.16.2 by @dependabot[bot] in #5962
  • feat: add INSUFFICIENT_PAYER_BALANCE in hedera specific statuses array by @natanasow in #5966
  • feat: populated aborted request as 499 instead of 500 by @natanasow in #5971
  • feat: optimize Redis usage in txpool metrics and add configurable command timeout by @tgntr in #5967
  • fix: use the earliest recorded gas price for blocks before the fee schedule has one by @ValentinVPK in #5969
  • ci(publish): Add repo config to package.json and add .npmignore by @rbarker-dev in #5976
  • ci(publish): remove duplicate bin key and align package metadata by @rbarker-dev in #5978
  • feat: support disableCode, disableStorage and includeEmpty for prestateTracer by @ValentinVPK in #5954
  • fix: return null to for contract-create transactions in block and by-index lookups by @tgntr in #5982
  • feat: rework poller service by @tgntr in #5981
  • feat: support diffMode for prestateTracer by @ValentinVPK in #5985
  • build(deps): bump fast-uri from 3.1.7 to 3.1.9 by @dependabot[bot] in #5938
  • feat: add grafana panels for reworked poller by @natanasow in #5988
  • feat: cherry-pick rethrow request aborts instead of logging them in fallback catch blocks to 0.82 by @natanasow in #5993
  • feat: cherry-pick count Mirror Node client timeouts separately from upstream 504 to 0.82 by @natanasow in #6006
  • feat: cherry-pick limit size of one eth_getLogs to 0.82 by @natanasow in #6007
  • feat: cherry-pick activate nonce ordering and tx pool by default to 0.82 by @natanasow in #6008
  • feat: cherry-pick stop caching every block fetched by getBlocksByRange to 0.82 by @natanasow in #6009
  • feat: cherry-pick limit total eth_getLogs memory across the relay to 0.82 by @natanasow in #6010

#5966, #5971, #5967, #5969 and #5976 already shipped in v0.81.0 as cherry-picks and are not repeated above.

Full Changelog: v0.81.0...v0.82.0

Don't miss a new hiero-json-rpc-relay release

NewReleases is sending notifications on new releases.