Hedera Mirror Node

Hedera mirror node release notes

For the latest versions supported on each network please visit the Hedera status page.

Latest Releases

This is a smaller bug fix release with incremental improvements to some in-flight projects.

For HIP-857, an alpha version of the NFT allowance REST API is now in place. It can be used to experiment with while we work towards implementing the remaining query parameters and squashing any bugs. The Jooq library was integrated into the rest-java module to allow for dynamic SQL querying based upon user input. The next release should leverage this functionality to fully implement the remaining parts of the API.

Our Citus implementation was successfully deployed to the performance environment and it is passing initial benchmarks. Preliminary results show that Citus improves ingest performance by 600ms while sharding the data across multiple nodes. Promtail was enabled on Citus nodes to capture database logs and a new ZFS dashboard was added to Grafana.

This release adds support for storing the new mutable metadata information available in HIP-646, HIP-657, and HIP-765. For now, it just persists the data and in future releases we'll expose it via the REST APIs.

The /api/v1/tokens REST API now supports multiple token.id parameters. This allows users to efficiently query for multiple tokens in a single call.

The /api/v1/contracts/call REST API saw some major performance improvements this release. The first change was to switch the Kubernetes node pools to a different machine class that provides dedicated resource allocation. The endpoint was also switched from a reactive MVC stack to a synchronous MVC stack. Simultaneously, the module enabled the new virtual thread technology that replaces platform threads. These changes combined to improve the request throughput by 1-2x.

Another important change was to enable batching between the download and parser threads in the importer. For now, this functionality is configured to behave as before with no batching. When configured manually, this can reduce sync times for historical data by at least 12x. In the future, we'll look at ways to automatically enable this functionality when the importer is attempting to catch up.

This release implements HIP-859, adding support for returning gas consumed in the contract result REST APIs. The current gasUsed field in the API holds the amount of gas charged, while the new gasConsumed field holds the amount of gas actually used during EVM execution. Providing this extra data will allow users to provide a more accurate gas when invoking a contract and reduce the fees they are charged.

/api/v1/contracts/call now supports a configurable max gas limit property hedera.mirror.web3.evm.maxGas. The default value remains at 15 million but operators can now choose to increase it to suite their needs. The EVM version and features have been upgraded to v0.46. This brings feature parity with the latest consensus node software for EVM execution.

There was a large amount of work to improve our integration with Citus. Three repeatable migrations were enhanced to work optimally with Citus: account balance migration, token balance migration, and synthetic transfer approval migration. Token account insertion was optimized to improve its performance by removing the join on the token table. Range partitioning was removed for entity related tables since it caused degraded performance due to having sparse partitions. Finally, the deployment now supports different sized disks for individual workers to optimize for unbalanced data.

This release contains the implementation of HIP-873 adding token decimals to the REST API. Previously users had to make N + 1 queries to determine accurate token balance information by querying /api/v1/accounts/{id}/tokens once and /api/v1/tokens/{id} N times to get the relevant decimal information. This HIP adds decimals to both /api/v1/tokens/{tokenId}/balances and /api/v1/accounts/{id}/tokens so that decimal information is directly returned alongside the token relationships and the additional N queries are unnecessary. It also adds name and decimals fields to the /api/v1/tokens response to expose more of the existing token information on that API.

The /api/v1/contracts/call REST API now supports a configurable hedera.mirror.web3.evm.maxDataSize property so that mirror node operators can adjust how large of a payload they wish to support. The default value for the max data size was increased from 24 KiB to 25 KiB for creates and from 6 KiB to 25 KiB for calls. This change makes it possible for view functions with large inputs like oracles to now work on the network.

There were a few items to improve the performance and security of the mirror node. A new hedera.mirror.importer.downloader.maxSize=50MiB property controls the maximum stream file size it will attempt to download. This protects the mirror node against large files uploaded accidentally or via malicious actors. The importer was refactored to support batch stream file ingestion so that it is possible to process multiple stream files in one transaction. This will help pave the way for future enhancements like improving historical synchronization times.

The database saw a number of improvements including new setup documentation with recommendations for how to configure the database. Our Citus deployment had some notable additions including a huge improvement in performance by adjusting its resource configuration. The Stackgres version was upgraded to 1.8 and ZFS to 2.4.1. The entity stake calculation was optimized for Citus so it runs efficiently in a sharded database. Finally, database metrics were fixed so that partitioned tables are appropriately aggregated under the parent table name.

This release saw the implementation of HIP-844 Handling and externalization improvements for account nonce updates. This HIP resolve issues where the consensus nodes and the mirror nodes are account nonces are out of sync. The consensus nodes now sends the mirror node the up-to-date account nonce instead of the mirror node attempting to increment the nonce based upon its prior state.

There were two important changes to the database that helped to reduce its size substantially. The topic_message table primary key index was dropped in favor of relying upon a similar index on the transaction table. This simple change shaved 800 GiB off the mainnet database. The staking reward calculation performance was improved to only write accounts that elected to receive rewards. This reduces the staking reward calculation runtime from 47 minutes down to less than 2 minutes. A migration also removes the existing staking rows that did not have a staking reward election, shrinking those tables by 155 GiB. Note that to realize these disks savings mirror node operators will need to manually perform a full vacuum on the entity_stake and entity_stake_history tables. So in total the size of the mirror node database was reduced by almost 1 TB this release!

There was quite a bit of technical debt paid down in this release. We've removed support for the event file format from the importer. This format was never fully implemented in the mirror node, didn't support the latest version, and no user interest in this data was expressed during its 4 years of existence. The acceptance tests were refactored to use the OpenAPI generated models, ensuring we dogfood our own API specification. The brittle MockPool tests were removed in favor of additional coverage in other, easier to maintain tests. The REST API tests now uses the correct read only user and common database setup that the other modules use. Finally, the unused RestoreClientIntegrationTest and associated test images were removed.

Our Citus deployment saw a number of improvements. Performance was optimized for hash insertions by reducing the shard count for hash tables. Entity upserts saw improvement by increasing the number of CPU resources to the database. Finally, the transactions list and accounts by ID endpoints saw their read performance improved for Citus.

This release sees some incremental changes to the REST API. The REST API now supports a RFC5988 compliant Link header in its response as an alternative to the links.nextin the response body. Either link can now be used for pagination, but the Link header provides a standard approach that's supported by more tools. The /api/v1/accounts/{id}?timestamp endpoint now shows historically accurate staking information in its response so that users can view their past pending rewards. The timestamp in the response of the /api/v1/tokens/{id}/balances endpoint is now more accurate by reflecting the max balance timestamp of the tokens in its response.

The helm chart was verified to be compatible with Kubernetes 1.28 and saw its dependencies all bumped to the latest release. The new rest-java module was converted from WebFlux to servlets with virtual threads. This should increase its scalability once we implement HIP-857 NFT allowance REST API in a future relase. Some internal refactoring of BatchEntityListener to BatchPublisher will enable future improvements to historical syncing and batch processing.

The /api/v1/contracts/call endpoint saw a lot of important bug fixes this release. Support for historical blocks should be complete with some remaining bugs ironed out. The supported operations documentation was updated to reflect this increased level of compatibility.

With a lot of the developers taking some time off for the holiday season, this release is a bit smaller than normal but still contains some important changes. The previewnet and testnet bootstrap address books were updated to reflect the current state of the network. The default volume size for Loki was increased from 100 GB to 250 GB to account for increasing amounts of log activity. The processing of EthereumTransaction was made more resilient so that the importer does not halt if encounters a badly encoded transaction. Finally, a memory leak in the REST API should greatly reduce out of memory errors and improve request throughput.

To improve ingest performance of entity tables when used with a distributed SQL database we introduced a new temporary database schema. This schema is used to hold the temporary data inserted when processing entities from a record file. Previously this information was added to temporary tables created within the transaction scope, but these temporary tables could not be made distributed in Citus. With the temporary schema, this information can now be distributed appropriately to ensure optimal ingest performance. This change does require manual DDL statements be ran before the next upgrade (see next section).

Breaking Changes

As previously mentioned, a new database schema was introduced to handle the processing of upsertable entities. This change doesn't require any manual steps for new operators that use one of our initialization scripts or helm charts to configure the database. However, existing operators upgrading to 0.96.0 or later are required to create the schema by configuring and executing a script before the upgrade.

PGHOST= ./init-temp-schema.sh

Another breaking change concerns operators using our hedera-mirror-common chart. The aforementioned Loki volume size increase was made to the embedded PersistentVolumeClaim on the Loki StatefulSet. Kubernetes does not allow changes to this immutable field so to workaround the StatefulSet will need to be manually deleted for the upgrade of the common chart.

This release saw the Java components upgraded to use Java 21. In a future release, we will explore the new language features in 21 like virtual threads to unlock additional scalability. Some technical debt items were tackled including removing redundant test configuration by creating a common test hierarchy. Explicit @Autowired annotations on test constructors were removed, reducing boilerplate. Finally, various classes were renamed to align to our naming standards including the removal of the Mirror prefix from classes that were not used across modules.

HIP-584 EVM archive node for historical blocks saw some major additions including initial support for historical blocks. EVM Configuration is now loaded based upon block number instead of always utilizing the latest EVM. This ensures that /api/v1/contracts/call simulates the execution as it would've been on consensus nodes at that point in time. Database queries were adapted to work with timestamp filters to allow for returning historical block information.

