docs(operators): role-based operator docs with guided setup (#24219)

## Summary

Restructures the operator docs (`docs/docs-operate/operators/`) into a
**role-based guided setup**: an operator picks what they want to run
(full node, solo sequencer, staking provider, or prover) and follows a
path sized to that role, instead of navigating a flat list of setup
pages.

**Rationale.** The current operator docs are hard to navigate: new
operators don't know where to start, and existing operators can't find
answers to recurring questions. The top-level "Build / Operate /
Participate" navigation is abstract and overlaps for anyone who doesn't
already know the network's vocabulary, and the operator landing page is
theory-heavy with no obvious "what do I do next."

This redesign is driven by two data sources:
- **Discord operator channels** (`#mn-sequencer-technical`,
`#new-sequencer-technical`, `#new-prover-technical`), analyzed for
recurring complaints as of 2026-05-15.
- **The Aztec operator feedback survey**, run 2026-05-13 to 2026-05-27.

It follows two principles: (1) the first page an operator sees should
answer *"what can I do here and where do I start,"* not *"what is a
sequencer"*; and (2) if a question has been asked dozens of times in
Discord, the answer should be one or two clicks from the landing page.

**What's actually new in these pages.** The content below didn't exist
in the operator docs before; each page was written from on-chain
verification and the operator-reported pain points:

- **Identity model** (new Essentials page) — the full address-to-role
table (attester, publisher, coinbase, fee recipient, withdrawer, plus
provider admin and rewards-recipient) with slashable/rotatable columns,
a "which address gets which reward" model, where each address lives in
the keystore, how to check each on-chain, and the four most common
confusions as an FAQ.

- **L1 RPC requirements** (new Essentials page) — the three endpoints a
node needs (`ETHEREUM_HOSTS`, `L1_CONSENSUS_HOST_URLS`,
`ETHEREUM_DEBUG_HOSTS`); the post-Fusaka blob-serving requirement with
concrete supernode/semi-supernode versions (Lighthouse v8.0.0+, Prysm
v7.10+ and the flags); the `debug_traceTransaction` history requirement
(~12h / ~3,600 blocks); measured RPC call volume (~170,000/day/node
floor); polling-interval tuning; and a common-errors table. None of this
was canonically documented before.

- **Hardware spec** (new Essentials page) — corrected canonical numbers
(8 core / 8 GB / 1 TB SSD, NVMe recommended, 50,000+ IOPS, 25 Mbps
floor), an explicit per-sequencer note (the spec is per attester and
committee overlap drives real load), co-hosted L1 disk math by network
(~2 TB testnet / ~4 TB mainnet), provider per-attester multiplication,
and prover broker/agent scaling (the 1→4 agent table and the
`aztec.proving_queue.size` metric).

- **Slashing** (new Essentials page) — the eight offenses with their
penalty parameters and which actually fire today, the flat 2,000-AZTEC
penalty and the V5 tiered-penalty forward note, the three thresholds
(200K / 190K / 100K) and the five-slashes-of-headroom math, the veto
council and how to request a veto, how to detect a slash, and the full
**recovery path after ejection** including the genesis-sequencer case
and the zombie initiate/finalize-unstake flow on the dashboard.

- **Claiming rewards** (new Essentials page) — reframed around the
staking dashboard as the primary path. Distinguishes self-staker
claiming (per-sequencer Claim on `/my-position`) from provider claiming
(Operator Commission tab on `/operator`), with the two coinbase
scenarios (separate address vs coinbase=attester) that explain why the
dashboard total can read zero, and the Manage-Addresses tracking-list
steps. Screenshots included.

- **Claiming prover rewards** (new Prover page) — the
previously-undocumented claim flow: how prover rewards accrue per epoch
to `PROVER_ID`, the `claimProverRewards(coinbase, [epochs])` call, the
fact that any wallet can submit it (the prover key never has to sign the
claim), the manual `cast` fallback, and the mainnet + testnet Rollup
addresses with the Registry as source of truth.

- **Reading your logs** (new Reference page) — a catalogue of the most
common log messages labeled **ignore / investigate / urgent**, covering
the keystore ZodError (staker-output file in the keystore dir), libp2p
churn, attestation timeouts, the archiver debug-trace warning, and the
prover payload-size error. Each entry verified against the v4.3.1
source.

- **Monitoring** (new Essentials page) — the handful of metrics that
actually matter (block height, publisher balance, peer count, mempool)
with concrete alert thresholds, why publisher-balance is the key
slashing proxy, the OTEL→Prometheus naming, and how to wire up a stack
or use the community dashboards.

- **Run a Node landing + Popular questions + Operator tooling index** —
the role-picker entry point, the recurring-question shortcuts, and a
curated index of Foundation vs community tools (clearly labeled as
third-party).

A set of loopholes is intentionally **staged, not yet in this PR**
(tracked for follow-up): jailed/genesis-sequencer recovery framing, a
"Sequencer troubleshooting" decision tree, "Managing delegations,"
"Where to stay informed," migration guides for HA topology changes, and
the per-version changelog template extensions (RPC schema / metric-name
/ env-var subsections).

## What's new

- **Navbar: "Operate" → "Run a Node"** — matches the CTA already used on
the homepage; URLs stay at `/operate/...` for backwards compatibility.
<img width="341" height="40" alt="navbar"
src="https://github.com/user-attachments/assets/dba52d25-89dd-43fb-8775-7fe636b182e7"
/>

- **Role-picker landing** at `/operate/operators`: four cards (full
node, solo sequencer, staking provider, prover), each with the role's
purpose, key requirements (stake, hardware, what you earn), what's
distinctive, and a CTA into the matching setup path. Operators decide
what they're setting up before touching any commands.
<img width="689" height="528" alt="role_picker_02"
src="https://github.com/user-attachments/assets/b2ac13ae-e712-4a38-a1b1-6facaeb09360"
/>
<img width="689" height="414" alt="role_picker_01"
src="https://github.com/user-attachments/assets/e5bd49bf-7362-48b4-9a2b-d145bb24e315"
/>

- **"Popular questions" section** below the role-picker: a flat list of
links to the pages that answer the recurring pain points (identity
model, L1 RPC requirements, hardware spec, …), so an operator with one
specific question doesn't have to walk the role tree.
<img width="693" height="346" alt="popular_questions"
src="https://github.com/user-attachments/assets/9872cdaa-6563-4562-9193-385b93372352"
/>

- **Setup paths sized per role.** Full node is a short reference
section. **Solo sequencer and staking provider share one guided
walkthrough** (they're ~80% the same setup) with a track-picker toggle
for the differences (stake source, key management, commission). **Prover
has its own walkthrough** (different architecture and reward model).
- **Essentials concept pages**: identity model, hardware spec, L1 RPC
requirements, slashing, monitoring, claiming rewards.
- **Prover**: overview, setup, verification, troubleshooting, and a new
**Claiming prover rewards** page.
- **Reference → Reading your logs**: a catalogue of common log messages
labeled **ignore / investigate / urgent**.
- **Sidebar restructure**: role tracks become the primary entry points;
the old per-page Setup entries (running-a-node, sequencer-setup,
registering-sequencer, running-a-prover, staking-provider) are reachable
through the tiles, and genuinely advanced topics (HA, bootnode,
building-from-source, syncing, blob storage/upload) move under
**Advanced operations**. Monitoring, Keystore management, Sequencer
management, FAQ, and Reference stay intact.
<img width="229" height="535" alt="sidebar"
src="https://github.com/user-attachments/assets/ff4d0cfd-9b88-4012-9048-ec66c0164a5c"
/>

## Notable changes

Three interactive helpers were added to remove the most error-prone
manual steps. All are client-side React components (no backend); they
read public on-chain data via the operator's own RPC and never handle
private keys.

- **Operator config pane (`OperatorConfig`)** — on the guided playbooks,
the operator pastes their values (network, RPC, addresses, sequencer
count) once via a track-picker, and every code block on the page fills
in with those values. Removes copy-paste-and-edit errors across a
multi-page walkthrough.
<img width="679" height="536" alt="config_pane"
src="https://github.com/user-attachments/assets/093013b5-d120-4d7e-accf-3e99bc727cf5"
/>

- **L1 gas / publisher-funding calculator** — addresses the recurring
"how much ETH does the publisher need" question. The operator pastes
their L1 RPC; the component scans the last 30 days of `propose()`
activity, derives the per-propose gas and the gas-price percentiles
actually paid (including the proposal blob fee), and converts a top-up
amount into a runway estimate at chosen and elevated gas prices. Falls
back to a measured baseline before a scan.
<img width="679" height="516" alt="gas_calculator"
src="https://github.com/user-attachments/assets/c4eafed0-6d10-46f5-ab3f-d89c0ffbbf5e"
/>

- **Prover-rewards claim command generator** — on the new "Claiming
prover rewards" page. The operator enters their RPC, Rollup address, and
`PROVER_ID`; the component runs read-only calls to find every recent
epoch with an unclaimed reward and assembles the exact
`claimProverRewards(coinbase, [epochs])` command with the epoch list
filled in. Solves the "which epochs do I claim, and how" problem that
previously forced provers into Etherscan.
<img width="679" height="201" alt="prover_rewards"
src="https://github.com/user-attachments/assets/f98fa911-85d2-4ca8-958f-2999c99a0d45"
/>

Supporting plumbing:
- New shared components under `src/components/` (`OperatorConfig`,
`RolePicker`, `PopularQuestions`), registered in
`src/theme/MDXComponents.js`.
- `--aztec-card-bg` added to `src/css/custom.css` (used by the role
cards).

## Verification

Builds clean against `next` with `onBrokenLinks: "throw"` (`yarn
preprocess && yarn docusaurus build` → `[SUCCESS] Generated static
files`).

Author: y3v63n

docs/docs-operate/operators/concepts/claiming-rewards.md

@@ -0,0 +1,102 @@
+---
+id: claiming-rewards
+title: Claiming rewards
+description: When rewards show up, how much you earn, and how to claim across many sequencers and rollups from the staking dashboard.
+displayed_sidebar: operatorsSidebar
+---
+
+This page explains when Aztec rewards become claimable and how to claim them. The [staking dashboard](https://stake.aztec.network) is the primary path: it finds your rewards across every rollup and bundles the claims into a single wallet flow, which is what makes claiming practical once you run more than one sequencer or operate at provider scale. The `cast` recipes for a single attester live in [Advanced operations](/operate/operators/sequencer-management/claiming-rewards).
+
+## TL;DR
+
+- Rewards accrue **on the Rollup contract** under your coinbase address. Nothing reaches your wallet until they are claimed.
+- You earn **350 AZTEC per checkpoint you propose** (70% of the 500 AZTEC checkpoint reward).
+- After a rollup upgrade, rewards earned before the upgrade stay on the old Rollup contract. The dashboard claims across both.
+- Claim from the [staking dashboard](https://stake.aztec.network): **self-stakers** use the per-sequencer Claim in the stake breakdown on the My position page; **providers** use the Operator Commission tab.
+- Slashing reduces your stake, not your accrued rewards.
+
+## When rewards show up
+
+Rewards are credited to your coinbase **after the epoch containing your proposed checkpoint has been proven**, not at proposal time. Proving happens within the proof submission window (typically a few epochs after the block).
+
+Practical timing: most rewards land within 1 to 2 hours of the corresponding block. During gas-spike periods or proving incidents, the lag can extend. If an epoch is pruned (provers missed the window), the rewards for that epoch do not credit at all.
+
+## How much you earn
+
+You earn **350 AZTEC** to your coinbase for each checkpoint you propose. This can change by governance proposal.
+
+## Claiming from the staking dashboard
+
+The dashboard reads pending rewards across every rollup the Registry has ever made canonical, so it surfaces rewards on both the current and previous Rollup contracts in one place, and routes the claim through a single transaction cart. Connect the wallet that holds your stake position: for a direct stake that is the **withdrawer** address, and for a stake from a token vault it is the vault **beneficiary** wallet. The dashboard then shows the path that applies to you.
+
+### Self-stakers: claiming your own sequencer rewards
+
+If you run your own sequencers (whether one or many), open your position on [stake.aztec.network/my-position](https://stake.aztec.network/my-position). The **Stake breakdown** section lists each sequencer you run, with a **Claim** button on each row.
+
+![Stake breakdown on the staking dashboard position page, listing each self-staked sequencer with a per-row Claim button](/img/claim_self_stake_breakdown.jpg)
+
+That per-sequencer Claim opens a dialog with a **Coinbase address** field: you enter the coinbase, and the dashboard finds the pending rewards for it across every rollup and adds one claim to the transaction cart per rollup.
+
+![Claim Self-Stake Rewards dialog, with the coinbase address entered and a claim available per rollup](/img/claim_self_stake_dialog.jpg)
+
+Which address you enter depends on how you configured your node. Rewards always accrue on the Rollup contract under the **coinbase address**, so the coinbase is what you claim against.
+
+#### Scenario 1: coinbase is a separate address
+
+If you set the coinbase to an address you control when you generated your keystore (`aztec validator-keys new --coinbase <address>`) or manually added a coinbase address to your keystore, rewards accrue to that address. In the per-sequencer Claim dialog, enter that **coinbase address**. The claimed AZTEC lands at the coinbase, which is already an address you hold the keys to.
+
+To make all sequencer rewards claimable in one pass, add your coinbase addresses to the dashboard's tracking list (see [Tracking addresses for the Claimable Rewards total](#tracking-addresses-for-the-claimable-rewards-total) below). The **Claimable Rewards** card at the top of the page then sums the pending rewards across the coinbases you have added and every rollup. When that total is above zero, expanding the card reveals **Claim All Rewards**, which batches the claims into a single flow rather than one Claim per sequencer.
+
+#### Scenario 2: coinbase is the attester address
+
+If you did not set a coinbase when you generated your keystore, the coinbase **defaults to the attester address**. Rewards accrue to the attester address itself.
+
+Two consequences:
+
+- In the per-sequencer Claim dialog, enter the **attester address** in the Coinbase address field (the dialog shows the attester address, so you can copy it from there).
+- The claimed AZTEC lands at the attester address. To move it afterward you need that address's key, which lives in your node's keystore.
+
+The **Claimable Rewards** card does not auto-detect self-stake rewards earned to a coinbase that equals the attester address. So when your coinbase is the attester, the card's **Self-Stake Rewards** line can read zero even while each sequencer has earned, until you add the attester address to the tracking list (see below). The per-sequencer Claim still works regardless.
+
+#### Tracking addresses for the Claimable Rewards total
+
+The **Claimable Rewards** card discovers your delegation rewards automatically, but for **self-stake** rewards it only counts the coinbase addresses you have told the dashboard to track. The tracking list is stored in your browser per connected wallet, so it does not carry across browsers or devices. To populate it:
+
+1. On [stake.aztec.network/my-position](https://stake.aztec.network/my-position), expand the **Claimable Rewards** card at the top of the page.
+2. Click **Manage Addresses**.
+
+   ![Expanded Claimable Rewards card showing the Claim All Rewards and Manage Addresses buttons](/img/claim_claimable_rewards_card.png)
+
+3. On the **Coinbase** tab, paste a coinbase address (in scenario 2, that is your attester address) and click **Add**. Repeat for each address.
+
+   ![Manage Reward Addresses dialog open on the Coinbase Addresses tab, with the address input and Add button](/img/claim_manage_addresses.png)
+
+The card then sums pending rewards across the addresses you added and every rollup. Removing an address only stops the dashboard tracking it; it does not affect your rewards or your ability to claim per sequencer.
+
+### Providers: claiming commission across delegations
+
+If you operate as a **staking provider**, rewards from your delegators' sequencers route into a **Splits contract** (one per delegation) that divides rewards between you and each delegator. Your **commission** routes to the `providerRewardsRecipient` address you set on the provider record; the remainder is claimable by each delegator.
+
+Open the **Operator Commission** tab at [stake.aztec.network/operator](https://stake.aztec.network/operator). The tab is visible when your connected wallet is the admin or rewards-recipient for at least one provider. It surfaces every split that pays you and bundles the full claim chain (claim the rollup rewards onto the split, distribute the split, withdraw your share) into the transaction cart, across all of your delegations and rollups at once.
+
+![Operator Commission tab on the staking dashboard, listing the splits that pay a provider with per-split pending commission and batch actions](/img/claim_operator_commission.jpg)
+
+This tab claims your **commission** on delegated stake. Rewards from any sequencers you self-stake are claimed on your position page, described above.
+
+## Prover rewards
+
+This page covers sequencer and provider rewards. Provers earn separately, per epoch, and claim with a different contract function. See [Claiming prover rewards](/operate/operators/prover/claiming-rewards).
+
+## Can my rewards disappear after a slash?
+
+Slashing reduces your **stake**, not your **pending rewards**. Rewards already accrued to your coinbase are unaffected by slashing events. You can still claim them.
+
+If you have been ejected (stake fell below the local 190,000 AZTEC threshold), you stop *earning new* rewards on subsequent epochs, but the rewards you have already accrued are still claimable.
+
+## See also
+
+- [Detailed claim guide](/operate/operators/sequencer-management/claiming-rewards): `cast` recipes including keystore and hardware-wallet variants, and gas-limit troubleshooting
+- [Identity model](./identity-model): what the coinbase, publisher, and withdrawer addresses each do
+- [Slashing](./slashing): what happens to your stake (not your rewards) when offenses occur
+- [Claiming prover rewards](/operate/operators/prover/claiming-rewards): the separate per-epoch prover claim flow
+- [Operator tooling](/operate/operators/tooling): the staking dashboard and other tools operators rely on

docs/docs-operate/operators/concepts/hardware.md

@@ -0,0 +1,91 @@
+---
+id: hardware
+title: Hardware spec
+description: What your machine actually needs to run an Aztec full node, sequencer, provider, or prover, including the CPU instruction-set floor and the extra disk for co-hosting an L1 node.
+displayed_sidebar: operatorsSidebar
+---
+
+A single-screen view of what each role needs.
+
+## Sequencer and full node (single machine)
+
+| Resource | Spec |
+|---|---|
+| CPU | 8 cores / 16 vCPU, **Skylake or newer** |
+| RAM | 8 GB |
+| Storage | 1 TB SSD (NVMe recommended) |
+| Network | 25 Mbps |
+
+These numbers are the same on testnet and mainnet: the node binary and its workload do not change with the network. What changes by network is the L1 node you connect to or co-host (see [Co-hosting an L1 node](#co-hosting-an-l1-node) below).
+
+### One node, many attesters: load stays about the same
+
+The spec above is for one node. Running more attester identities on the same node does **not** multiply the load. Stake scales in units of 200,000 AZTEC, and each unit is a separate attester identity, but the node's heavy work is validating each block proposal, which it does once per proposal regardless of how many of your attesters are on the committee. When several of your attesters are selected together, the node validates the proposal once and then just signs an attestation for each, which is cheap. So one node running 1 attester and one node running 100 attesters need roughly the same CPU and RAM.
+
+What does grow with the number of nodes (not attesters) is running more than one machine, for example for high availability. Size each node to the spec above.
+
+### Disk and IOPS
+
+1 TB is enough for the Aztec node itself. A normal SSD works; NVMe is recommended because random I/O performance matters as much as capacity, and cheap drives without consistent random-write performance can struggle under sustained load. SATA SSDs typically fall short. As a target, aim for **50,000+ random read/write IOPS**.
+
+You need more than 1 TB only if you co-host an L1 node on the same machine, covered next.
+
+### Co-hosting an L1 node
+
+If you run your own Ethereum execution and consensus clients on the **same machine** as the Aztec node (a common way to avoid hosted-RPC cost and rate limits), add the L1 node's disk on top of the Aztec node's 1 TB. The L1 footprint depends on the network:
+
+| Network | L1 node disk (execution + consensus + blobs, approximate) | Total with Aztec node |
+|---|---|---|
+| Testnet (Sepolia) | around 1.3 TB | ~2 TB |
+| Mainnet (Ethereum) | around 2.5 to 3.5 TB, depending on the client | ~4 TB |
+
+These L1 figures are external to Aztec and drift over time as the chains grow; check current Ethereum client guidance when you provision. If you point at a hosted or separate L1 endpoint instead, the Aztec node stays at 1 TB. See [L1 RPC requirements](./l1-rpc) for the endpoints a node needs.
+
+### Network
+
+25 Mbps is the floor. Sustained P2P load spikes above the average at epoch boundaries, so provision headroom; symmetric 100 Mbps is comfortable for production.
+
+## Staking provider
+
+Same per-node spec as the solo sequencer. As above, the number of delegated attester positions you run does not change the per-node load: 10, 100, or 1,000 attesters on one node is roughly the same work, because the node validates each proposal once and signs cheaply per attester.
+
+What multiplies the spec is the number of **nodes**, not attesters:
+
+- Each delegated stake position you operate is a separate attester identity, but they can share a node.
+- For high availability, run one publisher plus one or more redundant nodes with a coordinated shared keystore.
+- A provider running across 2 HA-paired nodes is operating roughly 2x the spec above because there are 2 machines, not because of the attester count.
+
+Plan for `(number of nodes) x per-node-spec`.
+
+## Prover
+
+The prover has a different architecture: one **prover node** plus one **broker** plus N **prover agents** (the workers that do the heavy proof generation).
+
+| Component | Spec per instance |
+|---|---|
+| Prover node | 16 cores / 32 vCPU, 16 GB RAM, 1 TB NVMe, 25 Mbps |
+| Prover broker | 8 cores / 16 vCPU, 16 GB RAM, 10 GB SSD |
+| Prover agent (each) | 32 cores / 64 vCPU, 128 GB RAM, 10 GB SSD |
+
+Agents carry the Skylake-or-newer CPU floor too, and lean on it hardest. They do the heavy lifting, and their hardware scales roughly linearly with how many you run (set with `PROVER_AGENT_COUNT`):
+
+| Agents | Cores | RAM |
+|---|---|---|
+| 1 | 32 | 128 GB |
+| 2 | 64 | 256 GB |
+| 3 | 96 | 384 GB |
+| 4 | 128 | 512 GB |
+
+### How many agents do you need
+
+A full prover for the heaviest sustained workload runs on the order of 200 agents. Real network load is usually well below that.
+
+If you are provisioning, start with one broker and 2 to 4 agents, then watch the proving queue depth and scale agents up if it grows. The broker exports the queue size as the `aztec.proving_queue.size` OpenTelemetry metric (number of jobs waiting); see the [Job Queue metrics](/operate/operators/monitoring/metrics-reference#job-queue) for the full set.
+
+## See also
+
+- [Prerequisites](/operate/operators/prerequisites): the full operator-prerequisites checklist (OS, Docker, port-forwarding)
+- [L1 RPC requirements](./l1-rpc): the execution, consensus, and debug endpoints a node needs
+- [Full node setup](/operate/operators/full-node/setup): concrete Docker Compose with these specs
+- [Prover overview](/operate/operators/prover/overview): the broker and agent architecture in detail
+- [Topology and infrastructure](/operate/operators/setup/high_availability_sequencers): HA patterns for providers