NAME

xelis_daemon - run a xelis blockchain node

SYNOPSIS

xelis_daemon [OPTIONS] [CHECKPOINTS]

DESCRIPTION

XELIS is an innovative cryptocurrency built from scratch with BlockDAG, Homomorphic Encryption, Zero-Knowledge Proofs, and Smart Contracts.

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.

A formatted and hyperlinked copy of the latest xelis_daemon documentation can be viewed at https://docs.xelis.io/getting-started/configuration/xelis_daemon  or https://github.com/xelis-project/xelis-docs/resources/manpages/xelis_daemon/xelis_daemon.html 

OPTIONS

-h, --help

Print help (see a summary with -h).

-V, --version

Print version.

--network

Select the blockchain network the node will connect to.

Possible values: mainnet, testnet, devnet

Default: mainnet

--dir-path <path>

Set the directory <path> for blockchain storage. This will be appended by the network name for the database directory. The path specified must end with a slash (/).

--config-file <file>

Load the daemon configuration from <file>. JSON format.

--generate-config-template

Generate the template at the --config-file path

--allow-boost-sync

Use Boost Sync Mode. This mode requests all blocks in parallel instead of sequentially during synchronization. It is not enabled by default because it will request several blocks before validating each previous block, which requires more system resources.

--allow-fast-sync

Enable fast sync mode. Fast sync mode downloads the last chain state from any peer. It allows having a light node with very light disk usage as it will use only the latest available data.

Note
This mode will not store any blocks or transactions and will not verify the history locally.

Warning
Use this option with extreme caution because you are trusting nodes to have a valid bootstrapped chain.

--auto-prune-keep-n-blocks <n>

Enable the auto prune mode and prune the chain at each new block by keeping at least <n> blocks before the top block. This is useful to keep a light node and to reduce the disk usage.

--disable-p2p-server

Disable the P2P Server. No connections will be accepted. The node will not be able not be able to sync the chain or broadcast mined blocks.

--disable-rpc-server

Disable the RPC Server. This will also disable the GetWork Server as it is loaded on RPC server.

--max-peers <n>

Set the maximum number of P2P peers to connect to <n>.
Default: 32

--exclusive-nodes <nodes>

Set exclusive nodes to connect to.

Sets a list of <nodes> (node addresses) that the node must connect to, and this connection is maintained. The node will only connect to the listed nodes and will not connect to any other nodes, including seed nodes.

A comma must separate each Socket Address.

Example --exclusive-nodes 0.0.0.0:2125,0.0.0.0:2126

--priority-nodes <nodes>

Gives connection priority to a list of <nodes> (node addresses) when P2P is started. A priority node is connected only one time. Connections will be made with priority nodes first, and then with regular nodes. Connections to priority nodes will be also maintained in case of disconnection.

A comma must separate each Socket Address.

Other nodes will still be connected to as long as the maximum number of peers is not reached.

Example to connect to two nodes: --priority-nodes 0.0.0.0:2125,0.0.0.0:2126

--tag <tag>

Identify the node in the network using <tag> name.
This is useful to identify the node in the network. The maximum length of <tag> is 16 characters.

--max-chain-response-size <n>

Set the maximum chain response size to <n>.
This is useful for low devices that want to reduce resource usage and for high-end devices that want to (or help others to) sync faster.

Minimum size: 512, Maximum size: 16384

Default: 4096

--disable-ip-sharing

Ask peers to not share the node IP address to others and/or through the API.

This is useful for people that do not want their IP address to be revealed in the RPC API or not shared with other nodes as a potential new peer to connect to. By default, your IP is allowed to be shared across the network to other nodes.

Note
This option may prevent new incoming peers as your IP will not be shared with others.

—disable-getwork-server

Disable GetWork Server (WebSocket for miners)

—getwork-rate-limit-ms <getwork-rate-limit-ms>

Set the rate limit for GetWork server in milliseconds. In the case of high transactions added in mempool, new jobs are rate limited. If is set to 0 (no limit), any new job will be sent to miners directly

Default: 500

--getwork-notify-job-concurrency <n>

Set the concurrency for GetWork server during a new job notification. Notify concurrently to <n> miners at a time. <n> = 0 means no limit and will process as one task per miner. Default is detected based on available parallelism.

Default: 16

--prometheus-enable

Enable Prometheus metrics server This only works if the RPC server is enabled

--prometheus-route <route>

Set the <route> for the Prometheus metrics export.

Default: /metrics

--rpc-bind-address <address>

RPC bind address to listen for HTTP requests

Default: 0.0.0.0:8080

--rpc-threads <n>

Set the number of workers to spawn for the HTTP server to <n>. If not provided, it will use the available parallelism.

Default: 16

--rpc-notify-events-concurrency <n>

