Skip to main content

Run a local node

The supported hands-on entry point is the devnet script, which creates validator/signing processes and a separate observer RPC node.

Toolchain​

Use GCC 16, CMake 4.4+, Ninja, Conan 2 and OpenSSL 3. GCC's C++26 standard-library module support is required by the presets. The node build uses pinned RocksDB, evmone, cryptographic dependencies and Solidity compiler artifacts.

cmake --preset gcc16-release
cmake --build --preset gcc16-release --target \
  joltzu_validator joltzu_local joltzu_keygen joltzu_dev_signer

On Apple Silicon with an older selected assembler:

DEVELOPER_DIR=/Library/Developer/CommandLineTools cmake --preset gcc16-release
DEVELOPER_DIR=/Library/Developer/CommandLineTools cmake --build --preset gcc16-release \
  --target joltzu_validator joltzu_local joltzu_keygen joltzu_dev_signer

Use an installed current tools directory. This selection is command-local.

A minimal network for an explorer​

Run from cpp-node:

export OPENSSL="$(brew --prefix openssl@3)/bin/openssl"
tools/devnet.sh init build/devnet --validators 1
tools/devnet.sh start build/devnet

On Linux, set OPENSSL to the installed OpenSSL 3 executable instead of using brew. One validator, its signer and one observer are three processes. The observer provides RPC at port 30400 and the validator at 30401 by default. The observer supplies the validator's required peer connection.

Configure the devnet​

init supports --validators N (1–31), --chain-id ID, --base-port PORT and repeatable --fund ADDRESS. init validates every option before creating the directory: the chain ID must be a positive decimal, the base port at least 1024, and every derived port within range. JOLTZU_BUILD selects the build folder, defaulting to build/gcc16-release; init records it and later commands use that build. Startup refuses occupied ports. stop sends SIGTERM to validators, then signers, and force-stops anything still running after 30 seconds.

For remote access to your own observer:

ssh -L 8545:127.0.0.1:30400 NODE_HOST

Then use http://127.0.0.1:8545. This is a template; substitute the host. Remote public service uses the gateway.

Operating beyond one machine​

Peers need stable numeric IPv4 addresses, inbound reachability and certificate-bound names. Replace loopback peer addresses with reachable addresses, preserve certificate names and configure peer-bind explicitly. Firewalls should allow the intended peer ports from the intended peers. NAT traversal is not automatic.

The node includes a Docker build and Google Cloud Terraform/configuration tooling. Cloud infrastructure is paid; the free hosting option for this documentation does not cover validator operation.

The deployment tooling carries guardrails:

  • It refuses mainnet's chain ID (5658), because its development signer has no slashing protection.
  • Nodes run only a container image pinned by @sha256 digest. Base images are pinned by digest and downloaded source archives by SHA-256. Debian packages and some build tooling still resolve at build time.
  • Each VM reads only its own secrets, and SSH goes only through an identity-aware proxy.
  • The testnet gateway allowlists 32 node-served Ethereum methods at 50 requests per second per client.

The cloud tooling has not been run against a real project. Public deployment requires measured multi-host calibration and production key custody.