Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
19f79a3
docs: expand initial registration section with all required values
decofe Mar 30, 2026
ac87d54
docs: move initial registration to 'Running a validator' page
decofe Mar 30, 2026
d6f56fe
docs: rename to 'Deploying a validator' and make it the first section
decofe Mar 31, 2026
96cdd6f
docs: move deploying a validator details into validator-config-v2
decofe Mar 31, 2026
dd13e2d
docs: simplify validator intro and flatten info block
decofe Mar 31, 2026
056e94c
docs: shorten deploying a validator link text
decofe Mar 31, 2026
b58dc03
docs: make Initial registration the first subsection under Operator g…
decofe Mar 31, 2026
e9f1e2c
docs: move generating a signing key into validator-config-v2 under in…
decofe Mar 31, 2026
1c70534
docs: use zero address for fee burning
decofe Mar 31, 2026
efa1848
docs: link to generating a signing key from rotate section
decofe Mar 31, 2026
2c62602
docs: flatten validator sidebar into single 'Running a validator' group
decofe Mar 31, 2026
5ba0418
remove bit on --consensus.fee-recipient
SuperFluffy Apr 7, 2026
62a4f69
docs: expand rotate-validator with all required arguments
decofe Apr 7, 2026
7b5507b
docs: remove V2 activation check, link mainnet activation tx
decofe Apr 7, 2026
65eab07
docs: warn against sharing private signing key
decofe Apr 7, 2026
f068553
docs: simplify rotate section, mention create-rotate-validator-signat…
decofe Apr 7, 2026
bab0e36
docs: fix wording on V2 activation
decofe Apr 7, 2026
d913636
Merge branch 'main' into janis/expand-initial-registration
SuperFluffy Apr 7, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 61 additions & 31 deletions src/pages/guide/node/validator-config-v2.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: Manage your validator with ValidatorConfig V2. Self-service key rot

ValidatorConfig V2 ([TIP-1017](/protocol/tips/tip-1017)) is a new precompile for managing consensus participants. It replaces the original ValidatorConfig with stronger safety guarantees: ed25519 signature verification at registration, append-only history, and self-service operations for validators.