Our distributed database effort saw some notable improvements including upgrading the version of Citus to 12.1. PostgreSQL 16 support was tested confirming compatibility with both regular PostgreSQL and Citus. Both /api/v1/topics/{id}/messages/{sequenceNumber} and /api/v1/topics/{id}/messages saw optimizations implemented when used with Citus.


If you're compiling locally, ensure you have upgraded to Java 21 in your terminal and IDE. For MacOS, we recommend using SDKMAN! to manage Java versions so that upgrading is as simple as sdk install java 21-tem. If you're using a custom Dockerfile ensure it is also updated to Java 21. We recommend Eclipse Temurin as the base image for our Java components.

Provides an important fix to pending reward calculation that regressed due to the balance deduplication work. The database migration for this will take approximately 17 minutes on mainnet.

This release is mainly a bug fix release along with some minor technical debt items. A new Helm chart for the new REST Java module was added in anticipation of future work to support new APIs in Java only instead of the current JavaScript based approach. Support for Elasticsearch metrics export was removed in favor of relying solely upon Prometheus. The /api/v1/contracts/call API some some notable bug fixes and performance improvements. Finally, some technical debt was tackled by refactoring SqlEntityListener to use a new ParserContext which should reduce its maintenance burden.

This release deduplicates balance history resulting in a major reduction in database size with no loss in balance granularity. The mainnet database saw a 45% reduction going from 50 TB to 28TB! This deduplication process works by not updating balance history if the account did not experience a balance change since the last snapshot. A migration to deduplicate historical balances runs asynchronously in the background and against mainnet state took about 24 hours to complete. Because the index was changed to reverse the order from (timestamp, account_id) to (account_id, timestamp), this required a large effort to rework queries in multiple REST APIs. Also, the balance tables are now partitioned and this meant changes in our database metrics to properly aggregate child tables on their parent name.

HIP-584 continues to chug along with multiple bug fixes and optimizations. Changing per request objects to be singletons resulted in a large decrease in memory and CPU usage, allowing more concurrent requests to be handled. Web3 k6 tests were hooked into our automated performance testing to ensure they run every release to ensure no regressions. Finally, support for historical blocks made progress with more of the plumbing put in place to process non-latest blocks.

A new cluster database health check was added to the monitor to provide proper failover in multi-cluster deployments. The local file stream provider now allows for input files to be grouped by date for faster processing when the directory contains millions of files. This is a step towards a faster historical syncing mode. Finally, REST API queries were optimized for Citus deployments so that they could reach parity with PostgreSQL.

HIP-584 Mirror EVM Archive node saw further refinements in this release. Memory usage was optimized by making most classes stateless and leveraging ThreadLocal where appropriate. Work continues on making /api/v1/contracts/call support historical blocks with lower level support for historical contract state, account, and contract information added. Additional test coverage for estimate gas was introduced to compare gas estimation is close to the actual gas used via HAPI. Finally, an issue with the blockhash operation returning 0x0 was resolved.

We added an option to deduplicate account and token balance data for Citus that can dramatically reduce the size of the balance tables. Balance tables currently consume 50% of the database. In the next release, we will bring this capability to regular PostgreSQL to realize those cost savings there as well. We now no longer update the token history for supply change operations like mint, burn, or wipe thus reducing the amount of data in this table.

This release adds support for ad-hoc transaction filters using the Spring Expression Language (SpEL). SpEL filters can be used for both including or excluding transactions from being persisted to the database. Previous filtering capability allowed mirror node operators to include or exclude certain entity IDs or transaction types, but if they needed something more custom they were out of luck. SpEL itself is pretty powerful and allows access to any bean or class on the classpath, so to reduce the attack surface we limit it to only allow filtering on the TransactionBody and the TransactionRecord contained within the record file. See the docs for additional details and examples. Below is an example that only includes transactions with certain memos:


Monitoring saw improvements this release with newly added metrics for the size of table and indexes on disk to help track the growing size of the database. Likewise, new cache metrics were implemented to monitor the cache hit rate and size. Dashboards were updated to visualize these new metrics.

HIP-584 EVM archive node saw support for block.prevrandao implemented. Also, support for pending, safe, and finalized block types were added with all three being equivalent to latest since Hedera's blocks are always final. Work has started on historical support for /api/v1/contracts/call so that specific blocks in the past can be queried. This release saw the lower level queries for token balance implemented.

HIP-794 Sunset account balance saw a couple of remaining items completed. The balance timestamp that was added in v0.89.0 was put to use to provide more accurate timestamps for the accounts and balances REST API. Finally, the reconciliation job was disabled since it doesn't make sense to reconcile from balance data that mirror node generates itself.

This release was mainly focused on testing and bug fixes. Acceptance tests saw a number of improvements including a reduction in overall costs by caching contract creation used in multiple tests. Acceptance tests were added to verify support for HIP-786 staking properties in network stake REST API. An issue with exchange rates varying in different environments was solved by querying the exchange rate REST API and using that to calculate fees to HAPI. The importer had an option added to fail on recoverable errors to find record stream issues earlier in the lifecycle.

HIP-786 adds support for enriched staking metadata exports to the record stream for use by downstream systems. The mirror node now ingests the new max_stake_rewarded, max_total_reward, reserved_staking_rewards, reward_balance_threshold, and unreserved_staking_reward_balance fields and persists them to the database. The REST API has been updated to expose this data via /api/v1/network/stake.

HIP-794 Sunsetting Balance File saw further refinements in this release. The mirror node now captures the consensus timestamp at which the balance was updated for both accounts and token relationship. This information will be used in the future to provide more accurate balance timestamps in the API and to deduplicate the balance information. Entity balance tracking and migration was enabled in the Rosetta API. Finally, we now track the balance of all entity types and not just accounts and contracts.

HIP-584 Mirror EVM Archive node continues to improve with the addition of support for the PRNG system contract. Missing Besu internal precompiles for the Istanbul release are now properly registered. A lot of new tests were added in the form of integration, acceptance, and performance tests.

There were a number of technical debt items addressed in this release. The importer component saw noticeable improvements in CPU and memory usage at 10,000 transactions per second. It now uses about 50% less memory and 33% less CPU. The Log4j2 logging framework was replaced with Logback to provide a path to compiling to native code and to simplify configuration. The EntityId saw its final improvement with the addition of a cache to reduce allocating temporary immutable objects. Tests were standardized to use the simpler and logging framework agnostic OutputCaptureExtension. Finally, we researched approaches to parallel transaction insertion and saw a path forward for additional ingest scalability.

This release contains support for HIP-794 Sunsetting Account Balance File. Consensus nodes will soon stop generating account balance files every 15 minutes due to the growing number of accounts making this operation unsustainable. To fill in the gaps, mirror nodes will now generate balance snapshot information from the record stream. This change will be transparent to end users and operators alike since the same data will be returned by the various APIs. For now, we're generating synthetic account_balance_file rows (not files) until we can remove the reliance on this table everywhere. In this release, we updated the accounts by ID, balance, and network supply REST APIs to not depend upon this table. Entity stake calculation and a fungible token migration were updated similarly. The next release will see further work in this area.

HIP-584 saw the exchange rate precompiles tinycentsToTinybars and tinybarsToTinycents implemented. Also added was support for the HTS redirectForToken precompile. But the main focus was on testing and bug fixes with a large number of them squashed in this release.

There was good amount of technical debt addressed in 0.88. For starters, we have a new hedera-mirror-rest-java module that is intended to contain new or existing REST APIs converted from JavaScript. By creating any new REST APIs in Java and slowly converting existing APIs to Java we can improve the quality of this area of the codebase and promoting code reuse with the other modules. A community member helped us to remove the deprecated Spring Cloud Kubernetes property spring.cloud.kubernetes.enabled since it was no longer used anyway. We also took the time to remove unused Flyway placeholders properties and eliminate code redundancy in web3 acceptance tests. Finally, we removed the type field from the widely used EntityId in the codebase and eliminated the unnecessary AssessedCustomFeeWrapper.

This release wraps up the initiative to ensure we capture all changes to Hedera entities. One of the oldest tickets in the repository going back to 2019 was completed, finally persisting the FreezeTransaction details to the database. There's a new option to store the raw TransactionRecord protobuf bytes that is set to off by default. The custom fee table was split into separate main and history tables for consistency with other data and improved querying efficiency.

An asynchronous database migration was added to efficiently update every account's crypto allowance amount after support for live allowance tracking was implemented in the last release. Furthermore, new crypto and fungible acceptance tests verify the live allowance tracking works correctly. Finally, we now rerun conditional migrations that would historically run only on initial startup. For migrations like balance initialization this means we automatically correct account and token relationship balances after ingesting the first balance file. For other migrations, it means they are triggered automatically based upon a specific record file version being ingested.

The REST API had a couple of noticeable changes. We now show only active allowances in the /api/v1/accounts/{id}/allowances/crypto and /api/v1/accounts/{id}/allowances/tokens REST APIs, providing consistency with how consensus nodes return this data. The /api/v1/network/stake API saw a change in how its stake value is calculated by changing it to stake rewarded plus not rewarded.

HIP-584 EVM Archive Node saw a number of HederaTokenService precompiles implemented including allowance, getApproved, isApprovedForAll updateTokenExpiryInfo, updateTokenInfo, and updateTokenKeys. A large focus on testing resulted in increased integration and acceptance test coverage. The extra coverage resulted in a number of bugs being found and squashed, improving the reliability of /api/v1/contracts/call.

