Introduction

xelis_daemon is the core service that runs the XELIS blockchain on your machine. It is responsible for maintaining a full copy of the distributed ledger, validating incoming blocks, and relaying transactions across the network.

When the daemon is running, your node actively participates in the XELIS peer-to-peer system, helping to secure the network and keep it synchronized in real time.

The daemon also provides the foundation for other components, such as the wallet and the miner, by exposing an interface through which they can interact with the blockchain. Running the daemon is an essential step for users who want to operate a full node, mine directly on the network, or simply ensure they are working with the most up-to-date state of the chain.

Running a local node is highly recommended, as it ensures you remain fully trustless and independent of third parties, enhances your privacy, and helps spread and secure the XELIS network.

Configuration

XELIS daemon node. Synchronizes and validates the blockchain, participates in the P2P network, and serves RPC and mining work.

disable-getwork-server

Disable the GetWork websocket server used by miners

getwork-rate-limit-ms

Minimum delay, in milliseconds, between GetWork job notifications.

New jobs can be produced quickly when the mempool changes. Use this to coalesce updates before notifying miners. Set to 0 to send every new job immediately.

getwork-notify-job-concurrency

Maximum number of miners notified concurrently for each new job.

Defaults to the detected CPU parallelism. Set to 0 to remove the limit and spawn one notification task per miner.

enable

Enable the Prometheus metrics endpoint.

The endpoint is served by the RPC server, so RPC must also be enabled.

prometheus-route

HTTP route used to expose Prometheus metrics

disable-rpc-server

Disable the RPC server.

This also disables GetWork and Prometheus because both are served through the RPC server.

rpc-bind-address

Address and port where the RPC server listens for HTTP and websocket requests

rpc-threads

Number of worker threads used by the RPC HTTP server.

Defaults to the detected CPU parallelism.

rpc-notify-events-concurrency

Maximum number of concurrent RPC event notification tasks.

Defaults to the detected CPU parallelism. Set to 0 to remove the concurrency limit.

rpc-json-rpc-batch-limit

Maximum number of calls accepted in one JSON-RPC batch request.

This limits large batches to reduce denial-of-service risk.

rpc-max-websocket-sessions

Maximum number of websocket sessions accepted by each RPC websocket server

rpc-websocket-session-channel-size

Maximum number of outbound messages queued per websocket session

rpc-websocket-session-work-queue-size

Maximum number of inbound RPC work items queued per websocket session

rpc-cors-allowed-origins

Browser origins allowed to call the RPC server through CORS.

Leave empty to avoid adding CORS allow-origin rules.

rpc-allow-private-methods

Allow private RPC methods intended only for trusted environments.

Do not expose this on a public RPC endpoint.

rpc-allow-contract-vm-executions

Allow RPC methods to execute the contract VM against current chain state.

Currently used by simulate_contract_invoke.

p2p-proxy-address

Proxy address used for outbound P2P peer connections.

Also set p2p-proxy so the daemon knows which proxy protocol to use.

p2p-proxy

Proxy protocol used for outbound P2P peer connections

p2p-proxy-username

Username used to authenticate to the configured P2P proxy

p2p-proxy-password

Password used to authenticate to the configured P2P proxy

tag

Optional label advertised by this node on the P2P network

p2p-bind-address

Address and port where the P2P server listens for incoming peers

max_peers

Maximum total number of connected P2P peers

p2p-max-outgoing-peers

Maximum number of outbound P2P peer connections

priority_nodes

Priority peer addresses to connect to when P2P starts.

Priority peers are attempted in addition to normal peer discovery and are not continuously reconnected unless they are also exclusive peers.

exclusive_nodes

Exclusive peer addresses that replace normal peer discovery.

Connections to exclusive peers are maintained after disconnects. When at least one exclusive peer is configured, seed nodes and non-exclusive inbound peers are not accepted.

disable-p2p-server

Disable the P2P server.

The daemon will not accept peer connections or participate in network propagation.

allow_fast_sync

Allow fast sync from a bootstrapped chain state.

