docs: document network identities and rotation by decofe · Pull Request #923 · tempoxyz/docs

decofe · 2026-09-28T16:15:58Z

Document Tempo's network identities and how node operators handle identity rotation.

Network Upgrades and Releases: add a Network identities section with Mainnet and Testnet tabs listing the full BLS network identity and starting epoch for each network. This keeps the current identities next to the release table that is updated with every release.
Troubleshooting and FAQ: add "My node fails to start: finalized tip certificate failed verification against the trusted network identity". It quotes the startup error that validators on v1.15.0+ log when their latest finalized certificate does not verify against the trusted identity (from the DKG actor's startup check), explains when this happens (a full DKG rotation while the node was offline, or a post-rotation snapshot with an older release), and lists the warnings follow/RPC nodes log instead, since the follow engine has no equivalent startup check. It then covers upgrading, the --consensus.network-identity / --consensus.network-identity-from-epoch override with per-network commands, and the panics you see if the override does not match the network's DKG outcome.
New page, Consensus, DKG, and network identity: explains threshold BLS signing, DKG dealers and players, the epoch E → E+2 timing, routine resharing versus full DKG identity rotation, how follow/RPC nodes and validators use the network identity to verify finalizations and snapshots, and the requirement to start new nodes on a release with the rotated-to identity. The page is added to the node sidebar and to the node overview cards.
Managing validator keys: add a short info box linking to the new page, since validators do not manage the network identity directly.
Shared identity values: src/snippets/network-identities.txt holds each network's identity and override command as named regions. The identity tabs and FAQ commands pull them in with Vocs [!include], so a rotation only needs one file edited. src/lib/network-identities.test.ts fails if an override command's identity or from-epoch differs from its identity region, if the "from epoch N" labels on the releases page drift, or if either page hard-codes an identity again.

Error and warning text matches tempoxyz/tempo v1.15.0 and main (crates/consensus/src/dkg/manager/actor/startup.rs, crates/consensus/src/epoch/scheme_provider.rs, crates/consensus/src/follow/driver/actor.rs, crates/consensus/src/finalized_header_stream/mod.rs). CLI arguments match crates/consensus/src/args.rs, and identities and epochs match crates/chainspec/src/network_identity.rs.

Validation: CI (checks, tests, anchors, build, generated-Markdown include audit, E2E) and the Vercel preview build pass.

Prompted by: @SuperFluffy

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

vercel · 2026-09-28T16:16:04Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
tempo-docs	Ready	Preview	Sep 30, 2026 4:35pm UTC

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

jenpaff · 2026-09-29T08:54:47Z


+<a id="override-network-identity" />
+
+## How do I override the network identity?


when would i want to do that? whats the issue/error?

jenpaff · 2026-09-29T08:55:20Z

+<Tabs>
+<Tab title="Mainnet">
+
+**Network identity, from epoch 0:**


I'd move this to the releases page which we keep up to date with releases

jenpaff · 2026-09-29T09:10:51Z

 | **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) |
 | **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)) |

+## DKG and network identity


I think this deserves its own section, its a bit confusing here because we're talking about validator keys and network identity isn't really something validators manage.

i think just add a new page where we explain consensus & dkg better . we can link to network identity here as an fyi

jenpaff · 2026-09-30T10:16:03Z

+
+Both identity override arguments are required together. Keep your other node configuration arguments when applying these overrides.
+
+::::code-group


this should go to the releases page instead

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

Adds a short network identity link below the tagline and a dedicated section above Security, with the full Mainnet and Moderato keys and their starting epochs. This makes the identities easy to find while keeping the introduction concise. Closes tempoxyz#7947; the override FAQ link depends on tempoxyz/docs#923. Validation: keys and epochs match the compiled constants; GitHub Markdown rendering and `git diff --check` pass. --------- Co-authored-by: Pep Schu <pep@tempo.xyz> Co-authored-by: Derek <256792747+decofe@users.noreply.github.com> Co-authored-by: Amp <amp@ampcode.com>