A lot of work went into the operations side of things as well. A good number of metrics and Grafana dashboards saw cleanup and improvements to aid in production monitoring. All chart dependencies saw version bumps and configuration adjustments to bring them up to date. Kubernetes 1.27 compatibility was confirmed as a deployment target while still ensuring backwards compatibility with prior Kubernetes versions. Compressed ZFS volume support now handles Kubernetes upgrades properly. Our Citus deployment saw an upgrade to Citus 12 with PostgreSQL 15. This release brings in the improvements we contributed upstream to Citus' create_time_partitions stored procedure so that it can support the bigint type that we use to store consensus timestamps. This allowed us to remove the pg_partman extension in favor of the native create_time_partitions. The pg_cron extension was also removed in favor of a Java-based scheduled service running on the importer.

There was a ton of progress towards our goal capturing all entity changes. This release adds the highly requested feature of tracking the remaining hbar and fungible token allowances and showing it via the amount field on the REST API. Importantly, this tracking only applies to new or updated allowances. Existing allowances will see their remaining allowance adjusted appropriately in the next release.

Traditionally, the mirror node has only stored the aggregated transfers from the transaction record. Now in addition we store the itemized transfers from the transaction body by default and embed it within the transaction table. For partial mirror nodes, we now create entities during balance initialization. This means even if a mirror node starts up now this migration can be rerun to create every account and contract with accurate balance information. In the next release, we'll extend this to automatically rerun this migration when processing the first account balance file.

Finally, we added an entity_transaction join table to start tracking all entities associated with a transaction. This will enable us provide a better transaction search experience and find all transactions associated with an entity. This functionality is disabled in this release as we iterate on it to make it performant.

Support for Ethereum transaction type 1 as specified in EIP-2930 is now available. Previously only legacy and type 2 Ethereum transactions were supported. The new EIP-2930 transactions can be sent either directly to HAPI via an EthereumTransaction or via the JSON-RPC Relay.

HIP-584 EVM Archive node saw a large number of precompiles implemented. This includes all of the following:

  • approve

  • approveNFT

  • associateToken

  • associateTokens

  • burnToken

  • createFungibleToken

  • createFungibleTokenWithCustomFees

  • createNonFungibleToken

  • createNonFungibleTokenWithCustomFees

  • deleteToken

  • freezeToken

  • pauseToken

  • setApprovalForAll

  • transferFrom

  • transferFromNFT

  • transferNFT

  • transferNFTs

  • transferToken

  • transferTokens

  • unfreezeToken

  • unpauseToken

With the recent testnet reset that occurred on 2023-07-27, a new cloud storage bucket was created to store the stream files generated by the consensus nodes. This release will now use that updated bucket name by default when the network is set to testnet.

There were a few optimizations done specifically for the JSON-RPC Relay in this release that other users might also find useful. The /api/v1/accounts/idOrAddress REST API now supports an optional transactions query parameter that when set to false will omit the list of nested transactions. It defaults to true to match the previous behavior. If you're not using the transactions from this API please consider setting it to false to reduce the amount of data returned and provide an improved response time for your queries. Additionally, the /api/v1/contracts/results REST API was updated to include more fields to match the detailed results returned from /api/v1/contracts/results/{id}.

HIP-584 EVM Archive Node is adding functionality at a steady pace. This release adds support for the Ethereum Shanghai EVM version that adds a new PUSH0 opcode. Estimate gas calls that were failing for contract creates over 6 KB were fixed. Much of the focus was on implementing various precompiles including: approve allowance, burn, create, delete allowance, dissociate, grant KYC, revoke KYC, and wipe.

Making progress on capturing all state changes, we now keep a history of an account's daily entity stake. In the future, this information will be used to provide an accurate staked amount when looking up an account's historical information using /api/v1/accounts/{id}?timestamp=.

There were a lot of other bug fixes and small improvements. Please see the release notes below for the full list.

This release contains support for HIP-729 contract nonce externalization. Consensus nodes now track and externalized contract nonce information in the record stream. A contract's nonce increases whenever it creates another contract. Mirror nodes persist this data and expose a contract's nonce on the /api/v1/contracts and /api/v1/contracts/{id} REST APIs.

HIP-584 EVM archive node continues to make progress. This release contains full support for contract state reads for both precompiled and non-precompile functions. Support was added for contract state modifications for non-precompile functions with the exception of lazy account creation.

Our goal of capturing all entity changes saw further refinements. Token information saw a history table be added to keep track of any changes to the token metadata over time. Also, we now use the real-time token balance in the token balances REST API.



In this release we made the highly requested change to show the list of NFT transfers on the transactions list REST API. Originally, only the /api/v1/transactions/{id} showed the list of nft_transfers due to performance concerns with joining on another large table for such a heavily used and heavyweight API. To show this information while staying performant, we had to denormalize the NFT transfer information to nest it under the transaction table as a JSONB column. This avoids an extra join and allows us to return the given information with the existing query.

The mirror node is focused on tracking all possible changes to Hedera entities over time. To that end a NFT history table was created to capture all possible changes to a NFT over time. In addition to persisting this data, we're also exposing more of this historical information via the API. Now when the timestamp parameter is supplied on the /api/v1/accounts/{id} endpoint it will show the historical view of that account. Previously, the parameter would only be used for displaying the list of transactions at the given time. Expect additional improvements around historical entity information in the next release.

HIP-584 continues to make strides every release. This release focused on improving precompile support for /api/v1/contracts/call. There is now support for the CREATE2 opcode along with non-static contract state reads for precompile and non-precompile functions. Non-static contract modifications for non-precompile functions (excluding lazy account creation) was also worked on. Finally, acceptance test coverage was greatly increased and a number of bugs were addressed.

This release adds integration with the Stackgres Operator to provide a highly available Citus deployment. Stackgres is an established Kubernetes operator for PostgreSQL and their support for the Citus extension has made it easy to provide a production ready deployment without depending upon expensive, cloud-specific managed database services. This along with the ZFS volume compression we added in a previous release should greatly reduce the total cost of running a mirror node while providing horizontal scalability.


Expect upgrading to take about an hour due to the large NFT transfer migration in this release. As always, it's recommended upgrades be completed in a staging environment first (e.g. a red/black deployment) to allow for deployment verification and reduce downtime before being opened up to customer traffic.



HIP-679 saw its initial work completed in this release to support a restructured bucket. The importer now supports the existing account ID-based bucket path along with a future node ID-based bucket path. It also adds a path type property that can automatically switch between the two so the transition between the two formats is transparent to mirror node operators. For now, the default path type will stay as account ID until node ID becomes a reality to reduce the S3 costs.

HIP-584 Mirror EVM Archive Node saw a large number of improvements to bring it closer to parity with consensus nodes. Stacked state and database accessors were integrated to allow for smarts contracts to change state temporarily. An operation tracer was added to make it easier to debug smart contracts in an environment.

Finally, a topic message lookup table was added to optimize finding topic messages on distributed databases.



This release comes with a number of improvements to support the JSON-RPC Relay. We now support alias and EVM address lookups for the account.id parameter on the balances endpoint. We optimized the transaction nonce filtering in /api/v1/contracts/{id}/results by denormalizing the data. Finally, an issue with empty function_parameters in /api/v1/contracts/results/{id} response was addressed.

The other big item we worked on was support for volume level compression with Citus. We know that the type of time series data the mirror node stores would be highly compressible and we wanted to use that to our advantage to both reduce increasing storage costs and improve read/write performance. PostgreSQL supports a basic form of compression at the column level called TOAST, but it only takes effect for very large columns. Citus has compression when using their columnar storage access method, but we found it to be too slow for our needs. Since with Citus we knew we wouldn't be using a SaaS service we had more control over the database deployment, so we decided to experiment with Kubernetes volume compression. By creating custom Kubernetes node pools exclusively for Citus, we could install ZFS via the zfs-localpv and enable Zstandard compression on the database's underlying volume. The results were a 3.6x compression ratio with zero loss in performance. To put into perspective, that means the current mainnet database size of 17TB could be reduced to 4.7TB.

Other areas of improvement include improving documentation around disaster recovery efforts. This includes a runbook on restoring a mirror node from backup. There's also a runbook on how to perform local stream file verification. Acceptance tests have been previously integrated into the automated deployment process but suffered from a long execution time mainly due to using Gradle to download dependencies at runtime. We containerized the acceptance tests so the dependencies are downloaded at build time reducing runtime by 3-4x.



Work continues on HIP-584 with this release the first to support non-static contract state reads for non-precompile functions. Please see the Swagger UI table for /api/v1/contracts/call for a breakdown of which functionality is supported in what release. More estimate gas functionality was copied from services code to make progress on estimation. A new stacked state frame functionality was added to be used in the future to support contract writes and cached reads.

The Spotless code formatting tool was used to format the entire codebase to be consistent. A git commit hook was added to ensure any new changes stays consistent and developers can focus on what matters.

Finally, there were a large number of bug fixes and performance improvements. See below for the full details.



HIP-584 EVM archive node saw further progress this release with a focus on testing and establishing the foundation for estimate gas functionality in the next release. While consensus nodes undergo a modularization effort that will pay dividends down the road, the archive node needs functionality for estimate gas before that process could be completed. To make progress on HIP-584, the necessary EVM logic was temporarily copied from consensus nodes into the mirror node web3 module. A large focus was placed on increasing acceptance test coverage for contract call with precompiles.

