System configuration is a set of parameters that determine the network access parameters of a node and behavior of the node while operating in the network.
The configuration is stored in the TOML format. A path to the configuration file should be specified on the node start up.
Services may have their own configuration settings. On node initialization the
configuration is passed to all services deployed in the blockchain.
The configuration for a service is stored in the
of the overall configuration
under a separate key equal to the name of the service.
The configuration settings of the anchoring service
include the parameters of the RPC connection to
a Bitcoin Core node as well as a Bitcoin address used for anchoring.
These parameters are stored in the
section of the overall configuration.
System configuration contains 2 types of configuration parameters:
- Global parameters must be identical for all full nodes in the network. The global parameters are saved in the blockchain when the genesis block is created
- Local parameters may differ for each node
This categorization holds for both core and service parameters.
The following table shows all 4 possible parameter categories.
|Global||Validators’ public keys||Anchoring address|
|Local||Validator’s private key||RPC params for Bitcoin Core|
See sample configuration file for reference.
The configuration used to create a genesis block.
List of validators’ public keys as hex strings. Each list element consists of two parts:
Validator’s public key (hex) for use with consensus messages
Validator’s public key (hex) for use with service transactions
Consensus algorithm parameters.
Maximum message length (in bytes). This parameter determines the maximum size of both consensus messages and transactions. The default value of the parameter is 1 MB (1024 * 1024 bytes). The range of possible values for this parameter is between 1MB and 2^32 bytes.
Maximum propose timeout (in ms)
Minimum propose timeout (in ms)
Peers exchange timeout (in ms)
Amount of transactions in the pool to start using
Timeout interval (ms) between rounds
Timeout interval (ms) for sending a
Maximum number of transactions per block
The node address broadcasted to other peers using
Listen address of the current node
List of full node addresses
Node’s public key (hex) for use with consensus messages
Node’s private key (hex) for signing consensus messages
Node’s public key (hex) for use with service transactions
Node’s private key (hex) for signing service transactions
Local connection parameters.
Maximum number of incoming connections
Maximum number of outgoing connections
Activation of the
NODELAYalgorithm from the TCP stack (see RFC2126)
Timeout interval (ms) before the first reconnect attempt
Maximum timeout interval (ms) for reconnect attempt
API configuration parameters.
Enables API endpoints for the blockchain explorer at the public API address
Timeout interval (ms) to update info about connected peers
Listen address for public API endpoints
Listen address for private API endpoints
Sets up the CORS headers for public API endpoints. The parameter can take any of the three forms:
"*"enables requests from all origins
- Origin string (e.g.,
"http://example.com") enables requests from a single specific origin
- An array of origin strings (e.g.,
["http://a.example.com", "http://b.example.com"]) enables requests from any of the specified origins
allow_origin parameter is not specified, CORS headers are not added
to any requests, which can lead to requests from external origins
being improperly processed by user agents with the CORS support
(such as web browsers). However, you can easily avoid this by passing the
public API of an Exonum node through the web server
delivering web assets (for example, Nginx). In this case, the requests to API
would be same-origin, so CORS restrictions would not apply.
Network whitelisting parameters.
List of consensus public keys for trusted peers
Message processing parameters.
Maximum number of events in the event queue
Maximum number of transactions in the pool of unconfirmed transactions
Service-specific parameters under the keys corresponding to
of the blockchain services.
Global parameters should be changed by using the global variables updater service. The service ensures that the configuration updates are synchronized among nodes in the network. Changing global parameters by editing the configuration file is inadmissible as this may cause improper behavior of the node. Modifying global parameters by the configuration file editing is admissible only before the genesis block is created.
Local parameters may be changed by editing the configuration file and restarting the node to apply changes. In certain cases additional actions may be required to keep the system operational.
To keep a node operating when changing its validator key, you also need to update the corresponding global variable (the list of validator keys) using the global variables updater service.