From 13a6d0daeab790c2e1939a588f0322e21bc7d3d7 Mon Sep 17 00:00:00 2001 From: Esau Date: Fri, 2 Jan 2026 21:52:59 +0800 Subject: [PATCH] init --- .../concepts/architecture/block-production.md | 50 ++++ .../concepts/architecture/index.md | 29 ++ .../proving-coordination.md} | 15 +- .../contracts/deployment-architecture.md | 68 +++++ .../concepts/deployments/_category_.json | 6 - .../deployments/what_is_deployment.md | 247 ------------------ .../concepts/governance/governance.md | 18 -- docs/docs-network/concepts/governance/gse.md | 229 ++++++++++++++++ .../docs-network/concepts/governance/index.md | 112 ++++++++ .../concepts/governance/proposal-lifecycle.md | 221 ++++++++++++++++ .../governance/putting_forward_proposals.md | 18 -- .../concepts/governance/upgrades.md | 71 +++-- .../concepts/governance/voting.md | 217 ++++++++++++++- docs/docs-network/concepts/index.md | 44 ++++ .../concepts/proof-of-stake/index.md | 112 ++++++++ .../concepts/proof_of_stake/_category_.json | 6 - .../concepts/proof_of_stake/index.md | 8 - .../concepts/proof_of_stake/slashing.md | 53 ---- .../provers-and-sequencers/_category_.json | 7 - .../concepts/provers-and-sequencers/index.md | 16 -- .../provers-and-sequencers/sequencer/index.md | 46 ---- .../sequencer/sequencer_selection.md | 103 -------- docs/docs-network/index.md | 114 +++----- docs/docs-network/operation/_category_.json | 6 - .../sequencer_management/_category_.json | 6 - docs/docs-network/operators/index.md | 55 ++++ .../keystore/advanced-patterns.md} | 10 +- .../keystore/creating-keystores.md} | 16 +- .../keystore/examples.md | 4 +- .../keystore/index.md | 12 +- .../keystore/storage-methods.md} | 2 +- .../keystore/troubleshooting.md | 14 +- .../monitoring/grafana-setup.md} | 4 +- .../monitoring/index.md} | 18 +- .../monitoring/metrics-reference.md} | 8 +- .../monitoring/otel-setup.md} | 4 +- .../monitoring/prometheus-setup.md} | 6 +- .../monitoring/troubleshooting.md} | 2 +- .../operator-faq.md} | 12 +- .../{ => operators}/prerequisites.md | 9 +- .../reference/changelog/index.md | 8 +- .../reference/changelog/v2.0.2.md | 10 +- .../reference/cli-reference.md} | 2 +- .../reference/ethereum-rpc-reference.md} | 10 +- .../{ => operators}/reference/glossary.md | 10 +- .../reference/node-api-reference.md} | 8 +- .../sequencer-management/claiming-rewards.md} | 14 +- .../governance-participation.md} | 20 +- .../sequencer-management}/index.md | 26 +- .../slashing-configuration.md} | 8 +- .../sequencer-management/useful-commands.md} | 10 +- .../setup/bootnode-operation.md} | 2 +- .../setup/building-from-source.md} | 12 +- .../setup/high-availability.md} | 16 +- .../setup/registering-sequencer.md} | 10 +- .../setup/running-a-node.md} | 10 +- .../setup/running-a-prover.md} | 8 +- .../setup/sequencer-setup.md} | 22 +- .../setup/staking-provider.md} | 8 +- .../setup/syncing-best-practices.md} | 8 +- docs/docs-network/setup/_category_.json | 6 - docs/docs-network/users/delegation.md | 81 ++++++ docs/docs-network/users/index.md | 36 +++ docs/docs-network/users/staking.md | 63 +++++ docs/docs-network/users/voting.md | 126 +++++++++ docs/docs-words.txt | 4 + docs/docusaurus.config.js | 8 +- docs/sidebars-network.js | 244 +++++++++++------ docs/src/css/custom.css | 67 +++++ 69 files changed, 1943 insertions(+), 912 deletions(-) create mode 100644 docs/docs-network/concepts/architecture/block-production.md create mode 100644 docs/docs-network/concepts/architecture/index.md rename docs/docs-network/concepts/{provers-and-sequencers/proving_coordination_workflow.md => architecture/proving-coordination.md} (92%) create mode 100644 docs/docs-network/concepts/contracts/deployment-architecture.md delete mode 100644 docs/docs-network/concepts/deployments/_category_.json delete mode 100644 docs/docs-network/concepts/deployments/what_is_deployment.md delete mode 100644 docs/docs-network/concepts/governance/governance.md create mode 100644 docs/docs-network/concepts/governance/gse.md create mode 100644 docs/docs-network/concepts/governance/index.md create mode 100644 docs/docs-network/concepts/governance/proposal-lifecycle.md delete mode 100644 docs/docs-network/concepts/governance/putting_forward_proposals.md create mode 100644 docs/docs-network/concepts/index.md create mode 100644 docs/docs-network/concepts/proof-of-stake/index.md delete mode 100644 docs/docs-network/concepts/proof_of_stake/_category_.json delete mode 100644 docs/docs-network/concepts/proof_of_stake/index.md delete mode 100644 docs/docs-network/concepts/proof_of_stake/slashing.md delete mode 100644 docs/docs-network/concepts/provers-and-sequencers/_category_.json delete mode 100644 docs/docs-network/concepts/provers-and-sequencers/index.md delete mode 100644 docs/docs-network/concepts/provers-and-sequencers/sequencer/index.md delete mode 100644 docs/docs-network/concepts/provers-and-sequencers/sequencer/sequencer_selection.md delete mode 100644 docs/docs-network/operation/_category_.json delete mode 100644 docs/docs-network/operation/sequencer_management/_category_.json create mode 100644 docs/docs-network/operators/index.md rename docs/docs-network/{operation/keystore/advanced_patterns.md => operators/keystore/advanced-patterns.md} (94%) rename docs/docs-network/{operation/keystore/creating_keystores.md => operators/keystore/creating-keystores.md} (95%) rename docs/docs-network/{operation => operators}/keystore/examples.md (98%) rename docs/docs-network/{operation => operators}/keystore/index.md (89%) rename docs/docs-network/{operation/keystore/storage_methods.md => operators/keystore/storage-methods.md} (99%) rename docs/docs-network/{operation => operators}/keystore/troubleshooting.md (95%) rename docs/docs-network/{operation/grafana_setup.md => operators/monitoring/grafana-setup.md} (97%) rename docs/docs-network/{operation/monitoring.md => operators/monitoring/index.md} (78%) rename docs/docs-network/{operation/metrics_reference.md => operators/monitoring/metrics-reference.md} (98%) rename docs/docs-network/{operation/otel_setup.md => operators/monitoring/otel-setup.md} (96%) rename docs/docs-network/{operation/prometheus_setup.md => operators/monitoring/prometheus-setup.md} (92%) rename docs/docs-network/{operation/monitoring_example_troubleshooting.md => operators/monitoring/troubleshooting.md} (99%) rename docs/docs-network/{operation/operator_faq.md => operators/operator-faq.md} (96%) rename docs/docs-network/{ => operators}/prerequisites.md (94%) rename docs/docs-network/{ => operators}/reference/changelog/index.md (85%) rename docs/docs-network/{ => operators}/reference/changelog/v2.0.2.md (97%) rename docs/docs-network/{reference/cli_reference.md => operators/reference/cli-reference.md} (99%) rename docs/docs-network/{reference/ethereum_rpc_reference.md => operators/reference/ethereum-rpc-reference.md} (95%) rename docs/docs-network/{ => operators}/reference/glossary.md (96%) rename docs/docs-network/{reference/node_api_reference.md => operators/reference/node-api-reference.md} (99%) rename docs/docs-network/{operation/sequencer_management/claiming_rewards.md => operators/sequencer-management/claiming-rewards.md} (95%) rename docs/docs-network/{operation/sequencer_management/creating_and_voting_on_proposals.md => operators/sequencer-management/governance-participation.md} (93%) rename docs/docs-network/{operation/sequencer_management => operators/sequencer-management}/index.md (81%) rename docs/docs-network/{operation/sequencer_management/slashing_and_offenses.md => operators/sequencer-management/slashing-configuration.md} (98%) rename docs/docs-network/{operation/sequencer_management/useful_commands.md => operators/sequencer-management/useful-commands.md} (96%) rename docs/docs-network/{setup/bootnode_operation.md => operators/setup/bootnode-operation.md} (99%) rename docs/docs-network/{setup/building_from_source.md => operators/setup/building-from-source.md} (97%) rename docs/docs-network/{setup/high_availability_sequencers.md => operators/setup/high-availability.md} (94%) rename docs/docs-network/{operation/sequencer_management/registering_sequencer.md => operators/setup/registering-sequencer.md} (93%) rename docs/docs-network/{setup/running_a_node.md => operators/setup/running-a-node.md} (95%) rename docs/docs-network/{setup/running_a_prover.md => operators/setup/running-a-prover.md} (97%) rename docs/docs-network/{setup/sequencer_management.md => operators/setup/sequencer-setup.md} (95%) rename docs/docs-network/{operation/sequencer_management/running_delegated_stake.md => operators/setup/staking-provider.md} (99%) rename docs/docs-network/{setup/syncing_best_practices.md => operators/setup/syncing-best-practices.md} (97%) delete mode 100644 docs/docs-network/setup/_category_.json create mode 100644 docs/docs-network/users/delegation.md create mode 100644 docs/docs-network/users/index.md create mode 100644 docs/docs-network/users/staking.md create mode 100644 docs/docs-network/users/voting.md diff --git a/docs/docs-network/concepts/architecture/block-production.md b/docs/docs-network/concepts/architecture/block-production.md new file mode 100644 index 000000000000..86d8449e033b --- /dev/null +++ b/docs/docs-network/concepts/architecture/block-production.md @@ -0,0 +1,50 @@ +--- +title: Block Production +description: Learn about how blocks are produced on the Aztec network through sequencers and provers. +displayed_sidebar: conceptsSidebar +--- + +# Block Production + +Both sequencing and proving in the Aztec Network are intended to be fully decentralized. + +## Overview + +Block production in Aztec involves two key roles: + +- **Sequencers**: Order transactions and produce blocks +- **Provers**: Generate cryptographic proofs for blocks + +Sequencers are chosen via a random election using a verifiable random function (VRF), while provers are selected by sequencers via an out-of-protocol coordination mechanism. + +## How It Works + +### Block Proposal + +1. A sequencer is selected for each slot using a VRF-based random selection +2. The selected sequencer collects transactions from the mempool +3. The sequencer orders transactions and proposes a block + +### Attestation + +1. Committee members receive the proposed block +2. Each committee member re-executes the transactions +3. If valid, committee members sign attestations +4. The proposer collects attestations (needs 2/3 + 1) + +### Proof Generation + +The proposers in the first `C=13` slots in epoch `N+1` will accept quotes to prove epoch N from provers. The winning prover will have until the end of epoch `N+1` to produce and submit the proof to L1. + +See [Proving Coordination](./proving-coordination) for details on how provers coordinate. + +## Related Topics + +- [Proving Coordination](./proving-coordination) - How provers are selected and coordinated + +--- + +:::tip Ready to operate? +- [Run a sequencer](../../operators/setup/sequencer_management) +- [Run a prover](../../operators/setup/running_a_prover) +::: diff --git a/docs/docs-network/concepts/architecture/index.md b/docs/docs-network/concepts/architecture/index.md new file mode 100644 index 000000000000..bcc799d166e9 --- /dev/null +++ b/docs/docs-network/concepts/architecture/index.md @@ -0,0 +1,29 @@ +--- +title: Network Architecture +description: Understand how the Aztec network architecture works - block production, sequencer selection, and proving. +displayed_sidebar: conceptsSidebar +--- + +# Network Architecture + +The Aztec network operates through coordinated interaction between different node types. Together, they process transactions, produce blocks, and generate proofs. + +## How Nodes Work Together + +1. **Transaction Flow**: Users submit transactions to full nodes, which validate and propagate them through the P2P network +2. **Block Production**: Sequencer nodes collect transactions from the mempool, order them, and propose new blocks +3. **Consensus**: The sequencer committee validates proposed blocks and provides attestations +4. **Proof Generation**: Prover nodes generate cryptographic proofs for epochs of blocks +5. **L1 Submission**: Sequencers submit attested blocks and provers submit epoch proofs to Ethereum + +## Topics + +- [Block Production](architecture/block-production) - How sequencers and provers work together to produce and finalize blocks +- [Proving Coordination](architecture/proving-coordination) - How provers coordinate to generate epoch proofs + +--- + +:::tip Ready to operate? +- [Run a sequencer](../operators/setup/sequencer_management) +- [Run a prover](../operators/setup/running_a_prover) +::: diff --git a/docs/docs-network/concepts/provers-and-sequencers/proving_coordination_workflow.md b/docs/docs-network/concepts/architecture/proving-coordination.md similarity index 92% rename from docs/docs-network/concepts/provers-and-sequencers/proving_coordination_workflow.md rename to docs/docs-network/concepts/architecture/proving-coordination.md index 2e03205b8230..b425799a83fb 100644 --- a/docs/docs-network/concepts/provers-and-sequencers/proving_coordination_workflow.md +++ b/docs/docs-network/concepts/architecture/proving-coordination.md @@ -1,10 +1,15 @@ --- -sidebar_position: 1 -title: Prover Coordination Workflow +title: Proving Coordination description: Learn about the proving coordination workflow on the Aztec network. -draft: true +displayed_sidebar: conceptsSidebar --- +# Proving Coordination + +Provers in the Aztec network coordinate with proposers through a request-for-quote (RFQ) process. This page explains how provers submit quotes and get selected to prove epochs. + +## Overview + Proposers run RFQs to obtain quotes from provers. Quotes are binding promises from provers to prove an entire epoch. The exact channel over which provers send quotes to proposers is **NOT** enshrined by the protocol. However, Aztec Nodes will support two optional mechanisms that provers can use to submit quotes to proposers: @@ -102,6 +107,6 @@ interface L1Publisher { The Prover Node will call this method at least once per L2 slot to check for unclaimed accepted quotes if its quotes have been accepted. You can update the polling interval using the environment variable `PROVER_NODE_POLLING_INTERVAL_MS`. -## Run a prover +## Run a Prover -Go to the [Prover Guide](../../setup/running_a_prover.md) to run a prover. +Go to the [Prover Guide](../../operators/setup/running_a_prover) to run a prover. diff --git a/docs/docs-network/concepts/contracts/deployment-architecture.md b/docs/docs-network/concepts/contracts/deployment-architecture.md new file mode 100644 index 000000000000..b99c22f7e9db --- /dev/null +++ b/docs/docs-network/concepts/contracts/deployment-architecture.md @@ -0,0 +1,68 @@ +--- +title: L1 Contracts +description: Overview of the L1 smart contracts that power Aztec network governance. +displayed_sidebar: conceptsSidebar +--- + +# L1 Contracts + +:::warning Work in Progress +This page provides a high-level overview of Aztec's governance contracts. The contract interfaces and implementations are still evolving. For the authoritative source, see the [l1-contracts repository](https://github.com/AztecProtocol/aztec-packages/tree/master/l1-contracts/src/governance). +::: + +## Contract Overview + +The Aztec governance system consists of several L1 smart contracts: + +| Contract | Purpose | +|----------|---------| +| **Registry** | Tracks all rollup instances; determines which is canonical | +| **Governance** | Handles proposal voting and execution | +| **GovernanceProposer** | Manages sequencer signaling and proposal submission | +| **GSE** | Governance Staking Escrow - manages validator stakes and voting power | +| **Rollup** | The rollup contract itself; validators stake here | + +## Registry + +The [Registry](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/governance/Registry.sol) maintains an append-only list of rollup instances. Only the Governance contract (as owner) can add new rollups. + +Key properties: +- **Backwards compatible**: All historical rollups remain accessible +- **Canonical selection**: Only the latest rollup receives block rewards +- **Immutable entries**: Once added, rollup addresses cannot be removed + +## Governance + +The [Governance](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/governance/Governance.sol) contract is the decision-making body that executes approved proposals. + +Key functions: +- `deposit()` / `initiateWithdraw()` - Manage voting power +- `vote()` - Cast votes on proposals +- `execute()` - Execute approved proposals + +See [Proposal Lifecycle](../governance/proposal-lifecycle) for how proposals move through the system. + +## GovernanceProposer + +The [GovernanceProposer](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/governance/proposer/GovernanceProposer.sol) handles the signaling phase where sequencers vote to promote payloads to proposals. + +Key functions: +- `signal()` - Sequencers signal support for a payload during their slot +- `submitRoundWinner()` - Submit a payload that reached quorum as a proposal + +## GSE (Governance Staking Escrow) + +The [GSE](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/governance/GSE.sol) holds validator stakes and manages voting power delegation. + +Key features: +- **Stake mobility**: Stakes can automatically follow rollup upgrades +- **Voting delegation**: Validators can delegate voting power +- **Escape hatch**: `proposeWithLock()` for emergency proposals + +See [GSE and Stake Mobility](../governance/gse) for details. + +## Related Topics + +- [Governance Overview](../governance/) - How the governance system works +- [Proposal Lifecycle](../governance/proposal-lifecycle) - Stages from signaling to execution +- [Network Upgrades](../governance/upgrades) - How upgrades use these contracts diff --git a/docs/docs-network/concepts/deployments/_category_.json b/docs/docs-network/concepts/deployments/_category_.json deleted file mode 100644 index 03142f5a9e87..000000000000 --- a/docs/docs-network/concepts/deployments/_category_.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "position": 2, - "collapsible": true, - "collapsed": true, - "label": "Deployments" -} diff --git a/docs/docs-network/concepts/deployments/what_is_deployment.md b/docs/docs-network/concepts/deployments/what_is_deployment.md deleted file mode 100644 index 75003e1e66e4..000000000000 --- a/docs/docs-network/concepts/deployments/what_is_deployment.md +++ /dev/null @@ -1,247 +0,0 @@ ---- -sidebar_position: 0 -title: What is a Deployment? -description: Learn about the constituent components of a network deployment and the deployment process on the Aztec network. ---- - -An Aztec deployment is a set of the following contracts: - -| Smart Contract | Immutability | -| ---------------------------- | ------------ | -| Hypothetical Asset | Immutable | -| Issuer Contract | Immutable | -| Registry Contract | Immutable | -| Reward Distribution Contract | Mutable | -| Proposals Contract | Mutable | -| Governance Contract | Immutable | -| Rollup Contract | Immutable | - -## Hypothetical Asset Contract - -Hypothetical Asset would live on Ethereum L1. It may have a minter which would be the only actor capable of calling the `mint` function on the Hypothetical Asset contract. - -This is brought up to the community for discussion purposes only to illustrate how proposed governance mechanisms could work with a Hypothetical Asset. - -- **Sequencers** must stake the Hypothetical Asset within the instance's contract to join that instance's sequencer set. -- **Holders** must lock Hypothetical Asset with the Governance contract to be able to vote on proposals. -- **Provers** must deposit Hypothetical Asset in the escrow contract in order to bid for the right to create a proof for an epoch. - -## Issuer Contract - -This contract will be the sole minter of Hypothetical Asset. It will itself have an owner, which is the only actor capable of calling the `mint` function on the Hypothetical Asset ERC20 contract. - -The `mint` function will limit the amount of Hypothetical Assets that could be minted in a given time period. The reasoning behind this limit is that it makes supply expansions more predictable since "infinite mints" cannot be made. - -```mermaid -flowchart LR - Issuer -->|Calls mint| HypotheticalAsset -``` - -```solidity -contract Issuer is Ownable { - ERC20 immutable public ASSET; // Hypothetical Asset - uint256 immutable public RATE; - uint256 public timeOfLastMint; - - constructor(ERC20 _asset, uint256 _rate, address _owner) Ownable(_owner) { - ASSET = _asset; - RATE = _rate; - timeOfLastMint = block.timestamp; - } - - function mint(address _to, uint256 _amount) external onlyOwner { - uint256 maxMint = RATE * (block.timestamp - timeOfLastMint); - require(_amount <= maxMint, 'Insufficient mint available'); - - timeOfLastMint = block.timestamp; - ASSET.mint(_to, _amount); - } -} -``` - -## Registry Contract - -The governance of Aztec will be community driven - the Aztec community will be able to decide whether to upgrade or migrate to a new rollup instance. Portals / apps donʼt need to follow along with the Aztec governance and can specify the specific instance (i.e. “versionˮ) of the rollup that they view as canonical. - -Therefore it will be necessary to keep track onchain of what versions of the rollup have existed as well as what version the Aztec governance views as the current canonical rollup. Only the current canonical rollup from the perspective of Aztec governance will be eligible to claim any further Hypothetical Asset rewards. - -```mermaid -flowchart LR - Registry --> RollupContract0["Rollup Contract
Instance 0"] - Registry --> RollupContract1["Rollup Contract
Instance 1"] - Registry --> |Returns latest instance|RollupContractN["Rollup Contract
Instance n"] -``` - -In practice, the Registry is an array of rollup instances that can only be inserted into by the Registryʼs owner - the Governance contract. - -```solidity -contract Registry is IRegistry, Ownable { - struct Instance { - address rollup; - uint96 blockNumber; - } - - Instance[] public instances; - - constructor(address _gov) Ownable(_gov) { - instances.push( - Instance({address: address(0), blockNumber: block.number}) - ); - } - - function addInstance(address _rollup) external onlyOwner { - instances.push( - Instance({address: _rollup, blockNumber: block.number}) - ); - } - - function getRollup() external view returns (address) { - return instances[instances.length - 1].rollup; - } - - function getInstancesLength() external view returns (uint256) { - return instances.length; - } -} -``` - -## Reward Distribution Contract - -This contract distributes ERC20 rewards only to the instance the Registry contract says is canonical. This is separated from the Registry and the Issuer so that the distribution logic can be changed without replacing the Registry. - -In practice, the following flow is expected. Infrequently, the Aztec Governance votes for the Issuer smart contract to mint a quantity of Hypothetical Asset and send them to the Distribution contract. The rollup contract will call `claim(_to)` on the Distribution contract. This checks that the calling Rollup is the current canonical Rollup before releasing a Hypothetical Asset to the rollup. - -The Rollup smart contract implements custom logic for how to split `BLOCK_REWARDS` amongst the proposers/committee/provers who provide real work in the form of electricity and hardware intensive computational resources to the Rollup smart contract. - -```mermaid -flowchart TD - Issuer -->|1. Calls mint| HypotheticalAsset - Issuer -->|2. Transfer Hypothetical Asset| RewardDistribution - RollupContract -->|3. Calls claim| RewardDistribution -``` - -```solidity -contract RewardDistribution is Ownable { - uint256 public constant BLOCK_REWARD = xxx; - - IERC20 public immutable ASSET; - IRegistry public registry; - - // constructor etc - - function claim(address _to) external returns (uint256) { - address canonical = registry.getRollup(); - require(msg.sender == canonical); - ASSET.safeTransfer(_to, BLOCK_REWARD); - return BLOCK_REWARD; - } - - function updateRegistry(IRegistry _registry) external onlyOwner { - // ... - } -} -``` - -Rollup contacts implementations should not revert if the `claim()` call reverts because the rollup is no longer canonical. Otherwise, no one could sequence the rollup anymore. - -The separation of Distribution and Issuer is primarily for code hygiene purposes. - -The protocol inflation rate is defined in the Issuer smart contract as the constant `RATE`. It is not possible to change this inflation rate once the Issuer smart contract has been deployed. Aztec Governance can vote on a proposal to deploy a new Issuer smart contract that contains a new `RATE` - -The Aztec Governance will choose how often to call `mint()` on the Issuer smart contract which will send any Hypothetical Assets to the Distribution smart contract. The Distribution smart contract defines a `BLOCK_REWARD` constant value (again cannot be changed). Every epoch, the Rollup contract can call the Distribution smart contract to claim `BLOCK_REWARD` of Hypothetical Assets from the Distribution contract. - -Both `RATE` and `BLOCK_REWARD` will be set upon deployment of the Aztec Rollup by the Aztec Governance. Both values are immutable and cannot be changed without re-deploying a new smart contract and a successful vote by Aztec Governance to switch to the new smart contracts. - -## Proposals contract - -This is the only smart contract that is able to submit proposals to the Governance contract. - -The Proposals Contract will accept proposals only from sequencers of the current canonical instance, as indicated by the Registry. - -```solidity -contract Proposals is IProposals { - - // ... imports - - IGovernance public immutable GOVERNANCE; - IRegistry public immutable REGISTRY; - uint256 public immutable N; - uint256 public immutable M; - - constructor(IGovernance _governane, IRegistry _registry, uint256 _n, uint256 _m) { - // ... - - require(N > M / 2); - require(N <= M); - } - - function vote(address _proposal) external override(IProposals) returns (bool) { - require(_proposal.code.length > 0); - // ... - - Rollup instance = Rollup(REGISTRY.getRollup()); - address proposer = instance.getCurrentProposer(); - require(msg.sender == proposer); - } - // ... -} -``` - -To vote to table a proposal, the current sequencer of the canonical rollup must deploy the contracts being proposed to upgrade / migrate to, to the L1. Then the current sequencer deploys the upgrade logic i.e. `_proposal`, then call `Proposals.vote(_proposal)`. - -The Proposals contract will then count votes specifying that same `_proposal`. For a proposal to be nominated for voting, it must garner at least N votes in a single round, where a round is defined as a M consecutive L2 slots. Round 1 is L2 slots 0 - M - 1, while Round 2 is L2 slots M - 2M - 1 and so on. - -Note that a sequencer’s ability to vote is not affected by the rollupʼs availability since voting happens on the L1. - -```mermaid -flowchart TD - Issuer[Issuer] -->|1. Calls mint| HypotheticalAsset[Hypothetical Asset] - Issuer -->|2. Transfer Hypothetical Asset| RewardDistribution[Reward Distribution] - RewardDistribution -->|3. Calls claim| RollupContract[RollupContract] -``` - -If the quorum has been reahed, anyone can call `pushProposal(uint256 _roundNumber)` on the Proposals contract to send the proposal to the Governance contract for voting. As a result, only one proposal can be nominated for voting at any given round. - -## Governance contract - -This contract is the “assembly of Aztec citizensˮ that is the final arbiter of whether to enact the proposals from the Proposals Contract or not. - -This contract decides what is the canonical instance which gets block rewards. - -The Proposals contract tables proposals for voting, Holders who lock their Hypothetical Assets with the Governance contract may vote once for each Hypothetical Asset locked. They can vote either Yea or Nea. - -Once a proposal garners the minimum number of votes, and the Yay votes exceed Nay by at least the `quorum%` , the proposal can be executed by the Governance contract. - -```solidity -contract Governance is IGovernance { // ... imports - IERC20 public immutable ASSET; address public proposalsContract; // ... - constructor(IERC20 _asset, address _proposalsContract, ui nt256 _votingDelay, uint256 _votingDuration, uint256 _gracePeriod, uint256 _quorum, uin t256 _voteDifferential, uint256 _minimumVotes) { // ... - configuration = DataStructures.Configuration({ votingDelay: Timestamp.wrap(_votingDelay), // Min time between proposal creation and when voting starts votingDuration: Timestamp.wrap(_votingDuration), // Max duration of voting period - executionDelay: Timestamp.wrap(_executionDelay), // Min time between voting passing and proposal execution gracePeriod: Timestamp.wrap(_gracePeriod), // max time between proposal creation and proposal execution. - quorum: _quorum, // % of deposited ASSET that mus t participate in a vote (could be Yes or No) voteDifferential: _voteDifferential, // Yea must outweight Nea by this % to pass vote minimumVotes: _minimumVotes, // users with this much cummulative deposited ASSET must participate in the vote }) - } -// ... -function deposit(address _onBehalfOf, uint256 _amount) external override(IGovernance) { - // deposits are allowed on behalf of other addresses - users[_onBehalfOf].add(_amount); - // ... -} - -function initiateWithdraw(address _to, uint256 _amount) external override(IGovernance) returns (uint256) { - // ... - // No one can withdraw on behalf of someone else - users[msg.sender].sub(_amount); - // ... -} - -function propose(address _payload) external override(IGovernance) returns (bool) { - require(msg.sender == proposalsContract); - // ... -} - -function vote(uint256 _proposalId, uint256 _amount, bool _support) external override(IGovernance) returns (bool) {} - -function execute(uint256 _proposalId) external override(IGovernance) returns (bool) { - // execute proposal via `call()` -} -``` diff --git a/docs/docs-network/concepts/governance/governance.md b/docs/docs-network/concepts/governance/governance.md deleted file mode 100644 index a96fa065538f..000000000000 --- a/docs/docs-network/concepts/governance/governance.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -id: governance -sidebar_position: 3 -title: Governance Overview -description: Learn about the governance process on the Aztec network. ---- - -import Image from "@theme/IdealImage"; - -This diagram outlines how governance works on Aztec: - - - -Sequencers put forward, or “nominate”, proposals for voting by the Aztec citizens. To do this, sequencers interact with the Governance Proposer smart contract. Nominations are “signals” by sequencers that they wish to put up for vote the execution of certain code by the Governance smart contract. - -If the Governance Proposer smart contract records a certain number of nominations/signals from sequencers, then the Governance Proposer smart contract initiates a voting process where any holders of any Hypothetical Assets can participate. - -All voting and signalling happen on the L1. diff --git a/docs/docs-network/concepts/governance/gse.md b/docs/docs-network/concepts/governance/gse.md new file mode 100644 index 000000000000..ab3f8070571a --- /dev/null +++ b/docs/docs-network/concepts/governance/gse.md @@ -0,0 +1,229 @@ +--- +title: GSE and Stake Mobility +description: Learn how the Governance Staking Escrow (GSE) enables seamless stake migration during rollup upgrades. +displayed_sidebar: conceptsSidebar +--- + +# Governance Staking Escrow (GSE) + +The Governance Staking Escrow (GSE) solves a critical challenge in network upgrades: how do validators transition their stake from an old rollup to a new one without lengthy exit and entry delays? + +## The Problem + +When the network upgrades to a new rollup contract, validators face a dilemma: + +1. Their stake is locked in the old rollup +2. Exiting the old rollup has a delay (for security) +3. Entering the new rollup has a queue +4. During this transition, they can't validate on either rollup + +Without a solution, upgrades would cause significant disruption as the validator set scrambles to migrate. + +## The Solution: GSE + +The GSE acts as a neutral escrow that holds validator stakes on behalf of rollup contracts. Instead of validators depositing directly into each rollup, they deposit into the GSE, which: + +1. Tracks stakes per validator per rollup +2. Allows stakes to automatically move with rollup upgrades +3. Maintains voting power delegation for governance +4. Enables seamless transitions between rollup versions + +## How It Works + +### Depositing with Move Flag + +When a validator deposits stake, they choose whether their stake should follow upgrades: + +```solidity +function deposit( + address _attester, + address _withdrawer, + bool _moveWithLatestRollup +) external; +``` + +The `_moveWithLatestRollup` flag determines stake behavior: + +| Flag Value | Behavior | +|------------|----------| +| `false` | Stake is tied to the specific rollup address | +| `true` | Stake follows the "latest" rollup automatically | + +### The Bonus Instance + +The GSE uses a special address called the "bonus instance" to track stakes that should move: + +```solidity +address public constant BONUS_INSTANCE_ADDRESS = + address(uint160(uint256(keccak256("bonus-instance")))); +``` + +This is the one exception where "instance" doesn't refer to a rollup contract—it's a virtual address for accounting purposes. + +### Stake Visibility + +When the GSE determines which validators have stake in a rollup: + +- Stakes deposited with `_moveWithLatestRollup = false` are tied to that rollup's address +- Stakes deposited with `_moveWithLatestRollup = true` are tied to the bonus instance +- Only the **latest** rollup in the GSE can access stakes from the bonus instance + +### Example Scenario + +``` +Initial State: +├── Rollup A is canonical +├── Alice deposits 100 tokens (moveWithLatest = false) +├── Bob deposits 100 tokens (moveWithLatest = true) +└── Both can validate on Rollup A + +After Upgrade to Rollup B: +├── Rollup B is now canonical +├── Alice's stake: Still on Rollup A only +├── Bob's stake: Now available to Rollup B +├── Alice must manually exit A and enter B +└── Bob validates on B immediately +``` + +## GSE Payload Verification + +When the Governance Proposer wraps payloads in a [GSEPayload](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/governance/GSEPayload.sol), it adds checks to ensure the new rollup has sufficient stake: + +After executing the original payload actions, the GSEPayload verifies: + +``` +(stake in latest rollup) + (stake in bonus instance) > 2/3 of total stake +``` + +This prevents proposals that would leave the network without a supermajority of validators on the active rollup. + +### Why This Matters + +Without this check: +- A malicious proposal could switch to a rollup with zero validators +- Block production would halt +- The network couldn't even propose a fix through governance + +The GSEPayload ensures continuity of the validator set across upgrades. + +## GSE Accounting + +The GSE maintains several pieces of information per rollup: + +### Per Validator (Attester) +- Balance in the rollup +- Withdrawer address (who can initiate withdrawals) +- Delegation target (who votes with their power) + +### Per Rollup +- Total stake deposited +- Entry/exit queues +- Latest rollup pointer + +### For Governance +- Voting power per delegatee +- Power used per proposal +- Timestamp snapshots for voting + +## Voting Power Delegation + +By default, when validators deposit stake: + +1. Their voting power is delegated to the rollup contract +2. The rollup votes "yea" on proposals its block producers signaled for +3. This creates automatic alignment between validators and governance + +### Custom Delegation + +Validators can change their delegation: + +```solidity +function delegate( + address _rollup, + address _attester, + address _delegatee +) external; +``` + +Requirements: +- Must be called by the withdrawer +- Delegatee can be any address (including the validator themselves) +- Once delegated, the delegatee can vote directly through the GSE + +### Voting Through GSE + +After custom delegation, validators can vote directly: + +```solidity +function vote( + uint256 _proposalId, + uint256 _amount, + bool _support +) external; +``` + +This allows: +- Voting against proposals (rollups always vote "yea") +- Partial voting with specific amounts +- More granular control + +## Propose With Lock + +The GSE provides an escape hatch for creating proposals without sequencer signaling: + +```solidity +function proposeWithLock(IPayload _payload, address _to) external returns (uint256); +``` + +This function: +1. Takes tokens from `msg.sender` +2. Deposits them into Governance +3. Calls `proposeWithLock` on Governance +4. Creates a proposal with a long withdrawal lock + +The long lock prevents governance attacks while ensuring the network can always upgrade if needed. + +## State Transitions + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ GSE State │ +├─────────────────────────────────────────────────────────────────┤ +│ Rollup A (old) │ Bonus Instance │ Rollup B (new) │ +│ ───────────────── │ ─────────────── │ ────────────── │ +│ Alice: 100 │ Bob: 100 │ (empty) │ +│ │ │ │ +│ Access: Rollup A only │ Access: Latest │ Access: B only │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ (Upgrade to B) +┌─────────────────────────────────────────────────────────────────┐ +│ Rollup A (old) │ Bonus Instance │ Rollup B (new) │ +│ ───────────────── │ ─────────────── │ ────────────── │ +│ Alice: 100 │ Bob: 100 │ (empty) │ +│ │ │ │ │ +│ Alice validates on A │ └───────────┼──▶ Bob can │ +│ (must exit to move) │ │ validate │ +└─────────────────────────────────────────────────────────────────┘ +``` + +## Best Practices + +### For Validators + +1. **Use `moveWithLatestRollup = true`** if you want automatic migration +2. **Delegate to yourself** if you want to vote independently +3. **Monitor governance proposals** even if your stake moves automatically + +### For Governance Proposals + +1. **Ensure new rollups use the same GSE** for stake continuity +2. **Test that sufficient stake will be available** before signaling +3. **Allow time for validators to prepare** before execution + +## Related Topics + +- [Voting](./voting) - How voting power and delegation work +- [Proposal Lifecycle](./proposal-lifecycle) - How GSEPayload wrapping fits in +- [Upgrades](./upgrades) - End-to-end upgrade process +- [Proof of Stake](../proof-of-stake/) - How staking works at the protocol level diff --git a/docs/docs-network/concepts/governance/index.md b/docs/docs-network/concepts/governance/index.md new file mode 100644 index 000000000000..448a5ed0dce3 --- /dev/null +++ b/docs/docs-network/concepts/governance/index.md @@ -0,0 +1,112 @@ +--- +title: Governance Overview +description: Learn how the Aztec network is governed through onchain voting, sequencer signaling, and stake-based voting power. +displayed_sidebar: conceptsSidebar +--- + +import Image from "@theme/IdealImage"; + +# Governance + +The Aztec network is governed by its community through an onchain governance system. This system allows the network to upgrade rollup contracts, adjust parameters, and evolve over time while maintaining security and decentralization. + +## Design Goals + +The governance system is designed around two core requirements: + +1. **Backwards Compatibility**: Users must always be able to bridge assets in and out of any rollup version that has ever existed +2. **Canonical Rewards**: Only the most recent (canonical) rollup should receive block rewards + +These goals shape the entire governance architecture, from how rollups are tracked to how upgrades are proposed and executed. + +## How Governance Works + + + +Governance follows a multi-stage process: + +1. **Signaling**: Block producers on the canonical rollup signal support for a payload by calling `signal()` on the Governance Proposer during their assigned slots +2. **Quorum**: When enough signals are received within a round (e.g., 151 out of 300 slots), the payload qualifies for proposal +3. **Proposal Creation**: Anyone can call `submitRoundWinner()` to formally submit the payload as a proposal to Governance +4. **Voting**: Token holders vote on the proposal using their voting power (determined at the moment voting opens) +5. **Execution**: After the voting period and execution delay, anyone can trigger execution of approved proposals + +All signaling and voting happen on L1 (Ethereum). + +## Core Contracts + +The governance system consists of several interconnected smart contracts: + +### Registry + +The [Registry](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/governance/Registry.sol) maintains a list of all rollup contract instances. The most recent entry is considered "canonical" and is eligible to receive block rewards. The Registry's `addRollup()` function can only be called by the Governance contract. + +### Governance + +The [Governance](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/governance/Governance.sol) contract is the core of the system. It: + +- Receives proposals from the Governance Proposer +- Tracks proposal state through their lifecycle +- Manages voting power through deposits and withdrawals +- Executes approved proposals + +### Governance Proposer + +The [Governance Proposer](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/governance/proposer/GovernanceProposer.sol) is the gateway for submitting proposals. Only this contract can propose to Governance, ensuring that proposals have community support before entering the voting phase. + +The Governance Proposer extends the [EmpireBase](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/governance/proposer/EmpireBase.sol) contract, which implements the round-based signaling mechanism. + +### Governance Staking Escrow (GSE) + +The [GSE](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/governance/GSE.sol) bridges staking and governance. It: + +- Holds validator stakes on behalf of rollup contracts +- Tracks voting power delegation +- Enables stake to automatically move to new rollup versions +- Allows validators to vote independently or delegate to the rollup + +See [GSE and Stake Mobility](governance/gse) for details. + +## Key Concepts + +### Payloads + +A **payload** is a contract that defines the actions to be executed if a proposal passes. Payloads implement the [IPayload](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/governance/interfaces/IPayload.sol) interface, which has a `getActions()` function returning a list of calls to make. + +For example, a payload to register a new rollup would include a call to `Registry.addRollup(newRollupAddress)`. + +### Rounds and Slots + +The signaling system operates in **rounds**, where each round consists of a fixed number of **slots** (e.g., 300 slots per round). A slot corresponds to approximately 36 seconds of L2 time. + +During each slot, only the designated block proposer can signal for a payload. This prevents timing games and ensures signaling reflects genuine validator support. + +### Quorum + +For a payload to become a proposal, it must receive signals from a quorum of slots within a single round. For example, if quorum is set to 151 out of 300 slots, at least 151 different block proposers must signal for the same payload address within one round. + +### Voting Power + +Voting power in Governance comes from depositing tokens. Key points: + +- Power is timestamped at deposit time +- When voting on a proposal, only power you had *before* the proposal became active counts +- Withdrawing requires a two-step process with a delay (on the order of days) +- Partial voting is allowed (e.g., vote "yea" with half your power, "nay" with the other half) + +## Topics in This Section + +- [Proposal Lifecycle](governance/proposal-lifecycle) - The complete journey from payload to execution +- [Voting](governance/voting) - How voting power works and how votes are cast +- [GSE and Stake Mobility](governance/gse) - How the GSE enables seamless rollup upgrades +- [Upgrades](governance/upgrades) - The end-to-end process for network upgrades + +## Related Guides + +:::tip For Sequencer Operators +To participate in governance as a sequencer (signaling and voting), see [Governance Participation](../operators/sequencer-management/creating_and_voting_on_proposals). +::: + +:::tip For Token Holders +To vote on proposals with your staked tokens, see [Voting on Proposals](../users/voting). +::: diff --git a/docs/docs-network/concepts/governance/proposal-lifecycle.md b/docs/docs-network/concepts/governance/proposal-lifecycle.md new file mode 100644 index 000000000000..74f44673fbae --- /dev/null +++ b/docs/docs-network/concepts/governance/proposal-lifecycle.md @@ -0,0 +1,221 @@ +--- +title: Proposal Lifecycle +description: Learn how proposals move through the governance process, from initial signaling to final execution. +displayed_sidebar: conceptsSidebar +--- + +# Proposal Lifecycle + +A proposal's journey from idea to execution involves multiple stages, each with specific requirements and timing constraints. This page details each stage of the lifecycle. + +## Overview + +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ Payload │────▶│ Signaling │────▶│ Queued │────▶│ Active │────▶│ Executable │────▶│ Executed │ +│ Deployed │ │ (Round) │ │(Voting Delay│ │ (Voting) │ │(Exec. Delay)│ │ │ +└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ + │ │ + ▼ ▼ + ┌─────────────┐ ┌─────────────┐ + │ Expired │ │ Rejected │ + │ (No Quorum) │ │(Insufficient│ + └─────────────┘ │ Support) │ + └─────────────┘ +``` + +## Stage 1: Payload Deployment + +Before any governance process begins, someone must deploy the contracts that define what the proposal will do: + +1. **New Contracts**: Deploy any new contracts the proposal requires (e.g., a new rollup version) +2. **Payload Contract**: Deploy a payload contract implementing `IPayload` that returns the actions to execute + +```solidity +interface IPayload { + struct Action { + address target; + bytes data; + } + + function getActions() external view returns (Action[] memory); +} +``` + +For example, a payload to add a new rollup to the Registry might look like: + +```solidity +contract RegisterRollupPayload is IPayload { + IRegistry public immutable REGISTRY; + address public immutable NEW_ROLLUP; + + constructor(IRegistry _registry, address _newRollup) { + REGISTRY = _registry; + NEW_ROLLUP = _newRollup; + } + + function getActions() external view returns (Action[] memory) { + Action[] memory actions = new Action[](1); + actions[0] = Action({ + target: address(REGISTRY), + data: abi.encodeWithSelector(REGISTRY.addRollup.selector, NEW_ROLLUP) + }); + return actions; + } +} +``` + +## Stage 2: Signaling + +Once a payload is deployed, block producers on the canonical rollup can signal support for it. + +### How Signaling Works + +The Governance Proposer operates in **rounds**. Each round consists of `ROUND_SIZE` slots (e.g., 300 slots, approximately 180 minutes at 36 seconds per slot). + +During each slot: +1. The Governance Proposer queries the canonical rollup for the current proposer +2. Only that proposer can successfully call `signal(payloadAddress)` +3. The signal is recorded for the current round + +### Reaching Quorum + +A payload reaches quorum when it receives `QUORUM` signals within a single round. For example: +- Round size: 300 slots +- Quorum: 151 signals (>50% of round size) + +If multiple block proposers signal for the same payload address and it reaches 151 signals before the round ends, that payload wins the round. + +### Round Expiration + +If no payload reaches quorum by the end of a round: +- All signals for that round are discarded +- A new round begins +- Signaling can start fresh for any payload + +## Stage 3: Proposal Submission + +When a payload reaches quorum, anyone can call `submitRoundWinner()` on the Governance Proposer to formally create a proposal. + +### GSE Payload Wrapping + +The Governance Proposer doesn't submit the original payload directly. Instead, it wraps it in a [GSEPayload](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/governance/GSEPayload.sol) that: + +1. Copies all actions from the original payload +2. Appends an `amIValid()` validation check as the final action +3. When executed, verifies that >2/3 of total stake remains with the latest rollup + +:::note Validation Timing +The GSEPayload validation runs at **execution time**, not at proposal submission. This means a proposal could pass voting but fail execution if stake distribution changes during the voting and execution delay periods. +::: + +This wrapping prevents proposals that would leave the network without a supermajority of validators on the active rollup. + +## Stage 4: Queued (Voting Delay) + +After submission, the proposal enters a mandatory waiting period before voting opens. + +- **Purpose**: Give the community time to review the proposal +- **Duration**: Configurable (e.g., 12 hours on testnet) +- **State**: Proposal exists but no votes can be cast yet + +During this period: +- Anyone can review the payload code +- Community discussion can occur offchain +- Token holders can prepare their voting power + +:::warning Voting Power Snapshot +Voting power is snapshotted at the moment the proposal transitions from Queued to Active. If you want to vote on a proposal, you must have deposited tokens *before* the voting delay ends. +::: + +## Stage 5: Active (Voting Period) + +Once the voting delay passes, the proposal becomes active and voting opens. + +- **Duration**: Configurable (e.g., 24 hours on testnet) +- **Who can vote**: Anyone with voting power at the snapshot timestamp +- **Vote options**: "Yea" (support) or "Nay" (oppose) + +### Voting Mechanics + +- Votes are weighted by voting power at the snapshot +- Partial voting is allowed (split your power between yea and nay) +- Votes cannot be changed once cast +- The rollup contract automatically votes "yea" on proposals it signaled for + +See [Voting](./voting) for complete details on voting mechanics. + +## Stage 6: Resolution + +When the voting period ends, the proposal's fate is determined: + +### Passed +If the proposal receives sufficient support: +- "Yea" votes exceed the required threshold +- Proposal transitions to Executable state + +### Rejected +If the proposal fails to gain sufficient support: +- Proposal is marked as rejected +- It cannot be executed +- A new proposal would need to go through the entire process again + +## Stage 7: Executable (Execution Delay) + +Proposals that pass voting enter another waiting period before execution. + +- **Purpose**: Allow node operators time to prepare for changes +- **Duration**: Configurable (e.g., 12 hours on testnet) +- **State**: Approved but not yet executed + +This delay is critical for upgrades because: +- Operators may need to update node software +- Services can prepare for the transition +- Any last-minute issues can be identified + +## Stage 8: Execution + +After the execution delay, anyone can call `execute(proposalId)` on the Governance contract. + +Execution: +1. Retrieves the proposal's payload +2. Calls `getActions()` on the payload +3. Executes each action in sequence +4. Marks the proposal as executed + +If any action reverts, the entire execution reverts and the proposal remains executable. + +## Timeline Example (Testnet) + +| Stage | Duration | Cumulative Time | +|-------|----------|-----------------| +| Signaling | Up to 1 round (~3 hours) | 3 hours | +| Voting Delay | 12 hours | 15 hours | +| Voting Period | 24 hours | 39 hours | +| Execution Delay | 12 hours | 51 hours | +| **Total** | | **~2 days minimum** | + +Note: Mainnet parameters will likely be longer to provide more security. + +## Escape Hatch: Propose With Lock + +What if block producers cannot or will not signal for a critical proposal? The governance system includes an escape hatch. + +The `proposeWithLock()` function allows anyone with sufficient voting power to bypass the signaling process: + +```solidity +function proposeWithLock(IPayload _proposal, address _to) external returns (uint256); +``` + +This requires: +- A large amount of voting power (configured in governance) +- The power is immediately locked with a long withdrawal delay +- The proposal still goes through normal voting + +This mechanism protects against governance capture while ensuring the network can always upgrade if needed. + +## Related Topics + +- [Voting](./voting) - Detailed voting mechanics +- [GSE and Stake Mobility](./gse) - How GSEPayload ensures stake continuity +- [Upgrades](./upgrades) - End-to-end upgrade process diff --git a/docs/docs-network/concepts/governance/putting_forward_proposals.md b/docs/docs-network/concepts/governance/putting_forward_proposals.md deleted file mode 100644 index 270f69e3c8be..000000000000 --- a/docs/docs-network/concepts/governance/putting_forward_proposals.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -sidebar_position: 0 -title: Putting forward Proposals -description: Learn how to put forward proposals for governance on the Aztec network. ---- - -Sequencers of the _current_ canonical rollup (as indicated by the Registry) can propose changes to the Aztec community for voting. In order for a proposal to be voted on through the governance process, _N_ sequencers must nominate the proposal in any given round. A round is defined as a sequence of contiguous _M_ L2 blocks. Both _N_ and _M_ are governance defined parameters. - -Sequencers can only nominate a proposal during an L2 slot for which they’ve been assigned proposer duties. This minimizes timing games and provides a lower bound on the time required to successfully bring about a vote by governance. - -A mechanism is also proposed whereby any Hypothetical Asset holder (“Holderˮ) can burn a large quantity of Hypothetical Asset to trigger a vote on a proposal, without having the sequencers nominating the proposal. Note that Hypothetical Asset holders would still need to vote to approve any proposals nominated via this mechanism. - -To nominate a proposal, a sequencer of the current canonical rollup would deploy two sets of contracts: - -1. The upgraded contracts they wish to upgrade to -2. `code` which can be executed by governance to upgrade into these contracts - -Then when it is their turn as the proposer, they call `vote(address _proposal)` on the `Proposals` contract, where `_proposal ` is the address of the `code` payload. Alternatively, sequencers can set the `GOVERNANCE_PROPOSAL_PAYLOAD=_proposal` env variable which will call `vote(address _proposal)` during a slot they're eligible to signal in. diff --git a/docs/docs-network/concepts/governance/upgrades.md b/docs/docs-network/concepts/governance/upgrades.md index 8bf80b60b125..d79d90bf7067 100644 --- a/docs/docs-network/concepts/governance/upgrades.md +++ b/docs/docs-network/concepts/governance/upgrades.md @@ -1,41 +1,66 @@ --- -sidebar_position: 4 -title: Upgrades -description: Learn about the network upgrade process for the Aztec network. +title: Network Upgrades +description: Learn how the Aztec network upgrades to new rollup versions and how validators transition. +displayed_sidebar: conceptsSidebar --- -Upgrades involve transitioning the network to a new instance of the Rollup contract. They might fix vulnerabilities, introduce new features, or enhance performance. +# Network Upgrades -## AZIP +Network upgrades transition the Aztec network to a new rollup contract instance. This page explains why upgrades happen, how the Registry model works, and how validators migrate to new versions. -It is expected that the community will coordinate upgrade proposals via an AZIP process, which is a design document outlining the upgrade rationale and one that allows for collecting technical input from and by the community. +For the detailed governance stages (signaling, voting, execution), see [Proposal Lifecycle](./proposal-lifecycle). -Once developers of client software agree to support the upgrade, sequencers can begin signaling to table this proposal from a certain block height. +## Why Upgrades Happen -## Initial Contract Deployment +The Aztec protocol evolves over time. Common reasons for upgrades include: -The initial deployment creates a set of contracts, as described in the [Deployment section](../deployments/what_is_deployment.md). +- **Security Fixes**: Patching vulnerabilities discovered in the rollup +- **Feature Additions**: Adding new functionality to the protocol +- **Performance Improvements**: Optimizing proof generation or block processing +- **Parameter Changes**: Adjusting staking requirements, fees, or timing -## Upgrading the Rollup Contract +## The Registry Model -1. **Proposal Creation:** +The Aztec governance system maintains a [Registry](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/governance/Registry.sol) of all rollup contract instances. This design enables: - - A new Rollup contract is deployed to the network - - Proposal code to execute the upgrade is deployed separately +1. **Backwards Compatibility**: Every rollup that has ever existed remains accessible. Users can always bridge assets in or out of any historical rollup version. -2. **Sequencer Participation:** +2. **Canonical Selection**: Only the most recent rollup in the Registry is "canonical" and receives block rewards. - - Sequencers must signal their readiness by voting through the Proposals contract. - - This vote occurs during their assigned L2 slot, as dictated by the L1 Rollup smart contract. +When an upgrade passes governance, the new rollup address is added to the Registry via `addRollup()`. -3. **Governance Approval:** - - Hypothetical Asset holders vote to approve or reject the proposal. Votes are proportional to the amount of Hypothetical Asset locked in the Governance contract. +## Validator Transition -## Proposal Execution +The [GSE](./gse) enables smooth validator transitions during upgrades. -After governance approval and a delay period, the proposal becomes executable: +### Automatic Migration -- Any Ethereum account can call `execute(_proposalId)` on the Governance contract. -- The `execute` function calls the proposal code, transitioning the network to the new Rollup instance. +Validators who deposited with `moveWithLatestRollup = true`: +- Stake automatically becomes available to the new rollup +- No action required—they can validate immediately +- Voting power moves with their stake -For a more hands-on guide to participating in governance as a sequencer, see the [Governance and Proposal Process](../../operation/sequencer_management/creating_and_voting_on_proposals.md) guide. +### Manual Migration + +Validators who deposited with `moveWithLatestRollup = false`: +- Must initiate withdrawal from the old rollup (has a delay) +- Then deposit into the new rollup (may have an entry queue) +- Temporary gap in validation ability + +### Best Practice + +Use `moveWithLatestRollup = true` for seamless upgrades. Only use `false` if you specifically want to remain on an older rollup version. + +## After an Upgrade + +Once an upgrade is executed: + +1. **New Rollup is Canonical**: Block rewards go to the new rollup; Governance Proposer accepts signals only from new rollup validators + +2. **Old Rollup Remains Accessible**: Users can still bridge assets in/out; validators with unmoved stake can still operate + +## Related Topics + +- [Proposal Lifecycle](./proposal-lifecycle) - Detailed stages from signaling to execution +- [GSE and Stake Mobility](./gse) - How stake transitions work +- [Governance Participation](../../operators/sequencer-management/creating_and_voting_on_proposals) - How to participate as a sequencer diff --git a/docs/docs-network/concepts/governance/voting.md b/docs/docs-network/concepts/governance/voting.md index e21008876b37..7ef8697820f4 100644 --- a/docs/docs-network/concepts/governance/voting.md +++ b/docs/docs-network/concepts/governance/voting.md @@ -1,11 +1,216 @@ --- -sidebar_position: 1 -title: Voting on Proposals -description: Learn about the voting process for governance on the Aztec network. +title: Voting +description: Learn how voting power works in Aztec governance, including deposits, withdrawals, delegation, and vote casting. +displayed_sidebar: conceptsSidebar --- -Holders have the ability to vote on proposals as long as they lock any Hypothetical Assets within the Governance contract. The act of locking the funds can be thought of as “activatingˮ the voting power of Hypothetical Asset. Locked Hypothetical Assets used to vote on a proposal must wait a delay before being withdrawn to prevent malicious governance attacks. +# Voting -Hypothetical Assets locked in the Governance contract are simply locked and not “at stakeˮ i.e. there are no slashing conditions. +Voting is how the Aztec community decides which proposals should be executed. This page explains how voting power is acquired, managed, and used. -Since sequencers may be able to stake Hypothetical Assets with the rollup instances in order to join the sequencer set, the rollup instance could in turn lock those Hypothetical Assets in the Governance contract and vote on behalf of the sequencers. This is expected behavior. +## Voting Power + +Voting power in Governance comes from depositing tokens into the Governance contract. The amount of tokens deposited equals your voting power. + +### Acquiring Voting Power + +To get voting power, call `deposit()` on the Governance contract: + +```solidity +function deposit(address beneficiary, uint256 amount) external; +``` + +This: +1. Transfers tokens from `msg.sender` to the Governance contract +2. Increases the `beneficiary`'s voting power +3. Records the power with a timestamp + +### Timestamped Power + +Voting power is **timestamped** at the moment of deposit. This is crucial because: + +- When voting on a proposal, you can only use power you had *before* the proposal became active +- This prevents flash loan attacks where someone borrows tokens just to vote +- Your current balance doesn't matter; only your historical balance at the snapshot + +Example: +``` +Timeline: +├── Day 1: Alice deposits 1000 tokens +├── Day 2: Proposal becomes Active (snapshot taken) +├── Day 3: Alice deposits 500 more tokens +└── Day 4: Alice votes + +Alice can only vote with 1000 tokens (her balance at the Day 2 snapshot) +``` + +## Deposit Control + +By default, not everyone can deposit into Governance. A **deposit control** mechanism restricts who can hold voting power. + +### GSE as Deposit Controller + +In the standard configuration, only the Governance Staking Escrow (GSE) can deposit into Governance. This means: + +- Validators who stake into the rollup automatically get voting power +- The rollup contract can vote on behalf of its validators +- Non-validators cannot directly hold governance power + +### Disabling Deposit Control + +Governance can vote to disable deposit control, allowing anyone to hold voting power. This requires executing a proposal that calls the appropriate function on the Governance contract. + +:::note Current Status +On mainnet, deposit control was disabled at launch by passing the zero address as the GSE to the Governance constructor. This means anyone can deposit tokens and participate in governance. +::: + +## Withdrawing + +Withdrawing voting power is a two-step process with a mandatory delay. + +### Step 1: Initiate Withdrawal + +Call `initiateWithdraw()` to start the withdrawal process: + +```solidity +function initiateWithdraw(address to, uint256 amount) external; +``` + +This: +1. Reduces your voting power immediately +2. Creates a pending withdrawal record +3. Starts the withdrawal delay timer + +### Step 2: Finalize Withdrawal + +After the delay period passes, call `finaliseWithdraw()`: + +```solidity +function finaliseWithdraw(uint256 withdrawalId) external; +``` + +This transfers the tokens to the specified recipient. + +### Why the Delay? + +The withdrawal delay (typically on the order of days) prevents governance attacks: + +- Attackers cannot quickly deposit, vote, and withdraw +- The community has time to react to suspicious voting patterns +- Long-term stakeholders have more influence than short-term speculators + +## Delegation + +Validators can delegate their voting power to another address, allowing for flexible voting arrangements. + +### Default Delegation + +When a validator deposits stake into a rollup: +1. The stake is held in the GSE +2. Voting power is delegated to the rollup contract by default +3. The rollup votes automatically on proposals its block producers signaled for + +### Custom Delegation + +Validators can delegate to themselves or any other address: + +```solidity +// On the GSE +function delegate(address rollup, address attester, address delegatee) external; +``` + +After delegating to yourself, you can vote directly on the GSE: + +```solidity +function vote(uint256 proposalId, uint256 amount, bool support) external; +``` + +### Delegation Accounting + +The GSE tracks: `delegatee => proposal => power used` + +This allows: +- Partial voting (use some power for "yea", some for "nay") +- Split delegation (delegate to multiple addresses) +- Transparent power tracking + +## Casting Votes + +### Voting Through the Rollup + +The rollup contract has a `vote(uint256 proposalId)` function that: + +1. Checks the rollup is canonical according to the Registry +2. Verifies it was canonical when the proposal was created +3. Votes "yea" using all delegated voting power + +The rollup only votes on proposals that: +- Were submitted through the Governance Proposer +- Had their block producers signal for the payload +- Match the current governance configuration + +### Voting Through the GSE + +If you've delegated to yourself, vote directly on the GSE: + +```solidity +function vote( + uint256 proposalId, + uint256 amount, + bool support // true = yea, false = nay +) external; +``` + +This allows: +- Voting against proposals (the rollup always votes "yea") +- Partial voting with specific amounts +- More granular control over your voting power + +## Partial Voting + +You can split your voting power between "yea" and "nay" on the same proposal: + +```solidity +// Vote "yea" with half your power +gse.vote(proposalId, 500, true); + +// Vote "nay" with the other half +gse.vote(proposalId, 500, false); +``` + +This is useful when you: +- Have mixed feelings about a proposal +- Want to signal nuanced support +- Are voting on behalf of multiple stakeholders + +## Vote Finality + +Once cast, votes cannot be changed. Consider carefully before voting, as you cannot: +- Switch from "yea" to "nay" or vice versa +- Increase or decrease your vote amount +- Revoke your vote + +## Quorum and Thresholds + +For a proposal to pass, it must meet certain thresholds: + +- **Participation Quorum**: Minimum total votes (yea + nay) required +- **Approval Threshold**: Minimum percentage of "yea" votes required + +These parameters are configured in the Governance contract and can be changed through governance proposals. + +## Timeline Considerations + +| Event | Voting Power Impact | +|-------|---------------------| +| Deposit tokens | Power recorded with current timestamp | +| Proposal becomes Active | Snapshot taken of all power at this moment | +| Vote on proposal | Must have power from before the snapshot | +| Initiate withdrawal | Power reduced immediately | +| Finalize withdrawal | Tokens returned after delay | + +## Related Topics + +- [Proposal Lifecycle](./proposal-lifecycle) - When voting occurs in the proposal process +- [GSE and Stake Mobility](./gse) - How validator stakes translate to voting power +- [Voting on Proposals](../../users/voting) - Practical guide for token holders diff --git a/docs/docs-network/concepts/index.md b/docs/docs-network/concepts/index.md new file mode 100644 index 000000000000..36428b60e1fe --- /dev/null +++ b/docs/docs-network/concepts/index.md @@ -0,0 +1,44 @@ +--- +title: Network Concepts +description: Understand how the Aztec network works - architecture, consensus, governance, and more. +displayed_sidebar: conceptsSidebar +--- + +# Network Concepts + +This section explains how the Aztec network operates. Understanding these fundamentals helps you participate more effectively, whether as a token holder or infrastructure operator. + +## Architecture + +How the different components of the network work together: + +- [Block Production](concepts/architecture/block-production) - How transactions become blocks +- [Proving Coordination](concepts/architecture/proving-coordination) - How proofs are generated and submitted + +## Proof of Stake + +The economic mechanisms that secure the network: + +- [Proof of Stake](concepts/proof-of-stake) - Staking, rewards, and slashing + +## Governance + +How the protocol evolves through decentralized governance: + +- [Governance Overview](concepts/governance) - How decisions are made +- [Proposal Lifecycle](concepts/governance/proposal-lifecycle) - From idea to execution +- [Voting](concepts/governance/voting) - How voting works +- [Upgrades](concepts/governance/upgrades) - How the network upgrades + +## Contracts + +The smart contracts that power the network: + +- [L1 Contracts](concepts/contracts/deployment-architecture) - Core contract overview + +--- + +:::tip Ready to participate? +- **Token holders**: See [User Guides](users) to stake, delegate, and vote +- **Operators**: See [Operator Guides](operators) to run infrastructure +::: diff --git a/docs/docs-network/concepts/proof-of-stake/index.md b/docs/docs-network/concepts/proof-of-stake/index.md new file mode 100644 index 000000000000..13409c375855 --- /dev/null +++ b/docs/docs-network/concepts/proof-of-stake/index.md @@ -0,0 +1,112 @@ +--- +title: Proof of Stake +description: Learn about the proof of stake mechanism on the Aztec network - staking, rewards, and slashing. +displayed_sidebar: conceptsSidebar +--- + +# Proof of Stake + +The Aztec network uses a proof of stake consensus mechanism to secure the network and coordinate block production. + +## Overview + +In a proof of stake system: +- **Validators stake tokens** as collateral to participate in consensus +- **Block producers are selected** based on stake and randomness +- **Honest behavior is rewarded** with block rewards +- **Malicious behavior is punished** through slashing + +## Staking + +Validators must stake tokens on L1 to join the sequencer set. The staked tokens serve as: +- **Economic security**: Validators have financial incentive to behave honestly +- **Sybil resistance**: Prevents attackers from creating unlimited validator identities +- **Governance weight**: Stake can influence governance decisions + +### Staking Requirements + +**Activation Threshold**: To become an active validator, sequencers must stake at least the minimum activation threshold. This ensures validators have sufficient stake to be economically incentivized to behave honestly. + +**Activation Delay**: After staking, a sequencer needs to wait for an activation period before they can start proposing new blocks. This delay provides time for the network to recognize the new validator. + +**Unstaking Delay**: Unstaking requires a delay to allow for slashing of dishonest behavior that may have occurred while the validator was active. + +### Stake Delegation + +Token holders who don't want to run their own infrastructure can delegate their stake to professional operators. See the [Delegating Stake](../users/delegation) guide for details. + +### Key Registration + +When staking, each sequencer registers a public key that will be used for: +- VRF submissions for sequencer selection +- Attestation signatures +- Block proposal authentication + +## Sequencer Selection + +Each slot, a sequencer is selected to propose a block using a verifiable random function (VRF). The selection process ensures: +- **Randomness**: Proposer selection is unpredictable +- **Fairness**: All staked validators have a chance to propose +- **Verifiability**: Anyone can verify the selection was legitimate + +## Rewards + +The Aztec network distributes rewards to participants who contribute to network security and operation. Rewards are funded through protocol inflation and distributed to sequencers and provers. + +### Reward Distribution + +The Reward Distribution contract distributes tokens only to the canonical rollup instance (as indicated by the Registry contract). This ensures that only the legitimate chain receives rewards. + +Each epoch, the Rollup contract can claim `BLOCK_REWARD` tokens from the Distribution contract. The Rollup smart contract implements custom logic for how to split rewards among: +- Block proposers +- Committee members (attesters) +- Provers + +### Inflation Rate + +The protocol inflation rate is defined in the Issuer smart contract as the constant `RATE`. Key points: +- The inflation rate cannot be changed once the Issuer contract is deployed +- Aztec Governance can vote to deploy a new Issuer contract with a different `RATE` +- The Governance periodically calls `mint()` on the Issuer to fund the Distribution contract + +### Reward Flow + +```mermaid +flowchart TD + Issuer -->|1. Mints tokens| Token[Native Token] + Issuer -->|2. Transfers to| Distribution[Reward Distribution] + Rollup -->|3. Claims rewards| Distribution +``` + +The canonical Rollup contract calls `claim()` on the Distribution contract to receive rewards, which are then distributed to network participants. + +## Slashing + +Slashing is the mechanism by which validators lose a portion of their staked tokens for misbehavior. + +### Why Slashing Exists + +The chain must always (eventually) finalize new blocks. This requires: +1. More than 2/3 of the committee making attestations +2. Provers producing proofs + +### Slashable Offenses + +**Insufficient Quorum**: If a significant portion of the sequencer set goes offline and proposers cannot get enough attestations, the rollup cannot finalize new blocks. In prolonged cases, the network may enter [Based Fallback mode](https://forum.aztec.network/t/request-for-comments-aztecs-block-production-system/6155), where anyone can propose blocks if they supply proofs. + +**Data Withholding**: A malicious committee may not gossip transaction data or proofs to the rest of the network. Without this data, provers cannot produce proofs and the epoch will reorg. + +**Invalid State Roots**: Committee members who attest to invalid state transitions (either through negligence or malice) cause epochs to fail proving and reorg. + +### Slashing Mechanism + +Because transaction data and attestations are not posted onchain, automatic slashing is difficult to implement. Instead, the sequencer set votes to slash dishonest sequencers based on evidence collected both onchain and offchain, discussed and analyzed in community forums. + +A sequencer must aggregate BLS signatures on slashing proposals and post them to L1 for slash execution. When a sequencer's balance is slashed below `MINIMUM_STAKING_BALANCE` (e.g., 50%), they are removed from the sequencer set. + +--- + +:::tip Ready to participate? +- **Token holders**: See [Staking Tokens](../users/staking) to stake your tokens +- **Operators**: See [Sequencer Setup](../operators/setup/sequencer_management) to run a validator +::: diff --git a/docs/docs-network/concepts/proof_of_stake/_category_.json b/docs/docs-network/concepts/proof_of_stake/_category_.json deleted file mode 100644 index b4fac2f6e6ab..000000000000 --- a/docs/docs-network/concepts/proof_of_stake/_category_.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "position": 3, - "collapsible": true, - "collapsed": true, - "label": "Proof of Stake" -} diff --git a/docs/docs-network/concepts/proof_of_stake/index.md b/docs/docs-network/concepts/proof_of_stake/index.md deleted file mode 100644 index 1815233c7d35..000000000000 --- a/docs/docs-network/concepts/proof_of_stake/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -sidebar_position: 1 -title: Proof of Stake system -description: Learn about the proof of stake mechanism on the Aztec network. -draft: true ---- - -This doc will be updated soon. \ No newline at end of file diff --git a/docs/docs-network/concepts/proof_of_stake/slashing.md b/docs/docs-network/concepts/proof_of_stake/slashing.md deleted file mode 100644 index e196cb36e10c..000000000000 --- a/docs/docs-network/concepts/proof_of_stake/slashing.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -sidebar_position: 2 -title: Slashing -description: Learn about the slashing mechanism on the Aztec network. -draft: true ---- - -We need to make sure that the chain is always (eventually) finalizing new blocks. -The following conditions are required for the chain to finalize new blocks: - -1. More than 2/3 of the committee is making attestations -2. Provers are producing proofs. - -## Avoiding network halt - -There are some actions that impact the chainʼs ability to finalize new blocks: - -### Insufficient quorum - -In the event that a significant portion of the sequencer set goes offline (i.e. large internet outage) and proposers are unable to get enough attestations on block proposals, the Aztec Rollup will be unable to finalize new blocks. This will require the community to engage to fix the issue and make sure new blocks are being finalized. - -In the event of a prolonged period where the Aztec Rollup is not finalizing new blocks, it may enter Based Fallback mode. The conditions that lead to [Based Fallback (forum link)](https://forum.aztec.network/t/request-for-comments-aztecs-block-production-system/6155) mode are expected to be well defined by the community of sequencers, provers, client teams and all other Aztec Rollup stakeholders and participants. - -During Based Fallback mode, anyone can propose blocks if they supply proofs for these blocks alongside them. This is in contrast to the usual condition that only the sequencer assigned to a particular slot can propose blocks during that slot. This means that the inactive sequencer set is bypassed and anyone can advance the chain in the event of an inactive / non-participating sequencer set. - -But terminally inactive sequencers must be removed from the sequencer set or otherwise we end up in Based Fallback too often. Slashing is a method whereby the sequencer set votes to “slash” the stake of inactive sequencers down to a point where they are kicked off the sequencer set. For example, if we set `MINIMUM_STAKING_BALANCE=50%` then as soon as 50% or more of a sequencer's balance is slashed, they will be kicked out of the set. - -### Committee withholding data from the provers - -Provers need the transaction data (i.e. `TxObjects`) plus the client-side generated proofs to produce the final rollup proof, none of which are posted onchain. Client side proofs + transaction data are gossiped on the p2p instead so that committee members can re-execute block proposals and verify that the proposed state root is correct. - -Recall from the [RFC (forum link)](https://forum.aztec.network/t/request-for-comments-aztecs-block-production-system/6155) on block production that the committee is a subset of sequencers, randomly sampled from the entire sequencer set. Block proposers are sampled from this committee. ⅔ + 1 of this committee must attest to L2 block proposals before they are posted to the L1 by the block proposer. - -A malicious committee may not gossip the transaction data or proofs to the rest of the sequencer set, nor to the provers. As a result, no prover can produce the proof and the epoch in question will reorg by design. Recall from the RFC on block production that if no proof for epoch N is submitted to L1 by the end of epoch N+1, then epoch N + any blocks built in epoch N+1 are reorged. - -### Committee proposing an invalid state root - -Committee members who receive a block proposal from a proposer, must execute the block’s transaction to compare the resulting state root with that contained in the proposal. In theory, a committee member should only attest to a block proposal’s validity after checking for the correctness of the state root. - -A committee member could skip re-executing block proposals, for a number of reasons including saving compute, faulty client software or maliciousness. This opens up the possibility of a malicious proposer posting an invalid state transition to L1. Or a malicious entity that bribes ⅔ + 1 of the committee can obtain the required signatures to post an invalid state transition. -The epoch will not be proven and will be re-orged. - -### L1 congestion has made it impossible for provers to land proofs on time - -An honest prover who has funds at stake (i.e. posted a bond to produce the epoch proof), could be unable to post the proof on L1 due to congestion, an L1 reorg or just an inactivity of the L1 proposers (i.e. inactivity leak). - -## Slashing mechanism - -In all the previous cases, it is very hard to verify and automatically slash for these events onchain. This is mainly due to the fact that neither TxObjects nor client side proofs are posted onchain. Committee members also gossip attestations on the p2p and do not post them directly on chain. - -Therefore a slashing mechanism is required as a deterrence against the malicious behaviour by sequencers and to make sure that the Aztec Rollup retains liveness. The sequencer set votes to slash dishonest sequencers based on evidence that is collected onchain + offchain, and discussed and analyzed offchain (i.e. on a forum). - -A sequencer must aggregate BLS signatures on slashing proposals and post them to the L1 for slash execution. diff --git a/docs/docs-network/concepts/provers-and-sequencers/_category_.json b/docs/docs-network/concepts/provers-and-sequencers/_category_.json deleted file mode 100644 index 24bb8c8ac104..000000000000 --- a/docs/docs-network/concepts/provers-and-sequencers/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "position": 4, - "collapsible": true, - "collapsed": true, - "label": "Provers and Sequencers" -} - diff --git a/docs/docs-network/concepts/provers-and-sequencers/index.md b/docs/docs-network/concepts/provers-and-sequencers/index.md deleted file mode 100644 index cc05c547bd66..000000000000 --- a/docs/docs-network/concepts/provers-and-sequencers/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_position: 0 -title: Provers and Sequencers -description: Learn about the roles of provers and sequencers on the Aztec network. -draft: true ---- - -## Block Production Overview - -Both sequencing and proving in the Aztec Network are intended to be fully decentralized. - -Sequencers will be chosen via a random election, while provers will be selected by sequencers via an out-of-protocol coordination mechanism. - -The proposers in the first `C=13` slots in epoch `N+1` will accept quotes to prove epoch N from provers. The winning prover will have until the end of epoch `N+1` to produce and submit the proof to L1. - -If you are interested in running a sequencer node or a prover node, you can refer to the [sequencer guide](../../setup/sequencer_management) or [prover guide](../../setup/running_a_prover.md). diff --git a/docs/docs-network/concepts/provers-and-sequencers/sequencer/index.md b/docs/docs-network/concepts/provers-and-sequencers/sequencer/index.md deleted file mode 100644 index 099b0e4f20f5..000000000000 --- a/docs/docs-network/concepts/provers-and-sequencers/sequencer/index.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Sequencer -tags: [protocol, sequencer] -draft: true -description: Understand the role of sequencers in Aztec, how they order transactions and produce blocks. ---- - -The sequencer is a module responsible for creating and publishing new rollup blocks. This involves fetching txs from the P2P pool, ordering them, executing any public functions, running them through the rollup circuits, assembling the L2 block, and posting it to the L1 rollup contract along with any contract deployment public data. - -On every new block assembled, it modifies the world state database to reflect the txs processed, but these changes are only committed once the world state synchronizer sees the new block on L1. - -## Components - -The **block builder** is responsible for assembling an L2 block out of a set of processed transactions (we say a tx has been processed if all its function calls have been executed). This involves running the txs through the base, merge, and rollup circuits, updating the world state trees, and building the L2 block object. - -The **prover** generates proofs for every circuit used. For the time being, no proofs are being actually generated, so the only implementation is an empty one. - -The **publisher** deals with sending L1 transactions to the rollup and contract deployment emitter contracts. It is responsible for assembling the Ethereum tx, choosing reasonable gas settings, and monitoring the tx until it gets mined. Note that the current implementation does not handle unstable network conditions (gas price spikes, reorgs, etc). - -The **public processor** executes any public function calls in the transactions. Unlike private function calls, which are resolved in the client, public functions require access to the latest data trees, so they are executed by the sequencer, much like in any non-private L2. - -The **simulator** is an interface to the wasm implementations of the circuits used by the sequencer. - -The **sequencer** pulls txs from the P2P pool, orchestrates all the components above to assemble and publish a block, and updates the world state database. - -## Circuits - -What circuits does the sequencer depend on? - -The **public circuit** is responsible for proving the execution of Brillig (public function bytecode). At the moment, we are using a fake version that actually runs ACIR (intermediate representation for private functions) and does not emit any proofs. - -The **public kernel circuit** then validates the output of the public circuit, and outputs a set of changes to the world state in the same format as the private kernel circuit, meaning we get a standard representation for all txs, regardless of whether public or private functions (or both) were run. The kernel circuits are run iteratively for every recursive call in the transaction. - -The **base rollup circuit** aggregates the changes from two txs (more precisely, the outputs from their kernel circuits once all call stacks are emptied) into a single output. - -The **merge rollup circuit** aggregates two outputs from base rollup circuits into a single one. This circuit is executed recursively until only two outputs are left. This setup means that an L2 block needs to contain always a power-of-two number of txs; if there are not enough, then empty txs are added. - -The **root rollup circuit** consumes two outputs from base or merge rollups and outputs the data to assemble an L2 block. The L1 rollup contract then verifies the proof from this circuit, which implies that all txs included in it were correct. - -## Source code - -You can view the current implementation on Github [here](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/sequencer-client). - -## Further Reading - -- [Sequencer Selection](sequencer_selection.md) diff --git a/docs/docs-network/concepts/provers-and-sequencers/sequencer/sequencer_selection.md b/docs/docs-network/concepts/provers-and-sequencers/sequencer/sequencer_selection.md deleted file mode 100644 index f325bbae91be..000000000000 --- a/docs/docs-network/concepts/provers-and-sequencers/sequencer/sequencer_selection.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Sequencer Selection -tags: [protocol, sequencer] -draft: true -description: Learn about the sequencer selection mechanism in Aztec and how sequencers are chosen for block production. ---- - -## Fernet - -_A protocol for random sequencer selection for the Aztec Network. Prior versions:_ - -- [Fernet 52 (Aug 2023)](https://hackmd.io/0cI_xVsaSVi7PToCJ9A2Ew?view) -- [Sequencer Selection: Fernet (Jun 2023)](https://hackmd.io/0FwyoEjKSUiHQsmowXnJPw?both) -- [Sequencer Selection: Fernet (Jun 2023, Forum)](https://discourse.aztec.network/t/proposal-sequencer-selection-fernet/533) - -## Introduction - -_Fair Election Randomized Natively on Ethereum Trustlessly_ (**Fernet**) is a protocol for random _sequencer_ selection. In each iteration, it relies on a VRF to assign a random score to each sequencer in order to rank them. The sequencer with the highest score can propose an ordering for transactions and the block they build upon, and then reveal its contents for the chain to advance under soft finality. _Provers_ must then assemble a proof for this block and submit it to L1 for the block to be finalized. - -## Staking - -Sequencers are required to stake on L1 in order to participate in the protocol. Each sequencer registers a public key when they stake, which will be used to verify their VRF submission. After staking, a sequencer needs to wait for an activation period of N L1 blocks until they can start proposing new blocks. Unstaking also requires a delay to allow for slashing of dishonest behavior. - -## Randomness - -We use a verifiable random function to rank each sequencer. We propose a SNARK of a hash over the sequencer private key and a public input, borrowing [this proposal from the Espresso team](https://discourse.aztec.network/t/proposal-sequencer-selection-irish-coffee/483#vrf-specification-4). The public input is the current block number and a random beacon value from RANDAO. The value sourced from RANDAO should be old enough to prevent L1 reorgs from affecting sequencer selection on L2. This approach allows each individual proposer to secretly calculate the likelihood of being elected for a given block with enough anticipation. - -Alternatively, we can compute the VRF over the _public_ key of each sequencer. This opens the door to DoS attacks, since the leader for each block becomes public in advance, but it also provides clarity to all sequencers as to who the expected leader is, and facilitates off-protocol PBS. - -## Protocol phases - -Each block goes through three main phases in L1: proposal, reveal, and proving. Transactions can achieve soft finality at the end of the reveal phase. - -![](https://hackmd.io/_uploads/SyReMn1An.png) - -### Proposal phase - -During the initial proposal phase, proposers submit to L1 a **block commitment**, which includes a commitment to the transaction ordering in the proposed block, the previous block being built upon, and any additional metadata required by the protocol. - -**Block commitment contents:** - -- Hash of the ordered list of transaction identifiers for the block (with an optional salt). -- Identifier of the previous block in the chain. -- The output of the VRF for this sequencer. - -At the end of the proposal phase, the sequencer with the highest score submitted becomes the leader for this cycle, and has exclusive rights to decide the contents of the block. Note that this plays nicely with private mempools, since having exclusive rights allows the leader to disclose private transaction data in the reveal phase. - -> _In the original version of Fernet, multiple competing proposals could enter the proving phase. Read more about the rationale for this change [here](https://hackmd.io/0cI_xVsaSVi7PToCJ9A2Ew?both#Mitigation-Elect-single-leader-after-proposal-phase)._ - -### Reveal phase - -The sequencer with the highest score in the proposal phase must then upload the block contents to either L1 or a verifiable DA layer. This guarantees that the next sequencer will have all data available to start building the next block, and clients will have the updated state to create new txs upon. It should be safe to assume that, in the happy path, this block would be proven and become final, so this provides early soft finality to transactions in the L2. - -> _This phase is a recent addition and a detour from the original version of Fernet. Read more about the rationale for this addition [here](https://hackmd.io/0cI_xVsaSVi7PToCJ9A2Ew?both#Mitigation-Block-reveal-phase)._ - -Should the leading sequencer fail to reveal the block contents, we flag that block as skipped, and the next sequencer is expected to build from the previous one. We could consider this to be a slashing condition for the sequencer. - -![](https://hackmd.io/_uploads/B1njcnJCn.png) - -### Proving phase - -During this phase, provers work to assemble an aggregated proof of the winning block. Before the end of this phase, it is expected for the block proof to be published to L1 for verification. - -> Prover selection is still being worked on and out of scope of this sequencer selection protocol. - -Once the proof for the winning block is submitted to L1, the block becomes final, assuming its parent block in the chain is also final. This triggers payouts to sequencer and provers (if applicable depending on the proving network design). - -**Canonical block selection:** - -- Has been proven during the proving phase. -- Its contents have been submitted to the DA layer in the reveal phase. -- It had the highest score on the proposal phase. -- Its referenced previous block is also canonical. - -## Next block - -The cycle for block N+1 (ie from the start of the proposal phase until the end of the proving phase) can start at the end of block N reveal phase, where the network has all data available on L1 or a DA to construct the next block. - -![](https://hackmd.io/_uploads/SJbPKJe0n.png) - -The only way to trigger an L2 reorg (without an L1 one) is if block N is revealed but doesn't get proven. In this case, all subsequent blocks become invalidated and the chain needs to restart from block N-1. - -![](https://hackmd.io/_uploads/HkMDHxxC2.png) - -To mitigate the effect of wasted effort by all sequencers from block N+1 until the reorg, we could implement uncle rewards for these sequencers. And if we are comfortable with slashing, take those rewards out of the pocket of the sequencer that failed to finalize their block. - -## Batching - -> _Read more approaches to batching [here](https://hackmd.io/0cI_xVsaSVi7PToCJ9A2Ew?both#Batching)._ - -As an extension to the protocol, we can bake in batching of multiple blocks. Rather than creating one proof per block, we can aggregate multiple blocks into a single proof, in order to amortize the cost of verifying the root rollup ZKP on L1, thus reducing fees. - -The tradeoff in batching is delayed finalization: if we are not posting proofs to L1 for every block, then the network needs to wait until the batch proof is submitted for finalization. This can also lead to deeper L2 reorgs. - -In a batching model, proving for each block happens immediately as the block is revealed, same as usual. But the resulting proof is not submitted to L1: instead, it is aggregated into the proof of the next block. - -![](https://hackmd.io/_uploads/H1Y61ABJT.png) - -Here all individual block proofs are valid as candidates to finalize the current batch. This opens the door to dynamic batch sizes, so the proof could be verified on L1 when it's economically convenient. - -## Resources - -- [Excalidraw diagrams](https://excalidraw.com/#json=DZcYDUKVImApNjj17KhAf,fMbieqJpOysX9obVitUDEA) diff --git a/docs/docs-network/index.md b/docs/docs-network/index.md index 0bc07d4de2fa..b7a53fa897da 100644 --- a/docs/docs-network/index.md +++ b/docs/docs-network/index.md @@ -1,91 +1,53 @@ --- -id: index -sidebar_position: 0 -title: Introduction -description: Learn about the Aztec network, node types, roles, best practices, and how to participate in the network. +title: The Aztec Network +description: Learn about and participate in the Aztec network - a decentralized privacy-focused rollup on Ethereum. +hide_table_of_contents: true --- -## Overview +import Link from '@docusaurus/Link'; +import useBaseUrl from '@docusaurus/useBaseUrl'; -The Aztec network is a decentralized privacy-focused rollup on Ethereum. Network nodes work together to process transactions, maintain state, and generate proofs that ensure rollup integrity. This guide provides an overview of node types, their roles, best practices, and how to get started. +# The Aztec Network -## Actors and Roles +The Aztec network is a decentralized privacy-focused rollup on Ethereum. Network participants work together to process transactions, maintain state, generate proofs, and govern the protocol. -The Aztec network consists of several types of actors, each serving a specific purpose: +Choose your path based on how you want to engage with the network: -### Full Nodes +
-Full nodes provide users with the ability to connect and interact with the network. They maintain a complete copy of the blockchain state and allow users to send and receive transactions without relying on third parties. +
+