Users writing dApps want to be able to monitor for token approval and transfer events. HAPI transactions like CryptoTransfer, CryptoApproveAllowance, CryptoDeleteAllowance, TokenMint, TokenWipe, and TokenBurn do not emit events that could be captured by monitoring tools like The Graph since they’re executed outside the EVM. To address, the mirror node now generates synthetic contract log events for these non-EVM HAPI transactions.

A new subscription API was designed for HIP-668 GraphQL API. Once it's implemented in a future release, the new contract log subscription will stream contract events to clients via a WebSocket connection.

For our Citus database transition, PostgreSQL 15 compatibility was verified and made the default for this v2 schema. The lookup of historical balance information via /api/v1/balances?timestamp= was optimized for sharded databases so it stays performant. Performance testing showed a decrease in shard count could greatly improve performance so we lowered the number of shards from 32 to 16. This testing also allowed us to provide an initial recommended resource configuration for the Citus deployment.

There was a large focus on test improvements in this release. In addition to the aforementioned HIP-584 test coverage, we also optimized the acceptance tests to reduce the overall test duration in Kubernetes by half without reducing coverage. The acceptance test logs were cleaned up to reduce unnecessary log statements and standardize its output. The hbar balance used by the tests now is logged at the end of test execution. Acceptance tests for hollow account creation were added. We now generate multi-platform snapshot images from the main branch for testing with local node. Testkube configuration was enhanced to make it more configurable. Finally, all Java test compiler warnings were fixed and will now fail the build if any future warnings occur.

Known Issues

There is a bug introduced by #5776 that causes the importer to fail on startup. It's recommended to hold off on upgrading to v0.79.0 until we can address this in a v0.79.1. Alternatively, it can be worked around by disabling the faulty migration by setting hedera.mirror.importer.migration.syntheticTokenAllowanceOwnerMigration.enabled=false.



HIP-584 Mirror Evm Archive Node now has token precompile support. This was the last major piece of functionality needed for the /api/v1/contracts/call to be considered eth_call equivalent. The new API was added to the REST API's OpenAPI documentation so that it appears on our Swagger UI. A number of performance optimizations were worked on to make it scalable as well as various test improvements to verify its correctness. Various bugs were addressed including the proper handling of reverts. In the next few releases, we plan to fine tune contract call and implement contract gas estimation.

A large focus was put on performance and resiliency this release. On the performance front, we've optimized the list schedules REST API to be scalable on Citus. Performance tests can now trigger automatically via TestKube once the helm tests complete. Those same k6 performance tests were enhanced to automatically pick appropriate configuration values specific to the environment. The transaction hash table was partitioned and the ingest process made to insert hashes in parallel. This change dramatically speeds up the time to insert the optional transaction hashes. Similarly, an option was added to control which transaction types should cause a hash insertion.

On the resiliency front, the importer component was analyzed for any code paths that may cause record file processing to halt due to bad input from consensus nodes. Any such code was made to handle the error, log/notify, and move on to the next transaction. This change makes the mirror node ingestion more resilient and moves toward preferring availability over correctness. Partial mirror nodes that might become stuck due to having an incomplete address book can now continue to ingest with a new consensusMode property and logic. Partial mirror nodes will now also be able to have a corrected account and token balance even if the entity was missing a deleted flag. Finally, we were able to complete a longstanding refactoring effort to move all transaction specific logic to individual transaction handlers and fixed a number of bugs in the process.

There were a few important bugs fixed in this release that are worth noting. A fix was put in place to correct inaccurate fungible token total supply. Additionally, NFTs for deleted tokens no longer appear as active in the REST API.



This release fixes the tracking of NFT balances. Historically, these came from the balance file sent by the consensus nodes every 15 minutes. When we started tracking the live fungible token balances and moved away from using this balance file we unfortunately broke the NFT balance calculation. We not only fixed the issue but went ahead and took the time to track the up-to-date NFT balance as well.

The /api/v1/contracts/{id}/state REST API shows the current state of a contract's slot values. Users requested the ability to query for the key/value pairs for their contract at an arbitrary point in the past. To address, we now expose a timestamp query parameter that will get the historical contract state. This allows the JSON-RPC relay to offer a proper eth_getStorageAt with support for historical blocks.

HIP-584 continues to make progress. Quite a few bugs were squashed including handling reverts and populating the revert reason and raw data. Performance tests were added to k6 to load test contract calls with token precompiles.



The new /api/v1/contracts/call REST API as specified in HIP-584 is finally ready for initial production use. This release adds support for rate limiting the API with an initial value of 100 requests per second per instance. Tags were added to the gas per second metric to indicate if the request was a call, an estimate, or resulted in an error for increased observability. Various bug fixes were also addressed.

HIP-668 GraphQL API was added to our deployment with the addition of a new helm chart for this API. This will allow for initial use of the API in all environments with the understanding that it's still very much alpha and subject to change.

We made a lot of headway on our Citus integration. Citus was upgraded to 11.2 which showed a nice 15-20% performance boost for a number of query patterns. We optimized the contract results APIs performance by distributing based upon contract ID instead of payer account. Search for a transaction by its hash on Citus was improved by adding the distribution column to the query and limiting the results to a timestamp range. The search for an account by its ID also saw improvements on Citus.

Breaking Changes

The Helm charts contain some breaking changes to be aware of. The hedera-mirror wrapper chart enables the new hedera-mirror-graphql sub-chart by default. The GraphQL deployment requires a new mirror_graphql database user to exist for it to successfully start up. You can create the user by logging into the database as owner and executing the following SQL query:

create user mirror_graphql with login password 'password' in role readonly;

If you're using the embedded PostgreSQL sub-chart (which we don't recommend for production use), then you'll have to delete its StatefulSet before upgrading due to a major bump in its chart version.

The hedera-mirror-common chart had all of its components upgraded to new major versions that include breaking changes. If you're using this chart, run the following commands before upgrading:

kubectl delete daemonset mirror-prometheus-node-exporter
kubectl delete daemonset mirror-traefik
kubectl delete statefulset mirror-loki
kubectl delete ingressroute mirror-traefik-dashboard
kubectl apply --server-side --force-conflicts=true -f https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/v0.63.0/example/prometheus-operator-crd/monitoring.coreos.com_alertmanagerconfigs.yaml
kubectl apply --server-side --force-conflicts=true -f https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/v0.63.0/example/prometheus-operator-crd/monitoring.coreos.com_alertmanagers.yaml
kubectl apply --server-side --force-conflicts=true -f https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/v0.63.0/example/prometheus-operator-crd/monitoring.coreos.com_podmonitors.yaml
kubectl apply --server-side --force-conflicts=true -f https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/v0.63.0/example/prometheus-operator-crd/monitoring.coreos.com_probes.yaml
kubectl apply --server-side --force-conflicts=true -f https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/v0.63.0/example/prometheus-operator-crd/monitoring.coreos.com_prometheuses.yaml
kubectl apply --server-side --force-conflicts=true -f https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/v0.63.0/example/prometheus-operator-crd/monitoring.coreos.com_prometheusrules.yaml
kubectl apply --server-side --force-conflicts=true -f https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/v0.63.0/example/prometheus-operator-crd/monitoring.coreos.com_servicemonitors.yaml
kubectl apply --server-side --force-conflicts=true -f https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/v0.63.0/example/prometheus-operator-crd/monitoring.coreos.com_thanosrulers.yaml


Work continues on HIP-584 to get it closer to production ready for simple contract calls. Caching logic was added to the repository layer to optimize its capability along with performance tests to verify those improvements. A metric was added to track the gas per second being used along with various other bug fixes.

The monitor API and dashboard used internally for observing our production systems was containerized. Additionally, it was integrated into the Helm chart and invoked as part of the Helm tests to ensure the deployment is verified.

Finally, there were a number of query optimizations as part of our Citus effort.



This release switches the testnet bucket to the new one created for the testnet reset that occurred on January 26, 2023. It also updates the address book to reflect the additional nodes added to testnet since the last reset. If you're running a testnet mirror node, please see the reset instructions for help getting your node updated.

In HIP-668, we propose adding a new mirror node GraphQL API and would greatly appreciate your feedback. In this release, a new GraphQL module with a simple account lookup query was added to provide the basis for future work on this HIP. In the next release, we will add the automated deployment of this module to all environments. It is considered an alpha API subject to breaking changes at any time, so it's not recommended to depend upon for production use. This has been made explicit by using /graphql/alpha in its URL.

Finally, a number of query optimizations were implemented for Citus while ensuring it doesn't cause regressions with the existing database. This will continue to be the focus of the next few releases.



This release is the first one with support for HIP-584 EVM Archive Node. HIP-584 allows mirror nodes to act as a read only EVM for free execution of smart contracts. This new feature is considered alpha with much of the work still to be implemented like support for precompiled contracts, gas estimation, etc. This functionality requires the mirror node to be configured to ingest the optional traceability sidecar files and it requires a network where those files are generated. Currently only previewnet has contract traceability enabled.

The testnet bucket name has been updated to the new bucket name after its recent quarterly reset. Likewise the bootstrap testnet address book was updated to reflect the additional testnet nodes that have been added since the previous reset. Mirror node operators running a testnet node should either manually populate the new bucket name or update to this release.

