Skip to content

Commit 68c0042

Browse files
y3v63ny3v63n
committed
docs: role-based operator documentation
Restructure the operator documentation around what you run (full node, solo sequencer, staking provider, prover), with a role-picker landing page, guided per-role setup paths, concept essentials, and a reference section. Adds interactive helpers (an operator config pane that fills commands from your values, an L1 publisher funding calculator, and a prover-rewards claim generator), corrects metric names, slashing thresholds, reward-distribution mechanics, and the L1 blob and trace requirements against the current protocol, hosts operator helper scripts in the docs, and describes V5 as the current protocol (checkpoint-aware healthcheck, no standalone archiver flag, aztec_ JSON-RPC namespace, tiered slashing).
1 parent 48f6b87 commit 68c0042

97 files changed

Lines changed: 8304 additions & 665 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

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

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
id: claiming-rewards
3+
title: Claiming rewards
4+
description: When rewards show up, how much you earn, and how to claim across many sequencers and rollups from the staking dashboard.
5+
displayed_sidebar: operatorsSidebar
6+
---
7+
8+
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).
9+
10+
## TL;DR
11+
12+
- Rewards accrue **on the Rollup contract** under your coinbase address. Nothing reaches your wallet until they are claimed.
13+
- You earn **350 AZTEC per checkpoint you propose** (70% of the 500 AZTEC checkpoint reward).
14+
- After a rollup upgrade, rewards earned before the upgrade stay on the old Rollup contract. The dashboard claims across both.
15+
- 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.
16+
- Slashing reduces your stake, not your accrued rewards.
17+
18+
## When rewards show up
19+
20+
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).
21+
22+
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.
23+
24+
## How much you earn
25+
26+
You earn **350 AZTEC** to your coinbase for each checkpoint you propose. This can change by governance proposal.
27+
28+
## Claiming from the staking dashboard
29+
30+
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.
31+
32+
### Self-stakers: claiming your own sequencer rewards
33+
34+
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.
35+
36+
![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)
37+
38+
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.
39+
40+
![Claim Self-Stake Rewards dialog, with the coinbase address entered and a claim available per rollup](/img/claim_self_stake_dialog.jpg)
41+
42+
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.
43+
44+
#### Scenario 1: coinbase is a separate address
45+
46+
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.
47+
48+
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.
49+
50+
#### Scenario 2: coinbase is the attester address
51+
52+
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.
53+
54+
Two consequences:
55+
56+
- 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).
57+
- 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.
58+
59+
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.
60+
61+
#### Tracking addresses for the Claimable Rewards total
62+
63+
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:
64+
65+
1. On [stake.aztec.network/my-position](https://stake.aztec.network/my-position), expand the **Claimable Rewards** card at the top of the page.
66+
2. Click **Manage Addresses**.
67+
68+
![Expanded Claimable Rewards card showing the Claim All Rewards and Manage Addresses buttons](/img/claim_claimable_rewards_card.png)
69+
70+
3. On the **Coinbase** tab, paste a coinbase address (in scenario 2, that is your attester address) and click **Add**. Repeat for each address.
71+
72+
![Manage Reward Addresses dialog open on the Coinbase Addresses tab, with the address input and Add button](/img/claim_manage_addresses.png)
73+
74+
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.
75+
76+
### Providers: claiming commission across delegations
77+
78+
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.
79+
80+
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.
81+
82+
![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)
83+
84+
This tab claims your **commission** on delegated stake. Rewards from any sequencers you self-stake are claimed on your position page, described above.
85+
86+
## Prover rewards
87+
88+
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).
89+
90+
## Can my rewards disappear after a slash?
91+
92+
Slashing reduces your **stake**, not your **pending rewards**. Rewards already accrued to your coinbase are unaffected by slashing events. You can still claim them.
93+
94+
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.
95+
96+
## See also
97+
98+
- [Detailed claim guide](/operate/operators/sequencer-management/claiming-rewards): `cast` recipes including keystore and hardware-wallet variants, and gas-limit troubleshooting
99+
- [Identity model](./identity-model): what the coinbase, publisher, and withdrawer addresses each do
100+
- [Slashing](./slashing): what happens to your stake (not your rewards) when offenses occur
101+
- [Claiming prover rewards](/operate/operators/prover/claiming-rewards): the separate per-epoch prover claim flow
102+
- [Operator tooling](/operate/operators/tooling): the staking dashboard and other tools operators rely on

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

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
id: hardware
3+
title: Hardware spec
4+
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.
5+
displayed_sidebar: operatorsSidebar
6+
---
7+
8+
A single-screen view of what each role needs.
9+
10+
## Sequencer and full node (single machine)
11+
12+
| Resource | Spec |
13+
|---|---|
14+
| CPU | 8 cores / 16 vCPU, **Skylake or newer** |
15+
| RAM | 8 GB |
16+
| Storage | 1 TB SSD (NVMe recommended) |
17+
| Network | 25 Mbps |
18+
19+
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).
20+
21+
### One node, many attesters: load stays about the same
22+
23+
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.
24+
25+
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.
26+
27+
### Disk and IOPS
28+
29+
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**.
30+
31+
You need more than 1 TB only if you co-host an L1 node on the same machine, covered next.
32+
33+
### Co-hosting an L1 node
34+
35+
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:
36+
37+
| Network | L1 node disk (execution + consensus + blobs, approximate) | Total with Aztec node |
38+
|---|---|---|
39+
| Testnet (Sepolia) | around 1.3 TB | ~2 TB |
40+
| Mainnet (Ethereum) | around 2.5 to 3.5 TB, depending on the client | ~4 TB |
41+
42+
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.
43+
44+
### Network
45+
46+
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.
47+
48+
## Staking provider
49+
50+
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.
51+
52+
What multiplies the spec is the number of **nodes**, not attesters:
53+
54+
- Each delegated stake position you operate is a separate attester identity, but they can share a node.
55+
- For high availability, run one publisher plus one or more redundant nodes with a coordinated shared keystore.
56+
- 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.
57+
58+
Plan for `(number of nodes) x per-node-spec`.
59+
60+
## Prover
61+
62+
The prover has a different architecture: one **prover node** plus one **broker** plus N **prover agents** (the workers that do the heavy proof generation).
63+
64+
| Component | Spec per instance |
65+
|---|---|
66+
| Prover node | 16 cores / 32 vCPU, 16 GB RAM, 1 TB NVMe, 25 Mbps |
67+
| Prover broker | 8 cores / 16 vCPU, 16 GB RAM, 10 GB SSD |
68+
| Prover agent (each) | 32 cores / 64 vCPU, 128 GB RAM, 10 GB SSD |
69+
70+
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`):
71+
72+
| Agents | Cores | RAM |
73+
|---|---|---|
74+
| 1 | 32 | 128 GB |
75+
| 2 | 64 | 256 GB |
76+
| 3 | 96 | 384 GB |
77+
| 4 | 128 | 512 GB |
78+
79+
### How many agents do you need
80+
81+
A full prover for the heaviest sustained workload runs on the order of 200 agents. Real network load is usually well below that.
82+
83+
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.
84+
85+
## See also
86+
87+
- [Prerequisites](/operate/operators/prerequisites): the full operator-prerequisites checklist (OS, Docker, port-forwarding)
88+
- [L1 RPC requirements](./l1-rpc): the execution, consensus, and debug endpoints a node needs
89+
- [Full node setup](/operate/operators/full-node/setup): concrete Docker Compose with these specs
90+
- [Prover overview](/operate/operators/prover/overview): the broker and agent architecture in detail
91+
- [Topology and infrastructure](/operate/operators/setup/high_availability_sequencers): HA patterns for providers

0 commit comments

Comments
 (0)