fix: design doc

governance/permissionless-proposals.md

@@ -1,80 +1,90 @@
 # Purpose
 
-This document outlines the design for enabling permissionless proposals in the Optimism governance system. The goal is to allow top delegates to submit a proposal on-chain without requiring prior approval or gatekeeping by the manager. Instead, if all automated gating rules are met, the proposal is submitted for voting.
+This document outlines the design for enabling permissionless proposals in the Optimism governance system. The goal is to allow an approved address or anyone, based on the Proposal Type, to submit a proposal on-chain without requiring prior approval or gatekeeping by the manager. Instead, if all automated gating rules are met, the proposal is submitted for voting. 
 
 # Summary
 
-We propose introducing a `Top100DelegatesProposalValidator` contract that sits in front of the existing Governor. This contract will enforce additional permissions rules such as verifying delegate approvals, checking submission windows, and proposal type rules via the `ProposalTypeConfigurator`, before forwarding the proposal to the underlying governor. 
-This design represents a step towards fully permissionless proposals. While it removes manual gatekeeping and automates rule enforcement on-chain, it still relies on configurable thresholds and permissions to ensure system integrity.
+We propose introducing a `ProposalValidator` contract that sits in front of the existing Governor. This contract will enforce additional permissions rules such as verifying delegate approvals, checking submissions windows, and validating the Proposal Type, before forwarding the proposal to the underlying governor. This design represents a step towards fully permissionless proposals. While it remove manual gatekeeping and automates rule enforcement on-chain, it continues to rely on configurable thresholds and permissions, set by a manager, to ensure system integrity. 
 
 # Problem Statement + Context
 
