wip

docs/ADR-4-Support-only-for-mainnet-and-upcoming-eras.md

@@ -6,7 +6,8 @@
 
 ## Background
 
-In the cardano blockchain, available functionality is determined by the era (more precisely the protocol version). To capture this we defined the following types<sup>1, 2</sup>:
+In the cardano blockchain, available functionality is determined by the era (more precisely the protocol version).
+To capture this we defined the following types<sup>1, 2</sup>:
 ```haskell
 data ShelleyBasedEra era where
   ShelleyBasedEraShelley :: ShelleyBasedEra ShelleyEra
@@ -26,11 +27,16 @@ data CardanoEra era where
   ConwayEra :: CardanoEra ConwayEra
 
 ```
-Early on the idea was to parameterize functions on the era so they can have the era specific behaviour but also to capture this idea of backwards compatibility. In the Shelley era days, there was an (incorrect) assumption that later eras would be backwards compatible with previous eras, especially where transactions were concerned. This would have allowed users to in theory never update their `cardano-cli` version however this is not the case as hardforks introduce backwards incompatible changes (see Conway breaking changes as an example).
+Early on the idea was to parameterize functions on the era so they can have the era specific behaviour but also to capture this idea of backwards compatibility.
+In the Shelley era days, there was an (incorrect) assumption that later eras would be backwards compatible with previous eras, especially where transactions were concerned.
+This would have allowed users to in theory never update their `cardano-cli` version however this is not the case as hardforks introduce backwards incompatible changes (see Conway breaking changes as an example).
 
-The other justification for enumerating the eras like this was to allow QA to perform testing across all eras. However, the only test QA performs across the eras are hardforks. Therefore we don't need to expose all the era specific functionality for each era, rather we need to maintain the ability to submit hardfork update proposals across the eras i.e Byron -> latest era. 
+The other justification for enumerating the eras like this was to allow QA to perform testing across all eras.
+However, the only test QA performs across the eras are hardforks.
+Therefore we don't need to expose all the era specific functionality for each era, rather we need to maintain the ability to submit hardfork update proposals across the eras i.e Byron -> latest era. 
 
-Users consuming `cardano-api` are only interested in functionality relevant to mainnet and the upcoming era if they want to experiment with new features on a testnet. Therefore rather than maintaining a potentially never ending enumeration of eras, I propose to maintain only the era on mainnet and the upcoming era that will be hardforked to in the future.
+Users consuming `cardano-api` are only interested in functionality relevant to mainnet and the upcoming era if they want to experiment with new features on a testnet.
+Therefore rather than maintaining a potentially never ending enumeration of eras, I propose to maintain only the era on mainnet and the upcoming era that will be hardforked to in the future.
 
 ## Code 
 
@@ -53,19 +59,11 @@ type family AvailableErasToSbe era = (r :: Type) | r -> era where
 
 
 data Era era where
+  -- | Deprecated era, Do not use.
+  BabbageEra :: Era BabbageEra
   -- | The era currently active on Cardano's mainnet.
