Rework governance

docs/governance/how-is-etherlink-governed.md

@@ -36,7 +36,7 @@ The real-world duration of governance periods can be longer, depending on the ac
 
 For information about governance proposals and updates, see https://governance.etherlink.com.
 
-For the addresses of the contracts that manage governance, see [How do I participate in governance?](/governance/how-do-i-participate-in-governance).
+For the addresses of the contracts that manage governance, see [Governance overview](/governance/overview).
 
 ## Kernel governance (slow)
 

docs/governance/kernel-governance.md

@@ -0,0 +1,74 @@
+---
+title: Participating in kernel governance
+dependencies:
+  octez: 24.1
+---
+
+:::note
+
+For simplified instructions for voting for Etherlink kernel upgrades, see [Voting quickstart](/governance/quickstart).
+
+:::
+
+Bakers can vote on kernel updates with these commands.
+The commands are the same for slow and fast upgrades but they target different governance contracts.
+
+## Getting information about the current period
+
+You can get information about the current period at https://governance.etherlink.com.
+
+To get information about the current state of either kernel governance contract directly from the contract, connect the Octez client to an active node and call the contract's `get_voting_state` view.
+For example, this Octez client command calls this view for the slow governance contract on Mainnet:
+
+```bash
+octez-client -E https://mainnet.ecadinfra.com \
+  run view get_voting_state on contract KT1VZVNCNnhUp7s15d9RsdycP7C1iwYhAQ8r
+```
+
+The view returns information about the current governance period in this order:
+
+- The index of the current period
+- Whether the current period is Proposal (`Left Unit`) or Promotion (`Right Unit`)
+- The number of blocks remaining in the period
+- Information about voting during the period
+
+For example, this response shows that the contract is currently in the Proposal period:
+
+```
+(Pair 1619 (Left Unit) 64 None)
+```
+
+Block explorers and the [governance web site](https://governance.etherlink.com) show this information in a more human-readable format.
+
+You can also subscribe to the `voting_finished` event to be notified when the Proposal period completes.
+
+## Upvoting upgrades in the Proposal period
+
+To upvote a proposed kernel update during a Proposal period, go to the [governance web site](https://governance.etherlink.com), connect your wallet (baking key or voting key), select the governance process and active period, and cast your vote.
+
+As an alternative, call the `upvote_proposal` entrypoint with the same parameters as the `new_proposal` entrypoint:
+
+```bash
+octez-client call KT1VZVNCNnhUp7s15d9RsdycP7C1iwYhAQ8r from my_wallet \
+  --entrypoint "upvote_proposal" \
+  --arg "0x<KERNEL_HASH>"
+```
+
+## Voting for or against upgrades in the Promotion period
+
+When a proposal is in the Promotion period, you can vote for or against it by going to the [governance web site](https://governance.etherlink.com), connecting your wallet (baking key or voting key), selecting the governance process and active period, and casting your vote.
+
+As an alternative, you can vote for it by calling the `vote` entrypoint of the appropriate governance contract:
+
+```bash
+octez-client call KT1VZVNCNnhUp7s15d9RsdycP7C1iwYhAQ8r from my_wallet \
+  --entrypoint "vote" --arg '"yea"'
+```
+
+The command takes these parameters:
+
+- The address or Octez client alias of your baker account or voting key
+- The address of the Etherlink kernel governance contract
+- `"yea"`, `"nay"`, or `"pass"`, including the double quotes
+
+The command does not need the hash of the kernel because only one kernel can be in the Promotion period at a time, so the options are to vote for or against that kernel or to abstain by voting "pass."

docs/governance/overview.mdx

@@ -0,0 +1,59 @@
+---
+title: Governance overview
+---
+
+import InlineCopy from '@site/src/components/InlineCopy';
+
+The Etherlink governance process manages updates to Etherlink's kernel and the account that operates the sequencer.
+
+Tezos bakers can participate in the [Etherlink governance process](/governance/how-is-etherlink-governed) by submitting proposals to change the kernel and sequencer operator and voting for or against them.
+The voting power of a baker is the amount of tez that it has staked plus the tez that delegators have delegated to it, also called its _staking balance_.
+
+Separate contracts manage the slow kernel updates, the fast kernel updates, and the sequencer operator, so to interact with them, bakers send transactions to those contracts, such as with the Octez client.
+The addresses of the governance contracts are specified in Etherlink's kernel.
+For information about the Octez client, see [Command Line Interface](https://octez.tezos.com/docs/active/cli-commands.html) in the Octez documentation.
+
+## Governance web site
+
+For information about Etherlink governance and to vote on governance proposals, see https://governance.etherlink.com.
+This site:
+
+- Shows information about each governance process
+- Shows the active and past governance contracts
+- Shows active and past proposals and their states
+- Allows voting keys to claim voting rights
+
+## Governance contract addresses
+
+You need the address of the correct governance contract (and sometimes the address of the Etherlink Smart Rollup) to propose changes, vote on changes, and trigger approved changes.
+
+<table class="customTableContainer">
+<thead>
+<tr>
+<th>Contract</th>
+<th>Mainnet address</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Kernel governance (slow)</td>
+<td><InlineCopy code="KT1VZVNCNnhUp7s15d9RsdycP7C1iwYhAQ8r" href="https://better-call.dev/mainnet/KT1VZVNCNnhUp7s15d9RsdycP7C1iwYhAQ8r" abbreviate="6,4"></InlineCopy></td>
+</tr>
+<tr>
+<td>Kernel governance (fast)</td>
+<td><InlineCopy code="KT1DxndcFitAbxLdJCN3C1pPivqbC3RJxD1R" href="https://better-call.dev/mainnet/KT1DxndcFitAbxLdJCN3C1pPivqbC3RJxD1R" abbreviate="6,4"></InlineCopy></td>
+</tr>
+<tr>
+<td>Sequencer operator</td>
+<td><InlineCopy code="KT1WckZ2uiLfHCfQyNp1mtqeRcC1X6Jg2Qzf" href="https://better-call.dev/mainnet/KT1WckZ2uiLfHCfQyNp1mtqeRcC1X6Jg2Qzf" abbreviate="6,4"></InlineCopy></td>
+</tr>
+<tr>
+<td>Voting keys</td>
+<td><InlineCopy code="KT1Ut6kfrTV9tK967tDYgQPMvy9t578iN7iH" href="https://better-call.dev/mainnet/KT1Ut6kfrTV9tK967tDYgQPMvy9t578iN7iH" abbreviate="6,4"></InlineCopy></td>
+</tr>
+<tr>
+<td>Etherlink Smart Rollup</td>
+<td><InlineCopy code="sr1Ghq66tYK9y3r8CC1Tf8i8m5nxh8nTvZEf" href="https://tzkt.io/sr1Ghq66tYK9y3r8CC1Tf8i8m5nxh8nTvZEf" abbreviate="6,4"></InlineCopy></td>
+</tr>
+</tbody>
+</table>

docs/governance/proposing-upgrades.md

@@ -0,0 +1,32 @@
+---
+title: Proposing kernel upgrades
+dependencies:
+  octez: 24.1
+---
+
+:::note
+
+Only the baker that proposes the upgrade runs this command.
+Other bakers use different commands to vote for or against it, as described in [Participating in kernel governance](/governance/kernel-governance).
+
+:::
+
+During a Proposal period, bakers can propose updates by calling the `new_proposal` entrypoint of the appropriate governance contract and passing the hash of their proposed kernel, as in this example, which uses `<KERNEL_HASH>` as the kernel hash:
+
+```bash
+octez-client call KT1VZVNCNnhUp7s15d9RsdycP7C1iwYhAQ8r from my_wallet \
+  --entrypoint "new_proposal" \
+  --arg "0x<KERNEL_HASH>"
+```
+
+The command takes these parameters:
+
+- The address or Octez client alias of your baker account or [voting key](/governance/voting-key)
+- The address of the Etherlink kernel governance contract, either `KT1VZVNCNnhUp7s15d9RsdycP7C1iwYhAQ8r` for the slow governance process or `KT1DxndcFitAbxLdJCN3C1pPivqbC3RJxD1R` for the fast governance process; see [Governance contract addresses](/governance/overview#governance-contract-addresses)
+- The hash of the upgraded kernel, which the proposer must generate from the code of the new kernel
+
+The proposer must make the code and hash of the new kernel available for people to evaluate.
+You can look for this information in blog posts or other announcements from proposal developers.
+Proposers can make it easier for bakers to upgrade to the new kernel by providing the preimages for the kernel online so nodes can update from them directly.
+
+It's not necessary to upvote a proposal that you submitted; submitting a proposal implies that your account upvotes it.

docs/governance/quickstart.md

@@ -0,0 +1,51 @@
+---
+title: Voting quickstart
+dependencies:
+  octez: 24.1
+---
+
+:::note
+
+This page includes only the basic commands for voting for Etherlink kernel upgrade proposals.
+For complete information, see [Participating in kernel governance](/governance/kernel-governance).
+
+:::
+
+## Using the governance web site
+
+To upvote a proposed kernel update during a Proposal period, go to the [governance web site](https://governance.etherlink.com), connect your wallet (baking key or voting key), select the governance process and active period, and cast your vote.
+
+If you prefer to use the command line instead of the governance web site, the following sections cover how to vote with the Octez client.
+
+## Voting in the Proposal period with the command line
+
+During a Proposal period, go to the [governance web site](https://governance.etherlink.com) and find the hash of the kernel to upvote, adding `0x` if it doesn't already start with `0x`.
+Then run this command:
+
+```bash
+octez-client call <GOVERNANCE_CONTRACT> from <MY_VOTER> \
+  --entrypoint "upvote_proposal" \
+  --arg "0x<KERNEL_HASH>"
+```
+
+Parameters:
+
+- `<GOVERNANCE_CONTRACT>`: The governance contract to call, either `KT1VZVNCNnhUp7s15d9RsdycP7C1iwYhAQ8r` for the slow governance process or `KT1DxndcFitAbxLdJCN3C1pPivqbC3RJxD1R` for the fast governance process; see [Governance contract addresses](/governance/overview#governance-contract-addresses)
+- `<MY_VOTER>`: Your baker key or Etherlink [voting key](/governance/voting-key)
+- `<KERNEL_HASH>`: The hash of the kernel to upvote, starting with `0x`
+
+## Voting in the Promotion period with the command line
+
+During a Promotion period, run this command to vote for or against the kernel by running this command, using `yea`, `nay`, or `pass` as the argument:
+
+```bash
+octez-client call <GOVERNANCE_CONTRACT> from <MY_VOTER> \
+  --entrypoint "vote" --arg '"yea"'
+```
+
+Parameters:
+
+- `<GOVERNANCE_CONTRACT>`: The governance contract to call, either `KT1VZVNCNnhUp7s15d9RsdycP7C1iwYhAQ8r` for the slow governance process or `KT1DxndcFitAbxLdJCN3C1pPivqbC3RJxD1R` for the fast governance process; see [Governance contract addresses](/governance/overview#governance-contract-addresses)
+- `<MY_VOTER>`: Your baker key or Etherlink [voting key](/governance/voting-key)
+
+The command does not need the hash of the kernel because only one kernel can be in the Promotion period at a time, so the options are to vote for or against that kernel or to abstain by voting "pass."

docs/governance/sequencer-upgrades.md

@@ -0,0 +1,101 @@
+---
+title: Participating in sequencer governance
+dependencies:
+  octez: 24.1
+---
+
+Bakers can propose the account to operate Etherlink's sequencer, vote for or against proposed operators, and trigger the change to a new account.
+
+## Getting information about the current period
+
+You can get information about the current period at https://governance.etherlink.com.
+
+To get information about the current state of the sequencer operator governance contract directly from the contract, call its `get_voting_state` view.
+For example, this Octez client command calls this view for the kernel governance contract on Mainnet:
+
+```bash
+octez-client -E https://mainnet.ecadinfra.com \
+  run view get_voting_state on contract KT1WckZ2uiLfHCfQyNp1mtqeRcC1X6Jg2Qzf
+```
+
+The view returns information about the current governance period.
+Block explorers show this information in a more human-readable format.
+
+You can also subscribe to the `voting_finished` event to be notified when the Proposal period completes.
+
+## Proposing and voting for a new operator
+
+To propose an account to be the sequencer operator, bakers can call the `new_proposal` entrypoint of the governance contract during the Proposal period:
+
+```bash
+octez-client transfer 0 from my_wallet to KT1WckZ2uiLfHCfQyNp1mtqeRcC1X6Jg2Qzf \
+  --entrypoint new_proposal \
+  --arg 'Pair "<PUBLIC_KEY>" <L2_ADDRESS>'
+```
+
+The command takes these parameters:
+
+- The address or Octez client alias of your baker account or voting key
+- The address of the sequencer governance contract (referred to on the block explorer as the sequencer committee governance contract)
+- The public key (not the public key hash or account address) of the account to propose, including the double quotes, represented in this example as `<PUBLIC_KEY>`
+- The Etherlink address of the account to propose, represented in this example as `<L2_ADDRESS>`
+
+For example:
+
+```bash
+octez-client call KT1WckZ2uiLfHCfQyNp1mtqeRcC1X6Jg2Qzf from my_wallet \
+  --entrypoint new_proposal \
+  --arg 'Pair "<PUBLIC_KEY>" <L2_ADDRESS>'
+```
+
+To upvote a proposed sequencer operator during a Proposal period, go to the [governance web site](https://governance.etherlink.com), connect your wallet (baking key or voting key), select the governance process and active period, and cast your vote.
+
+As an alternative, call the `upvote_proposal` entrypoint with the same parameters as the `new_proposal` entrypoint:
+
+```bash
+octez-client call KT1WckZ2uiLfHCfQyNp1mtqeRcC1X6Jg2Qzf from my_wallet \
+  --entrypoint upvote_proposal \
+  --arg 'Pair "<PUBLIC_KEY>" <L2_ADDRESS>'
+```
+
+It's not necessary to upvote a proposal that you submitted; submitting a proposal implies that your account upvotes it.
+
+## Voting for or against an operator
+
+When a proposal is in the Promotion period, you can vote for or against it by going to the [governance web site](https://governance.etherlink.com), connecting your wallet (baking key or voting key), selecting the governance process and active period, and casting your vote.
+
+As an alternative, you can vote for or against it or pass on voting by calling the `vote` entrypoint of the governance contract:
+
+```bash
+octez-client call KT1WckZ2uiLfHCfQyNp1mtqeRcC1X6Jg2Qzf from my_wallet \
+  --entrypoint "vote" --arg '"yea"'
+```
+
+The command takes these parameters:
+
+- The address or Octez client alias of your baker account or voting key
+- The address of the sequencer governance contract
+- `"yea"`, `"nay"`, or `"pass"`, including the double quotes
+
+For example:
+
+```bash
+octez-client call KT1WckZ2uiLfHCfQyNp1mtqeRcC1X6Jg2Qzf from tz1RLPEeMxbJYQBFbXYw8WHdXjeUjnG5ZXNq \
+  --entrypoint "vote" --arg '"yea"'
+```
+
+## Triggering sequencer operator updates
+
+After a proposed account wins a vote, any account can trigger the change and enable that account to run the sequencer by calling the governance contract's `trigger_committee_upgrade` entrypoint:
+
+```bash
+octez-client call KT1WckZ2uiLfHCfQyNp1mtqeRcC1X6Jg2Qzf from my_wallet \
+  --entrypoint "trigger_committee_upgrade" \
+  --arg '"sr1Ghq66tYK9y3r8CC1Tf8i8m5nxh8nTvZEf"'
+```
+
+The command takes these parameters:
+
+- The address or Octez client alias of your baker account or voting key
+- The address of the sequencer governance contract
+- The address of the Etherlink Smart Rollup; the parameter must include the double quotes

docs/governance/triggering-upgrades.md

@@ -0,0 +1,23 @@
+---
+title: Triggering kernel upgrades
+dependencies:
+  octez: 24.1
+---
+
+After a proposal wins a vote, any account can trigger the kernel upgrade by calling the appropriate governance contract's `trigger_kernel_upgrade` entrypoint:
+
+```bash
+octez-client call KT1DxndcFitAbxLdJCN3C1pPivqbC3RJxD1R from my_wallet \
+  --entrypoint "trigger_kernel_upgrade" \
+  --arg '"sr1Ghq66tYK9y3r8CC1Tf8i8m5nxh8nTvZEf"'
+```
+
+The command takes these parameters:
+
+- The address or Octez client alias of your baker account or voting key
+- The address of the appropriate Etherlink kernel governance contract
+- The address of the Etherlink Smart Rollup; the parameter must include the double quotes
+
+After the new kernel becomes active, bakers must provide their nodes with the preimages for the new kernel to continue to participate in Etherlink.
+They can copy the new preimages into the node data directory without stopping or restarting the node.
+If a node uses a preimages endpoint as described in [Running an Etherlink EVM node](/network/evm-nodes) and [Running an Etherlink Smart Rollup node](/network/smart-rollup-nodes), the node updates automatically.