V2 becomes available after the T2 hardfork is activated and after an admin has finished the migration of entries from V1 to V2. Migration completion will be communicated to operators — you can also [check if V2 is active](#check-if-v2-is-active) yourself.
V2 was [activated on mainnet](https://explore.mainnet.tempo.xyz/receipt/0x4716147e3c2bf5c8d014b8c27d6e2af0042d5a5f29bdead256d6f33038702d64) after the T2 hardfork.

## Validator states

Expand Down Expand Up @@ -38,24 +38,6 @@ All write operations require either the contract owner or the validator's own ad
address constant VALIDATOR_CONFIG_V2 = 0xCCCCCCCC00000000000000000000000000000001;
```

## Check if V2 is active

After the T2 hardfork, the contract owner migrates validators from V1 to V2. Use these calls to check if migration is complete and V2 is active:

```bash
# Returns true once migration is complete and V2 is the active config
cast call 0xCCCCCCCC00000000000000000000000000000001 \
"isInitialized()(bool)" \
--rpc-url https://rpc.tempo.xyz

# Returns the block height at which V2 was initialized (0 if not yet initialized)
cast call 0xCCCCCCCC00000000000000000000000000000001 \
"getInitializedAtHeight()(uint64)" \
--rpc-url https://rpc.tempo.xyz
```

If `isInitialized()` returns `true`, V2 is active and all operations on this page are available. If it returns `false`, the network is still on [ValidatorConfig V1](/guide/node/validator-config-v1).

## Reading validator state

### Query active validators
Expand Down Expand Up @@ -96,6 +78,58 @@ The returned `Validator` struct fields are:

## Operator guide

### Initial registration

To register a new validator, you must provide the following values to the Tempo team:

| Value | Format | Description |
|-------|--------|-------------|
| **Validator address** | Ethereum address (`0x…`) | The control address for your validator. Used to authorize on-chain operations (IP updates, rotation, ownership transfer). |
| **Public key** | `0x`-prefixed 32-byte hex | Your ed25519 identity key. Generate one with `tempo consensus generate-private-key` (see [below](#generating-a-signing-key)). |
| **Ingress** | `IP:port` | The inbound address other validators use to reach your node. Must be unique across all active validators. |
| **Egress** | `IP` | The outbound IP address your node uses to connect to other validators. |
| **Fee recipient** | Ethereum address (`0x…`) | The address that receives transaction fees from blocks your validator proposes. If you are not prepared to accept fees, use `0x0000000000000000000000000000000000000000`. |
Comment thread
SuperFluffy marked this conversation as resolved.
| **Signature** | `0x`-prefixed hex | An ed25519 signature proving you control the signing key. See below. |

#### Generating a signing key

:::warning
Never share your private signing key. Anyone with access to it can impersonate your validator.
:::

Generate an ed25519 keypair:

```bash
tempo consensus generate-private-key --output <path>
Comment thread
SuperFluffy marked this conversation as resolved.
```

Verify the public key:

```bash
tempo consensus calculate-public-key --private-key <path>
```

The public key should match the output of the `generate-private-key` command.

#### Creating the add-validator signature
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if we add this, should we also add a section for create-rotate-validator-signature, or at least mention it?


The signature proves ownership of the ed25519 key being registered. Generate it with:

```bash
tempo consensus create-add-validator-signature \
--signing-key <PRIVATE_KEY_PATH> \
--validator-address <YOUR_VALIDATOR_ADDRESS> \
--public-key <YOUR_PUBLIC_KEY> \
--ingress <IP:PORT> \
--egress <IP> \
--fee-recipient <FEE_RECIPIENT_ADDRESS> \
--chain-id-from-rpc-url https://rpc.tempo.xyz
```

This outputs a hex-encoded signature. Provide this signature along with the values above to the Tempo team to complete registration.

Once the Tempo team adds your validator on-chain, it will enter the active set in the [next epoch](#validator-states).

### Update the Fee Recipient

The fee recipient used by your validator when constructing block proposals is managed on-chain. This can be updated and takes effect on the next finalized block
Expand All @@ -106,7 +140,6 @@ tempo consensus set-validator-fee-recipient <address/pubkey/index>
--rpc-url https://rpc.tempo.xyz
--private-key <PATH_TO_VALIDATOR_PRIVATE_KEY>
```

### Update IP addresses

If your node's network endpoints change, update them on-chain. The change takes effect at the next finalized block.
Expand All @@ -127,16 +160,23 @@ Ingress addresses must be unique across all active validators. The transaction w

### Rotate validator identity

V2 lets you rotate to a new ed25519 key while keeping your validator index stable. This is useful for key rotation or recovery without leaving and re-joining the committee.
V2 lets you rotate to a new ed25519 key while keeping your validator index stable. This is useful for key rotation or recovery without leaving and re-joining the committee. [Generate a new signing key](#generating-a-signing-key) first.

The simplest way to rotate is using the `tempo` CLI, which handles signature creation and the on-chain transaction in one step:

```bash
tempo consensus rotate-validator \
--validator-address <YOUR_VALIDATOR_ADDRESS> \
--public-key <NEW_PUBLIC_KEY> \
--ingress <NEW_IP:PORT> \
--egress <NEW_IP> \
--signing-key <NEW_PRIVATE_KEY_PATH> \
--private-key <ETHEREUM_PRIVATE_KEY_PATH> \
--rpc-url https://rpc.tempo.xyz
```

If self-service rotation is not yet enabled for your validator, use `tempo consensus create-rotate-validator-signature` to generate the signature and provide it to the Tempo team.

:::info
Rotation preserves your validator index and active validator count. The old entry is appended to history as deactivated, and the entry at your index is updated in place. You must use a different ingress address (changing the port is sufficient).
:::
Expand All @@ -155,16 +195,6 @@ tempo consensus validators-info --rpc-url https://rpc.tempo.xyz
Once the old validator shows `in_committee = false`, it is safe to shut down.
:::

#### Initial registration

When registering a new validator, generate the add-validator signature and provide it to the Tempo team:

```bash
tempo consensus create-add-validator-signature \
--signing-key <PRIVATE_KEY_PATH> \
--rpc-url https://rpc.tempo.xyz
```

### Transfer validator ownership

Rebind your validator entry to a new control address:
Expand Down
27 changes: 4 additions & 23 deletions src/pages/guide/node/validator.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@ description: Configure and run a Tempo validator node. Generate signing keys, pa

# Running a validator node

:::info
The management of the active validator set is currently permissioned by the Tempo team. If you are interested in becoming a validator, please [get in touch](mailto:partners@tempo.xyz) with the Tempo team.
:::
Validator nodes secure Tempo by validating blocks and participating in consensus.

Validator nodes secure Tempo by validating blocks and transactions, then using [Threshold Simplex](https://docs.rs/commonware-consensus/0.0.61/commonware_consensus/threshold_simplex/index.html) to reach consensus. They distribute signing shares among themselves to collectively sign block approvals and finalizations.
## Deploying a validator

The active validator set is currently permissioned. If you are interested in becoming a validator, please [get in touch](mailto:partners@tempo.xyz) with the Tempo team. See [Initial registration](/guide/node/validator-config-v2#initial-registration) for technical details.

## Cryptographic key hierarchy

Expand All @@ -18,22 +18,6 @@ All validators have two kinds of keys:

The signing key is static. Pre-T2, it can only be rotated by removing and re-creating a validator on-chain with the Tempo team. Post-T2, [ValidatorConfig V2](/guide/node/validator-config-v2) enables self-service rotation via the `rotateValidator` precompile. The signing share is dynamic and is updated periodically on each DKG ceremony. Once updated, it will be saved to disk. Currently, the DKG ceremony is scheduled to run on-chain every ~3 hours.

## Generating a signing key

You can generate an ED25519 keypair using the following command:

```bash
tempo consensus generate-private-key --output <path>
```

Once the private key is generated, you can calculate/verify the public key by running:

```bash
tempo consensus calculate-public-key --private-key <path>
```

The public key should match the output of the `generate-private-key` command.

## Running the validator

The process for running a validator node is very similar to [running a full node](/guide/node/rpc).
Expand All @@ -45,12 +29,9 @@ Once you've downloaded the snapshot and have been whitelisted on-chain, you can
tempo node --datadir <datadir> \
--chain <mainnet|moderato> \
--consensus.signing-key <path> \
--consensus.fee-recipient <validator_wallet_address> \
--telemetry-url <TELEMETRY_URL>
```

If you are not prepared to accept fees, we recommend setting the `--consensus.fee-recipient` field to `0x0000000000000000000000000000000000000001` as that will funnel the funds to a non-user controllable wallet (there is no known private key for the address).

### Optional flags

| Flag | Description |
Expand Down
9 changes: 4 additions & 5 deletions vocs.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -660,14 +660,13 @@ export default defineConfig({
},
{
text: 'Running a validator',
link: '/guide/node/validator',
},
{
text: 'Operating your validator',
collapsed: true,
items: [
{
text: 'Overview',
link: '/guide/node/validator',
},
{
text: 'Operation',
link: '/guide/node/operate-validator',
},
{
Expand Down
Loading