Skip to content

Commit 3d8dded

Browse files
decofeSuperFluffy
andauthored
docs: document network identities and rotation (#923)
* docs: show network identities first in node guide Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com> * docs: list mainnet identity before testnet Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com> * docs: explain snapshot trust and network identity overrides Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com> * docs: tab network identities with override commands Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com> * docs: clarify network identities apply to all node roles Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com> * docs: move network identity overrides to FAQ Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com> * docs: explain network identity rotation and trust anchors Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com> * docs: use testnet naming in network identity guidance Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com> * docs: move network identities to releases and add DKG page Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com> * docs: use generated anchors for network identity headings Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com> * docs: drop SEO title from consensus and DKG page Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com> * docs: move network identity override into startup failure FAQ Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com> * docs: share network identities through a snippet Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com> --------- Co-authored-by: Richard Janis Goldschmidt <701177+SuperFluffy@users.noreply.github.com>
1 parent 85cf479 commit 3d8dded

8 files changed

Lines changed: 217 additions & 0 deletions

File tree

‎src/lib/network-identities.test.ts‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
import { readFileSync } from 'node:fs'
2+
import { describe, expect, it } from 'vitest'
3+
4+
const read = (path: string) => readFileSync(path, 'utf8')
5+
6+
const snippetPath = 'src/snippets/network-identities.txt'
7+
const networkUpgradesPath = 'src/pages/docs/guide/node/network-upgrades.mdx'
8+
const troubleshootingPath = 'src/pages/docs/guide/node/validator-troubleshooting.mdx'
9+
10+
const networks = [
11+
{ name: 'mainnet', tab: 'Mainnet' },
12+
{ name: 'testnet', tab: 'Testnet' },
13+
] as const
14+
15+
function region(source: string, name: string) {
16+
const match = source.match(
17+
new RegExp(`// \\[!region ${name}\\]\\n([\\s\\S]*?)\\n// \\[!endregion ${name}\\]`),
18+
)
19+
expect(match, `missing region ${name}`).toBeTruthy()
20+
return match?.[1] ?? ''
21+
}
22+
23+
describe('network identities', () => {
24+
const snippet = read(snippetPath)
25+
const networkUpgrades = read(networkUpgradesPath)
26+
const troubleshooting = read(troubleshootingPath)
27+
28+
for (const { name, tab } of networks) {
29+
it(`keeps the ${name} identity, override command, and page epoch in sync`, () => {
30+
const identity = region(snippet, `${name}-identity`)
31+
const override = region(snippet, `${name}-override`)
32+
33+
expect(identity).toMatch(/^0x[0-9a-f]{192}$/)
34+
expect(override).toContain(`--consensus.network-identity ${identity} \\`)
35+
36+
const epoch = override.match(/--consensus\.network-identity-from-epoch (\d+)$/)?.[1]
37+
expect(epoch, `missing ${name} from-epoch`).toBeTruthy()
38+
39+
const tabSource = networkUpgrades.match(
40+
new RegExp(`<Tab title="${tab}">([\\s\\S]*?)</Tab>`),
41+
)?.[1]
42+
expect(tabSource, `missing ${tab} tab`).toBeTruthy()
43+
expect(tabSource).toContain(`**Network identity, from epoch ${epoch}:**`)
44+
expect(tabSource).toContain(
45+
`// [!include ~/snippets/network-identities.txt:${name}-identity]`,
46+
)
47+
expect(troubleshooting).toContain(
48+
`// [!include ~/snippets/network-identities.txt:${name}-override]`,
49+
)
50+
})
51+
}
52+
53+
it('does not hard-code identities outside the shared snippet', () => {
54+
for (const source of [networkUpgrades, troubleshooting]) {
55+
expect(source).not.toMatch(/0x[0-9a-f]{192}/)
56+
}
57+
})
58+
})
Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: Consensus, DKG, and network identity
3+
description: Learn how Tempo validators share a threshold signing key through DKG, how nodes verify finalizations with the network identity, and what to do when the identity rotates.
4+
---
5+
6+
# Consensus, DKG, and network identity
7+
8+
Tempo nodes verify consensus finalizations against a single network-wide public key called the network identity. This page explains how the validator committee produces that key through distributed key generation (DKG), how follow/RPC nodes and validators use it, and what node operators do when it rotates.
9+
10+
For the consensus protocol itself, see [Consensus and finality using Simplex BFT](/docs/protocol/blockspace/consensus).
11+
12+
## Committee signing with threshold BLS
13+
14+
Tempo validators form a committee that runs Simplex BFT consensus. Instead of attaching one signature per validator, the committee signs notarizations and finalizations with a BLS12-381 threshold scheme:
15+
16+
- Each committee member holds a private **signing share** of the committee's threshold signing key.
17+
- A certificate is valid once enough committee members contribute partial signatures to reach the threshold.
18+
- Anyone can verify the resulting certificate with the committee's single public key, the **network identity**.
19+
20+
The signing share and network identity are separate from each validator's Ed25519 signing key, which identifies the validator in the consensus protocol. See [Managing validator keys](/docs/guide/node/validator-keys) for the keys validators manage directly.
21+
22+
## DKG ceremonies
23+
24+
The committee creates and updates signing shares through DKG ceremonies. In a DKG ceremony, current committee members act as **dealers** that distribute shares, and next-epoch committee members act as **players** that receive them. No single party ever holds the full private key.
25+
26+
Tempo runs a DKG ceremony every epoch (about 3 hours). Validator changes made on-chain in epoch `E` are picked up by the ceremony in epoch `E+1` and take effect in epoch `E+2`. See [Checking validator status](/docs/guide/node/validator-status) for how this affects onboarding and exit.
27+
28+
Tempo uses two kinds of ceremonies:
29+
30+
| Ceremony | Signing shares | Network identity |
31+
| --- | --- | --- |
32+
| **Resharing** (routine) | Redistributed to the next committee | Unchanged |
33+
| **Full DKG** (identity rotation) | Generated fresh | Replaced with a new identity |
34+
35+
Routine resharing lets the committee change membership without changing the key that nodes verify against. A full DKG ceremony creates a new threshold key and therefore a new network identity.
36+
37+
## How nodes use the network identity
38+
39+
Both follow/RPC nodes and validators use the network identity as a trust anchor. A node checks finalization certificates against it before trusting finalized blocks, including the consensus certificates that authenticate Tempo snapshots downloaded through [tempo.xyz](https://tempo.xyz).
40+
41+
Each `tempo` release includes the current [mainnet and testnet network identities](/docs/guide/node/network-upgrades#network-identities), along with the epoch each identity is valid from. Nodes use these built-in values by default.
42+
43+
## Network identity rotation
44+
45+
Tempo can rotate the network identity by scheduling a full DKG ceremony to strengthen network safety. When it does, Tempo publishes a new `tempo` release with the rotated-to identity built in and lists it on [Network Upgrades and Releases](/docs/guide/node/network-upgrades).
46+
47+
:::warning[Update the binary before starting a new node]
48+
After an identity rotation, start new nodes with a release that includes the new identity, including nodes that start from a new snapshot. A binary with an outdated identity may be unable to verify certificates signed under the new identity.
49+
:::
50+
51+
If a node fails to start or logs a network identity warning after a rotation, see [My node fails to start: finalized tip certificate failed verification against the trusted network identity](/docs/guide/node/validator-troubleshooting#my-node-fails-to-start-finalized-tip-certificate-failed-verification-against-the-trusted-network-identity).

‎src/pages/docs/guide/node/index.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,12 @@ Most teams should start with [running RPC and standby nodes](/docs/guide/node/rp
3333
to="/docs/guide/node/rpc"
3434
icon="lucide:server"
3535
/>
36+
<Card
37+
title="Consensus, DKG, and Network Identity"
38+
description="Understand how nodes verify finalizations and what to do when the network identity rotates."
39+
to="/docs/guide/node/consensus-and-dkg"
40+
icon="lucide:key-round"
41+
/>
3642
<Card
3743
title="Node Security"
3844
description="Harden node operations, network exposure, key handling, and runtime configuration."

‎src/pages/docs/guide/node/network-upgrades.mdx‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ title: Network Upgrades and Releases
33
description: Timeline and details for Tempo network upgrades and important releases for node operators.
44
---
55

6+
import { Tab, Tabs } from 'vocs'
67
import { Badge } from '../../../../components/Badge'
78

89
# Network Upgrades and Releases
@@ -11,6 +12,33 @@ Tempo uses scheduled network upgrades to introduce protocol changes. Each upgrad
1112

1213
For detailed release notes and binaries, see the [Changelog](/docs/changelog).
1314

15+
## Network identities
16+
17+
Follow/RPC nodes and validators verify consensus finalization certificates, including those that authenticate Tempo snapshots, against the current network identity. Each `tempo` release includes these identities as [built-in trust anchors](https://github.com/tempoxyz/tempo/blob/main/crates/chainspec/src/network_identity.rs). To learn how the identity is produced and rotated, see [Consensus, DKG, and network identity](/docs/guide/node/consensus-and-dkg).
18+
19+
<Tabs>
20+
<Tab title="Mainnet">
21+
22+
**Network identity, from epoch 0:**
23+
24+
```text
25+
// [!include ~/snippets/network-identities.txt:mainnet-identity]
26+
```
27+
28+
</Tab>
29+
<Tab title="Testnet">
30+
31+
**Network identity, from epoch 51:**
32+
33+
```text
34+
// [!include ~/snippets/network-identities.txt:testnet-identity]
35+
```
36+
37+
</Tab>
38+
</Tabs>
39+
40+
After an identity rotation, this section and the release table below list the new identity and the first release that includes it. Start new nodes with that release or later. If a node fails to start after a rotation, see [My node fails to start: finalized tip certificate failed verification against the trusted network identity](/docs/guide/node/validator-troubleshooting#my-node-fails-to-start-finalized-tip-certificate-failed-verification-against-the-trusted-network-identity).
41+
1442
## Node Operator Updates
1543

1644
| Release | Date | Network | Description | Priority |

‎src/pages/docs/guide/node/validator-keys.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,10 @@ Use different signing keys and operator keys for testnet and mainnet. A testnet
2222
| **Fee recipient** | Ethereum address (`0x…`) | Receives transaction fees from blocks your validator proposes. | **Low** — changing it only redirects future fee revenue, no security impact. | [Update fee recipient](/docs/guide/node/validator-lifecycle#update-the-fee-recipient) |
2323
| **Signing share** | BLS12-381 key share | A share of the committee's threshold signing key, used to sign block notarizations and finalizations. | **Managed automatically** — updated every DKG ceremony (~3 hours). Lost shares are recovered from the network on restart. | Automatic (see [recovery](#signing-share-recovery)) |
2424

25+
:::info[Network identity]
26+
Signing shares combine into the committee's threshold key, whose public key is the network identity. Validators do not manage the network identity directly. To learn how DKG ceremonies update shares and rotate the identity, see [Consensus, DKG, and network identity](/docs/guide/node/consensus-and-dkg).
27+
:::
28+
2529
## Generating a signing key
2630

2731
:::warning

‎src/pages/docs/guide/node/validator-troubleshooting.mdx‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,48 @@ To fix:
7575

7676
See [Time Synchronization](/docs/guide/node/system-requirements#time-synchronization) for full setup details.
7777

78+
## My node fails to start: finalized tip certificate failed verification against the trusted network identity
79+
80+
Starting with [v1.15.0](https://github.com/tempoxyz/tempo/releases/tag/v1.15.0), a validator verifies the finalization certificate of its latest finalized block before its consensus engine starts. If verification fails, the node exits with an error chain that includes `failed initializing dkg manager` and ends with:
81+
82+
```text
83+
finalized tip certificate at height `<HEIGHT>` in epoch `<EPOCH>` failed verification against the trusted network identity from epoch `<FROM_EPOCH>`; configure an updated network identity if a full DKG rotation occurred while the node was offline
84+
```
85+
86+
The node checks the certificate against the newest [network identity](/docs/guide/node/consensus-and-dkg) it trusts: the identity built into the binary or passed on the command line, or a newer identity from its own persisted DKG state. Verification fails when the certificate was signed under a network identity the node does not know yet, for example:
87+
88+
- A full DKG rotation happened while your node was offline, and your release predates the rotation.
89+
- You started from a snapshot taken after a rotation with a release that predates the rotation.
90+
91+
Follow/RPC nodes do not run this startup check. Instead, they log one of these warnings when their network identity is outdated:
92+
93+
```text
94+
Network identity differs from the onchain DKG outcome!!! Update the binary with the latest network identity
95+
Network identity derived from the trusted start block differs from the configured network identity!!! Update the binary with the latest network identity
96+
```
97+
98+
To fix either case, upgrade to a release that includes the current identity. [Network Upgrades and Releases](/docs/guide/node/network-upgrades#network-identities) lists the current identities and the releases that include them.
99+
100+
If you cannot upgrade immediately, override the built-in identity by adding both of these arguments to your existing `tempo node` command:
101+
102+
| Argument | Meaning |
103+
| --- | --- |
104+
| `--consensus.network-identity <KEY>` | The full, hex-encoded 96-byte BLS threshold public key to use instead of the built-in network identity. |
105+
| `--consensus.network-identity-from-epoch <EPOCH>` | The first epoch for which the supplied identity is valid. |
106+
107+
Use the identity and epoch listed in [Network identities](/docs/guide/node/network-upgrades#network-identities). Keep your other node arguments, including `--chain testnet` for testnet nodes.
108+
109+
::::code-group
110+
```bash [Mainnet]
111+
// [!include ~/snippets/network-identities.txt:mainnet-override]
112+
```
113+
```bash [Testnet]
114+
// [!include ~/snippets/network-identities.txt:testnet-override]
115+
```
116+
::::
117+
118+
If the supplied identity does not match the network's DKG outcome for that epoch, the node stops with `network identity mismatch in epoch` or `persisted DKG network identity differs from the configured identity`. Check the identity and epoch values against [Network identities](/docs/guide/node/network-upgrades#network-identities).
119+
78120
## I accidentally deleted my consensus data directory
79121

80122
Current validators require consensus finalization certificates to start. Contact the Tempo team to coordinate restoring a consistent snapshot; do not assume restarting with an empty consensus directory is sufficient. Once startup data is restored, [signing-share recovery](/docs/guide/node/validator-keys#signing-share-recovery) can reconstruct a missing share, or the node can obtain one in a future successful DKG ceremony.
Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
// Built-in Tempo network identities, shared by the node guide pages.
2+
// Update these values when a full DKG rotation ships in a new release.
3+
// src/lib/network-identities.test.ts checks that each identity and epoch
4+
// matches its override command and the epochs stated on the pages.
5+
6+
// [!region mainnet-identity]
7+
0xa217bb85001d4dcf8e5c50136f77af88cb2cab1857279b91c6240f41cca95c4f43f6dcab3e0dfb87dafb3ecbeb6251e90a5df2e6c47432482821cd8b84665ee4642589d2d9628a92b03e2bbfb00e006d038cd98def76d2a41b7c228c05f5a193
8+
// [!endregion mainnet-identity]
9+
10+
// [!region mainnet-override]
11+
tempo node \
12+
--consensus.network-identity 0xa217bb85001d4dcf8e5c50136f77af88cb2cab1857279b91c6240f41cca95c4f43f6dcab3e0dfb87dafb3ecbeb6251e90a5df2e6c47432482821cd8b84665ee4642589d2d9628a92b03e2bbfb00e006d038cd98def76d2a41b7c228c05f5a193 \
13+
--consensus.network-identity-from-epoch 0
14+
// [!endregion mainnet-override]
15+
16+
// [!region testnet-identity]
17+
0x84591ad702a9ee67c0c64add2ff166c19a4666a1dc636cc530a810052957d34c185bb1d2c7f5569983485a5af49baed70166ba17ae782bc8c75701099c70474798ccc181d03b0c12054f1d01c7817b27b425bae4bfcf936218c0d097cccf3242
18+
// [!endregion testnet-identity]
19+
20+
// [!region testnet-override]
21+
tempo node --chain testnet \
22+
--consensus.network-identity 0x84591ad702a9ee67c0c64add2ff166c19a4666a1dc636cc530a810052957d34c185bb1d2c7f5569983485a5af49baed70166ba17ae782bc8c75701099c70474798ccc181d03b0c12054f1d01c7817b27b425bae4bfcf936218c0d097cccf3242 \
23+
--consensus.network-identity-from-epoch 51
24+
// [!endregion testnet-override]

‎vocs.config.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1117,6 +1117,10 @@ export default defineConfig({
11171117
text: 'Running RPC and Standby Nodes',
11181118
link: '/docs/guide/node/rpc',
11191119
},
1120+
{
1121+
text: 'Consensus, DKG, and Network Identity',
1122+
link: '/docs/guide/node/consensus-and-dkg',
1123+
},
11201124
{
11211125
text: 'Running a validator',
11221126
items: [

0 commit comments

Comments
 (0)