Skip to content

Commit

Permalink
EraTransitionGovernance.md: also explain the `TestXxxHardForkAtEpoch:…
Browse files Browse the repository at this point in the history
… 0` exception
  • Loading branch information
nfrisby committed Mar 4, 2025
1 parent 146c8db commit 240a112
Showing 1 changed file with 28 additions and 1 deletion.
29 changes: 28 additions & 1 deletion docs/website/contents/for-developers/EraTransitionGovernance.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,8 +51,35 @@ The stages on-chain are simpler than for Byron.
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
## 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".

## Setting the Protocol Version in the Genesis File

It is often convenient for testnet chains to be able to entirely skip some initial protocol versions.
The node currently supports that for testing purposes via the following steps.

- Choose X, the desired protocol version for the testnet's to start with.
As a running example, suppose it is 6.0.
- Declare the `protocolVersion` field to be X (eg `{major: 6, minor: 0}`) within the `protocolParams` field within top-level JSON object of the Shelley Genesis file.
- In the node configuration file, include a `Test<Era>HardForkAtEpoch: 0` declaration for each Cardano era up to and including the era that contains X.
In the running example, protocol version X=6.0 is in Alonzo (refer to the table in the Introduction above), so the following declarations need to be present within the node configuration file.

```
...
TestShelleyHardForkAtEpoch: 0,
TestAllegraHardForkAtEpoch: 0,
TestMaryHardForkAtEpoch: 0,
TestAlonzoHardForkAtEpoch: 0,
...
```

In this mode, today's node still begins from the Byron Genesis file with protocol version 0, but the first thing it does is use the ledger's translation functions to convert the initial Byron ledger state to as specified above, even before slot 0.

- The translation from Byron to Shelley uses the protocol version specified in the Shelley Genesis file.
- All subsequent translations do not alter the protocol version.

This interface is the result of historical choices, not ideal, but it seems sufficient for testnets.

0 comments on commit 240a112

Please sign in to comment.