Chain Configs

Some chains allow the node operator to provide a custom configuration. MetalGo can read chain configurations from files and pass them to the corresponding chains on initialization.

MetalGo looks for these files in the directory specified by --chain-config-dir MetalGo flag, as documented here. If omitted, value defaults to $HOME/.metalgo/configs/chains. This directory can have sub-directories whose names are chain IDs or chain aliases. Each sub-directory contains the configuration for the chain specified in the directory name. Each sub-directory should contain a file named config, whose value is passed in when the corresponding chain is initialized (see below for extension). For example, config for the C-Chain should be at: {chain-config-dir}/C/config.json.

This also applies to Subnets, for example, if a Subnet's chain id is 2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt, the config for this chain should be at {chain-config-dir}/2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt/config.json

tip

By default, none of these directories and/or files exist. You would need to create them manually if needed.

The filename extension that these files should have, and the contents of these files, is VM-dependent. For example, some chains may expect config.txt while others expect config.json. If multiple files are provided with the same name but different extensions (e.g. config.json and config.txt) in the same sub-directory, MetalGo will exit with an error.

For a given chain, MetalGo will look first for a config sub-directory whose name is the chain ID. If it isn't found, it looks for a config sub-directory whose name is the chain's primary alias. If it's not found, it looks for a config sub-directory whose name is another alias for the chain. All folder and file names are case sensitive.

Alternatively, for some setups it might be more convenient to provide config entirely via the command line. For that, you can use MetalGo --chain-config-dir flag, as documented here.

It is not required to provide these custom configurations. If they are not provided, a VM-specific default config will be used.

C-Chain Configs

In order to specify a config for the C-Chain, a JSON config file should be placed at {chain-config-dir}/C/config.json.

For example if chain-config-dir has the default value which is $HOME/.metalgo/configs/chains, then config.json should be placed at $HOME/.metalgo/configs/chains/C/config.json.

The default C-Chain config is:

{
  "snowman-api-enabled": false,
  "coreth-admin-api-enabled": false,
  "coreth-admin-api-dir": "",
  "eth-apis": [
    "eth",
    "eth-filter",
    "net",
    "web3",
    "internal-eth",
    "internal-blockchain",
    "internal-transaction-pool"
  ],
  "continuous-profiler-dir": "",
  "continuous-profiler-frequency": 900000000000,
  "continuous-profiler-max-files": 5,
  "rpc-gas-cap": 50000000,
  "rpc-tx-fee-cap": 100,
  "preimages-enabled": false,
  "snapshot-async": true,
  "snapshot-verification-enabled": false,
  "pruning-enabled": true,
  "allow-missing-tries": false,
  "populate-missing-tries-parallelism": 1024,
  "metrics-enabled": true,
  "metrics-expensive-enabled": false,
  "local-txs-enabled": false,
  "api-max-duration": 0,
  "ws-cpu-refill-rate": 0,
  "ws-cpu-max-stored": 0,
  "api-max-blocks-per-request": 0,
  "allow-unfinalized-queries": false,
  "allow-unprotected-txs": false,
  "keystore-directory": "",
  "keystore-external-signer": "",
  "keystore-insecure-unlock-allowed": false,
  "remote-tx-gossip-only-enabled": false,
  "tx-regossip-frequency": 60000000000,
  "tx-regossip-max-size": 15,
  "log-level": "info",
  "offline-pruning-enabled": false,
  "offline-pruning-bloom-filter-size": 512,
  "offline-pruning-data-directory": "",
  "max-outbound-active-requests": 8,
  "state-sync-enabled": false,
  "state-sync-skip-resume": false,
  "state-sync-min-blocks": 300000,
  "state-sync-ids": "",
  "state-sync-server-trie-cache": 64
}

Default values are overridden only if specified in the given config file. It is recommended to only provide values which are different from the default, as that makes the config more resilient to future default changes. Otherwise, if defaults change your node will remain with the old values, which might adversely affect your node operation.

Continuous Profiling

`continuous-profiler-dir` (string):

Enables the continuous profiler (captures a CPU/Memory/Lock profile at a specified interval). Defaults to "". If a non-empty string is provided, it enables the continuous profiler and specifies the directory to place the profiles in.

`continuous-profiler-frequency` (duration):

Specifies the frequency to run the continuous profiler. Defaults to 15 minutes.

`continuous-profiler-max-files` (int):

Specifies the maximum number of profiles to keep before removing the oldest.

Enabling Metal Specific APIs

`snowman-api-enabled` (boolean):

Enables the Snowman API. Defaults to false.

`coreth-admin-api-enabled` (boolean):

Enables the Admin API. Defaults to false.

