Add content to "Introduction" and "Design Goals" sections #1690
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
dnadales
requested review from
amesgen,
fraser-iohk,
geo2a,
jasagredo and
nfrisby
as code owners
dnadales
force-pushed
the
dnadales/add-content-to-introduction-and-design-goals
branch
2 times, most recently
from
12659a5 to
b357bde
Compare
jasagredo
approved these changes
Sep 25, 2025
| For example, validating headers before downloading block bodies prevents attackers from forcing nodes to process potentially invalid blocks. | ||
| The design often seeks a balance between the cost for an attacker to induce work and the cost for a node to defend against it. | ||
|
|
||
| [^1]: See the IOSim monad and the `io-classes` package of [`io-sim`](https://github.com/input-output-hk/io-sim). |
There was a problem hiding this comment.
Suggested change
| [^1]: See the IOSim monad and the `io-classes` package of [`io-sim`](https://github.com/input-output-hk/io-sim). | |
| [^1]: See the `IOSim` monad and the `io-classes` package of [`io-sim`](https://github.com/input-output-hk/io-sim). |
There was a problem hiding this comment.
Possibly could be reformulated to point to https://input-output-hk.github.io/io-sim/
| This design allows different ledgers (like the Byron or Shelley ledgers) and different Ouroboros protocol instances (like Praos or TPraos) to be integrated into the abstract consensus framework. | ||
| To reflect this design, the repository is structured into different sub-repositories. | ||
| - The polymorphic implementations and abstract classes, which define the core consensus logic independently of specific ledger or protocol details, can be found in the [`ouroboros-consensus`](https://github.com/IntersectMBO/ouroboros-consensus/tree/main/ouroboros-consensus) sub-directory. | ||
| - The Cardano specific instantiations, which provide the concrete implementations, reside in the [ouroboros-consensus-cardano](https://github.com/IntersectMBO/ouroboros-consensus/tree/main/ouroboros-consensus-cardano) sub-directory. |
There was a problem hiding this comment.
Suggested change
| - The Cardano specific instantiations, which provide the concrete implementations, reside in the [ouroboros-consensus-cardano](https://github.com/IntersectMBO/ouroboros-consensus/tree/main/ouroboros-consensus-cardano) sub-directory. | |
| - The Cardano specific instantiations, which provide the concrete implementations, reside in the [`ouroboros-consensus-cardano`](https://github.com/IntersectMBO/ouroboros-consensus/tree/main/ouroboros-consensus-cardano) sub-directory. |
fraser-iohk
reviewed
Sep 25, 2025
| @@ -1 +1,63 @@ | |||
| # Design Goals | |||
There was a problem hiding this comment.
should this document have a "see also" section at the bottom with relevant links to the documentation for the various protocols / eras? or have them linked inline?
| Whenever possible, we should abstract over IO, enabling simulations of various failures (such as disk or network errors) to verify system recovery capabilities[^1]. | ||
| Additionally, to leverage the property-based methodology, tests must be relatively inexpensive. | ||
| The design should also support testing rare but expected scenarios (such as multiple slot leaders in Praos) by allowing overrides in protocol or ledger behavior at specific points. | ||
| Furthermore, the system should facilitate the isolation testing of individual components. |
| This repository houses the Haskell implementation of three crucial components utilized by the [`cardano-node`](https://github.com/IntersectMBO/cardano-node): Consensus, Storage, and Mempool. | ||
| - The [Consensus component](https://cardano-scaling.github.io/cardano-blueprint/consensus/index.html) implements the [Ouroboros](https://iohk.io/en/research/library/papers/ouroboros-a-provably-secure-proof-of-stake-blockchain-protocol/) family of Proof-of-Stake protocols. | ||
| - The [Storage component](https://cardano-scaling.github.io/cardano-blueprint/storage/index.html) is responsible for providing efficient access to the blockchain data, as well as maintaining the current and recent past ledger states, and storing ledger state snapshots. | ||
| - The [Mempool component](https://cardano-scaling.github.io/cardano-blueprint/mempool/index.html) serves as a buffer for valid transactions that are waiting to be included in a block. It is used by Consensus component when forging a block and by the Network layer's transaction submission mini-protocol when adding or getting transactions. |
There was a problem hiding this comment.
"adding or getting" sounds very vague here, and it might not be clear exactly what's meant
| Ensuring the thorough testability of the consensus layer is a critical design goal. | ||
| As a core component of the Cardano Node, which manages the cryptocurrency, the consensus layer must adhere to strict correctness standards. | ||
| Currently, we extensively employ property-based testing. | ||
| Whenever possible, we should abstract over IO, enabling simulations of various failures (such as disk or network errors) to verify system recovery capabilities[^1]. |
There was a problem hiding this comment.
"IO" instead of "IO"? I don't know how much (if any) Haskell knowledge we're expecting a reader to have
There was a problem hiding this comment.
I changed it to IO. I think that since this is a Haskell-based implementation of the Cardano node we could expect the reader to be familiar with the language 👍
dnadales
force-pushed
the
dnadales/add-content-to-introduction-and-design-goals
branch
from
b357bde to
68d3b7e
Compare
bladyjoker
approved these changes
Sep 26, 2025
fraser-iohk
approved these changes
Sep 30, 2025
dnadales
force-pushed
the
dnadales/add-content-to-introduction-and-design-goals
branch
from
68d3b7e to
b0d476f
Compare
dnadales
force-pushed
the
dnadales/add-content-to-introduction-and-design-goals
branch
from
b0d476f to
bbcdd77
Compare
dnadales
deleted the
dnadales/add-content-to-introduction-and-design-goals
branch
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Split from #1542