-The current process (per the Operating Manual v0.4.2) requires proposals to be drafted on the forum, receive explicit approvals from at least four of the top 100 delegates (via linked attestations), and then be submitted for a vote during a specific voting cycle. The existing process is partially off-chain and manually enforced.
+The current process, per the [**Operating Manual v0.4.2**](https://github.com/ethereum-optimism/OPerating-manual/blob/main/manual.md), involves proposals being drafted on the forum, receiving delegate approvals (explicit sign-offs from four of the top 100 delegates), and then being submitted for a vote during a specific voting cycle. The existing flow is partially off-chain and manually enforced: delegates post drafts in the forum, approvals are coordinated in the comments, and a designated manager is responsible for calling the Governor to formally start the voting cycle.
 
 We need to replicate this process on-chain so that:
 
-- Any eligible participant can submit a proposal without manual gatekeeping by the manager.
+- Any eligible participant can submit a proposal without manual gatekeeping by the manager. Eligibility to propose will still depend on the proposal type.
 - The on-chain system automatically enforces delegate approvals, submission windows, and type-specific gating.
 - The system remains non-plutocratic by relying on multiple delegate approvals instead of token thresholds alone.
-- Additionally, certain roles (Security Council or a timelock) can still veto or cancel proposals if needed.
+- Additionally, specific roles (Security Council or a timelock) can still veto or cancel proposals if needed.
 
 # Proposed Solution
 
-At a high-level, we propose the creation of an `Top100DelegatesProposalValidator` contract that becomes the sole interface for proposal submissions to the Governor. The `Top100DelegatesProposalValidator` will:
+At a high-level, we propose the creation of a `ProposalValidator` contract that becomes the sole interface for proposal submissions to the Governor. The `ProposalValidator` will:
 
-- **Intercept proposal submissions**: Provide functions such as `propose()` and `proposeWithModule()` that include pre-validation steps.
-- **Delegate approval verification**: Require that a proposal submission gathers the sufficient delegate sign-offs before moving it for voting. These approvals will be validated by setting a minimum threshold of voting power that a delegate needs in order to approve, this threshold will be set by the manager along with the voting window.
-- **Submission window check:** Ensure the proposal is submitted within a defined short window relative to the current voting cycle. (Type proposal check, this is not valid of all types of proposals)
-- **Type-aware validation:** Confirm that the proposal meets any additional criteria based on its type (e.g. higher thresholds for larger OP grants) as defined in the `ProposalTypesConfigurator`.
-- **Distribution rate limit**: Ensures the proposed amount does not go over the distribution rate limit.
-- **Forward valid proposals:** Once all checks pass, forward the call to the existing `OptimismGovernor` without reimplementing its core functions. To enable this, the `Top100DelegatesProposalValidator` must be granted proposal rights, which are currently restricted to the manager role.
+- **Intercept proposal submissions**: Provide functions such as `submitProposal()` and `moveToVote()`that ensures a proposal is correctly validated before moving to the governor.
+- **Proposer Role:** This is the address that initiates a governance proposal. There are two classes of proposers, depending on the proposal type:
+  - **Approved Proposer:** An address that has been explicitly attested, by the OP Foundation, as eligible to submit a given proposal type. These proposers must hold an on-chain attestation  that confirms they are authorized to submit proposals of a specific `ProposalType`. This model is used for sensitive categories like protocol upgrades or elections, where tighter permissioning is necessary.
+  - **Permissionless Proposer:** Any address may submit a proposal (no attestation required) as long as the proposal type allows it. In this case, the proposer must gather the required number of sign-offs (from top 100 delegates) before calling `moveToVote(...)`. This model is used for more open categories like the Governance Fund and Council Budget, supporting broader community participation.
+- **Delegate approval verification**: Require that a proposal submission gathers sufficient delegate sign-offs before moving it for voting through the Agora UI. These approvals will be validated by setting a minimum threshold of voting power that a delegate needs to approve. This threshold will be set by the manager along with the voting window. This check will also happen for the specific proposal types that are shown bellow.
+- **Submission window check:** Ensure the proposal is submitted within a defined short window relative to the current voting cycle. (Submission window checks may not apply to all `ProposalTypes`).
+- **Proposal Voting Type Validation:** Each proposal must be validated to ensure it uses the correct voting configuration as defined by the ProposalTypeConfigurator. This includes verifying the appropriate voting system (e.g., approval voting, ranked choice, optimistic)
+- **No-ops checker:** This will be a guard that ensures non-executable proposals (those with no on-chain actions) do not execute OP transfers.
+- **Proposal distribution rate limit**: Ensures the proposed amount, for each proposal, does not go over the distribution rate limit. This check applies only to proposals that involve treasury outflows. Non-financial proposals may bypass this check entirely. The `ProposalTypes` determines whether a proposal type is subject to this treasury rate limit.
+- **Forward valid proposals:** Once all checks pass, forward the call to the existing `OptimismGovernor` without reimplementing its core functions.
 
-## The Workflow
+Each proposal type and their validation steps are detailed in the following table:
+
+| **Proposal Type**             | **Description**                                                                                                                                                                                          | **Proposer**                          | **Proposal Voting Type** | **Submission Checks**                                                                                                | **Moving To Vote Checks**                                          |
+|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------|--------------------------|----------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------|
+| Protocol or Governor Upgrade  | Scheduled changes to the on-chain smart contracts comprising the mainnet Optimism protocol or governance contract.                                                                                       | Any approved address by OP Foundation | Approval                 | - Input valid proposal type<br>- Proposer is an approved address<br>- No funds are transferred<br>- No state changes | - Gathered needed delegate approvals                               |
+| Maintenance Upgrade Proposals | Protocol maintenance required to continue network operation on a shorter timescale than voting periods. Must not materially change behavior for end users, infrastructure providers, or chain governors. | Any approved address by OP Foundation | Optimistic               | - Input valid proposal type<br>- Proposer is an approved address<br>- No funds are transferred<br>- No state changes | - N/A                                                              |
+| Council Member Elections      | Elections to replace or renew signers in a given cohort.                                                                                                                                                 | Any approved address by OP Foundation | Ranked Choice            | - Input valid proposal type<br>- Proposer is an approved address<br>- No funds are transferred<br>- No state changes | - Gathered needed delegate approvals<br>- Voting cycle enforcement |
+| Governance Fund (Missions)    | Used to support Collective development and ecosystem growth via the Mission framework.                                                                                                                   | Permissionless                        | Approval                 | - Input valid proposal type<br>- Requested amount does not exceed the OP Cap                                         | - Gathered needed delegate approvals<br>- Voting cycle enforcement |
+| Council Budget                | Allocation of funds for governance operations.                                                                                                                                                           | Permissionless                        | Approval                 | - Input valid proposal type<br>- Requested amount does not exceed the OP Cap                                         | - Gathered needed delegate approvals<br>- Voting cycle enforcement |
+
+# The Workflow
 
 The general workflow would be:
 
 1. **Draft Proposal:** A delegate starts by creating a Draft proposal and posting it on the optimism governance forum. At this stage, the proposal is open to the entire community for feedback. 
-2. **Proposal Finalization**: After the proposal has been drafted, delegates provide feedback, ask clarifying questions, and propose changes. Once the delegate incorporates this input and the proposal is refined, an approved proposer will be able to call `propose` on the `Top100DelegatesProposalValidator` contract which will return a `proposalId` , aimed to be added into the forum proposal and mark it as “FINAL”.
-3. **Move to vote via Top100DelegatesProposalValidator:** With the final proposal ready, the top 100 delegates can start signing-off on the on-chain proposal using the `proposalId`. When the proposal is ready to move to voting anyone should be able to call `moveToVote` , and if the proposal meets the necessary rules, such as having the required top 100 delegates sign-offs, being submitted within the correct time window, not going over the distribution rate limit, and adhering to any proposal type-specific threshold it will be moved to the Governor for voting.
-4. **Governor:** If the `Top100DelegatesProposalValidator`confirms that the proposal is valid, it forwards the proposal to the OP Governor contract. Then, the voting time begins as usual.
-
-### Off-chain flow
+2. **Proposal Finalization**: After the proposal has been drafted and shared on the forum, delegates provide feedback, ask clarifying questions, and propose changes. Once the delegate incorporates this input and the proposal is refined, the delegate updates its status to "Final Draft". At this point, the delegate must create an on-chain transaction to create the proposal metadata record in the `ProposalValidator` by calling `submitProposal()`, which can be done either through EthersScan or Agora UI. This call emits a `ProposalSubmitted` event, which includes the `proposalId` and other relevant data. Agora listens for this event and uses it to fetch and display the finalized proposal on its UI, allowing delegates to begin the sign-off process.
+
 ```mermaid
-  flowchart LR
-    Delegate([Delegate])
-    ForumDraft[OPGov Forum]
-    Community([Community])
-    ForumFinal[OPGov Forum]
-
-    Delegate -->|submit DRAFT proposal| ForumDraft
-    Community -->|provide feedback| ForumDraft
-    ForumDraft -->|submit FINAL proposal with proposalId| ForumFinal
+flowchart LR
+    Delegate([Delegate]) -->|Submit DRAFT proposal| OPGov1[OPGov Forum]
+    Community([Community]) -->|Provide feedback| OPGov1
+    OPGov1 -->|Submit FINAL proposal| OPGov2[OPGov Forum]
 ```
+
+3. **On-chain Sign-Offs via Agora**: With the final proposal ready, the top 100 delegates can start signing-off on the on-chain proposal using the `proposalId` through Agora. Their sign-offs are recorded via the `approveProposal(...)` function in the `ProposalValidator` contract, that emits a `ProposalApproved` event. Agora will display the real-time signature status for each proposal.
+4. **Move to vote via** `ProposalValidator`**:** Once the required number of sign-offs is reached, the "Approve Proposal" button in Agora changes to "Propose". Any user can click this button to call `moveToVote(...)` on the `ProposalValidator`. If the proposal meets the necessary rules, such as having the required top 100 delegates sign-offs, being submitted within the correct time window, not going over the distribution rate limit, and adhering to any proposal type-specific threshold it will be moved to the Governor for voting. This is done by internally calling `propose(...)` or `proposeWithModule(...)` **within `moveToVote(...)`.
+5. **Governor:** If the `ProposalValidator` checks that the proposal is valid, it forwards the proposal to the OP Governor contract. Then, the voting time begins as usual.
 
-### On-chain flow
 ```mermaid
 flowchart LR
-    Proposer([Approved Proposer])
-    Validator[ProposalValidator]
-    TopDelegates([Top Delegates])
-    Executor([Executioner])
-    FinalValidator[ProposalValidator]
-    OPGov[OPGov]
-
-    Proposer -->|propose| Validator
-    Validator -->|get proposalId| Proposer
-    TopDelegates -->|approve proposal| Validator
-
-    Executor -->|move to vote| FinalValidator
-    FinalValidator -->|propose| OPGov
+    subgraph Agora UI
+        AgoraUI -->|listens to ProposalSubmitted| A2[Agora UI]
+    end
+
+    A2 -->|Displays new proposal<br>based on Proposal Type| B[Agora UI]
+    C[Top Delegates] -->|approve proposal Id| B
+    B -->|approveProposal| D[ProposalValidator]
+
+    E[Approved Proposer] -->|moveToVote| F[Agora UI]
+    F -->|moveToVote| G[ProposalValidator]
+    G -->|propose| H[OPGov]
 ```
 
+Detailed flows for each Proposal Type can be seen [here](https://www.figma.com/board/V0zh1Lg5QqhGfhVrJaIJVu/Permissionless-Proposals-DRAFT?node-id=0-1&p=f&t=sFuVhRioJR1kAIzV-0).
+
 # Alternatives Considered
 
 - **Permissioned voting cycle configuration**: As an MVP, we allow a permissioned role to set the voting cycle and delegate approval thresholds. While not fully decentralized, this is acceptable given OF’s existing veto power. A future improvement could use an optimistic oracle to fetch these values on-chain, but this adds complexity we don’t believe is needed yet.
-- **Forum sign-offs with signature verification**: The current process relies on forum comments from top delegates as attestations. We considered maintaining this model, where proposers collect these off-chain signatures and verify them in the `Top100DelegatesProposalValidator`. However, direct on-chain approvals are simpler, reduce errors, and avoid coordination overhead.
+- **Forum sign-offs with signature verification**: The current process relies on forum comments from top delegates as attestations. We considered maintaining this model, where proposers collect these off-chain signatures and verify them in the `ProposalValidator`. However, direct on-chain approvals are simpler, reduce errors, and avoid coordination overhead.
+- **On-chain sign-offs initiated from the Forum**: An alternative flow would be to allow sign-offs to begin directly from the forum once a proposal is marked as “Final Draft.” In this model, delegates would click a “Approve Proposal” button embedded in the forum interface. Once the required number of sign-offs is collected, any user could call `propose(...)`. While feasible, this option creates more fragmented UX across governance tools and adds complexity for users interacting with the proposal lifecycle. We opted for Agora as the source of truth to unify coordination and finalization into a single interface.
 
 # Risks and Uncertainties
 
-- **Proposal type flexibility**: The current design relies on a permissioned `ProposalTypesConfigurator` to define and update proposal types. This is acceptable for the MVP but introduces centralization risk. In the future, we’ll need a more permissionless or community-driven mechanism to support new proposal types without relying on a single role.
-- **Alligator voting power**: This design does not currently account for subdelegations via the Alligator contract. In a very rare case, a subdelegator could appear in the top 100 delegates by aggregating voting power from multiple authority chains. This introduces ambiguity, as subdelegated voting power may be partially consumed elsewhere.
+- **Proposal type flexibility**: The current design relies on a permissioned role to define and update proposal types. This is acceptable for the MVP but introduces centralization risk. In the future, we’ll need a more permissionless or community-driven mechanism to support new proposal types without relying on a single role.
+- **Alligator voting power**: This design does not currently account for subdelegations via the Alligator contract. In a very rare case, a subdelegator could appear in the top 100 delegates by aggregating voting power from multiple authority chains. This introduces ambiguity, as subdelegated voting power may be partially consumed elsewhere.
+- **Operational Monitoring and security responsibility:** as the `ProposalValidator` process becomes fully on-chain, it’s important to define which actors are responsible for monitoring its correct operation. For example, what conditions should be enforced or tracked by the smart contract itself, and which anomalies should be monitored off-chain by the Foundation or other ecosystem participants? If a bug or unexpected behavior occurs in `ProposalValidator`, it could block valid proposals from reaching the Governor or allow invalid ones through.