From d73c5381a49729105bee3c7f0975e3d185a8df68 Mon Sep 17 00:00:00 2001 From: Nicolas Frisby Date: Tue, 4 Mar 2025 12:13:33 -0800 Subject: [PATCH] EraTransitionGovernance.md: link to existing example test suites --- .../for-developers/EraTransitionGovernance.md | 34 +++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/website/contents/for-developers/EraTransitionGovernance.md b/docs/website/contents/for-developers/EraTransitionGovernance.md index 44c06d6a4a..aca1e55f2f 100644 --- a/docs/website/contents/for-developers/EraTransitionGovernance.md +++ b/docs/website/contents/for-developers/EraTransitionGovernance.md @@ -62,6 +62,40 @@ The Conway era uses a dedicated [`Hard Fork Initiation` governance action](https 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". +## Examples of On-Chain Governance in TestNets + +A few teams within IOG already have test suites that involve on-chain governance. + +- `cardano-node-tests`. + The SDET Team maintains a set of tests that involve a local cluster of nodes building a Cardano chain that has some blocks in every Cardano era. + [Their script]( https://github.com/IntersectMBO/cardano-node-tests/blob/05d0c4989d3d1bbebb7af894b4c5f9ba9fd32a25/cardano_node_tests/cluster_scripts/conway/start-cluster) demonstrates how to use `cardano-cli` commands to construct, sign, and submit the necessary transactions for every era except Byron. + + The Byron era there is currently termninated after one epoch via a `TestShelleyHardForkAt: 1` configuration setting, but the Consensus Team is currently working to [remove that functionality](https://github.com/IntersectMBO/ouroboros-consensus/issues/416). + Byron on-chain governance as described in this document will replace it, although it will require two epochs, one each to reach protocol versions 1 and 2. + +- `cardano-db-sync`. + The DB Sync Team creates a "mock" chain to use when testing their tool. + [This test](https://github.com/IntersectMBO/cardano-db-sync/blob/0f1d93f9b868caaf14c6cd0e77991e63c07c067f/cardano-chain-gen/test/Test/Cardano/Db/Mock/Unit/Conway/Governance.hs#L451) raises the protocol version within Conway. + And [this test](https://github.com/IntersectMBO/cardano-db-sync/blob/0f1d93f9b868caaf14c6cd0e77991e63c07c067f/cardano-chain-gen/test/Test/Cardano/Db/Mock/Unit/Conway/Other.hs#L447) raises the protocol version within Babbage. + The linked definitions use more combinators defined elsewhere in that codebase, but it's only a few indirections until the definitions start using the `cardano-ledger` interface directly. + Do note that these transactions have no witnesses, which is sufficient for the testing of a tool that trusts its upstream node. + +- `ouroboros-consensus`. + The Consensus Team wrote tests shortly before the end of the Byron era that tested the mechanism that would transition to Shelley. + In particular, [the `mkProtocolByronAndHardForkTxs` function](https://github.com/IntersectMBO/ouroboros-consensus/blob/a9a5f3aaf3ddd45b3dd58a132d65b657bbf285e5/ouroboros-consensus-cardano/src/unstable-byron-testlib/Test/ThreadNet/Infra/Byron/TrackUpdates.hs#L318-L363) and the `mkHardForkProposal` function defined just below it use the `cardano-ledger` interface for Byron in order to create the transactions for the proposal and votes --- each with the necessary witnesses/signatures --- in order to increment the protocol version via Byron on-chain governance. + Those functions are used within the Consensus Layer's "ThreadNet" tests, which submit the transactions listed in the `tniCrucialTxs` field at every possible opportunity. + That degenerate persistence and eagerness reliably ensures that the chain increments the protocol version as soon as possible. + + A similar ThreadNet test transitions from Shelley to Allegra; its `tniCrucialTxs` field is created by [this function](https://github.com/IntersectMBO/ouroboros-consensus/blob/a9a5f3aaf3ddd45b3dd58a132d65b657bbf285e5/ouroboros-consensus-cardano/src/unstable-shelley-testlib/Test/ThreadNet/Infra/Shelley.hs#L431), which leverages the fact that a single Shelley transaction can demonstrate the necesary quorum for the protocol version increment. + +The key features of these three suites with regard to this document are summarized in the following table. + +| Repository | Byron | Shelley, ..., and/or Babbage | Conway | +| - | - | - | - | +| `cardano-db-sync` | No | Haskell, unsigned | Haskell, unsigned | +| `ouroboros-consensus` | Haskell, signed | Haskell, signed | No | +| `cardano-node-tests` | No | `cardano-cli`, signed | `cardano-cli`, signed | + ## Initializing the Chain with a Later Protocol Version It is often convenient for testnet chains to entirely skip some initial protocol versions.