Set the number of concurrent tasks that will be used to notify the events to the clients to <n>. By default, it will use the available parallelism. If <n> = 0, it will be unlimited.

Default: 16

--allow-priority-blocks

Allow blocks coming from priority nodes to be fast-forwarded to our peers.

Propagate a new block to our peers as soon as we receive it from a priority node before verifying it ourselves. This reduces the time to propagate a new block to our peers. Useful for pools operating having several nodes across the world to propagate their blocks faster.

By default, this is disabled.

--simulator <simulator>

Enable the <simulator> mode. This will disable the P2P server and will simulate the blockchain based on its variant. This will generate new blocks when necessary and will not connect to any other nodes.

Available values are:

blockchain: Simulate the blockchain with a new block every 15 seconds and up to 15 random transactions.

blockdag: Simulate the blockdag with up to 3 new block every 15 seconds and up to 15 random transactions.

stress: Simulate a blockDAG under attacks with heavy blocks and a lot of transactions.

--skip-pow-verification

Skip PoW verification.

Warning
This is dangerous and should not be used in production!

--skip-block-template-txs-verification

Disable the (double) verification of the transactions while building a block template. This is useful to speed up the block template creation for miners node.

This will rely entirely on the transaction verification done by the mempool and will not verify the transactions again.

Note
In case of a TX not deleted correctly from the mempool, it may be included in a block template and will make your block rejected by the network.

--genesis-block-hex <hex>

Use the hexadecimal representation of the genesis block for the dev mode. This is useful for testing and development

--txs-verification-threads-count <n>

Set the thread count to use during TXs verifications to <n>. By default, it will detect the best value. If <n> = 1, it will use the main thread.

Default: 16

P2P

--p2p-bind-address <address>

Set the P2P bind <address> to listen on for incoming connections.

Default: 0.0.0.0:2125

--p2p-max-outgoing-peers <n>

Set the maximum number of P2P outgoing peers to <n>.

This is useful to limit to how many nodes you want to connect to.

Default: 8

--p2p-concurrency-task-count-limit <limit>

Set the number of concurrent tasks accepting new incoming connections to <limit>

Default: 4

--p2p-proxy-address <address>

Set a proxy <address> to be used.

Note
Make sure to set --p2p-proxy along with it when connecting to a peer.

--p2p-proxy <protocol>

Set the proxy <protocol> to use when connecting to a peer. Possible values: socks5, socks4

--p2p-proxy-username <username>

Set the Proxy <username> for authentication.

--p2p-proxy-password <password>

Set the proxy <password> for authentication.

--p2p-on-dh-key-change <action>

Execute a specific <action> when the P2p Diffie-Hellman Key of a peer is different from our stored one. By default, it will ignore the key change and update it.

Possible values:

• warn: Warn the user by logging a message.
• reject: Reject the connection with the peer.
• ignore: Ignore the key change for the peer.

Default: ignore

--p2p-dh-private-key <p2p-dh-private-key>

P2P DH private key to use. By default, a newly generated key will be used. Reusing the same private key will keep the same public key and avoid the need to re-verify the key with our peers. This is useful for nodes that want to keep the same public key across several restarts. Note that reusing the same key may cause your node to be tracked across IP changes.

--p2p-stream-concurrency <n>

Set the amount of P2P Concurrency to use during streams to <n>. This is used to configure the number of concurrent tasks that will be used to process the streams. By default, it will use the available parallelism. If set to 0, it will be unlimited.

Default: 16

--p2p-temp-ban-duration <n>

P2P Time to set when banning a peer temporarily due to the fail count limit reached. This is used to configure the time to wait before unbanning the peer. By default, it will be set to 15 minutes.

Default: 15m

—p2p-fail-count-limit <p2p-fail-count-limit>

P2P Fail count limit to ban a peer temporarily. This is used to configure the number of failed requests before banning the peer temporarily.

Default: 50

--p2p-disable-reexecute-blocks-on-sync

Disable the P2P to re-execute an orphaned block during chain sync. If set, the P2P server will stop removing the block from storage and prevent re-executing it by adding it back to the chain.

--p2p-block-propagation-log-level <level>

Set the P2P log <level> for the block propagation. This is used to configure the log level used during the block propagation to peers. By default, it will be set to debug

Possible values: off, error, warn, info, debug, trace

Default: debug

--p2p-disable-fetching-txs-propagated

Disable requesting P2P transactions propagated

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

Handle peer packets in parallel by creating a new dedicated task.

Each packet has its own dedicated task except those which are order-dependent. They are set in a sequential executor to ensure that the order stays the same despite this option being enabled.

Creating a dedicated task per packet handling is useful for reducing latency during heavy network usage, but may increase overall resource usage (cpu, ram, io) significantly under high load.

By default, all P2P packets are handled sequentially in a single task per peer.

