ADR-016 Backwards and Forwards Compatibility #79

Jimbo4350 · 2025-10-09T13:11:42Z

No description provided.

palas

Looks good 👍. I just wrote some suggestions to improve readability

palas · 2025-10-09T14:03:29Z

docs/ADR-016-Backwards-and-Forwards-Compatibility.md

+
+I will make this clearer with an example below.
+
+**NB**: We will only implement functionality constrained by `IsShelleyBasedEra era` and `IsEra era` that either is currently exposed by the "old" api or specifically required by QA. If we do not need backwards compatibility then we will use`Era era` or `IsEra era` without implementing an additional type synonym family.


Suggested change

**NB**: We will only implement functionality constrained by `IsShelleyBasedEra era` and `IsEra era` that either is currently exposed by the "old" api or specifically required by QA. If we do not need backwards compatibility then we will use`Era era` or `IsEra era` without implementing an additional type synonym family.

**NB**: We will only implement functionality constrained by `IsShelleyBasedEra era` and `IsEra era` that either is currently exposed by the "old" api or specifically required by QA. If we do not need backwards compatibility then we will use `Era era` or `IsEra era` without implementing an additional type synonym family.

There is no space between "use" and "Era era"

palas · 2025-10-09T14:39:41Z

docs/ADR-016-Backwards-and-Forwards-Compatibility.md

+          Ledger.mkDelegTxCert (Api.toShelleyStakeCredential sCred) delegatee
+
+
+--- BELOW IS IN A SEPARATE "COMPATIBLE" MODULE DESIGNED FOR BACKWARDS COMPATIBILITY.


This already implies that the function above is not backwards compatible, but I would say it explicitly, so that the difference is more obvious to the reader. I would even explicitly say that IsEra constrains to the latest two eras while IsShelleyBasedEra doesn't and thus provides backwards compatibility.
Also both versions could be in two separate Haskell code blocks.

palas · 2025-10-09T14:44:39Z

docs/ADR-016-Backwards-and-Forwards-Compatibility.md

+-- The `StakeDelegationRequirements era` GADT will necessitate more data constructors if there are any changes to the requirements of stake delegation in future eras. 
+-- This is already seen in the transition from Babbage (can only delegate to stake pools) -> Conway (can delegate to stake pools and dreps). 
+-- This obviously does not scale in the face of possible incoming changes and requires the propagation of an additional data constructor.
+
+-- I propose the following:


These comments could be unquoted. I think that would make it easier to parse

palas · 2025-10-09T14:46:36Z

docs/ADR-016-Backwards-and-Forwards-Compatibility.md

