feat: Add OP content (#54)

Implementing actual content of the old repository
https://github.com/defi-wonderland/op-handbook

Issue https://linear.app/defi-wonderland/issue/CHA-345/content-migration

Author: th0rOdinson

sites/optimism/docs/governance/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Governance",
+  "position": 4,
+  "link": {
+    "type": "doc",
+    "id": "governance/governance-overview"
+  }
+} 

sites/optimism/docs/governance/bye.md

@@ -0,0 +1,54 @@
+---
+id: bye
+title: Wrapping up
+sidebar_label: Wrapping up
+---
+
+# Wrapping Up
+
+To wrap up, where the OP Stack defines *how the system runs*, governance defines *how it changes*. It encodes: who can propose, who can vote, and who can veto. And because governance must evolve with the Collective, it’s designed to be both programmable and flexible—via modules, managers, and community experimentation.
+
+As you’ve seen, governance isn’t just about casting votes. It’s about trust minimization, fault tolerance, consent, and credible neutrality. The system must balance legitimacy with execution, and decentralization with security.
+
+Now that you’ve studied the full structure, we encourage you to sit with some deeper technical questions:
+
+## 🧠 Questions to think about
+
+<details>
+<summary>Why separate the Governor from the Proposal Validator?</summary>
+
+The Validator acts as a permissioned gatekeeper, enforcing off-chain rules (like delegate approval) in an on-chain format. It allows us to evolve the proposal logic independently from the core voting and execution engine. What trade-offs are we making in doing so?
+</details>
+
+<details>
+<summary>What could go wrong if the ProposalTypesConfigurator is centralized?</summary>
+
+Since quorum and approval thresholds depend on proposal type IDs, a compromised Configurator could lower requirements to push malicious proposals through. How would you design a decentralized alternative?
+</details>
+
+<details>
+<summary>How would you detect a subdelegation abuse via Alligator?</summary>
+
+If voting power is subdelegated to multiple downstream voters, how do we ensure no over-delegation occurs? What data structures or interfaces would help us prevent double-spending of votes?
+</details>
+
+<details>
+<summary>Can we remove the Manager role entirely?</summary>
+
+What would need to change in the system to remove the Manager's power to submit proposals, configure thresholds, or change voting deadlines? Could this be replaced with a DAO-controlled policy engine?
+</details>
+
+<details>
+<summary>What does 'forkability' look like in governance?</summary>
+
+If a delegate or group of citizens disagrees with the direction of governance, can they fork the system? What technical mechanisms or social affordances (e.g. reproducible config, open contracts) enable this?
+</details>
+
+### Keep Building
+
+Governance is never done. If you're working on tooling, researching modules, or helping design the next iteration of participation, it shapes the protocol!
+
+You can follow ongoing governance upgrades in:
+- [vote.optimism.io](https://vote.optimism.io/)
+- [gov.optimism.io](https://gov.optimism.io/)
+- [github.com/voteagora](https://github.com/voteagora)

sites/optimism/docs/governance/governance-overview.md

@@ -0,0 +1,30 @@
+---
+id: governance-overview
+title: Governance Overview
+sidebar_label: Overview
+pagination_next: governance/intro-to-governance
+---
+
+# Governance: What You Should Know
+
+This section introduces how governance works in the Optimism Collective: how proposals are created, who gets to vote, what infrastructure runs the system, and how that infrastructure is evolving toward greater decentralization and permissionlessness.
+
+We’ll start from the basics, what governance means in crypto, what proposals look like under the hood, and the vocabulary you’ll need to reason about things like quorums, thresholds, or veto rights.
+
+Then we’ll walk through the **OP Governor** smart contracts and the modular architecture surrounding them: `Alligator`, `ProposalTypesConfigurator`, `VotableSupplyOracle`, and the emerging validator logic for permissionless proposals. If you're wondering *who proposes what, and how proposals actually work*, this section is for you.
+
+We’ll also look at the **Operating Manual**, the dual-house structure (Token House & Citizens’ House), and how protocol upgrades, Retro Funding, and Missions are routed through this governance system.
+
+Finally, we’ll end with a breakdown of our current work to open up Optimism governance to more direct participation, removing bottlenecks, making rule enforcement on-chain, and enabling a path to *trust-minimized proposal submission*.
+
+By the end of this section, you should be able to answer:
+
+- What’s the difference between an approval and a vote on Optimism?
+- Who can propose? Who can vote? What powers are delegated?
+- How do proposals move through states like Pending → Active → Executed?
+- How is quorum calculated, and what makes a proposal “pass”?
+- What is Alligator, and why is delegation logic so complicated?
+- What happens if a delegate tries to push a proposal that violates cycle rules?
+- What is permissionless governance, and what tradeoffs does it introduce?
+
+Let’s dive into the design to understand who gets to change the rules.

sites/optimism/docs/governance/governor-walkthrough.md

@@ -0,0 +1,128 @@
+---
+id: governor-walkthrough
+title: Governor Walkthrough
+sidebar_label: Governor Walkthrough
+---
+
+# The Optimism Governor Walkthrough
+
+The Optimism Governor is based on the OpenZeppelin’s Governor, customized to support Optimism’s governance needs: signaling proposals, customizable voting rules, subdelegations, and so on.
+
+In the long run anyone should be able to propose changes, but safeguards like delegate approvals, quorum thresholds, and timelocks are required to ensure quality and protect against manipulation.
+
+Some useful resources: 
+
+- [Governor GitHub Repo (voteagora)](https://github.com/voteagora/optimism-governor)  
+- [vote.optimism.io](https://vote.optimism.io/): front-end interface for participation
+
+## Architecture and Deployment
+
+The [`OptimismGovernor`](https://github.com/voteagora/optimism-governor/blob/main/src/OptimismGovernor.sol) contract is upgradeable, following a proxy pattern:
+
+- `Governor Proxy`: `0xcDF27F107725988f2261Ce2256bDfCdE8B382B10`
+- `Alligator` (subdelegations): `0x7f08F3095530B67CdF8466B7a923607944136Df0`
+- `ProposalTypesConfigurator`: `0xCE52b7cc490523B3e81C3076D5ae5Cca9a3e2D6F`
+- `VotableSupplyOracle`: `0x1b7CA7437748375302bAA8954A2447fC3FBE44CC`
+
+While proposals today are signaling-only for most types (i.e., they do not trigger automatic onchain execution), the system enforces the full governance lifecycle: `Pending → Active → Succeeded → Queued → Executed`. The key exceptions are Governance Fund (Missions) proposals and certain Security Council proposals, which do cause onchain token transfers, for example, transferring OP to fund a Mission or allocating ETH from the treasury.
+
+## Core Roles
+
+- **`admin`**: Owns the proxy and controls upgrades. Does not vote or propose.
+- **`manager`**: Can create proposals, execute them, or update system parameters.
+- **`voters`**: Any address with delegated OP — either directly or through Alligator.
+
+## Inheritance
+
+```solidity
+contract OptimismGovernor is
+    Initializable,
+    GovernorUpgradeableV2,
+    GovernorCountingSimpleUpgradeableV2,
+    GovernorVotesUpgradeableV2,
+    GovernorVotesQuorumFractionUpgradeableV2,
+    GovernorSettingsUpgradeableV2
+``` 
+
+Each inherited contract contributes:
+- `GovernorUpgradeableV2`: Core lifecycle logic, proposal state machine
+- `GovernorCountingSimpleUpgradeableV2`: Vote tallying (for/against/abstain)
+- `GovernorVotesUpgradeableV2`: Gets historical voting power at a given block
+- `GovernorVotesQuorumFractionUpgradeableV2`: Legacy support for % quorum
+- `GovernorSettingsUpgradeableV2`: Configurable parameters (e.g. voting period)
+
+:::warning
+The Optimism Governor overrides some of these base contracts, notably quorum and proposal thresholds, using a `ProposalTypesConfigurator` and `VotableSupplyOracle`
+:::
+
+## Proposal Flow
+
+The Governor supports two proposal paths:
+
+```solidity
+propose(...):               // Standard proposal
+proposeWithModule(...):     // Proposal with custom voting module
+```
+
+Only the `manager` or `timelock()` can call propose. Each proposal is assigned a `proposalType`, which maps to specific quorum/approval thresholds in the `ProposalTypesConfigurator`.
+
+Voting is handled via:
+- `castVote()`: standard token-based voting
+- `castVoteFromAlligator()`: partial delegation via the Alligator contract
+- `VoteCastWithParams`: supports modules that require additional input (e.g., ranked or approval voting)
+
+Proposals are executed via the Timelock contract, using `execute()` or `executeWithModule()`.
+
+## The key Modules
+
+### Alligator - Subdelegations
+
+The Alligator enables partial delegation, a user can split their voting power across multiple delegates using absolute or relative rules. These delegations can be chained (A → B → C) and validated onchain using authority[] arrays.
+
+The key structures are:
+- `subdelegations[from][to]`: maps delegations
+- `SubdelegationRules`: define allowance, `maxRedelegations`, timing, and custom logic
+- Supports batched voting with `castVoteWithReasonAndParamsBatched(...)`
+
+The contract validates that:
+1. Each delegation is valid and within limits
+2. The final sender is authorized
+3. No overuse or double-voting has occurred
+
+It then forwards votes to `castVoteFromAlligator()` on the Governor.
+
+## ProposalTypesConfigurator
+
+Proposals can have different voting requirements depending on their type. This configurator allows each `proposalType` to define:
+- quorum (e.g. 5100 = 51%)
+- approvalThreshold (e.g. 7600 = 76%)
+- name, description, module (if any)
+
+Proposal thresholds are stored with 1e4 scaling (10000 = 100%). The Governor calls `proposalTypesConfigurator.proposalTypes(proposalTypeId)` during voting and quorum checks.
+
+## Votable Supply Oracle
+
+Instead of total token supply, quorum is based on votable supply — the total OP that has been delegated. This is retrieved at proposal creation block and used to calculate thresholds dynamically.
+
+- **Fallback**: if `votableSupply()` returns zero, the Governor falls back to total token supply.
+
+## Functions Summary
+
+**Proposal Management**
+- `propose()` / `proposeWithModule()`
+- `setVotingDelay()`, `setVotingPeriod()`, `setProposalThreshold()`
+- `setProposalDeadline()`: update deadline during voting
+- `cancel()`, `cancelWithModule()`
+
+**Voting**
+- `castVote()`
+- `castVoteFromAlligator(...)`
+- `increaseWeightCast(...)`: internal weight accounting for partial votes
+
+**Execution**
+- `queue()`, `queueWithModule()`
+- `execute()`, `executeWithModule()`
+
+## Future Extensions
+
+We are working on an upgrade that is evolving toward permissionless proposals, enforced via `DelegatesProposalValidator` contract, it gates access to `propose()` based on delegate approvals and submission windows, allowing any qualifying participant to propose, while still preserving cycle alignment.

sites/optimism/docs/governance/intro-to-governance.md

@@ -0,0 +1,111 @@
+---
+id: intro-to-governance
+title: Governance in a nutshell
+sidebar_label: Governance in a nutshell
+---
+
+# Governance in a nutshell
+
+Before we get into Optimism-specific contracts, let’s zoom out.
+
+On-chain governance is a mechanism for managing shared infrastructure using verifiable rules. In practice, governance contracts behave similar to multisigs, but with vote weights distributed across token holders rather than multisig signers.
+
+At its core, governance is about managing change. A **proposal** is just a transaction (or set of transactions): a list of target addresses, call data, and sometimes ETH values. Token holders vote to approve or reject the proposal. If the vote passes and quorum is met, the transaction can be executed onchain. If it fails, it’s simply discarded.
+
+Voting power is usually determined by the number of tokens an address holds at a specific snapshot block. Most systems also allow **delegation**, meaning you can assign your voting power to another address to vote on your behalf.
+
+Some proposals affect onchain systems directly (e.g. upgrading a contract). Others are **signaling-only** (e.g. changing a community guideline or legal structure). In those cases, proposals still follow the same governance flow, but their “execution” happens through offchain coordination or manual implementation.
+
+## Common Terms
+
+These are the core terms used across most governance systems, including Optimism:
+
+- **Proposal**: A governance action defined by a set of addresses and calldata. Often restricted to users with a minimum token balance.
+- **Vote**: A signal (usually onchain) cast by a token holder. Can be FOR, AGAINST, or ABSTAIN.
+- **Voting Power**: The influence a voter has, usually based on token holdings at a snapshot block. Voting power can be delegated.
+- **Voting Period**: A fixed duration during which votes can be submitted. If quorum isn’t reached, the proposal fails.
+- **Quorum**: The minimum percentage of voting power that must participate for a proposal to be valid.
+- **Timelock**: A delay between passing a proposal and executing it. Gives time for reactions before changes take effect.
+- **Queued / Execution**: Proposals are queued in a timelock contract after passing, and only then executed.
+
+## The Proposal Lifecycle
+
+While implementations vary, the lifecycle of a proposal usually looks like this:
+
+```nasm
+Pending ⭢ Active ⭢ Defeated ⭢ Canceled
+			                 ⮑ Succeeded ⭢ Queued ⭢ Executed
+				                   ⮑----------⮑-------⮑  Expired
+```
+- **Pending**: Proposal exists, but voting hasn’t started (waiting for delay).
+- **Active**: Voting is open.
+- **Succeeded**: Quorum was reached and a majority voted FOR.
+- **Queued**: Added to timelock. Awaiting delay before execution.
+- **Executed**: Transactions have been run.
+- **Defeated / Canceled / Expired**: Proposal did not pass or was invalidated.
+
+:::info Reference
+When in doubt about how a transition works, [just read the contract.](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/release-v4.8/contracts/governance) 
+:::
+
+## Compound’s Bravo + OpenZeppelin’s Governor
+
+The most influential governance systems today trace back to [Compound’s Governor Bravo](https://docs.compound.finance/v2/governance/). It introduced:
+
+- Support for explicit ABSTAIN votes
+- Upgradeable architecture
+- Reason strings on vote calls (`castVoteWithReason`)
+
+OpenZeppelin later extended Bravo to create a fully composable [Governor](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/release-v4.8/contracts/governance/Governor.sol) base contract, which defines the lifecycle (propose → vote → queue → execute), and lets developers plug in extensions for voting, quorum logic, timelocks, and more.
+
+In particular, the [`GovernorCompatibilityBravo`](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/release-v4.8/contracts/governance/compatibility/GovernorCompatibilityBravo.sol) contract matches the Bravo API, enabling drop-in compatibility with Compound-style frontends.
+
+## Function Primer
+
+### Proposal Management
+
+| Function | Description |
+|----------|-------------|
+| `propose()` | Create a new proposal (must meet threshold) |
+| `queue()` | Queue a passed proposal for timelock |
+| `execute()` | Execute proposal after delay |
+| `cancel()` | Cancel a proposal if conditions change |
+
+### Voting
+
+| Function | Description |
+|----------|-------------|
+| `castVote()` | Submit a vote (FOR/AGAINST/ABSTAIN) |
+| `castVoteWithReason()` | Submit a vote with an explanation |
+| `getReceipt()` | View voting record for an address |
+
+### Querying
+
+| Function | Description |
+|----------|-------------|
+| `state()` | Get current proposal state (Pending, Active, etc.) |
+| `getActions()` | See what the proposal will execute |
+| `quorumVotes()` | Check quorum required for proposal to pass |
+
+## Design Patterns in Governance
+
+Most governance systems in Ethereum share the same building blocks:
+- A voting mechanism that calculates token-weighted power at a specific block (snapshot).
+- A registry of proposals with metadata like start/end blocks, vote tallies, and actions.
+- A timelock controller that enforces a minimum delay before execution.
+- A quorum and approval threshold to ensure decisions are legitimate.
+
+On top of this, each protocol adds its own mechanics: delegation systems, role-based permissions, modular thresholds, and custom voting logic.
+
+Some proposals are executable, others are advisory. Some are submitted by anyone, others require approvals. Governance is always opinionated, the trick is making those opinions legible and upgradeable.
+
+## Limitations and Responsibilities
+
+Governance systems can encode process, but not intention. They can enforce thresholds, track votes, and trigger transactions, but they can’t make communities healthy or decisions wise.
+
+As you move deeper into OP governance, keep in mind:
+- Power structures can be encoded, but legitimacy is earned.
+- Permissionless doesn’t mean consequence-free.
+- The goal is alignment.
+
+Governance is still an evolving experiment. And in the next section, we’ll look at how its infrastructure reflects that approach.

sites/optimism/docs/governance/our-work/diagram-1.png

@@ -0,0 +1,24 @@
+---
+id: overview
+title: Our Work
+sidebar_label: Our Work
+---
+
+This section documents active governance-related development initiatives led by or contributed to Wonderland. While the previous sections described how the governance system functions today, this space focuses on improvements in progress—features that are being designed, discussed, or implemented. Some initiatives are in early stages; others are already live onchain.
+
+## Why it matters
+
+The governance is designed to evolve. Improvements often arise from practical bottlenecks observed by delegates, contributors, and protocol developers. This section records how those pain points are being addressed—through new contracts, improved interfaces, or procedural upgrades.
+
+Each entry aims to explain:
+
+- The motivation for the change
+- How the proposed solution works
+- Key trade-offs or risks involved
+- Links to contracts, proposals, or diagrams
+
+## Included so far
+
+- [Permissionless Proposals](./permissionless-proposals.md): Automating the proposal submission process to remove reliance on gatekeeping, while preserving collective approval via delegate sign-offs.
+
+As the governance system grows, this section will expand to include changes to proposal types, validator flows, delegate tooling, and so on.