config.toml guide
Pre-requisites
Please, make sure that you have installed and initialized celestia-node
Viewing the help menu
In order to view all flags and their descriptions, use:
celestia light start --helpUnderstanding config.toml
After initialization, for any type of node, you will find a
config.toml in the node store. The default node store depends on the
node type and the network:
| Node type | Mainnet Beta | Mocha |
|---|---|---|
| bridge node | $HOME/.celestia-bridge/config.toml | $HOME/.celestia-bridge-mocha-5/config.toml |
| light node | $HOME/.celestia-light/config.toml | $HOME/.celestia-light-mocha-5/config.toml |
Only Mainnet Beta uses a path without a network suffix. Every other
network, including custom networks, uses $HOME/.celestia-<node_type>-<network>.
Two settings override the default node store:
- The
--node.store <path>flag sets the node store for a single command. - The
CELESTIA_HOMEenvironment variable replaces the default path. The node uses the value as the node store itself and does not append the node type or network. An explicit--node.storetakes precedence.
To load a different configuration file without moving the node store, pass
--node.config <file>. The node reads that file instead of the store's
config.toml.
Let's break down some of the most used sections.
Core (Consensus)
This section sets the consensus node endpoint that the node connects
to over gRPC. A bridge node requires it. The fields are IP, Port
(default 9090), TLSEnabled and XTokenPath. You can also set them
with the command line flags --core.ip, --core.port, --core.tls
and --core.xtoken.path.
IPv6 literal endpoints
IPv6 literal endpoints are supported starting with celestia-node v0.33.2 and v0.34.2-mocha, including the current v0.36.0 and v0.36.0-mocha releases. Earlier releases may reject or incorrectly parse IPv6 addresses; use a supported release for your network.
In your node's config.toml, keep the IPv6 address and port in separate fields.
For a consensus endpoint and node RPC server on the same machine:
[Core]
IP = "::1"
Port = "9090"
[RPC]
Address = "::1"
Port = "26658"Edit the existing sections and restart the node to apply the changes.
::1 is IPv6 loopback; the consensus service must listen on that address and
port. The equivalent Core CLI flags are --core.ip=::1 --core.port=9090.
The IP field in each [[Core.AdditionalCoreEndpoints]] entry also accepts
an IPv6 literal, with its port in the separate Port field.
When an address includes a port in a URL, put brackets around the IPv6 literal:
http://[::1]:26658. The node constructs RPC client URLs with these brackets
automatically. This support is for literal IPv6 addresses; it does not change
hostname resolution to use IPv6.
RPC
Starting with celestia-node v0.31.3, the RPC server supports optional per-IP rate limiting. If you upgraded an existing node from an earlier version, add the new fields while preserving your custom configuration by running:
celestia <node_type> config-update --p2p.network <network>The default rate-limit configuration is:
[RPC.RateLimit]
Enabled = false
RequestsPerSec = 100
Burst = 200
CacheSize = 8192Enabledturns per-IP rate limiting on or off.RequestsPerSecsets the sustained request rate allowed for each IP address.Burstallows short request spikes before the sustained rate is enforced.CacheSizelimits the number of per-IP rate-limit buckets held in memory.
When the limit is exceeded, the RPC server responds with HTTP status 429 Too Many Requests. Leave this rate limiter disabled when the node is behind a
reverse proxy because all requests may appear to come from the proxy's IP
address. Apply rate limiting at the proxy instead.
RPC request bodies are limited to 16 MiB, and the server accepts up to 500
concurrent connections. These limits are enforced by the server and are not
configurable in config.toml.
See the celestia-node v0.31.3 release notes for the complete upgrade instructions.
RPC TLS
The RPC server can serve HTTPS directly. TLS is disabled by default. To
enable it, set the certificate and private key paths in config.toml.
Both files must be in PEM format:
[RPC]
TLSEnabled = true
TLSCertPath = "<cert_path>"
TLSKeyPath = "<key_path>"The equivalent command line flags are:
celestia <node_type> start --rpc.tls --rpc.tls-cert <cert_path> --rpc.tls-key <key_path>The node does not start if TLS is enabled and either path is missing or
does not point to an existing file. The --rpc.tls-cert and --rpc.tls-key
flags return an error unless TLS is also enabled. For HTTP requests, use
https:// instead of http://. For WebSocket connections, including
subscriptions, use wss:// instead of ws://.
celestia-node v0.35.0 upgrade
Starting with celestia-node v0.35.0,
Bitswap is removed and shrex is the only share exchange protocol on both
Mainnet Beta and Mocha, including the current v0.36.0
and v0.36.0-mocha releases.
The Share.UseShareExchange, Share.UseBitswap, and
Share.BlockStoreCacheSize configuration keys are removed and ignored if
present.
Stop the node, upgrade the binary, and run config-update before restarting.
Use the command for your node type, replacing <network> with mainnet or mocha:
celestia bridge config-update --p2p.network <network>
# Or, for a light node:
celestia light config-update --p2p.network <network>This removes the obsolete keys while preserving other custom values. Review
config.toml before restarting. Light nodes delete the old Bitswap samples
once on their first start after upgrading. No coordinated upgrade is needed:
v0.35.0 nodes remain compatible with v0.34.x peers.
P2P
Bootstrap
Bootstrappers help new nodes to find peers faster in the network.
Bootstrap peers are built in for each network and are not set in
config.toml. If you want your node to be a bootstrapper, start it
with the environment variable CELESTIA_BOOTSTRAPPER=true.
To provide your own bootstrap peers for a custom network, set their
multiaddresses in the
CELESTIA_CUSTOM environment variable.
Mutual peers
The purpose of this config is to set up a bidirectional communication.
This is usually the case for Celestia bridge nodes. The field
PeerExchange defaults to true on bridge nodes and false on
light nodes.
Header
Syncer
The [Header.Syncer] section controls where header synchronization starts and
how long headers are retained:
PruningWindowis a Go duration string. Bridge nodes default to the availability storage window (169h0m0s).SyncFromHeightsets a starting height. Its zero value disables the setting.SyncFromHashsets a starting header hash and takes priority overSyncFromHeight. Its empty value disables the setting.
These fields have the following defaults in a generated bridge-node configuration:
[Header.Syncer]
PruningWindow = "169h0m0s"
SyncFromHash = ""
SyncFromHeight = 0For most bridge nodes, keep these defaults. To disable pruning and sync from
genesis, pass --archival each time you run celestia bridge start instead of
setting PruningWindow manually. PruningWindow controls header retention;
changing it alone does not disable data pruning or make the node archival.
Trusted peers
TrustedPeers is the array of bridge nodes' peers that Celestia
light node trusts. By default, bootstrap peers becomes trusted peers
for Celestia light nodes if a user is not setting the trusted peer params
in config file.
Any Celestia bridge node can be a trusted peer for the light one. However, the light node by design can not be a trusted peer for another light node.