`coreth-admin-api-dir` (string):

Specifies the directory for the Admin API to use to store CPU/Mem/Lock Profiles. Defaults to "".

Enabling EVM APIs

`eth-apis` ([]string):

Use the eth-apis field to specify the exact set of below services to enable on your node. If this field is not set, then the default list will be: ["eth","eth-filter","net","web3","internal-eth","internal-blockchain","internal-transaction"].

note

The names used in this configuration flag have been updated in coreth v.0.8.14. The previous names containing public- and private- are deprecated. While the current version continues to accept deprecated values, they may not be supported in future updates and updating to the new values is recommended.

The mapping of deprecated values and their updated equivalent follows:

Deprecated	Use instead
`public-eth`	`eth`
`public-eth-filter`	`eth-filter`
`private-admin`	`admin`
`private-debug`	`debug`
`public-debug`	`debug`
`internal-public-eth`	`internal-eth`
`internal-public-blockchain`	`internal-blockchain`
`internal-public-transaction-pool`	`internal-transaction`
`internal-public-tx-pool`	`internal-tx-pool`
`internal-public-debug`	`internal-debug`
`internal-private-debug`	`internal-debug`
`internal-public-account`	`internal-account`
`internal-private-personal`	`internal-personal`

note

If you populate this field, it will override the defaults so you must include every service you wish to enable.

`eth`:

The API name public-eth is deprecated as of v1.7.15, and the APIs previously under this name have been migrated to eth.

Adds the following RPC calls to the eth_* namespace. Defaults to true.

eth_coinbase eth_etherbase

`eth-filter`:

The API name public-eth-filter is deprecated as of v1.7.15, and the APIs previously under this name have been migrated to eth-filter.

Enables the public filter API for the eth_* namespace. Defaults to true.

