From fe587c638e68963e9d8d2bdb1cb8cf8b43fac449 Mon Sep 17 00:00:00 2001 From: Jared Corduan Date: Wed, 9 Nov 2022 14:59:41 -0500 Subject: [PATCH] transaction serialization CIP for compatibility --- .../README.md | 116 ++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 CIP-tx-serialization-deprecation-cycles/README.md diff --git a/CIP-tx-serialization-deprecation-cycles/README.md b/CIP-tx-serialization-deprecation-cycles/README.md new file mode 100644 index 0000000000..b85ce06609 --- /dev/null +++ b/CIP-tx-serialization-deprecation-cycles/README.md @@ -0,0 +1,116 @@ +--- +CIP: $\pi$ +Title: Transaction Serialization Deprecation Cycle +Authors: Jared Corduan +Status: Proposed +Category: Ledger +Created: 2022-11-09 +License: CC-BY-4.0 +--- + +## Abstract + +This CIP specifies a policy for the backwards compatibility of the serialization scheme of +Cardano transactions. + +## Motivation + +Transactions on Cardano are sent on the wire using CBOR and are specified with CDDL. +The first scheme was introduced with the Byron phase. +This scheme was changed dramatically with the introduction of the Shelley phase. +As of the time of the writing of this CIP, however, every new scheme has been backwards +compatible with the original scheme from the Shelley phase. +The intention is still to maintain backwards compatibility to the extent reasonable, +and to make explicit our policy for breaking backwards compatibility when deemed necessary. + +## Specification + +Problems with serialization fall into two categories: +* flaws in the implementation +* flaws is the CDDL specification + +Note that at the time of the writing of this CIP, there is only one implementation of the Cardano +node, and we do not yet need to consider inconsistencies between different implementations. + +The policy for maintaining backwards compatibility with the transaction serialization will be +as follows. + +### Serious Flaws + +A **serious flaw** in the serialization is an issue which could have a large and negative impact +on the network, and which requires a hard fork to fix. +These will almost always be problems with the serialization and not the specification. +It is up to human discretion to determine what constitutes a serious flaw, +mostly likely by the core developers. + +Backwards compatibility can be abandoned in the case of a serious flaw, +and **the fix will occur at the next available hard fork**. + +### Non-Serious Flaws + +A **non-serious flaw** in the serialization is an issue which is not safety critical, +but is problematic enough to merit breaking backwards compatibility and requires a +hard fork to fix. +This is again a human judgment. + +Backwards compatibility can be abandoned in the case of a non-serious flaw, +but there must be a deprecation cycle: +* A new format can be introduced at a hard fork, but the old format must be supported for at + least **six months**. After six months, the old format can be abandoned at the next possible + hard fork. + +#### Example + +A good example of a non-serious flaw is the CDDL specification of the transaction output in the +Alonzo ledger era: + +``` +alonzo_transaction_output = [ address, amount : value, ? datum_hash : $hash32 ] +``` + +There is nothing inherently wrong with this scheme, but it caused a problem in the Babbage ledger +era with the addition of inline datums and script references. +In particular, there were two new optional fields, and there was mutual exclusivity. +In order to maintain backwards compatibility, Babbage introduced this scheme: + +``` +transaction_output = alonzo_transaction_output / babbage_transaction_output + +babbage_transaction_output = + { 0 : address + , 1 : value + , ? 2 : [ 0, $hash32 // 1, data ] + , ? 3 : script_ref + } +``` + +In other words, a new format was created, but the legacy format was still supported. +The new format, `babbage_transaction_output`, was introduced 2022-09-22 with the Vasil hard fork, +The old format, `alonzo_transaction_output`, can be retired after 2023-03-22. + +### Summary + +* We should strive to maintain backwards compatibility. +* Serious flaws can be fixed immediately (at the next hard fork), and can break backwards + compatibility. +* Non-Serious flaws can be fixed (at the next hard fork), but the old format + must be supported for at least six months with support ending at the next hard fork event after + the six months have passed. + +## Rationale + +It seems clear that security issues merit breaking backwards compatibility and should be fixed +as soon as possible. +The six month compatibility window for non-serious flaws is mostly +arbitrary, but we need to allow enough time for people to migrate. +It would be great to have more explicit definitions for "serious" and "non-serious" flaws, +but this seems very difficult. + + +## Path to Active + +Not applicable. + +## Copyright + +This CIP is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode)