Managing validator keys

Tempo validators use several keys and addresses. This page explains what each one does, how sensitive it is, and how to manage it.

Key and address overview

Generating a signing key

Generate an encrypted ed25519 keypair. The --secret argument points to a file-like input that contains the encryption key. Prefer a named pipe (FIFO) or shell process substitution for this path: a FIFO lets one process stream bytes directly to another process without storing those bytes as a regular file, and it keeps the secret out of environment variables and command-line arguments. See Why FIFOs and not env vars.

mkfifo /run/tempo/consensus-secret
<ENCRYPTION_KEY_CMD> > /run/tempo/consensus-secret &
tempo consensus generate-signing-key \
  --output <SIGNING_KEY_PATH> \
  --secret /run/tempo/consensus-secret

Verify the public key:

<ENCRYPTION_KEY_CMD> > /run/tempo/consensus-secret &
tempo consensus show-verification-key \
  --private-key <SIGNING_KEY_PATH> \
  --secret /run/tempo/consensus-secret

The verification key should match the output of the generate-signing-key command.

<ENCRYPTION_KEY_CMD> should be a command that retrieves the encryption key from your KMS or secret manager and writes the raw secret to stdout.

Encrypting an existing signing key

If you already have an unencrypted ed25519 signing key, encrypt it with tempo consensus encrypt-signing-key. The command reads the existing plaintext key, reads the encryption key from --secret, and writes a new encrypted key file.

tempo consensus encrypt-signing-key \
  --input <OLD_SIGNING_KEY_PATH> \
  --output <ENCRYPTED_SIGNING_KEY_PATH> \
  --secret <(<ENCRYPTION_KEY_CMD>)

Verify the encrypted key before replacing the old file:

tempo consensus show-verification-key \
  --private-key <ENCRYPTED_SIGNING_KEY_PATH> \
  --secret <(<ENCRYPTION_KEY_CMD>)

After the verification key matches the old signing key's public key, update --consensus.signing-key to point at the encrypted file and start tempo node with --consensus.secret <ENCRYPTION_KEY_PATH>.

Once the encrypted key is verified and backed up, delete the old unencrypted key file. On Linux, you can use shred to overwrite and remove the file:

shred --remove --zero <OLD_SIGNING_KEY_PATH>

Why FIFOs and not env vars

--secret accepts any filesystem path. The tempo node binary does not place extra restrictions on where it reads the secret from, so a regular file works, but a named pipe (FIFO) or process-substitution path is preferred. A FIFO is a special filesystem entry used to pass data between processes; it has a path, but the bytes written to it are streamed through the kernel rather than stored as regular file contents.

Use a FIFO so the encryption key is provided to tempo only when it is needed, without putting the key in the process environment or command-line arguments. Environment variables can be inherited by child processes and may be exposed through process inspection, crash dumps, shell history, or service-manager diagnostics. A FIFO also avoids leaving the secret behind in a regular file, though the producing command and tempo may still hold the value briefly in process memory while handling it.

mkfifo /run/tempo/consensus-secret
printf '%s' '<ENCRYPTION_KEY>' > /run/tempo/consensus-secret &
tempo consensus show-verification-key \
  --private-key <SIGNING_KEY_PATH> \
  --secret /run/tempo/consensus-secret

With shell process substitution and a KMS-backed secret command:

tempo consensus generate-signing-key \
  --output <SIGNING_KEY_PATH> \
  --secret <(<ENCRYPTION_KEY_CMD>)

Signing key rotation

The ed25519 signing key can be rotated while preserving your validator index and committee slot. See Rotate validator identity for the full procedure.

Validator operator address custody

The validator operator address is an Ethereum address, but it does not need to be controlled by a plaintext EOA private key. The Tempo CLI can submit validator on-chain operations with a local wallet key, a hardware wallet, or a remote KMS signer.

Use these signer flags for CLI commands that submit transactions to the validator contract, including rotation, IP updates, fee-recipient updates, deactivation, and ownership transfer.

Signing share recovery

If the signing share is lost — for example by deleting <datadir>/consensus — the node will recover a new share in the following epochs from the network when it restarts.

ValidatorConfig V2 precompile

All key and identity operations are executed through the ValidatorConfig V2 precompile (TIP-1017):

address constant VALIDATOR_CONFIG_V2 = 0xCCCCCCCC00000000000000000000000000000001;

Public validator write operations require the validator operator address.