Ergo Rust Node

An independent Rust full node for Ergo, built for consensus compatibility with the Scala reference client. It is for node operators, miners, and developers who want to explore a Rust implementation. Pre-1.0 alpha: do not use it for funds custody or production infrastructure. Read the security policy and compatibility limits.

Get started

Download

Download the archive for your platform from GitHub Releases. Each archive holds both programs, ergo-node and the ergo-wallet CLI, with config templates and docs. These six platforms are built by the release workflow:

Platform	Archive
Linux x86-64, glibc	ergo-x86_64-unknown-linux-gnu.tar.gz
Linux x86-64, static musl	ergo-x86_64-unknown-linux-musl.tar.gz
Linux ARM64, glibc	ergo-aarch64-unknown-linux-gnu.tar.gz
macOS Apple Silicon	ergo-aarch64-apple-darwin.tar.gz
macOS Intel	ergo-x86_64-apple-darwin.tar.gz
Windows x86-64, MSVC	ergo-x86_64-pc-windows-msvc.zip

Verify it against the release's SHA256SUMS, for example sha256sum --ignore-missing -c SHA256SUMS on Linux.

Run

Extract the archive into its own directory. From that directory:

./ergo-node init --data-dir ../ergo-data

init asks what the node is for (wallet, mining, explorer or archival) and how to sync, then writes a validated config and a protected API key into the data directory and prints the command that starts the node. For scripted setups, pass the choices as flags; see ./ergo-node init --help. To configure by hand instead:

cp config/ergo-node.toml ./ergo-node.toml
./ergo-node --config ./ergo-node.toml --data-dir ../ergo-data

On Windows, use ergo-node.exe. Open the dashboard at http://127.0.0.1:9099/. Keep the data directory outside the extracted archive so upgrades do not replace it. See the release quickstart.

Choose a setup

Edit the copied ergo-node.toml before starting; update its existing sections.

Preset	Settings	What to expect
Archival + explorer (default)	[node] state_type = "utxo", verify_transactions = true, blocks_to_keep = -1; [indexer] enabled = true	Full history and address/token queries; long sync from genesis.
Fast bootstrap	[node.utxo] utxo_bootstrap = true; [node.nipopow] nipopow_bootstrap = true; [indexer] enabled = false	UTXO snapshot + NiPoPoW; about 20 minutes on mainnet, depending on peers and bandwidth.
Mining	[node] state_type = "utxo"; [mining] enabled = true; reward key as described below	External miner API; starts serving work after sync.

For fast bootstrap, start with an empty data directory and use these settings:

[node]
state_type = "utxo"
verify_transactions = true
blocks_to_keep = -1
[node.utxo]
utxo_bootstrap = true
[node.nipopow]
nipopow_bootstrap = true
p2p_nipopows = 2
[indexer]
enabled = false

Snapshot trust verification is provisional. Cross-check the installed UTXO root against a known-good reference before trusting the state. Read the fast bootstrap guide and configuration reference.

Mining needs either [mining] miner_public_key_hex (a 33-byte compressed secp256k1 public key, 66 hex characters; ergo-wallet pubkey prints it from a mnemonic) or an initialized node wallet, whose first EIP-3 key is used. The node supplies mining work through REST, so GPU rigs need a Stratum server or pool in between: for example ergo-solo for solo mining, or Lithos. See mining templates.

Unlock wallet and mining

Wallet routes, mining controls, and other privileged calls need an API key. The dashboard and public reads work without one. ergo-node init already creates one; for a hand-written config, create a key:

./ergo-node api-key generate --secret-file ./api-key.secret

This saves a random secret in a new file only you can read, and prints the line to add to your config:

[api.security]
api_key_hash = "<64 lowercase hex characters>"

Add it to ergo-node.toml and restart the node. Clients send the secret from the file, not the hash, in the api_key header; enter it in the dashboard to authorize privileged calls. Then initialize or unlock your wallet. ergo-node api-key hash --secret-file PATH prints the hash for an existing secret. See API authentication.

Requirements

• Mainnet P2P uses TCP port 9030. The default config is outbound-only; set [peers] bind_addr to accept inbound connections.
• The API and dashboard bind to 127.0.0.1:9099 by default. Keep remote access behind an authenticated reverse proxy. See API security.
• The explorer index roughly doubles disk usage. For scale, one mainnet archival node in October 2026 used about 44 GB for state, 45 GB for the index and about 3 GB of RAM. Memory includes a default 1 GiB tree cache plus separate 1 GiB cache budgets for state, indexer, and peer databases; these do not limit total memory use. See resource planning.