Operate

+

Run network infrastructure: full nodes, sequencers, provers. Set up monitoring and manage your validator.

+Run infrastructure → +
-**Key responsibilities:** -- Maintain synchronized copy of the blockchain state -- Provide RPC interface for transaction submission -- Validate and relay transactions -- Offer privacy-preserving interaction with the network +
+

Participate

+

Stake tokens, delegate to operators, vote on governance proposals, and help shape the future of Aztec.

+Get started as a participant → +
-[Learn more about running a full node →](./setup/running_a_node.md) +
+

Concepts

+

Understand how the network works: architecture, proof of stake, governance, and the contracts that power Aztec.

+Learn the fundamentals → +
-### Sequencer Nodes +
-Sequencer nodes order transactions and produce blocks. Selected via a proof-of-stake mechanism, they play a critical role in the consensus process. +## Quick Links -**Key responsibilities:** -- Assemble unprocessed transactions and propose new blocks -- Execute public functions in transactions -- Attest to correct execution when part of the sequencer committee -- Submit successfully attested blocks to L1 +### For Token Holders +- Stake your tokens to participate in network security +- Delegate to operators if you don't want to run infrastructure +- Vote on proposals to influence protocol upgrades -Before publication, blocks must be validated by a committee of sequencer nodes who re-execute public transactions and verify private function proofs. Committee members attest to validity by signing the block header. Once sufficient attestations are collected (two-thirds of the committee plus one), the block can be submitted to L1. +### For Operators +- Run a full node to interact with the network +- Become a sequencer to produce blocks and earn rewards +- Set up monitoring to keep your infrastructure healthy -[Learn more about running a sequencer →](./setup/sequencer_management.md) - -### Provers - -Provers generate cryptographic proofs that attest to transaction correctness. They produce the final rollup proof submitted to Ethereum, ensuring rollup integrity. - -**Key components and responsibilities:** -- **Prover node**: Polls L1 for unproven epochs, creates prover jobs, and submits final proofs -- **Prover broker**: Manages job queues and distributes work to agents -- **Prover agents**: Execute proof generation jobs in a stateless manner - -Note that running provers require: -- High-performance hardware (typically data center-grade) -- Significant computational resources for proof generation -- Technical expertise in operating distributed systems - -[Learn more about running a prover →](./setup/running_a_prover.md) - -## How Nodes Work Together - -The Aztec network operates through the coordinated interaction of these different node types: - -1. **Transaction Flow**: Users submit transactions to full nodes, which validate and propagate them through the P2P network -2. **Block Production**: Sequencer nodes collect transactions from the mempool, order them, and propose new blocks -3. **Consensus**: The sequencer committee validates proposed blocks and provides attestations -4. **Proof Generation**: Prover nodes generate cryptographic proofs for epochs of blocks -5. **L1 Submission**: Sequencers submit attested blocks and provers submit epoch proofs to Ethereum - -## Using Your Own L1 Node - -For optimal performance and reliability, it's highly recommended to run your own Ethereum L1 node rather than relying on third-party RPC providers. - -**Benefits:** -- Better performance and lower latency -- No rate limiting or request throttling -- Greater reliability and uptime control -- Enhanced privacy for your node operations - -**Requirements:** -- Access to both execution and consensus client endpoints -- Endpoints must support high throughput -- Must be connected to Sepolia testnet for Aztec testnet - -See [Eth Docker's guide](https://ethdocker.com/Usage/QuickStart) for setting up your own L1 node. - -## Next Steps - -- **Check Prerequisites**: Review the [prerequisites guide](./prerequisites.md) to ensure you have everything needed -- **Run a Full Node**: Follow the [complete full node guide](./setup/running_a_node.md) for detailed setup instructions -- **Operate a Sequencer**: Learn how to [run a sequencer node](./setup/sequencer_management.md) and join the validator set -- **Operate a Prover**: Set up [prover infrastructure](./setup/running_a_prover.md) to generate rollup proofs -- **Join the Community**: Connect with other operators on [Discord](https://discord.gg/aztec) +### Understanding the Network +- How block production works +- Proof of stake mechanism +- Governance and upgrades diff --git a/docs/docs-network/operation/_category_.json b/docs/docs-network/operation/_category_.json deleted file mode 100644 index 2bf7015f1f6f..000000000000 --- a/docs/docs-network/operation/_category_.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "position": 6, - "collapsible": true, - "collapsed": false, - "label": "Operation" -} diff --git a/docs/docs-network/operation/sequencer_management/_category_.json b/docs/docs-network/operation/sequencer_management/_category_.json deleted file mode 100644 index b4c6f72d1de9..000000000000 --- a/docs/docs-network/operation/sequencer_management/_category_.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "label": "Sequencer Management", - "position": 2, - "collapsible": true, - "collapsed": false -} diff --git a/docs/docs-network/operators/index.md b/docs/docs-network/operators/index.md new file mode 100644 index 000000000000..a5f864965bc1 --- /dev/null +++ b/docs/docs-network/operators/index.md @@ -0,0 +1,55 @@ +--- +title: Operator Guides +description: Run Aztec network infrastructure - nodes, sequencers, provers, and monitoring. +displayed_sidebar: operatorsSidebar +--- + +# Operating Aztec Infrastructure + +This section covers everything you need to run and maintain Aztec network infrastructure. Whether you're running a full node for personal use or operating a professional sequencer, you'll find the guides you need here. + +## Getting Started + +1. Review the [Prerequisites](./prerequisites.md) to ensure you have the necessary hardware and software +2. [Run a Full Node](./setup/running-a-node.md) - the foundation for all other roles +3. Choose your path: [Sequencer](./setup/sequencer-setup.md) or [Prover](./setup/running-a-prover.md) + +## Roles + +### Full Node Operator +Run a node to interact with the network, submit transactions, and maintain a copy of the state. +- [Running a Node](./setup/running-a-node.md) +- [Syncing Best Practices](./setup/syncing-best-practices.md) + +### Sequencer Operator +Produce blocks, participate in consensus, and earn rewards. +- [Sequencer Setup](./setup/sequencer-setup.md) +- [Registration](./setup/registering-sequencer.md) +- [High Availability](./setup/high-availability.md) +- [Governance Participation](./sequencer-management/governance-participation.md) + +### Prover Operator +Generate cryptographic proofs for the network. +- [Running a Prover](./setup/running-a-prover.md) + +### Staking Provider +Accept delegated stake and operate sequencers on behalf of token holders. +- [Becoming a Staking Provider](./setup/staking-provider.md) + +## Operations + +- [Monitoring](./monitoring/index.md) - Set up observability for your infrastructure +- [Keystore Management](./keystore/index.md) - Secure key handling +- [Sequencer Management](./sequencer-management/index.md) - Day-to-day operations + +## Reference + +- [CLI Reference](./reference/cli-reference.md) +- [Node API Reference](./reference/node-api-reference.md) +- [Changelog](./reference/changelog/index.md) + +--- + +:::info Conceptual Background +For background on how the network works, see [Network Concepts](../concepts/index.md). +::: diff --git a/docs/docs-network/operation/keystore/advanced_patterns.md b/docs/docs-network/operators/keystore/advanced-patterns.md similarity index 94% rename from docs/docs-network/operation/keystore/advanced_patterns.md rename to docs/docs-network/operators/keystore/advanced-patterns.md index aea97edde5bf..0e83c71dceaf 100644 --- a/docs/docs-network/operation/keystore/advanced_patterns.md +++ b/docs/docs-network/operators/keystore/advanced-patterns.md @@ -81,7 +81,7 @@ All publisher accounts must be funded with ETH. Monitor balances to avoid missed Run multiple sequencer identities in a single node. This is useful when you operate multiple sequencers but want to consolidate infrastructure. :::info High Availability Across Nodes -If you want to run the **same** sequencer across multiple nodes for redundancy and high availability, see the [High Availability Sequencers guide](../../setup/high_availability_sequencers.md). That guide covers running one sequencer identity on multiple physical nodes. +If you want to run the **same** sequencer across multiple nodes for redundancy and high availability, see the [High Availability Sequencers guide](../setup/high-availability.md). That guide covers running one sequencer identity on multiple physical nodes. This section covers running **multiple different sequencer identities** on a single node. ::: @@ -151,7 +151,7 @@ Each sequencer with its own publisher, coinbase, and fee recipient: } ``` -For high availability configurations where you run the same sequencer across multiple nodes, see the [High Availability Sequencers guide](../../setup/high_availability_sequencers.md). +For high availability configurations where you run the same sequencer across multiple nodes, see the [High Availability Sequencers guide](../setup/high-availability.md). ## Infrastructure provider scenarios @@ -279,10 +279,10 @@ After generation, you'll have a keystore with one attester and multiple publishe Each node's keystore will have the **same attester keys** (both ETH and BLS) but a **different publisher key**. -For detailed step-by-step HA setup instructions, see the [High Availability Sequencers guide](../../setup/high_availability_sequencers.md). +For detailed step-by-step HA setup instructions, see the [High Availability Sequencers guide](../setup/high-availability.md). ## Next steps - See [Troubleshooting](./troubleshooting.md) for common issues -- Return to [Key Storage Methods](./storage_methods.md) for more options -- Start with basics at [Creating Keystores](./creating_keystores.md) +- Return to [Key Storage Methods](./storage-methods.md) for more options +- Start with basics at [Creating Keystores](./creating-keystores.md) diff --git a/docs/docs-network/operation/keystore/creating_keystores.md b/docs/docs-network/operators/keystore/creating-keystores.md similarity index 95% rename from docs/docs-network/operation/keystore/creating_keystores.md rename to docs/docs-network/operators/keystore/creating-keystores.md index 7a4000bbe76f..70399cd32106 100644 --- a/docs/docs-network/operation/keystore/creating_keystores.md +++ b/docs/docs-network/operators/keystore/creating-keystores.md @@ -1,6 +1,6 @@ --- id: creating_keystores -sidebar_position: 0 +displayed_sidebar: operatorsSidebar title: Creating Sequencer Keystores description: Learn how to create sequencer keystores for running validators on the Aztec network using the Aztec CLI. --- @@ -213,7 +213,7 @@ Keep `key1_staker_output.json` on your local machine - you'll need it for regist ### Step 5: Start Your Node -Start your sequencer node following the [Sequencer Management guide](../../setup/sequencer_management.md). +Start your sequencer node following the [Sequencer Setup guide](../setup/sequencer-setup.md). When your node starts successfully, you'll see output similar to: @@ -225,7 +225,7 @@ These are your validator attester addresses - they match the addresses shown whe ### Step 6: Register Your Validators -Use the public keystore (`key1_staker_output.json`) to register your validators on the staking dashboard. See [Registering a Sequencer](../../setup/sequencer_management.md#next-steps-registering-your-sequencer) for details. +Use the public keystore (`key1_staker_output.json`) to register your validators on the staking dashboard. See [Registering a Sequencer](../setup/registering-sequencer.md) for details. --- @@ -417,18 +417,18 @@ Now that you've created your keystores: ### For Sequencer Operators 1. **Fund publisher addresses** - At least 0.1 ETH per validator -2. **Set up your node** - See [Sequencer Management](../../setup/sequencer_management.md) +2. **Set up your node** - See [Sequencer Management](../setup/sequencer-setup.md) 3. **Register validators** - Use the public keystore with the staking dashboard 4. **Monitor operations** - Track attestations and publisher balance ### Advanced Configurations -- **[Advanced Keystore Patterns](./advanced_patterns.md)** - Multiple validators, high availability, remote signers -- **[Key Storage Methods](./storage_methods.md)** - Encrypted keystores, HSMs, key management systems +- **[Advanced Keystore Patterns](./advanced-patterns.md)** - Multiple validators, high availability, remote signers +- **[Key Storage Methods](./storage-methods.md)** - Encrypted keystores, HSMs, key management systems - **[Troubleshooting and Best Practices](./troubleshooting.md)** - Common issues, security best practices, and CLI reference ### Getting Help -- Review the [Operator FAQ](../operator_faq.md) for common questions +- Review the [Operator FAQ](../operator-faq.md) for common questions - Join the [Aztec Discord](https://discord.gg/aztec) for operator support -- Check the [CLI reference](../../reference/cli_reference.md) for all available commands +- Check the [CLI reference](../reference/cli-reference.md) for all available commands diff --git a/docs/docs-network/operation/keystore/examples.md b/docs/docs-network/operators/keystore/examples.md similarity index 98% rename from docs/docs-network/operation/keystore/examples.md rename to docs/docs-network/operators/keystore/examples.md index 72ba173bd0c7..382b8da86e0b 100644 --- a/docs/docs-network/operation/keystore/examples.md +++ b/docs/docs-network/operators/keystore/examples.md @@ -316,5 +316,5 @@ Attester (critical) uses remote signer; publishers (operational) use inline keys ## Next steps - See [Troubleshooting](./troubleshooting.md) for common issues -- Return to [Advanced Configuration Patterns](./advanced_patterns.md) for more details -- Review [Key Storage Methods](./storage_methods.md) for storage options +- Return to [Advanced Configuration Patterns](./advanced-patterns.md) for more details +- Review [Key Storage Methods](./storage-methods.md) for storage options diff --git a/docs/docs-network/operation/keystore/index.md b/docs/docs-network/operators/keystore/index.md similarity index 89% rename from docs/docs-network/operation/keystore/index.md rename to docs/docs-network/operators/keystore/index.md index cc4fbb1fb5c9..2e8250435737 100644 --- a/docs/docs-network/operation/keystore/index.md +++ b/docs/docs-network/operators/keystore/index.md @@ -1,6 +1,6 @@ --- id: advanced_keystore_guide -sidebar_position: 2 +displayed_sidebar: operatorsSidebar title: Advanced Keystore Usage description: Learn how to configure keystores with remote signers, mnemonics, JSON V3 keystores, and multiple publishers for enhanced security and flexibility. --- @@ -14,7 +14,7 @@ The keystore manages private keys and addresses for your Aztec sequencer or prov Before proceeding, you should: - Be familiar with running a sequencer or prover node -- Understand the basic keystore structure from the [sequencer setup guide](../../setup/sequencer_management.md) +- Understand the basic keystore structure from the [sequencer setup guide](../setup/sequencer-setup.md) - Have access to appropriate key management infrastructure (if using remote signers) ## Understanding Keystore Roles @@ -56,7 +56,7 @@ Learn about different ways to store and access private keys: - JSON V3 encrypted keystores - BIP44 mnemonic derivation -See [Key Storage Methods](./storage_methods.md) for detailed instructions. +See [Key Storage Methods](./storage-methods.md) for detailed instructions. ### 2. Advanced Configuration Patterns @@ -67,7 +67,7 @@ Explore complex deployment scenarios: - Infrastructure provider configurations - High availability setups -See [Advanced Configuration Patterns](./advanced_patterns.md) for examples. +See [Advanced Configuration Patterns](./advanced-patterns.md) for examples. ### 3. Troubleshooting @@ -82,8 +82,8 @@ See [Troubleshooting](./troubleshooting.md) for solutions. ## Getting Started -**First time creating a keystore?** Start with the [Creating Validator Keystores guide](./creating_keystores.md) to learn how to use the Aztec CLI to generate keystores for sequencers and provers. +**First time creating a keystore?** Start with the [Creating Validator Keystores guide](./creating-keystores.md) to learn how to use the Aztec CLI to generate keystores for sequencers and provers. -Once you have a basic keystore, explore the [Key Storage Methods](./storage_methods.md) guide to understand advanced options like remote signers and encrypted keystores. Then check out [Advanced Configuration Patterns](./advanced_patterns.md) for complex deployment scenarios. +Once you have a basic keystore, explore the [Key Storage Methods](./storage-methods.md) guide to understand advanced options like remote signers and encrypted keystores. Then check out [Advanced Configuration Patterns](./advanced-patterns.md) for complex deployment scenarios. For production deployments, we strongly recommend using remote signers or encrypted keystores instead of inline private keys. diff --git a/docs/docs-network/operation/keystore/storage_methods.md b/docs/docs-network/operators/keystore/storage-methods.md similarity index 99% rename from docs/docs-network/operation/keystore/storage_methods.md rename to docs/docs-network/operators/keystore/storage-methods.md index 7c82e24e4837..abf470e2dde4 100644 --- a/docs/docs-network/operation/keystore/storage_methods.md +++ b/docs/docs-network/operators/keystore/storage-methods.md @@ -221,5 +221,5 @@ Mnemonics are convenient for testing but should be avoided in production. Use re ## Next steps -- Learn about [Advanced Configuration Patterns](./advanced_patterns.md) +- Learn about [Advanced Configuration Patterns](./advanced-patterns.md) - See [Troubleshooting](./troubleshooting.md) if you encounter issues diff --git a/docs/docs-network/operation/keystore/troubleshooting.md b/docs/docs-network/operators/keystore/troubleshooting.md similarity index 95% rename from docs/docs-network/operation/keystore/troubleshooting.md rename to docs/docs-network/operators/keystore/troubleshooting.md index 48667b0730ae..53556038b5d4 100644 --- a/docs/docs-network/operation/keystore/troubleshooting.md +++ b/docs/docs-network/operators/keystore/troubleshooting.md @@ -342,7 +342,7 @@ For production, consider: - **Encrypted keystores** with password protection - **Key management systems** (HashiCorp Vault, AWS Secrets Manager) -See [Key Storage Methods](./storage_methods.md) for advanced security patterns. +See [Key Storage Methods](./storage-methods.md) for advanced security patterns. ## CLI Reference @@ -399,9 +399,9 @@ aztec validator-keys staker \ If you encounter issues not covered here: -- Review the [Operator FAQ](../operator_faq.md) for common questions +- Review the [Operator FAQ](../operator-faq.md) for common questions - Join the [Aztec Discord](https://discord.gg/aztec) for operator support -- Check the [CLI reference](../../reference/cli_reference.md) for all available commands +- Check the [CLI reference](../reference/cli-reference.md) for all available commands - Review node logs for specific error messages (redact private keys!) - When asking for help, provide: - Error messages (with private keys redacted) @@ -410,7 +410,7 @@ If you encounter issues not covered here: ## Related Documentation -- **[Creating Keystores](./creating_keystores.md)** - Main guide for generating keystores -- **[Advanced Keystore Patterns](./advanced_patterns.md)** - Multiple validators, high availability, remote signers -- **[Key Storage Methods](./storage_methods.md)** - Encrypted keystores, HSMs, key management systems -- **[Sequencer Management](../../setup/sequencer_management.md)** - Operational guidance for running sequencers +- **[Creating Keystores](./creating-keystores.md)** - Main guide for generating keystores +- **[Advanced Keystore Patterns](./advanced-patterns.md)** - Multiple validators, high availability, remote signers +- **[Key Storage Methods](./storage-methods.md)** - Encrypted keystores, HSMs, key management systems +- **[Sequencer Management](../setup/sequencer-setup.md)** - Operational guidance for running sequencers diff --git a/docs/docs-network/operation/grafana_setup.md b/docs/docs-network/operators/monitoring/grafana-setup.md similarity index 97% rename from docs/docs-network/operation/grafana_setup.md rename to docs/docs-network/operators/monitoring/grafana-setup.md index eb8eb4b5ce49..252116dd83d8 100644 --- a/docs/docs-network/operation/grafana_setup.md +++ b/docs/docs-network/operators/monitoring/grafana-setup.md @@ -9,7 +9,7 @@ Grafana provides visualization and alerting for your metrics, allowing you to cr ## Prerequisites -- Completed [Prometheus Setup](./prometheus_setup.md) +- Completed [Prometheus Setup](./prometheus-setup.md) - Prometheus running and accessible at `http://prometheus:9090` ## Setup Steps @@ -165,6 +165,6 @@ Alert if peer count drops too low: ## Next Steps -- Explore the [Monitoring Overview](./monitoring.md) for troubleshooting and metrics reference +- Explore the [Monitoring Overview](./) for troubleshooting and metrics reference - Join the [Aztec Discord](https://discord.gg/aztec) to share dashboards with the community - Configure additional notification channels for your alerts diff --git a/docs/docs-network/operation/monitoring.md b/docs/docs-network/operators/monitoring/index.md similarity index 78% rename from docs/docs-network/operation/monitoring.md rename to docs/docs-network/operators/monitoring/index.md index 9f9d2459f58c..62b0f780faf2 100644 --- a/docs/docs-network/operation/monitoring.md +++ b/docs/docs-network/operators/monitoring/index.md @@ -1,5 +1,5 @@ --- -sidebar_position: 0 +displayed_sidebar: operatorsSidebar id: monitoring title: Monitoring and Observability description: Learn how to monitor your Aztec node with metrics, OpenTelemetry, Prometheus, and Grafana. @@ -27,11 +27,11 @@ Your Aztec node exports metrics to the OpenTelemetry Collector, which processes Follow these guides in order to set up your complete monitoring stack: -1. [OpenTelemetry Collector Setup](./otel_setup.md) - Configure OTEL to receive metrics from your node -2. [Prometheus Setup](./prometheus_setup.md) - Set up Prometheus to store and query metrics -3. [Grafana Setup](./grafana_setup.md) - Configure Grafana for visualization and alerting -4. [Key Metrics Reference](./metrics_reference.md) - Understand the metrics your node exposes and create custom dashboards -5. [Complete Example and Troubleshooting](./monitoring_example_troubleshooting.md) - Full Docker Compose configuration and troubleshooting help +1. [OpenTelemetry Collector Setup](./otel-setup.md) - Configure OTEL to receive metrics from your node +2. [Prometheus Setup](./prometheus-setup.md) - Set up Prometheus to store and query metrics +3. [Grafana Setup](./grafana-setup.md) - Configure Grafana for visualization and alerting +4. [Key Metrics Reference](./metrics-reference.md) - Understand the metrics your node exposes and create custom dashboards +5. [Complete Example and Troubleshooting](./troubleshooting.md) - Full Docker Compose configuration and troubleshooting help ## Available Metrics Overview @@ -46,16 +46,16 @@ Your node exposes metrics in these categories: - **Prover Metrics**: Job queue, proof generation, and agent utilization (prover nodes only) - **System Metrics**: CPU, memory, disk I/O, and network bandwidth -For detailed information about each metric, PromQL queries, and dashboard creation, see the [Key Metrics Reference](./metrics_reference.md). +For detailed information about each metric, PromQL queries, and dashboard creation, see the [Key Metrics Reference](./metrics-reference.md). ## Next Steps Once your monitoring stack is running: -- Review the [Key Metrics Reference](./metrics_reference.md) to understand available metrics and PromQL queries +- Review the [Key Metrics Reference](./metrics-reference.md) to understand available metrics and PromQL queries - Set up alerting rules in Prometheus for critical conditions - Create custom dashboards tailored to your operational needs - Configure notification channels (Slack, PagerDuty, email) in Grafana - Join the [Aztec Discord](https://discord.gg/aztec) to share dashboards with the community -For troubleshooting common monitoring issues, see the [Complete Example and Troubleshooting](./monitoring_example_troubleshooting.md) guide. +For troubleshooting common monitoring issues, see the [Troubleshooting](./troubleshooting.md) guide. diff --git a/docs/docs-network/operation/metrics_reference.md b/docs/docs-network/operators/monitoring/metrics-reference.md similarity index 98% rename from docs/docs-network/operation/metrics_reference.md rename to docs/docs-network/operators/monitoring/metrics-reference.md index 2e65e415e3fd..ed3f4d3a8176 100644 --- a/docs/docs-network/operation/metrics_reference.md +++ b/docs/docs-network/operators/monitoring/metrics-reference.md @@ -13,7 +13,7 @@ Once your monitoring stack is running, you can discover available metrics in the ## Prerequisites -- Complete monitoring stack setup following the [Monitoring Overview](./monitoring.md) +- Complete monitoring stack setup following the [Monitoring Overview](./) - Ensure Prometheus is running and scraping metrics from your OTEL collector - Verify access to Prometheus UI at `http://localhost:9090` @@ -386,7 +386,7 @@ Track network throughput: ## Creating Dashboards in Grafana -Organize your Grafana dashboards by operational focus to make monitoring efficient and actionable. For specific panel configurations and queries, see the [Grafana Setup](./grafana_setup.md) guide. +Organize your Grafana dashboards by operational focus to make monitoring efficient and actionable. For specific panel configurations and queries, see the [Grafana Setup](./grafana-setup.md) guide. ### Dashboard Organization Strategy @@ -459,6 +459,6 @@ Organize your Grafana dashboards by operational focus to make monitoring efficie - Explore advanced PromQL queries in the [Prometheus documentation](https://prometheus.io/docs/prometheus/latest/querying/basics/) - Set up alerting rules following the [Prometheus alerting guide](https://prometheus.io/docs/alerting/latest/overview/) -- Configure notification channels in [Grafana](./grafana_setup.md) -- Return to [Monitoring Overview](./monitoring.md) +- Configure notification channels in [Grafana](./grafana-setup.md) +- Return to [Monitoring Overview](./) - Join the [Aztec Discord](https://discord.gg/aztec) to share dashboards with the community diff --git a/docs/docs-network/operation/otel_setup.md b/docs/docs-network/operators/monitoring/otel-setup.md similarity index 96% rename from docs/docs-network/operation/otel_setup.md rename to docs/docs-network/operators/monitoring/otel-setup.md index 952553cb95b1..b81ca8d210de 100644 --- a/docs/docs-network/operation/otel_setup.md +++ b/docs/docs-network/operators/monitoring/otel-setup.md @@ -122,5 +122,5 @@ You should see metrics in Prometheus format. ## Next Steps -- Proceed to [Prometheus Setup](./prometheus_setup.md) to configure metric storage and querying -- Return to [Monitoring Overview](./monitoring.md) +- Proceed to [Prometheus Setup](./prometheus-setup.md) to configure metric storage and querying +- Return to [Monitoring Overview](./) diff --git a/docs/docs-network/operation/prometheus_setup.md b/docs/docs-network/operators/monitoring/prometheus-setup.md similarity index 92% rename from docs/docs-network/operation/prometheus_setup.md rename to docs/docs-network/operators/monitoring/prometheus-setup.md index 294e4fa2816e..ee11a5abd409 100644 --- a/docs/docs-network/operation/prometheus_setup.md +++ b/docs/docs-network/operators/monitoring/prometheus-setup.md @@ -9,7 +9,7 @@ Prometheus scrapes and stores the metrics exposed by the OTEL collector, providi ## Prerequisites -- Completed [OpenTelemetry Collector Setup](./otel_setup.md) +- Completed [OpenTelemetry Collector Setup](./otel-setup.md) - OTEL collector running and exposing metrics on port 8889 ## Setup Steps @@ -102,5 +102,5 @@ rate(process_cpu_seconds_total[5m]) ## Next Steps -- Proceed to [Grafana Setup](./grafana_setup.md) to configure visualization and alerting -- Return to [Monitoring Overview](./monitoring.md) +- Proceed to [Grafana Setup](./grafana-setup.md) to configure visualization and alerting +- Return to [Monitoring Overview](./) diff --git a/docs/docs-network/operation/monitoring_example_troubleshooting.md b/docs/docs-network/operators/monitoring/troubleshooting.md similarity index 99% rename from docs/docs-network/operation/monitoring_example_troubleshooting.md rename to docs/docs-network/operators/monitoring/troubleshooting.md index 3e62212b7e73..987558adddcc 100644 --- a/docs/docs-network/operation/monitoring_example_troubleshooting.md +++ b/docs/docs-network/operators/monitoring/troubleshooting.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +displayed_sidebar: operatorsSidebar title: Complete Example and Troubleshooting description: Complete Docker Compose example with all monitoring components and troubleshooting guide for common monitoring issues. --- diff --git a/docs/docs-network/operation/operator_faq.md b/docs/docs-network/operators/operator-faq.md similarity index 96% rename from docs/docs-network/operation/operator_faq.md rename to docs/docs-network/operators/operator-faq.md index bac29e3e7e3c..5b131c7b6f3d 100644 --- a/docs/docs-network/operation/operator_faq.md +++ b/docs/docs-network/operators/operator-faq.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +displayed_sidebar: operatorsSidebar title: FAQs & Common Issues description: Troubleshooting guide for common Aztec node operator issues including sync errors, RPC limits, and update procedures. keywords: [aztec, sequencer, node, validator, setup] @@ -49,7 +49,7 @@ ERROR: world-state:database Call SYNC_BLOCK failed: Error: Can't synch block: bl ``` :::warning Data Loss and Resync -This process removes local state and requires full resynchronization. Consider using snapshot sync mode (`SYNC_MODE=snapshot`) to speed up recovery. See the [syncing best practices guide](../setup/syncing_best_practices.md) for more information. +This process removes local state and requires full resynchronization. Consider using snapshot sync mode (`SYNC_MODE=snapshot`) to speed up recovery. See the [syncing best practices guide](./setup/syncing-best-practices.md) for more information. ::: ### Error Getting Slot Number @@ -168,7 +168,7 @@ Error: Unable to get blob sidecar, Gateway Time-out (504) 4. **Run your own beacon node** (recommended): - Using a third-party beacon endpoint may have rate limits - Running your own provides better reliability and eliminates timeouts - - See the [prerequisites guide](../prerequisites.md) for L1 infrastructure setup + - See the [prerequisites guide](./prerequisites.md) for L1 infrastructure setup ## Funding and Resources @@ -347,7 +347,7 @@ CodeError: stream reset - Ensure `KEY_STORE_DIRECTORY` environment variable is set in your `.env` file - Verify the volume mount in `docker-compose.yml` points to the correct directory -For more information on keystore configuration and creation, see the [Creating Validator Keystores guide](./keystore/creating_keystores.md) and the [Advanced Keystore Usage guide](./keystore/index.md). +For more information on keystore configuration and creation, see the [Creating Validator Keystores guide](./keystore/creating-keystores.md) and the [Advanced Keystore Usage guide](./keystore/index.md). ### Docker Container Won't Start @@ -431,6 +431,6 @@ If you've tried the solutions above and are still experiencing issues: ## Next Steps -- Review [monitoring setup](./monitoring.md) to catch issues early with metrics and alerts -- Check the [CLI reference](../reference/cli_reference.md) for all configuration options +- Review [monitoring setup](./monitoring/index.md) to catch issues early with metrics and alerts +- Check the [CLI reference](./reference/cli-reference.md) for all configuration options - Join the [Aztec Discord](https://discord.gg/aztec) for real-time operator support diff --git a/docs/docs-network/prerequisites.md b/docs/docs-network/operators/prerequisites.md similarity index 94% rename from docs/docs-network/prerequisites.md rename to docs/docs-network/operators/prerequisites.md index 6e54c9b74f42..00768d057412 100644 --- a/docs/docs-network/prerequisites.md +++ b/docs/docs-network/operators/prerequisites.md @@ -1,8 +1,7 @@ --- -id: prerequisites -sidebar_position: 1 title: Prerequisites description: Common prerequisites and requirements for running nodes on the Aztec network, including hardware, software, and network configuration. +displayed_sidebar: operatorsSidebar --- ## Overview @@ -126,6 +125,6 @@ If port forwarding isn't properly configured, your node may not be able to parti Once you have met the prerequisites, proceed to set up your desired node type: -- [Run a Full Node →](./setup/running_a_node.md) -- [Run a Sequencer Node →](./setup/sequencer_management) -- [Run a Prover Node →](./setup/running_a_prover.md) +- [Run a Full Node →](./setup/running-a-node.md) +- [Run a Sequencer Node →](./setup/sequencer-setup.md) +- [Run a Prover Node →](./setup/running-a-prover.md) diff --git a/docs/docs-network/reference/changelog/index.md b/docs/docs-network/operators/reference/changelog/index.md similarity index 85% rename from docs/docs-network/reference/changelog/index.md rename to docs/docs-network/operators/reference/changelog/index.md index 57857e8a7836..3da2fe06811d 100644 --- a/docs/docs-network/reference/changelog/index.md +++ b/docs/docs-network/operators/reference/changelog/index.md @@ -1,6 +1,6 @@ --- id: changelog -sidebar_position: 0 +displayed_sidebar: operatorsSidebar title: Changelog description: Comprehensive changelog documenting configuration changes, new features, and breaking changes across Aztec node versions. --- @@ -40,6 +40,6 @@ When upgrading between versions: ## Related resources -- [CLI Reference](../cli_reference.md) - Current command-line options -- [Node API Reference](../node_api_reference.md) - API documentation -- [Ethereum RPC Reference](../ethereum_rpc_reference.md) - L1 RPC usage +- [CLI Reference](../cli-reference.md) - Current command-line options +- [Node API Reference](../node-api-reference.md) - API documentation +- [Ethereum RPC Reference](../ethereum-rpc-reference.md) - L1 RPC usage diff --git a/docs/docs-network/reference/changelog/v2.0.2.md b/docs/docs-network/operators/reference/changelog/v2.0.2.md similarity index 97% rename from docs/docs-network/reference/changelog/v2.0.2.md rename to docs/docs-network/operators/reference/changelog/v2.0.2.md index f91f1eebb27d..90f08e6c89b9 100644 --- a/docs/docs-network/reference/changelog/v2.0.2.md +++ b/docs/docs-network/operators/reference/changelog/v2.0.2.md @@ -52,7 +52,7 @@ Version 2.0.2 introduces significant configuration simplification, an integrated --proverNode.publisherAddresses ($PROVER_PUBLISHER_ADDRESSES) ``` -**Migration**: Create keystore directory, change singular to plural. Use `*_ADDRESSES` for remote signers. See [Advanced Keystore Guide](../../operation/keystore/index.md). +**Migration**: Create keystore directory, change singular to plural. Use `*_ADDRESSES` for remote signers. See [Advanced Keystore Guide](../../keystore/). ### Validator configuration @@ -333,7 +333,7 @@ All rollup constants now derived from L1 contracts: **Solution**: - Check `--proverNode.keyStoreDirectory` ($KEY_STORE_DIRECTORY) is set - Change `--*.publisherPrivateKey` to `--*.publisherPrivateKeys` (plural) -- See [Advanced Keystore Guide](../../operation/keystore/index.md) +- See [Advanced Keystore Guide](../../keystore/) ### World state sync failures (prover) **Solution**: @@ -359,7 +359,7 @@ All rollup constants now derived from L1 contracts: ## Next steps -- [How to Run a Sequencer Node](../../setup/sequencer_management) - Updated setup instructions -- [Advanced Keystore Usage](../../operation/keystore/index.md) - Keystore configuration -- [Ethereum RPC Calls Reference](../ethereum_rpc_reference.md) - Infrastructure requirements +- [How to Run a Sequencer Node](../../setup/sequencer-setup.md) - Updated setup instructions +- [Advanced Keystore Usage](../../keystore/) - Keystore configuration +- [Ethereum RPC Calls Reference](../ethereum-rpc-reference.md) - Infrastructure requirements - [Aztec Discord](https://discord.gg/aztec) - Upgrade support \ No newline at end of file diff --git a/docs/docs-network/reference/cli_reference.md b/docs/docs-network/operators/reference/cli-reference.md similarity index 99% rename from docs/docs-network/reference/cli_reference.md rename to docs/docs-network/operators/reference/cli-reference.md index 92da74e30ecc..9037dd1c0dd9 100644 --- a/docs/docs-network/reference/cli_reference.md +++ b/docs/docs-network/operators/reference/cli-reference.md @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +displayed_sidebar: operatorsSidebar title: Cli Reference description: A reference of the --help output when running aztec start. references: ["yarn-project/aztec/src/cli/aztec_start_options.ts", "yarn-project/aztec/src/cli/cli.ts"] diff --git a/docs/docs-network/reference/ethereum_rpc_reference.md b/docs/docs-network/operators/reference/ethereum-rpc-reference.md similarity index 95% rename from docs/docs-network/reference/ethereum_rpc_reference.md rename to docs/docs-network/operators/reference/ethereum-rpc-reference.md index cc8b63b17cdd..a75fc770f303 100644 --- a/docs/docs-network/reference/ethereum_rpc_reference.md +++ b/docs/docs-network/operators/reference/ethereum-rpc-reference.md @@ -1,6 +1,6 @@ --- id: ethereum_rpc_reference -sidebar_position: 3 +displayed_sidebar: operatorsSidebar title: Ethereum RPC call reference description: A comprehensive reference of Ethereum RPC calls used by different Aztec node components, including archiver, sequencer, prover, and slasher nodes. --- @@ -304,8 +304,8 @@ Look for log entries related to: ## Next steps -- Review [How to Run a Sequencer Node](../setup/sequencer_management) for operational guidance -- Learn about [High Availability Sequencers](../setup/high_availability_sequencers.md) for production redundancy configurations -- Explore [Advanced Keystore Patterns](../operation/keystore/advanced_patterns.md) for complex key management -- Check [Useful Commands](../operation/sequencer_management/useful_commands.md) for monitoring tools +- Review [How to Run a Sequencer Node](../setup/sequencer-setup.md) for operational guidance +- Learn about [High Availability Sequencers](../setup/high-availability.md) for production redundancy configurations +- Explore [Advanced Keystore Patterns](../keystore/advanced-patterns.md) for complex key management +- Check [Useful Commands](../sequencer-management/useful-commands.md) for monitoring tools - Join the [Aztec Discord](https://discord.gg/aztec) for infrastructure support diff --git a/docs/docs-network/reference/glossary.md b/docs/docs-network/operators/reference/glossary.md similarity index 96% rename from docs/docs-network/reference/glossary.md rename to docs/docs-network/operators/reference/glossary.md index 06e80897d937..dafbf8b24f79 100644 --- a/docs/docs-network/reference/glossary.md +++ b/docs/docs-network/operators/reference/glossary.md @@ -1,6 +1,6 @@ --- id: glossary -sidebar_position: 4 +displayed_sidebar: operatorsSidebar title: Glossary description: A comprehensive glossary of terms used throughout the Aztec network documentation, covering node operations, consensus, cryptography, and infrastructure concepts. --- @@ -289,7 +289,7 @@ The complete state of the Aztec network at a given block height, including all c ## Related Resources -- [Node API Reference](./node_api_reference.md) - Complete API documentation for node JSON-RPC methods -- [Ethereum RPC Reference](./ethereum_rpc_reference.md) - L1 RPC calls used by Aztec components -- [Advanced Keystore Guide](../operation/keystore/index.md) - Detailed keystore configuration options -- [CLI Reference](./cli_reference.md) - Complete command-line interface documentation +- [Node API Reference](./node-api-reference.md) - Complete API documentation for node JSON-RPC methods +- [Ethereum RPC Reference](./ethereum-rpc-reference.md) - L1 RPC calls used by Aztec components +- [Advanced Keystore Guide](../keystore/index.md) - Detailed keystore configuration options +- [CLI Reference](./cli-reference.md) - Complete command-line interface documentation diff --git a/docs/docs-network/reference/node_api_reference.md b/docs/docs-network/operators/reference/node-api-reference.md similarity index 99% rename from docs/docs-network/reference/node_api_reference.md rename to docs/docs-network/operators/reference/node-api-reference.md index cc7f2422d22a..ce1b293a2fd0 100644 --- a/docs/docs-network/reference/node_api_reference.md +++ b/docs/docs-network/operators/reference/node-api-reference.md @@ -1,6 +1,6 @@ --- id: node_api_reference -sidebar_position: 2 +displayed_sidebar: operatorsSidebar title: Node JSON RPC API reference description: Complete reference for the Aztec Node JSON RPC API, including block queries, transaction submission, world state access, and administrative operations. references: ["yarn-project/stdlib/src/interfaces/aztec-node.ts"] @@ -1044,7 +1044,7 @@ docker exec -it aztec-node curl -X POST http://localhost:8880 \ ## Next steps -- [How to Run a Sequencer Node](../setup/sequencer_management) - Set up a node -- [Ethereum RPC Calls Reference](./ethereum_rpc_reference.md) - L1 RPC usage -- [CLI Reference](./cli_reference.md) - Command-line options +- [How to Run a Sequencer Node](../setup/sequencer-setup.md) - Set up a node +- [Ethereum RPC Calls Reference](./ethereum-rpc-reference.md) - L1 RPC usage +- [CLI Reference](./cli-reference.md) - Command-line options - [Aztec Discord](https://discord.gg/aztec) - Developer support diff --git a/docs/docs-network/operation/sequencer_management/claiming_rewards.md b/docs/docs-network/operators/sequencer-management/claiming-rewards.md similarity index 95% rename from docs/docs-network/operation/sequencer_management/claiming_rewards.md rename to docs/docs-network/operators/sequencer-management/claiming-rewards.md index 7afce86abcd7..b9f4dbfacce1 100644 --- a/docs/docs-network/operation/sequencer_management/claiming_rewards.md +++ b/docs/docs-network/operators/sequencer-management/claiming-rewards.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +displayed_sidebar: operatorsSidebar title: Claiming Rewards description: Learn how to claim your sequencer rewards from the Aztec Rollup contract using cast commands. --- @@ -12,9 +12,9 @@ Sequencer rewards accumulate in the Rollup contract but are not automatically di Before proceeding, you should: -- Have a running sequencer that earned rewards (see [Sequencer Setup Guide](../../setup/sequencer_management.md)) +- Have a running sequencer that earned rewards (see [Sequencer Setup Guide](../setup/sequencer-setup.md)) - Have Foundry installed with the `cast` command available ([installation guide](https://book.getfoundry.sh/getting-started/installation)) -- Know your Rollup contract address (see [Useful Commands](./useful_commands.md#get-the-rollup-contract-address)) +- Know your Rollup contract address (see [Useful Commands](./useful-commands.md#get-the-rollup-contract-address)) - Have your sequencer's coinbase address - Have an Ethereum RPC endpoint for the network you're querying @@ -180,7 +180,7 @@ cast call $ROLLUP_ADDRESS "getSequencerRewards(address)" [COINBASE_ADDRESS] --rp 3. Your coinbase address is configured incorrectly **Solutions**: -1. Verify your sequencer is active and proposing blocks (check [monitoring](../monitoring.md)) +1. Verify your sequencer is active and proposing blocks (check [monitoring](../monitoring/index.md)) 2. Check your sequencer logs for block proposals 3. Verify the coinbase address in your sequencer configuration matches the address you're querying 4. Check if blocks you proposed have been proven (rewards are distributed after proof submission) @@ -237,7 +237,7 @@ cast call $ROLLUP_ADDRESS "getSequencerRewards(address)" [COINBASE_ADDRESS] --rp ## Next Steps -- Set up [monitoring](../monitoring.md) to track reward accumulation automatically -- Learn about [delegated stake management](./running_delegated_stake.md) if operating with delegators -- Review [useful commands](./useful_commands.md) for other sequencer queries +- Set up [monitoring](../monitoring/index.md) to track reward accumulation automatically +- Learn about [becoming a staking provider](../setup/staking-provider.md) if operating with delegators +- Review [useful commands](./useful-commands.md) for other sequencer queries - Join the [Aztec Discord](https://discord.gg/aztec) for operator support and community discussions diff --git a/docs/docs-network/operation/sequencer_management/creating_and_voting_on_proposals.md b/docs/docs-network/operators/sequencer-management/governance-participation.md similarity index 93% rename from docs/docs-network/operation/sequencer_management/creating_and_voting_on_proposals.md rename to docs/docs-network/operators/sequencer-management/governance-participation.md index 04faab47712f..f5c0d370635d 100644 --- a/docs/docs-network/operation/sequencer_management/creating_and_voting_on_proposals.md +++ b/docs/docs-network/operators/sequencer-management/governance-participation.md @@ -1,6 +1,6 @@ --- id: creating_and_voting_on_proposals -sidebar_position: 1 +displayed_sidebar: operatorsSidebar title: Governance and Proposal Process description: Learn how to participate in protocol governance as a sequencer, including signaling support, creating proposals, and voting --- @@ -9,12 +9,20 @@ description: Learn how to participate in protocol governance as a sequencer, inc This guide shows you how to participate in protocol governance as a sequencer. You'll learn how to signal support for protocol upgrades, create proposals, and vote on governance decisions that shape the Aztec network. +:::info Conceptual Background +Before diving into the practical steps, you may want to understand the underlying concepts: +- [Governance Overview](../../concepts/governance/index.md) - How the governance system works +- [Proposal Lifecycle](../../concepts/governance/proposal-lifecycle.md) - The stages from signaling to execution +- [Voting](../../concepts/governance/voting.md) - How voting power and delegation work +- [GSE and Stake Mobility](../../concepts/governance/gse.md) - How your stake moves during upgrades +::: + ## Prerequisites Before proceeding, you should: -- Have a running sequencer node (see [Sequencer Setup Guide](../../setup/sequencer_management)) -- Have a basic understanding of Aztec's governance model and voting mechanisms +- Have a running sequencer node (see [Sequencer Setup Guide](../setup/sequencer-setup.md)) +- Understand [how governance works](../../concepts/governance/index.md) ## Understanding Governance Components @@ -319,6 +327,10 @@ After execution, the governance contract performs all actions defined in the pay Monitor proposals closely from the signaling stage through execution. When a vote passes, prepare to upgrade your node software during the execution delay period, so you're ready when the proposal becomes effective. In practice, this often means running multiple nodes, with one node being on the version upgraded from, and one being on the version being upgraded to. +:::tip Stake Mobility +If you deposited with `moveWithLatestRollup = true`, your stake automatically becomes available to the new rollup after an upgrade. If you used `false`, you'll need to manually exit and re-enter. See [GSE and Stake Mobility](../../concepts/governance/gse.md) for details. +::: + ## Troubleshooting ### My Signal Isn't Being Recorded @@ -376,5 +388,5 @@ As a sequencer participating in governance: ## Next Steps -- Learn about [sequencer management](../../setup/sequencer_management) for operating your node +- Learn about [sequencer setup](../setup/sequencer-setup.md) for operating your node - Join the [Aztec Discord](https://discord.gg/aztec) to participate in governance discussions and stay informed about upcoming proposals diff --git a/docs/docs-network/operation/sequencer_management/index.md b/docs/docs-network/operators/sequencer-management/index.md similarity index 81% rename from docs/docs-network/operation/sequencer_management/index.md rename to docs/docs-network/operators/sequencer-management/index.md index d24f718716d2..d019af892812 100644 --- a/docs/docs-network/operation/sequencer_management/index.md +++ b/docs/docs-network/operators/sequencer-management/index.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +displayed_sidebar: operatorsSidebar id: sequencer_management_overview title: Sequencer Management description: Learn how to manage your sequencer operations including governance participation, delegated stake, and contract queries. @@ -13,7 +13,7 @@ Once your sequencer is running, you need to manage its ongoing operations. This Before proceeding, you should: -- Have a running sequencer node (see [Sequencer Setup Guide](../../setup/sequencer_management.md)) +- Have a running sequencer node (see [Sequencer Setup Guide](../setup/sequencer-setup.md)) - Be familiar with basic sequencer operations - Have access to Foundry's `cast` tool for contract queries - Understand your sequencer's role in the network @@ -44,9 +44,9 @@ Learn how to participate in protocol governance: - Executing approved changes - Upgrading your node after governance changes -See [Governance and Proposal Process](./creating_and_voting_on_proposals.md) for detailed instructions. +See [Governance Participation](./governance-participation.md) for detailed instructions. -### 2. Running Delegated Stake +### 2. Running as a Staking Provider If you're operating a sequencer with delegated stake: @@ -56,7 +56,7 @@ If you're operating a sequencer with delegated stake: - Updating provider configuration and commission rates - Monitoring delegator relationships -See [Running Delegated Stake](./running_delegated_stake.md) for setup instructions. +See [Becoming a Staking Provider](../setup/staking-provider.md) for setup instructions. ### 3. Claiming Rewards @@ -67,7 +67,7 @@ Learn how to claim your sequencer rewards: - Claiming rewards to your coinbase address - Troubleshooting common claiming issues -See [Claiming Rewards](./claiming_rewards.md) for detailed instructions. +See [Claiming Rewards](./claiming-rewards.md) for detailed instructions. ### 4. Useful Commands @@ -79,15 +79,15 @@ Essential contract query commands for operators: - Monitoring stake balances and voting power - Troubleshooting common query issues -See [Useful Commands](./useful_commands.md) for a complete reference. +See [Useful Commands](./useful-commands.md) for a complete reference. ## Getting Started -Start with the [Useful Commands](./useful_commands.md) guide to learn how to query your sequencer's status and verify it's operating correctly. This helps you establish a baseline for monitoring. +Start with the [Useful Commands](./useful-commands.md) guide to learn how to query your sequencer's status and verify it's operating correctly. This helps you establish a baseline for monitoring. -If you're participating in governance, review the [Governance and Proposal Process](./creating_and_voting_on_proposals.md) guide to understand how to signal, vote, and execute proposals. +If you're participating in governance, review the [Governance Participation](./governance-participation.md) guide to understand how to signal, vote, and execute proposals. -For operators running with delegated stake, the [Running Delegated Stake](./running_delegated_stake.md) guide walks you through provider registration and management. +For operators running with delegated stake, the [Becoming a Staking Provider](../setup/staking-provider.md) guide walks you through provider registration and management. ## Best Practices @@ -103,7 +103,7 @@ For operators running with delegated stake, the [Running Delegated Stake](./runn ## Next Steps -- Query your sequencer status using the [Useful Commands](./useful_commands.md) -- Learn about [governance participation](./creating_and_voting_on_proposals.md) to vote on protocol changes -- Set up [monitoring](../monitoring.md) to track your sequencer's performance +- Query your sequencer status using the [Useful Commands](./useful-commands.md) +- Learn about [governance participation](./governance-participation.md) to vote on protocol changes +- Set up [monitoring](../monitoring/index.md) to track your sequencer's performance - Join the [Aztec Discord](https://discord.gg/aztec) for operator support and community discussions diff --git a/docs/docs-network/operation/sequencer_management/slashing_and_offenses.md b/docs/docs-network/operators/sequencer-management/slashing-configuration.md similarity index 98% rename from docs/docs-network/operation/sequencer_management/slashing_and_offenses.md rename to docs/docs-network/operators/sequencer-management/slashing-configuration.md index e706f97f1bf2..7ca59950b0e9 100644 --- a/docs/docs-network/operation/sequencer_management/slashing_and_offenses.md +++ b/docs/docs-network/operators/sequencer-management/slashing-configuration.md @@ -1,6 +1,6 @@ --- id: slashing_and_offenses -sidebar_position: 2 +displayed_sidebar: operatorsSidebar title: Slashing and Offenses description: Learn how the slashing mechanism works, what offenses are detected, and how to configure your sequencer to participate in consensus-based slashing --- @@ -13,7 +13,7 @@ This guide explains how the Aztec network's slashing mechanism works and how you Before proceeding, you should: -- Have a running sequencer node (see [Sequencer Setup Guide](../../setup/sequencer_management)) +- Have a running sequencer node (see [Sequencer Setup Guide](../setup/sequencer-setup.md)) - Understand that slashing actions are executed automatically when you propose blocks - Have the Sentinel enabled if you want to detect inactivity offenses @@ -415,6 +415,6 @@ As a sequencer operator: ## Next Steps -- Review [Governance and Proposal Process](./creating_and_voting_on_proposals.md) to understand how slashing parameters can be changed -- Set up [monitoring](../monitoring.md) to track your sequencer's slashing activity +- Review [Governance and Proposal Process](./governance-participation.md) to understand how slashing parameters can be changed +- Set up [monitoring](../monitoring/index.md) to track your sequencer's slashing activity - Join the [Aztec Discord](https://discord.gg/aztec) to discuss slashing behavior and network health with other operators diff --git a/docs/docs-network/operation/sequencer_management/useful_commands.md b/docs/docs-network/operators/sequencer-management/useful-commands.md similarity index 96% rename from docs/docs-network/operation/sequencer_management/useful_commands.md rename to docs/docs-network/operators/sequencer-management/useful-commands.md index 8afba3f6b5f2..9f9390bd9e02 100644 --- a/docs/docs-network/operation/sequencer_management/useful_commands.md +++ b/docs/docs-network/operators/sequencer-management/useful-commands.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +displayed_sidebar: operatorsSidebar title: Useful Commands description: Essential cast commands for querying Registry, Rollup, and Governance contracts as a sequencer operator. --- @@ -15,7 +15,7 @@ If you need help with something not covered here, visit the [Aztec Discord](http Before using these commands, ensure you have: - **Foundry installed** with the `cast` command available ([installation guide](https://book.getfoundry.sh/getting-started/installation)) -- **Aztec CLI tool** installed (see [prerequisites guide](../../prerequisites.md#aztec-toolchain)) +- **Aztec CLI tool** installed (see [prerequisites guide](../prerequisites.md#aztec-toolchain)) - **Ethereum RPC endpoint** (execution layer) for the network you're querying - **Contract addresses** for your deployment (Registry, Rollup, Governance) @@ -334,7 +334,7 @@ cast --to-address 0x000000000000000000000000742d35Cc6634C0532925a3b844Bc9e7595f0 ## Next Steps -- [Learn about sequencer management](../../setup/sequencer_management) to operate your sequencer node -- [Participate in governance](./creating_and_voting_on_proposals.md) by signaling, voting, and creating proposals -- [Monitor your node](../monitoring.md) with metrics and observability tools +- [Learn about sequencer setup](../setup/sequencer-setup.md) to operate your sequencer node +- [Participate in governance](./governance-participation.md) by signaling, voting, and creating proposals +- [Monitor your node](../monitoring/index.md) with metrics and observability tools - Join the [Aztec Discord](https://discord.gg/aztec) for operator support and community discussions diff --git a/docs/docs-network/setup/bootnode_operation.md b/docs/docs-network/operators/setup/bootnode-operation.md similarity index 99% rename from docs/docs-network/setup/bootnode_operation.md rename to docs/docs-network/operators/setup/bootnode-operation.md index 9f05db6a3088..8ae19149afc2 100644 --- a/docs/docs-network/setup/bootnode_operation.md +++ b/docs/docs-network/operators/setup/bootnode-operation.md @@ -1,6 +1,6 @@ --- id: bootnode_operation -sidebar_position: 3 +displayed_sidebar: operatorsSidebar title: Using and running a bootnode description: Learn how to connect to and operate bootnodes for peer discovery in the Aztec network. references: ["yarn-project/aztec/src/cli/cmds/start_p2p_bootstrap.ts"] diff --git a/docs/docs-network/setup/building_from_source.md b/docs/docs-network/operators/setup/building-from-source.md similarity index 97% rename from docs/docs-network/setup/building_from_source.md rename to docs/docs-network/operators/setup/building-from-source.md index 2f0550f620aa..5a87fafdbcfb 100644 --- a/docs/docs-network/setup/building_from_source.md +++ b/docs/docs-network/operators/setup/building-from-source.md @@ -2,7 +2,7 @@ id: building_from_source title: Building Node Software from Source description: Build the Aztec node Docker image from source code for development, testing, or running a specific version. -sidebar_position: 10 +displayed_sidebar: operatorsSidebar --- ## Overview @@ -30,7 +30,7 @@ Building from source allows you to: This guide assumes you're using a standard Linux distribution such as Debian or Ubuntu. While other operating systems may work, these instructions are tested and optimized for Linux environments. -These requirements are for building the software. Running a node has different requirements—see [Running a Full Node](./running_a_node.md). +These requirements are for building the software. Running a node has different requirements—see [Running a Full Node](./running-a-node.md). ## Build Steps @@ -271,7 +271,7 @@ services: # ... rest of configuration ``` -See [Running a Full Node](./running_a_node.md) for complete setup instructions. +See [Running a Full Node](./running-a-node.md) for complete setup instructions. ### Using the CLI @@ -318,7 +318,7 @@ The official CI pipeline follows a similar process. See `.github/workflows/ci3.y ## Next Steps -- Use your custom build to [run a full node](./running_a_node.md) -- Set up [monitoring](../operation/monitoring.md) for your node -- Review the [CLI reference](../reference/cli_reference.md) for configuration options +- Use your custom build to [run a full node](./running-a-node.md) +- Set up [monitoring](../monitoring/index.md) for your node +- Review the [CLI reference](../reference/cli-reference.md) for configuration options - Join the [Aztec Discord](https://discord.gg/aztec) to discuss development and customization diff --git a/docs/docs-network/setup/high_availability_sequencers.md b/docs/docs-network/operators/setup/high-availability.md similarity index 94% rename from docs/docs-network/setup/high_availability_sequencers.md rename to docs/docs-network/operators/setup/high-availability.md index befee207a2e1..01bc47592e63 100644 --- a/docs/docs-network/setup/high_availability_sequencers.md +++ b/docs/docs-network/operators/setup/high-availability.md @@ -1,6 +1,6 @@ --- id: high_availability_sequencers -sidebar_position: 3 +displayed_sidebar: operatorsSidebar title: High Availability Sequencers description: Learn how to run highly available sequencers across multiple nodes for redundancy and improved reliability. --- @@ -21,7 +21,7 @@ High availability means running multiple sequencer nodes that share the same att Before setting up HA sequencers, ensure you have: -- Experience running a single sequencer node (see the [Sequencer Management guide](../setup/sequencer_management.md)) +- Experience running a single sequencer node (see the [Sequencer Setup guide](./sequencer-setup.md)) - Understanding of basic keystore structure and configuration - Access to multiple servers or VMs for running separate nodes - Ability to securely distribute keys across infrastructure @@ -57,7 +57,7 @@ In an HA setup: **HA Setup (2 nodes):** - 2 separate servers/VMs -- Each meeting the minimum sequencer requirements (see [Sequencer Management](./sequencer_management.md)) +- Each meeting the minimum sequencer requirements (see [Sequencer Setup](./sequencer-setup.md)) - Different physical locations or availability zones (recommended) - Reliable network connectivity for both nodes - Access to the same L1 infrastructure (or separate L1 endpoints) @@ -354,17 +354,17 @@ Periodically test your HA setup: - Check file permissions (readable by the node process) - Ensure the keystore path is correct - Validate all private keys are properly formatted -- Review the [Keystore Troubleshooting guide](../operation/keystore/troubleshooting.md) +- Review the [Keystore Troubleshooting guide](../keystore/troubleshooting.md) ## Related Guides :::tip Running Multiple Sequencers Per Node -Want to run multiple sequencer identities on a **single node** instead? See the [Advanced Keystore Patterns guide](../operation/keystore/advanced_patterns.md#multiple-sequencers)—that's a different use case from HA. +Want to run multiple sequencer identities on a **single node** instead? See the [Advanced Keystore Patterns guide](../keystore/advanced-patterns.md#multiple-sequencers)—that's a different use case from HA. ::: ## Next Steps -- Review the [Advanced Keystore Patterns guide](../operation/keystore/advanced_patterns.md) for multiple sequencers per node -- Set up [monitoring and observability](../operation/monitoring.md) for your HA infrastructure -- Learn about [governance participation](../operation/sequencer_management/creating_and_voting_on_proposals.md) as a sequencer +- Review the [Advanced Keystore Patterns guide](../keystore/advanced-patterns.md) for multiple sequencers per node +- Set up [monitoring and observability](../monitoring/index.md) for your HA infrastructure +- Learn about [governance participation](../sequencer-management/governance-participation.md) as a sequencer - Join the [Aztec Discord](https://discord.gg/aztec) for operator support and best practices diff --git a/docs/docs-network/operation/sequencer_management/registering_sequencer.md b/docs/docs-network/operators/setup/registering-sequencer.md similarity index 93% rename from docs/docs-network/operation/sequencer_management/registering_sequencer.md rename to docs/docs-network/operators/setup/registering-sequencer.md index 570689e51a60..cd7cd9d07d89 100644 --- a/docs/docs-network/operation/sequencer_management/registering_sequencer.md +++ b/docs/docs-network/operators/setup/registering-sequencer.md @@ -1,6 +1,6 @@ --- id: registering_sequencer -sidebar_position: 3 +displayed_sidebar: operatorsSidebar title: Registering a Sequencer description: Learn how to register your sequencer on the Aztec network using the staking dashboard for self-staking. --- @@ -10,9 +10,9 @@ description: Learn how to register your sequencer on the Aztec network using the This guide covers registering your sequencer on the Aztec network through the staking dashboard for **self-staking**. This is one of two ways to participate as a sequencer: 1. **Self-staking** (this guide): You provide your own stake via the staking dashboard -2. **Delegated staking**: You receive stake from delegators (see [Running with Delegated Stake](./running_delegated_stake.md)) +2. **Delegated staking**: You receive stake from delegators (see [Running as a Staking Provider](./staking-provider.md)) -Before proceeding, ensure you have completed the [Sequencer Setup Guide](../../setup/sequencer_management.md) and your node is running. +Before proceeding, ensure you have completed the [Sequencer Setup Guide](./sequencer-setup.md) and your node is running. ## Prerequisites @@ -181,7 +181,7 @@ You can verify your sequencers are in the queue at https://dashtec.xyz/queue ### Via Smart Contract -You can also query the status directly using the Rollup contract. See [Monitoring Sequencer Status](../../setup/sequencer_management.md#monitoring-sequencer-status) for detailed instructions. +You can also query the status directly using the Rollup contract. See [Useful Commands](../sequencer-management/useful-commands.md) for detailed instructions. ## Next Steps @@ -194,4 +194,4 @@ After registering your sequencer: ## Alternative: Running with Delegated Stake -If you prefer to run a sequencer backed by delegated stake instead of self-staking, see the [Running with Delegated Stake](./running_delegated_stake.md) guide. +If you prefer to run a sequencer backed by delegated stake instead of self-staking, see the [Becoming a Staking Provider](./staking-provider.md) guide. diff --git a/docs/docs-network/setup/running_a_node.md b/docs/docs-network/operators/setup/running-a-node.md similarity index 95% rename from docs/docs-network/setup/running_a_node.md rename to docs/docs-network/operators/setup/running-a-node.md index b02e6533a9c8..bde9f7c60d34 100644 --- a/docs/docs-network/setup/running_a_node.md +++ b/docs/docs-network/operators/setup/running-a-node.md @@ -1,6 +1,6 @@ --- id: running_a_node -sidebar_position: 2 +displayed_sidebar: operatorsSidebar title: Running a Full Node description: A comprehensive guide on how to run a full node on the Aztec network using Docker Compose. references: ["yarn-project/aztec/src/cli/cmds/start_node.ts"] @@ -25,7 +25,7 @@ These requirements are subject to change as the network throughput increases. **Before proceeding:** Ensure you've reviewed and completed the [prerequisites](../prerequisites.md). -This setup includes only essential settings. The `--network #release_network` flag applies network-specific defaults—see the [CLI reference](../reference/cli_reference.md) for all available configuration options. +This setup includes only essential settings. The `--network #release_network` flag applies network-specific defaults—see the [CLI reference](../reference/cli-reference.md) for all available configuration options. ## Setup @@ -204,7 +204,7 @@ If all checks pass, your node should be up, running, and connected to the networ ## Next Steps -- Review [syncing best practices](./syncing_best_practices.md) for faster synchronization -- Learn about [bootnode operation](./bootnode_operation.md) for peer discovery -- Check the [CLI reference](../reference/cli_reference.md) for advanced configuration options +- Review [syncing best practices](./syncing-best-practices.md) for faster synchronization +- Learn about [bootnode operation](./bootnode-operation.md) for peer discovery +- Check the [CLI reference](../reference/cli-reference.md) for advanced configuration options - Join the [Aztec Discord](https://discord.gg/aztec) for support and community discussions diff --git a/docs/docs-network/setup/running_a_prover.md b/docs/docs-network/operators/setup/running-a-prover.md similarity index 97% rename from docs/docs-network/setup/running_a_prover.md rename to docs/docs-network/operators/setup/running-a-prover.md index 46d0bc1f05e0..21ad39a29b73 100644 --- a/docs/docs-network/setup/running_a_prover.md +++ b/docs/docs-network/operators/setup/running-a-prover.md @@ -1,6 +1,6 @@ --- id: running_a_prover -sidebar_position: 4 +displayed_sidebar: operatorsSidebar title: Running a Prover description: A comprehensive guide on how to run an Aztec prover on the network using Docker Compose in a distributed configuration. references: ["yarn-project/aztec/src/cli/cmds/start_prover_node.ts"] @@ -215,7 +215,7 @@ docker exec -it prover-node curl -X POST http://localhost:8880 \ **Important:** The broker exposes port 8080 via `ports: - ${PROVER_BROKER_PORT}:8080`, making it accessible to external prover agents. Ensure this port is reachable from your agent machines. -This configuration includes only essential settings. The `--network #release_network` flag applies network-specific defaults—see the [CLI reference](../reference/cli_reference.md) for all available configuration options. +This configuration includes only essential settings. The `--network #release_network` flag applies network-specific defaults—see the [CLI reference](../reference/cli-reference.md) for all available configuration options. #### Step 4: Start Node and Broker @@ -373,11 +373,11 @@ docker compose logs -f prover-agent ### Common Issues -See the [Operator FAQ](../operation/operator_faq.md) for additional common issues and resolutions. +See the [Operator FAQ](../operator-faq.md) for additional common issues and resolutions. ## Next Steps - Monitor your prover's performance and proof submission rate - Consider adding more prover agents for increased capacity (either by increasing `PROVER_AGENT_COUNT` or adding more machines) - Join the [Aztec Discord](https://discord.gg/aztec) for operator support -- Review [creating and voting on proposals](../operation/sequencer_management/creating_and_voting_on_proposals.md) for participating in governance +- Review [governance participation](../sequencer-management/governance-participation.md) for participating in governance diff --git a/docs/docs-network/setup/sequencer_management.md b/docs/docs-network/operators/setup/sequencer-setup.md similarity index 95% rename from docs/docs-network/setup/sequencer_management.md rename to docs/docs-network/operators/setup/sequencer-setup.md index 8b157ac8ff7a..b98f5e062b12 100644 --- a/docs/docs-network/setup/sequencer_management.md +++ b/docs/docs-network/operators/setup/sequencer-setup.md @@ -1,6 +1,6 @@ --- id: sequencer_management -sidebar_position: 1 +displayed_sidebar: operatorsSidebar title: Running a Sequencer description: Learn how to manage your sequencer on the Aztec network, including registration, keystore configuration, stake management, and status monitoring. --- @@ -221,7 +221,7 @@ Each identity gets a unique attester address derived from sequential derivation - The same public keystore file (`keyN_staker_output.json`) ::: -For detailed instructions, advanced options, and complete examples, see the [Creating Sequencer Keystores guide](../operation/keystore/creating_keystores.md). +For detailed instructions, advanced options, and complete examples, see the [Creating Sequencer Keystores guide](../keystore/creating-keystores.md). ## Setup with Docker Compose @@ -368,7 +368,7 @@ docker exec -it aztec-sequencer curl -X POST http://localhost:8880 \ ``` ::: -This configuration includes only essential settings. The `--network mainnet` flag applies network-specific defaults—see the [CLI reference](../reference/cli_reference.md) for all available configuration options. +This configuration includes only essential settings. The `--network mainnet` flag applies network-specific defaults—see the [CLI reference](../reference/cli-reference.md) for all available configuration options. ### Step 6: Start the Sequencer @@ -414,7 +414,7 @@ Now that your sequencer node is set up and running, you need to register it with Register your sequencer and provide your own stake through the staking dashboard. This is the most common approach for individual operators. -**→ [Register Your Sequencer (Self-Staking)](../operation/sequencer_management/registering_sequencer.md)** +**→ [Register Your Sequencer (Self-Staking)](./registering-sequencer.md)** You'll use the **public keystore** file (`keyN_staker_output.json`) that was generated when you created your keys. @@ -422,7 +422,7 @@ You'll use the **public keystore** file (`keyN_staker_output.json`) that was gen Operate sequencers backed by tokens from delegators. This non-custodial system allows you to run sequencer infrastructure while delegators provide the economic backing. -**→ [Run with Delegated Stake](../operation/sequencer_management/running_delegated_stake.md)** +**→ [Run as a Staking Provider](./staking-provider.md)** As a provider, you'll register with the Staking Registry and manage a queue of sequencer identities that activate when delegators stake to you. @@ -546,18 +546,18 @@ Information about the exit process will be added when the mechanism is finalized ### Common Issues -See the [Operator FAQ](../operation/operator_faq.md) for additional common issues and resolutions. +See the [Operator FAQ](../operator-faq.md) for additional common issues and resolutions. ## Additional Resources After setting up and registering your sequencer: -- **[Register Your Sequencer](../operation/sequencer_management/registering_sequencer.md)** - Complete registration via staking dashboard +- **[Register Your Sequencer](./registering-sequencer.md)** - Complete registration via staking dashboard - **[Monitor Sequencer Status](#monitoring-sequencer-status)** - Track performance and attestation rate -- **[Operator FAQ](../operation/operator_faq.md)** - Common issues and resolutions -- **[Creating and Voting on Proposals](../operation/sequencer_management/creating_and_voting_on_proposals.md)** - Participate in governance -- **[High Availability Setup](./high_availability_sequencers.md)** - Run your sequencer across multiple nodes for redundancy -- **[Advanced Keystore Patterns](../operation/keystore/advanced_patterns.md)** - Manage multiple sequencer identities +- **[Operator FAQ](../operator-faq.md)** - Common issues and resolutions +- **[Governance Participation](../sequencer-management/governance-participation.md)** - Participate in governance +- **[High Availability Setup](./high-availability.md)** - Run your sequencer across multiple nodes for redundancy +- **[Advanced Keystore Patterns](../keystore/advanced-patterns.md)** - Manage multiple sequencer identities **Community support:** - Join the [Aztec Discord](https://discord.gg/aztec) for operator support and network updates diff --git a/docs/docs-network/operation/sequencer_management/running_delegated_stake.md b/docs/docs-network/operators/setup/staking-provider.md similarity index 99% rename from docs/docs-network/operation/sequencer_management/running_delegated_stake.md rename to docs/docs-network/operators/setup/staking-provider.md index 79b99e81b78a..2fb1dc87a824 100644 --- a/docs/docs-network/operation/sequencer_management/running_delegated_stake.md +++ b/docs/docs-network/operators/setup/staking-provider.md @@ -1,6 +1,6 @@ --- id: become_a_staking_provider -sidebar_position: 2 +displayed_sidebar: operatorsSidebar title: Become a Staking Provider description: Learn how to run a sequencer with delegated stake on the Aztec network, including provider registration and sequencer identity management. --- @@ -15,7 +15,7 @@ This guide covers running a sequencer with delegated stake on the Aztec network. Before proceeding, ensure you have: -- Knowledge of running a sequencer node (see [Sequencer Setup Guide](../../setup/sequencer_management)) +- Knowledge of running a sequencer node (see [Sequencer Setup Guide](./sequencer-setup.md)) - An Ethereum wallet with sufficient ETH for gas fees - Understanding of basic Aztec staking mechanics - Foundry installed for `cast` commands @@ -199,7 +199,7 @@ This command automatically: The public keystore file (`keyN_staker_output.json`) contains the data you'll use for provider registration. -For more details on keystore creation, see the [Sequencer Setup Guide](../../setup/sequencer_management.md#generating-keys). +For more details on keystore creation, see the [Sequencer Setup Guide](./sequencer-setup.md#generating-keys). ### Building the Registration Command @@ -518,7 +518,7 @@ View these metrics on the staking dashboard: ### Confirm Node Operation -Ensure your sequencer nodes are running and synced. See [Useful Commands](./useful_commands.md) for commands to check sequencer status. +Ensure your sequencer nodes are running and synced. See [Useful Commands](../sequencer-management/useful-commands.md) for commands to check sequencer status. ## Troubleshooting diff --git a/docs/docs-network/setup/syncing_best_practices.md b/docs/docs-network/operators/setup/syncing-best-practices.md similarity index 97% rename from docs/docs-network/setup/syncing_best_practices.md rename to docs/docs-network/operators/setup/syncing-best-practices.md index f59f115b6e6c..3931e1cb4f03 100644 --- a/docs/docs-network/setup/syncing_best_practices.md +++ b/docs/docs-network/operators/setup/syncing-best-practices.md @@ -1,6 +1,6 @@ --- id: syncing_best_practices -sidebar_position: 3 +displayed_sidebar: operatorsSidebar title: Using and uploading snapshots description: Learn sync modes and snapshot strategies to efficiently sync your Aztec node with the network. --- @@ -243,7 +243,7 @@ To verify your sync configuration is working: ## Next Steps -- Learn about [running bootnodes](./bootnode_operation.md) for improved peer discovery -- Set up [monitoring](../operation/monitoring.md) to track your node's sync progress -- Check the [CLI reference](../reference/cli_reference.md) for additional sync-related options +- Learn about [running bootnodes](./bootnode-operation.md) for improved peer discovery +- Set up [monitoring](../monitoring/index.md) to track your node's sync progress +- Check the [CLI reference](../reference/cli-reference.md) for additional sync-related options - Join the [Aztec Discord](https://discord.gg/aztec) for sync optimization tips diff --git a/docs/docs-network/setup/_category_.json b/docs/docs-network/setup/_category_.json deleted file mode 100644 index 2bccb9e539ef..000000000000 --- a/docs/docs-network/setup/_category_.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "position": 1, - "collapsible": true, - "collapsed": true, - "label": "Setup" -} diff --git a/docs/docs-network/users/delegation.md b/docs/docs-network/users/delegation.md new file mode 100644 index 000000000000..5a65cdf612f1 --- /dev/null +++ b/docs/docs-network/users/delegation.md @@ -0,0 +1,81 @@ +--- +title: Delegating Stake +description: Learn how to delegate your stake to operators on the Aztec network without running infrastructure. +displayed_sidebar: usersSidebar +--- + +# Delegating Stake + +If you want to participate in staking but don't want to run your own infrastructure, you can delegate your tokens to professional operators who run sequencers on your behalf. + +## Before You Delegate + +Understanding these concepts will help you choose the right operator: + +- [How proof of stake works](../concepts/proof-of-stake/) +- [Slashing conditions](../concepts/proof-of-stake/#slashing) - your delegated stake can be slashed +- [How governance works](../concepts/governance/) - understand voting power + +## How Delegation Works + +When you delegate tokens to an operator: + +1. **Your tokens are staked** through the operator's validator +2. **The operator runs infrastructure** on your behalf +3. **Rewards are shared** between you and the operator based on their fee structure +4. **Slashing risk is shared** - if the operator misbehaves, your delegated stake can be slashed + +## Choosing an Operator + +When selecting an operator to delegate to, consider: + +### Performance Metrics +- **Uptime**: How reliably does the operator maintain their infrastructure? +- **Attestation Rate**: Do they consistently participate in consensus? +- **Slashing History**: Have they been slashed before? + +### Economic Terms +- **Commission Rate**: What percentage of rewards does the operator keep? +- **Minimum Delegation**: Is there a minimum amount required? + +### Reputation +- **Track Record**: How long have they been operating? +- **Community Standing**: Are they known in the Aztec community? +- **Transparency**: Do they communicate openly about their operations? + +## Delegation Process + +:::note Coming Soon +Detailed delegation instructions will be added once the delegation mechanism is fully specified. +::: + +## Managing Your Delegation + +### Monitoring Performance + +Keep track of your delegated stake: +- Check operator uptime and performance +- Monitor for any slashing events +- Review reward distributions + +### Changing Operators + +If you want to switch to a different operator: +1. Initiate undelegation from your current operator +2. Wait for the unbonding period +3. Delegate to your new chosen operator + +## Voting with Delegated Stake + +By default, when you delegate to an operator, they may vote on your behalf in governance decisions. + +To maintain control over your votes: +- Check if the operator allows custom voting preferences +- Consider delegating voting power separately from stake +- See [Voting on Proposals](./voting) for voting options + +## Next Steps + +- [Learn about voting](./voting) with your staked or delegated tokens +- [Understand slashing](../concepts/proof-of-stake/#slashing) to know the risks +- [Run your own validator](../operators/setup/sequencer_management) if you prefer direct control diff --git a/docs/docs-network/users/index.md b/docs/docs-network/users/index.md new file mode 100644 index 000000000000..750a9bbd9a36 --- /dev/null +++ b/docs/docs-network/users/index.md @@ -0,0 +1,36 @@ +--- +title: User Guides +description: Participate in the Aztec network as a token holder - stake, delegate, and vote. +displayed_sidebar: usersSidebar +--- + +# Participating in the Aztec Network + +As a token holder, you can actively participate in the Aztec network without running any infrastructure. This section covers how to stake tokens, delegate to operators, and participate in governance. + +## Guides + +### [Staking Tokens](users/staking) +Stake your tokens to help secure the network and earn rewards. Learn about staking requirements, risks, and how to get started. + +### [Delegating Stake](users/delegation) +If you don't want to run your own infrastructure, you can delegate your stake to professional operators who run sequencers on your behalf. + +### [Voting on Proposals](users/voting) +Use your staked tokens to vote on governance proposals that shape the future of the Aztec protocol. + +--- + +## Before You Start + +Understanding these concepts will help you make informed decisions: + +- [How proof of stake works](concepts/proof-of-stake) +- [Slashing conditions](concepts/proof-of-stake#slashing) - understand the risks +- [How governance works](concepts/governance) + +--- + +:::tip Want to run infrastructure? +If you're interested in operating a node, sequencer, or prover, see the [Operator Guides](operators). +::: diff --git a/docs/docs-network/users/staking.md b/docs/docs-network/users/staking.md new file mode 100644 index 000000000000..e9f2ba187636 --- /dev/null +++ b/docs/docs-network/users/staking.md @@ -0,0 +1,63 @@ +--- +title: Staking Tokens +description: Learn how to stake tokens on the Aztec network to participate in network security and earn rewards. +displayed_sidebar: usersSidebar +--- + +# Staking Tokens + +Staking allows you to participate in securing the Aztec network while earning rewards. This guide explains how staking works and how to get started. + +## Before You Stake + +Understanding these concepts will help you make informed decisions: + +- [How proof of stake works](../concepts/proof-of-stake/) +- [Staking mechanism details](../concepts/proof-of-stake/#staking) +- [Slashing conditions](../concepts/proof-of-stake/#slashing) - understand the risks +- [Reward distribution](../concepts/proof-of-stake/#rewards) + +## Overview + +When you stake tokens on the Aztec network, your tokens are locked in a smart contract and used to secure the network. In return, you earn a share of the network rewards proportional to your stake. + +### Key Concepts + +- **Activation Threshold**: The minimum amount required to become an active validator +- **Staking Period**: Tokens must remain staked for a minimum period before withdrawal +- **Rewards**: Earned based on your stake proportion and network activity +- **Slashing Risk**: Validators who misbehave may have a portion of their stake slashed + +## Staking Options + +### Option 1: Run Your Own Validator + +If you have the technical expertise and infrastructure, you can run your own sequencer node and stake directly. + +**Requirements:** +- Meet the minimum stake threshold +- Run and maintain sequencer infrastructure +- Ensure high availability and proper operation + +See the [Sequencer Setup Guide](../operators/setup/sequencer_management) for details. + +### Option 2: Delegate to an Operator + +If you don't want to run infrastructure, you can delegate your stake to a professional operator. + +See [Delegating Stake](./delegation) for details. + +## Understanding Slashing Risk + +Before staking, understand that your stake can be partially slashed if: +- The validator you stake with (or delegate to) commits protocol violations +- The validator is inactive for extended periods +- The validator proposes or attests to invalid blocks + +See [Slashing Concepts](../concepts/proof-of-stake/#slashing) for detailed information. + +## Next Steps + +- [Delegate your stake](./delegation) if you prefer not to run infrastructure +- [Learn about voting](./voting) to participate in governance with your staked tokens +- [Understand governance](../concepts/governance/) to know how protocol decisions are made diff --git a/docs/docs-network/users/voting.md b/docs/docs-network/users/voting.md new file mode 100644 index 000000000000..8bca909cae36 --- /dev/null +++ b/docs/docs-network/users/voting.md @@ -0,0 +1,126 @@ +--- +title: Voting on Proposals +description: Learn how to vote on governance proposals on the Aztec network using your staked tokens. +displayed_sidebar: usersSidebar +--- + +# Voting on Proposals + +As a token holder with staked tokens, you can vote on governance proposals that shape the future of the Aztec protocol. + +:::info Conceptual Background +Understanding these concepts will help you participate effectively: +- [How governance works](../concepts/governance/) - Overview of the governance system +- [Proposal lifecycle](../concepts/governance/proposal-lifecycle) - The stages from signaling to execution +- [Voting mechanics](../concepts/governance/voting) - How voting power and timestamps work +::: + +## How Voting Works + +### Voting Power + +Your voting power is determined by the amount of tokens you have locked in the Governance contract. Key points: + +- **Locking Required**: You must lock tokens in the Governance contract to activate voting power +- **No Slashing on Votes**: Locked voting tokens are not subject to slashing (unlike staked tokens) +- **Withdrawal Delay**: After voting, there's a delay before you can withdraw tokens to prevent governance attacks + +### Voting Timeline + +Each proposal goes through these stages: + +1. **Signaling** - Sequencers signal support for a payload +2. **Proposal Creation** - Once quorum is reached, the proposal is submitted +3. **Voting Delay** (~12 hours) - Mandatory waiting period for community review +4. **Voting Period** (~24 hours) - Token holders vote on the proposal +5. **Execution Delay** (~12 hours) - Delay before approved proposals execute +6. **Execution** - Anyone can trigger execution of passed proposals + +:::note Testnet Values +These timeline values are specific to testnet and may change for future network phases. +::: + +## Default Voting (Delegated to Rollup) + +If you've staked tokens as a sequencer or delegated to one, your voting power is delegated to the rollup contract by default. This means: + +- The rollup automatically votes "yea" on proposals that reached quorum through sequencer signaling +- **You don't need to take any action** if you support proposals created through normal governance +- If you want to vote differently, you must delegate your voting power to yourself (see below) + +## Custom Voting + +To vote differently from the default, you need to delegate your voting power to an address you control. + +### Step 1: Delegate Voting Power + +Use the Governance Staking Escrow (GSE) contract to delegate to yourself: + +```bash +cast send [GSE_ADDRESS] \ + "delegate(address,address,address)" \ + [ROLLUP_ADDRESS] \ + [YOUR_ATTESTER_ADDRESS] \ + [YOUR_VOTING_ADDRESS] \ + --rpc-url [YOUR_RPC_URL] \ + --private-key [YOUR_WITHDRAWER_PRIVATE_KEY] +``` + +:::warning Timing Matters +You must complete delegation **before** the voting period begins. Voting power is timestamped at the moment a proposal becomes active. +::: + +### Step 2: Cast Your Vote + +Once delegated, vote through the GSE contract: + +```bash +# Vote "yea" +cast send [GSE_ADDRESS] \ + "vote(uint256,uint256,bool)" \ + [PROPOSAL_ID] \ + [AMOUNT] \ + true \ + --rpc-url [YOUR_RPC_URL] \ + --private-key [YOUR_VOTING_PRIVATE_KEY] + +# Vote "nay" (change true to false) +cast send [GSE_ADDRESS] \ + "vote(uint256,uint256,bool)" \ + [PROPOSAL_ID] \ + [AMOUNT] \ + false \ + --rpc-url [YOUR_RPC_URL] \ + --private-key [YOUR_VOTING_PRIVATE_KEY] +``` + +### Step 3: Verify Your Vote + +Check that your vote was recorded: + +```bash +cast call [GOVERNANCE_CONTRACT_ADDRESS] \ + "getProposal(uint256)" [PROPOSAL_ID] \ + --rpc-url [YOUR_RPC_URL] +``` + +## Finding Active Proposals + +To see what proposals are currently up for vote: + +1. Monitor the [Aztec Discord](https://discord.gg/aztec) governance channels +2. Query the Governance contract for active proposals +3. Review proposal details before voting + +## Best Practices + +1. **Research Before Voting**: Always review proposal details and community discussions +2. **Delegate Early**: Complete delegation well before voting opens +3. **Verify Payloads**: For technical proposals, review the payload code on Etherscan +4. **Stay Informed**: Follow governance discussions to understand proposal implications + +## Next Steps + +- [Learn about staking](./staking) to acquire voting power +- [Understand governance concepts](../concepts/governance/) for deeper knowledge +- [Become a sequencer](../operators/setup/sequencer_management) to participate in proposal signaling diff --git a/docs/docs-words.txt b/docs/docs-words.txt index 17ac4904ce4d..408e66901096 100644 --- a/docs/docs-words.txt +++ b/docs/docs-words.txt @@ -367,3 +367,7 @@ whoooaa flamegraphs mycontract notegetteroptions +supermajority +finalise +undelegation +unbonding diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 265425dfdba4..48eccc905c96 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -282,13 +282,13 @@ const config = { label: "Build", }, - // Network sidebar link + // Network portal link { - type: "docSidebar", - sidebarId: "sidebar", + type: "doc", + docId: "index", docsPluginId: "network", position: "left", - label: "Run a node", + label: "Network", }, { to: "/ignition_info", diff --git a/docs/sidebars-network.js b/docs/sidebars-network.js index 1e1571162a5e..26b6af5c1a49 100644 --- a/docs/sidebars-network.js +++ b/docs/sidebars-network.js @@ -1,9 +1,124 @@ // @ts-check -// Sidebar configuration for Network (node operators) documentation +// Sidebar configuration for Network documentation +// Supports three sections: Concepts, Users, and Operators /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ const sidebars = { - sidebar: [ + // ============================================ + // CONCEPTS SIDEBAR + // ============================================ + conceptsSidebar: [ + { + type: "html", + value: '← Back to Network', + className: "sidebar-back-link-wrapper", + }, + { + type: "html", + value: '', + }, + { + type: "html", + value: 'Concepts', + className: "sidebar-title", + }, + { + type: "doc", + id: "concepts/index", + label: "Overview", + }, + { + type: "category", + label: "Network Architecture", + link: { + type: "doc", + id: "concepts/architecture/index", + }, + items: [ + "concepts/architecture/block-production", + "concepts/architecture/proving-coordination", + ], + }, + { + type: "doc", + id: "concepts/proof-of-stake/index", + label: "Proof of Stake", + }, + { + type: "category", + label: "Governance", + link: { + type: "doc", + id: "concepts/governance/index", + }, + items: [ + "concepts/governance/proposal-lifecycle", + "concepts/governance/voting", + "concepts/governance/gse", + "concepts/governance/upgrades", + ], + }, + { + type: "doc", + id: "concepts/contracts/deployment-architecture", + label: "L1 Contracts", + }, + ], + + // ============================================ + // USERS SIDEBAR + // ============================================ + usersSidebar: [ + { + type: "html", + value: '← Back to Network', + className: "sidebar-back-link-wrapper", + }, + { + type: "html", + value: '', + }, + { + type: "html", + value: 'User Guides', + className: "sidebar-title", + }, + { + type: "doc", + id: "users/index", + label: "Overview", + }, + { + type: "doc", + id: "users/staking", + label: "Staking Tokens", + }, + { + type: "doc", + id: "users/delegation", + label: "Delegating Stake", + }, + { + type: "doc", + id: "users/voting", + label: "Voting on Proposals", + }, + ], + + // ============================================ + // OPERATORS SIDEBAR + // IDs match actual doc IDs (mix of underscores from frontmatter and dashes from file paths) + // ============================================ + operatorsSidebar: [ + { + type: "html", + value: '← Back to Network', + className: "sidebar-back-link-wrapper", + }, + { + type: "html", + value: '', + }, { type: "html", value: 'Getting Started', @@ -11,11 +126,12 @@ const sidebars = { }, { type: "doc", - id: "index", + id: "operators/index", + label: "Operator Overview", }, { type: "doc", - id: "prerequisites", + id: "operators/prerequisites", }, { type: "html", @@ -28,37 +144,40 @@ const sidebars = { }, { type: "doc", - id: "setup/running_a_node", + id: "operators/setup/running_a_node", }, { type: "category", label: "Running a Sequencer", link: { type: "doc", - id: "setup/sequencer_management", + id: "operators/setup/sequencer_management", }, items: [ - { - type: "doc", - id: "setup/high_availability_sequencers", - }, + "operators/setup/registering_sequencer", + "operators/setup/become_a_staking_provider", + "operators/setup/high_availability_sequencers", ], }, { type: "doc", - id: "setup/running_a_prover", + id: "operators/setup/running_a_prover", }, { type: "doc", - id: "setup/building_from_source", + id: "operators/setup/building_from_source", }, { type: "doc", - id: "setup/bootnode_operation", + id: "operators/setup/bootnode_operation", }, { type: "doc", - id: "setup/syncing_best_practices", + id: "operators/setup/syncing_best_practices", + }, + { + type: "html", + value: '', }, { type: "html", @@ -70,61 +189,35 @@ const sidebars = { label: "Monitoring", link: { type: "doc", - id: "operation/monitoring", + id: "operators/monitoring/monitoring", }, items: [ { type: "category", label: "Setup Guides", items: [ - { - type: "doc", - id: "operation/otel_setup", - }, - { - type: "doc", - id: "operation/prometheus_setup", - }, - { - type: "doc", - id: "operation/grafana_setup", - }, + "operators/monitoring/otel-setup", + "operators/monitoring/prometheus-setup", + "operators/monitoring/grafana-setup", ], }, - { - type: "doc", - id: "operation/metrics_reference", - }, - { - type: "doc", - id: "operation/monitoring_example_troubleshooting", - }, + "operators/monitoring/metrics-reference", + "operators/monitoring/troubleshooting", ], }, { type: "category", - label: "Keystore Usage", + label: "Keystore Management", link: { type: "doc", - id: "operation/keystore/advanced_keystore_guide", + id: "operators/keystore/advanced_keystore_guide", }, items: [ - { - type: "doc", - id: "operation/keystore/creating_keystores", - }, - { - type: "doc", - id: "operation/keystore/storage_methods", - }, - { - type: "doc", - id: "operation/keystore/advanced_patterns", - }, - { - type: "doc", - id: "operation/keystore/troubleshooting", - }, + "operators/keystore/creating_keystores", + "operators/keystore/storage-methods", + "operators/keystore/advanced-patterns", + "operators/keystore/examples", + "operators/keystore/troubleshooting", ], }, { @@ -132,34 +225,18 @@ const sidebars = { label: "Sequencer Management", link: { type: "doc", - id: "operation/sequencer_management/sequencer_management_overview", + id: "operators/sequencer-management/sequencer_management_overview", }, items: [ - { - type: "doc", - id: "operation/sequencer_management/creating_and_voting_on_proposals", - }, - { - type: "doc", - id: "operation/sequencer_management/slashing_and_offenses", - }, - { - type: "doc", - id: "operation/sequencer_management/become_a_staking_provider", - }, - { - type: "doc", - id: "operation/sequencer_management/claiming_rewards", - }, - { - type: "doc", - id: "operation/sequencer_management/useful_commands", - }, + "operators/sequencer-management/creating_and_voting_on_proposals", + "operators/sequencer-management/slashing_and_offenses", + "operators/sequencer-management/claiming-rewards", + "operators/sequencer-management/useful-commands", ], }, { type: "doc", - id: "operation/operator_faq", + id: "operators/operator-faq", }, { type: "html", @@ -175,30 +252,25 @@ const sidebars = { label: "Changelog", link: { type: "doc", - id: "reference/changelog/changelog", + id: "operators/reference/changelog/changelog", }, - items: [ - { - type: "doc", - id: "reference/changelog/v2.0.2", - }, - ], + items: ["operators/reference/changelog/v2.0.2"], }, { type: "doc", - id: "reference/cli_reference", + id: "operators/reference/cli-reference", }, { type: "doc", - id: "reference/node_api_reference", + id: "operators/reference/node_api_reference", }, { type: "doc", - id: "reference/ethereum_rpc_reference", + id: "operators/reference/ethereum_rpc_reference", }, { type: "doc", - id: "reference/glossary", + id: "operators/reference/glossary", }, ], }; diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index bed4930f20e7..96b9eb00a674 100644 --- a/docs/src/css/custom.css +++ b/docs/src/css/custom.css @@ -444,3 +444,70 @@ html[data-theme="dark"] .sidebar-divider { .dropdown-version-section-header-item:hover { background: none !important; } + +/* ============================================ + NETWORK PORTAL STYLES + ============================================ */ + +/* Portal Grid Layout */ +.portal-grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); + gap: 1.5rem; + margin: 2rem 0; +} + +/* Portal Cards */ +.portal-card { + padding: 1.5rem; + border: 1px solid var(--ifm-color-emphasis-300); + border-radius: 8px; + transition: border-color 0.2s, box-shadow 0.2s; +} + +.portal-card:hover { + border-color: var(--ifm-color-primary); + box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1); +} + +.portal-card h3 { + margin-top: 0; + margin-bottom: 0.75rem; +} + +.portal-card p { + color: var(--ifm-color-emphasis-700); + margin-bottom: 1rem; +} + +.portal-card a { + font-weight: 500; +} + +/* Sidebar Back Link */ +.sidebar-back-link { + display: block; + padding: 0.5rem 0; + margin-bottom: 0.5rem; +} + +.sidebar-back-link a { + color: var(--ifm-color-primary); + text-decoration: none; + font-size: 0.875rem; +} + +.sidebar-back-link a:hover { + text-decoration: underline; +} + +/* Sidebar Subtitle (for "Related Guides" etc.) */ +.sidebar-subtitle { + display: block; + padding: 0.25rem 0; + font-size: 0.75rem; + font-weight: 600; + text-transform: uppercase; + color: var(--ifm-color-emphasis-600); + letter-spacing: 0.05em; +}