EraTransitionGovernance.md: first draft

docs/website/contents/for-developers/EraTransitionGovernance.md

@@ -0,0 +1,58 @@
+# Era Transition Goverance
+
+This document explains how on-chain governance ends each era within Cardano, with a particular emphasis on testnets.
+
+Every era ends when on-chain governance increments the major protocol version past the greatest within that era.
+According to [the table maintained alongside CIP-59](https://github.com/cardano-foundation/CIPs/blob/master/CIP-0059/feature-table.md), those versions are as follows.
+
+| Era | Contained major versions |
+| - | - |
+| Byron | 0, 1 | 
+| Shelley | 2 | 
+| Allegra | 3 | 
+| Mary | 4 | 
+| Alonzo | 5, 6 | 
+| Babbage | 7, 8 |
+| Conway | 9, 10, ...? (Conway is the latest era at time of writing) |
+
+All eras forbid proposals to increase the major protocol version by more than one at a time.
+Thus the governance process within those eras (Byron, Alonzo, Babbage, and Conway, so far) that contain multiple major protocol versions must take place multiple times.
+In turn, for example, at least the first two epochs of any Cardano chain will be in the Byron era.
+
+# Byron
+
+The relevant Byron update proposal [increments the major component of the protocol version](https://github.com/IntersectMBO/cardano-ledger/blob/f5b35692b4d92d664187781a98b7af3fab445bad/eras/byron/ledger/impl/src/Cardano/Chain/Update/Proposal.hs#L219).
+As with all Byron governance, it's a six stage process on-chain.
+
+- Some genesis key delegate registers the update proposal at least `4k` slots before the intended first slot of the next era.
+  (On mainnet, `k=2160`, but that value can be different on testnets.)
+- Enough of the genesis key delegates vote for the proposal.
+  The exact quorum threshold is a protocol parameter; testnets can ignore the particular value by simply having all keys vote for the proposal.
+- At least `2k` slots pass.
+- Enough genesis delegates then extend the chain with a block that endorses the proposal, by setting their [`headerProtocolVersion` field](https://github.com/IntersectMBO/cardano-ledger/blob/f5b35692b4d92d664187781a98b7af3fab445bad/eras/byron/ledger/impl/src/Cardano/Chain/Block/Header.hs#L158-L159) to the proposed version.
+  The validation for this field is lax, so testnets can simply set it for all Byron blocks to the Shelley protocol version (ie the one in the proposal that ends Byron).
+- At least `2k` slots pass.
+- The next epoch transition will adopt the proposal, thereby incrementing the major protocol version.
+
+The proposal and all of the votes for one increment can be introduced in a single transaction.
+Testnets when possible should introduce that transaction in the first slot of whichever epoch is intended to be the last with that protocol version, to maximize the probability that it enters the mempools and is included in a block soon enough, for example.
+
+# Shelley, Allegra, Mary, Alonzo, and Babbage
+
+These eras all use [an update proposal the increments the major component of the protocol version](https://github.com/IntersectMBO/cardano-ledger/blob/f5b35692b4d92d664187781a98b7af3fab445bad/libs/cardano-ledger-core/src/Cardano/Ledger/Core/PParams.hs#L355).
+The stages on-chain are simpler than for Byron.
+
+- Enough of the genesis key delegates make the same proposal at least `6k/f` slots before the intended first slot of the next era.
+  (On mainnet, `k=2160` and `f=1/20`, but those values can be different on testnets.)
+  The exact quorum threshold is a protocol parameter; testnets can ignore the particular value by simply having all keys propose the increment.
+  (Voting is no longer distinct from proposing.)
+- The next epoch transition will adopt the proposal, thereby incrementing the major protocol version.
+
+All of the proposals for one increment can be introduced in a single transaction.
+Testnets when possible should introduce that transaction in the first slot of whichever epoch is intended to be the last with that protocol version, to maximize the probability that it enters the mempools and is included in a block soon enough, for example.
+
+# Conway
+
+The Conway era uses a dedicated [`Hard Fork Initiation` governance action](https://github.com/IntersectMBO/cardano-ledger/blob/f5b35692b4d92d664187781a98b7af3fab445bad/eras/conway/impl/src/Cardano/Ledger/Conway/Governance/Procedures.hs#L805-L810) to increment the major protocol version.
+
+See [CIP-1694](https://cips.cardano.org/cip/CIP-1694) for the stages of the governance process, specifically the dynamics (eg dedicated quorum threshold) of "Hard Fork Initiations".