Run as a service

Linux systemd and Docker Compose packages are included. Systemd uses an unprivileged user and persistent state. Compose keeps data in a named volume and publishes the API on host loopback. Follow deployment instructions.

Upgrading

Stop the old node cleanly and back up its data and config before upgrading. 0.11 data upgrades automatically when started with the new binary. Conversion needs extra free space, and the explorer index rebuilds in the background. Read the 0.11 upgrade guide and operating instructions first.

What you get

• Dashboard: Overview with charts and events, Explorer, Peers, Mempool, Mining, Voting, and Wallet. See monitoring.
• REST APIs: Scala-compatible routes plus the native /api/v1/* API. Browse /swagger and /swagger/native on your node; see API coverage.
• Events and webhooks: polling, realtime WebSocket subscriptions, replay, and delivery. See the events guide.
• Mining: external-miner candidates and solutions, exact candidate inspection, fee estimates, block policies, and private transactions. See mining, block policies, and private mining.
• Wallet CLI: mnemonic generation/import, key derivation, addresses, and encrypted keystore export. Run ./ergo-wallet --help; see wallet usage and keystore export.
• Offline recovery: doctor, utxo-stats, backup, verify-backup, restore, and wallet-scan-utxo. Stop the node first and follow the recovery guide.

Status

Consensus paths have oracle-backed tests and mainnet validation evidence; deployment exposure is limited. Read compatibility and mode evidence for scope and remaining work.

Capability	Status	Caveat
Mode 1 — full archive	Supported	Long initial sync
Mode 2 — UTXO snapshot, consume + serve	Supported	Provisional snapshot trust
Mode 3 — pruned history	Supported	Fresh stores replay from genesis before pruning; retention campaigns open
Mode 4 — pruned + snapshot	Supported	Live multi-peer soak outstanding
Mode 5 — digest verifier	Supported	AD-proof parity pinned to one mainnet window; reorg re-anchor open
Mode 6 — headers only	Supported	No transaction validation or UTXO queries
NiPoPoW, consume + serve	Supported	Bootstrap requires compatible settings
Explorer index (/blockchain/*)	Supported	Full archive required
External-miner protocol	Supported	UTXO state required
HD wallet and multisig primitives	Supported	Cooperative distributed multisig deferred

For developers

Build and test

Rust 1.99.0 is pinned in rust-toolchain.toml; rustup installs it on first build. From a source checkout:

cargo build --locked --release -p ergo-node
cargo build --locked --release -p ergo-wallet
./target/release/ergo-node --config ergo-node/ergo-node.toml

The core checks are:

cargo fmt --all -- --check
python3 scripts/check-rust-fragments.py
cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
cargo test --locked --workspace
RUSTDOCFLAGS="-D warnings" cargo doc --locked --workspace --all-features --no-deps
python3 scripts/ci-policy.py

The contribution guide gives the full local gate and feature-gated tests. The overview covers build profiles and workflows; ARCHITECTURE.md and the codemap explain runtime boundaries and crate responsibilities.

Correctness and contributions

Consensus-boundary tests use external Scala fixtures and real mainnet bytes, never self-oracles. Expected values computed by the code under test show internal consistency, not compatibility. Mainnet-observed behavior settles parity disputes. sigma-rust is a dev/test oracle and never part of the consensus path.

Changes to consensus crates (ergo-primitives, ergo-ser, ergo-crypto, ergo-sigma, ergo-validation, ergo-state, ergo-mining) require oracle-backed fixtures. Keep fixtures in test-vectors/ with reproducible provenance. Read contribution rules and compatibility policy.

Documentation

Operators

• Release quickstart · Configuration
• Operating and modes · Deployment
• Offline recovery · Operator controls
• Mining · Lithos · Wallet mining jobs
• Events and webhooks · Logging · Release notes

Developers

• Architecture · Codemap · Overview
• Compatibility · Operating-mode evidence
• Contributing · Releasing · Code of conduct

Security

Pre-1.0: do not use this node for production infrastructure or funds custody. Report consensus, state-integrity, remote-input crash, and cryptographic-verdict issues privately through a GitHub Security Advisory. See SECURITY.md. Findings against the dev oracle sigma-rust belong upstream.

License

Dual-licensed under MIT or Apache 2.0, at your option. See LICENSE-MIT and LICENSE-APACHE.