Skip to main content
Run your own nodes. A third-party RPC endpoint can lag, be on a fork, or lie, and an exchange that credits deposits from someone else’s view of the chain inherits all of that. Everything in this guide assumes nodes you operate.

​
Topology

A sensible minimum is three nodes on separate hosts: Comparing the head of each node against the others, and against the status page, is how you notice that one of them has been cut off from the network or fed a different chain. Two nodes on the same host or behind the same NAT protect against far less. Size the hosts from Hardware requirements. An archive node needs considerably more disk than a pruned one and grows with every block.

​
Install

Download a release from GitHub and verify its SHA256 hash before running it, or use the Docker image. Run only stable releases on mainnet, never rc or unstable builds. See Installing the client and Versioning. Each release ships three binaries:
  • parallaxd, the node.
  • parallax-cli, a bitcoin-cli-style client for scripts and health checks. See Command-line RPC.
  • parallax-wallet, an offline key tool that never talks to a node. See parallax-wallet.

​
Configure

Settings can be passed as flags or kept in a TOML file loaded with --config. Generate a template from your flags with parallaxd dumpconfig; see Config files. Flags given on the command line override the file. A deposit indexer, as a systemd service:
/etc/systemd/system/parallaxd.service
Leave TimeoutStopSec generous: on shutdown the node flushes its caches to disk, and killing it part-way forces a slower recovery on the next start.

​
Ports

To accept inbound peers, forward TCP and UDP 32110. A node that only makes outbound connections still works, but nodes with inbound peers see blocks sooner and are harder to isolate. See Connecting to peers.

​
Lock down JSON-RPC

JSON-RPC has no authentication. There is no cookie file, user name or password, and the --authrpc.* JWT flags do not protect the public namespaces. Anyone who can reach the port can use every namespace it serves. Security comes from where the port listens and what it serves.
  • Bind to localhost. --http.addr and --ws.addr default to 127.0.0.1. Keep it that way, or bind to a private interface that only your services can reach, behind a firewall. Never expose 8545 or 8546 to the internet.
  • If services on other hosts need RPC, put a proxy in front. Terminate TLS and authenticate at a reverse proxy (mTLS, or a key header) and forward to the node on localhost. Allow only the methods those services use.
  • Serve only the namespaces you need. HTTP and WebSocket default to eth,net,web3. Add txpool for mempool visibility. Add debug only on the deposit indexer, only on localhost, because it can also rewind the chain (debug_setHead) and run expensive traces. Never serve admin, personal or miner over HTTP. Use IPC for administration.
  • Keep keys off your nodes. Leave the node keystore empty and sign withdrawals elsewhere (see Withdrawals). The node refuses to unlock accounts while HTTP or WebSocket is enabled unless you pass --allow-insecure-unlock, and you should not.
  • Set --http.vhosts to the host names your proxy forwards with, if not localhost, and leave --http.corsdomain empty. Browsers have no reason to talk to an exchange node.
Two limits on the RPC server are worth knowing:

​
History and indexing

How much history a node keeps decides what your scanner can ask it: A deposit indexer that has fallen behind (after downtime, or rebuilding from scratch) needs to trace blocks older than 128, so give it an archive node. See Sync modes and Pruning.

​
Health checks

Before crediting anything, your scanner should know the node is synced and current. Check, at least once a minute:
Alert on, and stop crediting from, a node that:
  • reports eth_syncing as anything but false;
  • has fewer than about 8 peers (net_peerCount);
  • has a head block more than about 2 hours old. Blocks average 10 minutes, so a 2-hour gap is very unlikely while miners are working, and points to an isolated node, a network-wide halt, or a large miner holding back blocks. Confirmations covers what each means;
  • disagrees with your other nodes on the hash at a height more than a couple of blocks below the head. Disagreement at the very tip is a normal block race and settles within a block or two.
The node also exports Prometheus metrics with --metrics. See Metrics and Dashboards.

​
Reporting to the status page

Nodes can report their view to status.parallaxprotocol.org with --prlstats. More reporting nodes make its figures more robust, but a reporting node’s name, client version, country and latency become public. Exchanges usually leave their custody nodes off it. If you want to contribute, report from a separate node that holds nothing; see Setting up a node.

​
Upgrades

Parallax treats consensus rules the way Bitcoin does: they are meant to stay fixed, and a release is not an occasion to change them. Most releases are optional bug fixes and features. On the rare occasion a consensus change is needed, it activates at a block height, and the release carrying it is mandatory. Release notes say so explicitly. See Versioning.
  • Watch GitHub releases (GitHub can notify you of new releases only).
  • Run parallaxd version-check from monitoring. It downloads the project’s signed list of known vulnerabilities and reports whether your binary is affected.
  • Upgrade the watcher first, then the broadcaster, then the indexer. A node restart is quick, but blocks keep arriving: let the scanner catch up before resuming credits.
  • The status page shows how many reporting nodes run the latest release, and raises an info alert when some are behind.

​
Back up

Back up what cannot be rebuilt: your signing keys, wherever they live, and your scanner’s database. Chain data can always be resynced, though an archive resync takes days, so keep a recent snapshot of the indexer’s data directory if downtime matters. See Backup and restore.