Configuring

info

Before attempting to configure stellar-core, it is highly recommended to first try running a private network or joining the test network.

Configuration Basics

After you've installed Stellar Core, your next step is to complete a configuration file that specifies crucial things about your node — like whether it connects to the Testnet or the Mainnet public network, what database it writes to, and which other nodes are in its quorum set.

All configuration for stellar-core is done with a TOML file. By default, Stellar Core loads that file from ./stellar-core.cfg, but you can specify a different file to load on the command line:

stellar-core --conf betterfile.cfg <COMMAND>

The examples in these docs don't specify --conf betterfile.cfg for the sake of brevity.

This page will walk you through the key fields you'll need to include in your config file to get your node up and runninig.

info

This page attempts (as strictly as is possible) to focus on the specific fields and values that you may need to modify in your Stellar Core configuration file. To keep this page concise, we try to avoid conceptual context and background information. You will likely find some of that related information on the prerequisites or environment preparation pages, if you'd like.

Example Configurations

While we're looking at some of the config basics on this page, we've written this content to work best in conjunction with concrete config examples, so as you read through it, you may want to review the following:

• The complete example config is not a real configuration, but thoroughly documents all possible configuration elements, as well as their default values. It's got every knob you can turn and every setting you can tweak along with detailed explanations of how to turn and tweak them. You don't need to put everything from the complete example config into your config file. Fields you omit will assume the default setting, and the default setting will generally serve you well. There are a few required fields, though, and this page will explain what they are.

• If you want to connect to the Testnet network, check out the example Testnet config. As you can see, most of the fields from the complete example config are omitted since the default settings work fine. You can easily tailor this config to meet your Testnet needs.

• If you want to connect to the Mainnet network, check out this example Mainnet config for a full validator. It includes a properly crafted quorum set with all the current Tier 1 validators, which is a good place to start for most configurations. This node is set up to both validate and write history to a public archive, but you can disable either feature by adjusting this config so it's a little lighter.

Auditing of the P2P network is enabled by default, see the overlay topology section for more detail if you'd like to disable it

Network Passphrase

Use the NETWORK_PASSPHRASE field to specify whether your node connects to the Testnet or the Mainnet network.

• NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
• NETWORK_PASSPHRASE="Public Global Stellar Network ; September 2015"

For more about the Network Passphrase and how it works, check out the encyclopedia entry.

Database

You specify your node's database by using the aptly named DATABASE field of your config file, which you can can read more about in the complete example config. It defaults to an in-memory database, but you can specify a path as per the example.

Buckets

The flat XDR files of Stellar Core are placed in a directory specified in the config file as BUCKET_DIR_PATH, which defaults to buckets.

Validating Node

note

If you don't intend for your node to participate in consensus votes, you can skip ahead to configuring your quorum set

If you want to validate, you must generate a public/private key for your node. Nodes shouldn't share keys. You should carefully secure your private key. If it is compromised, someone can send false messages to the network and those messages will look like they came from you.

Generate a key pair for your validating node like this:

stellar-core gen-seed

Your output should look something like:

Secret seed: SBAAOHEU4WSWX6GBZ3VOXEGQGWRBJ72ZN3B3MFAJZWXRYGDIWHQO37SY
Public: GDMTUTQRCP6L3JQKX3OOKYIGZC6LG2O6K2BSUCI6WNGLL4XXCIB3OK2P

Add this secret seed to your config file, and mark the node as "validator":

NODE_SEED="SBAAOHEU4WSWX6GBZ3VOXEGQGWRBJ72ZN3B3MFAJZWXRYGDIWHQO37SY mynode"
NODE_IS_VALIDATOR=true

NODE_HOME_DOMAIN=<your domain name here - i.e., stellar.org>

[[HOME_DOMAINS]]
HOME_DOMAIN=<your domain name here, same as NODE_HOME_DOMAIN>
QUALITY="MEDIUM"

If you don't include a NODE_SEED or set NODE_IS_VALIDATOR=true, your node will still watch SCP and see all the data in the network, but it will not send validation messages.

If you run multiple validators, make sure to set a common HOME_DOMAIN for them by setting the NODE_HOME_DOMAIN property to the same value. This will ensure your nodes get grouped correctly during quorum set generation. You also need to include your other nodes in in your config file's VALIDATORS array.

If you want other validators to add your node to their quorum sets, you should also share your public key (GDMTUTQ...) by publishing a stellar.toml file on your home domain following specifications laid out by SEP-20.

Choosing Your Quorum Set

To create your quorum set, Stellar Core relies on two arrays of tables: [[HOME_DOMAINS]] and [[VALIDATORS]]. Check out the example config's HOME_DOMAINS array and VALIDATORS array to see them in action.

info

It is beneficial to take a brief detour here and explore some background information of validator quorums and network consensus. If you'd like, you can skip ahead and begin creating your home domains array now. Otherwise, read on, my friend!

