> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parallaxprotocol.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Running your nodes

> How an exchange should deploy parallaxd: topology, sync and history settings, locking down JSON-RPC, health checks and upgrades.

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:

| Node | Role | Settings |
| - | - | - |
| **Deposit indexer** | Follows the chain, feeds your deposit scanner, answers traces | Full history and tracing: `--syncmode full --gcmode archive --txlookuplimit 0` |
| **Withdrawal broadcaster** | Accepts your signed withdrawals and relays them | Default snap sync is fine |
| **Watcher** | An independent view of the chain for cross-checks and alerts, ideally in a different network or region | Default snap sync is fine |

Comparing the head of each node against the others, and against the
[status page](./status-api), 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](/v2.1.x/parallax-client/getting-started/hardware-requirements).
An archive node needs considerably more disk than a pruned one and grows
with every block.

## Install

Download a release from [GitHub](https://github.com/ParallaxProtocol/parallax/releases)
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](/v2.1.x/parallax-client/getting-started/installing-client)
and [Versioning](/v2.1.x/parallax-client/fundamentals/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](/v2.1.x/parallax-client/interacting-with-parallax/command-line-rpc).
* `parallax-wallet`, an offline key tool that never talks to a node. See
  [parallax-wallet](/v2.1.x/parallax-client/tools/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](/v2.1.x/parallax-client/fundamentals/config-files). Flags
given on the command line override the file.

A deposit indexer, as a systemd service:

```ini /etc/systemd/system/parallaxd.service theme={null}
[Unit]
Description=Parallax node (deposit indexer)
After=network-online.target
Wants=network-online.target

[Service]
User=parallax
ExecStart=/usr/local/bin/parallaxd \
  --datadir /var/lib/parallax \
  --syncmode full --gcmode archive --txlookuplimit 0 \
  --http --http.addr 127.0.0.1 --http.port 8545 \
  --http.api eth,net,web3,txpool \
  --ws --ws.addr 127.0.0.1 --ws.port 8546 --ws.api eth,net,web3 \
  --metrics --metrics.addr 127.0.0.1
ExecStop=/usr/local/bin/parallax-cli --datadir /var/lib/parallax stop
Restart=on-failure
TimeoutStopSec=300

[Install]
WantedBy=multi-user.target
```

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

| Service | Default | Exposure |
| - | - | - |
| P2P (TCP and UDP) | `32110` | Open to the internet, so the node can find and serve peers |
| HTTP JSON-RPC | `8545` | Off until `--http`. Localhost or a private network only |
| WebSocket JSON-RPC | `8546` | Off until `--ws`. Localhost or a private network only |
| GraphQL | `8547` | Off until `--graphql`. Leave off unless you use it |
| Metrics | `127.0.0.1:6060` | Off until `--metrics`. Private only |
| IPC | `<datadir>/parallax.ipc` | On by default. Local only, carries every namespace |

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](/v2.1.x/parallax-client/fundamentals/connecting-to-peers).

## Lock down JSON-RPC

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

* **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](./withdrawals#where-keys-live)). 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:

| Flag | Default | Effect |
| - | - | - |
| `--rpc.txfeecap` | `1` (LAX) | `eth_sendRawTransaction` rejects a transaction whose fee (gas limit × gas price) exceeds this. Raise it only if you deliberately send very large contract calls at high prices |
| `--rpc.allow-unprotected-txs` | off | Transactions without an EIP-155 chain ID are rejected. Leave it off |

## History and indexing

How much history a node keeps decides what your scanner can ask it:

| Need | Setting |
| - | - |
| Look up any transaction by hash, however old | `--txlookuplimit 0`. The default, `52560`, indexes only the last 52,560 blocks, about a year at 10 minutes. Older transactions stay in their blocks but `eth_getTransactionByHash` and `eth_getTransactionReceipt` return nothing for them |
| Trace transactions in recent blocks (internal transfers) | Any full node. Tracing re-executes from the nearest stored state, which on a pruned node is at most 128 blocks back, about 21 hours |
| Trace any historical block quickly, or read balances at old heights | `--gcmode archive`. Best combined with `--syncmode full`, which verifies every block from genesis |

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](/v2.1.x/parallax-client/fundamentals/sync-modes) and
[Pruning](/v2.1.x/parallax-client/fundamentals/pruning).

## Health checks

Before crediting anything, your scanner should know the node is synced and
current. Check, at least once a minute:

```bash theme={null}
# false once synced; an object with progress while syncing
parallax-cli syncing

# head number, hash and timestamp
parallax-cli tip

# peer count, chain, versions, mempool, all in one
parallax-cli info
```

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](./confirmations#halt-conditions) 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](/v2.1.x/parallax-client/monitoring/metrics) and
[Dashboards](/v2.1.x/parallax-client/monitoring/creating-dashboards).

### Reporting to the status page

Nodes can report their view to [status.parallaxprotocol.org](https://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](/v2.1.x/guides/client/setup).

## 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](/v2.1.x/parallax-client/fundamentals/versioning#consensus-is-not-versioned-by-releases).

* Watch [GitHub releases](https://github.com/ParallaxProtocol/parallax/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](/v2.1.x/parallax-client/fundamentals/backup-and-restore).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.