Merge pull request #50 from cardano-scaling/blueprint-resources

ch1bo · web-flow · commit b8c272386e1c · 2025-07-25T15:03:04.000+02:00
Blueprint resources
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
@@ -21,7 +21,6 @@
 - [Ledger](ledger/README.md)
   - [Transaction fee](ledger/transaction-fee.md)
   - [Block Validation](ledger/block-validation.md)
-  - [CDDL Specs](ledger/cddls.md)
 - [Plutus](plutus/README.md)
   - [Syntax](plutus/syntax.md)
   - [Builtin Types and Functions](plutus/builtin.md)
diff --git a/src/consensus/README.md b/src/consensus/README.md
@@ -1,15 +1,16 @@
-# The Consensus Layer
+# Consensus
+
+> [!WARNING]
+>
+> This blueprint is a work in progress.
+> See also [Resources](#resources)
 
 This document describes the components of the Consensus layer of a Cardano node,
 serving as a reference for Cardano developers who want to implement a node or
 interact with the Consensus layer of an existing implementation. We strive to
 provide implementation-agnostic requirements and responsibilities for the
 Consensus layer.
 
-> [!WARNING]
->
-> This document is a work in progress.
-
 The Consensus Layer runs the Consensus Protocol and invokes the [Ledger
 layer](../ledger) to validate chains produced according to the
 protocol. The chain is then persisted in the [Storage
@@ -215,6 +216,13 @@ view_. We require not just that the ledger can provide a view of the current
 ledger state but also that it can predict what view will be for slots in the
 near future.
 
+
+## Resources
+
+- [Technical report: Data Diffusion and Network][network-design]: Original design document of the peer-to-peer network protocols and diffusion semantics
+- [Technical report: Cardano Consensus and Storage Layer](https://ouroboros-consensus.cardano.intersectmbo.org/pdfs/report.pdf): Documentation of the Haskell implementation of consensus components
+- [Website: ouroboros-consensus > For Developers](https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers): Collection of developer articles on the Haskell implementation of consensus components
+
 [feature-table]: https://github.com/cardano-foundation/CIPs/blob/master/CIP-0059/feature-table.md
 [network-design]: https://ouroboros-network.cardano.intersectmbo.org/pdfs/network-design/network-design.pdf
 [Classic]: https://iohk.io/en/research/library/papers/ouroboros-a-provably-secure-proof-of-stake-blockchain-protocol/
diff --git a/src/ledger/README.md b/src/ledger/README.md
@@ -1,7 +1,31 @@
 # Ledger
 
-Cardano uses the Extended Unspent Transaction Output (EUTxO) ledger model...
+> [!WARNING]
+>
+> This blueprint is a work in progress.
 
-```agda
-data S
-```
+The Ledger is responsible for validating Blocks and represents the actual semantics of Cardano transactions. The format of blocks and transactions is defined in so-called **eras**: `Byron`, `Shelley`, `Allegra`, `Mary`, `Alonzo`, `Babbage` and `Conway`.
+
+This blueprint is currently more of an entrypoint to already existing implementation-independent descriptions of Cardano transactions and the ledger rules. While existing work covers a lot already, the `cardano-blueprint` may serve as an incubation or staging area for material to cover gaps.
+
+For starters, the [EUTxO Crash Course](https://aiken-lang.org/fundamentals/eutxo) from Aiken is a very good introduction about Cardano transactions.
+
+See [Transaction fee](./transaction-fee.md) for an informal write-up on how transaction fees are currently calculated.
+
+## Ledger rules
+
+The [Formal Specification](https://intersectmbo.github.io/formal-ledger-specifications/site/index.html) is the source of truth for ledger semantics. While it is currently being made more accessible by interleaving explanations with Agda definitions, its very dense on the Agda and actively worked on to close the gap latest era descriptions and the old era definitions. The Haskell implementation of the ledger holds a list of [design documents and ledger specifications](https://github.com/IntersectMBO/cardano-ledger?tab=readme-ov-file#cardano-ledger) for all eras.
+
+See [Block Validation](./block-validation.md) for a description of the `Conway` era block validation rules.
+
+## Block and transaction format
+
+The [.cddl files in cardano-ledger](https://github.com/search?q=repo%3AIntersectMBO%2Fcardano-ledger+path%3A.cddl&type=code) define the wire-format of blocks and transactions for each era. These are self-contained for each
+era and are referenced in [other blueprint CDDL schemas](../codecs#cddl).
+
+> [!WARNING]
+> TODO: make ledger cddls available through blueprint directly
+
+## Conformance tests 
+
+Despite the formal specification provides a precise definition for semantics, testing the behavior of ledger implementations against the specification and also the ledger implementations against each other is crucial. For this purpose, a conformance test suite with [implementation-independent test vectors](https://github.com/cardano-scaling/cardano-blueprint/tree/main/src/ledger/conformance-test-vectors) can be used.
diff --git a/src/ledger/block-validation.md b/src/ledger/block-validation.md
@@ -1,7 +1,7 @@
 # Ledger: Block Validation
 
 Block validation is the process of applying a set of ledger rules to a candidate block before adding it to the blockchain and updating the state of the ledger.
-Each [era](../consensus/README.md#multi-era-considerations) has it's own set of rules for block validation.
+Each [era](../consensus/multiera.md) has it's own set of rules for block validation.
 
 > [!NOTE]
 > TODO: Write a full introduction here with relevant terminology and concepts defined.
diff --git a/src/ledger/cddls.md b/src/ledger/cddls.md
diff --git a/src/mempool/README.md b/src/mempool/README.md
@@ -1,5 +1,10 @@
 # Mempool
 
+> [!WARNING]
+>
+> This blueprint is a work in progress.
+> See also [Resources](#resources)
+
 In Cardano, for blocks to have useful data, they have to contain transactions,
 which are codifications of operations on the Ledger state that only some
 authorized actors can enact. Notice that such transactions are what makes up the
@@ -82,3 +87,7 @@ original transaction is the one that will be forwarded to other peers, i.e. the
 > [!WARNING]
 >
 > TODO: describe fairness and what should mempools do in this regard.
+
+## Resources
+
+- [Technical report: Cardano Consensus and Storage Layer](https://ouroboros-consensus.cardano.intersectmbo.org/pdfs/report.pdf): Documentation of the Haskell implementation of consensus components
diff --git a/src/network/README.md b/src/network/README.md
@@ -1,5 +1,10 @@
 # Network
 
+> [!WARNING]
+>
+> This blueprint is a work in progress.
+> See also [Resources](#resources)
+
 The network layer is responsible of implementing the Node-To-Node interface of a
 node, for transmitting data between nodes.
 
@@ -29,7 +34,7 @@ graph TB
 > the networking layer of a node but it is not mandatory. For more information
 > see [Client interfaces](../client).
 
-### Node-to-node mini-protocols
+## Node-to-node mini-protocols
 
 > Current node-to-node protocol version: v14
 
@@ -44,3 +49,10 @@ network (combined by the multiplexing wrapper) is:
 * [Keep Alive](node-to-node/keep-alive) - for maintaining and measuring timing of the connection
 * [Peer Sharing]() - for exchanging peer information to create the peer-to-peer
   (P2P) network
+
+
+## Resources
+
+- [Technical report: Data Diffusion and Network](https://ouroboros-network.cardano.intersectmbo.org/pdfs/network-design/network-design.pdf): Original design document of the peer-to-peer network protocols and diffusion semantics
+- [Ouroboros Network Specification](https://ouroboros-network.cardano.intersectmbo.org/pdfs/network-spec/network-spec.pdf): Document generated from the Haskell implementation of the Cardano network stack. Contains definitions of all mini-protocols and some documentation the connection management. 
+
diff --git a/src/storage/README.md b/src/storage/README.md
@@ -1,4 +1,9 @@
-# The Storage Layer
+# Storage
+
+> [!WARNING]
+>
+> This blueprint is a work in progress.
+> See also [Resources](#resources)
 
 The Storage layer is responsible of storing the blocks on behalf of the
 Consensus layer. It is also involved in serving the data for [Chain
@@ -77,3 +82,8 @@ of messages a protocol is composed by. It is possible to run an interaction of
 the protocol exchanging data that does not follow the intended semantics (for
 example an evil node sending all the chains it knows about instead of only the
 best selection).
+
+## Resources
+
+- [Technical report: Cardano Consensus and Storage Layer](https://ouroboros-consensus.cardano.intersectmbo.org/pdfs/report.pdf): Documentation of the Haskell implementation of consensus components
+- [Website: ouroboros-consensus > For Developers](https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers): Collection of developer articles on the Haskell implementation of consensus components
