Setup PulseChain Node

Interactive PulseChain node installation with persistent storage, pruning choices, and optional validator preparation.

Choose execution and consensus independently for a fresh installation:

Execution client	Consensus choices
Erigon-Pulse 2	Lighthouse-Pulse or Prysm-Pulse
Go-Pulse / Geth	Lighthouse-Pulse or Prysm-Pulse

The wizard defaults to Lighthouse for Erigon 2 and Prysm for Geth. The validator client follows the consensus choice. Erigon 3 is planned, not installable.

Docker runs on Linux, macOS, and Windows. Native systemd installation is Linux-only: Debian/Ubuntu, RHEL/Fedora/Rocky/Alma, and Arch/Manjaro. Windows uses Docker Desktop with Ubuntu WSL2 integration. Client artifacts are pinned in manifests/versions.env.

The repository is private and requires field testing. Full mainnet synchronization and live validator duties remain unverified. macOS, Windows, and ARM64 host execution still need testing on those platforms.

Setup

From a checkout on Linux or macOS:

./run.sh

Choose execution, consensus, runtime, pruning, optional validator preparation, and storage. Review the summary before installation. Rerun the launcher for the management menu. Keep the host awake and Docker running during synchronization and operation.

On Windows, open PowerShell in the checkout:

./run.ps1
./run.ps1 -ExecutionClient erigon2 -ConsensusClient prysm

Windows setup offers Docker Desktop and WSL2 prerequisites. First launch or a reboot may require rerunning the command. Missing prerequisites require confirmation; --yes alone does not authorize Docker installation.

For unattended Linux installation, specify both clients, runtime, profile, and data directory:

./run.sh install --execution-client erigon2 --consensus-client prysm \
  --mode docker --profile pruned --data-dir /blockchain --yes

Append --dry-run to render configuration without installation or startup; this requires jq. Use --help for all options. ./run.sh clients lists clients and allowed pairings.

Legacy --stack erigon2 selects Erigon 2 + Lighthouse; --stack geth selects Geth + Prysm. Existing shell wrappers and PowerShell -Stack retain those presets. Do not combine a preset with independent client options. Existing installations retain their saved clients, storage, and JWT. Switching clients or reusing another client's database is not implemented.

Storage and Pruning

Profile	Retention
archive	Full historical state and supported indexes.
pruned	Bounded history and indexes.
max-pruned	The most aggressive supplied profile retaining deposit history needed for later validator preparation.
custom	Execution-client retention settings shown by --help.

Pruning cannot recover deleted history. Established runtime, client, storage, and pruning settings cannot be changed in place. The storage preflight is a conservative budget; --allow-low-resources explicitly overrides it.

Docker data uses external volumes and survives container recreation and both forms of Compose teardown. Linux volumes use selected host folders; Desktop defaults use its VM disk. Independent backups are required for disk failure, deliberate deletion, or Desktop reset.

Fresh installations can assign execution/consensus roots and client-specific storage to separate disks: Erigon snapshots/temp, Geth ancient storage, Lighthouse freezer, or Prysm blobs. Only options for the selected clients are accepted. Use fast SSD/NVMe for active databases and recent blobs; slower historical storage reduces query performance. Desktop host binds may be slower than VM volumes; validator credentials remain VM-backed.

Custom paths must be absolute, initially empty, mounted, writable, and nonoverlapping. No disk formatting or filesystem-table changes are performed. Split-disk capacity requires acknowledgment because per-folder growth requirements remain unverified. Erigon temp uses an owned storage root with a disposable work/ child.

Startup checks storage identity, including automatic container restarts. Missing/replaced storage or JWT stops the operation without creating replacements. Do not remove an operation lock until its recorded process has stopped.

Manage the Node

Linux installs the manager as setup-pulsechain-node; macOS uses ~/.local/bin, which must be in PATH. On Windows, forward commands with ./run.ps1 -NodeArguments @('status').

setup-pulsechain-node status
setup-pulsechain-node doctor
setup-pulsechain-node logs consensus
setup-pulsechain-node locations
setup-pulsechain-node stop

RPC binds to localhost 8545; optional WebSocket uses 8546. Docker does not publish the Engine API. Lighthouse REST uses localhost 5052; Prysm REST uses localhost 3500 and readiness metrics use localhost 18080.

Execution P2P uses 30303 TCP/UDP, plus 42069 TCP/UDP for Erigon. Consensus uses 9000 TCP/UDP and 9001 UDP for Lighthouse, or 13000 TCP and 12000 UDP for Prysm. --configure-firewall updates a supported active Linux firewall or prints the selected ports. Configure router forwarding separately.

Optional Validator

Prepare the validator during installation or enable it later:

setup-pulsechain-node validator enable --fee-recipient 0xYOUR_FEE_RECIPIENT

Lighthouse enables deposit sync and catches up its cache; Prysm uses its own readiness checks. Generate keys externally and follow the PulseChain launchpad for deposits. The installer does not generate mnemonics or submit deposits.

For keys that have never signed:

setup-pulsechain-node validator import --keys-dir /path/to/validator_keys --fresh-keys

For previously used keys, stop the old signer and supply its EIP-3076 slashing history:

setup-pulsechain-node validator import --keys-dir /path/to/validator_keys \
  --slashing-protection /path/to/slashing.json --previous-validator-stopped

Each keystore password is prompted separately. Never run the same validator keys on two machines. Keep offline backups of keys, recovery material, and slashing protection. Imported keys remain stopped until explicitly started:

setup-pulsechain-node validator start
setup-pulsechain-node validator stop

Start checks network identity, current execution/consensus state, deposit readiness, time, peers, and imported credentials/slashing protection. Both validator clients use doppelganger protection. validator configure changes fee recipient or graffiti and leaves signing stopped.

Update and Checks

Run ./setup-pulsechain-node update from a reviewed newer checkout. Both selected clients must retain their adapters and database generations. Artifacts are staged before activation; signing remains stopped afterward. rollback permits the same pairing, generations, and client versions; cross-version database downgrades are refused.

Tests require Bash, jq, OpenSSL, and Docker Compose where used. Python tests require Python 3; keystore fixtures also require cryptography. PowerShell forwarding tests require PowerShell 7. Docker tests use disposable resources.

bash tests/client-selection.sh
bash tests/manager.sh
bash tests/update-selection.sh
bash tests/locations.sh --docker
bash tests/clients.sh --pull
bash tests/startup.sh
bash tests/validator-import.sh
pwsh -NoProfile -File tests/windows-selection.ps1

The optional tests/client-pairs.py integration test takes --fixture-generator (a verified prysmctl supporting Bellatrix genesis, tested with v5.1.2), --consensus-config (consensus YAML), and a new --output directory. It runs bounded pairs on isolated Docker networks without mainnet synchronization; Prysm fixtures use deterministic test validators behind a custom-genesis isolation check.

License

MIT — see LICENSE.