|
| 1 | +--- |
| 2 | +CIP: 80 |
| 3 | +Title: Transaction Serialization Deprecation Cycle |
| 4 | +Status: Active |
| 5 | +Category: Ledger |
| 6 | +Authors: |
| 7 | + - Jared Corduan <[email protected]> |
| 8 | +Implementors: N/A |
| 9 | +Discussions: |
| 10 | + - https://github.com/cardano-foundation/CIPs/pull/372 |
| 11 | +Created: 2022-11-09 |
| 12 | +License: CC-BY-4.0 |
| 13 | +--- |
| 14 | + |
| 15 | +## Abstract |
| 16 | + |
| 17 | +This CIP specifies a policy for the backwards compatibility of the serialization scheme of |
| 18 | +Cardano transactions. |
| 19 | + |
| 20 | +## Motivation: why is this CIP necessary? |
| 21 | + |
| 22 | +Transactions on Cardano are sent on the wire using CBOR and are specified with CDDL. |
| 23 | +The first scheme was introduced with the Byron phase. |
| 24 | +This scheme was changed dramatically with the introduction of the Shelley phase. |
| 25 | +As of the time of the writing of this CIP, however, every new scheme has been backwards |
| 26 | +compatible with the original scheme from the Shelley phase. |
| 27 | +The intention is still to maintain backwards compatibility to the extent reasonable, |
| 28 | +and to make explicit our policy for breaking backwards compatibility when deemed necessary. |
| 29 | + |
| 30 | +## Specification |
| 31 | + |
| 32 | +Problems with serialization fall into two categories: |
| 33 | +* flaws in the implementation |
| 34 | +* flaws is the CDDL specification |
| 35 | + |
| 36 | +Note that at the time of the writing of this CIP, there is only one implementation of the Cardano |
| 37 | +node, and we do not yet need to consider inconsistencies between different implementations. |
| 38 | + |
| 39 | +The policy for maintaining backwards compatibility with the transaction serialization will be |
| 40 | +as follows. |
| 41 | + |
| 42 | +### Serious Flaws |
| 43 | + |
| 44 | +A **serious flaw** in the serialization is an issue which could have a large and negative impact |
| 45 | +on the network, and which requires a hard fork to fix. |
| 46 | +These will almost always be problems with the serialization and not the specification. |
| 47 | +It is up to human discretion to determine what constitutes a serious flaw, |
| 48 | +mostly likely by the core developers. |
| 49 | + |
| 50 | +Backwards compatibility can be abandoned in the case of a serious flaw, |
| 51 | +and **the fix will occur at the next available hard fork**. |
| 52 | + |
| 53 | +### Non-Serious Flaws |
| 54 | + |
| 55 | +A **non-serious flaw** in the serialization is an issue which is not safety critical, |
| 56 | +but is problematic enough to merit breaking backwards compatibility. |
| 57 | +This is again a human judgment. |
| 58 | + |
| 59 | +Backwards compatibility can be abandoned in the case of a non-serious flaw, |
| 60 | +but there must be a deprecation cycle: |
| 61 | +* In the case of a **soft fork** (meaning that the change is backwards incompatible for |
| 62 | + block producers but *not* block validators), |
| 63 | + a new format can be introduced at the next major or minor protocol version, |
| 64 | + at which time the old format can be abandoned. |
| 65 | +* In the case of a **hard fork** (meaning that the change is backwards incompatible for |
| 66 | + both block producers and block validators), |
| 67 | + a new format can be introduced at the next major protocol version, |
| 68 | + but the old format must be supported for at least **six months**. |
| 69 | + After six months, the old format can be abandoned at the next possible fork. |
| 70 | + |
| 71 | +#### Examples |
| 72 | + |
| 73 | +A good example of a non-serious flaw is the CDDL specification of the transaction output in the |
| 74 | +Alonzo ledger era: |
| 75 | + |
| 76 | +``` |
| 77 | +alonzo_transaction_output = [ address, amount : value, ? datum_hash : $hash32 ] |
| 78 | +``` |
| 79 | + |
| 80 | +There is nothing inherently wrong with this scheme, but it caused a problem in the Babbage ledger |
| 81 | +era with the addition of inline datums and script references. |
| 82 | +In particular, there were two new optional fields, and there was mutual exclusivity. |
| 83 | +In order to maintain backwards compatibility, Babbage introduced this scheme: |
| 84 | + |
| 85 | +``` |
| 86 | +transaction_output = alonzo_transaction_output / babbage_transaction_output |
| 87 | +
|
| 88 | +babbage_transaction_output = |
| 89 | + { 0 : address |
| 90 | + , 1 : value |
| 91 | + , ? 2 : [ 0, $hash32 // 1, data ] |
| 92 | + , ? 3 : script_ref |
| 93 | + } |
| 94 | +``` |
| 95 | + |
| 96 | +In other words, a new format was created, but the legacy format was still supported. |
| 97 | +The new format, `babbage_transaction_output`, was introduced 2022-09-22 with the Vasil hard fork, |
| 98 | +The old format, `alonzo_transaction_output`, can be retired after 2023-03-22. |
| 99 | + |
| 100 | +Note that this example required a **hard fork**. |
| 101 | + |
| 102 | +A good example of a non-serious flaw requiring a **soft fork** is the removal |
| 103 | +of zero-valued multi-assets in the mint field of the transaction body. |
| 104 | + |
| 105 | +In the Babbage ledger era, a multi-asset value was defined as: |
| 106 | + |
| 107 | +``` |
| 108 | +value = coin / [coin,multiasset<uint>] |
| 109 | +``` |
| 110 | + |
| 111 | +Zero values can be confusing inside of things like explorers, so in the Conway era they are removed: |
| 112 | + |
| 113 | +``` |
| 114 | +natNum = 1 .. 4294967295 |
| 115 | +value = coin / [coin,multiasset<natNum>] |
| 116 | +``` |
| 117 | + |
| 118 | +Notice that block validators will not notice this change, though block producers will notice it. |
| 119 | + |
| 120 | +### Summary |
| 121 | + |
| 122 | +* We should strive to maintain backwards compatibility. |
| 123 | +* Serious flaws can be fixed immediately (at the next hard fork), and can break backwards |
| 124 | + compatibility. |
| 125 | +* Non-Serious flaws can be fixed (at the next hard fork), but the old format |
| 126 | + must be supported for at least six months with support ending at the next hard fork event after |
| 127 | + the six months have passed. |
| 128 | + |
| 129 | +## Rationale: how does this CIP achieve its goals? |
| 130 | + |
| 131 | +It seems clear that security issues merit breaking backwards compatibility and should be fixed |
| 132 | +as soon as possible. |
| 133 | +The six month compatibility window for non-serious flaws is mostly |
| 134 | +arbitrary, but we need to allow enough time for people to migrate. |
| 135 | +It would be great to have more explicit definitions for "serious" and "non-serious" flaws, |
| 136 | +but this seems very difficult. |
| 137 | + |
| 138 | +## Path to Active |
| 139 | + |
| 140 | +### Acceptance criteria |
| 141 | + |
| 142 | +- [x] The proposal is accepted and recognized by the ledger team. |
| 143 | + |
| 144 | +### Implementation plan |
| 145 | + |
| 146 | +N/A |
| 147 | + |
| 148 | +## Copyright |
| 149 | + |
| 150 | +This CIP is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode) |
0 commit comments