The remaining work targeted significant testing improvements and bug fixes. Our performance tests were expanded to all endpoints to catch issues earlier in the lifecycle. Additional acceptance test coverage was added along with a number of fixes. CI stability has greatly improved with a focus on fixing flaky tests. Code smells as reported by Sonar were reduced to only a handful and in the next release reduced all the way down to zero. Finally, we merged work that enables nightly performance testing in our integration and mainnet staging environments via TestKube.



This release is a smaller release as most of the team took time off for the holidays. Still, we managed to implement HIP-583 Expand alias support in CryptoCreate & CryptoTransfer Transactions. We now allow hollow accounts to be later finalized into a contract when it is fully created.

We also worked on adding support for Testkube. Testkube allows us to automate our testing in Kubernetes environments by triggering tests based upon various conditions. Specifically, it will be used to run nightly performance regression tests against a mainnet staging environment to ensure our API performance doesn't regress. We'll continue to expand on this automated testing in future releases.

There were also a number of bug fixes in this release, mainly focused on fixing our release process after the switch from Maven to Gradle in the last release.


As of this release, all account and token balances in the REST API will reflect their real time balance information. Historically, the mirror node has relied upon the balance file uploaded by consensus nodes every 15 minutes for its balance information. We've been working towards this milestone for many releases gradually rolling out real-time balance tracking to more entities and more APIs. This release completes this migration with the addition of real time token balances to both the accounts and the balances REST APIs.

The mirror node now implements support for HIP-583 alias on CryptoCreate transactions. With this, clients can directly set an alias during account creation instead of relying upon the implicit auto-account creation during transfers. The mirror node respects this explicit alias along with the new explicit EVM address in both CryptoCreate or the TransactionRecord. This avoids the brittle EVM address calculation on the mirror node that has caused us some trouble in the past.

This release completes the migration from Maven to Gradle for our build process. A lot of work has been put into the new build to improve its performance and stability both locally and in continuous integration (CI). GitHub Actions workflows have been consolidated from one workflow per module to a single Gradle build workflow with a matrix strategy running them in parallel for each module and database schema. This greatly simplifies the workflow configuration making it easier to maintain and debug.

We continue to make progress on our Citus exploration. The v2 schema for Citus now does timestamp based partitioning of data and automates this process via pg_cron. A Citus specific environment was created and we're currently conducting performance tests against it at scale to verify it meets our requirements.

This release adds automation to keep our GCP Marketplace application up to date with each release. While not fully automatic due to the manual nature of Marketplace version submission, now any new production tag will trigger the generation and verification of the marketplace images.

This was a big release and there were a lot of other various improvements and fixes. See the full release note below.



As part of HIP-406, the mirror node is adding a new account staking rewards REST API. This API will show the staking rewards paid to an account over time. The mirror node now also shows staking reward transfers in the transaction REST APIs (e.g. /api/v1/transactions, /api/v1/transactions/{id}, and the list of transactions in /api/v1/accounts/{id}). This can be useful to show which transaction involving your account after the staking period ended triggered the lazy reward payout.

