In this article you will learn about mirror nodes and how to use them for your applications.
With the high number of transactions that the Hedera Network is able to process every second, keeping this transaction history in all the network nodes for all time would eventually turn those nodes into massive data centers. Mirror nodes help address that issue by separating the consensus operations and the record keeping.
Mirror nodes receive information from the consensus nodes (mainnet or testnet), but the former do not contribute to consensus themselves - that’s the job of the consensus nodes only. However, the trust from the consensus nodes is transferred to the mirror nodes using signatures, chain of hashes, and state proofs. This all means that mirror nodes provide an efficient way to perform activities like queries, analytics, audit support, and monitoring without having a major impact on the performance of consensus nodes.
You have a few options available when it comes to using mirror nodes. You can choose from Hedera-operated, community-operated, or running your own mirror node.
One consideration when choosing an option is that the Hedera-managed mirror node is throttled at 100 requests per second (rps) for mainnet. This non-production mainnet mirror node is meant to help developers build applications without having to run their own mirror node. Once your application is ready for production, consider using one of the community-operated mirror node services, like HashScan and DragonGlass.
For the Hedera-managed mirror node, you can access network transaction records and account balances via REST and gRPC APIs.
The Hedera mirror node REST API enables you to query transactions and account information from mirror nodes managed by Hedera. You can use this REST API for all Hedera environments (mainnet, testnet, and previewnet).
With the REST API, you use the base URL for the appropriate Hedera network and customize the endpoints to get results that match your search criteria. You can look up transaction history and filter by account, balance, transaction, topic, token, NFT, smart contract, and more.
These are the base URLs for each Hedera network:
And in this page, you can see all the options for customizing the endpoints to filter your query results:
Now let’s do a few queries to help you get started.
For the first query, we want to get a JSON schema of the testnet accounts that have a balance greater than 10,000 tinybar in descending order. After using the testnet base URL and customizing the endpoints, our query looks like:
https://testnet.mirrornode.hed...
You can just copy paste that text in your web browser and see the results for yourself! There are a lot of results, so notice that the last item in the page is:
"links":{"next":"/api/v1/accounts?account.balance=gt:10000&order=desc&account.id=lt:0.0.26568308"}
Adding that last item to the base URL takes you to the next page of results.
Here are a few more query examples that you can enter in your web browser for:
Keep in mind that in release v0.44 of the Hedera mirror node, the maximum number of rows the REST API can return was changed from 500 to 100. In addition, the default number of rows the REST API returns if the limit parameter is unspecified was changed from 500 to 25. However, if a request is sent requesting more than 100 it won't fail. Instead, it will use the smaller of the two values.
You can also use the REST API in your code to consume transaction history information in your application. There are many ways to do this, but we’ll simply use the fetch API in JavaScript to wrap some of the REST commands we learned above.
console.clear(); import fetch from "node-fetch"; async function main() { let firstLink = "https://testnet.mirrornode.hedera.com/api/v1/tokens?type=NON_FUNGIBLE_UNIQUE&token.id=gte:0.0.26568401&token.id=lte:0.0.26568403&order=desc"; let results1 = await mirrorQuery(firstLink); console.log(`- One of the tokens has ID: ${results1.tokens[0].token_id} \n`); let secondLink = "https://testnet.mirrornode.hedera.com/api/v1/balances?account.id=lt:0.0.10&order=asc&limit=5"; let results2 = await mirrorQuery(secondLink); console.table(results2.balances); console.log( `\n - There are ${results2.balances[0].balance * 1e-8} test hbar in account ${results2.balances[0].account} \n` ); async function mirrorQuery(url) { let response = await fetch(url); let info = await response.json(); return info; } } main();
Based on the console.log commands, the code above outputs:
In our code, using fetch returns a data object with the information from the query that we can use in our application. Here’s what that data object looks like from the debug console for the variable results1.
It’s worth mentioning that the Hedera SDKs provide a way to get transaction confirmations from the consensus nodes. However, confirmations from those nodes are only available for a few minutes after a transaction is submitted to the network. In addition, some queries from consensus nodes may have an associated fee, whereas mirror node queries are free. If you want to get information about a transaction or entity from hours, days, weeks, months, or years ago, then querying the mirror nodes is the way to go.
When you configure the Hedera client for a network (mainnet, testnet, previewnet) through the SDKs, the connection with the corresponding mirror node is handled automatically. This automatic connection to the mirror node, however, is only valid for subscribing to Hedera Consensus Service (HCS) topics and querying those messages. Other history like transactions, account-specific activity, and similar can be fetched using the REST API.
You can customize the mirror node network you connect to, which is useful if you’re connecting to a community-operated mirror node or running your own. If you would like to modify the mirror client, follow the documentation.
You have multiple options when it comes to running your own mirror node:
For more details on these options, be sure give this blog post and the documentation instructions a good read!