DOCSEARCHbyAlgolia
Submit Docs

Hiero Mirror Node

repository·main·Indexed 41 days ago

https://github.com/hiero-ledger/hiero-mirror-node

An archive service for Hiero-based networks that stores historical data and provides APIs, auditing, and analytics. It consists of an Importer, gRPC API, REST API, and a PostgreSQL database, with deployment support for Google Kubernetes Engine (GKE) via Helm.

Tokens
137.8K
Snippets
281
Records
432
Agent score
41%

What's inside Hiero Mirror Node

  3. Overview of the REST Java API

    main
    The REST Java API provides Java-based REST endpoints for the Hiero Mirror Node. This module is designed to host new APIs and serves as the destination for existing JavaScript-based APIs as they are migrated from the original rest module. The long-term goal is to convert all JavaScript APIs to Java and merge the two modules into a single unified service.

  4. Overview of Smart Contract support in the Mirror Node

    main

    The Mirror Node is being enhanced to provide comprehensive storage and retrieval of smart contract data. This includes storing all contract-related information from transactions and transaction records, making this data accessible via REST APIs and exploring compatibility with Ethereum JSON-RPC APIs.

    Key capabilities include:

    • Retrieving smart contracts and their execution results via REST API.
    • Searching for data by smart contract log topics via REST API.
    • Providing an interface for smart contract data that aligns with Ethereum JSON-RPC standards (though 100% compatibility is not a goal).

  5. Understand the Importer component

    main

    The Importer is a core component of the Mirror Node responsible for:

    1. Downloading stream files uploaded by consensus nodes.
    2. Verifying the integrity of these files.
    3. Ingesting the normalized data into the database.

    It is designed to be compatible with HAPI (Hedera API) versions, though certain breaking changes in the stream format (like the introduction of Record File v6 or the deprecation of balance files) require specific Mirror Node versions to maintain compatibility.

  6. HTS Data Ingestion Goals

    main

    The Mirror Node is designed to achieve the following for HTS:

    • Transaction Ingestion: Ingest HTS Token transactions from record stream .rcd files and persist them.
    • Balance Ingestion: Ingest account token balances from balance stream .csv files and persist them.
    • REST API Support:
      • Expose token balances in existing account balance APIs.
      • Token Discovery: API to return all available tokens.
      • Token Supply Distribution: API to return all accounts holding a specific token.
    • Streaming Support: A gRPC API to subscribe to token transfers for a specific account.

  7. Overview of NFT support in the Mirror Node

    main

    The Mirror Node provides support for Non-Fungible Tokens (NFTs), allowing for the creation of tokens with unique data that can be individually tracked. The implementation covers whole, singleton, and fractional NFTs.

    Key capabilities include:

    • Ingesting NFT transactions and persisting them to the database.
    • Exposing NFT information and transfer history via REST APIs.
    • Monitoring NFT activity.

  8. Understand the Parser architecture and data flow

    main

    The Mirror Node parser is designed to decouple the parsing of data streams from the ingestion into a database. This decoupling allows for independent benchmarking of parser performance versus database ingestion performance and enables the use of different database types (e.g., Cassandra, Bigtable) without modifying the parser logic.

    Data flows through the system via specialized listeners that react to parsed items. The architecture supports distinct streams for records, balances, and events.

  9. Understand the Mirror Node Hooks Architecture

    main

    Mirror Node Hooks support (HIP-1195) allows the system to track and store data related to transaction hooks. The architecture relies on identifying specific ContractCall transactions to the system contract 0.0.365 (0x16d) that appear as children of a triggering CryptoTransfer transaction.

    Key components include:

    • Domain Models: Uses an EntityHistory pattern with Hook (current state) and HookHistory (historical records), alongside HookStorage and HookStorageChange for managing hook-specific data.
    • Transaction Handlers: Enhanced to extract HookCreationDetails from transaction bodies (e.g., CryptoCreateTransactionHandler, ContractUpdateTransactionHandler).
    • Hook Execution: Identified by checking if ContractCallTransactionBody.contractID == 0.0.365 and verifying the parentConsensusTimestamp matches the triggering transaction.
    • Storage Updates: Hook storage changes are captured via ContractStateChanges in the sidecars of these specific ContractCall transactions.

  11. How the Mirror Node architecture works

    main

    The Mirror Node acts as an archive node for Hiero-based networks, providing historical data, APIs, and analytics without participating in network consensus.

    Data Flow and Trust Model

    1. Consensus Nodes: When transactions reach consensus, nodes create record files. These files contain a hash of the previous record file, creating an unbreakable validation chain. Nodes generate signature files for these records and upload both to cloud storage (Amazon S3 or Google Cloud Storage).
    2. Mirror Nodes: The mirror node software downloads signature files from cloud storage and verifies them using the node's public key from the address book.
    3. Validation: To ensure data integrity, the mirror node verifies that at least 1/3 of signatures match the same record file hash. It then validates the record file hash against the signature and ensures the hash chain (previous hash) is continuous with the last processed file.

    Advantages of Mirror Nodes

    • Lower compute and bandwidth requirements compared to consensus nodes.
    • Ability to selectively save specific data to reduce storage.
    • Efficient data retrieval through indexing.
    • Fast integration via exposed APIs.

  12. How bootstrap handles crash recovery and resumes

    main

    The tool tracks state in bootstrap-logs/tracking.json. If the process is interrupted, it uses this file to resume:

    • IMPORTED files are skipped.
    • IN_PROGRESS, FAILED_TO_IMPORT, and FAILED_VALIDATION files are reset to NOT_STARTED before the new import begins.
    • All non-IMPORTED files are queued in manifest order.

    Data Cleanup on Resume: To prevent duplicate data, the tool performs targeted cleanup before re-importing a file:

    • Partitioned tables: The specific partition is truncated.
    • Non-partitioned tables: The tool derives a time range from the filename suffix (e.g., _pYYYY_MM) and executes a DELETE WHERE consensus_timestamp >= start AND < end to clear only the relevant data for that period.