Skip to content

docs: expand initial registration section with all required values #209

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
decofe wants to merge 11 commits into
base: main
Choose a base branch
from
+58 −37
Open

docs: expand initial registration section with all required values #209

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
b899c30
docs: expand initial registration section with all required values
decofe Mar 30, 2026
20648b6
docs: move initial registration to 'Running a validator' page
decofe Mar 30, 2026
78d1ef5
docs: rename to 'Deploying a validator' and make it the first section
decofe Mar 31, 2026
8d95472
docs: move deploying a validator details into validator-config-v2
decofe Mar 31, 2026
3d90bd2
docs: simplify validator intro and flatten info block
decofe Mar 31, 2026
edb6ebe
docs: shorten deploying a validator link text
decofe Mar 31, 2026
a4932ce
docs: make Initial registration the first subsection under Operator g…
decofe Mar 31, 2026
47e8bf0
docs: move generating a signing key into validator-config-v2 under in…
decofe Mar 31, 2026
94226fd
docs: use zero address for fee burning
decofe Mar 31, 2026
21986fc
docs: link to generating a signing key from rotate section
decofe Mar 31, 2026
32d9388
docs: flatten validator sidebar into single 'Running a validator' group
decofe Mar 31, 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
60 changes: 49 additions & 11 deletions src/pages/guide/node/validator-config-v2.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,54 @@ 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`. |
Copy link
Copy Markdown
Member

@emmajam emmajam Apr 1, 2026

Choose a reason for hiding this comment

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

there are some changes to fee recipient no? arent we making it so a proper value is required ?

| **Signature** | `0x`-prefixed hex | An ed25519 signature proving you control the signing key. See below. |

#### Generating a signing key

Generate an ed25519 keypair:

```bash
tempo consensus generate-private-key --output <path>
Copy link
Copy Markdown
Member

@emmajam emmajam Apr 1, 2026

Choose a reason for hiding this comment

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

can we add a note to say 'never ever share your private key with anyone'

```

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

@kuyziss kuyziss Mar 31, 2026

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 IP addresses

If your node's network endpoints change, update them on-chain. The change takes effect at the next finalized block.
Expand All @@ -136,7 +184,7 @@ 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:

Expand Down Expand Up @@ -164,16 +212,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
26 changes: 5 additions & 21 deletions src/pages/guide/node/validator.mdx
View file
Open in desktop
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 @@ -49,7 +33,7 @@ tempo node --datadir <datadir> \
--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).
If you are not prepared to accept fees, we recommend setting the `--consensus.fee-recipient` field to `0x0000000000000000000000000000000000000000` as that will funnel the funds to a non-user controllable wallet (there is no known private key for the address).
Copy link
Copy Markdown
Contributor

@kuyziss kuyziss Mar 31, 2026

Choose a reason for hiding this comment

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

aren't we deprecating this field? as it was moved to contract


### Optional flags

Expand Down
9 changes: 4 additions & 5 deletions vocs.config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -664,14 +664,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