Learn section: revised copy, adjusted contents (#1454)

This pull request proposes renaming the 'Core concepts' section to
'Learn'. This change will allow us to consolidate more overviews in this
section, such as the protocol overview and the specification, as
suggested by the team in the documentation questionnaire. The 'Learn'
section will cater to general users interested in core concepts, the
Hydra overview, and related information.

---------

Co-authored-by: Franco Testagrossa <[email protected]>
Co-authored-by: Franco Testagrossa <[email protected]>

docs/benchmarks/profiling.md

@@ -10,7 +10,7 @@ contributors to the `hydra-node`.
 On every PR and also for the latest `master`, we do compute typical transaction
 costs in size, memory and cpu usage of the Hydra protocol transactions on
 Cardano. The latest results can be seen
-[here](/benchmarks/transaction-cost/).
+[here](https://hydra.family/head-protocol/benchmarks/transaction-cost/).
 
 Such benchmarks provide a great overview of what "fits" into a given transaction
 in terms of maximum transaction size, percent of maximum memory and cpu budget.

docs/core-concepts/behavior.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 # API Behavior

docs/core-concepts/index.md

@@ -2,7 +2,7 @@
 sidebar_position: 1
 ---
 
-# Core Concepts
+# Learn
 
 ```mdx-code-block
 import DocCardList from '@theme/DocCardList';

docs/core-concepts/layer-two.md

@@ -2,51 +2,50 @@
 sidebar_position: 3
 ---
 
-# Layer 2 Solutions
+# Layer 2 solutions
 
-> What does layer 2 mean? What types of layer 2 solutions exist? 
+This section provides an overview of various types of layer 2 solutions, along with several examples.
 
-In the blockchain industry, we talk about **layer 2** solution whenever we refer to a solution that overlays an existing protocol (the layer 1) to provide either additional functionality or performance benefits over the underlying protocol. In essence, they are generic purpose solutions built on top of a protocol to enable other applications. They provide a framework for developing decentralized applications with generally different trade-offs than the underlying layer 1 protocol.
+In the blockchain industry, a layer 2 solution refers to any protocol that overlays an existing protocol (layer 1) to provide additional functionality or performance benefits. Essentially, these solutions are built on top of the base protocol to enable other applications. They offer a framework for developing decentralized applications with different trade-offs compared to the underlying layer 1 protocol.
 
-## State Channels
+## State channels
 
-The Hydra head protocol is a layer 2 solution which belongs to the family of **state channels**, which is itself a descendant of **payment channels**. A payment channel allows for two or more parties to exchange funds according to a given off-chain protocol without having to commit all transactions to the underlying blockchain. They are historically one of the first kind of layer 2 solution to arise as an answer to scalability issues of permission-less ledgers (and consequently, they're also the most studied and known kind of solutions).
+The Hydra Head protocol is a layer 2 solution within the family of **state channels**, which evolved from **payment channels**. A payment channel allows two or more parties to exchange funds using an off-chain protocol without committing all transactions to the underlying blockchain. Historically, they were among the first types of layer 2 solutions developed to address the scalability issues of permissionless ledgers, making them the most studied and well-known.
 
-State-channels extend the traditional concept of payment channels to support smart-contracts over off-chain channels. In such a setup, one or more parties are no longer limited to pure transactional payments, but they can execute full-blown scripts validations to handle complex logic, off-chain, only to later commit the result back to the layer 1. 
+State channels extend the concept of payment channels to support smart contracts over off-chain channels. In this setup, parties can execute complex logic and validate full-blown scripts off-chain, not just transactional payments. The final result is then committed back to the layer 1 blockchain.
 
 #### Examples
 
 - Lightning (Bitcoin)
 - Perun (Ethereum, Polkadot, Cosmos)
 - Sprites (Ethereum)
-- And of course, our favorite: **Hydra: Head** (Cardano)
+- And of course, our favorite: **Hydra: Head** (Cardano).
 
-## Side Chains
+## Sidechains
 
-**Side chains** allow for transferring assets from a layer 1 protocol to a new chain with its own set of consensus rules. Usually, a side-chain provides either a simpler or more efficient consensus mechanism which allows for more scalability or which ease the implementation of new functionality harder to get adopted on the layer 1. Often, this comes at the price of decentralization or security, since side-chains are typically involving only few actors or committees at their root. 
+Sidechains allow for transferring assets from a layer 1 protocol to a new chain with its own set of consensus rules. Typically, a sidechain provides a simpler or more efficient consensus mechanism that allows for greater scalability or facilitates the implementation of new functionality that is harder to adopt on layer 1. Often, this comes at the price of decentralization or security, as sidechains typically involve only a few actors or committees at their core.
 
-Side chains are however "proper chains", with blocks produced by validator and usually, smart-contract capabilities. Therefore, unlike state-channels, they provide data-availability and offer ways to participate into the validation and observation of the chain (in a state-channel, only participants of the channel really have a reliable view of what is going on in the channel). Entering a side-chain is usually done by burning or locking assets on the layer 1, to receive an equivalent counterpart on the side-chain network. 
+Sidechains are, however, 'proper chains', with blocks produced by validators and usually smart contract capabilities. Therefore, unlike state channels, they provide data availability and offer ways to participate in the validation and observation of the chain. In a state channel, only participants of the channel have a reliable view of what is happening within the channel. Entering a sidechain is usually done by burning or locking assets on layer 1 to receive an equivalent counterpart on the sidechain network.
 
 #### Examples
 
 - Liquid Network (Bitcoin)
 - RSK (Bitcoin)
 - Polygon (Ethereum)
-- Milkomeda (Cardano)
+- Milkomeda (Cardano).
 
 ## Rollups
 
-Another major type of layer 2 solution is **Rollups**. They provide a way for moving transaction execution off-chain only to keep a much more compact representation of the execution on the layer 1. Rollups are typically driven by a central actor, often called _sequencer_, with high availability and computational resource demands off-chain, while regularly leaving verifiable breadcrumbs on-chain (the rollups).
+Another major type of layer 2 solution is rollups. Rollups move transaction execution off-chain, keeping a much more compact representation of the execution on layer 1. They are typically driven by a central actor, often called a *sequencer*, which has high availability and computational resource demands off-chain, while regularly leaving verifiable ‘breadcrumbs’ on-chain (the rollups).
 
-In general, rollups come in two popular flavours 
-+ **optimistic** rollups involving interactive games for fraud disputes, and
-+ **validity** rollups involving Zero-Knowledge-based proofs for validity checks.
+In general, rollups come in two popular flavors: *optimistic* rollups and *validity* rollups.
 
-In the former, rollups are posted on-chain optimistically and verification are done _a posteriori_ by independent validators. In case of disagreement, the dispute is resolved on-chain and the rollup batch publisher endure financial consequences. In zero-knowledge approaches, a succinct proof of execution is calculated off-chain, published alongside the rollup batch commitment and controlled by on-chain validators (which thus enforce the rightful execution of the rollup). 
+- **Optimistic rollups** involve interactive games for fraud disputes. Transactions are posted on-chain optimistically, and verification is performed afterward by independent validators. In case of disagreement, the dispute is resolved on-chain, and the rollup batch publisher incurs financial consequences.
+- **Validity rollups** involve zero-knowledge proofs for validity checks. A succinct proof of execution is calculated off-chain, published alongside the rollup batch commitment, and controlled by on-chain validators, enforcing the rightful execution of the rollup.
 
 #### Examples
 
 - Arbitrum (Ethereum)
 - Optimism (Ethereum)
 - Hermez (Ethereum)
-- ZKSync (Ethereum)
+- ZKSync (Ethereum).

docs/core-concepts/protocol-overview.md

@@ -0,0 +1,28 @@
+---
+sidebar_position: 4
+---
+
+# Hydra Head protocol overview
+
+Hydra is the layer 2 scalability solution for Cardano, designed to increase transaction speed through low latency and high throughput while minimizing transaction costs. [Hydra Head](https://eprint.iacr.org/2020/299.pdf) is the first protocol of the Hydra family that lays the foundation for more advanced deployment scenarios using isomorphic, multi-party state channels. For an introduction to the protocol, refer to these two blog posts: 
+
+* [Hydra – Cardano’s solution for ultimate layer 2 scalability](https://iohk.io/en/blog/posts/2021/09/17/hydra-cardano-s-solution-for-ultimate-scalability/)
+* [Implementing Hydra Heads: the first step towards the full Hydra vision](https://iohk.io/en/blog/posts/2022/02/03/implementing-hydra-heads-the-first-step-towards-the-full-hydra-vision/).
+
+Hydra simplifies off-chain protocol and smart contract development by directly adopting the layer 1 smart contract system, allowing the same code to be used both on- and off-chain. Leveraging the Extended Unspent Transaction Output (EUTXO) model, Hydra enables fast off-chain protocol evolution with minimal round complexity and allows asynchronous and concurrent state channel processing. This design enhances transaction confirmation time and throughput while keeping storage requirements low.
+
+In Hydra, a set of parties coordinates to commit a set of UTXOs (owned by the parties) into an off-chain protocol called the Head protocol. This UTXO set constitutes the initial head state, which can be evolved by handling smart contracts and transactions among the parties without blockchain interaction, provided all participants behave optimistically. The isomorphic nature of Hydra heads ensures that transaction validation and script execution proceed according to the same rules as on-chain, simplifying engineering and guaranteeing consistency. In case of disputes or termination, the current state of the head is decommitted back to the blockchain, updating the blockchain state to reflect the off-chain protocol evolution. This decommit process is efficient, independent of the number of parties or the size of the head state, and supports incremental commits and decommits, allowing UTXOs to be added or removed from a running head without closing it.
+
+## Hydra head lifecycle 
+
+There are different flavors and extensions of the Hydra Head protocol, but first, let's discuss the full lifecycle of a basic Hydra head and how it allows for isomorphic state transfer between layer 1 and layer 2.
+
+![](./hydra-head-lifecycle.svg)
+
+A group of online and responsive participants form a Hydra head. Participants **init**ialize a head by announcing several parameters on-chain, including the participants list. Then, each participant **commit**s unspent transaction outputs (UTXOs) from the Cardano main chain to it. These UTXOs are **collect**ed and made available in the Hydra head as the initial state (U0). Participants can **abort** the process and recover their funds at any time before collecting the UTXOs.
+
+While open, participants can utilize the Hydra head via a Hydra node to submit transactions in the head network. These transactions maintain the same format and properties as those on the main chain – they are isomorphic. When spending UTXO entries and creating new ones in a Hydra head, all participants must acknowledge and agree on the new state in so-called snapshots (U1...Un). Snapshots are not posted back onto layer 1 but are only retained by the participants.
+
+Any participant can **close** the head using a snapshot, for example, if they wish to cash out on the mainnet or if another party misbehaves or stalls the head's evolution. There exists a mechanism to **contest** the final state on the main chain. Ultimately, a `FanOut` transaction distributes the final agreed state and makes it available on layer 1, transitioning the state that existed virtually in the head to an on-chain state.
+
+

docs/core-concepts/scalability.md

@@ -4,71 +4,36 @@ sidebar_position: 2
 
 # Scalability
 
-Any decentralized system is fundamentally limited in its scalability. This also
-applies to blockchains and is rooted in the fact that security is achieved
-through massive global replication of transactions. The more decentralized the
-system is, the more time and other resources are used up to process
-transactions. This is also often called the blockchain trilemma, where
-_decentralization_, _security_ and _scalability_ counter-act each other.
-
-Even though Cardano uses a very efficient consensus algorithm, the fact that
-it's distributed globally between thousands of block-producing nodes (with quite
-a low bar in system requirements) will have it create a block on average every
-20 seconds.
-
-These limitations ultimately mean that any state can only change in discrete
-steps of this duration. Besides, given peak hours on the blockchain when there
-is a transaction queue, the time required to settle and confirm a transaction
-might also be higher, further increasing the effective settlement time. This is
-because your transaction might not be added to the next block, but the second or
-even third one coming.
-
-## Vertical and horizontal scaling
-
-In general, there are two ways of scaling systems: **vertical** and
-**horizontal**. Both try to increase resources available to the system to
-achieve better overall performance.
-
-For vertical scaling, the performance of the system is increased by adding
-resources available to the already existing instances of the system. For
-Cardano, this practically means increasing the block size or reducing the block
-time. This is a great way to initially scale the system, but is ultimately
-limited by network latency and processing power of block-producing nodes. To
-ensure the security of the system, each block has roughly 5 seconds to propagate
-through the network, which includes relaying and validating it through multiple
-hops. At some point, driving the system requirements up will also reduce the
-level of decentralization, as less individuals will be able to run such a node.
-
-Scaling a system horizontally, means to increase performance of the overall
-system by adding more individual instances alongside each other. Practically,
-this could mean that besides the main chain, multiple side chains are spun up
-that do the same thing, each "x" seconds all instances create a block. Unlike
-vertical scaling, horizontal scaling does not have a direct limit, there can be
-many side chains that are connected to the layer one. A major downside to this
-way of scaling is that any state of the system is split into multiple pieces.
-Each instance is blind to what is happening on the other instances and moving
-state between instances results requires additional work (the state is sharded).
+Decentralized systems, including blockchains, face fundamental scalability limitations due to their reliance on global transaction replication to ensure security. This constraint is commonly known as the blockchain trilemma, where _decentralization_, _security_, and _scalability_ counteract each other. Although Cardano employs an efficient consensus algorithm, its global distribution among thousands of block-producing nodes results in block creation approximately every twenty seconds. During peak transaction times, this can lead to increased settlement times as transactions may not be included in the immediate next block.
+
+There are two primary approaches to scaling systems: vertical and horizontal scaling.
+
+## Vertical scaling
+
+Vertical scaling enhances system performance by increasing resources available to existing system instances. For Cardano, this could involve increasing block size or reducing block time. However, vertical scaling is limited by network latency and the processing power of block-producing nodes. Each block requires roughly five seconds to propagate through the network, ensuring security through multiple validation steps. Raising system requirements can reduce decentralization, as fewer individuals may be able to run such nodes.
+
+## Horizontal scaling
+
+Horizontal scaling improves overall system performance by adding more instances alongside each other. This might involve creating multiple sidechains that operate in parallel to the main chain, each producing blocks at regular intervals. Unlike vertical scaling, horizontal scaling has no direct limit, allowing many sidechains to connect to the layer 1 blockchain. However, this method fragments the system state, necessitating additional work to transfer state between instances.
 
 ![Horizontal & Vertical scaling](./horizontal-vertical-scaling.png)
 
-## State channels
+## Layer 1 and layer 2 solutions
+
+Layer 1 solutions aim to improve scalability by adapting the underlying ledger protocols directly. However, they face inherent limitations due to the complexity of the settlement process, which involves extensive data exchange among a large, dynamic set of participants.
 
-The Hydra Head protocol is a form of state channel and can be mostly classified
-as a horizontal scaling solution. While multiple instances of them can be
-deployed to off-load and increase the scalability of the overall system, it
-provides for a flexible way to decide on the level of decentralization of each
-instance and provides a mostly frictionless way to transfer state between the
-mainchain and the individual Hydra heads (through it _isomorphic_ nature).
+Layer 2 solutions, such as state channels, offer an alternative approach by overlaying new protocols on top of the blockchain. These solutions allow parties to securely transfer funds to an off-chain protocol instance, conduct transactions independently of the blockchain, and return the final state to the blockchain when needed. This method does not require additional trust assumptions beyond those of the underlying blockchain and can be highly efficient when all participants behave as expected.
+
+Read more about layer 2 solutions and their types in the next section. 
+
+
+## State channels and the Hydra Head protocol
+
+The Hydra Head protocol is a form of state channel and can be classified as a horizontal scaling solution. Multiple instances can be deployed to offload transactions and enhance the overall scalability of the system. It provides a flexible way to determine the level of decentralization for each instance and offers a mostly frictionless method to transfer state between the main chain and individual Hydra heads due to its isomorphic nature. 
 
 ![State Channel](./state-channel.png)
 
-State channels allow to take parts of the state from the layer one blockchain
-and validate its progress elsewhere between only those parties who are concerned
-about this state. Then, after this computation is done, the parties return the
-final state on which all parties agree back to layer one. This construction
-means that the 20 second block time limit no longer applies and state can be
-evolved as fast as only the involved parties approve.
+State channels allow parts of the state from the layer 1 blockchain to be validated off-chain by the concerned parties. Once the computation is complete, the parties return the final agreed-upon state to the layer 1 blockchain. This construction eliminates the 20-second block time limit, enabling state evolution as quickly as the involved parties approve.
+
+In conclusion, the Hydra Head protocol enables operators to balance the trade-off between decentralization, security, and scalability differently from the underlying blockchain, thereby meeting the specific needs of individual applications.
 
-In conclusion, Hydra Head will allow operators to strike the fundamental
-trade-off between decentralization, security and scalability different than the
-underlying blockchain to serve the needs of individual applications.