From cd8b7b4712054ad4416b5ac6a59ffcd06078b7f2 Mon Sep 17 00:00:00 2001 From: Sebastian Nagel Date: Mon, 6 Oct 2025 12:05:05 +0200 Subject: [PATCH 1/6] Add section about impact on ledger This currently covers serialization, new block structure, voting committee and protocol parameter considerations. --- docs/ImpactAnalysis.md | 61 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 59 insertions(+), 2 deletions(-) diff --git a/docs/ImpactAnalysis.md b/docs/ImpactAnalysis.md index 4404fbc20..989786e5e 100644 --- a/docs/ImpactAnalysis.md +++ b/docs/ImpactAnalysis.md @@ -1,7 +1,7 @@ --- Title: Leios impact analysis Status: Draft -Version: 0.2 +Version: 0.3 Authors: - Michael Karg - Nicolas Frisby @@ -414,8 +414,65 @@ The following experiments each pertain to several of the risks above. # Ledger +The [Ledger](https://cardano-scaling.github.io/cardano-blueprint/ledger/index.html) is responsible for validating Blocks and represents the actual semantics of Cardano transactions. CIP-164 sketches a protocol design that does not change the semantics of Cardano transactions, does not propose any changes to the transaction structure and also not requires changes to reward calculation. However, the Ledger component usually does not validate individual transactions, but has two entry points: + +1. Validating entire block bodies via [BBODY](https://intersectmbo.github.io/formal-ledger-specifications/site/Ledger.Conway.Specification.BlockBody.html#block-body-transition) +2. Updating rewards and other ledger state (primarily across epochs) via [TICK](https://intersectmbo.github.io/formal-ledger-specifications/site/Ledger.Conway.Specification.RewardUpdate.html#chain-tick-transition) + +Both of these entry points will need to be updated to handle the new block structure (ranking blocks not including transactions directly) and to be able to verify certificates (against the voting committee). Any change to the ledger demands a hard-fork and a change in formats or functionality are collected into [ledger eras](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0084#ledger-eras). The changes proposed by CIP-164 will need to go into new ledger era. Which era this will be, depends on when the functionality will be rolled out: + +- **REQ-LedgerNewEra**: The ledger must be prepared with a new era that includes all changes required by CIP-164. + +For the remainder of this document, let's assume the changes will go into the `Euler` era, where `Conway` is currently the latest and `Dijkstra` is in preparation at the time of writing. + +## New block structure + +In Praos, all transactions to be verified and applied to the ledger state are included directly in the block body. In Leios, ranking blocks (RB) may not include transactions directly, but instead certificate and reference to an endorsement block (EB) that further references the actual transactions. This gives rise to the following requirements: + +- **REQ-LedgerResolvedBlockValidation**: When validating a block body, the ledger must be provided with the endorsed transactions to be applied to the ledger state. +- **REQ-LedgerTxValidationUnchanged**: The actual transaction validation logic should remain unchanged, i.e., the ledger must validate each transaction as it does today. + +The endorsement block itself does not contain any additional information besides a list of transaction identifiers (hashes of the full transaction bytes). Hence, the list of transactions is sufficient to reconstruct the EB body and verify the certificate contained in the RB. The actual transactions to be applied to the ledger state must be provided by the caller of the ledger interface, typically the storage layer or the mempool. + +## Certificate verification + +In order to verify certificates contained in ranking blocks, the ledger must be aware of the voting committee and able to access their public keys. As defined in by **REQ-RegisterBLSKeys**, SPOs must be able to register their BLS keys to become part of the voting committee. The ledger will need to be able to keep track of the registered keys and use them to do certificate verification. Besides verifiying certificates, individual votes must also be verifiable by other components (e.g. to avoid diffusing invalid votes). This gives rise to: + +- **REQ-LedgerStateVotingCommittee**: The Leios voting committee must be part of the ledger state, updated on epoch boundaries and queryable via the state query interface. + +Being part of the ledger state, the voting committee will be stored in ledger snapshots and hence on disk in course of Ledger-HD. Depending on how exactly keys will be registered, the ledger might need to be able to access block headers in order to read the BLS public keys from the operational certificate. As this is not the case today (only block bodies are processed by the ledger), this results in requirement: + +- **REQ-LedgerBlockHeaderAccess**: The ledger must be able to access block headers. + +The voting committee consists of persistent and non-persistent voters. The persistet voters are to be selected at epoch boundaries using a [Fait Accompli sortition scheme](https://github.com/cardano-scaling/CIPs/blob/leios/CIP-0164/README.md#votes-and-certificates). Hence: + +- **REQ-LedgerCommitteeSelection**: The ledger must select persistent voters in the voting committee at epoch boundaries using the Fait Accompli sortition scheme. + +Finally, block validation of the ledger can use the voting committee state to verify certificates contained in ranking blocks: + +- **REQ-LedgerCertificateVerification**: The ledger must verify certificates contained in ranking blocks using the voting committee state. + +## New protocol parameters + +CIP-164 introduces several new protocol parameters that may be updated via on-chain governance. The ledger component is responsible for storing, providing access and updating any protocol parameters. Unless some of the new parameters will be deemed constant (a.k.a globals to the ledger), the following requirements must be satisfied for all new parameters: + +- **REQ-LedgerProtocolParameterAccess**: The ledger must provide access to all new protocol parameters via existing interfaces. +- **REQ-LedgerProtocolParameterUpdate**: The ledger must be able to update all new protocol parameters via on-chain governance. + +Concretely, this means defining the `PParams` and `PParamsUpdate` types for the `Euler` era to include the new parameters, as well as providing access via the `EulerPParams` and other type classes. + +## Serialization + +Traditionally, the ledger component defines the serialization format of blocks and transactions. CIP-164 introduces three new types that need to be serialized and deserialized: + +- **REQ-LedgerSerializationRB**: The ranking block body contents must be deterministically de-/serializable from/to bytes using CBOR encoding. +- **REQ-LedgerSerializationEB**: The endorsement block structure must be deterministically de-/serializable from/to bytes using CBOR encoding. +- **REQ-LedgerSerializationVote**: The vote structure must be deterministically de-/serializable from/to bytes using CBOR encoding. + > [!WARNING] -> TODO: Describe requirements and changes to the **Ledger component** +> TODO: Serialization of votes a consensus component responsibility? + +Corresponding types with instances of `EncCBOR` and `DecCBOR` must be provided in the ledger component. The `cardano-ledger` package is a dependency to most of the Haskell codebase, hence these new types can be used in most other components. # Cryptography From a052fa8e68447007c45df40894831a96140fb161 Mon Sep 17 00:00:00 2001 From: Sebastian Nagel Date: Tue, 7 Oct 2025 18:22:29 +0200 Subject: [PATCH 2/6] Add third entry point and transaction validation levels --- docs/ImpactAnalysis.md | 30 ++++++++++++++++++++++++------ 1 file changed, 24 insertions(+), 6 deletions(-) diff --git a/docs/ImpactAnalysis.md b/docs/ImpactAnalysis.md index 989786e5e..3a44de6ba 100644 --- a/docs/ImpactAnalysis.md +++ b/docs/ImpactAnalysis.md @@ -414,17 +414,35 @@ The following experiments each pertain to several of the risks above. # Ledger -The [Ledger](https://cardano-scaling.github.io/cardano-blueprint/ledger/index.html) is responsible for validating Blocks and represents the actual semantics of Cardano transactions. CIP-164 sketches a protocol design that does not change the semantics of Cardano transactions, does not propose any changes to the transaction structure and also not requires changes to reward calculation. However, the Ledger component usually does not validate individual transactions, but has two entry points: +The [Ledger](https://cardano-scaling.github.io/cardano-blueprint/ledger/index.html) is responsible for validating Blocks and represents the actual semantics of Cardano transactions. CIP-164 sketches a protocol design that does not change the semantics of Cardano transactions, does not propose any changes to the transaction structure and also not requires changes to reward calculation. The ledger component has three main entry points: -1. Validating entire block bodies via [BBODY](https://intersectmbo.github.io/formal-ledger-specifications/site/Ledger.Conway.Specification.BlockBody.html#block-body-transition) -2. Updating rewards and other ledger state (primarily across epochs) via [TICK](https://intersectmbo.github.io/formal-ledger-specifications/site/Ledger.Conway.Specification.RewardUpdate.html#chain-tick-transition) +1. Validating individual transactions via [`LEDGER`](https://intersectmbo.github.io/formal-ledger-specifications/site/Ledger.Conway.Specification.Ledger.html#ledger-transition-system) +2. Validating entire block bodies via [`BBODY`](https://intersectmbo.github.io/formal-ledger-specifications/site/Ledger.Conway.Specification.BlockBody.html#block-body-transition) +3. Updating rewards and other ledger state (primarily across epochs) via [`TICK`](https://intersectmbo.github.io/formal-ledger-specifications/site/Ledger.Conway.Specification.RewardUpdate.html#chain-tick-transition) -Both of these entry points will need to be updated to handle the new block structure (ranking blocks not including transactions directly) and to be able to verify certificates (against the voting committee). Any change to the ledger demands a hard-fork and a change in formats or functionality are collected into [ledger eras](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0084#ledger-eras). The changes proposed by CIP-164 will need to go into new ledger era. Which era this will be, depends on when the functionality will be rolled out: +The first will not need to change functionally, while the latter two will need to be updated to handle the new block structure (ranking blocks not including transactions directly) and to track a voting committee for certificate verification. Any change to the ledger demands a hard-fork and a change in formats or functionality are collected into [ledger eras](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0084#ledger-eras). The changes proposed by CIP-164 will need to go into new ledger era. Which era this will be, depends on when the functionality will be rolled out: - **REQ-LedgerNewEra**: The ledger must be prepared with a new era that includes all changes required by CIP-164. For the remainder of this document, let's assume the changes will go into the `Euler` era, where `Conway` is currently the latest and `Dijkstra` is in preparation at the time of writing. +## Transaction validation levels + +Validating individual transactions is currently done either via `applyTx` or `reapplyTx` functions. This corresponds to two levels of validation: + +- `applyTx` fully validates a transaction, including existence of inputs, checking balances, cryptographic hashes, signatures, evaluation of plutus scripts, etc. +- `reapplyTx` only check whether a transaction applies to a ledger state. This does not include expensive checks like script evaluation (a.k.a phase-2 validation) or signature verification. + +Where possible, `reapplyTx` is used when we know that the transaction has been fully validated before. For example when refreshing the mempool after adopting a new block. With Leios, a third level of validation is introduced: + +- **REQ-LedgerTxNoValidation** The ledger should provide a way to update the ledger state by just applying a transaction without validation. + +This third way of updating a ledger state would be used when we have a valid certificate about endorsed transactions in a ranking block. To avoid delaying diffusion of ranking blocks, we do want to do the minimal work necessary once an EB is certified and ease the [protocol security argument](https://github.com/cardano-scaling/CIPs/blob/leios/CIP-0164/README.md#protocol-security) with: + +- **REQ-LedgerCheapReapply** Updating the ledger state without validation must be significantly cheaper than reapplying a transaction. + +Note that this already anticipates that the new, third level `notValidateTx` will be even cheaper than `reapplyTx`. [Existing benchmarks](https://github.com/IntersectMBO/cardano-ledger/tree/master/libs/ledger-state) indicate that `reapplyTx` is already at least one order of magnitude cheaper than `applyTx` for transactions. + ## New block structure In Praos, all transactions to be verified and applied to the ledger state are included directly in the block body. In Leios, ranking blocks (RB) may not include transactions directly, but instead certificate and reference to an endorsement block (EB) that further references the actual transactions. This gives rise to the following requirements: @@ -432,13 +450,13 @@ In Praos, all transactions to be verified and applied to the ledger state are in - **REQ-LedgerResolvedBlockValidation**: When validating a block body, the ledger must be provided with the endorsed transactions to be applied to the ledger state. - **REQ-LedgerTxValidationUnchanged**: The actual transaction validation logic should remain unchanged, i.e., the ledger must validate each transaction as it does today. -The endorsement block itself does not contain any additional information besides a list of transaction identifiers (hashes of the full transaction bytes). Hence, the list of transactions is sufficient to reconstruct the EB body and verify the certificate contained in the RB. The actual transactions to be applied to the ledger state must be provided by the caller of the ledger interface, typically the storage layer or the mempool. +The endorsement block itself does not contain any additional information besides a list of transaction identifiers (hashes of the full transaction bytes). Hence, the list of transactions is sufficient to reconstruct the EB body and verify the certificate contained in the RB. The actual transactions to be applied to the ledger state must be provided by the caller of the ledger interface, typically the storage layer. ## Certificate verification In order to verify certificates contained in ranking blocks, the ledger must be aware of the voting committee and able to access their public keys. As defined in by **REQ-RegisterBLSKeys**, SPOs must be able to register their BLS keys to become part of the voting committee. The ledger will need to be able to keep track of the registered keys and use them to do certificate verification. Besides verifiying certificates, individual votes must also be verifiable by other components (e.g. to avoid diffusing invalid votes). This gives rise to: -- **REQ-LedgerStateVotingCommittee**: The Leios voting committee must be part of the ledger state, updated on epoch boundaries and queryable via the state query interface. +- **REQ-LedgerStateVotingCommittee**: The Leios voting committee must be part of the ledger state, updated on epoch boundaries and queryable through existing interfaces. Being part of the ledger state, the voting committee will be stored in ledger snapshots and hence on disk in course of Ledger-HD. Depending on how exactly keys will be registered, the ledger might need to be able to access block headers in order to read the BLS public keys from the operational certificate. As this is not the case today (only block bodies are processed by the ledger), this results in requirement: From cafd874c1620b95c5fef372811cbac9f56437c46 Mon Sep 17 00:00:00 2001 From: Sebastian Nagel Date: Wed, 8 Oct 2025 10:03:52 +0200 Subject: [PATCH 3/6] Add notes for currently unclear points --- docs/ImpactAnalysis.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/ImpactAnalysis.md b/docs/ImpactAnalysis.md index 3a44de6ba..9d6665f7c 100644 --- a/docs/ImpactAnalysis.md +++ b/docs/ImpactAnalysis.md @@ -452,6 +452,9 @@ In Praos, all transactions to be verified and applied to the ledger state are in The endorsement block itself does not contain any additional information besides a list of transaction identifiers (hashes of the full transaction bytes). Hence, the list of transactions is sufficient to reconstruct the EB body and verify the certificate contained in the RB. The actual transactions to be applied to the ledger state must be provided by the caller of the ledger interface, typically the storage layer. +> [!NOTE] +> In fact, the ledger might need to be provided with the previous block's slot: endorsed transactions need to be valid in the endorsing block's slot. Depending on the details of the consenus/ledger interface used for validating new blocks, this either means that the previous block's slot is provided or the block validation happens in two steps: (1) validate endorsed txs using announcing block's slot, (2) validate the certifying block (which may not contain further transactions). + ## Certificate verification In order to verify certificates contained in ranking blocks, the ledger must be aware of the voting committee and able to access their public keys. As defined in by **REQ-RegisterBLSKeys**, SPOs must be able to register their BLS keys to become part of the voting committee. The ledger will need to be able to keep track of the registered keys and use them to do certificate verification. Besides verifiying certificates, individual votes must also be verifiable by other components (e.g. to avoid diffusing invalid votes). This gives rise to: @@ -462,6 +465,9 @@ Being part of the ledger state, the voting committee will be stored in ledger sn - **REQ-LedgerBlockHeaderAccess**: The ledger must be able to access block headers. +> [!NOTE] +> This is a very generic requirement and will likely change depending on how the consensus/ledger interface for block validation is realized. It might be desirable to limit the ledger's access to block headers and only provide (a means to extract) relevant information. That is, the BLS public keys to be tracked and the voting committee to be selected from. + The voting committee consists of persistent and non-persistent voters. The persistet voters are to be selected at epoch boundaries using a [Fait Accompli sortition scheme](https://github.com/cardano-scaling/CIPs/blob/leios/CIP-0164/README.md#votes-and-certificates). Hence: - **REQ-LedgerCommitteeSelection**: The ledger must select persistent voters in the voting committee at epoch boundaries using the Fait Accompli sortition scheme. From beaedfea935c05d98efaf8f2decd1087ea421547 Mon Sep 17 00:00:00 2001 From: Sebastian Nagel Date: Wed, 8 Oct 2025 15:28:09 +0200 Subject: [PATCH 4/6] Clarified ledger block validation with unticked state --- docs/ImpactAnalysis.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/ImpactAnalysis.md b/docs/ImpactAnalysis.md index 9d6665f7c..50ab59970 100644 --- a/docs/ImpactAnalysis.md +++ b/docs/ImpactAnalysis.md @@ -447,14 +447,12 @@ Note that this already anticipates that the new, third level `notValidateTx` wil In Praos, all transactions to be verified and applied to the ledger state are included directly in the block body. In Leios, ranking blocks (RB) may not include transactions directly, but instead certificate and reference to an endorsement block (EB) that further references the actual transactions. This gives rise to the following requirements: -- **REQ-LedgerResolvedBlockValidation**: When validating a block body, the ledger must be provided with the endorsed transactions to be applied to the ledger state. +- **REQ-LedgerResolvedBlockValidation**: When validating a ranking block body, the ledger must be provided with all endorsed transactions resolved. +- **REQ-LedgerUntickedEBValidation**: When validating a ranking block body, the ledger must validate endorsed transactions against the ledger state before updating it with the new ranking block. - **REQ-LedgerTxValidationUnchanged**: The actual transaction validation logic should remain unchanged, i.e., the ledger must validate each transaction as it does today. The endorsement block itself does not contain any additional information besides a list of transaction identifiers (hashes of the full transaction bytes). Hence, the list of transactions is sufficient to reconstruct the EB body and verify the certificate contained in the RB. The actual transactions to be applied to the ledger state must be provided by the caller of the ledger interface, typically the storage layer. -> [!NOTE] -> In fact, the ledger might need to be provided with the previous block's slot: endorsed transactions need to be valid in the endorsing block's slot. Depending on the details of the consenus/ledger interface used for validating new blocks, this either means that the previous block's slot is provided or the block validation happens in two steps: (1) validate endorsed txs using announcing block's slot, (2) validate the certifying block (which may not contain further transactions). - ## Certificate verification In order to verify certificates contained in ranking blocks, the ledger must be aware of the voting committee and able to access their public keys. As defined in by **REQ-RegisterBLSKeys**, SPOs must be able to register their BLS keys to become part of the voting committee. The ledger will need to be able to keep track of the registered keys and use them to do certificate verification. Besides verifiying certificates, individual votes must also be verifiable by other components (e.g. to avoid diffusing invalid votes). This gives rise to: From 727f918c405a685e8adafdf747838d8f5e192794 Mon Sep 17 00:00:00 2001 From: Sebastian Nagel Date: Wed, 8 Oct 2025 15:29:10 +0200 Subject: [PATCH 5/6] Fix a typo --- docs/ImpactAnalysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ImpactAnalysis.md b/docs/ImpactAnalysis.md index 50ab59970..dedeadd42 100644 --- a/docs/ImpactAnalysis.md +++ b/docs/ImpactAnalysis.md @@ -466,7 +466,7 @@ Being part of the ledger state, the voting committee will be stored in ledger sn > [!NOTE] > This is a very generic requirement and will likely change depending on how the consensus/ledger interface for block validation is realized. It might be desirable to limit the ledger's access to block headers and only provide (a means to extract) relevant information. That is, the BLS public keys to be tracked and the voting committee to be selected from. -The voting committee consists of persistent and non-persistent voters. The persistet voters are to be selected at epoch boundaries using a [Fait Accompli sortition scheme](https://github.com/cardano-scaling/CIPs/blob/leios/CIP-0164/README.md#votes-and-certificates). Hence: +The voting committee consists of persistent and non-persistent voters. The persistent voters are to be selected at epoch boundaries using a [Fait Accompli sortition scheme](https://github.com/cardano-scaling/CIPs/blob/leios/CIP-0164/README.md#votes-and-certificates). Hence: - **REQ-LedgerCommitteeSelection**: The ledger must select persistent voters in the voting committee at epoch boundaries using the Fait Accompli sortition scheme. From 26677cf6c216bac97afafa5b381f5b00f853b5f7 Mon Sep 17 00:00:00 2001 From: Sebastian Nagel Date: Wed, 8 Oct 2025 17:08:07 +0200 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Nicolas Frisby --- docs/ImpactAnalysis.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ImpactAnalysis.md b/docs/ImpactAnalysis.md index dedeadd42..c08269d2f 100644 --- a/docs/ImpactAnalysis.md +++ b/docs/ImpactAnalysis.md @@ -420,7 +420,7 @@ The [Ledger](https://cardano-scaling.github.io/cardano-blueprint/ledger/index.ht 2. Validating entire block bodies via [`BBODY`](https://intersectmbo.github.io/formal-ledger-specifications/site/Ledger.Conway.Specification.BlockBody.html#block-body-transition) 3. Updating rewards and other ledger state (primarily across epochs) via [`TICK`](https://intersectmbo.github.io/formal-ledger-specifications/site/Ledger.Conway.Specification.RewardUpdate.html#chain-tick-transition) -The first will not need to change functionally, while the latter two will need to be updated to handle the new block structure (ranking blocks not including transactions directly) and to track a voting committee for certificate verification. Any change to the ledger demands a hard-fork and a change in formats or functionality are collected into [ledger eras](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0084#ledger-eras). The changes proposed by CIP-164 will need to go into new ledger era. Which era this will be, depends on when the functionality will be rolled out: +The first will not need to change functionally, while the latter two will need to be updated to handle the new block structure (ranking blocks not including transactions directly) and to enable the determination of a voting committee for certificate verification. Any change to the ledger demands a hard-fork and a change in formats or functionality are collected into [ledger eras](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0084#ledger-eras). The changes proposed by CIP-164 will need to go into new ledger era. Which era this will be, depends on when the functionality will be rolled out: - **REQ-LedgerNewEra**: The ledger must be prepared with a new era that includes all changes required by CIP-164. @@ -439,7 +439,7 @@ Where possible, `reapplyTx` is used when we know that the transaction has been f This third way of updating a ledger state would be used when we have a valid certificate about endorsed transactions in a ranking block. To avoid delaying diffusion of ranking blocks, we do want to do the minimal work necessary once an EB is certified and ease the [protocol security argument](https://github.com/cardano-scaling/CIPs/blob/leios/CIP-0164/README.md#protocol-security) with: -- **REQ-LedgerCheapReapply** Updating the ledger state without validation must be significantly cheaper than reapplying a transaction. +- **REQ-LedgerCheapReapply** Updating the ledger state without validation must be significantly cheaper than even reapplying a transaction is today. Note that this already anticipates that the new, third level `notValidateTx` will be even cheaper than `reapplyTx`. [Existing benchmarks](https://github.com/IntersectMBO/cardano-ledger/tree/master/libs/ledger-state) indicate that `reapplyTx` is already at least one order of magnitude cheaper than `applyTx` for transactions.