The components of the Mirror Node all support loading configuration from an application.yml file or via the
environment.
The default configuration allows users to quickly get up and running without having to configure anything. This provides ease of use at the trade-off of some insecure default configuration. Most configuration settings have appropriate defaults and can be left unchanged. It is recommended to browse the properties below and adjust to your needs.
One of the important settings that should be changed for all components is the network property as it controls which
of the networks to mirror. Additionally, the password properties have a default, but it is strongly recommended
passwords be changed from the default.
Depending upon your deployment tool, the process to modify this configuration may vary. For our Helm charts, we do support automatic generation of random passwords.
Some variables are common to more than one module.
| Name | Default | Description |
|---|---|---|
hiero.mirror.common.databaseStartup.enabled |
true | Controls if app waits for database connection on app start |
hiero.mirror.common.databaseStartup.interval |
2s | Interval between checking if database is connectable |
hiero.mirror.common.databaseStartup.timeout |
5m | Total time to wait for database to become available before erroring |
hiero.mirror.common.databaseStartup.validationTimeout |
2s | Time allowed for query to check if connection is valid |
hiero.mirror.common.databaseStartup.connectTimeout |
2s | Time allowed for driver connect timeout |
hiero.mirror.common.databaseStartup.socketTimeout |
2s | Time allowed for driver socket timeout |
hiero.mirror.common.realm |
0 | The default base realm the mirror node participates in. |
hiero.mirror.common.shard |
0 | The default shard number this mirror node participates in. |
The Importer component uses Spring Boot properties to configure the application. As a result, property files, YAML files, environment variables and command-line arguments can all be used to configure the application. See the Spring Boot documentation for the location and order it loads configuration.
The following table lists the available properties along with their default values. Unless you need to set a non-default
value, it is recommended to only populate overridden properties in the custom application.yml.
| Name | Default | Description |
|---|---|---|
hiero.mirror.importer.block.autoDiscoveryEnabled |
true | When enabled, auto-discovered block node properties (read from cache or database) are merged with block node config file properties. |
hiero.mirror.importer.block.bucketName |
The cloud storage bucket name to download blockstream files. This value takes priority over network hardcoded bucket names. | |
hiero.mirror.importer.block.cutover.enabled |
Whether to auto switch from record stream to block stream. This overrides the default set for the network. | |
hiero.mirror.importer.block.cutover.firstStage.baseBackoff |
2s | The base backoff period to avoid block stream when it fails to advance blocks. The effective backoff doubles on each consecutive failure |
hiero.mirror.importer.block.cutover.firstStage.enabled |
false | Whether to enable the first-stage cutover |
hiero.mirror.importer.block.cutover.firstStage.hapiVersion |
0.75.0 | The minimum HAPI version to enable the first-stage cutover |
hiero.mirror.importer.block.cutover.firstStage.latencyCheckThreshold |
10s | The elapsed time threshold in block stream streaming to check latency |
hiero.mirror.importer.block.cutover.firstStage.maxBackoffMultiplier |
64 | The maximum multiplier applied to baseBackoff for the exponential block stream backoff |
hiero.mirror.importer.block.cutover.firstStage.maxLatency |
4s | The maximum latency, if crossed, to fall back to record stream |
hiero.mirror.importer.block.cutover.hapiVersion |
0.79.0 | The HAPI version following which the final cutover will happen. |
hiero.mirror.importer.block.cutover.threshold |
16s | The amount of time to wait to switch between block stream and record stream during cutover. |
hiero.mirror.importer.block.enabled |
false | Whether to enable block stream source |
hiero.mirror.importer.block.frequency |
500ms | The fixed period between invocations. Can accept duration units like 10s, 2m, etc. If not specified, millisecond is implied as the unit. |
hiero.mirror.importer.block.initialLedgerIdPublication |
File path containing the serialized LedgerIdPublicationTransactionBody proto bytes used to bootstrap TSS verification. |
|
hiero.mirror.importer.block.nodes[].endpoints[].apis |
[STATUS, SUBSCRIBE_STREAM] | Block node APIs provided by the block node endpoint. The endpoints of a single block node must collectively provide both STATUS and SUBSCRIBE_STREAM APIs. |
hiero.mirror.importer.block.nodes[].endpoints[].host |
The host of the block node endpoint. | |
hiero.mirror.importer.block.nodes[].endpoints[].port |
40840 | The port of the block node endpoint. |
hiero.mirror.importer.block.nodes[].endpoints[].requiresTls |
false | Whether the block node endpoint requires TLS. |
hiero.mirror.importer.block.nodes[].priority |
0 | The priority of the block node server. A lower value indicates higher priority, and 0 is the highest priority. |
hiero.mirror.importer.block.persistBytes |
false | Whether to persist the block stream file bytes to the database. |
hiero.mirror.importer.block.scheduler.latency.backlog |
1 | The backlog size of pending latency measuring tasks. Note a max number of backlog plus 1 tasks can be scheduled when the service is idle. |
hiero.mirror.importer.block.scheduler.latency.frequency |
10s | The fixed period between attemps to schedule tasks. |
hiero.mirror.importer.block.scheduler.latency.timeout |
5s | The timeout when streaming a block from a block node for background latency measurement. |
hiero.mirror.importer.block.scheduler.maxPostProcessingLatency |
1s | The maximum allowed post-processing delay to calculate and record block node streaming latency. |
hiero.mirror.importer.block.scheduler.minRescheduleInterval |
10s | The mininum block node reschedule interval. |
hiero.mirror.importer.block.scheduler.rescheduleLatencyThreshold |
50ms | The threshold to meet for lower latency block nodes to trigger a reschedule. |
hiero.mirror.importer.block.scheduler.type |
PRIORITY_THEN_LATENCY | The scheduler type. Can be LATENCY, PRIORITY, or PRIORITY_THEN_LATENCY. |
hiero.mirror.importer.block.sourceType |
AUTO | Block source type, available values are AUTO, BLOCK_NODE, and FILE. The default is AUTO. In AUTO type, BLOCK_NODE is tried first, then FILE. |
hiero.mirror.importer.block.stream.keepAliveTime |
10m | The interval between gRPC keep-alive pings sent to a block node to detect a dead connection. |
hiero.mirror.importer.block.stream.keepAliveTimeout |
5s | The time to wait for a keep-alive ping response before considering the block node connection dead. |
hiero.mirror.importer.block.stream.keepAliveWithoutCalls |
true | Whether to send gRPC keep-alive pings on a block node connection even when there are no active calls. |
hiero.mirror.importer.block.stream.maxBlockItems |
800000 | The max number of block items allowed in a block streamed from block nodes. |
hiero.mirror.importer.block.stream.maxBlockSize |
512MB | The max decompressed size of a single block assembled from block node stream responses, guarding against unbounded memory use. |
hiero.mirror.importer.block.stream.maxDrainAttempts |
32 | The max number of attempts to drain the grpc buffer after unsubscribing from a block node. |
hiero.mirror.importer.block.stream.maxStreamResponseSize |
125MB | The max size of a stream response from block nodes, in MB. |
hiero.mirror.importer.block.stream.maxSubscribeAttempts |
3 | The max number of consecutive subscribe attempts to a block node before marking the node inactive. |
hiero.mirror.importer.block.stream.readmitDelay |
1m | The time to wait before readmitting an inactive block node. |
hiero.mirror.importer.block.stream.responseTimeout |
400ms | The block node server status request timeout. |
hiero.mirror.importer.block.stream.shutdownTimeout |
5s | The max time to wait for a block node gRPC channel to terminate gracefully before forcing shutdown. |
hiero.mirror.importer.block.writeFiles |
false | Whether to write verified block stream files to the filesystem. |
hiero.mirror.importer.cache.addressBook |
maximumSize=100,expireAfterWrite=5m,recordStats | The Caffeine cache specification for the address book. |
hiero.mirror.importer.cache.alias |
maximumSize=100000,expireAfterAccess=30m,recordStats | The Caffeine cache specification for alias or EVM address to entity ID mapping. |
hiero.mirror.importer.cache.enabled |
true | Whether caching should be enabled at all. |
hiero.mirror.importer.cache.evmAddress |
maximumSize=500000,recordStats | The Caffeine cache specification for encoded entity id to trimmed evm address or long zero mapping |
hiero.mirror.importer.cache.fileData |
maximumSize=100,expireAfterAccess=5m,recordStats | The Caffeine cache specification for file data |
hiero.mirror.importer.cache.timePartition |
maximumSize=50,expireAfterWrite=1d,recordStats | The Caffeine cache specification for time partition lookups. |
hiero.mirror.importer.cache.timePartitionOverlap |
maximumSize=50,expireAfterWrite=1d,recordStats | The Caffeine cache specification for time partition overlap lookups. |
hiero.mirror.importer.consensusMode |
STAKE_IN_ADDRESS_BOOK | The consensus mode to determine minimum consensus stake. See the ConsensusMode enum for a list of possible values |
hiero.mirror.importer.dataPath |
./data | The data directory used to store downloaded files and other application state |
hiero.mirror.importer.db.connectionInitSql |
set temp_buffers='256MB'; set timezone TO 'UTC'; | Sql ran on each connection initialized from the datasource |
hiero.mirror.importer.db.host |
127.0.0.1 | The IP or hostname used to connect to the database |
hiero.mirror.importer.db.loadBalance |
true | Whether to enable pgpool load balancing. If false, it sends all reads to the primary db backend instead of load balancing them across the primary and replicas. |
hiero.mirror.importer.db.metricRefreshInterval |
5m | The interval which we wait to refresh database statistics. Specified as a spring duration expression |
hiero.mirror.importer.db.name |
mirror_node | The name of the database |
hiero.mirror.importer.db.owner |
mirror_node | The username of the db user with owner permissions to create and modify the schema |
hiero.mirror.importer.db.ownerPassword |
mirror_node_pass | The password for the owner user the processor uses to connect. |
hiero.mirror.importer.db.partition.cron |
0 0 0 * * ? | The cron schedule for creating new partitions This is applicable to the v2 database schema |
hiero.mirror.importer.db.partition.enabled |
true | Whether new partitions should be created automatically. |
hiero.mirror.importer.db.password |
mirror_importer_pass | The database password for the Importer user the processor uses to connect. |
hiero.mirror.importer.db.port |
5432 | The port used to connect to the database |
hiero.mirror.importer.db.restPassword |
mirror_api_pass | The database password the API uses to connect. |
hiero.mirror.importer.db.restUsername |
mirror_api | The username the API uses to connect to the database |
hiero.mirror.importer.db.schema |
public | The name of the custom schema database objects will be created in. This is applicable from v2 of the data schema |
hiero.mirror.importer.db.sslMode |
disable | The ssl level of protection against Eavesdropping, Man-in-the-middle (MITM) and Impersonation on the db connection. Accepts either disable, allow, prefer, require, verify-ca or verify-full. |
hiero.mirror.importer.db.username |
mirror_importer | The Importer username the processor uses to connect to the database |
hiero.mirror.importer.downloader.accessKey |
"" | The cloud storage access key |
hiero.mirror.importer.downloader.allowAnonymousAccess |
Whether the cloud storage bucket allows for anonymous access. | |
hiero.mirror.importer.downloader.balance.enabled |
false | Whether to enable balance file downloads |
hiero.mirror.importer.downloader.balance.frequency |
30s | The fixed period between invocations. Can accept duration units like 10s, 2m, etc. If not specified, millisecond is implied as the unit. |
hiero.mirror.importer.downloader.balance.persistBytes |
false | Whether to persist the balance file bytes to the database. |
hiero.mirror.importer.downloader.balance.writeFiles |
false | Whether to write verified stream files to the filesystem. |
hiero.mirror.importer.downloader.balance.writeSignatures |
false | Whether to write verified signature files to the filesystem. |
hiero.mirror.importer.downloader.batchSize |
25 | The number of signature files to download per node before downloading the signed files |
hiero.mirror.importer.downloader.bucketName |
The cloud storage bucket name to download streamed files. This value takes priority over network hardcoded bucket names regardless of hiero.mirror.importer.network value. |
|
hiero.mirror.importer.downloader.cloudProvider |
S3 | The cloud provider to download files from. Either GCP, LOCAL, or S3. |
hiero.mirror.importer.downloader.consensusRatio |
0.33333333333 | The ratio of verified nodes (nodes used to come to consensus on the signature file hash) to total number of nodes available. |
hiero.mirror.importer.downloader.downloadRatio |
1 | The ratio of nodes (or stake) to be concurrently downloaded to verify signatures to total number of nodes (or stake) available. |
hiero.mirror.importer.downloader.endpointOverride |
Can be specified to download streams from a source other than S3 and GCP. Should be S3 compatible | |
hiero.mirror.importer.downloader.gcpProjectId |
GCP project id to bill for requests to GCS bucket which has Requester Pays enabled. | |
hiero.mirror.importer.downloader.groupByDay |
true | Whether to group downloaded files in different folders based on their date. |
hiero.mirror.importer.downloader.local.deleteAfterProcessing |
true | Whether to delete files downloaded locally after successfully processing them. |
hiero.mirror.importer.downloader.maxSize |
52428800 | The maximum size in bytes of stream files to consider for downloading. |
hiero.mirror.importer.downloader.pathPrefix |
"" | An optional prefix to prepend to the path used for accessing files in the storage bucket. This is useful for supporting subpaths within the bucket. |
hiero.mirror.importer.downloader.record.enabled |
true | Whether to enable record file downloads |
hiero.mirror.importer.downloader.record.frequency |
500ms | The fixed period between invocations. Can accept duration units like 10s, 2m, etc. If not specified, millisecond is implied as the unit. |
hiero.mirror.importer.downloader.record.persistBytes |
false | Whether to persist the record file bytes to the database. |
hiero.mirror.importer.downloader.record.writeFiles |
false | Whether to write verified stream files to the filesystem. |
hiero.mirror.importer.downloader.record.writeSignatures |
false | Whether to write verified signature files to the filesystem. |
hiero.mirror.importer.downloader.region |
us-east-1 | The region associated with the bucket |
hiero.mirror.importer.downloader.secretKey |
"" | The cloud storage secret key |
hiero.mirror.importer.downloader.sources |
[] | A list of download sources to use for stream files. The grandfathered hiero.mirror.importer.downloader will also be utilized as the first source in the list. |
hiero.mirror.importer.downloader.sources.backoff |
60s | The amount of time to wait before retrying a source after an exception |
hiero.mirror.importer.downloader.sources.connectionTimeout |
5s | The amount of time to wait for a connection before throwing an exception |
hiero.mirror.importer.downloader.sources.credentials.accessKey |
The cloud storage access key for the given source | |
hiero.mirror.importer.downloader.sources.credentials.secretKey |
The cloud storage secret key for the given source | |
hiero.mirror.importer.downloader.sources.maxConcurrency |
1000 | The maximum number of allowed open HTTP connections. Used by AWS SDK directly. |
hiero.mirror.importer.downloader.sources.projectId |
The cloud project ID to bill for requests to the bucket which has requester pays enabled. | |
hiero.mirror.importer.downloader.sources.region |
us-east-1 | The region associated with the bucket |
hiero.mirror.importer.downloader.sources.type |
The source type to download files from. Either GCP, LOCAL, or S3. |
|
hiero.mirror.importer.downloader.sources.uri |
The endpoint override URI to use as an alternate for the default URI provided by the source type. | |
hiero.mirror.importer.downloader.timeout |
5s | The amount of time to wait for a download before throwing an exception |
hiero.mirror.importer.endBlockNumber |
If set, the last block (inclusive) to ingest. Items after this number will be ignored. | |
hiero.mirror.importer.endDate |
2262-04-11T23:47:16.854775807Z | The end date (inclusive) of the data to import. Items after this date will be ignored. Format: YYYY-MM-ddTHH:mm:ss.nnnnnnnnnZ |
hiero.mirror.importer.importHistoricalAccountInfo |
true | Import historical account information that occurred before the last stream reset. Skipped if startDate is unset or after 2019-09-14T00:00:10Z. |
hiero.mirror.importer.initialAddressBook |
"" | The path to the bootstrap address book used to override the built-in address book |
hiero.mirror.importer.migration.<migrationName>.checksum |
1 | The checksum of the repeatable migration. Change it to a different value to re-run the migration |
hiero.mirror.importer.migration.<migrationName>.enabled |
true | Whether to enable the repeatable migration |
hiero.mirror.importer.network |
demo | Which network to use. Recognized names are demo, mainnet, other, testnet, and previewnet. Other names are allowed but are treated as development or test networks. |
hiero.mirror.importer.nodePublicKey |
A X509 public key in DER format encoded to hexadecimal. Used to override each node's public key in the address book solely for testing manually generated stream files. | |
hiero.mirror.importer.parser.balance.batchSize |
200000 | The number of balances to store in memory before saving to the database |
hiero.mirror.importer.parser.balance.batch.flushInterval |
2s | The amount of time to wait before a batch is flushed to be persisted by the parser |
hiero.mirror.importer.parser.balance.batch.maxFiles |
1 | The maximum number of files to consider for batching before being persistedy by the parser |
hiero.mirror.importer.parser.balance.batch.maxItems |
1000000 | The maximum number of items across multiple files to consider for batching before being persistedy by the parser |
hiero.mirror.importer.parser.balance.batch.queueCapacity |
1 | How many balance files to queue in memory while waiting to be persisted by the parser |
hiero.mirror.importer.parser.balance.batch.window |
5m | The amount of time the importer has to be behind before starting to batch stream files |
hiero.mirror.importer.parser.balance.enabled |
true | Whether to enable balance file parsing |
hiero.mirror.importer.parser.balance.fileBufferSize |
200000 | The size of the buffer to use when reading in the balance file |
hiero.mirror.importer.parser.balance.frequency |
1s | How often to poll for new messages. Can accept duration units like 10s, 2m etc. If not specified, millisecond is implied as the unit. |
hiero.mirror.importer.parser.balance.processingTimeout |
10s | The additional timeout to allow after the last balance stream file health check to verify that files are still being processed. |
hiero.mirror.importer.parser.balance.retry.maxAttempts |
3 | How many attempts should be made to retry file parsing errors |
hiero.mirror.importer.parser.balance.retry.maxBackoff |
10s | The maximum amount of time to wait between retries |
hiero.mirror.importer.parser.balance.retry.minBackoff |
250ms | The minimum amount of time to wait between retries |
hiero.mirror.importer.parser.balance.retry.multiplier |
2 | Used to generate the next delay for backoff |
hiero.mirror.importer.parser.balance.transactionTimeout |
5m | The timeout for a database transaction |
hiero.mirror.importer.parser.bufferSize |
32768 | The size of the byte buffer to allocate for each batch |
hiero.mirror.importer.parser.exclude |
[] | A list of filters that determine which transactions are ignored. Takes precedence over include |
hiero.mirror.importer.parser.exclude.entity |
[] | A list of entity IDs to ignore in shard.realm.num (e.g. 0.0.3) format |
hiero.mirror.importer.parser.exclude.expression |
A restricted Spring Expression Language (SpEL) expression which when evaluated to true ignores the transaction | |
hiero.mirror.importer.parser.exclude.transaction |
[] | A list of transaction types to ignore. See TransactionType.java for possible values |
hiero.mirror.importer.parser.include |
[] | A list of filters that determine which transactions are stored |
hiero.mirror.importer.parser.include.entity |
[] | A list of entity IDs to store in shard.realm.num (e.g. 0.0.3) format |
hiero.mirror.importer.parser.include.expression |
A restricted Spring Expression Language (SpEL) expression which when evaluated to true includes the transaction | |
hiero.mirror.importer.parser.include.transaction |
[] | A list of transaction types to store. See TransactionType.java for possible values |
hiero.mirror.importer.parser.record.batch.flushInterval |
2s | The amount of time to wait before a batch is flushed to be persisted by the parser |
hiero.mirror.importer.parser.record.batch.maxFiles |
1 | The maximum number of files to consider for batching before being persistedy by the parser |
hiero.mirror.importer.parser.record.batch.maxItems |
60000 | The maximum number of items across multiple files to consider for batching before being persistedy by the parser |
hiero.mirror.importer.parser.record.batch.queueCapacity |
10 | How many balance files to queue in memory while waiting to be persisted by the parser |
hiero.mirror.importer.parser.record.batch.window |
5m | The amount of time the importer has to be behind before starting to batch stream files |
hiero.mirror.importer.parser.record.enabled |
true | Whether to enable record file parsing |
hiero.mirror.importer.parser.record.entity.persist.claims |
false | Persist claim data to the database |
hiero.mirror.importer.parser.record.entity.persist.contracts |
true | Persist contract data to the database |
hiero.mirror.importer.parser.record.entity.persist.contractResults |
true | Persist contract results data to the database |
hiero.mirror.importer.parser.record.entity.persist.contractTransaction |
true | Persist contract transaction parties (records results, logs, and state changes |
hiero.mirror.importer.parser.record.entity.persist.contractTransactionHash |
true | Persist contract result transaction hash data to the database |
hiero.mirror.importer.parser.record.entity.persist.cryptoTransferAmounts |
true | Persist crypto transfer amounts to the database |
hiero.mirror.importer.parser.record.entity.persist.entityHistory |
true | Persist entity history to the database. When set to false, historical entity changes except entity creation are ignored. Use with caution since disabling it will break logic depending on accurate entity historical state. |
hiero.mirror.importer.parser.record.entity.persist.entityNftTransactions |
false | Persist entity transactions related to nft transfers |
hiero.mirror.importer.parser.record.entity.persist.entityTransactionExclusion |
["0.0.98", "0.0.800", "0.0.801", "0.0.802"] | Entity IDs excluded from transaction tracking |
hiero.mirror.importer.parser.record.entity.persist.entityTransactions |
false | Persist entity transactions to the database |
hiero.mirror.importer.parser.record.entity.persist.ethereumTransactions |
true | Persist all ethereum transactions data to the database |
hiero.mirror.importer.parser.record.entity.persist.files |
true | Persist all file data to the database |
hiero.mirror.importer.parser.record.entity.persist.itemizedTransfers |
false | Persist itemized transfers for transactions that explicitly request hbar transfers |
hiero.mirror.importer.parser.record.entity.persist.pendingReward |
true | Calculate pending reward and update entity stake state |
hiero.mirror.importer.parser.record.entity.persist.schedules |
true | Persist schedule transactions to the database |
hiero.mirror.importer.parser.record.entity.persist.syntheticContractLogs |
true | Persist synthetic contract logs from HAPI transaction to the database |
hiero.mirror.importer.parser.record.entity.persist.syntheticContractLogsMulti |
true | Persist synthetic contract logs from transactions including multi-party fungible token transfers to the database |
hiero.mirror.importer.parser.record.entity.persist.syntheticContractResults |
false | Persist synthetic contract results from HAPI transaction to the database |
hiero.mirror.importer.parser.record.entity.persist.systemFiles |
true | Persist only system files (number lower than 1000) to the database |
hiero.mirror.importer.parser.record.entity.persist.tokenAirdrops |
true | Persist token airdrop data to the database |
hiero.mirror.importer.parser.record.entity.persist.tokens |
true | Persist token data to the database |
hiero.mirror.importer.parser.record.entity.persist.topics |
true | Persist topic messages to the database |
hiero.mirror.importer.parser.record.entity.persist.topicMessageLookups |
false | Persist topic message lookups to the database |
hiero.mirror.importer.parser.record.entity.persist.trackAllowance |
true | Track remaining crypto and fungible token allowance amounts by debiting approved transfers from original grant amount and persist to the database |
hiero.mirror.importer.parser.record.entity.persist.trackBalance |
true | Track entity balance changes and persist to the database |
hiero.mirror.importer.parser.record.entity.persist.trackNonce |
true | Track nonce changes and persist to the entity database |
hiero.mirror.importer.parser.record.entity.persist.transactionBytes |
false | Persist raw transaction bytes to the database |
hiero.mirror.importer.parser.record.entity.persist.transactionHash |
true | Persist transaction hash to the database |
hiero.mirror.importer.parser.record.entity.persist.transactionHashTypes |
All except CONSENSUSSUBMITMESSAGE | A set of transaction types to persist transaction hash for |
hiero.mirror.importer.parser.record.entity.persist.transactionRecordBytes |
false | Persist raw transaction record bytes to the database |
hiero.mirror.importer.parser.record.entity.persist.transactionSignatures |
SCHEDULECREATE, SCHEDULESIGN | A list of transaction types whose transaction signatures will be stored |
hiero.mirror.importer.parser.record.entity.redis.enabled |
true | Whether to use Redis to send messages to the gRPC process. Requires spring.redis.* properties |
hiero.mirror.importer.parser.record.entity.redis.queueCapacity |
8 | The size of the queue used to buffer topic messages between parser and redis publisher threads |
hiero.mirror.importer.parser.record.entity.sql.enabled |
true | Whether to use PostgreSQL Copy mechanism to insert into the database |
hiero.mirror.importer.parser.record.entity.staking.chunkDelay |
10s | How long to pause between each chunk of the pending reward calculation to reduce database load |
hiero.mirror.importer.parser.record.entity.staking.chunkSize |
500000 | The number of entity IDs to process per chunk during the pending reward calculation. Larger values reduce total processing time but increase per-transaction database load. |
hiero.mirror.importer.parser.record.frequency |
20ms | How often to poll for new messages. Can accept duration units like 10s, 2m etc. If not specified, millisecond is implied as the unit. |
hiero.mirror.importer.parser.record.historicalBalance.enabled |
true | Whether to enable historical balances service to generate balances information |
hiero.mirror.importer.parser.record.historicalBalance.initialDelay |
2m | Initial delay for environments in which the consensus nodes don't produce account balance files. Can accept duration units like 10s, 2m etc. |
hiero.mirror.importer.parser.record.historicalBalance.minFrequency |
15m | How often at least to generate balances information. Can accept duration units like 10s, 2m etc. The minimum allowed value is 15m, and the maximum is 7d. |
hiero.mirror.importer.parser.record.historicalBalance.tokenBalances |
true | Whether to generate token balances information. |
hiero.mirror.importer.parser.record.historicalBalance.transactionTimeout |
10m | The timeout in seconds for the database transaction to generate balances information. |
hiero.mirror.importer.parser.record.processingTimeout |
10s | The additional timeout to allow after the last record stream file health check to verify that files are still being processed. |
hiero.mirror.importer.parser.record.retry.maxAttempts |
Integer.MAX_VALUE | How many attempts should be made to retry file parsing errors |
hiero.mirror.importer.parser.record.retry.maxBackoff |
30s | The maximum amount of time to wait between retries |
hiero.mirror.importer.parser.record.retry.minBackoff |
500ms | The minimum amount of time to wait between retries |
hiero.mirror.importer.parser.record.retry.multiplier |
2 | Used to generate the next delay for backoff |
hiero.mirror.importer.parser.record.sidecar.enabled |
false | Whether to download and read sidecar record files |
hiero.mirror.importer.parser.record.sidecar.persistBytes |
false | Whether to persist the sidecar file bytes to the database |
hiero.mirror.importer.parser.record.sidecar.types |
[] | Which types of transaction sidecar records to process. By default it is empty to indicate all types. Accepts CONTRACT_ACTION, CONTRACT_BYTECODE, or CONTRACT_STATE_CHANGE. |
hiero.mirror.importer.parser.record.transactionTimeout |
120s | The timeout in seconds for a database transaction |
hiero.mirror.importer.reconciliation.cron |
0 0 0 * * * | When to run the balance reconciliation job. Defaults to once a day at midnight. See Spring docs. |
hiero.mirror.importer.reconciliation.delay |
1s | How much time to wait in between balance files |
hiero.mirror.importer.reconciliation.enabled |
false | Whether the balance reconciliation job should periodically run to reconcile data. |
hiero.mirror.importer.reconciliation.endDate |
2262-04-11T23:47:16.854775807Z | The consensus timestamp of the last balance file to reconcile. |
hiero.mirror.importer.reconciliation.remediationStrategy |
FAIL | The strategy to use to handle errors. Can be ACCUMULATE, RESET, or FAIL. ACCUMULATE and RESET will both proceed after an error, but RESET will correct the balances while ACCUMULATE does not |
hiero.mirror.importer.reconciliation.startDate |
1970-01-01T00:00:00Z | The consensus timestamp of the first balance file to reconcile. |
hiero.mirror.importer.reconciliation.token |
false | Whether to reconcile token information. |
hiero.mirror.importer.retention.batchPeriod |
1d | How often to commit deletions when pruning. |
hiero.mirror.importer.retention.enabled |
false | Whether to data retention should be enabled to purge older data. |
hiero.mirror.importer.retention.exclude |
[] | Which tables to exclude when pruning data. By default it is empty to indicate no tables will be excluded from retention. |
hiero.mirror.importer.retention.frequency |
1d | How often to run the retention job to purge older data. If it is already running from a previous period, skip execution. If not specified, millisecond is implied as the unit. |
hiero.mirror.importer.retention.include |
[] | Which tables to include when pruning data. By default it is empty to indicate all tables that can be pruned will be. |
hiero.mirror.importer.retention.period |
90d | How far in the past to remove data. This value is relative to the timestamp of the last transaction in the database and not to the current time. |
hiero.mirror.importer.topicRunningHashV2AddedTimestamp |
Network-based | Unix timestamp (in nanos) of first topic message with v2 as running hash version. Use this config to override the default network based value |
hiero.mirror.importer.startDate |
The start date (inclusive) of the data to import. It takes effect 1) if it's set and the date is after the last downloaded file or the database is empty; 2) if it's not set and the database is empty, it defaults to now. Format: YYYY-MM-ddTHH:mm:ss.nnnnnnnnnZ | |
hiero.mirror.importer.startBlockNumber |
null | The block number that will be set as the downloaded stream files starting index. For block stream files, it's the first block to download and ignored if there are existing blocks in database. When set to -1, get the first available block from a block node |
hiero.mirror.importer.smartContractThrottlingVersion |
0.69.0 | Temporary parameter used to dynamically adjust the first HAPI version for record items, which denotes the roll out of HIP-1249 (smart contract throttling) |
The mirror node may be configured to only store a subset of data for entities and/or transaction types of interest --
essentially, which rows of data to retain.
Note that the exclude properties take priority over the include properties - if you list the same value in both
lists, it will be excluded.
In addition, the various boolean hiero.mirror.importer.record.entity.persist properties may be specified to control
which additional fields get stored (which additional tables get recorded).
See the hiero.mirror.importer.parser.include.* and hiero.mirror.importer.parser.exclude.* properties listed in the
table above for full details.
Spring Expression Language (SpEL) expressions may also be utilized for including or excluding transactions. The mirror node sets up a restricted evaluation context and parses and evaluates the supplied expressions.
Expression restrictions include:
- Each transaction is represented by a record item. Only the top-level
transactionBodyandtransactionRecordproperties may be referenced. These are respectively the TransactionBody and TransactionRecord protocol buffers defined in the Java SDK. These are immutable and you can refer to them to see what may be accessed as sub properties etc. - Mirror node Spring beans (using
@) cannot be accessed within an expression. - Arbitrary types (mirror node, dependencies, Java) such as
T(java.lang.Runtime)orT(com.hiero.mirror.importer.SomeClass)cannot be accessed within an expression. - No property can be written to.
- The expression must evaluate to a boolean value.
- Since expressions may contain Java code, enclosing them within single or double quotes will help prevent errors when read from YAML or properties configuration files.
For any property resolved, the methods it supports is not restricted. For example, TransactionBody.memo is
a String, and any public methods on that type can be invoked. Thus the following are all acceptable expressions
returning a boolean value:
transactionBody.memo.startsWith("MyApp")
transactionBody.memo.contains("Some value")
transactionBody.memo.length() > 10 && transactionBody.memo.startsWith("MyApp")
One objective is to provide sufficient access to support powerful expressions while limiting the SpEL injection attack surface. Keep in mind though, transaction filter configuration properties are set by mirror node operators, so intentionally injecting oneself should be a rare occurrence.
Another important goal is to not expose too many mirror node implementation details, which may change in future releases, possibly breaking filter expressions that functioned properly in the past.
The scenario we wish to model is the same for each of the three configuration formats. Only choose one of the three ways to configure your instance of the mirror node.
- We wish to omit all records (regardless of transaction type) that are associated with account 0.0.98, which is the account representing the network (to which fees generally get paid to).
- We are interested in all CRYPTOTRANSFER transactions, for all accounts other than 0.0.98.
- We are interested in accounts 0.0.1000 and 0.0.1001, and wish to store all their transactions, regardless of transaction type.
- We are also interested in system files 0.0.101 and 0.0.102, and wish to store all their FILEAPPEND, FILECREATE, FILEDELETE, and FILEUPDATE transactions.
- For all CONTRACTCREATEINSTANCE transactions, we are only interested in those where the renewal account number is 2000.
- We do not wish to persist message topics for any transactions we do store.
To configure the above scenario via application.yml file, include the following lines:
hiero:
mirror:
importer:
parser:
exclude:
- entity: [0.0.98]
include:
- transaction: [CRYPTOTRANSFER]
- entity: [0.0.1000, 0.0.1001]
- entity: [0.0.101, 0.0.102]
transaction: [FILEAPPEND, FILECREATE, FILEDELETE, FILEUPDATE]
- transaction: [CONTRACTCREATEINSTANCE]
expression: "transactionBody.contractCreateInstance.autoRenewAccountId.accountNum == 2000"
record:
entity:
persist:
topics: falseTo configure the above scenario via application.properties file, include the following lines:
hiero.mirror.importer.parser.exclude[0].entity[0]=0.0.98
hiero.mirror.importer.parser.include[0].transaction[0]=CRYPTOTRANSFER
hiero.mirror.importer.parser.include[1].entity[0]=0.0.1000
hiero.mirror.importer.parser.include[1].entity[1]=0.0.1001
hiero.mirror.importer.parser.include[2].entity[0]=0.0.101
hiero.mirror.importer.parser.include[2].entity[1]=0.0.102
hiero.mirror.importer.parser.include[2].transaction[0]=FILEAPPEND
hiero.mirror.importer.parser.include[2].transaction[1]=FILECREATE
hiero.mirror.importer.parser.include[2].transaction[2]=FILEDELETE
hiero.mirror.importer.parser.include[2].transaction[3]=FILEUPDATE
hiero.mirror.importer.parser.include[3].transaction[0]=CONTRACTCREATEINSTANCE
hiero.mirror.importer.parser.include[3].expression="transactionBody.contractCreateInstance.autoRenewAccountId.accountNum == 2000"
hiero.mirror.importer.parser.record.entity.persist.topics=falseTo configure the above scenario via environmental variables, set the following:
HIERO_MIRROR_IMPORTER_PARSER_EXCLUDE_0_ENTITY_0_: 0.0.98
HIERO_MIRROR_IMPORTER_PARSER_INCLUDE_0_TRANSACTION_0_: CRYPTOTRANSFER
HIERO_MIRROR_IMPORTER_PARSER_INCLUDE_1_ENTITY_0_: 0.0.1000
HIERO_MIRROR_IMPORTER_PARSER_INCLUDE_1_ENTITY_1_: 0.0.1001
HIERO_MIRROR_IMPORTER_PARSER_INCLUDE_2_ENTITY_0_: 0.0.101
HIERO_MIRROR_IMPORTER_PARSER_INCLUDE_2_ENTITY_1_: 0.0.102
HIERO_MIRROR_IMPORTER_PARSER_INCLUDE_2_TRANSACTION_0_: FILEAPPEND
HIERO_MIRROR_IMPORTER_PARSER_INCLUDE_2_TRANSACTION_1_: FILECREATE
HIERO_MIRROR_IMPORTER_PARSER_INCLUDE_2_TRANSACTION_2_: FILEDELETE
HIERO_MIRROR_IMPORTER_PARSER_INCLUDE_2_TRANSACTION_3_: FILEUPDATE
HIERO_MIRROR_IMPORTER_PARSER_INCLUDE_3_TRANSACTION_0_: CONTRACTCREATEINSTANCE
HIERO_MIRROR_IMPORTER_PARSER_INCLUDE_3_EXPRESSION_: "transactionBody.contractCreateInstance.autoRenewAccountId.accountNum == 2000"
HIERO_MIRROR_IMPORTER_PARSER_RECORD_ENTITY_PERSIST_TOPICS: "false"When connecting to an AWS S3 bucket that requires authentication (such as a requester pays bucket), you can opt to allow the AWS Default Credentials Provider Chain to handle the authentication for you, instead of providing your static access and secret keys in the config. This will also allow you to take advantage of alternative authorization modes such as AssumeRole. If the mirror node is configured to connect to an S3 bucket that requires authentication, and the static credentials are not provided in the config, the mirror node will default to using this provider. For more information and to see how you can set up your environment to take advantage of this, see the AWS Credentials Documentation When running in Docker or Kubernetes, credentials can be attached in a variety of ways, including by using volumes and secrets to directly add static credentials or an existing AWS credentials file, by using other tools such as Vault or AWS Secrets Manager, and many more.
Docker-compose.yml
volumes:
- ~/.aws/:/root/.aws:roSimilar to the Importer, the gRPC API uses Spring Boot properties to configure the application.
The following table lists the available properties along with their default values. Unless you need to set a non-default
value, it is recommended to only populate overridden properties in the custom application.yml.
| Name | Default | Description |
|---|---|---|
hiero.mirror.grpc.addressbook.cacheExpiry |
2s | The amount of time to cache address book entries |
hiero.mirror.grpc.addressbook.cacheSize |
50 | The maximum number of address book pages to cache |
hiero.mirror.grpc.addressbook.pageDelay |
250ms | The amount of time to sleep between paging for address book entries |
hiero.mirror.grpc.addressbook.pageSize |
10 | The maximum number of address book entries to return in a single page |
hiero.mirror.grpc.addressbook.nodeStakeCacheExpiry |
24h | The amount of time to cache node stake assignments |
hiero.mirror.grpc.addressbook.nodeStakeCacheSize |
5 | The maximum number of versions of node stake assignments to cache |
hiero.mirror.grpc.checkTopicExists |
true | Whether to throw an error when the topic doesn't exist |
hiero.mirror.grpc.db.host |
127.0.0.1 | The IP or hostname used to connect to the database |
hiero.mirror.grpc.db.name |
mirror_node | The name of the database |
hiero.mirror.grpc.db.password |
mirror_grpc_pass | The database password used to connect to the database. |
hiero.mirror.grpc.db.port |
5432 | The port used to connect to the database |
hiero.mirror.grpc.db.statementTimeout |
10000 | The number of milliseconds to wait before timing out a query statement |
hiero.mirror.grpc.db.username |
mirror_grpc | The username used to connect to the database |
hiero.mirror.grpc.endTimeInterval |
30s | How often we should check if a subscription has gone past the end time |
hiero.mirror.grpc.entityCacheSize |
50000 | The maximum size of the cache to store entities used for existence check |
hiero.mirror.grpc.listener.enabled |
true | Whether to listen for incoming massages or not |
hiero.mirror.grpc.listener.interval |
500ms | How often to poll or retry errors (varies by type). Can accept duration units like 50ms, 10s, etc. |
hiero.mirror.grpc.listener.maxBufferSize |
16384 | The maximum number of messages the shared polling listener buffers before sending an error to a client |
hiero.mirror.grpc.listener.maxPageSize |
5000 | The maximum number of messages the listener can return in a single call to the database |
hiero.mirror.grpc.listener.prefetch |
48 | The prefetch queue size for shared listeners |
hiero.mirror.grpc.listener.type |
REDIS | The type of listener to use for incoming messages. Accepts either POLL, REDIS or SHARED_POLL |
hiero.mirror.grpc.netty.maxConcurrentCallsPerConnection |
5 | The maximum number of concurrent calls permitted for each incoming connection |
hiero.mirror.grpc.port |
5600 | The GRPC API port |
hiero.mirror.grpc.retriever.enabled |
true | Whether to retrieve historical massages or not |
hiero.mirror.grpc.retriever.maxPageSize |
1000 | The maximum number of messages the retriever can return in a single call to the database |
hiero.mirror.grpc.retriever.pollingFrequency |
2s | How often to poll for historical messages. Can accept duration units like 50ms, 10s etc |
hiero.mirror.grpc.retriever.timeout |
60s | How long to wait between emission of messages before returning an error |
hiero.mirror.grpc.retriever.unthrottled.maxPageSize |
5000 | The maximum number of messages the retriever can return in a single call to the database when unthrottled |
hiero.mirror.grpc.retriever.unthrottled.maxPolls |
12 | The max number of polls when unthrottled |
hiero.mirror.grpc.retriever.unthrottled.pollingFrequency |
20ms | How often to poll for messages when unthrottled. Can accept duration units like 50ms, 10s etc |
Similar to the Importer, the monitor uses Spring Boot properties to configure the application.
The following table lists the available properties along with their default values. Unless you need to set a non-default
value, it is recommended to only populate overridden properties in the custom application.yml.
See the monitor documentation for more general information about configuring and using the monitor.
| Name | Default | Description |
|---|---|---|
hiero.mirror.monitor.health.importer-lag.clusters |
[] | List of other routable cluster names |
hiero.mirror.monitor.health.importer-lag.enabled |
true | Whether to enable importer lag health check (must also configure a list of clusters to check) |
hiero.mirror.monitor.health.importer-lag.localCluster |
Name of THIS cluster | |
hiero.mirror.monitor.health.importer-lag.prometheusBaseUrl |
Prometheus url to read metrics from | |
hiero.mirror.monitor.health.importer-lag.prometheusPassword |
Password or token to access prometheus | |
hiero.mirror.monitor.health.importer-lag.prometheusUsername |
Username to access prometheus | |
hiero.mirror.monitor.health.importer-lag.thresholdSeconds |
20 | Minimum lag to consider cluster unhealthy |
hiero.mirror.monitor.health.importer-lag.timeout |
5s | HTTP timeout for prometheus requests |
hiero.mirror.monitor.health.release.cacheExpiry |
30s | The amount of time to cache cluster release health status |
hiero.mirror.monitor.health.release.enabled |
false | Whether to enable cluster release health check |
hiero.mirror.monitor.health.release.failWhenInactive |
false | Whether to enable Status.DOWN when publisher or subscriber metric rates go to zero. |
hiero.mirror.monitor.mirrorNode.grpc.host |
"" | The hostname of the mirror node's gRPC API |
hiero.mirror.monitor.mirrorNode.grpc.port |
5600 | The port of the mirror node's gRPC API |
hiero.mirror.monitor.mirrorNode.rest.host |
"" | The hostname of the mirror node's REST API |
hiero.mirror.monitor.mirrorNode.rest.port |
443 | The port of the mirror node's REST API |
hiero.mirror.monitor.mirrorNode.restJava.host |
"" | The hostname of the mirror node's REST Java API |
hiero.mirror.monitor.mirrorNode.restJava.port |
443 | The port of the mirror node's REST Java API |
hiero.mirror.monitor.network |
TESTNET | Which network to connect to. Automatically populates the main node & mirror node endpoints. Can be MAINNET, PREVIEWNET, TESTNET or OTHER |
hiero.mirror.monitor.nodes[].accountId |
"" | The consensus node's account ID |
hiero.mirror.monitor.nodes[].certHash |
"" | The consensus node's certificate hash used for TLS certificate verification |
hiero.mirror.monitor.nodes[].host |
"" | The consensus node's hostname |
hiero.mirror.monitor.nodes[].nodeId |
"" | The consensus node's node ID |
hiero.mirror.monitor.nodes[].port |
50211 | The consensus node's port |
hiero.mirror.monitor.nodeValidation.enabled |
true | Whether to validate and remove invalid or down nodes permanently before publishing |
hiero.mirror.monitor.nodeValidation.frequency |
1d | The amount of time between validations of the network. If not specified, millisecond is implied as the unit. |
hiero.mirror.monitor.nodeValidation.maxAttempts |
8 | The number of times the monitor should attempt to receive a healthy response from a node before marking it as unhealthy. |
hiero.mirror.monitor.nodeValidation.maxBackoff |
2s | The maximum amount of time to wait in between attempts when trying to validate a node |
hiero.mirror.monitor.nodeValidation.maxEndpointsPerNode |
1 | The maximum number of endpoints per node to consider. Not applicable to manually configured nodes in hiero.mirror.monitor.nodes. |
hiero.mirror.monitor.nodeValidation.maxNodes |
30 | The maximum number of distinct nodes to validate and publish transactions to |
hiero.mirror.monitor.nodeValidation.maxThreads |
25 | The maximum number of threads to use for node validation |
hiero.mirror.monitor.nodeValidation.minBackoff |
500ms | The minimum amount of time to wait in between attempts when trying to validate a node |
hiero.mirror.monitor.nodeValidation.requestTimeout |
15s | The amount of time to wait for a validation request before timing out |
hiero.mirror.monitor.nodeValidation.retrieveAddressBook |
true | Whether to download the address book from the mirror node and use those nodes to publish transactions |
hiero.mirror.monitor.nodeValidation.retryBackoff |
2m | The fixed amount of time to wait in between unsuccessful node validations that result in no valid nodes |
hiero.mirror.monitor.nodeValidation.tls |
BOTH | Whether to communicate to consensus nodes over TLS, PLAINTEXT, or BOTH. |
hiero.mirror.monitor.operator.accountId |
"0.0.2" | Operator account ID used to pay for transactions |
hiero.mirror.monitor.operator.privateKey |
Genesis key | Operator ED25519 private key used to sign transactions in hex encoded DER format |
hiero.mirror.monitor.publish.async |
true | Whether to use the SDK's asynchronous execution or synchronous. Synchronous requires more monitor responseThreads. |
hiero.mirror.monitor.publish.batchDivisor |
100 | The divisor used to calculate batch size when generating transactions |
hiero.mirror.monitor.publish.clients |
4 | How many total SDK clients to publish transactions. Clients will be used in a round-robin fashion |
hiero.mirror.monitor.publish.enabled |
true | Whether to enable transaction publishing |
hiero.mirror.monitor.publish.nodeMaxBackoff |
1m | The maximum backoff time for any node in the network |
hiero.mirror.monitor.publish.responseThreads |
40 | How many threads to use to resolve the asynchronous responses |
hiero.mirror.monitor.publish.scenarios |
A map of scenario name to publish scenarios. The name is used as a unique identifier in logs, metrics, and the REST API | |
hiero.mirror.monitor.publish.scenarios.<name>.duration |
How long this scenario should publish transactions. Leave empty for infinite | |
hiero.mirror.monitor.publish.scenarios.<name>.enabled |
true | Whether this publish scenario is enabled |
hiero.mirror.monitor.publish.scenarios.<name>.limit |
0 | How many transactions to publish before halting. 0 for unlimited |
hiero.mirror.monitor.publish.scenarios.<name>.logResponse |
false | Whether to log the response from HAPI |
hiero.mirror.monitor.publish.scenarios.<name>.properties |
{} | Key/value pairs used to configure the TransactionSupplier |
hiero.mirror.monitor.publish.scenarios.<name>.receiptPercent |
0.0 | The percentage of receipts to retrieve from HAPI. Accepts values between 0-1 |
hiero.mirror.monitor.publish.scenarios.<name>.recordPercent |
0.0 | The percentage of records to retrieve from HAPI. Accepts values between 0-1 |
hiero.mirror.monitor.publish.scenarios.<name>.retry.maxAttempts |
1 | The maximum number of times a scenario transaction will be attempted |
hiero.mirror.monitor.publish.scenarios.<name>.timeout |
12s | How long to wait for the transaction result |
hiero.mirror.monitor.publish.scenarios.<name>.tps |
1.0 | The rate at which transactions will publish |
hiero.mirror.monitor.publish.scenarios.<name>.type |
The type of transaction to publish. See the TransactionType enum for a list of possible values |
|
hiero.mirror.monitor.publish.statusFrequency |
10s | How often to log publishing statistics |
hiero.mirror.monitor.publish.warmupPeriod |
30s | The amount of time the publisher should ramp up its rate before reaching its stable (maximum) rate |
hiero.mirror.monitor.subscribe.clients |
1 | How many SDK clients should be created to subscribe to mirror node APIs. Clients will be used in a round-robin fashion |
hiero.mirror.monitor.subscribe.enabled |
true | Whether to enable subscribing to mirror node APIs to verify published transactions |
hiero.mirror.monitor.subscribe.grpc |
A map of scenario name to gRPC subscriber scenarios. The name is used as a unique identifier in logs, metrics, and the REST API | |
hiero.mirror.monitor.subscribe.grpc.<name>.duration |
How long to stay subscribed to the API | |
hiero.mirror.monitor.subscribe.grpc.<name>.enabled |
true | Whether this subscribe scenario is enabled |
hiero.mirror.monitor.subscribe.grpc.<name>.limit |
0 | How many transactions to receive before halting. 0 for unlimited |
hiero.mirror.monitor.subscribe.grpc.<name>.retry.maxAttempts |
2^63 - 1 | How many consecutive retry attempts before giving up connecting to the API |
hiero.mirror.monitor.subscribe.grpc.<name>.retry.maxBackoff |
8s | The maximum amount of time to wait between retry attempts |
hiero.mirror.monitor.subscribe.grpc.<name>.retry.minBackoff |
500ms | The initial amount of time to wait between retry attempts |
hiero.mirror.monitor.subscribe.grpc.<name>.startTime |
The start time passed to the gRPC API. Defaults to current time if not set | |
hiero.mirror.monitor.subscribe.grpc.<name>.subscribers |
1 | How many concurrent subscribers should be instantiated for this scenario |
hiero.mirror.monitor.subscribe.grpc.<name>.topicId |
Which topic to subscribe to | |
hiero.mirror.monitor.subscribe.rest |
A map of scenario name to REST subscriber scenarios. The name is used as a unique identifier in logs, metrics, and the REST API | |
hiero.mirror.monitor.subscribe.rest.<name>.duration |
How long to stay subscribed to the API | |
hiero.mirror.monitor.subscribe.rest.<name>.enabled |
true | Whether this subscribe scenario is enabled |
hiero.mirror.monitor.subscribe.rest.<name>.limit |
0 | How many transactions to receive before halting. 0 for unlimited |
hiero.mirror.monitor.subscribe.rest.<name>.publishers |
[] | A list of publisher scenario names to consider for sampling |
hiero.mirror.monitor.subscribe.rest.<name>.retry.maxAttempts |
16 | How many consecutive retry attempts before giving up connecting to the API |
hiero.mirror.monitor.subscribe.rest.<name>.retry.maxBackoff |
1s | The maximum amount of time to wait between retry attempts |
hiero.mirror.monitor.subscribe.rest.<name>.retry.minBackoff |
500ms | The initial amount of time to wait between retry attempts |
hiero.mirror.monitor.subscribe.rest.<name>.samplePercent |
1.0 | The percentage of transactions to verify against the API. Accepts values between 0-1 |
hiero.mirror.monitor.subscribe.rest.<name>.timeout |
5s | Maximum amount of time to wait for a API call to retrieve data |
hiero.mirror.monitor.subscribe.statusFrequency |
10s | How often to log subscription statistics |
The REST API supports loading configuration from YAML or environment variables. By default, it loads a file named
application.yml or application.yaml in each of the search paths (see below). The file name can be changed by setting
the CONFIG_NAME environment variable. A custom location can be loaded by setting the CONFIG_PATH environment
variable. The configuration is loaded in the following order with the latter configuration overwriting (technically
recursively merged into) the current configuration:
./config/application.yml./application.yml${CONFIG_PATH}/application.yml- Environment variables that start with
HIERO_MIRROR_REST_(e.g.HIERO_MIRROR_REST_MAXLIMIT=100)
The following table lists the available properties along with their default values. Unless you need to set a non-default
value, it is recommended to only populate overridden properties in the custom application.yml.
| Name | Default | Description |
|---|---|---|
hiero.mirror.rest.cache.entityId.maxAge |
1800 | The number of seconds until the entityId cache entry expires |
hiero.mirror.rest.cache.entityId.maxSize |
100000 | The maximum number of entries in the entityId cache |
hiero.mirror.rest.cache.feeSchedule.maxAge |
3600 | The number of seconds until a fee schedule cache entry expires |
hiero.mirror.rest.cache.feeSchedule.maxSize |
1000 | The maximum number of entries in the fee schedule cache |
hiero.mirror.rest.cache.response.enabled |
false | Whether or not the Redis based REST API response cache is enabled. If so, Redis itself must be enabled and properly configured. |
hiero.mirror.rest.cache.response.compress |
true | Store cached response in gzip format and serve gzipped if supported by client |
hiero.mirror.rest.cache.response.compressThreshold |
150 | The minimum response body size to compress |
hiero.mirror.rest.cache.token.maxSize |
100000 | The maximum number of entries in the token cache |
hiero.mirror.rest.chainId |
"0x128" | The network chain ID used for Ethereum transactions |
hiero.mirror.rest.db.host |
127.0.0.1 | The IP or hostname used to connect to the database |
hiero.mirror.rest.db.name |
mirror_node | The name of the database |
hiero.mirror.rest.db.password |
mirror_api_pass | The database password the processor uses to connect. |
hiero.mirror.rest.db.pool.connectionTimeout |
20000 | The number of milliseconds to wait before timing out when connecting a new database client |
hiero.mirror.rest.db.pool.maxConnections |
10 | The maximum number of clients the database pool can contain |
hiero.mirror.rest.db.pool.statementTimeout |
20000 | The number of milliseconds to wait before timing out a query statement |
hiero.mirror.rest.db.port |
5432 | The port used to connect to the database |
hiero.mirror.rest.db.primaryHost |
"" | Optional IP or hostname used to connect to the primary instance |
hiero.mirror.rest.db.sslMode |
DISABLE | The ssl level of protection against Eavesdropping, Man-in-the-middle (MITM) and Impersonation on the db connection. Accepts either DISABLE, ALLOW, PREFER, REQUIRE, VERIFY_CA or VERIFY_FULL. |
hiero.mirror.rest.db.tls.ca |
"" | The path to the certificate authority used by the database for secure connections |
hiero.mirror.rest.db.tls.cert |
"" | The path to the public key the client should use to securely connect to the database |
hiero.mirror.rest.db.tls.enabled |
false | Whether TLS should be used for the database connection |
hiero.mirror.rest.db.tls.key |
"" | The path to the private key the client should use to securely connect to the database |
hiero.mirror.rest.db.username |
mirror_api | The username the processor uses to connect to the database |
hiero.mirror.rest.log.level |
info | The logging level. Can be trace, debug, info, warn, error or fatal. |
hiero.mirror.rest.log.sampleRate |
0.1 | The rate at which to log non-error access requests. |
hiero.mirror.rest.metrics.config |
See application.yml | The configuration to pass to Swagger stats (https://swaggerstats.io/guide/conf.html#options) |
hiero.mirror.rest.metrics.config.authentication |
true | Whether access to metrics for the REST API is authenticated |
hiero.mirror.rest.metrics.config.username |
mirror_api_metrics | The REST API metrics username to access the dashboard |
hiero.mirror.rest.metrics.config.password |
mirror_api_metrics_pass | The REST API metrics password to access the dashboard |
hiero.mirror.rest.metrics.config.uriPath |
'/swagger' | The REST API metrics uri path |
hiero.mirror.rest.metrics.enabled |
true | Whether metrics should be collected and exposed for scraping |
hiero.mirror.rest.network |
TESTNET | Which network to use. Recognized names are demo, mainnet, other, testnet, and previewnet. Other names are allowed but are treated as development or test networks. |
hiero.mirror.rest.openapi.specFileName |
'openapi' | The file name of the OpenAPI spec file |
hiero.mirror.rest.openapi.swaggerUIPath |
'/docs' | Swagger UI path for your REST API |
hiero.mirror.rest.openapi.validation.enabled |
false | Whether or not the OpenAPI request validation is enabled. |
hiero.mirror.rest.port |
5551 | The REST API port |
hiero.mirror.rest.query.bindTimestampRange |
false | Whether to bind the timestamp range to maxTimestampRange |
hiero.mirror.rest.query.maxFileAttempts |
12 | The maximum amount of times to query for Hedera files when the contents are not valid. |
hiero.mirror.rest.query.maxRecordFileCloseInterval |
10s | The maximum close interval of record files to limit the time partitions to scan. Note the default value is larger than the actual network close interval |
hiero.mirror.rest.query.maxRepeatedQueryParameters |
100 | The maximum number of times any query parameter can be repeated in the uri |
hiero.mirror.rest.query.maxScheduledTransactionConsensusTimestampRange |
89285m | The maximum amount of time of a scheduled transaction's consensus timestamp from its valid start timestamp. |
hiero.mirror.rest.query.maxTimestampRange |
7d | The maximum amount of time a timestamp range query param can span for some APIs. |
hiero.mirror.rest.query.maxTransactionConsensusTimestampRange |
35m | The maximum amount of time of a transaction's consensus timestamp from its valid start timestamp. |
hiero.mirror.rest.query.maxTransactionsTimestampRange |
60d | The maximum timestamp range to list transactions. |
hiero.mirror.rest.query.maxValidStartTimestampDrift |
1s | The maximum allowed drift when querying transactions by transaction ID where the consensus timestamp may be less than the valid start timestamp. Sets the lower bound for timestamp queries |
hiero.mirror.rest.query.strictTimestampParam |
true | Enables strict checking of timestamp query param (currently only effects /api/v1/accounts/{id}?timestamp={timestamp} |
hiero.mirror.rest.query.topicMessageLookup |
false | Enables topic message lookup querying |
| 'hiero.mirror.rest.query.transactions.precedingTransactionTypes' | [11, 15] | Array of transaction types to be included in transactions by account id response when there is no parent and nonce is non-zero. |
hiero.mirror.rest.redis.commandTimeout |
10000 | The amount of time in milliseconds to wait before a Redis command will timeout |
hiero.mirror.rest.redis.connectTimeout |
10000 | The amount of time in milliseconds to wait for a connection to Redis |
hiero.mirror.rest.redis.enabled |
true | Whether Redis should be used as a caching layer for the database |
hiero.mirror.rest.redis.maxBackoff |
128000 | The maximum amount of time in milliseconds to wait in between retrying Redis connection errors |
hiero.mirror.rest.redis.maxMemory |
250Mb | The maximum amount of memory that Redis should be configured to use for caching |
hiero.mirror.rest.redis.maxMemoryPolicy |
allkeys-lfu | The key eviction policy Redis should use when the max memory threshold has been reached |
hiero.mirror.rest.redis.maxRetriesPerRequest |
1 | The maximum number of times that the Redis command should be retried |
hiero.mirror.rest.redis.sentinel.enabled |
false | Whether Redis sentinel should be enabled |
hiero.mirror.rest.redis.sentinel.host |
127.0.0.1 | The Redis sentinel host |
hiero.mirror.rest.redis.sentinel.name |
"mirror" | The Redis sentinel master group name |
hiero.mirror.rest.redis.sentinel.password |
"" | The Redis sentinel password |
hiero.mirror.rest.redis.sentinel.port |
26379 | The Redis sentinel port |
hiero.mirror.rest.redis.uri |
redis://127.0.0.1:6379 | The URI to use when connecting to Redis |
hiero.mirror.rest.response.compression |
true | Whether content negotiation should occur to compress response bodies if requested |
hiero.mirror.rest.response.headers.default |
See application.yml | The default headers to add to every response. |
hiero.mirror.rest.response.headers.path |
See application.yml | The per path headers to add to every response. The key is the route name and the value is a header map. |
hiero.mirror.rest.response.headers.timeout |
630000 | The number of milliseconds the parser will wait to receive the complete HTTP headers. |
hiero.mirror.rest.response.includeHostInLink |
false | Whether to include the hostname and port in the next link in the response |
hiero.mirror.rest.response.keepAliveTimeout |
620000 | The number of milliseconds of inactivity a server needs to wait for additional incoming data, after it has finished writing the last response, before a socket will be destroyed. |
hiero.mirror.rest.response.limit.default |
25 | The default value for the limit parameter that controls the REST API response size |
hiero.mirror.rest.response.limit.max |
100 | The maximum size the limit parameter can be that controls the REST API response size |
hiero.mirror.rest.response.limit.tokenBalance.multipleAccounts |
50 | The maximum number of token balances per account for endpoints which return such info for multiple accounts |
hiero.mirror.rest.response.limit.tokenBalance.singleAccount |
1000 | The maximum number of token balances per account for endpoints which return such info for a single account |
hiero.mirror.rest.users |
[] | Array of user credentials for per-customer response limits. Each user object contains username, password, and optional limit (overrides max). |
Similar to the Importer, the REST Java API uses Spring Boot properties to configure the application.
The following table lists the available properties along with their default values. Unless you need to set a non-default
value, it is recommended to only populate overridden properties in the custom application.yml.
| Name | Default | Description |
|---|---|---|
hiero.mirror.restJava.db.host |
127.0.0.1 | The IP or hostname used to connect to the database |
hiero.mirror.restJava.db.name |
mirror_node | The name of the database |
hiero.mirror.restJava.db.password |
mirror_rest_java_pass | The database password used to connect to the database |
hiero.mirror.restJava.db.port |
5432 | The port used to connect to the database |
hiero.mirror.restJava.db.sslMode |
DISABLE | The SSL level. Accepts either DISABLE, ALLOW, PREFER, REQUIRE, VERIFY_CA or VERIFY_FULL. |
hiero.mirror.restJava.db.statementTimeout |
10000 | The number of milliseconds to wait before timing out a query statement |
hiero.mirror.restJava.db.username |
mirror_rest_java | The username used to connect to the database |
hiero.mirror.restJava.fee.refreshInterval |
10m | How often to check for fee schedule updates from the database. Can accept duration units like 10s, 2m etc. |
hiero.mirror.restJava.maxRequestBodySize |
130KB | The maximum size of a request body accepted by the rest-java API |
hiero.mirror.restJava.network |
TESTNET | Which network to use. Can be either DEMO, MAINNET, PREVIEWNET, TESTNET or OTHER. |
hiero.mirror.restJava.network.unreleasedSupplyAccounts |
2-2, 42-42, 44-71, 73-87, 99-100, 200-349, 400-750 | Account ranges holding unreleased HBAR supply, excluded from circulating supply calculations |
hiero.mirror.restJava.query.maxFileAttempts |
12 | The maximum amount of times to query for Hedera files when the contents are not valid. |
hiero.mirror.restJava.response.headers.defaults |
See application.yml | The default headers to add to every response. For each header, specify its name: value |
hiero.mirror.restJava.response.headers.path |
See application.yml | Override default or add headers per path to add to every response. The key is the controller request mapping, then for each header, specify its name: value |
The Rosetta API supports loading configuration from YAML. By default, it loads a file named
application.yml in each of the search paths (see below). The configuration is loaded in the following order with the
latter configuration overwriting (technically recursively merged into) the current configuration:
- Hard coded configuration embedded in the code
./application.yml${HIERO_MIRROR_ROSETTA_API_CONFIG}environment variable to custom values file ( e.g.HIERO_MIRROR_ROSETTA_API_CONFIG=$HOME/application.yml)- Environment variables that start with
HIERO_MIRROR_ROSETTA_(e.g.HIERO_MIRROR_ROSETTA_API_VERSION=1.4.2)
The following table lists the available properties along with their default values.
| Name | Default | Description |
|---|---|---|
hiero.mirror.rosetta.cache.entity.maxSize |
524288 | The max number of entities to cache |
hiero.mirror.rosetta.db.host |
127.0.0.1 | The IP or hostname used to connect to the database |
hiero.mirror.rosetta.db.name |
mirror_node | The name of the database |
hiero.mirror.rosetta.db.password |
mirror_rosetta_pass | The database password the processor uses to connect |
hiero.mirror.rosetta.db.pool.maxIdleConnections |
20 | The maximum number of idle database connections |
hiero.mirror.rosetta.db.pool.maxLifetime |
30 | The maximum lifetime of a database connection in minutes |
hiero.mirror.rosetta.db.pool.maxOpenConnections |
100 | The maximum number of open database connections |
hiero.mirror.rosetta.db.port |
5432 | The port used to connect to the database |
hiero.mirror.rosetta.db.statementTimeout |
20 | The number of seconds to wait before timing out a query statement |
hiero.mirror.rosetta.db.username |
mirror_rosetta | The username the processor uses to connect to the database |
hiero.mirror.rosetta.http.idleTimeout |
10000000000 | The maximum amount of time in nanoseconds to wait for the next request when keep-alives are enabled |
hiero.mirror.rosetta.http.readHeaderTimeout |
3000000000 | The maximum amount of time in nanoseconds to read request headers |
hiero.mirror.rosetta.http.readTimeout |
5000000000 | The maximum duration in nanoseconds for reading the entire request, including the body |
hiero.mirror.rosetta.http.writeTimeout |
10000000000 | The maximum duration in nanoseconds before timing out writes of the response |
hiero.mirror.rosetta.log.level |
info | The log level |
hiero.mirror.rosetta.network |
DEMO | Which network to use. Can be either DEMO, MAINNET, PREVIEWNET, TESTNET or OTHER. |
hiero.mirror.rosetta.nodeRefreshInterval |
24h | The fixed period between scheduled network address book updates. Can accept values like 10m, 2h |
hiero.mirror.rosetta.nodeVersion |
0 | The default canonical version of the node runtime |
hiero.mirror.rosetta.nodes |
{} | A map of main nodes with its service endpoint as the key and the node account id as its value |
hiero.mirror.rosetta.online |
true | The default online mode of the Rosetta interface |
hiero.mirror.rosetta.port |
5700 | The REST API port |
hiero.mirror.rosetta.shutdownTimeout |
10s | The time to wait for the server to shutdown gracefully |
Similar to the Importer, the web3 API uses Spring Boot properties to configure the application.
The following table lists the available properties along with their default values. Unless you need to set a non-default
value, it is recommended to only populate overridden properties in the custom application.yml.
| Name | Default | Description |
|---|---|---|
hiero.mirror.web3.api.<name>.request.timeout |
Per-endpoint request timeout override. Supported names: call (/contracts/call), opcodes (/contracts/results/{id}/opcodes). Falls back to requestTimeout when unset. |
|
hiero.mirror.web3.api.opcodes.request.timeout |
10s | Request timeout for the /contracts/results/{transactionIdOrHash}/opcodes endpoint. |
hiero.mirror.web3.cache.contract |
expireAfterAccess=60m,maximumSize=1000,recordStats | Cache configuration for contract |
hiero.mirror.web3.cache.contractSlots |
expireAfterAccess=5m,maximumSize=3000,recordStats | Cache for contract slots queried within a findStorage query |
hiero.mirror.web3.cache.contractState |
expireAfterWrite=2s,maximumSize=25000,recordStats | Cache configuration for contract state |
hiero.mirror.web3.cache.enableBatchContractSlotCaching |
true | Flag enabling batch contract slot caching |
hiero.mirror.web3.cache.entity |
expireAfterWrite=1s,maximumSize=10000,recordStats | Cache configuration for entity |
hiero.mirror.web3.cache.fee |
expireAfterWrite=60m,maximumSize=20,recordStats | Cache configuration for fee related info |
hiero.mirror.web3.cache.maxSlotKeysPerBatch |
100 | The maximum number of slot keys to store in the cache per contract. |
hiero.mirror.web3.cache.sharedWritableState |
expireAfterAccess=5m,maximumSize=100000,recordStats | Cache configuration for the shared writable state used across contract calls |
hiero.mirror.web3.cache.slotsPerContract |
expireAfterAccess=5m,maximumSize=1500 | Cache for slot keys per contract. Separate instance used for the value of each entry of the contractSlots cache |
hiero.mirror.web3.cache.systemAccount |
expireAfterWrite=10m,maximumSize=1000,recordStats | Cache for the system accounts that should prevent constantly querying them from the db on each request, unless balanceOf call is made. |
hiero.mirror.web3.cache.systemFile |
expireAfterWrite=10m,maximumSize=20,recordStats | Cache configuration for system files related info |
hiero.mirror.web3.cache.token |
expireAfterWrite=1s,maximumSize=10000,recordStats | Cache configuration for token related info |
hiero.mirror.web3.db.host |
127.0.0.1 | The IP or hostname used to connect to the database |
hiero.mirror.web3.db.name |
mirror_node | The name of the database |
hiero.mirror.web3.db.password |
mirror_web3_pass | The database password used to connect to the database |
hiero.mirror.web3.db.port |
5432 | The port used to connect to the database |
hiero.mirror.web3.db.sslMode |
DISABLE | The ssl level of protection against eavesdropping, man-in-the-middle (MITM) and impersonation on the db connection. Accepts either DISABLE, ALLOW, PREFER, REQUIRE, VERIFY_CA or VERIFY_FULL. |
hiero.mirror.web3.db.statementTimeout |
3000 | The number of milliseconds to wait before timing out a query statement |
hiero.mirror.web3.db.username |
mirror_web3 | The username used to connect to the database |
hiero.mirror.web3.evm.blockHashWindow |
256 | The number of most recent blocks (relative to the current block) for which the BLOCKHASH opcode can resolve a hash. |
hiero.mirror.web3.evm.entityNumBuffer |
1000 | A buffer added to the max known entity number to prevent contract call simulations from generating IDs that may conflict with entities persisted by the importer module. |
hiero.mirror.web3.evm.estimateGasIterationThresholdPercent |
0.10 | Percent used during gas estimation algorithm |
hiero.mirror.web3.evm.evmVersion |
v0.70 | The besu EVM version to be used as dynamic one |
hiero.mirror.web3.evm.maxFileAttempts |
12 | The maximum amount of times to query for Hedera files when the contents are not valid. |
hiero.mirror.web3.evm.maxGasAllowance |
100000000000000 | Maximum tinybars the simulated Ethereum transaction payer will cover for gas during debug replay. |
hiero.mirror.web3.evm.maxGasEstimateRetriesCount |
20 | Estimate gas contract call retry threshold |
hiero.mirror.web3.evm.maxGasRefundPercentage |
100% | Maximal percent of gas refunding |
hiero.mirror.web3.evm.maxGasLimit |
15000000 | The maximum amount of gas limit the user can supply in the request. |
hiero.mirror.web3.evm.minimumAccountBalance |
100000000000000000 | The minimum balance to use for an account for non-balance opcodes. |
hiero.mirror.web3.evm.network |
TESTNET | Which network to use. Can be either MAINNET, PREVIEWNET, TESTNET or OTHER |
hiero.mirror.web3.evm.properties |
{} | Custom properties to pass to the consensus node EVM library |
hiero.mirror.web3.evm.sharedWritableState |
false | Enables a shared writable state cache across contract calls within a session. |
hiero.mirror.web3.evm.trace.enabled |
false | Flag enabling tracer |
hiero.mirror.web3.evm.trace.contract |
[] | A set with contract addresses to filter. By default it is empty to indicate it will trace all contract addresses. |
hiero.mirror.web3.evm.trace.status |
[] | A set with frame statuses to filter. By default it is empty to indicate it will trace all frames regardless of status. |
hiero.mirror.web3.evm.validatePayerBalance |
false | Feature flag to enable payer balance validation for contract calls. When enabled, validates that the sender has sufficient balance when gasPrice or value is greater than zero. |
hiero.mirror.web3.maxPayloadLogSize |
300 | The maximum number of characters to use to log the request payload. |
hiero.mirror.web3.opcode.tracer.enabled |
true | Whether the /contracts/results/{transactionIdOrHash}/opcodes endpoint is enabled |
hiero.mirror.web3.opcode.tracer.maxOpcodes |
20000 | Maximum number of opcodes recorded per trace request. Beyond this the trace is truncated with a single marker opcode and the remaining opcodes are dropped. Bounds the base opcode list independently of the memory/stack/storage budgets. |
hiero.mirror.web3.opcode.tracer.maxMemoryWords |
3000000 | Maximum total number of 32-byte EVM memory words captured across all opcodes of a trace (default 3,000,000 ≈ 96 MB). Once reached the trace is truncated and the remaining opcodes are dropped. |
hiero.mirror.web3.opcode.tracer.maxStack |
1000000 | Maximum total number of stack items captured across all opcodes of a trace. Once reached the trace is truncated and the remaining opcodes are dropped. |
hiero.mirror.web3.opcode.tracer.maxStorage |
100000 | Maximum total number of storage entries captured across all opcodes of a trace. Once reached the trace is truncated and the remaining opcodes are dropped. |
hiero.mirror.web3.requestTimeout |
4s | The default maximum amount of time to wait for a request to process when no per-endpoint timeout is configured. |
hiero.mirror.web3.throttle.gasLimitRefundPercent |
100 | Maximum gas percent from the passed gas limit in a request to return in the throttle bucket after the request is processed |
hiero.mirror.web3.throttle.gasPerSecond |
1500000000 | Maximum gas limit that can be processed per second. The max value for this property is 1000000000. In case greater gas limit needs to be allowed per second, please refer to the property below. |
hiero.mirror.web3.throttle.opcodeRequestsPerSecond |
1 | Maximum RPS limit for /contracts/results/{transactionIdOrHash}/opcodes endpoint. Note that this endpoint is heavy and the value needs to be low. |
hiero.mirror.web3.throttle.request[].action |
LOG | The action to take if the request filter matches. One of LOG, REJECT, or THROTTLE. |
hiero.mirror.web3.throttle.request[].filters[].expression |
The expression or field value to filter the request field | |
hiero.mirror.web3.throttle.request[].filters[].field |
DATA | The field to target for filtering requests |
hiero.mirror.web3.throttle.request[].filters[].type |
CONTAINS | How the field should be matched against the request field |
hiero.mirror.web3.throttle.request[].limit |
Long.MAX_VALUE | Process-lifetime cap on how many matching requests receive the action. Does not reset until restart. Ignored for REJECT so a block rule cannot be exhausted. |
hiero.mirror.web3.throttle.request[].rate |
100 | The rate at which the action should apply to matched requests. |
hiero.mirror.web3.throttle.requestsPerSecond |
500 | Maximum RPS limit |