-  CurrentEra ::  Era BabbageEra
-  -- | The era planned for the next hardfork on Cardano's mainnet.
-  UpcomingEra :: Era ConwayEra
-
--- | After a hardfork there is usually no planned upcoming era
--- that we are able to experiment with. We force a type era
--- in this instance. See docs above.
-data EraCurrentlyNonExistent
-
-type family UninhabitableType a where
-  UninhabitableType EraCurrentlyNonExistent =
-    TypeError ('Text "There is currently no planned upcoming era. Use CurrentEra constructor instead.")
+  ConwayEra :: Era ConwayEra
+
 ```
 
 ### Deprecation as seen by users 
@@ -86,13 +84,14 @@ makeUnsignedTx era bc = ...
 
 
 testBabbageUnsignedTx :: Either UnsignedTxError (UnsignedTx BabbageEra)
-testBabbageUnsignedTx = makeUnsignedTx CurrentEra $ defaultTxBodyContent ShelleyBasedEraBabbage
+testBabbageUnsignedTx = makeUnsignedTx BabbageEra $ defaultTxBodyContent ShelleyBasedEraBabbage
 
 testConwayUnsignedTx :: Either UnsignedTxError (UnsignedTx ConwayEra)
-testConwayUnsignedTx = makeUnsignedTx UpcomingEra $ defaultTxBodyContent ShelleyBasedEraConway
+testConwayUnsignedTx = makeUnsignedTx ConwayEra $ defaultTxBodyContent ShelleyBasedEraConway
 ```
 
-In the current state of affairs both `testBabbageUnsignedTx` and `testConwayUnsignedTx` type check without issue. However let's update the types to show how a deprecation (or a successful hardfork to the upcoming era) will show up in a user's code.
+In the current state of affairs both `testBabbageUnsignedTx` and `testConwayUnsignedTx` type check without issue.
+However let's update the types to show how a deprecation (or a successful hardfork to the upcoming era) will show up in a user's code.
 
 Changes:
 
@@ -102,32 +101,22 @@ data BabbageEra
 ...
 ...
 data Era era where
+  -- | Previous era, do not use.
+  BabbageEra :: Era BabbageEra
   -- | The era currently active on Cardano's mainnet.
-  CurrentEra ::  Era ConwayEra
-  -- | The era planned for the next hardfork on Cardano's mainnet.
-  UpcomingEra :: Era (UninhabitableType EraCurrentlyNonExistent)
+  ConwayEra ::  Era ConwayEra
 ```
-Type errors:
 
-```haskell
+Type error:
+```
 In the use of type constructor or class ‘BabbageEra’
 (imported from Cardano.Api.Experimental.Eras, but defined in Cardano.Api.Protocol.AvailableEras):
 Deprecated: "We are currently in the Conway era. Please update your type Signature to ConwayEra"
-
-and
-
-internal/Cardano/Api/Experimental/Tx.hs:34:39: error: [GHC-64725]
-    • There is currently no planned upcoming era. Use CurrentEra instead.
-    • In the first argument of ‘makeUnsignedTx’, namely ‘UpcomingEra’
-      In the first argument of ‘($)’, namely ‘makeUnsignedTx UpcomingEra’
-      In the expression:
-        makeUnsignedTx UpcomingEra
-          $ defaultTxBodyContent ShelleyBasedEraConway
-   |
-34 | testConwayUnsignedTx = makeUnsignedTx UpcomingEra $ defaultTxBodyContent ShelleyBasedEraConway
 ```
 
-This deprecation will happen only after the hardfork has been successful. There should be no need for consumers of the api to need the prior era's specific functionality. If users for some reason want this, we can direct them to use the ledger's api directly.
+This deprecation will happen only after the hardfork has been successful.
+There should be no need for consumers of the api to need the prior era's specific functionality.
+If users for some reason want this, we can direct them to use the ledger's api directly.
 
 ## Downsides
 
@@ -136,14 +125,12 @@ Because we are using GADTs our library functions will have unreachable code path
 ### Deprecation as seen by cardano-api maintainers
 
 Before deprecation:
-
 ```haskell
-
 testBabbageEra :: Either UnsignedTxError (Ledger.TxBody (ToConstrainedEra BabbageEra))
-testBabbageEra = eraSpecificLedgerTxBody CurrentEra undefined $ defaultTxBodyContent ShelleyBasedEraBabbage
+testBabbageEra = eraSpecificLedgerTxBody BabbageEra undefined $ defaultTxBodyContent ShelleyBasedEraBabbage
 
 testConwayEra :: Either UnsignedTxError (Ledger.TxBody (ToConstrainedEra ConwayEra))
-testConwayEra = eraSpecificLedgerTxBody UpcomingEra undefined $ defaultTxBodyContent ShelleyBasedEraConway
+testConwayEra = eraSpecificLedgerTxBody ConwayEra undefined $ defaultTxBodyContent ShelleyBasedEraConway
 
 
 eraSpecificLedgerTxBody
@@ -250,7 +237,8 @@ internal/Cardano/Api/Experimental/Tx.hs:132:13: error: [GHC-64725]
 132 |           & L.proposalProceduresTxBodyL .~ convProposalProcedures (maybe TxProposalProceduresNone unFeatured propProcedures)
 ```
 
-We get somewhat obscure type errors but this should not be an issue as this is a direct result of deprecating an era in cardano-api. We know we have to update our functions because of this, so it comes as no surprise
+We get somewhat obscure type errors but this should not be an issue as this is a direct result of deprecating an era in cardano-api.
+We know we have to update our functions because of this, so it comes as no surprise
 
 However downstream users get better type eras:
 
@@ -349,9 +337,12 @@ ghci> eraSpecificLedgerTxBody UpcomingEra undefined undefined
 
 # Approach
 
-The new api should be created adjacant to the existing one. We then slowly replace the use of the existing api in cardano-api, eventually deprecating the "old" api. 
+The new api should be created adjacant to the existing one.
+We then slowly replace the use of the existing api in cardano-api, eventually deprecating the "old" api. 
 
-With respect to cardano-cli, we should introduce top level `current-era` and `upcoming-era` commands. We would have to release a cli version specific for post-hardfork usage, as `current-era` and `upcoming-era` commands will have different semantics to the pre-hardfork commands. This will require a little coordination but shouldn't be too much additional overhead. 
+With respect to cardano-cli, we should introduce top level `current-era` and `upcoming-era` commands.
+We would have to release a cli version specific for post-hardfork usage, as `current-era` and `upcoming-era` commands will have different semantics to the pre-hardfork commands.
+This will require a little coordination but shouldn't be too much additional overhead. 
 # Decision
 
 TBD