No matter what kind of node you run — Basic or Full Validator — you need to select a quorum set, which consists of validators (grouped by organization) that your node checks with to determine whether to apply a transaction set to a ledger. If you want to know more about how quorum sets work, check this article about how Stellar approaches quorums. If you want to see what a quorum set consisting of all the Tier 1 validators looks like — a tried and true setup — check out the public network config for a Full Validator.

A good quorum set:

• aligns with your organization's priorities,
• has enough redundancy to handle arbitrary node failures, and
• maintains good quorum intersection.

Since crafting a good quorum set is a difficult thing to do, stellar core automatically generates a quorum set for you based on structured information you provide in your config file. You choose the validators you want to trust; stellar core configures them into an optimal quorum set.

To generate a quorum set, stellar core:

• Groups validators run by the same organization into a subquorum
• Sets the threshold for each of those subquorums
• Gives weights to those subquorums based on quality

While this does not absolve you of all responsibility — you still need to pick trustworthy validators and keep an eye on them to ensure that they're consistent and reliable — it does make your life easier and reduces the chances for human error.

Validator Discovery

When you add a validating node to your quorum set, it's generally because you trust the organization running the node: you trust SDF, not some anonymous Stellar public key.

In order to create a self-verified link between a node and the organization that runs it, a validator declares a home domain on-chain using a set_options operation, and publishes organizational information in a stellar.toml file hosted on that domain. To find out how that works, take a look at SEP-20.

As a result of that link, you can look up a node by its Stellar public key and check the stellar.toml file to find out who runs it. It's possible to do that manually, but you can also just consult the list of nodes on Stellarbeat.io. If you decide to trust an organization, you can use that list to collect the information necessary to add their nodes to your configuration.

When you look at that list, you will discover that the most reliable organizations actually run more than one validator, and adding all of an organization's nodes to your quorum set creates the redundancy necessary to sustain arbitrary node failure. When an organization with a trio of nodes takes one down for maintenance, for instance, the remaining two nodes vote on the organization's behalf, and the organization's network presence persists.

Home Domains Array

[[HOME_DOMAINS]] defines a superset of validators: when you add nodes hosted by the same organization to your configuration, they share a home domain, and the information in the [[HOME_DOMAINS]] table, specifically the quality rating, will automatically apply to every one of those validators.

For each organization you want to add, create a separate [[HOME_DOMAINS]] table, and complete the following required fields:

Field	Requirements	Description
HOME_DOMAIN	string	URL of home domain linked to a group of validators
QUALITY	string	Rating for this organization's nodes: HIGH, MEDIUM, or LOW

Here is an example [[HOME_DOMAINS]] array, which creates two [[HOME_DOMAINS]] tables:

[[HOME_DOMAINS]]
HOME_DOMAIN="testnet.stellar.org"
QUALITY="HIGH"

[[HOME_DOMAINS]]
HOME_DOMAIN="some-other-domain"
QUALITY="LOW"

Validators Array

For each node you would like to add to your quorum set, complete a [[VALIDATORS]] table with the following fields:

Field	Requirements	Description
NAME	string	A unique alias for the node
QUALITY	string	Rating for node (required unless specified in [[HOME_DOMAINS]]): HIGH, MEDIUM, or LOW.
HOME_DOMAIN	string	URL of home domain linked to validator
PUBLIC_KEY	string	Stellar public key associated with validator
ADDRESS	string	Peer:port associated with validator (optional)
HISTORY	string	archive GET command associated with validator (optional)

If the node's HOME_DOMAIN aligns with an organization defined in the [[HOME_DOMAINS]] array, the quality rating specified there will apply to the node. If you're adding an individual node that is not covered in that array, you'll need to specify the QUALITY here.

Here is an example, which creates three [[VALIDATORS]] tables:

[[VALIDATORS]]
NAME="sdftest1"
HOME_DOMAIN="testnet.stellar.org"
PUBLIC_KEY="GDKXE2OZMJIPOSLNA6N6F2BVCI3O777I2OOC4BV7VOYUEHYX7RTRYA7Y"
ADDRESS="core-testnet1.stellar.org"
HISTORY="curl -sf http://history.stellar.org/prd/core-testnet/core_testnet_001/{0} -o {1}"

[[VALIDATORS]]
NAME="sdftest2"
HOME_DOMAIN="testnet.stellar.org"
PUBLIC_KEY="GCUCJTIYXSOXKBSNFGNFWW5MUQ54HKRPGJUTQFJ5RQXZXNOLNXYDHRAP"
ADDRESS="core-testnet2.stellar.org"
HISTORY="curl -sf http://history.stellar.org/prd/core-testnet/core_testnet_002/{0} -o {1}"

[[VALIDATORS]]
NAME="rando-node"
QUALITY="LOW"
HOME_DOMAIN="rando.com"
PUBLIC_KEY="GC2V2EFSXN6SQTWVYA5EPJPBWWIMSD2XQNKUOHGEKB535AQE2I6IXV2Z"
ADDRESS="core.rando.com"

