Validator hardening

Planned node software

Heartwood Core, the production Rust node, is still being built and does not yet ship a runnable relay or forger. A reference devnet runs now; the public testnet has not launched. This guide follows a working specification: parameters, economics, validator rules, commands, and configuration keys may change. Take exact commands from the release you install; see Network status for updates.

Missed slots carry no penalty. Under the draft, finality keeps progressing with up to 17 of the 53 validators crashed or offline; that is not proven against validators that deliberately build competing branches. Flooding a validator’s hosts threatens its rewards and, at scale, the network’s liveness. A stolen consensus key is worse: whoever holds it can sign conflicting blocks, and enough stolen keys would threaten the ledger’s safety, not just its liveness. Every node knows a round’s forging order when the round starts, so the next forgers are likely targets of flooding.

This guide covers what an operator can do: separate the keys, separate the processes, keep the relay that identifies the validator private, and firewall every host.

Separate the keys

A validator holds four ML-DSA-65 keys, each registered with a proof of possession. Keep each one on the host whose role needs it, and nowhere else.

Key	Where it lives	What it signs	If it is compromised
Account key	The operator’s wallet, never on a server	The validator’s transactions	That account’s funds; with a second key or a multisig account, one stolen key cannot spend
Consensus key	The forger	Blocks and online attestations, never transactions	Conflicting blocks can be signed; they are provable and punished by jailing and withheld rewards
Node key	The relay	The peer-to-peer connection transcript; its hash is the node’s identity	That relay can be impersonated on the peer-to-peer network
Migration attestation key	The IceRoot Connector, on its own machine or service	Migration attestations	One of the 36 attestations that a certification needs

• Keep the account key off every server. Consider registering a second key for the validator account, so that no single key can spend from it.
• Run each consensus key on exactly one forger. One key on two forgers can sign two blocks for one slot, which is evidence of misbehavior and leads to jailing. Never start a standby forger with the same key while the first one may still be running.
• Keep the signing record. For each key, the forger persists the last height, slot, and block hash it signed, and flushes the record to disk before a block leaves the forger. If the record is missing or older than the chain, the forger refuses to forge until the operator confirms with a command. When you move a forger to a new host, stop the old one first and move its signing record with the key.
• Restrict key files. A Heartwood process refuses to start if any key file it loads is readable by group or others. Make key files readable only by the account that runs the process.

Separate the processes

Heartwood runs each role as its own operating-system process. The planned command shape is heartwood <role> <command>, so a validator runs heartwood relay start and heartwood forger start as two processes.

• Relay. Talks to peers, validates and relays blocks and transactions, and holds the node key. It never reads the validator’s other keys; when it needs an online attestation, it asks the forger to sign one.
• Forger. Holds the consensus key. It opens no listener and serves no API. It reaches its relay over a small set of internal routes on the relay’s peer-to-peer port, which the relay admits only for addresses on its remoteAccess allow-list (planned configuration key). An empty allow-list admits nobody, and the node logs a warning.
• Combined mode. A mode that runs relay and forger in one process exists for testing. No default configuration or command selects it, and a validator should never use it, because it puts the consensus key inside the process that faces the network.
• IceRoot Connector. Runs on a machine or service separate from the relay and the forger, and reads each supported source network through the validator’s own node or a provider that the validator declares publicly. Under a declared policy, no provider serves more than 17 validators.
• Public services. Public API endpoints, history search, and the Mesh gateway belong on separate API nodes behind caching and rate limits, never on a validator’s relay.

When the forger runs on a different host from its relays, connect them over a private link, such as a WireGuard tunnel, and allow only the tunnel addresses. How a relay authenticates a remote forger’s online attestations is not yet fixed in the draft.

Sentry relays

Sentry relays are optional. They hide the relay that identifies the validator.

During connection setup, every relay presents its node key, and a validator’s relay must present the node key registered for that validator. Without sentries, that relay is reachable on the public network, and anyone can link its address to the validator. With sentries:

Host	Holds	Accepts connections from	Connects to
Sentry relay (public)	Its own node key, which carries no validator identity	Any peer, on the peer-to-peer port	Public peers and the validator relay
Validator relay (private)	The validator’s registered node key	The operator’s sentries and forger only	The operator’s sentries
Forger	The consensus key	Nothing: it has no listener	Two or three of the operator’s relays, with failover