+    -> Certificate era
+``` 
+
+`Cardano.Api.Certificate` exposes several helper functions that use this "old" type. E.g `makeStakeAddressDelegationCertificate`, `makeStakeAddressRegistrationCertificate` and `makeStakeAddressUnregistrationCertificate` to name a few. All of these "old" functions will be deprecated in favour of a new API that allows us to expose functionality from any era required without adding significant boilerplate as seen in the above definition of `data Certificate era`. We achieve this by the following:


Why not link to IntersectMBO/cardano-api#962 as an example. The inline example is much better, but still, being able to easily check the other one could help too.

palas · 2025-10-09T14:55:19Z

docs/ADR-016-Backwards-and-Forwards-Compatibility.md

+
+## Proposed Solution
+
+The solution proposed below is specific to certificates but can be expanded to any era depdendent type.


Suggested change

The solution proposed below is specific to certificates but can be expanded to any era depdendent type.

The solution proposed below is specific to certificates but can be expanded to any era dependent type.

carbolymer · 2025-10-15T15:49:27Z

docs/ADR-016-Backwards-and-Forwards-Compatibility.md

+
+I will make this clearer with an example below.
+
+**NB**: We will only implement functionality constrained by `IsShelleyBasedEra era` and `IsEra era` that either is currently exposed by the "old" api or specifically required by QA. If we do not need backwards compatibility then we will use`Era era` or `IsEra era` without implementing an additional type synonym family.


Suggestion: use [!NOTE] admonition instead of NB https://github.com/orgs/community/discussions/16925 for better visual separation.

carbolymer · 2025-10-15T16:04:17Z

docs/ADR-016-Backwards-and-Forwards-Compatibility.md

+  :: forall era
+   . IsShelleyBasedEra era
+  => StakeCredential
+  -> Delegatee era


Suggested change

-> Delegatee era

-> Delegatee (LedgerEra era)

carbolymer · 2025-10-15T16:04:32Z

docs/ADR-016-Backwards-and-Forwards-Compatibility.md

+  :: forall era
+   . IsEra era
+  => StakeCredential
+  -> Delegatee era


Suggested change

-> Delegatee era

-> Delegatee (LedgerEra era)

carbolymer · 2025-10-15T16:05:05Z

docs/ADR-016-Backwards-and-Forwards-Compatibility.md

+`Cardano.Api.Certificate` exposes several helper functions that use this "old" type. E.g `makeStakeAddressDelegationCertificate`, `makeStakeAddressRegistrationCertificate` and `makeStakeAddressUnregistrationCertificate` to name a few. All of these "old" functions will be deprecated in favour of a new API that allows us to expose functionality from any era required without adding significant boilerplate as seen in the above definition of `data Certificate era`. We achieve this by the following:
+
+
+Replace era-variant GADTs (like Certificate era) with a uniform wrapper (Certificate :: L.TxCert era -> Certificate era) and using open type families to resolve era-specific types (e.g., Delegatee era). Era constraints (IsEra, IsShelleyBasedEra) gate access to functionality.


using open type families to resolve era-specific types (e.g., Delegatee era)

The example below uses a closed type family Delegatee era. What's the final choice, and why?

carbolymer · 2025-10-15T16:22:03Z

docs/ADR-016-Backwards-and-Forwards-Compatibility.md

+  Delegatee ConwayEra = Ledger.Delegatee
+  Delegatee BabbageEra = Api.Hash Api.StakePoolKey
+  Delegatee AlonzoEra = Api.Hash Api.StakePoolKey 
+  ... 
+  ...
+  Delegate ShelleyEra = Api.Hash Api.StakePoolKey


Suggested change

Delegatee ConwayEra = Ledger.Delegatee

Delegatee BabbageEra = Api.Hash Api.StakePoolKey

Delegatee AlonzoEra = Api.Hash Api.StakePoolKey

...

...

Delegate ShelleyEra = Api.Hash Api.StakePoolKey

Delegatee L.ConwayEra = Ledger.Delegatee

Delegatee L.BabbageEra = Api.Hash Api.StakePoolKey

Delegatee L.AlonzoEra = Api.Hash Api.StakePoolKey

...

...

Delegate L.ShelleyEra = Api.Hash Api.StakePoolKey

Delegatee is a part of the experimental (new) API so I think we should be using ledger eras.

ADR-016 Backwards and Forwards Compatibility

7ff13bb

Jimbo4350 requested review from carbolymer, newhoggy and palas as code owners October 9, 2025 13:11

palas approved these changes Oct 9, 2025

View reviewed changes

carbolymer reviewed Oct 15, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

ADR-016 Backwards and Forwards Compatibility #79

ADR-016 Backwards and Forwards Compatibility #79

Uh oh!

Jimbo4350 commented Oct 9, 2025

Uh oh!

palas left a comment

Uh oh!

palas Oct 9, 2025

Uh oh!

palas Oct 9, 2025 •

edited

Loading

Uh oh!

palas Oct 9, 2025 •

edited

Loading

Uh oh!

palas Oct 9, 2025

Uh oh!

palas Oct 9, 2025

Uh oh!

carbolymer Oct 15, 2025 •

edited

Loading

Uh oh!

carbolymer Oct 15, 2025

Uh oh!

carbolymer Oct 15, 2025

Uh oh!

carbolymer Oct 15, 2025 •

edited

Loading

Uh oh!

carbolymer Oct 15, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		I will make this clearer with an example below.

		NB: We will only implement functionality constrained by `IsShelleyBasedEra era` and `IsEra era` that either is currently exposed by the "old" api or specifically required by QA. If we do not need backwards compatibility then we will use`Era era` or `IsEra era` without implementing an additional type synonym family.

		Ledger.mkDelegTxCert (Api.toShelleyStakeCredential sCred) delegatee


		--- BELOW IS IN A SEPARATE "COMPATIBLE" MODULE DESIGNED FOR BACKWARDS COMPATIBILITY.


		## Proposed Solution

		The solution proposed below is specific to certificates but can be expanded to any era depdendent type.

		`Cardano.Api.Certificate` exposes several helper functions that use this "old" type. E.g `makeStakeAddressDelegationCertificate`, `makeStakeAddressRegistrationCertificate` and `makeStakeAddressUnregistrationCertificate` to name a few. All of these "old" functions will be deprecated in favour of a new API that allows us to expose functionality from any era required without adding significant boilerplate as seen in the above definition of `data Certificate era`. We achieve this by the following:


		Replace era-variant GADTs (like Certificate era) with a uniform wrapper (Certificate :: L.TxCert era -> Certificate era) and using open type families to resolve era-specific types (e.g., Delegatee era). Era constraints (IsEra, IsShelleyBasedEra) gate access to functionality.

ADR-016 Backwards and Forwards Compatibility #79

Are you sure you want to change the base?

ADR-016 Backwards and Forwards Compatibility #79

Uh oh!

Conversation

Jimbo4350 commented Oct 9, 2025

Uh oh!

palas left a comment

Choose a reason for hiding this comment

Uh oh!

palas Oct 9, 2025

Choose a reason for hiding this comment

Uh oh!

palas Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

palas Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

palas Oct 9, 2025

Choose a reason for hiding this comment

Uh oh!

palas Oct 9, 2025

Choose a reason for hiding this comment

Uh oh!

carbolymer Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

carbolymer Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

carbolymer Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

carbolymer Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

carbolymer Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

palas Oct 9, 2025 •

edited

Loading

palas Oct 9, 2025 •

edited

Loading

carbolymer Oct 15, 2025 •

edited

Loading

carbolymer Oct 15, 2025 •

edited

Loading