Important Note

Your quorum set is automatically configured based on the information you provide in the [[VALIDATORS]] and/or [[HOME_DOMAINS]] tables. Removing a validator will result in a new quorum set being generated and may have unintended consequence for you and other network participants. Be sure to carefully consider the implications of removing a validator from your configuration and follow the guidance to coordinate with other validators before making changes.

Validator Quality

QUALITY is a required field for each node you add to your quorum set. Whether you specify it for a suite of nodes in a [[HOME_DOMAINS]] table, or for a single node in a [[VALIDATORS]] table, it means the same thing, and you have the same three rating options: HIGH, MEDIUM, or LOW.

HIGH Quality

HIGH quality validators are given the most weight in automatic quorum set configuration. Before assigning a high quality rating to a node, make sure it has low latency and good uptime, and that the organization running the node is reliable and trustworthy.

A high quality validator:

• publishes an archive, and
• belongs to a suite of nodes that provide redundancy.

Choosing redundant nodes is good practice. The archive requirement is programmatically enforced.

MEDIUM Quality

MEDIUM quality validators are nested below high quality validators, and their combined weight is equivalent to a single high quality entity. If a node doesn't publish an archive, but you deem it reliable, or have an organizational interest in including it in your quorum set, give it a medium quality rating.

LOW Quality

LOW quality validators are nested below medium quality validators, and their combined weight is equivalent to a single medium quality entity. Should they prove reliable over time, you can upgrade their rating to medium to give them a bigger role in your quorum set configuration.

Automatic Quorum Set Generation

Important Note

It is ideal to configure at least 4 entities in your quorum if you'll be using automatic quorum set generation. The tradeoff here is about fault tolerance: a quorum with fewer than 4 entities will tolerate zero node failures. Take this moment to ensure your configured quorum meets your required fault tolerance.

Once you add validators to your configuration, stellar core automatically generates a quorum set using the following rules:

• Validators with the same home domain are automatically grouped together and given a threshold requiring a simple majority (2f+1)
• Heterogeneous groups of validators are given a threshold assuming byzantine failure (3f+1)
• Entities are grouped by QUALITY and nested from HIGH to LOW
• HIGH quality entities are at the top, and are given decision-making priority
• The combined weight of MEDIUM quality entities equals a single HIGH quality entity
• The combined weight of LOW quality entities equals a single MEDIUM quality entity

Diagram: Depiction of the nested quality levels and how they interact.

Quorum and Overlay Network

In order to get in sync and run consensus, your validator needs to be able to connect to the Stellar Network. In most cases, it is sufficient to simply rely on node's built-in peer discovery. However, your validator can be configured to connect to specific peers via KNOWN_PEERS and PREFERRED_PEERS in the config file. These can be either domain names or IPs. This can be useful for troubleshooting.

Additionally, configuring PREFERRED_PEER_KEYS with the keys from your quorum set might be a good idea to give priority to the nodes that allow you to reach consensus.

Without those settings, your validator depends on other nodes on the network to forward you the right messages, which is typically done as a best effort.

Impact of Validator Quality on Nomination

The Stellar Consensus Protocol uses validator quality levels in determining which validator should nominate the next transaction set for inclusion in a ledger. This process of choosing the validator that will nominate the next transaction set is called leader election. To start, the leader election algorithm assigns organizations and validators weights as follows:

• Let $O_q$ be the set of all organizations with a given quality level $q$. $O_q$ includes all explicitly defined organizations in the configuration file at quality level $q$ as well as a single virtual organization containing $O_r$ where $r$ is the next quality level below $q$.
• All organizations of some quality level $q$ have weight $w_q$.
• If an organization of quality level $q$ has $n$ nodes, then the weight of each node is $\frac{w_q}{n}$.
• $w_\top$ is 1, where $\top$ is the highest quality value assigned to any organization.
• $w_\texttt{LOW} = 0$.
  • This allows a validator to participate in some SCP activities without being trusted to nominate transaction sets.
• For all other $q$ values, $w_q = \frac{w_p}{10 \times \left|\ O_p\ \right|}$ where $p$ is the next quality value above $q$.

The leader election algorithm then assigns each validator a probability of winning leader election of the validator's weight divided by the total weight of all validators. Altogether, these win probabilities ensure that Stellar Core's leader election algorithm has the following properties:

1. Higher quality organizations have a greater chance of winning leader election than lower quality organizations.
2. Organizations of equal quality have an equal chance of winning leader election.

Validator Nomination Weight Example

Let there be 3 HIGH quality organizations, 2 MEDIUM quality organizations, and 1 LOW quality organization. The weight of each organization is as follows:

• Each HIGH quality organization has a weight of 1.
• Each MEDIUM quality organization has a weight of 1/(10 * 3), or 1/30.
• Each LOW quality organization has a weight of 0.