Fast sync does not store all historical blocks or transactions and does not locally verify the full history. Use only with trusted peers.

allow_boost_sync

Allow boosted chain sync by requesting blocks in parallel.

This can improve sync speed, but requests blocks before previous blocks have been validated.

allow_priority_blocks

Forward blocks received from priority peers before local verification.

This reduces propagation latency for trusted priority peers, such as a pool operating several nodes in different regions.

max_chain_response_size

Maximum number of blocks returned in one chain sync response.

Lower values reduce memory and bandwidth spikes. Higher values can help well-provisioned nodes sync peers faster.

disable_ip_sharing

Ask peers not to share this node’s IP address.

This helps keep the node out of peer lists and RPC peer responses, but it can reduce incoming peer discovery.

p2p-concurrency-task-count-limit

Maximum number of concurrent tasks accepting new P2P connections

p2p-on-dh-key-change

Action to take when a peer’s stored Diffie-Hellman key changes.

By default the key change is accepted and the stored key is updated.

p2p-dh-private-key

Static P2P Diffie-Hellman private key.

When unset, a fresh key is generated. Reusing a key preserves the same public identity across restarts and avoids peer re-verification, but it can also make the node easier to track across IP changes.

p2p-stream-concurrency

Maximum number of concurrent tasks used to process P2P streams.

Defaults to the detected CPU parallelism. Set to 0 to remove the concurrency limit.

p2p-temp-ban-duration

Duration of a temporary peer ban after the fail-count limit is reached

p2p-outgoing-connection-timeout

Timeout used when initiating outbound P2P peer connections

p2p-fail-count-limit

Number of peer failures allowed before applying a temporary ban

disable-p2p-reexecute-blocks-on-sync

Disable re-execution of orphaned blocks during P2P chain sync.

When enabled, orphaned blocks are not removed and re-added to trigger execution again.

p2p-block-propagation-log-level

Log level used for P2P block propagation messages

disable-p2p-fetching-txs-propagated

Disable fetching transactions announced through P2P propagation.

The daemon will ignore propagated transaction announcements, which can leave the mempool unsynchronized on smaller networks.

p2p-handle-peer-packets-in-dedicated-task

Handle eligible peer packets in dedicated tasks.

Order-dependent packets still use a sequential executor. This can reduce latency during heavy network activity, but may increase resource usage under high load.

enable-p2p-compression

Enable Snappy compression for large P2P packets.

Only packets larger than 1 KiB are compressed. This can reduce bandwidth usage at the cost of additional CPU work.

disable-fast-sync-support

Disable serving fast sync data to other nodes

p2p-sync-from-priority-only

Sync chain data only from configured priority peers

p2p-reorg-from-priority-only

During reorganizations, accept blocks only from configured priority peers

min_fee_per_kb

Minimum transaction fee per kB accepted by the mempool.

The value is expressed in atomic units.

tx_expiration_time

Maximum time a transaction may stay in the mempool before expiration

max_memory_usage

Maximum memory the mempool may use before evicting transactions.

Accepts raw bytes or human-readable values such as 800 MB or 1.5 GiB.

dir_path

Base directory used for blockchain storage.

The network name is appended to this path. The path must end with / or \.

simulator

Enable simulator mode with the selected simulator settings.

Simulator mode skips proof-of-work verification and generates blocks at the configured block interval.

skip_pow_verification

Skip proof-of-work verification.

This is unsafe for production nodes.

enable_contracts_logging

Print contract logs while contracts execute

auto_prune_keep_n_blocks

Enable automatic pruning while keeping at least this many blocks below the tip.

Pruning runs after new blocks are applied.

skip_block_template_txs_verification

Skip transaction verification while building block templates

genesis_block_hex

Hex-encoded genesis block used in development networks

checkpoints

Block hash checkpoints that prevent rewinding below known states

txs_verification_threads_count

Number of threads used for transaction verification.

Defaults to the detected CPU parallelism. Set to 1 to run on the main verification thread.

pre_verify_block_threads_count

Number of threads used for block pre-verification.

Defaults to the detected CPU parallelism.