Logging

--disable-file-logging

Stops the daemon from writing logs to a file.

--disable-file-log-date-based

Disable date-based file naming for logs. If disabled, the log file will be named xelis-daemon.log instead of YYYY-MM-DD.xelis-daemon.log

--disable-log-color

Disable the usage of colors in the log.

--disable-interactive-mode

Disable terminal interactive mode. You will not be able to write CLI commands in it or have an updated prompt.

--filename-log <FILENAME_LOG>

Set the log file name to <FILENAME_LOG>. By default, the filename is set to xelis-daemon.log. Log files are stored in the logs folder and are named with the date of the day.

--logs-path <LOGS_PATH>

Set the log directory path where the log files are stored to <LOGS_PATH>. By default, it will be logs/ of the current directory.

Note
The directory will be created using the provided path if it does not exist. The path must end with a /.

--logs-modules <module_names>

Module configuration for logs.
A comma must separate each module name.
Example: To disable logging for two modules mod_1 and mod_2, use: --logs-modules mod_1=off,mod_2=off.

--log-level <level>

Set the log level to <level>.
Available values are trace, debug, info, warn, error.
By default, the log level is set to info.

--file-log-level <level>

Set the file log level to <level>.

Available values are trace, debug, info, warn, error.

This is useful for having a different log level for the file log than the console log.
By default, the file log level is set to value passed to --log-level (which is also info by default).

--datetime-format <format>

Change the datetime format used by the logger.
Default: "[%Y-%m-%d] (%H:%M:%S%.3f)"

--auto-compress-logs

Enable the log file auto-compression. If enabled, the log file will be compressed every day. This will only work if the log file is enabled.

Database

--use-db-backend <database>

Use <database> backend for the blockchain data.

Possible values: sled, rocksdb

Default: sled

Note
Pre-existing blockchain data will not be migrated from one database to another, and you may lose your data.

--check-db-integrity

Enable the DB integrity check that happens on chain initialization. This may take some time on a large DB as it is iterating through all versioned data to verify that no pointer or version is above our current topoheight. Please note that if the recovery mode is enabled, this will be skipped. By default, it is disabled.

--flush-db-every-n-blocks <n>

Flush the storage onto the disk every <n> (topoheight based) blocks. In the case of RocksDB, this will also compact the changes.

Sled Database Backend

--sled-cache-size <n>

Set LRUCache size to <n> (0 = disabled)

Default: 1024

--sled-internal-cache-size <n>

Set the Sled database cache size to <n> bytes.

Default: 67108864

--sled-internal-db-mode <mode>

Set the sled internal database to <mode>.

Possible values:

• high-throughput: Use the fastest mode to have the best performance but may provide bigger space usage.
• low-space: Use the slowest mode with the smallest space usage by rewriting (if needed) few times the data to defragment the database.

Default: low-space

RocksDB Database Backend

--rocksdb-background-threads <n>

Sets the number of background threads RocksDB should use for parallelism to <n>. Default set to the available parallelism detected.

Default: 16

--rocksdb-max-background-jobs <n>

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

Default: 16

--rocksdb-max-subcompaction-jobs <n>

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

Default: 16

--rocksdb-low-priority-background-threads <n>

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

Default: 16

--rocksdb-max-open-files <n>

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

Default: 1024

--rocksdb-keep-max-log-files <n>

Sets the maximal number of info log files to be kept to <n>.

Default: 4

--rocksdb-compression-mode <mode>

Set the compression mode to use for RocksDB to <mode>.

Possible values: none, snappy, zlib, bz2, lz4, lz4hc, zstd

Default: snappy

--rocksdb-cache-mode <mode>

Sets the RocksDB block-based cache mode to <mode>.

Possible values: none, lru, hyper_clock

Default: lru

--rocksdb-cache-size <n>

Sets the RocksDB block-based cache size to <n> bytes. Note that this is only used if --rocksdb-cache-mode is not None.

Default: 67108864

--rocksdb-write-buffer-size <n>

Sets the size of the write buffer for the amount of data to build up in memtables to <n> bytes.

Default: 67108864

--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.

--recovery-mode

Enable the recovery mode of the daemon. No DB integrity check or pre-computations will occur such as difficulty for tips, stable height, etc.

--disable-zkp-cache

Disables the ZK Proofs cache, which is used to prevent verifying the same ZK ProofS twice. A transaction added to the mempool will be fully verified again once the transaction is in a block.

--disable-ascii-art

Disable the ascii art at startup

CHECKPOINTS

Blocks hashes checkpoints. No rewind can go below any of those checkpoints

COPYRIGHT

BSD 3-Clause License

Copyright (c) 2025, XELIS

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRICOPYRIGHTGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

SEE ALSO

xelis_miner(1), xelis_wallet(1)