Validator lifecycle

A machine with a TPM 2.0 or a Secure Enclave, or one that reaches another machine's TPM through a key holder, can validate Tenzro Network. This page follows a validator from first boot to exit: how its keys work, how it joins the active set, how to upgrade and move it, and how it leaves.

Keys from hardware

A validator has no key file. Its identity is a hardware key in the TPM 2.0 (or a Secure Enclave on Apple hardware), or in the TPM of another machine the operator owns, reached through a key holder (see below):

• Signing keys are derived from the hardware on demand, used in memory and wiped.
• The hardware key signs the handshake of every validator channel, as a composite ML-DSA-65 plus P-256 signature. See Networking.
• At the start of each epoch the hardware certifies an in-memory session key. The validator signs its consensus votes for that epoch with the session key, so the TPM is not on the hot path of every round.
• When the epoch ends the session key is discarded and a new one is certified.

Because every vote chains back to a hardware key, a validator's signatures are attributable, and conflicting signatures are evidence for slashing.

A key held in another machine's TPM

A machine with no TPM of its own can hold the validator role through a key holder: tenzro-node tpm serve runs on a machine with a TPM, tenzro-node tpm key-holder runs beside the validator, and the node starts with --tpm-key-holder <socket> --tpm-label <label>. The P-256 leg of the consensus key is a key in the provider's TPM and the ML-DSA-65 leg is derived there for each use. Restrictions:

• The operator's passkey must grant the key holder's transport key for a limited time, and again after every reboot of the key holder. Without an unexpired grant the validator cannot sign.
• Each signature is a round trip to the provider, which queues its TPM commands, so the provider must stay reachable.
• The provider's file must enrol the client for derived keys.
• The ML-DSA-87 plus P-384 scheme is not available this way; it needs a TPM in the validator's own machine that implements ML-DSA and P-384.
• A passkey never holds a consensus key. It authorizes the operator and grants the key holder; the key stays in a TPM or Secure Enclave.
• Such a machine cannot be a genesis validator: the genesis entry (tenzro-node validator-entry) is read only from the machine's own TPM or Secure Enclave. It joins after genesis with tenzro validator register --tpm-key-holder.
• The key holder talks to the node over a Unix socket, so it runs on Linux and macOS only. A Windows machine with no TPM 2.0 cannot run a node.

States

tenzro validator list --status Active
tenzro validator get 0xValidatorAddress

1. Start the node

Build or install tenzro-node (see Deployment) and start it with the validator role:

tenzro-node \
  --roles validator \
  --data-dir ./data \
  --genesis genesis.toml

genesis.toml is the genesis file published with the release; check it first (see Verify your download). Run a validator node gives the full requirements and steps. The node derives its keys from the TPM, joins the network as a non-voting peer and replays the chain from block 0 until it reaches the network's finalized height. A validator always joins by block replay; see State and snapshots.

The guided setup does the same and writes the configuration for you:

tenzro setup --path network --mode validate

2. Register

Registration is a signed transaction from the account that owns the stake. It records the validator's hardware key, a withdrawal address for rewards and unbonded stake, and the self-stake. A node can register itself on start with --validator-self-stake, or you can register from the CLI with tenzro validator register.

Any machine can join and follow the chain without approval. The self-stake is set by governance (stake.validator_tnzo, 10,000 TNZO at genesis). A governed switch, validator.admission_approval, is 1 in the launch genesis (the preview), so a new validator registers only from an account that an enacted approve_validators proposal named; a vote sets it to 0 to open admission. Validators named at genesis or already registered are not affected. Amounts on tenzro validator and tenzro stake are TNZO (10000 or 10000 TNZO); wei needs its suffix.

If the account cannot cover the stake, an approved operator can apply for a sponsored bond. See Sponsorship and grants. One stake can also back other roles the node runs; see Operators and roles.

3. Activate at the epoch boundary

The validator set changes only at epoch boundaries. A registered validator becomes PendingActive, then Active at the next boundary, when its first session key is certified and its channels to the other validators are opened. From then on it proposes a vertex every round and signs checkpoints; see Consensus.

Rewards come from fees and from rewards for validator duties, and are paid to the withdrawal address.

To add stake without re-registering:

tenzro validator increase-stake --additional 500

Upgrading the binary

An upgrade is a stop and restart against the same data directory. On start, the node checks the chain on disk against the configured genesis. If they match, it keeps its database and carries on; if they differ, it refuses to start with an error, so a node never runs on the wrong chain by mistake.

Moving to new hardware

A validator's identity is its registered hardware key. To move to a new machine, submit a key-rotation transaction for the registered key, signed by the current key. The new key takes over at the next epoch boundary, when every validator picks up the change at once, so there is no window with two live keys.

Bootstrap discovery

--boot-nodes takes machine identities (did:tenzro:machine:<id>, optionally with a relay URL), never network addresses. Without it, a node joins through the genesis validators. See Networking.

4. Exit

To leave, send an exit transaction, signed by the stake owner's hardware key:

tenzro validator exit

The validator moves to PendingExit, keeps validating until the next epoch boundary, then becomes Exited. Its bond enters a 7-day unbonding period and is then released to the withdrawal address. Evidence of misbehavior from its active time can still be submitted during unbonding.

Slashing

A validator is slashed for signing two conflicting checkpoints, proven by its own signatures, or for a provable breach of its own signed operator policy. Slashing burns the offender's bond and removes it from the active set.

Jail is never permanent. A jailed validator returns as a candidate, admitted again like any candidate by the activation churn cap and the self-stake floor, in one of two ways. The term can run out: slashing.jail_term_epochs (720 epochs at genesis) counts from the epoch of the jailing. Or governance can reinstate it with a reinstate_validator proposal, which releases the validator at the next epoch boundary. Reinstatement does not undo the slash. tenzro_listValidators shows the epoch a jailed validator is released from (jailed_until_epoch). See Slashing and Governance.

Monitoring

curl -s https://rpc.tenzro.com \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tenzro_listActiveValidators","params":[]}'

Your own node reports its state, roles, height and peers at GET /status on its Web API, and exports Prometheus metrics at /metrics.