Skip to content

Helpful Flags for Running a Node on Moonbeam

Introduction

When spinning up your own Moonbeam node, there are some required and optional flags that can be used.

This guide will cover some of the most common flags and show you how to access all of the available flags.

Common Flags

  • --collator - enables collator mode for collator candidates and, if eligible, allows the node to actively participate in block production
  • --port - specifies the peer-to-peer protocol TCP port. The default port for parachains is 30333 and 30334 for the embedded relay chain
  • --rpc-port - sets the unified port for both HTTP and WS connections. The default port for parachains is 9944 and 9945 for the embedded relay chain
  • --ws-port - - deprecated as of client v0.33.0, use --rpc-port for HTTP and WS connections instead - sets the unified port for both HTTP and WS connections. The default port for parachains is 9944 and 9945 for the embedded relay chain
  • --rpc-max-connections - specifies the maximum number of HTTP and WS server connections. The default is 100
  • --ws-max-connections - deprecated as of client v0.33.0, use --rpc-max-connections to adjust the combined HTTP and WS connection limit instead - specifies the maximum number of HTTP and WS server connections. The default is 100
  • --execution - specifies the execution strategy that should be used by all execution contexts. The Substrate runtime is compiled into a native executable which is included locally as part of the node and a WebAssembly (Wasm) binary that is stored on-chain. The available options are:
    • native - only execute with the native build
    • wasm - only execute with the Wasm build
    • both - execute with both native and Wasm builds
    • nativeelsewasm - execute with the native build if possible and if it fails, then execute with Wasm
  • --wasm-execution - specifies the method for executing Wasm runtime code. The available options are:
    • compiled - this is the default and uses the Wasmtime compiled runtime
    • interpreted-i-know-what-i-do - uses the wasmi interpreter
  • --state-pruning - specifies the state pruning mode. For client versions prior to v0.27.0, the --state-pruning flag was named --pruning. If running a node with the --collator flag, the default is to keep the full state of all blocks. Otherwise, the state is only kept for the last 256 blocks. The available options are:
    • archive - keeps the full state of all blocks
    • <number-of-blocks> - specifies a custom number of blocks to keep the state for
  • --trie-cache-size - specifies the size of the internal state cache. The default is 67108864. You can try setting this value to 1073741824 (1GB) to improve collator performance. However, this value may be too low and need to be adjusted. For client versions prior to v0.27.0, the --trie-cache-size flag was named --state-cache-size
  • --db-cache - specifies the memory the database cache is limited to use. It is recommended to set it to 50% of the actual RAM your server has. For example, for 32 GB RAM, the value should be set to 16000. The minimum value is 2000, but it is below the recommended specs
  • --base-path - specifies the base path where your chain data is stored
  • --chain - specifies the chain specification to use. It can be a predefined chainspec such as moonbeam, moonriver, or alphanet. Or it can be a path to a file with the chainspec (such as the one exported by the build-spec command)
  • --name - specifies a human-readable name for the node, which can be seen on telemetry, if enabled
  • --telemetry-url - specifies the URL of the telemetry server to connect to. This flag can be passed multiple times as a means to specify multiple telemetry endpoints. This flag takes two parameters: the URL and the verbosity level. Verbosity levels range from 0-9, with 0 denoting the least verbosity. Expected format is '', e.g. --telemetry-url 'wss://foo/bar 0'.
  • --in-peers - specifies the maximum amount of accepted incoming connections. The default is 25
  • --out-peers - specifies the maximum amount of outgoing connections to maintain. The default is 25
  • --runtime-cache-size 64 - configures the number of different runtime versions preserved in the in-memory cache to 64
  • --eth-log-block-cache - size in bytes the LRU cache for block data is limited to use. This flag mostly pertains to RPC providers. The default is 300000000
  • --eth-statuses-cache - size in bytes the LRU cache for transaction statuses data is limited to use. This flag mostly pertains to RPC providers. The default is 300000000
  • --sync - sets the blockchain syncing mode, which can allow for the blockchain to be synced faster. The available options are:
    • full - downloads and validates the full blockchain history
    • fast - downloads blocks without executing them and downloads the latest state with proofs
    • fast-unsafe - same as fast, but skips downloading the state proofs
    • warp - downloads the latest state and proof
    • --prometheus-port - specifies a custom Prometheus port

Flags for Configuring a SQL Backend

  • --frontier-backend-type - sets the Frontier backend type to one of the following options:
    • key-value - uses either RocksDB or ParityDB as per interited from the global backend settings. This is the default option and RocksDB is the default backend
    • sql - uses a SQL database with custom log indexing
  • frontier-sql-backend-pool-size - sets the Frontier SQL backend's maximum number of database connections that a connection pool can simultaneously handle. The default is 100
  • frontier-sql-backend-num-ops-timeout - sets the Frontier SQL backend's query timeout in number of VM operations. The default is 10000000
  • frontier-sql-backend-thread-count - sets the Frontier SQL backend's auxiliary thread limit. The default is 4
  • frontier-sql-backend-cache-size - sets the Frontier SQL backend's cache size in bytes. The default value is 200MB, which is 209715200 bytes

How to Access All of the Available Flags

For a complete list of the available flags, you can spin up your Moonbeam node with --help added to the end of the command. The command will vary depending on how you choose to spin up your node, and if you're using Docker or Systemd.

Docker

docker run --network="host" -v "/var/lib/moonbeam-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moonbeamfoundation/moonbeam:v0.34.0 \
--help

docker run --network="host" -v "/var/lib/moonriver-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moonbeamfoundation/moonbeam:v0.34.0 \
--help

docker run --network="host" -v "/var/lib/alphanet-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moonbeamfoundation/moonbeam:v0.34.0 \
--help

Systemd

# If you used the release binary
./moonbeam --help

# Or if you compiled the binary
./target/release/moonbeam --help

# If you used the release binary
./moonbeam --help

# Or if you compiled the binary
./target/release/moonbeam --help

# If you used the release binary
./moonbeam --help

# Or if you compiled the binary
./target/release/moonbeam --help
Last update: November 20, 2023
| Created: February 15, 2022