GET /api/v1/accounts/{id}/rewards

  "rewards": [{
    "account_id": "0.0.1000",
    "amount": 10,
    "timestamp": "123456789.000000001"
  "links": {
    "next": null

The REST API saw further improvements outside of staking. The accounts REST APIs now show a calculated expiration timestamp to mirror the HAPI CryptoGetInfo query. Previously expiration timestamp only shows up if explicitly sent via a transaction that supports it (mainly update transactions). Now if it's null we calculate it as created_timestamp.seconds + auto_renew_period. Every contract results endpoint was updated to include an address field for the EVM address of the created contract.

This release makes progress on being able to execute contract calls on the mirror node as outlined in HIP-584. A lot of the groundwork is being laid that will be further refined in upcoming releases.\



As noted in previous releases, HIP-367 is deprecating the token relationship information returned from HAPI queries. In this release, its mirror node replacement is now feature complete. We now track and show the current fungible token balance in the token relationships API instead of relying upon the 15 minute balance export from consensus nodes. In a future release, the accounts and balances REST APIs will be updated to show the current fungible token balance.

The importer component now supports a local file stream provider. This allows it to read stream files from a local directory instead of just the S3-compatible providers it supported previously. This mode is useful for debugging stream files received out of band or for reducing complexity and latency in a local node setup. To try it out, set hedera.mirror.importer.downloader.cloudProvider=LOCAL and populate the hedera.mirror.importer.dataPath/streams folder with the same file structure as the cloud buckets.

We now show a contract's CREATE2 EVM address in the contract logs REST APIs. Previously, we would convert the Hedera shard.realm.num to a 20-byte EVM address but this did not always reflect the true EVM address of the contract. Using the CREATE2 form of the EVM address provides increased Ethereum compatibility.

We continue to make progress on converting our build process to Gradle. This release adds a Golang Gradle plugin to download the Go SDK and use it to build and test the Rosetta module.



Besides the usual round of bug fixes, this release focuses on some internal enhancements to lay the groundwork for some upcoming features. We now track and persist the current fungible token balance in the database. This information is not yet exposed on any API but will be rolled out to the token relationships, accounts and balances REST APIs in the near future.

We're continuing our work towards CitusDB as a possible database replacement in this release by adding distribution columns and fixing our v2 schema tests.

Finally, we implemented initial Gradle support to improve build times and provide a better developer experience. Initial testing shows build and test times reduced from 8 minutes overall down to 2 minutes. The Gradle and Maven build scripts will be maintained concurrently for a few releases until we can ensure the Gradle build reaches feature parity with Maven.



HIP-367 deprecated the list of token balances for an account returned via HAPI. The mirror node has been working on its replacement for a few releases by storing the current account balance, combining contract and entity tables, and adding a history table for token_account. This work has paved the way for a new token relationships REST API that will list all fungible and non-fungible tokens associated with a particular account. This API also returns some metadata like balance, KYC status, freeze status, and whether it's an automatic association or not. Currently the fungible token balance being returned is from the 15 minute account balance file. We are actively working towards tracking the real-time fungible token balance and it will be updated to reflect that in a future release.

GET /api/v1/accounts/{id}/tokens

  "tokens": [{
    "automatic_association": true,
    "balance": 15,
    "created_timestamp": "1234567890.000000002",
    "freeze_status": "UNFROZEN",
    "kyc_status": "GRANTED",
    "token_id": "0.0.1135"
  "links": {
    "next": null

HIP-513 details how smart contract traceability information from consensus nodes is made available via sidecar files. The contract state changes within the sidecar are persisted by mirror nodes and made available on the contract results APIs. However, these state changes do not always reflect the full list of smart contract storage values since not all slots are modified during any particular contract invocation. We now persist a rolled up view of state changes to track the latest slot key/value pairs. This contract state information is now exposed via a new /api/v1/contracts/{id}/state REST API where id is either the shard.realm.num, realm.num, num, or a hex encoded EVM address of the smart contract.

GET /api/v1/contracts/{id}/state

  "state": [{
    "address": "0x0000000000000000000000000000000000001f41",
    "contract_id": "0.0.100",
    "slot": "0x0000000000000000000000000000000000000000000000000000000000000001",
    "timestamp": "1676540001.234390005",
    "value": "0x0000000000000000000000000000000000000000000000000000000000000010"
  "links": {
    "next": null

In a push for further decentralization, we now randomize node used to download data files after reaching consensus. Previously, the data structure we used generally caused us to use the first node returned in the verified list, which was usually 0.0.3. We now randomly pick a node until we can successfully download the stream file. We also internally changed all tables that used node account ID to use its node ID instead.

On the testing front, we enhanced various test and monitoring tools to add support for new APIs. We also added an acceptance test startup probe to delay the start of the tests until the network as a whole was healthy. This avoids the mirror node acceptance tests reporting a false positive when a long migration or startup process on the consensus or mirror nodes causes a delay.



Continuing our goal of having up to date balances everywhere, this release now shows the current hbar balance on the balances REST API. If you provide a timestamp parameter, it will fallback to the previous behavior and use the 15 minute balance file. This allows us to continue to provide a historical view of your balance over time, while also showing the latest balance if no specific time range is requested. Live fungible token balance is actively being worked on for an upcoming release.

Another big feature this release is support for cloud storage failover. The importer can now be configured with multiple S3 download sources and will iterate over each until one is successful. This makes the mirror node more decentralized and provides more resiliency in the face of cloud failure. The existing hedera.mirror.importer.downloader properties used to configure the cloudProvider, accessKey, secretKey, etc. will continue to be supported and inserted as the first entry in the sources list, but it's recommended to migrate your configuration to the newer format. Also in the downloader, we increased the downloader batch size to 100 to improve historical synchronization speed. A hedera.mirror.importer.downloader.sources.connectionTimeout property was added to avoid occasional connection errors.

        - backoff: 30s
          connectionTimeout: 10s
            accessKey: <redacted>
            secretKey: <redacted>
          maxConcurrency: 50
          projectId: myapp
          region: us-east-2
          type: GCP
          uri: https://storage.googleapis.com
        - credentials:
            accessKey: <redacted>
            secretKey: <redacted>
          type: S3

HIP-573 gives token creators the option to exempt all of their token’s fee collectors from a custom fee. This mirror node release adds support to persist this new all_collectors_are_exempt HAPI field and expose it via the /api/v1/tokens/{id} REST API.

An important characteristic of a mirror node is that anyone can run one and store only the data they care about. The mirror node has supported such capability for a few years now but the configuration syntax was a bit tricky to get correct. To address this shortcoming, we add some examples to the configuration documentation to clarify things. This entity filtering was historically limited to just create, update and delete operations on entities. We've now expanded this filtering to include payer account IDs and accounts or tokens involved in transfers.

Breaking Changes

As part of the S3 failover work, we made a number of changes to existing properties to streamline things and only support one property for all stream types. The hedera.mirror.importer.downloader.(balance|event|record).batchSize properties were removed in favor of a single, generic hedera.mirror.importer.downloader.batchSize. Likewise, the hedera.mirror.importer.downloader.(balance|event|record).threads properties were removed in favor of hedera.mirror.importer.downloader.threads. The hedera.mirror.importer.downloader.(balance|event|record).prefix properties were removed in favor of hardcoded configuration since there's never been a need to adjust these. If you're using any of these properties, please adjust your config accordingly.

If you're writing stream files to disk after downloading by enabling the writeFiles or writeSignatures properties, there is one other breaking change to be aware of. As part of our migration away from node account IDs, we changed the paths on disk to use the node ID as well. If you'd like to avoid having two directories for the same node please rename your local directories manually. For example, change ${dataDir}/recordstreams/record0.0.3 to ${dataDir}/recordstreams/record0.



The mirror node now calculates consensus using the staking weight of all the nodes as outlined in HIP-406. If staking is not yet activated, it falls back to the previous behavior of counting each node as 1/N weight where N is the number of consensus nodes running on the network. The /api/v1/accounts and /api/v1/accounts/{id}REST APIs now expose a pending_reward field that provides an estimate of the staking reward payout in tinybars as of the last staking period. The /api/v1/network/supply REST API updated its configured list of unreleased supply accounts to accurately reflect the separation of accounts done for staking purposes by Hedera.

This release implements the contract actions REST API detailed in HIP-513. An example of an actions payload is shown below. We added transaction_hash, transaction_index, block_hash and block_number fields to the contract logs REST APIs. This work was done to optimize the performance for the eth_getLogs JSON-RPC method used by the relay. Also for the relay, we now support lookup of non-Ethereum contract results by its 32 byte transaction hash.

GET /api/v1/contracts/results/0.0.5001-1676540001-234390005/actions

  "actions": [{
    "call_depth": 1,
    "call_type": "CALL",
    "call_operation_type": "CALL",
    "caller": "0.0.5001",
    "caller_type": "CONTRACT",
    "from": "0x0000000000000000000000000000000000001389",
    "timestamp": "1676540001.234390005",
    "gas": 1000,
    "gas_used": 900,
    "index": 1,
    "input": "0xabcd",
    "to": "0x70f2b2914a2a4b783faefb75f459a580616fcb5e",
    "recipient": "0.0.8001",
    "recipient_type": "CONTRACT",
    "result_data": "0x1234",
    "result_data_type": "OUTPUT",
    "value": 100
  "links": {
    "next": null

To support mirror node explorers being able to display the transaction that created an entity, we added a created_timestamp field to the accounts REST API.

The Rosetta module saw a large number of improvements this release. Rosetta now supports a transaction memo be returned in its metadata response. To improve performance of large blocks, Rosetta now limits the number of transactions in its block response. The importer balance reconciliation job was disabled in the Rosetta Docker image since Rosetta performs its own reconciliation process. There were other various fixes to the reconciliation process balance offset, charts testing failing for PRs from forked repos, and fixing a slow search block by hash query in rosetta.



In the last release, we began keeping track of the current balance of every account and contract instead of solely relying upon the balance file written every 15 minutes by consensus nodes. In this release, we now show this up-to-date balance on the /api/v1/accounts and /api/v1/accounts/{id} REST APIs in the existing balance field. Token balances and the balances REST API still shows the balance information from the 15 minute balance file. In a future release, we'll look at changing those to track the current balance.

As part of HIP-406, it details a pending reward calculation that can be used to estimate the reward payout between your last payout event and the staking period that just ended. The mirror node now does a similar calculation daily and will in a future release show this pending reward amount on the REST API.

The reconciliation job periodically runs and reconciles the balance files with the crypto transfers that occurred in the record files. This job allowed us to catch an issue with missing transactions for FAIL_INVALID crypto transfers that was fixed in hedera-services v0.27.7. This release contains the errata for the missing transactions that allows reconciliation to proceed successfully once again. It also saw performance improvements including a delay property to throttle its speed and added job status persistence so it doesn't restart from the beginning every time. A new remediationStrategy property provides a mechanism to continue after failure to aid in debugging multiple reconciliation errors.



This release adds a highly requested feature: the mirror node now tracks the current account balance. Previously, the mirror node would store balance information whose source was a balance file that consensus nodes generate and upload every 15 minutes. As a result, balance information was always behind by up to 15 minutes for active accounts. We were able to figure out a way to track this information at scale with SQL in this release. The next release will actually expose this up to date account balance information on both /api/v1/accounts or /api/v1/accounts/{id}. In future releases, will look at adding live balances to /api/v1/balances when no timestamp parameter is provided and track up to date token balances.

Work continues on HIP-513 Contract Traceability, with this release adding a few important items. Consensus nodes will, when first activating the sidecar mechanism, send migration records that includes all smart contract runtime bytecode and current storage values. The mirror node now supports receiving these special migration sidecars and updating its database with the migrated data. This paves the way for the mirror node to have the necessary information to execute smart contracts without modifying state in a future release. Also in this release we now show the contract initcode that was used to unsuccessfully create a smart contract in a new failed_initcode field in the contract result REST API.

The network supply REST API saw an update to adjust the unreleased supply accounts used to calculate the unreleased supply. This change was necessary as Hedera adjusts the treasury accounts for use with staking.



Mirror Node 0.62 saw HIP-406 staking related improvements to its REST API and partial support for HIP-513 contract traceability.

The /api/v1/network/nodes will now use the address book stake as a fallback when it has not seen any NodeStakeUpdate transactions on the network. This release also contains a new network stake REST API /api/v1/network/stake to show aggregate stake information common to all nodes:

  "max_staking_reward_rate_per_hbar": 17808,
  "node_reward_fee_fraction": 0.0,
  "stake_total": 35000000000000000,
  "staking_period": {
    "from": "1658774045.000000000",
    "to": "1658860445.000000000"
  "staking_period_duration": 1440,
  "staking_periods_stored": 365,
  "staking_reward_fee_fraction": 1.0,
  "staking_reward_rate": 100000000000,
  "staking_start_threshold": 25000000000000000

HIP-513 Smart Contract Traceability adds support for an optional sidecar to contain contract traceability information. In this release, the mirror node supports downloading and persisting contract state changes, contract initcode, contract runtime bytecode, and contract actions (AKA traces). The /api/v1/contracts/{id} REST API now shows the runtime bytecode for newly created contracts. The next release will support a sidecar migration that will populate contract state changes and bytecode for all existing contracts.

HIP-435 Record Stream V6 required changes to the state proof REST API in order to not break when V6 was enabled. With this release, the API was updated to support record files in the new v6 format.

The Rosetta API saw a few minor fixes and improvements. It now uses the Hedera network alias everywhere in the Rosetta server . It also fixes the issue that Rosetta did not support alias as the from address for crypto transfers. Additionally, the Rosetta sub_network_identifier was disabled since it was not needed.

There were a surprising number of technical debt improvements this release. The REST API and monitor API were both converted from CommonJS to ES6 modules, allowing us to finally upgrade some of our dependencies to the latest version. The REST API spec tests were organization into folders by endpoint and changed to use a single database container for the entire suite. On the importer, mutable contract information was merged into the entity table. The RecordItem constructor was removed everywhere in favor its builder method. Finally, we added parser performance tests to be able to generate large record files and stress test record file ingestion.

Breaking Changes

In a recent release, we added the stake_total field to the /api/v1/network/nodes API to show the aggregate stake of the network. With the addition of the new /api/v1/network/stake API, we now have a separate API to return aggregate staking information associated with the network. As such, we made the decision in this release to remove the stake_total field from the response of the /api/v1/network/nodes API to stay consistent. If you're using this field, please update your code to use the stake_total field in the /api/v1/network/stake API.



This release adds initial support for HIP-513 Smart Contract Traceability Extension. Contract traceability information is now available inside an optional sidecar file uploaded separately to cloud storage. Mirror node operators can choose whether to download this extra information by configuring the hedera.mirror.importer.parser.record.sidecar properties on the importer. By default, sidecar files will not be downloaded. Enabling it will permit contract state, actions, and bytecode data to be persisted by the mirror node. HIP-513 support is incomplete in this release and the next release will enable full persistence of all sidecar types.

The transactions REST API now supports multiple transactiontype query filters to simplify searches across types.

The version of the mirror node in GCP Marketplace was updated to v0.60.0. This required migration to the new GCP Producer Portal which should help streamline future version updates.

The monitor components saw an option added to retrieve the address book on startup. This avoids having to configure the list of nodes to monitor manually in pre-production environments and ensure the list of nodes is up to date. The monitor now uses OpenAPI generated models to dog food our OpenAPI schema. We also added an option to the monitor to set the max memo length property for published transactions.



The two big features of this release are support for a data retention period and HIP-351 pseudorandom number generation.

On public networks, mirror nodes can generate tens of gigabytes worth of data every day and this rate is only projected to increase. Mirror nodes now support an optional data retention period that is disabled by default. When enabled, the retention job purges historical data beyond a configured time period. By reducing the overall amount of data in the database it will reduce operational costs and improve read/write performance. Only insert-only data associated with balance or transaction data is deleted. Cumulative entity information like accounts, contracts, etc. are not deleted.

HIP-351 adds a pseudorandom number generator transaction. The mirror node now persists this PrngTransaction type including the pseudorandom number or the bytes it generates. A future release will expose this information on the REST API.

There were various other improvements in this release. Block numbers are now migrated to be consistent with other mirror nodes regardless of their configured start date when it receives the first v6 record file with the canonical block number from consensus nodes. We added the reward rate at the start of the staking period to the nodes REST API. Rosetta now shows fee crypto transfers operation type as FEE. Rosetta also shows account aliases as account addresses in Rosetta DATA API response.


The previous release saw support for the persistence of HIP-406 staking-related data. Staking persistence saw further fine-tuning in this release to adapt to changes in the NodeStakeUpdateTransaction protobuf. The decline_reward, staked_account_id, staked_node_id fields were added to /api/v1/accounts and /api/v1/accounts/{id} to show account-level staking properties. We also added staking related fields to the existing /api/v1/network/nodes REST API (see example below).

GET /api/v1/network/nodes

  "nodes": [
      "description": "address book 1",
      "file_id": "0.0.102",
      "max_stake": 50000,
      "memo": "0.0.4",
      "min_stake": 1000,
      "node_account_id": "0.0.4",
      "node_cert_hash": "0x01d...",
      "node_id": 1,
      "public_key": "0x4a...",
      "service_endpoints": [],
      "stake": 20000,
      "stake_not_rewarded": 19900,
      "stake_rewarded": 100,
      "stake_total": 100000,
      "staking_period": {
        "from": "1655164800.000000000",
        "to": "1655251200.000000000"
      "timestamp": {
        "from": "16552512001.000000000",
        "to": null
  "links": {
    "next": null

Support for the new record file v6 format as defined in HIP-435 was added in this release. Record file v6 adds block number as well as support for the new sidecar record files that carry detailed contract traceability information that mirror nodes can optionally choose to download. The record and signature files are now in a more maintainable protobuf format that should make them easier to enhance with new fields in the future without requiring breaking changes. Also, the v6 record files will now be compressed which should translate into reduced network and storage costs while potentially improving performance. Once v6 is enabled in a future hedera-service's release, mirror node operators will be required to update to a version that supports the new v6 format to avoid downtime.

Rosetta saw a number of improvements this release to better align it with the Rosetta specification. A configurable valid duration seconds option was added to the transaction construction API to support customization of this value. Support for a consistent block number regardless of startDate was added in Rosetta now that Hedera has a consistent block as defined in HIP-415. A 0x prefix was added to alias addresses returned via the API to denote that the data is hex-encoded.



This release contains support for HIP-406 Staking, HIP-410 Wrapped Ethereum Transaction, and HIP-482 JSON-RPC Relay as well as a long overdue upgrade to Java 17.

HIP-406 Staking is coming and the mirror node is getting ready for it. This release we added persistence support to store staking information. In the next release, we'll expose this information via our APIs.

HIP-410 and HIP-482 are both intended to improve the onramp for existing Ethereum developers. Towards that end, we added pagination support to both of the contract logs REST APIs. You can now page through logs via a combination of a consensus timestamp and log index parameters. The new blocks REST APIs also saw new gas_used and logs_bloom fields added that show the aggregated values for all transactions within the block. Finally, we added a new network fee schedule REST API. Currently, it only exposes the gas price for ContractCall, ContractCreate, and EthereumTransaction types in tinybars.

GET /api/v1/network/fees

  "fees": [
      "gas": 35561,
      "transaction_type": "ContractCall"
      "gas": 481934,
      "transaction_type": "ContractCreate"
      "gas": 35561,
      "transaction_type": "EthereumTransaction"
  "timestamp": "1633392000.387357562"

Since mirror node's inception in 2019, it has used Java 11 to build and run due to it being the most recent LTS release. After Java 17 LTS was released in September 2021 we knew we wanted to upgrade. With this release we upgraded to 17 after validating that the mirror node was still functional and performant. If you're using our official container images, they are also on Java 17 so there will be no migration necessary besides updating the image. If you're running outside of a container, you'll need to either upgrade your JRE to 17 or rebuild the jar from source with -Djava.version=11.



This release is focused on adding the necessary data and APIs needed for the JSON-RPC Relay defined in HIP-482. The JSON-RPC Relay implements the Ethereum JSON-RPC standard and relays HIP-410 Ethereum transactions to consensus nodes. Since the concept of a block is crucial for JSON-RPC APIs, this release also contains the implementation of HIP-415 Introduction of Blocks.

The mirror node now exposes the concept of blocks as introduced in HIP-415. We now calculate and store the cumulative gas used and the contract log bloom filter for the block as a whole. This HIP defines three new REST APIs and this release includes all three: a list blocks REST API, a get blocks REST API, and a list contract results REST API. The new /api/v1/blocks API supports the usual limit and order query parameters along with timestamp and block.number to support equality and range operators for consensus timestamps and block numbers, respectively. The /api/v1/blocks/{hashOrNumber} is identical to the list blocks but only returns a single block by either its block hash or its block number. Finally, a /api/v1/contracts/results REST API was added that is identical to the existing /api/v1/contracts/{id}/results but able to search across contracts.

GET /api/v1/blocks

  "blocks": [{
    "count": 4,
    "gas_limit": 150000000,
    "gas_used": 50000000,
    "hapi_version": "0.24.0",
    "hash": "0xa4ef824cd63a325586bfe1a66396424cd33499f895db2ce2292996e2fc5667a69d83a48f3883f2acab0edfb6bfeb23c4",
    "logs_bloom": "0x549358c4c2e573e02410ef7b5a5ffa5f36dd7398",
    "name": "2022-04-07T16_59_23.159846673Z.rcd",
    "number": 19533336,
    "previous_hash": "0x4fbcefec4d07c60364ac42286d5dd989bc09c57acc7370b46fa8860de4b8721e63a5ed46addf1564e4f8cd7b956a5afa",
    "size": 8489,
    "timestamp": {
      "from": "1649350763.159846673",
      "to": "1649350763.382130000"
  "links": {
    "next": null

GET /api/v1/blocks/{hashOrNumber}

  "count": 4,
  "gas_limit": 150000000,
  "gas_used": 50000000,
  "hapi_version": "0.24.0",
  "hash": "0xa4ef824cd63a325586bfe1a66396424cd33499f895db2ce2292996e2fc5667a69d83a48f3883f2acab0edfb6bfeb23c4",
  "logs_bloom": "0x549358c4c2e573e02410ef7b5a5ffa5f36dd7398",
  "name": "2022-04-07T16_59_23.159846673Z.rcd",
  "number": 19533336,
  "previous_hash": "0x4fbcefec4d07c60364ac42286d5dd989bc09c57acc7370b46fa8860de4b8721e63a5ed46addf1564e4f8cd7b956a5afa",
  "size": 8489,
  "timestamp": {
    "from": "1649350763.159846673"
    "to": "1649350763.382130000"

A number of changes were made in support of HIP-410 Ethereum Transactions. The /api/v1/accounts/{idOrAlias} REST API was updated to accept an EVM address as a path parameter in lieu of an ID or alias. An ethereum_nonce and evm_address was added to the response of /api/v1/accounts/{idOrAliasOrAddress} and /api/v1/accounts. The existing /api/v1/contracts/results/{transactionId} was updated to accept the 32 byte Ethereum transaction hash as a path parameter in addition to the transaction ID that it supports now. Its response, as well as the similar /api/v1/contracts/{idOrAddress}/results/{timestamp}, was updated to add the following new Ethereum transaction fields:

  "access_list": "0xabcd...",
  "block_gas_used": 564684,
  "chain_id": "0x0127",
  "gas_price": "0xabcd...",
  "max_fee_per_gas": "0xabcd...",
  "max_priority_fee_per_gas": "0xabcd...",
  "nonce": 1,
  "r": "0x84f0...",
  "s": "0x5e03...",
  "transaction_index": 1,
  "type": 2,
  "v": 0

Note: Existing fields omitted for brevity.

A new exchange rate REST API /api/v1/network/exchangerate was added that returns the exchange rate network file stored in 0.0.112. It supports a timestamp parameter to retrieve the exchange rate at a certain time in the past.

  "current_rate": {
    "cent_equivalent": 596987
    "expiration_time": 1649689200
    "hbar_equivalent": 30000
  "next_rate": {
    "cent_equivalent": 594920
    "expiration_time": 1649692800
    "hbar_equivalent": 30000
  "timestamp": "1649689200.123456789"

A new /api/v1/contracts/results/logs API was added with the same query parameters and response as /api/v1/contracts/{address}/results/logs but with the ability to search across contracts. It does not support address as a query parameter as it’s expected users use the existing API if they need logs for a specific address. The same rules around not exceeding maxTimestampRange still applies and allows it to stay performant. Pagination is possible using a combination of the timestamp and index query parameters.

Finally, this releases completes our implementation of HIP-423 Long Term Scheduled Transactions. Two new fields wait_for_expiry and expiration_time were added to /api/v1/schedules and /api/v1/schedules/{id}



This is a big release with support for six different Hedera Improvement Proposals. Most of these changes are on the ingest side of things and future releases will work on adding them to our APIs.

HIP-16 will enable contract expiry and brings a new auto renew account field that contains the account responsible for any renewal fees associated with the contract. The contract REST APIs now show this auto_renew_account field along with a new permanent_removal flag that is set to true when the system expires a contract.

We missed a requirement in our implementation of HIP-329 CREATE2 opcode to allow a HAPI client to do a native transfer of assets to a contract known only by its CREATE2 address. We fixed this logic gap and now support EVM addresses in a CryptoTransferTransaction.

HIP-336 saw further polish to our allowance support. Support for an optional spender ID parameter on our /api/v1/accounts/{id}/nfts?spender.id={id} REST API is now included.

HIP-410 brings with it the ability to wrap an Ethereum native transaction and submit it to Hedera. The mirror node can now parse this new EthereumTransaction along with the results from its execution. Any contracts created or results and logs generated by its execution will automatically show up on the relevant contract REST APIs. Support for specifying the contract initcode directly on a contract create was also added. To support Externally Owned Accounts (EOA) being able to submit Ethereum transactions, we now calculate and store the EVM address of the account's ECDSA secp256k1 alias. Finally, we added support for repeated topics in contract logs REST API to bring it more inline with the eth_getLogs JSON-RPC method. If you supply multiple different topic parameters (e.g. topic0 and topic1) it is considered an AND operation as before, but if pass repeated parameters like topic0=0x01&topic0=0x02&topic1=0x03 it means “(topic 0 is 0x01 or 0x02) and (topic 1 is 0x03)”.

HIP-415 is defining a block as the number of records files since stream start (AKA genesis). Since only mirror nodes have a full history, they will be used to provide consensus nodes the current block number to update their state. Since partial mirror nodes with an effective start date after stream start won't have all record files, they may contain an inconsistent value for their block number in contrast to other mirror nodes with all data. This release attempts to correct that with a migration to bring them inline with full mirror nodes so everyone has a consistent block number value.

HIP-423 Long term scheduled transactions enhances the existing scheduled transactions to allow time-based scheduling of transactions. This release adds ingest support for the new schedule-related fields. Next release will expose these fields via our existing schedule REST APIs.


As part of this release, we have finished upgrading our PostgreSQL databases to version 14 and have updated all tests to use that version as well. We recommend mirror node operators plan their migration to PostgreSQL 14 at their earliest convenience. More details on the upgrade process can be found in our database guide.

The migrations in this release are estimated to take up to 2 hours against a mainnet database. However, the migration that takes up the bulk of this time will only run if it needs to correct block numbers. This is only necessary if your mirror node is a partial mirror node and has an effective start date that occurs after the stream start.


This release is mainly focused on finishing out our support for HIP-336 Approval and Allowance API for Tokens. We added support for the new CryptoDeleteAllowance transaction and removed support for the CryptoAdjustAllowance transaction that didn't make it into the final design. NFT allowances are tracked at the NFT transfer granularity allowing for up to date allowance information on the mirror node. Current spender information will show up in both /api/v1/accounts/{id}/nfts and /api/v1/tokens/{id}/nfts REST APIs. We also added the is_approval flag to APIs that show transfers.

With more developers using computers using Apple's M-series CPUs, it become clear the mirror node needed to support ARM-based architectures to accommodate them. In this release we added multi-architecture Docker images using docker buildx. We now push linux/amd64 and linux/arm64 variants to our Google Container Registry. If there's a need for additional operating systems or architectures in the future it can easily be expanded upon.

We also updated our GCP Marketplace application to the latest version.



This release adds support for three new REST APIs and four HIPs.

HIP-21 describes the need for a free network info query to enable SDKs and other clients to be able to retrieve the current list of nodes. In v0.49.1, we added a new NetworkService.getNodes() gRPC API. In this release, we're adding an equivalent address book API to our REST API. In addition to the standard order and limit parameters, it supports a file.id query parameter to filter by the two address books 0.0.101 or 0.0.102 and a node.id query parameter to filter nodes and provide pagination.

GET /api/v1/network/nodes

  "nodes": [
      "description": "",
      "file_id": "0.0.102",
      "memo": "0.0.3",
      "node_account_id": "0.0.3",
      "node_cert_hash": "0x3334...",
      "node_id": 0,
      "public_key": "0x308201...",
      "service_endpoints": [
          "ip_address_v4": "",
          "port": 50211
      "timestamp": {
        "from": "1636052707.740848001",
        "to": null
  "links": {
    "next": null

HIP-336 describes new Hedera APIs to approve and exercise allowances to a delegate account. An allowance grants a spender the right to transfer a predetermined amount of the payer's hbars or tokens to another account of the spender's choice. In v0.50.0 we added database support to store the new allowance transactions. In this release, two new REST APIs were created to expose the hbar and fungible token allowances. Full allowance support won't be available until a future release when consensus nodes enable it on mainnet.

GET /api/v1/accounts/{accountId}/allowances/crypto

  "allowances": [
      "amount_granted": 10,
      "owner": "0.0.1000",
      "spender": "0.0.8488",
      "timestamp": {
        "from": "1633466229.96874612",
        "to": "1633466568.31556926"
      "amount_granted": 5,
      "owner": "0.0.1000",
      "spender": "0.0.9857",
      "timestamp": {
        "from": "1633466229.96874612",
        "to": null
  "links": {}

GET /api/v1/accounts/{accountId}/allowances/tokens

  "allowances": [
      "amount_granted": 10,
      "owner": "0.0.1000",
      "spender": "0.0.8488",
      "token_id": "0.0.1032",
      "timestamp": {
        "from": "1633466229.96874612",
        "to": "1633466568.31556926"
      "amount_granted": 5,
      "owner": "0.0.1000",
      "spender": "0.0.9857",
      "token_id": "0.0.1032",
      "timestamp": {
        "from": "1633466229.96874612",
        "to": null
  "links": {}

Also on the REST API, we added support for HIP-329 CREATE2 addresses. Now any API that accepts a contract ID will also accept the 20-byte EVM address as a hex-encoded string. We improved the performance of the REST API by adding cache control headers to enable distributed caching via a CDN. The performance of the list transactions by type REST API saw a fix to improve its performance.

As part of HIP-260, contract precompile call data now populates new fields amount, gas, and function_parameter inside ContractFunctionResult within the TransactionRecord. Mirror node now stores these fields and exposes them via its existing contract results REST APIs.

There were a number of security improvements made to containerized mirror nodes. All Docker images now run as non-root regardless of running in Kubernetes or Docker Compose. The helm charts saw changes to conform to the Kubernetes restricted pod security standard. This ensures the mirror node runs with security best practices and reduces its overall attack surface. The Kubernetes Pod Security Standard replaces the deprecated PodSecurityPolicy and as such we've removed all configuration related to the latter.


This release has a long migration that is expected to take around 75 minutes to complete, depending upon your database hardware and configuration. As always, we recommend a red/black deployment to eliminate downtime during migrations. If you're using the hedera-mirror-common chart, please check the kube-prometheus-stack upgrade notes to ensure Prometheus Operator can update successfully.



This release is mainly focused around the area of data integrity and ensuring the data in the mirror node is consistent with consensus nodes. To this end, we added an errata database migration that only runs for mainnet and corrects three known issues that impacted the stream files. The state of the consensus nodes was never impacted, only the externalization of these changes to the stream files that the mirror node consumes.

To find the inconsistent data and ensure it stays consistent going forward, we added a new balance reconciliation job. This job runs nightly and compares the balance file information against the record file information to ensure they are in sync. It does three checks for each balance file: verifies the balance files add up to 50 billion hbars, verifies the aggregated hbar transfers match the balance file, and verifies the aggregated token transfers match the balance file. It can be disabled if not needed via hedera.mirror.importer.reconciliation.enabled=false.

We also fixed a bug that caused transfers with a zero amount to show up for crypto create transactions with a zero initial balance. This was due entirely to our code inserting the extra transfers, not because of any problem in the stream files. We also fixed an REST API bug that caused the contract byte code to show up as double encoded to hex.

For the Rosetta API, we added account alias support to various endpoints. And we now support parsing contract results for precompiled contract functions like HTS functions. This capability is disabled by a feature flag and will be enabled in a future release.


This release contains a couple medium sized database migrations to correct the erroneous data in the database. It is expected to take about 45 minutes against a full mainnet database.



HIP-331 is a community contributed improvement proposal requesting the addition of a new REST API to retrieve an account's list of owned non-fungible tokens (NFTs). The mirror node has an existing /api/v1/tokens/{tokenId}/nfts API to retrieve all NFTs for a given token, but it didn't satisfy the requirement to show NFTs across token classes. This release adds the new /api/v1/accounts/{accountId}/nfts API to satisfy this need. It is our first API with multiple query parameters required for paging and as such has a few restrictions around their use. Please see the OpenAPI description for this API for further details.

GET /api/v1/accounts/0.0.1001/nfts?token.id=gte:1500&serialnumber=gte:2&order=asc&limit=2

    "nfts": [
        "account_id": "0.0.1001",
        "created_timestamp": "1234567890.000000006",