📝 add reference to onchain values

Author: koenmtb1

AZIPs/template.md

@@ -60,6 +60,10 @@ The `discussions-to` header will indicate the URL of the GitHub Discussions thre
 
 - *Abstract is a multi-sentence (short paragraph) technical summary. This should be a very terse and human-readable version of the specification section. Someone should be able to read only the abstract to get the gist of what this specification does.*
 
+## Impacted Stakeholders
+
+- *For each stakeholder group affected by this proposal, write a paragraph describing the impact and summarizing any relevant discussions held with that group. Consider: Oracles, Wallets, Block Explorers, RPCs, Intent Bridges, Indexing Protocols, Messaging Bridges, Analytics Platforms, Liquidity Provisioning, Market Making, Co-Snarks, Mobile Wallets, AMMs, Lending Markets, NFTs, Extension Wallets, Token Bridges, Fintech Apps, Gaming, Escrow, Stablecoins, Prediction Markets, Sequencers, Provers.*
+
 ## Motivation
 
 - *A motivation section is required for all AZIPs. It should clearly explain why the existing protocol specification is inadequate to address the problem that the AZIP solves.*

AZUPs/template.md

@@ -81,20 +81,6 @@ The `discussions-to` header will indicate the URL of the GitHub Discussions thre
 
 - *Discuss security implications, potential risks, and how they are being addressed. Include links to the relevant code repository, key contracts or modules, and any verified deployments on explorers so reviewers can inspect the logic themselves.*
 
-## Implementation Timeline
-
-| Phase | Start Date | Estimated Duration | Target / Notes |
-| --- | --- | --- | --- |
-| Community Discussion | [FILL IN] | 3 days | — |
-| Signaling  | [FILL IN] | -  | [Quorum or condition] |
-| Proposal Created | [FILL IN] | [Timing relative to signaling] | — |
-| Proposal Delay | [FILL IN] | 3 days |  |
-| Voting Period | [FILL IN] | 7 days | — |
-| Execution Delay | [FILL IN] | 30 days | — |
-| **Earliest Possible Execution** | [FILL IN] | — | **[Date and time in UTC, if known]** |
-
-*Note: The actual execution date depends on when signaling quorum is reached (if relevant), the proposal passes, and execution occurs.*
-
 ## Open Questions and Feedback
 
 - *Any Open Questions or Requests for Feedback for the Aztec community*

azup-process.md

@@ -53,13 +53,15 @@ Once the payload is deployed, Core Contributors publish a forum post following t
 
 Signaling is an onchain mechanism for sequencers to express coordinated support for a specific upgrade candidate before a formal proposal is created. Sequencers signal support for payloads by configuring their nodes to signal for a specific payload address. A signal can be made for each slot that a sequencer is selected to propose checkpoints. Signaling is separate from checkpoint proposals. Each successful signal increments that payload's support count for the current round.
 