Set it up in this order:

1. Start two or more sentries. Give each its own node key, never the validator’s. A relay that presents the registered node key is identified as the validator’s node.
2. Make the validator relay private. Close its peer-to-peer port to everyone except the sentries and the forger’s addresses, and point it at the sentries as its only peers. The configuration keys for fixed private peers are planned.
3. Give the forger failover. Configure the forger with two or three of your relays, and add the forger’s address to each relay’s remoteAccess allow-list. If one relay becomes unreachable, the forger continues through the next. The configuration key for the relay list is planned.
4. Keep the address private. Do not publish the validator relay’s address, and do not reuse it for other public services.
5. Check before your slot. Confirm that the forger reaches each configured relay and that the relays see the network, before relying on the setup in a live round.

A flooded sentry can be replaced with a fresh host and a new node key. Nothing registered on chain changes, because sentries carry no validator identity.

The explorer’s planned network views place validators only by their declared country and hosting provider, never by IP address, and never show forgers.

Default ports

Service	Mainnet	Public testnet	Devnets
Peer-to-peer (relay)	7668	17668	27668
Node API (relay)	7669	17669	27669
History search and event stream (indexer)	7670	17670	27670
Mesh gateway	7671	17671	27671

The public testnet adds 10000 to each mainnet port, and devnets add 20000. The forger has no port of its own. Operators can change any port in their configuration; update the firewall rules when you do.

Firewall each host

Deny inbound traffic by default and open only what each role needs. The ports below are mainnet defaults.

Host	Allow inbound	Allow outbound
Sentry relay	Peer-to-peer, 7668, from anywhere; administration from your own addresses	Peer-to-peer to public peers and to your validator relay
Validator relay, with sentries	Peer-to-peer, 7668, from your sentries and your forger only; administration from your own addresses	Peer-to-peer to your sentries
Validator relay, without sentries	Peer-to-peer, 7668, from anywhere; administration from your own addresses	Peer-to-peer to public peers
Forger	Administration from your own addresses only	Peer-to-peer, 7668, to its configured relays
Connector	Administration from your own addresses	Its source-chain node or declared provider; other needs come with the Connector release

• Keep the node API closed. Do not expose 7669 on a validator relay or on sentries. Reach it locally or over your private link, for example for heartwood relay status (planned command).
• Keep 7670 and 7671 off validator hosts. History search and the Mesh gateway run on separate API nodes when you offer them.
• Rate-limit at the edge. Each incoming handshake costs the accepting node an ML-DSA-65 signature, so nodes rate-limit incoming connections. Host public relays with a provider that offers DDoS protection.

Heartwood also defends itself: it scores peers and bans those whose misbehavior crosses a limit, keeps diverse outbound peers across subnets and providers, and caps inbound connections per subnet.

Declarations and diversity

Validators declare their operator, hosting provider, and country, and their source-chain access, in standard declarations that the indexer reads. The explorer shows seats per declared operator and per hosting provider, with alerts at 6 and 18 seats. Choosing a less common provider helps the network stay diverse. These views are transparency measures, not consensus rules.

Install releases safely

• Check checksums in two places. Compare the SHA-256 checksum in the GitHub release notes with the one in the announcement before installing. Reproducible builds are required before mainnet launches; once they are in place, you can also rebuild from the release tag and compare the result with the download.
• Watch for activation heights. A release that changes validity names an activation height on a round start. Nodes below the version floor are refused as peers from that height.
• Follow announcements. See Network status for where releases are announced and mirrored.

A separate diagnostic tool, the doctor, is planned. It runs deterministic checks of a node’s configuration and state and exports a report with keys, secrets, and IP addresses removed.

Checklist

• The account key is on no server, and the validator account has a second key or multisig setup.
• Each consensus key runs on exactly one forger, and its signing record moves with it.
• Key files are readable only by the account that runs each process.
• The Connector runs on its own machine or service, with declared source-chain access.
• The forger has no listener and reaches its relays over private links.
• If you use sentries, only the private validator relay holds the registered node key.
• The node API, history search, and the Mesh gateway are not exposed on validator hosts.

Validators and voting → · Network configuration →