Skip to content

configuration.md

Latest commit

 

History

History
737 lines (668 loc) · 152 KB

configuration.md

File metadata and controls

737 lines (668 loc) · 152 KB

Configuration

The components of the Mirror Node all support loading configuration from an application.yml file or via the environment.

Default Values

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.

Common

Some variables are common to more than one module.

Name Default Description
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.

Importer

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.enabled false Whether to enable block stream source
hiero.mirror.importer.block.frequency 100ms 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.nodes[].host The hostname or IP of the block node server.
hiero.mirror.importer.block.nodes[].port 40840 The port of the block node server.
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.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. If the last block is streamed from a block node, AUTO falls back to BLOCK_NODE.
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.maxStreamResponseSize 8MB 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.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.pathType ACCOUNT_ID The bucket structure path type to assume for all consensus nodes when downloading streams via the stream file provider. Either ACCOUNT_ID (legacy), NODE_ID (HIP-679), or AUTO (detect at runtime, per consensus node)
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 30s 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.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.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.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)

Transaction and Entity Filtering

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 Support

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 transactionBody and transactionRecord properties 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) or T(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.

Filtering Example

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.

application.yml

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: false

application.properties

To 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=false

Environment variables

To 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"

Connect to S3 with the Default Credentials Provider

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:ro

GRPC API

Similar 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.maxPageDelay 250ms The maximum amount of time to sleep between paging for address book entries
hiero.mirror.grpc.addressbook.minPageDelay 100ms The minimum 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.executorCoreThreadCount 10 The number of core threads
hiero.mirror.grpc.netty.executorMaxThreadCount 1000 The maximum allowed number of threads
hiero.mirror.grpc.netty.maxConnectionIdle 10m The max amount of time a connection can be idle before it will be gracefully terminated
hiero.mirror.grpc.netty.maxConcurrentCallsPerConnection 5 The maximum number of concurrent calls permitted for each incoming connection
hiero.mirror.grpc.netty.maxInboundMessageSize 1024 The maximum message size allowed to be received on the server
hiero.mirror.grpc.netty.maxInboundMetadataSize 1024 The maximum size of metadata allowed to be received
hiero.mirror.grpc.netty.threadKeepAliveTime 1m The amount of time for which threads may remain idle before being terminated
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.threadMultiplier 4 Multiplied by the CPU count to calculate the number of retriever threads
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

Monitor

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.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

REST API

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:

  1. ./config/application.yml
  2. ./application.yml
  3. ${CONFIG_PATH}/application.yml
  4. 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.token.maxSize 100000 The maximum number of entries in the token 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.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.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.metrics.ipMetrics false Whether metrics should be associated with a masked client IP label
hiero.mirror.rest.network.unreleasedSupplyAccounts [0.0.2, 0.0.42, ...] An array of account IDs whose aggregated balance subtracted from the total supply is the released supply
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.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.includeHostInLink false Whether to include the hostname and port in the next link in the response
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).
hiero.mirror.rest.stateproof.enabled false Whether to enable stateproof REST API or not
hiero.mirror.rest.stateproof.streams.accessKey "" The cloud storage access key
hiero.mirror.rest.stateproof.streams.bucketName The cloud storage bucket name to download streamed files. This value takes priority over network hardcoded bucket names regardless of hiero.mirror.rest.stateproof.streams.network
hiero.mirror.rest.stateproof.streams.cloudProvider S3 The cloud provider to download files from. Either S3 or GCP
hiero.mirror.rest.stateproof.streams.endpointOverride Can be specified to download streams from a source other than S3 and GCP. Should be S3 compatible
hiero.mirror.rest.stateproof.streams.gcpProjectId GCP project id to bill for requests to GCS bucket which has Requester Pays enabled.
hiero.mirror.rest.stateproof.streams.httpOptions.connectTimeout 2000 The number of milliseconds to wait to establish a connection
hiero.mirror.rest.stateproof.streams.httpOptions.timeout 5000 The number of milliseconds a request can take before automatically being terminated
hiero.mirror.rest.stateproof.streams.maxRetries 3 The maximum amount of retries to perform for a cloud storage download request.
hiero.mirror.rest.stateproof.streams.network DEMO Which network to use. Can be either DEMO, MAINNET, TESTNET, PREVIEWNET or OTHER
hiero.mirror.rest.stateproof.streams.region us-east-1 The region associated with the bucket
hiero.mirror.rest.stateproof.streams.secretKey "" The cloud storage secret key

Enable State Proof Alpha

To enable State Proof logic the REST API configurations must updated to allow for communication with cloud buckets to pull down the necessary files (address book, signatures files and record file). The process involves setting the properties under hiero.mirror.rest.stateproof as documented above REST API Config.

An example configuration is provided below

hiero:
  mirror:
    rest:
      stateproof:
        enabled: true
        streams:
          accessKey: <accessKey>
          bucketName: "hedera-mainnet-streams"
          cloudProvider: "GCP"
          network: "MAINNET"
          region: "us-east-1"
          secretKey: <secretKey>

REST Java API

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.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.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

Rosetta API

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:

  1. Hard coded configuration embedded in the code
  2. ./application.yml
  3. ${HIERO_MIRROR_ROSETTA_API_CONFIG} environment variable to custom values file ( e.g. HIERO_MIRROR_ROSETTA_API_CONFIG=$HOME/application.yml)
  4. 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

Web3 API

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.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=10m,maximumSize=20,recordStats Cache configuration for fee related info
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.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.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.67 The besu EVM version to be used as dynamic one
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.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 false Whether the /contracts/results/{transactionIdOrHash}/opcodes endpoint is exposed
hiero.mirror.web3.requestTimeout 10000 The maximum amount of time to wait for a request to process.
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.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 The maximum amount of requests that the action should be applied to requests that match.
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