From 4e49f06c743293e1881fb82222571f489d602201 Mon Sep 17 00:00:00 2001 From: SIDANWhatever Date: Wed, 29 Oct 2025 14:13:20 +0000 Subject: [PATCH 01/12] init for canonical cbor ser standard --- CPS-?/README.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 CPS-?/README.md diff --git a/CPS-?/README.md b/CPS-?/README.md new file mode 100644 index 0000000000..becc6d8514 --- /dev/null +++ b/CPS-?/README.md @@ -0,0 +1,50 @@ +--- +CPS: ? +Title: Canonical CBOR Serialization Standard +Category: Tools, Wallets, Ledger +Status: Open +Authors: + - Hinson Wong + - Tsz Wai Wu +Proposed Solutions: [] +Discussions: + - https://github.com/cardano-foundation/CIPs/pull/? +Created: 2025-10-29 +License: CC-BY-4.0 +--- + +## Abstract + + + +## Problem + + + +## Use cases + + + +## Goals + + + +## Open Questions + + + + + +## Copyright + + + + + From 6078531aa51e8d516119d41fc177b6e3acde7a40 Mon Sep 17 00:00:00 2001 From: SIDANWhatever Date: Wed, 29 Oct 2025 14:36:42 +0000 Subject: [PATCH 02/12] update content --- CPS-?/README.md | 50 ------------------------------- CPS-????/README.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 75 insertions(+), 50 deletions(-) delete mode 100644 CPS-?/README.md create mode 100644 CPS-????/README.md diff --git a/CPS-?/README.md b/CPS-?/README.md deleted file mode 100644 index becc6d8514..0000000000 --- a/CPS-?/README.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -CPS: ? -Title: Canonical CBOR Serialization Standard -Category: Tools, Wallets, Ledger -Status: Open -Authors: - - Hinson Wong - - Tsz Wai Wu -Proposed Solutions: [] -Discussions: - - https://github.com/cardano-foundation/CIPs/pull/? -Created: 2025-10-29 -License: CC-BY-4.0 ---- - -## Abstract - - - -## Problem - - - -## Use cases - - - -## Goals - - - -## Open Questions - - - - - -## Copyright - - - - - diff --git a/CPS-????/README.md b/CPS-????/README.md new file mode 100644 index 0000000000..a8ce8ec07a --- /dev/null +++ b/CPS-????/README.md @@ -0,0 +1,75 @@ +--- +CPS: ? +Title: Canonical CBOR Serialization Standard +Category: Tools, Wallets, Ledger +Status: Open +Authors: + - Hinson Wong + - Tsz Wai Wu +Proposed Solutions: [] +Discussions: + - https://github.com/cardano-foundation/CIPs/pull/? +Created: 2025-10-29 +License: CC-BY-4.0 +--- + +## Abstract + +There is no canonical CBOR serialization standard in Cardano. While this is a delibrate design choice initially, standardizing it has growing popularity in Cardano developer community as evidenced by developer meetups such as Cardano Builder Fest 2025 hosted in Vietnam. This CPS outlines the motivation of the growing concern of fragmented CBOR serialization patterns across in the community. + +## Problem + + + +Unstandardized CBOR serialization has hindered the progress for Cardano developers community for a long time. While it allows higher flexibility of tool chain selection, it caused community overheads + +- Wallet sign tx change the tx body +- Unpredictable transaction building +- Difference in script serialzation + +## Use cases + + + +- Developers can switch across libraries and tools and yield a predictable result + +## Goals + + + +Solving this CPS means: + +1. There is a CIP specifying guidance on standardizing Cardano CBOR serialization. + +2. The community, naming serialization libraries and wallets are aware of the standard and comply accordingly. + +3. Optional: If we deemed the standard should be enforced, the standard is then implemented on the ledger. + +A good solution should consist of both a well crafted standard with clear guiding principle, carrying our the comprehensive `Path to Active`. + +## Open Questions + + + + + +### Should we enforce it in ledger? + +- Not enforcing: difficult to make wider tooling community comply with it +- Enforcing: backward compatibility issue, might not be practical to do so + +### What are the guiding principles to decide the standard? + +Some possible dimensions: + +- Efficiency: whichever producing smallest size of transaction +- Friction: whichever more adapted in current community +- etc + +## Copyright + +This CPS is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). From 19e6edcf83b15ae67a69a0e3e3dd60560931b79d Mon Sep 17 00:00:00 2001 From: twwu123 Date: Wed, 29 Oct 2025 14:50:10 +0000 Subject: [PATCH 03/12] updates for cbor encoding standard --- CPS-????/README.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/CPS-????/README.md b/CPS-????/README.md index a8ce8ec07a..37bec0aa07 100644 --- a/CPS-????/README.md +++ b/CPS-????/README.md @@ -32,6 +32,7 @@ Unstandardized CBOR serialization has hindered the progress for Cardano develope - Developers can switch across libraries and tools and yield a predictable result +- It is possible for serialization libraries to worry about only one way of serialization, deserialization would also become easier to maintain ## Goals @@ -45,9 +46,9 @@ Solving this CPS means: 1. There is a CIP specifying guidance on standardizing Cardano CBOR serialization. -2. The community, naming serialization libraries and wallets are aware of the standard and comply accordingly. +2. The community, namely serialization libraries and wallets are aware of the standard and comply accordingly. -3. Optional: If we deemed the standard should be enforced, the standard is then implemented on the ledger. +3. Optional: If the standard is deemed to be worth enforcing, the standard is then implemented on the ledger. A good solution should consist of both a well crafted standard with clear guiding principle, carrying our the comprehensive `Path to Active`. @@ -57,6 +58,10 @@ A good solution should consist of both a well crafted standard with clear guidin +## How should we allow this CIP to evolve with ledger changes? + +- When hardforks happen, should we gain consensus on precisely how the new fields should be encoded before serialization libraries begin implementation? + ### Should we enforce it in ledger? - Not enforcing: difficult to make wider tooling community comply with it From f3c86d7f4480ad3caf6a5d21c0be5a36aea2d82f Mon Sep 17 00:00:00 2001 From: SIDANWhatever Date: Wed, 29 Oct 2025 15:41:11 +0000 Subject: [PATCH 04/12] flesh out content --- CPS-????/README.md | 103 +++++++++++++++++++++++++++++++++++---------- 1 file changed, 80 insertions(+), 23 deletions(-) diff --git a/CPS-????/README.md b/CPS-????/README.md index 37bec0aa07..a07126dd03 100644 --- a/CPS-????/README.md +++ b/CPS-????/README.md @@ -21,18 +21,38 @@ There is no canonical CBOR serialization standard in Cardano. While this is a de -Unstandardized CBOR serialization has hindered the progress for Cardano developers community for a long time. While it allows higher flexibility of tool chain selection, it caused community overheads +The Cardano ledger accepts any valid CBOR encoding for transactions and on-chain data. While this flexibility was intentional to encourage ecosystem diversity, it has created significant interoperability challenges as the tooling landscape has matured. The same logical data can be encoded in multiple ways (map key ordering, integer encoding, definite vs. indefinite length, etc.), leading to different byte representations and transaction hashes. -- Wallet sign tx change the tx body -- Unpredictable transaction building -- Difference in script serialzation +### Core Issues + +**Transaction Hash Instability**: When a transaction is passed between tools or wallets for signing, each may re-serialize it differently. Since transaction hashes are computed over CBOR bytes, logically identical transactions produce different hashes. This breaks: + +- Multi-signature workflows where each signer's wallet may re-serialize the transaction +- Cross-tool transaction building where fee calculations depend on exact byte size + +**Script Inconsistencies**: Smart contracts suffer from unpredictable script hashes, reference script mismatches across tools. The same compiled script may produce different hashes depending on the library used to apply parameters or cbor serialize the script. + +**Development Friction**: Developers face increased testing burden across multiple libraries and wallets, library-specific test fixtures, vendor lock-in risks, and debugging challenges that require logical rather than byte-level comparison. + +### Ecosystem Impact + +The lack of standardization creates: + +- **Security risks**: Hard-to-diagnose bugs and complex audit requirements due to multiple serialization paths +- **Community overhead**: High support burden in addressing serialization issues and maintaining multiple strategies +- **Adoption barriers**: Unpredictable behavior discourages enterprise adoption and increases new developer friction + +This problem has become urgent as sophisticated DApps require cross-tool interoperability, multi-signature usage grows, and community feedback (e.g., Cardano Builder Fest 2025) has identified this as a critical pain point. ## Use cases -- Developers can switch across libraries and tools and yield a predictable result -- It is possible for serialization libraries to worry about only one way of serialization, deserialization would also become easier to maintain +**Cross-Library DApp Development**: A DApp developer builds transactions with Lucid in their frontend, but users sign with various wallets built on cardano-serialization-lib or pycardano. Canonical serialization ensures the transaction built equals the transaction signed. + +**Script Hash Consistency**: A developer publishes a reference script on-chain, then references it from their off-chain code. Currently, locally computed script hashes may not match the on-chain version due to encoding differences. Canonical serialization guarantees hash consistency across compilation and deployment pipelines. + +**Library Maintainers**: Serialization library authors currently must support multiple encoding strategies for compatibility. With a standard, they can focus on a single canonical implementation, reducing maintenance burden and improving deserialization reliability. ## Goals @@ -42,38 +62,75 @@ Goals may also contain requirements for the project. For example, they may inclu Finally, goals may also serve as evaluation metrics to assess how good a proposed solution is. --> -Solving this CPS means: +### Primary Goals + +1. **Establish a canonical CBOR standard**: A CIP that specifies deterministic encoding rules for all Cardano transaction and on-chain data structures, with clear guiding principles for choosing between encoding alternatives. -1. There is a CIP specifying guidance on standardizing Cardano CBOR serialization. +2. **Achieve ecosystem adoption**: Widespread implementation across major serialization libraries (cardano-serialization-lib, pycardano, Lucid, Aiken, etc.) and wallets (Nami, Eternl, Lace, Yoroi, etc.), ensuring cross-tool interoperability. -2. The community, namely serialization libraries and wallets are aware of the standard and comply accordingly. +3. **Provide implementation guidance**: Comprehensive documentation including test vectors, reference implementations or validation tools, and migration paths for existing tooling. -3. Optional: If the standard is deemed to be worth enforcing, the standard is then implemented on the ledger. +### Optional Goals -A good solution should consist of both a well crafted standard with clear guiding principle, carrying our the comprehensive `Path to Active`. +4. **Ledger-level enforcement**: If community consensus supports it, implement validation rules in the ledger to guarantee compliance (requires hardfork and backward compatibility strategy). + +### Success Criteria + +This CPS is successfully resolved when: + +- A canonical CBOR serialization CIP reaches "Active" status with clear specifications +- At least 80% of major libraries and wallets demonstrate compliance +- Serialization-related issues in community support channels decrease measurably +- Cross-tool transaction building becomes reliably predictable + +### Requirements for Solutions + +A good solution must: + +- **Technical clarity**: Unambiguous encoding rules for all covered data structures +- **Guiding principles**: Clear rationale for choosing specific encodings (efficiency, simplicity, adoption) +- **Comprehensive scope**: Address transactions, scripts, datums, redeemers, and specify what is out-of-scope +- **Path to Active**: Detailed adoption strategy including timeline, stakeholder coordination, and migration tooling +- **Evolution mechanism**: Process for handling future hardforks and new ledger types +- **Verification**: Test vectors or validation tools to verify implementation compliance ## Open Questions - +### What are the guiding principles for choosing the canonical form? + +When multiple valid CBOR encodings exist, how should we decide which becomes canonical? + +- **Efficiency**: Minimize transaction size (e.g., smallest integer encoding, definite over indefinite length) +- **Simplicity**: Choose the most straightforward encoding to implement and verify +- **Existing adoption**: Align with the most widely-used pattern in current tooling (e.g., cardano-serialization-lib as de facto standard) +- **Trade-offs**: How should we balance these potentially conflicting dimensions? + +### Should the standard be enforced at the ledger level? + +**Enforcing** (ledger validation): + +- Pros: Guarantees compliance; eliminates ambiguity; strongest interoperability guarantee +- Cons: Breaks backward compatibility; requires hard fork; existing tools and transactions may become invalid; potentially impractical migration burden - +**Not enforcing** (off-chain standard only): -## How should we allow this CIP to evolve with ledger changes? +- Pros: No backward compatibility concerns; existing transactions remain valid; easier initial adoption +- Cons: Voluntary compliance may be insufficient; fragmentation may persist; no guarantee of universal adoption -- When hardforks happen, should we gain consensus on precisely how the new fields should be encoded before serialization libraries begin implementation? +### How should canonical serialization evolve with hardforks? -### Should we enforce it in ledger? +When a hardfork introduces new ledger types or transaction fields, the CBOR encoding for these new structures must be decided. This raises critical workflow questions: -- Not enforcing: difficult to make wider tooling community comply with it -- Enforcing: backward compatibility issue, might not be practical to do so +**Pre-hardfork standardization**: Should the canonical encoding for new ledger types be specified as part of the hardfork proposal itself? This would prevent fragmentation but may slow down hardfork timelines. -### What are the guiding principles to decide the standard? +**Implementation sequencing**: Should serialization libraries wait for a canonical standard to be ratified before implementing support for new ledger types? Or should they implement independently and risk creating incompatible encodings? -Some possible dimensions: +**Governance and responsibility**: Who should define the canonical encoding for new types? -- Efficiency: whichever producing smallest size of transaction -- Friction: whichever more adapted in current community -- etc +- The team proposing the hardfork (e.g., IOG, Intersect ledger team)? +- CIP editors through a formal proposal process? +- Library maintainers through community consensus? +- A designated standardization working group? ## Copyright From fae3905253f814620322137c749c8f2b8ab76dc4 Mon Sep 17 00:00:00 2001 From: SIDANWhatever Date: Wed, 12 Nov 2025 07:32:15 +0100 Subject: [PATCH 05/12] chore: choose category --- CPS-????/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CPS-????/README.md b/CPS-????/README.md index a07126dd03..5e87733aff 100644 --- a/CPS-????/README.md +++ b/CPS-????/README.md @@ -1,7 +1,7 @@ --- CPS: ? Title: Canonical CBOR Serialization Standard -Category: Tools, Wallets, Ledger +Category: Tools Status: Open Authors: - Hinson Wong From 7bc1fd3ad48269edf9e21dc82d94fe0c9f80d674 Mon Sep 17 00:00:00 2001 From: Robert Phair Date: Thu, 13 Nov 2025 12:44:33 +0530 Subject: [PATCH 06/12] filled out original `Discussion:` link --- CPS-????/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CPS-????/README.md b/CPS-????/README.md index 5e87733aff..d38ad7f3a1 100644 --- a/CPS-????/README.md +++ b/CPS-????/README.md @@ -8,7 +8,7 @@ Authors: - Tsz Wai Wu Proposed Solutions: [] Discussions: - - https://github.com/cardano-foundation/CIPs/pull/? + - https://github.com/cardano-foundation/CIPs/pull/1109 Created: 2025-10-29 License: CC-BY-4.0 --- From 0d8e4fc74a09c7c1544c46e242ad1ac4b8594fd6 Mon Sep 17 00:00:00 2001 From: SIDANWhatever Date: Mon, 8 Dec 2025 14:05:19 +0800 Subject: [PATCH 07/12] chore: update email --- CPS-????/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CPS-????/README.md b/CPS-????/README.md index d38ad7f3a1..57d7fceea6 100644 --- a/CPS-????/README.md +++ b/CPS-????/README.md @@ -4,8 +4,8 @@ Title: Canonical CBOR Serialization Standard Category: Tools Status: Open Authors: - - Hinson Wong - - Tsz Wai Wu + - Hinson Wong + - Tsz Wai Wu Proposed Solutions: [] Discussions: - https://github.com/cardano-foundation/CIPs/pull/1109 From 6e54b4a4977c1f5fe0b5ca97c91c6ce9326c18a4 Mon Sep 17 00:00:00 2001 From: Robert Phair Date: Wed, 10 Dec 2025 01:25:20 -0500 Subject: [PATCH 08/12] assign CPS number 24 --- CPS-????/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CPS-????/README.md b/CPS-????/README.md index 57d7fceea6..49ef2a7e90 100644 --- a/CPS-????/README.md +++ b/CPS-????/README.md @@ -1,5 +1,5 @@ --- -CPS: ? +CPS: 24 Title: Canonical CBOR Serialization Standard Category: Tools Status: Open From 7f28dbae9ca48432fafee4073ec1ba98fc64970c Mon Sep 17 00:00:00 2001 From: Robert Phair Date: Thu, 11 Dec 2025 19:14:12 -0500 Subject: [PATCH 09/12] dropped "standard" from title as redundant + perhaps misleading --- CPS-????/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CPS-????/README.md b/CPS-????/README.md index 49ef2a7e90..2b5d6b5c4e 100644 --- a/CPS-????/README.md +++ b/CPS-????/README.md @@ -1,6 +1,6 @@ --- CPS: 24 -Title: Canonical CBOR Serialization Standard +Title: Canonical CBOR Serialization Category: Tools Status: Open Authors: From 18dc2ffd0a7cb7c00fe5899ffe5b2d1f3c61a3dd Mon Sep 17 00:00:00 2001 From: Robert Phair Date: Thu, 11 Dec 2025 19:14:44 -0500 Subject: [PATCH 10/12] removed artefact from CPS template (1 of 3) --- CPS-????/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/CPS-????/README.md b/CPS-????/README.md index 2b5d6b5c4e..bb708e3fae 100644 --- a/CPS-????/README.md +++ b/CPS-????/README.md @@ -19,8 +19,6 @@ There is no canonical CBOR serialization standard in Cardano. While this is a de ## Problem - - The Cardano ledger accepts any valid CBOR encoding for transactions and on-chain data. While this flexibility was intentional to encourage ecosystem diversity, it has created significant interoperability challenges as the tooling landscape has matured. The same logical data can be encoded in multiple ways (map key ordering, integer encoding, definite vs. indefinite length, etc.), leading to different byte representations and transaction hashes. ### Core Issues From f244d37bc9f119848d32db778683f904c5fe8f1e Mon Sep 17 00:00:00 2001 From: Robert Phair Date: Thu, 11 Dec 2025 19:15:09 -0500 Subject: [PATCH 11/12] removed artefact from CPS template (2 of 3) --- CPS-????/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/CPS-????/README.md b/CPS-????/README.md index bb708e3fae..d935c9a05f 100644 --- a/CPS-????/README.md +++ b/CPS-????/README.md @@ -44,8 +44,6 @@ This problem has become urgent as sophisticated DApps require cross-tool interop ## Use cases - - **Cross-Library DApp Development**: A DApp developer builds transactions with Lucid in their frontend, but users sign with various wallets built on cardano-serialization-lib or pycardano. Canonical serialization ensures the transaction built equals the transaction signed. **Script Hash Consistency**: A developer publishes a reference script on-chain, then references it from their off-chain code. Currently, locally computed script hashes may not match the on-chain version due to encoding differences. Canonical serialization guarantees hash consistency across compilation and deployment pipelines. From a6e419cdbdf816900b448542fa690e2823a0c3cb Mon Sep 17 00:00:00 2001 From: Robert Phair Date: Thu, 11 Dec 2025 19:15:46 -0500 Subject: [PATCH 12/12] removed artefact from CPS template (3 of 3) --- CPS-????/README.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/CPS-????/README.md b/CPS-????/README.md index d935c9a05f..ae5079d5d9 100644 --- a/CPS-????/README.md +++ b/CPS-????/README.md @@ -52,12 +52,6 @@ This problem has become urgent as sophisticated DApps require cross-tool interop ## Goals - - ### Primary Goals 1. **Establish a canonical CBOR standard**: A CIP that specifies deterministic encoding rules for all Cardano transaction and on-chain data structures, with clear guiding principles for choosing between encoding alternatives.