Interacting with the network
Use the X-Cash Daemon (xcashd) to create a node, sync the blockchain and relay transactions.
Overview
Syncing the blockchain
The X-Cash daemon xcashd
keeps your computer synced up with the X-Cash network.
It downloads and validates the blockchain from the other nodes.
About privacy and best practices
xcashd
is entirely decoupled from your wallet.
xcashd
does not access your private keys and therefore doesn't know your transactions and balance.
This means that you can run xcashd
on a separate computer or in the cloud and access it remotely to retrieve/provide the data needed for wallet operations.
In practice, you can connect to a remotexcashd
instance provided by a semi-trusted 3rd party. Such 3rd party will not be able to steal your funds as all transactions are signed locally.
However, there are privacy and reliability implications when using a remote, untrusted node. For any real business we recommend running your own full node.
To provide a better reliability and trust, the team has setup a several public remote nodes across different locations:
Name | Location |
usseed1.x-cash.org:18281 | US - Oregon |
usseed2.x-cash.org:18281 | US - Virginia |
euseed1.x-cash.org:18281 | Europe - Germany |
euseed3.x-cash.org:18281 | Europe - France |
asiaseed2.x-cash.org:18281 | Asia - Singapore |
Syntax
./xcashd [options] [command]
Options define how the daemon should be working and are optional. Their names follow the --option-name
convention.
Commands give access to specific services provided by the daemon. Commands are executed against the running daemon. Their names follow the command_name
convention.
Running
Go to directory where you unpacked X-Cash.
For learning and experimentation, you should stick to the testnet to avoid any wrong manipulation.
By default, the daemon connects to the mainnet. If you want to use real XCASH there is no need to add a specific argument.
Options
Options define how the daemon should be working. Their names follow the --option-name
convention.
The following groups are only to make reference easier to follow. The daemon itself does not group options in any way.
Help and version
Option | Description |
| Enlist available options. |
| Show |
| Show build timestamp and target operating system. Example output: |
Pick network
Option | Description |
(missing) | By default xcashd assumes mainnet. |
| Run on stagenet. Remember to run your wallet with |
| Run on testnet. Remember to run your wallet with |
Logging
Option | Description |
| Full path to the log file. Example (make sure your file permissions are correctly setup): |
|
|
| Soft limit in bytes for the log file (=104850000 by default, which is just under 100MB). Once log file grows past that limit, |
| Limit on the number of log files (=50 by default). The oldest log files are removed. In production deployments, you would probably prefer to use established solutions like logrotate instead. |
Server
xcashd
defaults are adjusted for running it occasionally on the same computer as your X-Cash wallet.
The following options will be helpful if you intend to have an always running node — most likely on a remote server or your own separate PC.
Option | Description |
| Full path to the configuration file. By default xcashd looks for bitxcash.conf in X-Cash data directory. |
| Full path to data directory. This is where the blockchain, log files, and p2p network memory are stored. For defaults and details see data directory. |
| Full path to the PID file. Works only with Example: |
| Go to background (decouple from the terminal). This is useful for long-running / server scenarios. Typically, you will also want to manage |
| Do not require tty in a foreground mode. Helpful when running in a container. By default |
| Disable UPnP port mapping on the router ("Internet Gateway Device"). Add this option to improve security if you are not behind a NAT (you can bind directly to public IP or you run through Tor). |
| Set maximum transactions pool size in bytes. By default 648000000 (~618MB). These are transactions pending for confirmations (not included in any block). |
| The emergency checkpoints set by X-CashPulse operators will be enforced. It is probably a good idea to set enforcing for unattended nodes. If encountered block hash does not match corresponding checkpoint, the local blockchain will be rolled back a few blocks, effectively blocking following what X-CashPulse operators consider invalid fork. The log entry will be produced: By default checkpointing only notifies about discrepancy by producing the following log entry: |
| The X-CashPulse checkpoints set by core developers will be discarded. As of 04/09/2019, X-Cash has not implemented the X-CashPulse operators feature. |
The following options define how your node participates in X-Cash peer-to-peer network. This is for node-to-node communication. The following options do not affect wallet-to-node interface.
The node and peer words are used interchangeably.
Option | Description |
| Network interface to bind to for p2p network protocol. Default value |
| TCP port to listen for p2p network connections. Defaults to |
| TCP port to listen for p2p network connections on your router. Relevant if you are behind a NAT and still want to accept incoming connections. You must then set this to relevant port on your router. This is to let |
|
|
| Connect to a node to retrieve other nodes' addresses, and disconnect. If not specified, |
| Manually add node to local peer list. |
| Specify list of nodes to connect to and then attempt to keep the connection open. To add multiple nodes use the option several times. Example: |
| Specify list of nodes to connect to only. If this option is given the options |
| Set max number of outgoing connections to other nodes. By default 8. Value |
| Set max number of incoming connections (nodes actively connecting to you). By default unlimited. Value |
| Set outgoing data transfer limit [kB/s]. By default 2048 kB/s. Value |
| Set incoming data transfer limit [kB/s]. By default 8192 kB/s. Value |
| Set the same limit value for incoming and outgoing data transfer. By default ( |
| Do not listen for peers, nor connect to any. Useful for working with a local, archival blockchain. |
| Allow adding local IP to peer list. Useful mostly for debug purposes when you may want to have multiple nodes on a single machine. |
Node RPC API
xcashd
node offers a powerful API. It serves 3 purposes:
provides network data (stats, blocks, transactions, ...)
provides local node information (peer list, hash rate if mining, ...)
provides interface for wallets (send transactions, ...)
This API is typically referred to as "RPC" because it is mostly based on JSON/RPC standard.
The following options define how the API behaves.
Option | Description |
| IP to listen on. By default |
| TCP port to listen on. By default |
| TCP port to listen on with the limited version of API. The limited API can be made public to create an Open Node. At the same time, you may firewall the full API port to still enjoy local querying and administration. |
| Confirm you consciously set |
| Restrict API to view only commands and do not return privacy sensitive data. Note this does not make sense with |
| Specify |
| Specify a comma separated list of origins to allow cross origin resource sharing. This is useful if you want to use |
Accepting X-Cash
These are network notifications offered by xcashd
. There are also wallet notifications like --tx-notify
offered by xcashd-wallet-rpc
here.
Option | Description |
| Run a program for each new block. The |
| Run a program when the number of blocks received in the recent past deviates significantly from the expectation. The |
| Run a program when reorganization happens (ie, at least one block is removed from the top of the blockchain). The |
Performance
These are advanced options that allow you to optimize performance of your xcashd
node, sometimes at the expense of reliability.
Option | Description | |||||
| Specify sync option, using format: `[safe fast | fast | fastest]:[sync | async]:[[blocks] | [bytes]] | |
| Max number of threads to use for parallel jobs. The default value | |||||
| Sync up most of the way by using embedded, "known" block hashes. Pass | |||||
| How many blocks are processed in a single batch during chain synchronization. By default this is 20 blocks for newer history and 100 blocks for older history ("pre v4"). Default behavior is represented by value | |||||
| The host:port of a "bootstrap" remote open node that the connected wallets can use while this node is still not fully synced. Example: | |||||
| Specify username:password for the bootstrap daemon login (if required). This considers the RPC interface used by the wallet. Normally, open nodes do not require any credentials. |
Mining
Mining functions will not work anymore under X-Cash 2.0
The following options configure solo mining using CPU with the standard software stack xcashd
. This is mostly useful for:
generating your stagenet or testnet coins
experimentation and learning
if you have super cheap access to vast CPU resources
Be advised though that real mining happens in pools and with high-end GPU-s instead of CPU-s.
Note: On block 281000
, X-Cash switched to Cryptonight HeavyX algorithm which is ASIC and NiceHash resistant.
Option | Description |
| Specify wallet address to mining for. This must be a standard address! It can be neither a subaddres nor integrated address. |
| Specify mining threads count. By default ony one thread will be used. For best results, set it to number of your physical cores. |
| Specify file for extra messages to include into coinbase transactions. |
| Enable unobtrusive mining. In this mode mining will use a small percentage of your system resources to never noticeably slow down your computer. This is intended to encourage people to mine to improve decentralization. That being said chances of finding a block are diminishingly small with solo CPU mining, and even lesser with its unobtrusive version. You can tweak the unobtrusivness / power trade-offs with the further |
| If true, assumes plugged in when unable to query system power status. |
| Specify min lookback interval in seconds for determining idle state. |
| Specify minimum avg idle percentage over lookback interval. |
| Specify maximum percentage cpu use by miner(s). |
Testing X-Cash
These options are useful for X-Cash project developers and testers. Normal users shouldn't be concerned with these.
Option | Description |
| For net tests: in download, discard ALL blocks instead checking/saving them (very fast). |
| Like test-drop-download but discards only after around certain height. By default |
| Run in a regression testing mode. |
| Fixed difficulty used for testing. By default |
| Sleep time in ms, defaults to 0 (off), used to debug before/after locking mutex. Values 100 to 1000 are good for tests. |
| Save data for dr X-Cash. |
Legacy
These options should no longer be necessary but are still present in xcashd
for backwards compatibility.
Option | Description |
| Relay compact blocks. Default. Compact block is just a header and a list of transaction IDs. |
| Relay classic full blocks. Classic block contains all transactions |
| Official docs say "Show time-stats when processing blocks/txs and disk synchronization" but it does not seem to produce any output during usual blockchain synchronization. |
| IP for ZMQ RPC server to listen on. By default |
| Port for ZMQ RPC server to listen on. By default |
| Specify database type. The default and only available: |
Commands
Commands give access to specific services provided by the daemon. Commands are executed against the running daemon. Their names follow the command_name
convention.
The following groups are only to make reference easier to follow. The daemon itself does not group commands in any way.
See running for example usage. You can also type commands directly in the console of the running xcashd
(if not detached).
Help, version, status
Option | Description |
| Show help for |
| Show version information. Example output: |
| Show status. Example output: |
P2P network
Option | Description |
| Show the full peer list. |
| Show the full peer list statistics (white vs gray peers). White peers are online and reachable. Grey peers are offline but your |
| Show connected peers with connection initiative (incoming/outgoing) and other stats. |
| Ban a given |
| Unban a given |
| Show the currently banned IPs. Example output: |
| Set the of incoming connections from other peers. |
| Set the of outgoing connections to other peers. |
| Get or set the download and upload limit. |
| Get or set the download limit. |
| Get or set the upload limit. |
Transaction pool
Option | Description |
| Flush specified transaction from transactions pool, or flush the whole transactions pool if was not provided. |
| Print the transaction pool using a verbose format. |
| Print the transaction pool using a short format. |
| Print the transaction pool's statistics (number of transactions, memory size, fees, double spend attempts etc). |
Transactions
Option | Description |
| Show a sum of all emitted coins and paid fees within specified range. Example: |
| Show specified transaction as JSON and/or HEX. |
| Force relaying the transaction. Useful if you want to rebroadcast the transaction for any reason or if transaction was previously created with "do_not_relay":true. |
Blockchain
Option | Description |
| Show local blockchain height. |
| Show blockchain sync progress and connected peers along with download / upload stats. |
| Show detailed data of specified block. |
| Show current consensus version and future hard fork block height, if any. |
| Check if specified key image is spent. Key image is a hash. |
Manage daemon
Option | Description |
| Ask daemon to exit gracefully. The |
| Set the current log level/categories where |
| Show if daemon is running. |
| Check if update is available and optionally download it. The hash is SHA-256. On linux use |
Mining
Mining functions will not work anymore under X-Cash 2.0
Option | Description |
| Ask |
| Ask |
| Ask |
| Ask |
Testing
Option | Description |
| Start saving data for dr X-Cash. |
| Stop saving data for dr X-Cash. |
Legacy
Option | Description |
| Flush blockchain data to disk. This is normally no longer necessary as |
| Show number of outputs for each amount denomination. This was only relevant in the pre-RingCT era. The old wallet used this to determine which outputs can be used for the requested mixin. With RingCT denominations are irrelevant as amounts are hidden. More info in these SA answers. |
Last updated