check_db_integrity

Check database integrity during chain initialization.

This scans versioned data to ensure no pointer or version is above the current topoheight. It can take a long time on large databases and is skipped when recovery mode is enabled.

recovery_mode

Start the daemon in recovery mode.

Recovery mode skips database integrity checks and startup pre-computations such as tip difficulty and stable height.

flush_db_every_n_blocks

Flush storage to disk every N blocks, based on topoheight.

With RocksDB, this also compacts pending changes.

disable_zkp_cache

Disable the transaction zero-knowledge proof cache.

The cache is enabled by default to avoid verifying the same proofs more than once.

concurrency

Maximum concurrency for general daemon tasks.

Defaults to the detected CPU parallelism.

enable_snapshot_on_reorg

Enable snapshot buffering during DAG reorganizations.

Before applying a reorg, the daemon snapshots the current state, applies the reorg through an in-memory buffer, then flushes the final state to storage.

sled-cache-size

Set LRUCache size (0 = disabled)

sled-internal-cache-size

DB cache size in bytes

sled-internal-db-mode

Internal DB mode to use

rocksdb-background-threads

How many background threads RocksDB should use for parallelism. Default set to the available parallelism detected

rocksdb-max-background-jobs

Sets maximum number of concurrent background jobs (compactions and flushes). Default set to the available parallelism detected

rocksdb-max-subcompaction-jobs

Sets maximum number of threads that will concurrently perform a compaction job by breaking it into multiple, smaller ones that are run simultaneously. Default set to the available parallelism detected

rocksdb-low-priority-background-threads

Sets the size of the low priority thread pool that can be used to prevent compactions from stalling memtable flushes. Default set to the available parallelism detected

rocksdb-max-open-files

Sets the number of open files that can be used by the DB. You may need to increase this if your database has a large working set. Value -1 means files opened are always kept open

rocksdb-keep-max-log-files

Specify the maximal number of info log files to be kept

rocksdb-compression-mode

Compression mode to use for RocksDB

rocksdb-cache-mode

RocksDB block based cache mode to use

rocksdb-cache-size

Size in bytes for the RocksDB block based to cache use if mode is not None

rocksdb-write-buffer-size

Write buffer to use for the amount of data to build up in memtables

rocksdb-write-buffer-shared

Enforces a limit for a single memtable using the above write buffer size. Disabled by default, each column will have its own buffer

rocksdb-bloom-filter-bits-per-key

Bloom filter bits per key for column families that use a prefix extractor. Higher values reduce false positives but increase memory usage

rocksdb-target-file-size-base

Override for target SST file size in bytes. None (default) uses the RocksDB default of 64 MiB

rocksdb-disable-compaction-on-flush

Disable compaction on flush. This can be useful to speed up shutdown time at the cost of increased storage usage and potentially slower read performance

use_db_backend

Storage backend used by the daemon.

Existing data is not migrated when switching backends. Select the backend that matches the data directory you intend to use.

log_level

Minimum log level printed to the terminal

file_log_level

Minimum log level written to the log file.

Defaults to the terminal log level.

disable_file_logging

Disable writing logs to a file

disable_file_log_date_based

Disable date-based log filenames.

When enabled, the log file is named xelis-daemon.log instead of YYYY-MM-DD.xelis-daemon.log.

disable_log_color

Disable colors in terminal logs

disable_interactive_mode

Disable the interactive terminal prompt.

CLI commands and live prompt updates are unavailable in this mode.

auto_compress_logs

Compress rotated log files automatically.

This only applies when file logging is enabled.

filename_log

Log filename stored inside logs_path.

Unless date-based filenames are disabled, daily log files are named YYYY-MM-DD.xelis-daemon.log.

logs_path

Directory where log files are written.

Defaults to logs/. The path must end with / or \.

logs_modules

Per-module log filters

disable_ascii_art

Disable the ASCII art shown at startup

datetime_format

Datetime format used in log entries

network

Network to run and validate

config_file

JSON configuration file to load

generate_config_template

Generate a configuration template at config_file