| CIP | Title | Status | Category | Authors | Implementors | Created | Discussions | License | |
|---|---|---|---|---|---|---|---|---|---|
84 |
Cardano Ledger Evolution |
Active |
Meta |
|
N/A |
2023-01-30 |
CC-BY-4.0 |
This CIP provides guidance for future CIPs concerning the Cardano ledger.
The ledger is responsible for processing transactions and updating the shared state of the network. It also processes block headers and handles the state transformation from one epoch to the next (e.g. computing the staking rewards).
Most of the state maintained by the ledger relates to the Extended UTxO accounting model and support for Ouroboros, the proof-of-stake consensus mechanism used in Cardano.
This CIP aims to give guidance for future CIPs related to the ledger, making it a registered category of the CIP process1.
Many thanks to Arnaud Bailly and Michael Peyton Jones for all their help reviewing and providing feedback on the first versions of this CIP.
Context for the terminology used in this document is given in CIP-59.
The ledger is specified as a state transition system using a small step operational semantics. We refer to this framework as the Small Step Semantics for Cardano, or the STS for short. An understanding of the existing STS specifications for the existing ledger eras is often required to fully understand the implications of changes to the ledger (though an understanding of the Haskell implementation is a fair substitute).
The STS framework leaves both cryptographic primitives and the serialization format abstract. The STS specifications need to be complete enough to realize a full implementation of the ledger given the cryptographic primitives and serialization format. The cryptographic primitives are described as appendices to the STS specifications, and the serialization format is given as a CDDL file. There SHOULD be one STS specification per ledger era.
From the Byron to the Babbage ledger eras, the STS frameworks were written in
A ledger era is a collection of features added to the ledger which are introduced at a hard fork. The existing ledger eras, with very simplistic descriptions, are given below.
| name | new features | link |
|---|---|---|
| Byron | initial UTxO ledger | spec |
| Shelley | decentralized block production, stake delegation | spec |
| Allegra | timelock scripts | - |
| Mary | multi-assets | spec |
| Alonzo | Plutus scripts | spec |
| Babbage | improved Plutus script contexts | spec |
| Conway | governance | spec WIP |
Note that there is no Allegra specification. The Allegra era consists entirely of the addition of timelocks to the MultiSig script introduced in the Shelley ledger era (See figure 12 of the Mary specification).
Note that small, isolated changes can be made within a ledger era by way of an intra-era hard fork. See CIP-59 for more details.
Some provenance about the ledger calculations is provided by ledger events. Sometimes these events have clear triggers (e.g. Plutus script execution) and sometimes they provide intermediate calculations performed by the ledger rules (e.g. the reweard calculation). The events come with zero cost to a running node if not used and are not stored in the ledger state. Documentation about the existing events can be found here.
Since most ledger CIPs will involve backwards incompatible changes, the following two definitions are helpful:
Hard fork - A hard fork is a change to the protocol (not restricted to the ledger) resulting in a single new block definition becoming valid.
Alternatively, a hard fork is a backwards incompatible change for both block producers and block validators.
Soft fork - A soft fork is a change to the protocol (not restricted to the ledger) resulting in fewer blocks being valid.
Alternatively, a soft fork is a backwards incompatible change for block producers, but a backwards compatible change for block validators.
Transactions and blocks are serialized with CBOR and specified with CDDL file.
Serialization changes to the ledger are discussed in CIP-80.
Note that the serialisation format of the ledger state is unspecified and left as an implementation detail (unlike the format of blocks).
The ledger and Plutus scripts have a common interface, described in CIP-35. CIPs relating to this inteface are relevant to both the ledger and to the Plutus CIP categories.
Additionally, there is significant overlap with the Ledger category around the ledger-script interface and the protocol parameters. CIPs which change these parts of Cardano should generally use the Plutus category and not the Ledger category, although the Editors may ask the Ledger reviewers to comment.
The criterion for deciding if a change to the ledger merits a CIP is as follows: changes to the ledger require going through the CIP process whenever every implementation of the Cardano ledger needs to be standardized on the details.
Bug fixes are an exception to this criterion, they do not merit a CIP except in the case that the fix is substantially complicated. A "bug fix" is a change to behavior where:
- The implemented behavior does not match the specification; or
- The specified behavior is clearly wrong (in the judgment of relevant experts)
Serialization changes are another possible exception to the criterion. Many serialization changes can be handled as a part of the normal development process without the need for a CIP. Dramatic changes to the serialization, however, may benefit from the CIP process.
The ledger rules MUST be standardized in order for consensus to be maintained, but things like the ledger events are more open to debate.
Changes to the protocol parameter values do not require a CIP since they are a governance issue (see CIP-1694).
- Familiarity with the existing ledger specifications is required to propose changes to the ledger.
- The CIP specifications for ledger CIPs must be sufficiently detailed for inclusion in a formal ledger specification.
- Though proposals can be accepted solely on the basis of peer and Ledger team review, some areas (e.g. changes to the incentives model) might only considered ready for implementation if accompanied by an opinion from an expert designated by the implementor (e.g. with a proper game theoretic analysis).
The following table gives the current set of reviewers for Ledger CIPs.
| Name | GitHub username | |
|---|---|---|
| Andre Knispel | andre.knispel@iohk.io | @WhatisRT |
| Alexey Kuleshevich | alexey.kuleshevich@iohk.io | @lehins |
Even though there is currently only one implementation, this provides us with a clear definition of what is essential to the ledger. It also provides a clear path for future implementations.
This decision should be left to the community as more use cases emerge.
It is not always clear which seemingly small details can make a large difference to the many consumers of the ledger. It is better that the CIP process achieve consensus on all the details than for these decisions to be made during the implementation phase.
This CIP requires the acceptance of the Ledger team, which it has in virtue of its authorship.
No implementation is required.
This CIP is licensed under CC-BY-4.0.