Adds the following RPC calls (see https://eth.wiki/json-rpc/API for complete documentation):

eth_newPendingTransactionFilter
eth_newPendingTransactions
eth_newAcceptedTransactions
eth_newBlockFilter
eth_newHeads
eth_logs
eth_newFilter
eth_getLogs
eth_uninstallFilter
eth_getFilterLogs
eth_getFilterChanges

`admin`:

The API name private-admin is deprecated as of v1.7.15, and the APIs previously under this name have been migrated to admin.

Adds the following RPC calls to the admin_* namespace. Defaults to false.

admin_importChain
admin_exportChain

`debug`:

The API names private-debug and public-debug are deprecated as of v1.7.15, and the APIs previously under these names have been migrated to debug.

Adds the following RPC calls to the debug_* namespace. Defaults to false.

debug_dumpBlock
debug_accountRange
debug_preimage
debug_getBadBlocks
debug_storageRangeAt
debug_getModifiedAccountsByNumber
debug_getModifiedAccountsByHash
debug_getAccessibleState

`net`:

Adds the following RPC calls to the net_* namespace. Defaults to true.

net_listening
net_peerCount
net_version

Note: Coreth is a virtual machine and does not have direct access to the networking layer, so net_listening always returns true and net_peerCount always returns 0. For accurate metrics on the network layer, users should use the MetalGo APIs.

`debug-tracer`:

Adds the following RPC calls to the debug_* namespace. Defaults to false.

debug_traceChain
debug_traceBlockByNumber
debug_traceBlockByHash
debug_traceBlock
debug_traceBadBlock
debug_intermediateRoots
debug_traceTransaction
debug_traceCall

`web3`:

Adds the following RPC calls to the web3_* namespace. Defaults to true.

web3_clientVersion
web3_sha3

`internal-eth`:

The API name internal-public-eth is deprecated as of v1.7.15, and the APIs previously under this name have been migrated to internal-eth.

Adds the following RPC calls to the eth_* namespace. Defaults to true.

eth_gasPrice
eth_baseFee
eth_maxPriorityFeePerGas
eth_feeHistory

`internal-blockchain`:

The API name internal-public-blockchain is deprecated as of v1.7.15, and the APIs previously under this name have been migrated to internal-blockchain.

Adds the following RPC calls to the eth_* namespace. Defaults to true.

eth_chainId
eth_blockNumber
eth_getBalance
eth_getAssetBalance
eth_getProof
eth_getHeaderByNumber
eth_getHeaderByHash
eth_getBlockByNumber
eth_getBlockByHash
eth_getUncleBlockByNumberAndIndex
eth_getUncleBlockByBlockHashAndIndex
eth_getUncleCountByBlockNumber
eth_getUncleCountByBlockHash
eth_getCode
eth_getStorageAt
eth_call
eth_estimateGas
eth_createAccessList

`internal-transaction`:

The API name internal-public-transaction-pool is deprecated as of v1.7.15, and the APIs previously under this name have been migrated to internal-transaction.

Adds the following RPC calls to the eth_* namespace. Defaults to true.

eth_getBlockTransactionCountByNumber
eth_getBlockTransactionCountByHash
eth_getTransactionByBlockNumberAndIndex
eth_getTransactionByBlockHashAndIndex
eth_getRawTransactionByBlockNumberAndIndex
eth_getRawTransactionByBlockHashAndIndex
eth_getTransactionCount
eth_getTransactionByHash
eth_getRawTransactionByHash
eth_getTransactionReceipt
eth_sendTransaction
eth_fillTransaction
eth_sendRawTransaction
eth_sign
eth_signTransaction
eth_pendingTransactions
eth_resend

`internal-tx-pool`:

The API name internal-public-tx-pool is deprecated as of v1.7.15, and the APIs previously under this name have been migrated to internal-tx-pool.

Adds the following RPC calls to the txpool_* namespace. Defaults to false.

txpool_content
txpool_contentFrom
txpool_status
txpool_inspect

`internal-debug`:

The API names internal-private-debug and internal-public-debug are deprecated as of v1.7.15, and the APIs previously under these names have been migrated to internal-debug.

Adds the following RPC calls to the debug_* namespace. Defaults to false.

debug_getHeaderRlp
debug_getBlockRlp
debug_printBlock
debug_chaindbProperty
debug_chaindbCompact

`debug-handler`:

Adds the following RPC calls to the debug_* namespace. Defaults to false.

debug_verbosity
debug_vmodule
debug_backtraceAt
debug_memStats
debug_gcStats
debug_blockProfile
debug_setBlockProfileRate
debug_writeBlockProfile
debug_mutexProfile
debug_setMutexProfileFraction
debug_writeMutexProfile
debug_writeMemProfile
debug_stacks
debug_freeOSMemory
debug_setGCPercent

`internal-account`:

The API name internal-public-account is deprecated as of v1.7.15, and the APIs previously under this name have been migrated to internal-account.

Adds the following RPC calls to the eth_* namespace. Defaults to true.

eth_accounts

`internal-personal`:

The API name internal-private-personal is deprecated as of v1.7.15, and the APIs previously under this name have been migrated to internal-personal.

Adds the following RPC calls to the personal_* namespace. Defaults to false.

personal_listAccounts
personal_listWallets
personal_openWallet
personal_deriveAccount
personal_newAccount
personal_importRawKey
personal_unlockAccount
personal_lockAccount
personal_sendTransaction
personal_signTransaction
personal_sign
personal_ecRecover
personal_signAndSendTransaction
personal_initializeWallet
personal_unpair

API Configuration

`rpc-gas-cap` (int):

The maximum gas to be consumed by an RPC Call (used in eth_estimateGas and eth_call). Defaults to 50,000,000.

`rpc-tx-fee-cap` (int):

Global transaction fee (price * gaslimit) cap (measured in METAL) for send-transaction variants. Defaults to 100.

`api-max-duration` (duration):

Maximum API call duration. If API calls exceed this duration, they will time out. Defaults to 0 (no maximum).

`api-max-blocks-per-request` (int):

Maximum number of blocks to serve per getLogs request. Defaults to 0 (no maximum).

`ws-cpu-refill-rate` (duration):

The refill rate specifies the maximum amount of CPU time to allot a single connection per second. Defaults to no maximum (0).

`ws-cpu-max-stored` (duration):

Specifies the maximum amount of CPU time that can be stored for a single WS connection. Defaults to no maximum (0).

`allow-unfinalized-queries` (boolean):

Allows queries for unfinalized (not yet accepted) blocks/transactions. Defaults to false.

Transaction Pool

`local-txs-enabled` (boolean):

Enables local transaction handling (prioritizes transactions submitted through this node). Defaults to false.

`allow-unprotected-txs` (boolean):

If true, the APIs will allow transactions that are not replay protected (EIP-155) to be issued through this node. Defaults to false.

`remote-tx-gossip-only-enabled` (boolean):

If true, the node will only gossip remote transactions to prevent transactions issued through this node from being broadcast to the network. Defaults to false.

`tx-regossip-frequency` (duration):

Amount of time that should elapse before we attempt to re-gossip a transaction that was already gossiped once. Defaults to 1 minute.

`tx-regossip-max-size` (int):

Maximum number of transactions to re-gossip at once. Defaults to 15.

Metrics

`metrics-enabled` (boolean):

Enables metrics. Defaults to false.

`metrics-expensive-enabled` (boolean):

Enables expensive metrics. Defaults to false.

Database

`pruning-enabled` (boolean):

If true, database pruning of obsolete historical data will be enabled. Should be disabled for nodes that need access to all data at historical roots. Pruning will be done only for new data. Defaults to false in v1.4.9, and true in subsequent versions.

`preimages-enabled` (boolean):

If true, enables preimages. Defaults to false.

`offline-pruning-enabled` (boolean):

If true, offline pruning will run on startup and block until it completes (approximately one hour on mainnet). This will reduce the size of the database by deleting old trie nodes. While performing offline pruning, your node will not be able to process blocks and will be considered offline. While ongoing, the pruning process consumes a small amount of additional disk space (for deletion markers and the bloom filter). For more information see here.

Since offline pruning deletes old state data, this should not be run on nodes that need to support archival API requests.

This is meant to be run manually, so after running with this flag once, it must be toggled back to false before running the node again. Therefore, you should run with this flag set to true and then set it to false on the subsequent run.

`offline-pruning-bloom-filter-size` (int):

This flag sets the size of the bloom filter to use in offline pruning (denominated in MB and defaulting to 512 MB). The bloom filter is kept in memory for efficient checks during pruning and is also written to disk to allow pruning to resume without re-generating the bloom filter.

The active state is added to the bloom filter before iterating the DB to find trie nodes that can be safely deleted, any trie nodes not in the bloom filter are considered safe for deletion. The size of the bloom filter may impact its false positive rate, which can impact the results of offline pruning. This is an advanced parameter that has been tuned to 512 MB and should not be changed without thoughtful consideration.

`offline-pruning-data-directory` (string):

This flag must be set when offline pruning is enabled and sets the directory that offline pruning will use to write its bloom filter to disk. This directory should not be changed in between runs until offline pruning has completed.

Snapshots

`snapshot-async` (boolean):

If true, allows snapshot generation to be executed asynchronously. Defaults to true.

`snapshot-verification-enabled` (boolean):

If true, verifies the complete snapshot after it has been generated. Defaults to false.

Log Level

`log-level` (string):

Defines the C-chain log level. Must be one of "trace", "debug", "info", "warn", "error", "crit". Defaults to "info".

Keystore Settings

`keystore-directory` (string):

The directory that contains private keys. Can be given as a relative path. If empty, uses a temporary directory at coreth-keystore. Defaults to empty string.

`keystore-external-signer` (string):

Specifies an external URI for a clef-type signer. Defaults to the empty string (not enabled).

`keystore-insecure-unlock-allowed` (bool):

If true, allow users to unlock accounts in unsafe HTTP environment. Defaults to false.

State Sync Settings

`state-sync-enabled` (boolean):

Set to true to start the C-Chain with state sync enabled. The peer will download chain state from peers up to a recent block near tip, then proceed with normal bootstrapping. Defaults to false.

`state-sync-skip-resume` (boolean):

If set to true, the chain will not resume a previously started state sync operation that did not complete. Normally, the chain should be able to resume state syncing without any issue. Defaults to false.

`state-sync-min-blocks` (int):

Minimum number of blocks the chain should be ahead of the local node to prefer state syncing over bootstrapping. If the node's database is already close to the chain's tip, bootstrapping is more efficient. Defaults to 300000.

`state-sync-ids` (string):

Comma separated list of node IDs (prefixed with NodeID-) to fetch state sync data from. An example setting of this field would be --state-sync-ids="NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg,NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ". If not specified (or empty), peers are selected at random. Defaults to empty string.

`state-sync-server-trie-cache` (int):

Size of trie cache used for providing state sync data to peers in MBs. Should be a multiple of 64. Defaults to 64.

X-Chain Configs

In order to specify a config for the X-Chain, a JSON config file should be placed at {chain-config-dir}/X/config.json.

For example if chain-config-dir has the default value which is $HOME/.metalgo/configs/chains, then config.json can be placed at $HOME/.metalgo/configs/chains/X/config.json.

This allows you to specify a config to be passed into the X-Chain. The default values for this config are:

{
  "index-transactions": false,
  "index-allow-incomplete": false
}

Default values are overridden only if explicitly specified in the config.

The parameters are as follows:

Transaction Indexing

`index-transactions` (boolean):

Enables AVM transaction indexing if set to true. Default value is false. When set to true, AVM transactions are indexed against the address and assetID involved. This data is available via avm.getAddressTxs API.

note

If index-transactions is set to true, it must always be set to true for the node's lifetime. If set to false after having been set to true, the node will refuse to start unless index-allow-incomplete is also set to true (see below).

`index-allow-incomplete` (boolean):

Allows incomplete indices. Default value is false.

This config value is ignored if there is no X-Chain indexed data in the DB and index-transactions is set to false.

Subnet Chain Configs

As mentioned above, if a Subnet's chain id is 2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt, the config for this chain should be at {chain-config-dir}/2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt/config.json

Chain Configs

C-Chain Configs​

Continuous Profiling​

continuous-profiler-dir (string):​

continuous-profiler-frequency (duration):​

continuous-profiler-max-files (int):​

Enabling Metal Specific APIs​

snowman-api-enabled (boolean):​

coreth-admin-api-enabled (boolean):​

coreth-admin-api-dir (string):​

Enabling EVM APIs​

eth-apis ([]string):​

eth:​

eth-filter:​

admin:​

debug:​

net:​

debug-tracer:​

web3:​

internal-eth:​

internal-blockchain:​

internal-transaction:​

internal-tx-pool:​

internal-debug:​

debug-handler:​

internal-account:​

internal-personal:​

API Configuration​

rpc-gas-cap (int):​

rpc-tx-fee-cap (int):​

api-max-duration (duration):​

api-max-blocks-per-request (int):​

ws-cpu-refill-rate (duration):​

ws-cpu-max-stored (duration):​

allow-unfinalized-queries (boolean):​

Transaction Pool​

local-txs-enabled (boolean):​

allow-unprotected-txs (boolean):​

remote-tx-gossip-only-enabled (boolean):​

tx-regossip-frequency (duration):​

tx-regossip-max-size (int):​

Metrics​

metrics-enabled (boolean):​

metrics-expensive-enabled (boolean):​

Database​

pruning-enabled (boolean):​

preimages-enabled (boolean):​

offline-pruning-enabled (boolean):​

offline-pruning-bloom-filter-size (int):​

offline-pruning-data-directory (string):​

Snapshots​

snapshot-async (boolean):​

snapshot-verification-enabled (boolean):​

Log Level​

log-level (string):​

Keystore Settings​

keystore-directory (string):​

keystore-external-signer (string):​

keystore-insecure-unlock-allowed (bool):​

State Sync Settings​

state-sync-enabled (boolean):​

state-sync-skip-resume (boolean):​

state-sync-min-blocks (int):​

state-sync-ids (string):​

state-sync-server-trie-cache (int):​

X-Chain Configs​

index-transactions (boolean):​

index-allow-incomplete (boolean):​

Subnet Chain Configs​

C-Chain Configs

Continuous Profiling

`continuous-profiler-dir` (string):

`continuous-profiler-frequency` (duration):

`continuous-profiler-max-files` (int):

Enabling Metal Specific APIs

`snowman-api-enabled` (boolean):

`coreth-admin-api-enabled` (boolean):

`coreth-admin-api-dir` (string):

Enabling EVM APIs

`eth-apis` ([]string):

`eth`:

`eth-filter`:

`admin`:

`debug`:

`net`:

`debug-tracer`:

`web3`:

`internal-eth`:

`internal-blockchain`:

`internal-transaction`:

`internal-tx-pool`:

`internal-debug`:

`debug-handler`:

`internal-account`:

`internal-personal`:

API Configuration

`rpc-gas-cap` (int):

`rpc-tx-fee-cap` (int):

`api-max-duration` (duration):

`api-max-blocks-per-request` (int):

`ws-cpu-refill-rate` (duration):

`ws-cpu-max-stored` (duration):

`allow-unfinalized-queries` (boolean):

Transaction Pool

`local-txs-enabled` (boolean):

`allow-unprotected-txs` (boolean):

`remote-tx-gossip-only-enabled` (boolean):

`tx-regossip-frequency` (duration):

`tx-regossip-max-size` (int):

Metrics

`metrics-enabled` (boolean):

`metrics-expensive-enabled` (boolean):

Database

`pruning-enabled` (boolean):

`preimages-enabled` (boolean):

`offline-pruning-enabled` (boolean):

`offline-pruning-bloom-filter-size` (int):

`offline-pruning-data-directory` (string):

Snapshots

`snapshot-async` (boolean):

`snapshot-verification-enabled` (boolean):

Log Level

`log-level` (string):

Keystore Settings

`keystore-directory` (string):

`keystore-external-signer` (string):

`keystore-insecure-unlock-allowed` (bool):

State Sync Settings

`state-sync-enabled` (boolean):

`state-sync-skip-resume` (boolean):

`state-sync-min-blocks` (int):

`state-sync-ids` (string):

`state-sync-server-trie-cache` (int):

X-Chain Configs

`index-transactions` (boolean):

`index-allow-incomplete` (boolean):

Subnet Chain Configs