From 8fa6210dd4c4c3bc83cb7a95017ca79c0040d3fd Mon Sep 17 00:00:00 2001 From: Jared Corduan Date: Wed, 9 Nov 2022 14:59:41 -0500 Subject: [PATCH 1/7] 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 000000000..b85ce0660 --- /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) From ace1363eebf895e4e90cc10e0f3a4b1caddab643 Mon Sep 17 00:00:00 2001 From: Jared Corduan Date: Wed, 30 Nov 2022 08:27:45 -0500 Subject: [PATCH 2/7] assign CIP number 80 Co-authored-by: Matthias Benkort <5680256+KtorZ@users.noreply.github.com> --- CIP-tx-serialization-deprecation-cycles/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-tx-serialization-deprecation-cycles/README.md b/CIP-tx-serialization-deprecation-cycles/README.md index b85ce0660..9a21b253f 100644 --- a/CIP-tx-serialization-deprecation-cycles/README.md +++ b/CIP-tx-serialization-deprecation-cycles/README.md @@ -1,5 +1,5 @@ --- -CIP: $\pi$ +CIP: 80 Title: Transaction Serialization Deprecation Cycle Authors: Jared Corduan Status: Proposed From 3f928b3eac56404792a17b09679bdb3a02d00c51 Mon Sep 17 00:00:00 2001 From: Jared Corduan Date: Mon, 30 Jan 2023 15:52:08 -0500 Subject: [PATCH 3/7] separated hard and soft fork requirements --- .../README.md | 42 +++++++++++++++---- 1 file changed, 34 insertions(+), 8 deletions(-) diff --git a/CIP-tx-serialization-deprecation-cycles/README.md b/CIP-tx-serialization-deprecation-cycles/README.md index 9a21b253f..8b8409935 100644 --- a/CIP-tx-serialization-deprecation-cycles/README.md +++ b/CIP-tx-serialization-deprecation-cycles/README.md @@ -1,9 +1,10 @@ --- CIP: 80 Title: Transaction Serialization Deprecation Cycle -Authors: Jared Corduan Status: Proposed Category: Ledger +Authors: Jared Corduan +Implementors: N/A Created: 2022-11-09 License: CC-BY-4.0 --- @@ -49,17 +50,22 @@ 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. +but is problematic enough to merit breaking backwards compatibility. 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 +* In the case of a **soft fork** (meaning that the change is backwards incompatible for + block producers but *not* block validators), + a new format can be introduced at the next major or minor protocol version, + at which time the old format can be abandoned. +* In the case of a **hard fork** (meaning that the change is backwards incompatible for + both block producers and block validators), + a new format can be introduced at the next major protocol version, + 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 fork. + +#### Examples A good example of a non-serious flaw is the CDDL specification of the transaction output in the Alonzo ledger era: @@ -88,6 +94,26 @@ In other words, a new format was created, but the legacy format was still suppor 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. +Note that this example required a **hard fork**. + +A good example of a non-serious flaw requiring a **soft fork** is the removal +of zero-valued multi-assets in the mint field of the transaction body. + +In the Babbage ledger era, a multi-asset value was defined as: + +``` +value = coin / [coin,multiasset] +``` + +Zero values can be confusing inside of things like explorers, so in the Conway era they are removed: + +``` +natNum = 1 .. 4294967295 +value = coin / [coin,multiasset] +``` + +Notice that block validators will not notice this change, though block producers will notice it. + ### Summary * We should strive to maintain backwards compatibility. From 3799cf25aaf40ca9fc628480a6d8759c755d0d04 Mon Sep 17 00:00:00 2001 From: Matthias Benkort <5680256+KtorZ@users.noreply.github.com> Date: Sat, 18 Mar 2023 11:27:35 +0100 Subject: [PATCH 4/7] Update CIP-tx-serialization-deprecation-cycles/README.md --- CIP-tx-serialization-deprecation-cycles/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CIP-tx-serialization-deprecation-cycles/README.md b/CIP-tx-serialization-deprecation-cycles/README.md index 8b8409935..561bc7c24 100644 --- a/CIP-tx-serialization-deprecation-cycles/README.md +++ b/CIP-tx-serialization-deprecation-cycles/README.md @@ -1,9 +1,10 @@ --- CIP: 80 Title: Transaction Serialization Deprecation Cycle -Status: Proposed +Status: Active Category: Ledger -Authors: Jared Corduan +Authors: + - Jared Corduan Implementors: N/A Created: 2022-11-09 License: CC-BY-4.0 From 3e266aa584f966d1c446a4eefd2f68bdad0062e8 Mon Sep 17 00:00:00 2001 From: KtorZ Date: Sat, 18 Mar 2023 11:29:26 +0100 Subject: [PATCH 5/7] Move CIP-0080 in its dedicated folder. --- {CIP-tx-serialization-deprecation-cycles => CIP-0080}/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename {CIP-tx-serialization-deprecation-cycles => CIP-0080}/README.md (99%) diff --git a/CIP-tx-serialization-deprecation-cycles/README.md b/CIP-0080/README.md similarity index 99% rename from CIP-tx-serialization-deprecation-cycles/README.md rename to CIP-0080/README.md index 561bc7c24..3597b99c8 100644 --- a/CIP-tx-serialization-deprecation-cycles/README.md +++ b/CIP-0080/README.md @@ -3,7 +3,7 @@ CIP: 80 Title: Transaction Serialization Deprecation Cycle Status: Active Category: Ledger -Authors: +Authors: - Jared Corduan Implementors: N/A Created: 2022-11-09 From bac50322a9206adda27f936f1eee69fa702bbc4d Mon Sep 17 00:00:00 2001 From: KtorZ Date: Sat, 18 Mar 2023 11:31:56 +0100 Subject: [PATCH 6/7] Minor edits - Add discussions - Add subtitles to 'Motivation' & 'Rationale' - Fix 'Path to Active' section. --- CIP-0080/README.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/CIP-0080/README.md b/CIP-0080/README.md index 3597b99c8..82aac4dbd 100644 --- a/CIP-0080/README.md +++ b/CIP-0080/README.md @@ -6,6 +6,8 @@ Category: Ledger Authors: - Jared Corduan Implementors: N/A +Discussions: + - https://github.com/cardano-foundation/CIPs/pull/372 Created: 2022-11-09 License: CC-BY-4.0 --- @@ -15,7 +17,7 @@ License: CC-BY-4.0 This CIP specifies a policy for the backwards compatibility of the serialization scheme of Cardano transactions. -## Motivation +## Motivation: why is this CIP necessary? Transactions on Cardano are sent on the wire using CBOR and are specified with CDDL. The first scheme was introduced with the Byron phase. @@ -124,7 +126,7 @@ Notice that block validators will not notice this change, though block producers must be supported for at least six months with support ending at the next hard fork event after the six months have passed. -## Rationale +## Rationale: how does this CIP achieve its goals? It seems clear that security issues merit breaking backwards compatibility and should be fixed as soon as possible. @@ -133,10 +135,15 @@ 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. +### Acceptance criteria + +- [x] The proposal is accepted and recognized by the ledger team. + +### Implementation plan + +N/A ## Copyright From 34000183a51ad09b58cc85fe8889f1dcc349757d Mon Sep 17 00:00:00 2001 From: KtorZ Date: Sat, 18 Mar 2023 11:33:52 +0100 Subject: [PATCH 7/7] Update top-level README with CIP-0080 inclusion. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 341550133..aaa9fbcc1 100644 --- a/README.md +++ b/README.md @@ -76,6 +76,7 @@ CIP Editors meetings are public, recorded, and [published on Youtube](https://ww | 68 | [Datum Metadata Standard](./CIP-0068) | Proposed | | 71 | [Non-Fungible Token (NFT) Proxy Voting Standard](./CIP-0071) | Proposed | | 74 | [Set min-pool-cost to 0](./CIP-0074) | Proposed | +| 80 | [Transaction Serialization Deprecation Cycle](./CIP-0080) | Active | | 83 | [Encrypted Transaction message/comment metadata (Addendum to CIP-0020)](./CIP-0083) | Active | | 381 | [Plutus Support for Pairings Over BLS12-381](./CIP-0381) | Proposed | | 1852 | [HD (Hierarchy for Deterministic) Wallets for Cardano](./CIP-1852/) | Active | @@ -111,7 +112,6 @@ Below are listed tentative CIPs still under discussion with the community. They | 77? | [Verified Stake Pool Identity](https://github.com/cardano-foundation/CIPs/pull/361) | | 78? | [Extended Local Chain Sync Protocol](https://github.com/cardano-foundation/CIPs/pull/375) | | 79? | [Implement Ouroboros Leios to increase Cardano throughput](https://github.com/cardano-foundation/CIPs/pull/379) | -| 80? | [Transaction Serialization Deprecation Cycle](https://github.com/cardano-foundation/CIPs/pull/372) | | 81? | [Tiered Pricing Protocol](https://github.com/cardano-foundation/CIPs/pull/381) | 82? | [Improved Rewards Scheme Parameters](https://github.com/cardano-foundation/CIPs/pull/422) | | 84? | [Cardano Ledger Evolution](https://github.com/cardano-foundation/CIPs/pull/456) |