docs: show network identities first in node guide

dc1d7e7

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

decofe assigned SuperFluffy Sep 28, 2026

vercel Bot deployed to Preview September 28, 2026 16:19 View deployment

SuperFluffy and others added 4 commits September 28, 2026 16:22

docs: list mainnet identity before testnet

589e848

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

docs: explain snapshot trust and network identity overrides

390f5bf

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

docs: tab network identities with override commands

eb2dc0b

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

docs: clarify network identities apply to all node roles

53fced7

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

vercel Bot deployed to Preview September 28, 2026 16:33 View deployment

docs: move network identity overrides to FAQ

1a91bd8

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

decofe mentioned this pull request Sep 28, 2026

docs: highlight network identities in node setup tempoxyz/tempo#7947

Closed

vercel Bot deployed to Preview September 28, 2026 17:11 View deployment

docs: explain network identity rotation and trust anchors

a53a6fc

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

decofe changed the title ~~docs: show network identities first in node guide~~ docs: document network identities and rotation Sep 28, 2026

vercel Bot deployed to Preview September 28, 2026 18:22 View deployment

hamdiallam reviewed Sep 28, 2026

View reviewed changes

Comment thread src/pages/docs/guide/node/validator-troubleshooting.mdx Outdated

docs: use testnet naming in network identity guidance

b4a64df

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

vercel Bot deployed to Preview September 28, 2026 18:53 View deployment

jenpaff reviewed Sep 29, 2026

View reviewed changes

jenpaff mentioned this pull request Sep 29, 2026

docs: make network identities visible in README tempoxyz/tempo#7958

Merged

jenpaff reviewed Sep 29, 2026

View reviewed changes

Comment thread src/pages/docs/guide/node/index.mdx Outdated

jenpaff reviewed Sep 30, 2026

View reviewed changes

docs: move network identities to releases and add DKG page

b0d15a0

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

vercel Bot had a problem deploying to Preview September 30, 2026 15:39 Failure

docs: use generated anchors for network identity headings

d178dfe

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

vercel Bot deployed to Preview September 30, 2026 15:49 View deployment

docs: drop SEO title from consensus and DKG page

5340f8d

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

vercel Bot deployed to Preview September 30, 2026 15:55 View deployment

docs: move network identity override into startup failure FAQ

1d30e5c

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

vercel Bot deployed to Preview September 30, 2026 16:08 View deployment

docs: share network identities through a snippet

95f2cb4

Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com>

vercel Bot deployed to Preview September 30, 2026 16:35 View deployment

pepyakin approved these changes Sep 30, 2026

View reviewed changes

SuperFluffy merged commit 3d8dded into main Sep 30, 2026
14 checks passed

SuperFluffy deleted the centaur/document-network-identities-1790612087 branch September 30, 2026 16:55

Navigation Menu

docs: document network identities and rotation - #923

docs: document network identities and rotation#923
SuperFluffy merged 13 commits into
mainfrom
centaur/document-network-identities-1790612087

decofe commented Sep 28, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Sep 28, 2026 •

edited

Loading

Uh oh!

Uh oh!

jenpaff Sep 29, 2026

Uh oh!

jenpaff Sep 29, 2026

Uh oh!

jenpaff Sep 29, 2026 •

edited

Loading

Uh oh!

Uh oh!

jenpaff Sep 30, 2026

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants


		<a id="override-network-identity" />

		## How do I override the network identity?


		Both identity override arguments are required together. Keep your other node configuration arguments when applying these overrides.

		::::code-group

Conversation

decofe commented Sep 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel Bot commented Sep 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

jenpaff Sep 29, 2026

Choose a reason for hiding this comment

Uh oh!

jenpaff Sep 29, 2026

Choose a reason for hiding this comment

Uh oh!

jenpaff Sep 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jenpaff Sep 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

decofe commented Sep 28, 2026 •

edited

Loading

vercel Bot commented Sep 28, 2026 •

edited

Loading

jenpaff Sep 29, 2026 •

edited

Loading