Add content to "Introduction" and "Design Goals" sections

docs/website/README.md

@@ -43,6 +43,22 @@ The order of entries in the `items` list determines their placement in the sideb
 
 # Building the website
 
+If you use `nix`, you can enter a shell with a `yarn` installation by running:
+
+
+```
+nix develop .#website
+```
+
+To omit the `.website` part in `nix develop`, you can add an `.envrc` file in `docs/website` containing:
+
+```
+use flake .#website
+```
+
+
+If you don't use `nix`, please refer to the `yarn` installation instructions online.
+
 To install the required packages for the documentation site, run:
 
 ```

docs/website/contents/explanations/design_goals.md

@@ -1 +1,63 @@
 # Design Goals
+
+The components that make up `ouroboros-consensus` were designed with the following goals in mind.
+
+## Multiple Consensus Protocols
+
+The design must support different consensus algorithms, requiring abstraction over the specific choice of consensus protocol.
+From the project's inception, it was evident that multiple protocols would be required.
+The [Byron era](../references/glossary.md#byron-era) of Cardano utilizes the [PBFT](../references/glossary.md#permissive-bft-pbft) protocol, while the [Shelley era](../references/glossary.md#shelley-based-eras) transitioned to [TPraos](../references/glossary.md#tpraos), and [Praos](../references/glossary.md#ouroboros-praos) has been used since the [Babbage](../references/glossary.md#babbage-era) era.
+The consensus component must support not only the current era but also past eras, requiring the ability to compose protocols.
+Additionally, we must ensure support for integrating new consensus protocols.
+
+## Support for Multiple Ledgers
+
+Similar to the need for multiple consensus protocols, our implementation must support multiple ledger implementations.
+This is crucial for accommodating ledger changes as improvements are made.
+Abstracting over the ledger implementation enables the consensus layer to work with various ledgers.
+
+## Decoupling Consensus Protocol from Ledger
+
+The consensus protocol is designed to be independent of any specific ledger implementation.
+Since multiple ledgers (such as Shelley and its Shelley-based successors) can utilize the same consensus protocol (TPraos or Praos), the consensus protocol is defined based on what it expects or requires from the ledger rather than being tightly coupled to a specific one.
+This approach makes the consensus protocol abstract and reusable across different ledgers.
+
+## Testability
+
+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].
+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 isolated testing of individual components.
+
+## Adaptability and Maintainability
+
+The consensus layer was developed as a replacement for a [previous implementation](https://github.com/input-output-hk/cardano-sl), with the immediate goal of transitioning from Byron/BFT to Shelley/Praos while supporting future ledger and protocol changes.
+This called for a flexible and adaptable design.
+Abstracting both the consensus algorithm and the ledger plays a crucial role in achieving this.
+Working with abstract interfaces prevents developers from making assumptions that may hold for one ledger but not others, avoiding costly fixes later.
+This abstraction also allows the consensus layer to be reused in other blockchain projects.
+Most importantly, an abstract design enables extensive testing with simpler mock ledgers, which are easier to set up and reason about compared to the complex real ledger.
+Abstraction is considered good engineering practice, enhancing clarity, reducing dependencies, and making the system easier to understand and maintain.
+
+## Composability
+
+Given the complexity and scale of the consensus layer codebase, it is essential to divide it into smaller, manageable components that can be understood and modified independently.
+Composability is a key technique employed to achieve this.
+A prime example is the [Hard Fork Combinator](../references/glossary.md#hard-fork-combinator) (HFC), which enables the combination of different consensus protocols (such as BFT and Praos) and ledgers (such as Byron and Shelley) into a unified composite protocol or ledger for the hybrid chain.
+
+## Predictable Performance
+
+This goal ensures that node operators can configure nodes for "normal circumstances" without the network failing during infrequent but expected events.
+It aims to make node performance predictable, ensuring that the average-case scenario aligns with the worst-case scenario in terms of resource requirements—not only for security but also to maintain network stability with honest nodes.
+
+## Protection Against DoS Attacks
+
+The consensus layer must help safeguard the network against disruptions, making denial-of-service (DoS) attacks prohibitively expensive for adversaries.
+This involves design decisions that prevent attackers from easily causing a node to perform extensive, wasteful computations.
+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://input-output-hk.github.io/io-sim/).

docs/website/contents/explanations/index.md

@@ -1 +1,14 @@
 # Introduction
+
+Welcome to the documentation for the [`ouroboros-consensus`](https://github.com/IntersectMBO/ouroboros-consensus) repository.
+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 the Consensus component when forging a block and by the Network layer's transaction submission mini-protocol to diffuse transactions among nodes.
+
+A core design principle in the implementation of these components is the abstraction from specific ledger and protocol implementations.
+The aim is to decouple the consensus protocol from the ledger and to support multiple consensus algorithms and ledgers for improved adaptability and maintainability.
+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.

docs/website/contents/references/glossary.md

@@ -31,6 +31,12 @@ Security analyses typically assume the worst-case, ie the behavior of all advers
 
 A chain fragment always has an anchor point, which is the predecessor of the oldest header/block on the fragment.
 
+## ;Babbage era
+
+The Babbage era is a major phase of the Cardano blockchain, identified as a [Shelley-based era](#shelley-based-eras), that succeeded the Alonzo era.
+On mainnet, it corresponds to least major protocol version 7 and ends when the version increments past 8.
+It uses the Ouroboros [Praos](#ouroboros-praos) consensus protocol.
+
 ## ;Block
 
 In some slots, the protocol allows a block-producing node to contribute to the chain; it does so by minting a new block.
@@ -58,6 +64,11 @@ A valid block satisfies the ledger rules in the context of the ledger state that
 
 Trusted honest caught-up peers that are used for syncing before a Genesis-capable node is released. By default, these are public root peers.
 
+## ;Byron era
+
+The Byron era refers to the first implementation of the Cardano blockchain, which was introduced in September 2017.
+On the [first implementation](https://github.com/input-output-hk/cardano-sl) it used the Ouroboros Classic consensus protocol. In the current Haskell implementation, the Byron Era uses the Permissive Ouroboros BFT consensus protocol, which is backwards compatible with the Ouroboros Classic protocol, relying on seven federated nodes for block production.
+
 ## ;Chain
 
 A sequence of blocks.
@@ -255,6 +266,12 @@ There is one at each era change but they can also happen within the same era; th
 Intra-era hard forks are mostly ledger related, for instance to fix a bug of (de)serialisation of transactions, or to add a new smart contract feature.
 Recently, hard forks have been given names: Vasil is the hard fork from Alonzo to Babbage; Valentine is an intra-era hard fork within Babbage.
 
+## ;Hard-fork combinator
+
+The Hard-fork Combinator (HFC) is a core architectural component of the Consensus layer designed to enable sequential composition of multiple blockchain eras (eg Byron, Shelley, Allegra, Babbage, etc.) so they can be managed as a single, unified chain type.
+It is responsible for handling the complex logistics of transitions, including providing the necessary context for the underlying ledgers.
+It facilitates the necessary translations between successive eras, such as translating the ledger state and chain dependency state during an era boundary
+
 ## ;Header-body split
 
 The [stability window](#stability-window) enables the engineering design of nodes exchanging chains of headers before exchanging chains of the corresponding blocks.
@@ -461,6 +478,9 @@ A slight refinement of [Praos](#ouroboros-praos).
 ## ;Ouroboros Praos
 
 The protocol underlying the latest Cardano era.
+It was the first proof-of-stake protocol designed and formally proven to provide security against fully-adaptive corruption in a setting that tolerates adversarial message delays (up to Δ slots).
+Praos implements slot leader election using stake distribution and Verifiable Random Functions (VRF), and honest parties converge to a unique chain view primarily by following the longest chain rule.
+The name "Praos" means "mellow" or "gentle," derived from the protocol's use of deliberately inserted empty slots to facilitate synchronization in the semi-synchronous environment.
 
 ## ;Peer kinds
 
@@ -485,6 +505,14 @@ Consider a chain fragment `F`:
 
 Note that these notions are always relative to a particular anchor, so different chain fragments must have the same anchor when their total weight is to be compared.
 
+## ;Permissive BFT (PBFT)
+
+Ouroboros Permissive BFT (PBFT) is a simple, deterministic, Byzantine Fault Tolerant (BFT) consensus protocol derived from Ouroboros-BFT, typically designed to ensure consistency and liveness against `t < n/3` Byzantine faults.
+The protocol is deemed "permissive" because it relaxes the strict requirement that blocks must be signed according to a predetermined round-robin schedule.
+Instead, blocks are merely required to be signed by any of the known core nodes.
+However, this permissiveness is still bounded: the protocol limits the number of signatures a given node can contribute within a window of blocks.
+
+
 ## ;Phases
 
 Byron, Shelley, Goguen (current one as of August 2023), Basho, Voltaire.
@@ -565,6 +593,11 @@ Some entity that maintains/controls one or multiple stake pools.
 
 The process of becoming synchronized with the system, either from scratch or due to a temporary restart/crash/local network outage.
 
+## ;TPraos
+
+TPraos (Transitional Praos) is a Proof-of-Stake consensus protocol used in the early decentralized eras of Cardano (specifically Shelley, Allegra, and Mary).
+It was designed to manage the transition from the initial federated system by using a decentralization parameter (`d`) which controls the ratio of slots produced by legacy bootstrap keys (OBFT slots) versus those produced by stake pools selected via Ouroboros Praos, allowing for a smooth shift toward full decentralization.
+
 ## ;Transactions
 
 If a slot has multiple leaders or if the leader of a slot hadn't received the latest block, then they will issue multiple blocks that all claim to have the same predecessor.A [block body](#header-and-body) is just a sequence of transactions.