-A payload reaches signaling quorum when it accumulates at least **600 signals within a 1,000-slot round** (60% of the round's total possible signals). Payloads that meet this threshold are eligible to be promoted into formal proposals. Once a payload reaches quorum, it must be promoted to a formal proposal within 5 rounds (`LIFETIME_IN_ROUNDS` in `GovernanceProposer.sol`). If not promoted in time, the quorum expires and signals must be gathered again.
+A payload reaches signaling quorum when it accumulates at least **`QUORUM_SIZE` signals within a `ROUND_SIZE`-slot round** (`GovernanceProposer.sol`). Payloads that meet this threshold are eligible to be promoted into formal proposals. Once a payload reaches quorum, it must be promoted to a formal proposal within `LIFETIME_IN_ROUNDS` (`GovernanceProposer.sol`). If not promoted in time, the quorum expires and signals must be gathered again.
 
 For more on how signaling works, see [sequencer documentation](https://docs.aztec.network/network/operation/sequencer_management/creating_and_voting_on_proposals).
 
 ### Alternative Proposal Path
 
-In addition to the sequencer signaling path, the Governance contract supports an alternative proposal mechanism that bypasses sequencer signaling. This path requires the proposer to lock a significant amount of tokens for an extended period. Once submitted, the proposal follows the same voting and execution process as any other proposal. This mechanism exists as a safeguard in case sequencer signaling is unable to function as intended.
+In addition to the sequencer signaling path, the Governance contract supports an alternative proposal mechanism (`proposeWithLock`) that bypasses sequencer signaling. This path requires the proposer to lock `proposeConfig.lockAmount` tokens for `proposeConfig.lockDelay` (both from `getConfiguration()` in `Governance.sol`). Once submitted, the proposal follows the same voting and execution process as any other proposal. This mechanism exists as a safeguard in case sequencer signaling is unable to function as intended.
+
+The rollup does **not** automatically vote "yea" on proposals submitted via `proposeWithLock`. Sequencers and tokenholders must actively vote to pass these proposals.
 
 ## Voting
 
@@ -79,11 +81,11 @@ At this point, the payload transitions from a “signaled upgrade candidate” t
 
 ### Preparing for the Vote
 
-Following proposal creation, there is a **3-day voting delay** in which the proposal is pending and votes cannot yet be cast. This delay is designed to:
+Following proposal creation, there is a **`votingDelay`** period in which the proposal is pending and votes cannot yet be cast. This delay is designed to:
 
 - Give the community time to review the payload and its implications.
 - Allow node operators to assess operational impact.
-- Allow tokenholders to stake and/or deposit into governance to participate in the upcoming vote. Staking (for running a sequencer) deposits tokens into governance by default and delegates voting power to the rollup (which always votes "yea"). Depositing into governance without staking allows tokenholders to vote directly.
+- Allow tokenholders to stake and/or deposit into governance to participate in the upcoming vote. Staking (for running a sequencer) deposits tokens into governance by default and delegates voting power to the rollup (which automatically votes "yea" on proposals from the `GovernanceProposer`). Depositing into governance without staking allows tokenholders to vote directly.
 - Provide sequencers with an opportunity to adjust their delegation if they want to vote differently from the default rollup behavior.
 
 **Custom Voting via Delegation to a Controlled Address**
@@ -94,13 +96,13 @@ See [Custom Voting](https://docs.aztec.network/network/operation/sequencer_manag
 
 ### Voting
 
-After the waiting period expires, the proposal enters a 7-day voting period. At the moment voting begins:
+After the waiting period expires, the proposal enters the `votingDuration` voting period. At the moment voting begins:
 
 - The system snapshots voting power derived from staked tokens.
 - The delegation state at that time determines who holds voting rights for the proposal.
 - Any delegation changes made *after* voting has started do not affect voting power for that active proposal.
 
-To participate in voting, eligible tokenholders can stake and lock their tokens to vote. All staked tokens will be locked for at least 38 days to ensure the proposal can be executed before the voter exits.
+To participate in voting, eligible tokenholders can stake and lock their tokens to vote. All staked tokens will be locked for the minimum lock period (`votingDelay + votingDuration + executionDelay` from `getConfiguration()` in `Governance.sol`) to ensure the proposal can be executed before the voter exits.
 
 **Default Voting via Rollup Delegation**
 
@@ -112,15 +114,17 @@ By default, tokenholders staked as sequencers delegate their voting power to the
 
 A proposal is approved only if it satisfies all of the following:
 
-- **Quorum:** At least **20%** of the total voting power in governance must participate.
-- **Supermajority:** The difference between yea and nay votes must be at least **33%**, meaning at least **66%** of votes cast must be yea.
-- **Minimum Votes:** At least **100,000,000 tokens** must be deposited in governance for any vote to pass.
+- **Quorum:** At least **`quorum`** of the total voting power in governance must participate.
+- **Supermajority:** The difference between yea and nay votes must meet the **`requiredYeaMargin`** threshold.
+- **Minimum Votes:** At least **`minimumVotes`** tokens must be deposited in governance for any vote to pass.
+
+*(All fields from `getConfiguration()` in `Governance.sol`)*
 
 If these thresholds are not met, the proposal fails and does not proceed to execution.
 
 ### Execution
 
-When a proposal receives sufficient support, it passes. After passing, there's another mandatory 30-day delay before the proposal becomes executable. 
+When a proposal receives sufficient support, it passes. After passing, there's another mandatory `executionDelay` (`getConfiguration()` in `Governance.sol`) before the proposal becomes executable. 
 
 This delay serves several purposes:
 
@@ -130,7 +134,7 @@ This delay serves several purposes:
 
 In practice, operators may run multiple node versions during this window (for example, one on the current version and one on the upcoming version) to ensure a smooth transition.
 
-Once executable, anyone can trigger execution. See [Executing Proposals](https://docs.aztec.network/network/operation/sequencer_management/creating_and_voting_on_proposals#executing-proposals) for instructions on how to execute proposals. If not executed within the grace period (`getGracePeriod()` in `Governance.sol`), the proposal expires.
+Once executable, anyone can trigger execution. See [Executing Proposals](https://docs.aztec.network/network/operation/sequencer_management/creating_and_voting_on_proposals#executing-proposals) for instructions on how to execute proposals. If not executed within the `gracePeriod` (`getConfiguration()` in `Governance.sol`), the proposal expires.
 
 ### Failed Proposals
 

governance-manual.md

@@ -11,7 +11,7 @@ The purpose of Aztec governance is to remove control over the network from the h
 - **AZIPs** – Offchain, version-controlled design documents that specify proposed changes to Aztec’s protocols, standards, or governance processes, serving as the canonical record of what should change and why.
 - **AZUPs** – Onchain upgrade bundles that package one or more AZIPs, plus their associated payload, into a concrete proposal for execution on the Aztec Network.
 - **Payloads** – Series of onchain commands that execute against protocol contracts (or update contract references) detailed by an approved AZUP.
-- **Signaling** – The process by which sequencers express support for an AZUP’s payload onchain; once a payload receives signals in at least 600 of 1,000 eligible slots, it is promoted to a formal onchain proposal.
+- **Signaling** – The process by which sequencers express support for an AZUP’s payload onchain; once a payload receives at least `QUORUM_SIZE` signals within a `ROUND_SIZE`-slot round (`GovernanceProposer.sol`), it is promoted to a formal onchain proposal.
 - **Onchain Proposals** – Governance objects created once a payload meets sequencer signaling thresholds, defining a specific upgrade that tokenholders can vote to accept or reject.
 - **Voting** – The onchain decision process in which eligible tokenholders lock tokens to cast “yea” or “nay” votes on proposals, with quorum and supermajority requirements determining whether an upgrade is authorized to execute.
 
@@ -21,7 +21,7 @@ The purpose of Aztec governance is to remove control over the network from the h
 
 Sequencers in Aztec are block producers and core governance actors. By running a sequencer node and staking into a rollup, they both build blocks and help steer protocol upgrades. 
 
-Before AZUPs are presented to tokenholders for voting, they must gather enough support from sequencers. Sequencers vote on the support of AZUPs via onchain signaling. 600 of 1,000 signals are needed from sequencers to advance an AZUP’s payload into the voting phase. This means sequencers collectively decide which AZUPs reach the formal voting stage.
+Before AZUPs are presented to tokenholders for voting, they must gather enough support from sequencers. Sequencers vote on the support of AZUPs via onchain signaling. `QUORUM_SIZE` of `ROUND_SIZE` signals are needed from sequencers (`GovernanceProposer.sol`) to advance an AZUP’s payload into the voting phase. This means sequencers collectively decide which AZUPs reach the formal voting stage.
 
 A sequencer’s staked capital is its voting power. By default, their stake is delegated through the Governance Staking Escrow (GSE) to the rollup contract, which automatically votes “yea” on AZUPs that came through the sequencer signaling path. This means sequencers passively support all AZUPs unless they explicitly delegate away from the rollup to an address they control and vote directly via the GSE.
 
@@ -41,9 +41,9 @@ If you would like to join the governance process and participate in the calls, j
 
 ## Tokenholders
 
-Tokenholders play a direct role in Aztec governance by staking their tokens and participating in onchain votes. Any tokenholder may participate in governance votes by connecting their wallet to the governance dashboard, depositing into the Governance contract, and locking tokens for at least 38 days to ensure proposals can be executed before they exit. 
+Tokenholders play a direct role in Aztec governance by staking their tokens and participating in onchain votes. Any tokenholder may participate in governance votes by connecting their wallet to the governance dashboard, depositing into the Governance contract, and locking tokens for the minimum lock period (`votingDelay + votingDuration + executionDelay` in `Governance.sol`) to ensure proposals can be executed before they exit. 
 
-Once a proposal is created by sequencers, all eligible stakers can vote during a 7-day voting window, following a fixed timeline that includes an initial waiting period, a voting period, an execution delay, and a final grace period for execution. For a proposal to pass, at least 20% of the total voting power in governance must participate, at least 66% of votes cast must be yea, and at least 100,000,000 tokens must be deposited in governance.
+Once a proposal is created by sequencers, all eligible stakers can vote during the `votingDuration` window, following a fixed timeline that includes an initial waiting period, a voting period, an execution delay, and a final grace period for execution. For a proposal to pass, the `quorum` of total voting power must participate, the `requiredYeaMargin` must be met, and at least `minimumVotes` tokens must be deposited in governance (all fields from `getConfiguration()` in `Governance.sol`).
 
 Aztec Labs and Aztec Foundation teams, as well as investors, are excluded from staking and governance for the first 12 months (including the TGE vote), with their tokens locked for 1 year and then vesting over the following 2 years. 
 
@@ -61,7 +61,7 @@ The current AZIP process is defined by the [AZIP Process](azip-process.md).
 
 AZUPs (AZtec Upgrade Proposals) bundle the implementations of one or more AZIPs that Core Contributors have approved for inclusion in the Aztec Network. Once an AZUP is scheduled, its onchain payload is deployed to mainnet, where it is submitted to sequencers for signaling.
 
-Once sequencers have signaled support for the deployed payload, anyone can promote it to a formal onchain governance proposal. After a 3-day review delay, the proposal enters a 7-day voting window where staked tokenholders vote “yea” or “nay”. If quorum, supermajority, and participation thresholds are met, the proposal passes. After a final 30-day execution delay, the proposal can then be executed by anyone within the grace period (`getGracePeriod()` in `Governance.sol`), implementing the AZUP onchain. If not executed within the grace period, the proposal expires.
+Once sequencers have signaled support for the deployed payload, anyone can promote it to a formal onchain governance proposal. After a `votingDelay` review period, the proposal enters a `votingDuration` voting window where staked tokenholders vote “yea” or “nay”. If quorum, supermajority, and participation thresholds are met, the proposal passes. After an `executionDelay`, the proposal can then be executed by anyone within the `gracePeriod` (all fields from `getConfiguration()` in `Governance.sol`), implementing the AZUP onchain. If not executed within the grace period, the proposal expires.
 
 ### Process
 
@@ -71,17 +71,23 @@ The current AZUP process is defined by the [AZUP Process](azup-process.md).
 flowchart LR
     A["AZIP\n(Specification)"] --> B["AZUP\n(Upgrade Proposal)"]
     B --> C["Payload Deployed\n(Ethereum Mainnet)"]
-    C --> D["Sequencer Signaling\n(600/1,000 slots)"]
+    C --> D["Sequencer Signaling\n(QUORUM_SIZE/ROUND_SIZE)"]
     D --> E["Proposal Created"]
-    E --> F["Voting Delay\n(3 days)"]
-    F --> G["Voting Period\n(7 days)"]
-    G --> H{"Quorum 20%\nSupermajority 66%\nMin 100M tokens"}
-    H -- Pass --> I["Execution Delay\n(30 days)"]
+    E --> F["Voting Delay\n(votingDelay)"]
+    F --> G["Voting Period\n(votingDuration)"]
+    G --> H{"quorum\nrequiredYeaMargin\nminimumVotes"}
+    H -- Pass --> I["Execution Delay\n(executionDelay)"]
     H -- Fail --> J["Failed"]
     I --> K["Execution\n(Grace Period)"]
     K --> L["Upgrade Live"]
 ```
 
+## Updating the Governance Process
+
+The governance process documents (this manual, the AZIP process, and the AZUP process) can be updated without going through a formal AZIP. Proposed changes should be raised as a thread in [GitHub Discussions](https://github.com/AztecProtocol/governance/discussions) so the community can review and provide feedback. Once rough consensus is reached among Core Contributors, the change is applied via a pull request to the governance repository.
+
+Substantive changes to the process — such as introducing new AZIP categories, changing how proposals advance, or altering the role of governance bodies — should be discussed broadly before being merged. Editorial fixes, clarifications, and minor updates do not require a formal discussion thread.
+
 ## Disputes and Disagreements
 
 Disagreements are a natural part of governance. The AZIP and AZUP processes are designed to surface conflicts early and resolve them through transparent, structured mechanisms.