diff --git a/docs/learn/protocols/iota2.0/core-concepts/consensus/chain-switching-rule.md b/docs/learn/protocols/iota2.0/core-concepts/consensus/chain-switching-rule.md
new file mode 100644
index 00000000000..6a41e3ccfa5
--- /dev/null
+++ b/docs/learn/protocols/iota2.0/core-concepts/consensus/chain-switching-rule.md
@@ -0,0 +1,56 @@
+# Chain Switching Rule
+
+The chain switching rule in IOTA 2.0 is a tool that enables liveness for finalization after an asynchronous period ends and allows for the safety property of the finalization flag. With the chain switching rule, a node finds the heaviest chain and syncs from that chain, i.e., updates the locally maintained Tangle and the ledger.
+
+## Cumulative Weight
+
+### Weight of a Slot Commitment
+
+Let $(C_1,\ldots,C_s,C_{s+1},\dots,C_{s+d})$ be a slot commitment chain.
+Let $A$ denote the set of all [accepted](consensus-flags.md#acceptance-flag) validation blocks that are committed into $C_{s+1},\dots,C_{s+d}$ such that each block from $A$ [approves](preliminaries.md#about-blocks-and-the-tangle) $C_s$. Then the weight of the slot commitment $C_s$ with drifting parameter $d$ (in the code, it is set to parameter `maxCommittableSlotAge`) is defined as the sum of [voting weights](preliminaries.md#epoch-committee) of committee members who issued a block from $A$, i.e. those committee members who approve this commitment during $d$ slots after slot $s$, i.e.
+
+$$
+W(C_{s})=\sum_{i\in IssuerIDs(A)}W_i(e),
+$$
+
+where slot $s$ belongs to epoch $e$.
+
+### Example
+
+In this example, the committee consists of $7$ nodes. Their weights are specified at the bottom of the following image.
+
+Suppose that the current slot commitment chain consists of two elements $(C_1,C_2)$. The weight of the commitment $C_1$ with drifting parameter $d=3$ can be computed as follows:
+
+All the blocks, that are included in the set $A$ in the above definition, are highlighted with a border. The weight $W(C_1)$ is equal to the sum of voting weights of the blue, orange, purple, grey, and green nodes, i.e. $W(C_1)=1+2+3+1+1=8$. The weight of the green node that commits to $C_2$ is counted as $C_2$ is an extension of $C_1$ and the corresponding block of the green node is issued at slot $4$, which is covered by the drifting parameter. The weight of the grey node is counted only once in $W(C_1)$ even though it has issued two blocks satisfying the requirements. The weight of the yellow node that commits to $C_1$ at slot $5$ is not counted as this slot is not covered by the drifting parameter $d=3$, i.e. $1+3<5$.
+
+
+
+**Image:** Illustration for computing the weight of a slot commitment.
+
+### Cumulative Weight of a Slot Commitment Chain
+
+Let $(C_1,\ldots,C_s,C_{s+1}\dots,C_{s+d})$ be a slot commitment chain. Then the cumulative weight of the chain $(C_1,\ldots,C_s)$ with a drifting parameter $d$ is defined as
+
+$$
+CW(C_1,\ldots,C_s)=\sum_{j=1}^{s}W(C_j).
+$$
+
+## Chain Switching Rule Algorithm
+
+The chain switching rule relies on the last finalized slot and the [cumulative weight of slot commitment chains](preliminaries.md#5-cumulative-weight).
+
+### Conflicting Slot Commitments
+
+Two slot commitment chains are called conflicting if none of them is a prefix of the other. A slot commitment $C$ is called conflicting to a slot commitment chain if this chain is conflicting with the slot commitment chain that ends at $C$.
+
+Suppose a node adopts a slot commitment chain $ch_{loc}=(C_1,\dots,C_{s+d})$ and receives a block $b$ from a conflicting slot commitment chain $ch_{fork}=(B_1,\dots,B_{s+d})$. Then the node proceeds with the following steps:
+
+1. Find the slot index $f$ of the forking point, i.e. $C_1=B_1,\dots,C_f=B_f$ and $C_{f+1}\neq B_{f+1}$.
+2. Check if the last finalized slot of the chain $ch_{loc}$ is greater than $f$. If yes, ignore the block $b$ and stay on the chain $ch_{loc}$. Otherwise, proceed with the next step.
+3. Check if the inequality holds $CW(B_1,\dots,B_s)\le CW(C_1,\dots,C_s)$. If yes, ignore the block $b$ and stay on the chain $ch_{loc}$. Otherwise, proceed with the next step.
+4. If there exist at least `optsChainSwitchingThreshold=3` consecutive indices when the cumulative weight of the conflicting chain $ch_{fork}$ is larger than the one of the currently adopted chain $ch_{loc}$, i.e. $CW(B_1,\dots,B_{t})>CW(C_1,\dots,C_{t}), CW(B_1,\dots,B_{t+1})>CW(C_1,\dots,C_{t+1}), CW(B_1,\dots,B_{t+2})>CW(C_1,\dots,C_{t+2})$ for $f\le t \le s-2$, then request the attestation for the cumulative weight, validate the attestations and switch $ch_{loc}$ to $ch_{fork}$ after the current slot is completed.
+
+### Chain Switching
+
+Switching the chain only happens when the current slot is finished. This property is important for the safety of the finalization flag as it does not allow honest nodes to vote on conflicting chains within one slot.
+
diff --git a/docs/learn/protocols/iota2.0/core-concepts/consensus/consensus-flags.md b/docs/learn/protocols/iota2.0/core-concepts/consensus/consensus-flags.md
new file mode 100644
index 00000000000..996526adce0
--- /dev/null
+++ b/docs/learn/protocols/iota2.0/core-concepts/consensus/consensus-flags.md
@@ -0,0 +1,126 @@
+# Consensus Flags
+
+## Conditions for Consensus Flags
+
+The following table summarizes the required conditions used by all nodes in the network to determine the status of blocks and transactions. Every condition represents a specific [validation block pattern](introduction.md#provide-consensus-flags) that occurs within the structure of the Tangle. Once a node detects a new pattern, the node marks the corresponding object with the respected flag.
+
+| Confidence Level | Block $b$ | Conflicting Transaction $b.Tx$ |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Pre-Acceptance | [Online supermajority of blocks approving block $b$](#pre-acceptance-flag) | - |
+| Acceptance | [Online supermajority of pre-accepted blocks approving block $b$](#acceptance-of-blocks-and-non-conflicting-transactions) | [Online supermajority of pre-accepted blocks voting for transaction $b.Tx$\*](#acceptance-of-conflicting-transactions) |
+| Pre-Confirmation | [Total supermajority of blocks approving block $b$](#pre-confirmation-flag) | - |
+| Confirmation | [Total supermajority of pre-confirmed blocks approving block $b$](#confirmation-of-blocks-and-non-conflicting-transactions) | [Transaction $b.Tx$ is accepted and block $b$ is confirmed](#confirmation-of-conflicting-transactions) |
+| Finalization | [Confirmed block containing the slot commitment\*\*](#finalization-flag) | [Confirmed block containing the slot commitment\*\*](#finalization-flag) |
+
+\*These blocks represent the latest opinion of the issuers.
+\*\*Finalization is defined on the slot commitment level. A block or transaction is finalized if it is committed into the slot commitment and this commitment is finalized.
+
+## Pre-Acceptance Flag
+
+To pre-accept blocks, nodes make use of the weight of the [online committee](preliminaries.md#epoch-committee) $\mathcal{C}_{online}$. This preliminary status is defined for blocks only.
+
+A block $b$ is _pre-accepted_ if there exists an [online supermajority of blocks](preliminaries.md#total-and-online-supermajority) $S$ so that every block in $S$ [approves](preliminaries.md#about-blocks-and-the-tangle) $b$.
+
+### Example
+
+In the following example, $7$ committee members have equal weight, and only $4$ are online. Different colors are used to distinguish distinct block issuers. Block $b$ is pre-accepted because an online supermajority of the committee approves this block. Note that the block is pre-accepted even though no total supermajority of blocks approve $b$.
+
+
+**Image:** Pre-acceptance of a block.
+
+## Pre-Confirmation Flag
+
+To pre-confirm blocks, nodes make use of the weight of the [total committee](preliminaries.md#epoch-committee) $\mathcal{C}_{total}$. In principle, the same methodology as for the pre-acceptance flag is used for this flag. However, the weight of nodes approving a block (or voting for a transaction) is compared with the [total weight](preliminaries.md#epoch-committee) $W_{total}$. This preliminary flag is defined for blocks only.
+
+A block $b$ is _pre-confirmed_ if there exists a [total supermajority of blocks](preliminaries.md#total-and-online-supermajority) $S$ such that every block in $S$ [approves](preliminaries.md#about-blocks-and-the-tangle) $b$. In this case, $S$ _pre-confirms_ $b$.
+
+### Example
+
+Block $b$ is pre-confirmed in the following example because a total supermajority of nodes approves this block.
+
+
+**Image:** Pre-confirmation of a block.
+
+## Acceptance Flag
+
+To define acceptance for blocks and transactions, nodes use the weight of the online committee $\mathcal{C}_{online}$.
+
+Once a block or transaction is accepted, it stays accepted in the perception of a node unless the node [switches its slot commitment chain](chain-switching-rule.md). In other words, accepted blocks and transactions issued in a slot become committable, i.e., they are used to generate the [commitment](preliminaries.md#slot-commitment-chain) for the slot.
+
+### Acceptance of Blocks and Non-Conflicting Transactions
+
+A block $b$ is accepted if there is an [online supermajority](preliminaries.md#total-and-online-supermajority) of [pre-accepted](#pre-acceptance-flag) blocks approving $b$. If the transaction included in the block is non-conflicting, it also becomes accepted.
+
+#### Example
+
+In the following example, the online committee consists of $4$ nodes with equal weight. The block $b$ is accepted since $3$ pre-accepted blocks are approving this block.
+
+
+**Image:** Acceptance of a block.
+
+### Acceptance of Conflicting Transactions
+
+A conflicting transaction $tx$ is accepted if there exists an [online supermajority](preliminaries.md#total-and-online-supermajority) of [pre-accepted](#pre-acceptance-flag) blocks which [vote](preliminaries.md#reality-based-utxo-ledger) for $tx$.
+
+:::warning Removed Transactions
+
+Any transaction that conflicts with an accepted transaction becomes [rejected](preliminaries.md#reality-based-utxo-ledger) and gets removed from the reality-based ledger.
+
+:::
+
+#### Example:
+
+In the following example, the transaction $tx$ is accepted since an online supermajority of pre-accepted blocks vote for $tx$.
+
+Note that the blue node initially voted for transaction $tx'$ because it was delivered before $tx$. However, the blue node changes its stance in the following validation block, as it has received and processed both validation blocks that voted for $tx$. According to the blue node's local perception, $tx$ now receives support from the majority of the network. This means that the [preferred reality](relevant-algorithms.md#algorithm-to-compute-the-preferred-reality) of the blue node now contains $tx$, and the [branch](preliminaries.md#reality-based-utxo-ledger) of the next validation block is aligned with the preferred reality.
+
+
+**Image:** Acceptance of a conflicting transaction.
+
+## Confirmation Flag
+
+### Confirmation of Blocks and Non-Conflicting Transactions
+
+A block $b$ is confirmed if there is a [total supermajority](preliminaries.md#total-and-online-supermajority) of [pre-confirmed](#pre-confirmation-flag) blocks approving $b$. In addition, these pre-confirmed blocks must be issued within `optsConfirmationRatificationThreshold=2` slots after the slot at which $b$ is issued. If the transaction in the block is non-conflicting, it is also confirmed.
+
+:::note
+
+The parameter `optsConfirmationRatificationThreshold` is set to a low value to guarantee the irreversibility of the confirmation flag and the [finalization flag](#finalization-flag), which utilizes confirmation. The safety property is achieved because honest nodes do not [switch their adopted slot commitment chain](chain-switching-rule.md) until their current slot concludes. This means that the decision in the voting process is achieved in a short period while a total supermajority of nodes stays on the same slot commitment chain.
+
+:::
+
+#### Example
+
+In the following example, the block $b$ is confirmed as a total supermajority of pre-confirmed blocks approve $b$.
+
+
+**Image:** Confirmation of a block.
+
+### Confirmation of Conflicting Transactions
+
+A conflicting transaction $tx$ is confirmed if $tx$ is [accepted](#acceptance-of-conflicting-transactions) and one of the attachments (blocks containing $tx$) is [confirmed](#confirmation-of-blocks-and-non-conflicting-transactions).
+
+#### Example
+
+In the following example, $tx$ is confirmed as it first was accepted, and then the block containing $tx$ gets confirmed.
+
+
+**Image:** Confirmation of a conflicting transaction.
+
+## Finalization Flag
+
+Finalization in the IOTA 2.0 consensus protocol works on the slot commitment level. This means that to finalize a block (a transaction), which is issued at a slot $s$, two conditions should hold:
+
+1. The block or transaction is committed to slot commitment $C_s$ of slot $s$;
+2. The commitment $C_s$ for slot $s$ is finalized.
+
+This means finalization of the commitment $C_s$ implies that all blocks and transactions committed into $C_s$ and all the previous commitments in the [slot commitment chain](introduction.md#slot-commitment-chains) that ends at $C_s$ are finalized as well.
+
+A slot commitment $C$ is finalized if a block contains the commitment $C$, and this block gets [confirmed](#confirmation-of-blocks-and-non-conflicting-transactions).
+
+### Example
+
+In the following example, slot commitment $C_1$ is finalized, thanks to the [confirmation](#confirmation-flag) of the block containing $C_1$. Consequently, all blocks and transactions committed into $C_1$, are finalized.
+
+
+**Image:** Finalization of a slot commitment.
diff --git a/docs/learn/protocols/iota2.0/core-concepts/consensus/introduction.md b/docs/learn/protocols/iota2.0/core-concepts/consensus/introduction.md
new file mode 100644
index 00000000000..fda07f028f2
--- /dev/null
+++ b/docs/learn/protocols/iota2.0/core-concepts/consensus/introduction.md
@@ -0,0 +1,99 @@
+# Consensus on a DAG
+
+The consensus protocol is necessary to achieve agreement among the nodes of the network on the set of blocks in the [Tangle](preliminaries.md#about-blocks-and-the-tangle) and the set of transactions in the [ledger](preliminaries.md#reality-based-utxo-ledger).
+
+Each node in the network maintains its local copy of the Tangle and runs the consensus protocol through logical interpretation of the directed acyclic graph (DAG). More precisely, the Tangle includes blocks that carry payloads, serving as transaction proposals intended to update the ledger. Block references serve as votes from the block issuers, expressing their support for the referenced blocks and transactions. IOTA 2.0 uses bounded-size committees whose members regularly issue validation blocks to reduce communication overhead and minimize confirmation time. To evaluate consensus flags for blocks and transactions, nodes in the network read votes from the validation blocks and find specific [validation block patterns](#provide-consensus-flags) in the Tangle.
+
+## Required Components for Consensus
+
+The following modules are necessary to achieve agreement using the IOTA 2.0 consensus protocol:
+
+### Approval Weight Module
+
+The approval weight module is responsible for gathering votes from the validation blocks, finding appropriate [validation block patterns](#provide-consensus-flags) in the Tangle, and evaluating the voting results to determine [consensus flags](consensus-flags.md) for blocks and transactions.
+
+:::info Consensus Flags
+
+This article does not specify which algorithms are used to find appropriate validation block patterns; it only focuses on describing the [consensus flags](consensus-flags.md) used by the protocol.
+
+:::
+
+### Tip Selection Algorithm
+
+The tip selection algorithm guides the voting and agreement process, in which the committee and other nodes partake. Consensus is achieved by logically interpreting the locally maintained Tangle, specifically its blocks and the references between them.
+
+All nodes collectively build the Tangle by attaching their blocks to a bounded number of randomly selected [eligible tips](tip-selection-algorithm.md#eligible-tips). Consensus on conflicting transactions is achieved without total ordering in a leaderless way. Committee members cast their votes by regularly issuing validation blocks, encoding their opinions about conflicting payloads by incorporating suitable [block references](preliminaries.md#block-references). The default number of references is increased for validation blocks to improve the time to achieve consensus for blocks and transactions.
+
+### Slot Commitment Chains
+
+Slot commitment chains are one of the core data structures in the protocol. A slot commitment is a hash digest of the accepted blocks and transactions issued during a given slot. It is linked to the commitment of the previous slot, creating a chain that extends back to the genesis block.
+
+Under good network conditions, nodes collectively produce the same slot commitments. Under network partitioning, there could be a divergence in the perception of the suffix of the slot commitment chain. However, the finalized part of the slot commitment chain is safe under any network conditions. When the network converges, all honest nodes eventually switch to the heaviest slot commitment chain with the latest [finalized slot commitment](#finalization), thanks to the **[chain switching rule](chain-switching-rule.md)**.
+
+## The Consensus Protocol’s Two Dimensions
+
+The consensus protocol can be divided in two separate dimensions charged with different responsibilities:
+
+1. [Agreement tasks for blocks and transactions](#agreement-tasks-for-blocks-and-transactions).
+2. [Provide Consensus Flags](#provide-consensus-flags).
+
+### Agreement Tasks for Blocks and Transactions
+
+The first dimension consists of the agreement tasks for blocks and transactions. It has two main tasks:
+
+#### Broadcast blocks reliably
+
+This task ensures the delivery of newly created blocks to all nodes in the network. Reliable broadcast guarantees that if an honest node includes a block in its locally maintained copy of the Tangle, all other honest nodes will eventually receive and deliver that block, including it in their locally maintained version.
+
+#### Agreement on conflicting transactions
+
+This task focuses on resolving conflicts that arise when multiple transactions in different blocks in the Tangle conflict with each other, attempting to consume the same output. By fulfilling this task, all honest nodes can reach a consensus on which conflicting transaction appears in the ledger, ensuring a consistent view across the network.
+
+### Provide Consensus Flags
+
+The second dimension provides different consensus flags or confidence levels about the irreversibility of blocks and transactions.
+
+When they receive a new validation block, nodes examine the Tangle to identify distinct validation block patterns, and attribute specific flags to blocks in the Tangle or transactions contained in the blocks.
+
+A pattern corresponds to a causally ordered set of validation blocks. For instance, if a block is [approved](preliminaries.md#about-blocks-and-the-tangle) by a supermajority of the committee (validators holding more than $2/3$ of the total voting power), then the block gets the [pre-confirmed flag](#pre-confirmation). In this context, the validation blocks from these validators constitute a validation block pattern necessary for pre-confirmation.
+
+The IOTA 2.0 consensus protocol is endowed with dynamic availability. This attribute ensures continuous operation even when some validator committee members may be offline or the network experiences partitions. During such instances, the online validator committee within each partition maintains the process of updating their available ledger, which is constructed from the transactions that have been [accepted](#acceptance).
+
+Once the network recovers from its divided state and a [supermajority](preliminaries.md#total-and-online-supermajority) of the committee is back online, the transaction finalization process recommences. The consensus flags differentiate between degrees of irreversibility. This aspect balances safety and liveness, providing different trade-offs to manage various network conditions effectively.
+
+:::info
+
+You can learn more about a formal description of consensus protocols supporting both safety and liveness in the [Ebb and Flow Protocols: A Resolution of the Availability-Finality Dilemma paper](https://arxiv.org/pdf/2009.04987).
+
+:::
+
+The consensus flags in the IOTA 2.0 consensus protocol are outlined as follows:
+
+#### Pre-Acceptance
+
+The [Pre-Acceptance flag](consensus-flags.md#pre-acceptance-flag) is an internal flag used to define Acceptance. This flag is raised for a block when the block is causally referenced by a [supermajority of the online committee members](preliminaries.md#total-and-online-supermajority). It means the block is deemed valid by a significant portion of the active validators in the network, hence suggesting initial agreement on the block's validity.
+
+#### Acceptance
+
+The [Acceptance flag](consensus-flags.md#acceptance-flag) is an internal flag that is used to generate [slot commitment chains](#slot-commitment-chains), i.e., only accepted blocks and transactions are committed.
+
+For a block, this flag shows whether the block is acknowledged by an [online supermajority](preliminaries.md#total-and-online-supermajority) of pre-accepted validation blocks.
+
+For a transaction, the flag indicates whether the transaction has received votes from an [online supermajority](preliminaries.md#total-and-online-supermajority) of pre-accepted blocks. This flag prioritizes liveness and quickly adjusts its response to varying network conditions.
+
+#### Pre-Confirmation
+
+The [Pre-Confirmation flag](consensus-flags.md#pre-confirmation-flag) is an internal flag used to define Confirmation. This flag is raised for a block when the block is causally referenced by a [supermajority of the total committee](preliminaries.md#total-and-online-supermajority), not just those currently online. It signifies a higher approval level than the pre-acceptance flag, but it is raised slowly under bad network conditions.
+
+#### Confirmation
+
+The [Confirmation flag](consensus-flags.md#confirmation-flag) is a flag that is exposed to the user in the wallet. For a block, it shows whether the block has been acknowledged by a [total supermajority](preliminaries.md#total-and-online-supermajority) of pre-confirmed validation blocks. This flag is raised for a transaction when it is accepted, and one of its attachments (blocks containing this transaction) gets confirmed. The confirmation flag favors safety and can be slow under bad network conditions.
+
+#### Finalization
+
+The [Finalization flag](consensus-flags.md#finalization-flag) is a flag that is exposed to the user in the wallet. This block or transaction flag relies on finalizing the slot commitment that commits to the block or transaction. The latter means that a block containing a given [slot commitment](preliminaries.md#slot-commitment-chain) (and all objects assigned to it) gets [confirmed](consensus-flags.md#confirmation-flag). This flag is safe under any network conditions.
+
+The flag hierarchy from Pre-Acceptance to Finalization is summarized in the following diagram:
+
+
+**Image:** Flag hierarchy from pre-acceptance to finalization.
diff --git a/docs/learn/protocols/iota2.0/core-concepts/consensus/preliminaries.md b/docs/learn/protocols/iota2.0/core-concepts/consensus/preliminaries.md
new file mode 100644
index 00000000000..9d957869aee
--- /dev/null
+++ b/docs/learn/protocols/iota2.0/core-concepts/consensus/preliminaries.md
@@ -0,0 +1,291 @@
+# Preliminaries
+
+Before diving deeper into the consensus algorithm's inner workings, you should familiarize yourself with the following terms.
+
+## Epochs and Slots
+
+The IOTA protocol divides time into non-overlapping slots of fixed duration `slotDurationSeconds`, set to `10` seconds. Slots are indexed with the slot index $s = 0, 1, 2, 3,...$. The slot indexed with $0$ is a unique slot that commences at negative infinity and concludes at the genesis timestamp `genesisUnixTime`. Every `2^slotsPerEpochExponent` sequential slots are grouped into epochs, which are enumerated with the epoch index $e = 0, 1, 2, 3,...$.
+
+Using slots primarily aims to generate [commitments](#slot-commitment-chain) for short time intervals. Generating commitments in a timely manner allows nodes to keep in Random Access Memory (RAM) only data of bounded size.
+
+Slot commitments improve the convergence of the overall consensus and let nodes know whether they need to synchronize their views on the Tangle. In addition, slot commitments facilitate data locality: understanding where a block belongs makes tasks such as block lookups, eviction, and pruning more straightforward. Furthermore, [finalization](consensus-flags.md#finalization-flag) occurs on the slot commitment level.
+
+The committee members are fixed within a given epoch, and their voting weights remain constant. However, at the epoch boundary, reconfiguration becomes possible, leading to potential changes in the composition of the committee and adjustments in their voting weights.
+
+### Epoch Committee
+
+For an epoch, a fixed subset of validators is responsible for achieving agreement about blocks and transactions issued during the epoch. This set has the size `committeeTotalSeats` (between `25` and `50`). The selected set of validators is called the epoch committee.
+
+A committee member is expected to issue validation blocks every `frequencyValidationBlock` seconds (set to either `0.5` or `1`) and to follow the [tip selection algorithm](tip-selection-algorithm.md) for selecting tips to be referenced by the validation blocks.
+
+#### Total committee
+
+Denote the total committee for epoch $e$ as $\mathcal{C}_{total}(e)$. Denote the voting weight of a node $i$ at epoch $e$ as $W_i(e)$. Note that $W_i(e)>0$ if and only if $i$ is a committee member in epoch $e$, i.e., $i\in \mathcal{C}_{total}(e)$.
+
+:::info
+
+In the first version of the protocol, all committee members have the same weight, specifically if $W_i(e)>0$, then $W_i(e)=1$. This will be changed in future updates of the protocol.
+
+:::
+
+The total committee is determined for [slot commitment chains](#slot-commitment-chain). Specifically, two nodes that adopt the same slot commitment chain before an epoch $e$ starts perceive the same total committee for epoch $e$.
+
+To support the dynamic availability of the protocol and timely generate slot commitments, only actively participating committee members are considered when determining which blocks and transactions are [accepted](consensus-flags.md#acceptance-flag).
+
+#### Online committee
+
+At time instant $t$ at epoch $e$, a node perceives the online committee $\mathcal{C}_{online}(t)\subset \mathcal{C}_{total}(e)$, as a subset of the committee that consists of committee members who have issued at least one block with the timestamp within `(t-activityWindow, t]`.
+
+:::info
+
+The online committee is a subjective notion determined by each node locally based on its perception of the Tangle. The block in the above definition must commit to the [slot commitment chain](#slot-commitment-chain) a node adopts. The protocol parameter `activityWindow` is set to `10` seconds.
+
+:::
+
+#### Total weight
+
+Denote the total weight of the total committee at epoch $e$ as:
+
+$$
+W_{total}(e)=\sum_{i\in\mathcal{C}_{total}(e)}W_i(e)
+$$
+
+#### Online weight
+
+Denote the online weight of the online committee at moment $t$ at epoch $e$ as:
+
+$$
+W_{online}(t)=\sum_{i\in\mathcal{C}_{online}(t)}W_i(e).
+$$
+
+:::note
+
+$W_{total}(e)$ is constant for the whole epoch $e$, whereas $W_{online}(t)$ can be changed based on the perception of a node at the moment $t$.
+
+In the following, the time instant index $t$ and epoch index $e$ are omitted in notation to simplify the discussion.
+
+:::
+
+## About Blocks and the Tangle
+
+The basic unit data structure in IOTA 2.0 is called a block. The collection of all blocks is called the Tangle. Since blocks contain references to previously issued blocks, the Tangle is a directed acyclic graph (DAG).
+
+For the notation of this article, a block is denoted as $b$, and a specific content of the block is referred to using the following fields
+
+| Name of the field | Description |
+| -------------------- | ------------------------------------------------------------------- |
+| $b.Tx$ | The payload of block $b$ |
+| $b.SlotCommitmentID$ | The [slot commitment](#slot-commitment-chain) included to block $b$ |
+| $b.IssuerID$ | The ID of the issuer of block $b$ |
+| $b.References$ | The [references](#reference-types) to the previously issued blocks |
+| $b.IssuingTime$ | The timestamp of block $b$ |
+
+**Table:** Fields of a block.
+
+:::info Block Fields
+
+Some fields in the block structure have been omitted to simply this article.
+
+:::
+
+### Supplementary Definitions
+
+#### Block approves block
+
+A block $b$ approves a block $c$ if there is a sequence of blocks $b_1=b,b_2,\ldots,b_t=c$ such that $b_i$ directly references $b_{i+1}$, i.e. $b_{i+1}\in b_i.References$.
+
+#### Cones of a block
+
+##### Past cone of a block
+
+For block $b$, the set of blocks that $b$ approves is the past cone of $b$.
+
+##### Future cone of a block
+
+For block $b$, the set of blocks that approve $b$, is the future cone of $b$.
+
+##### Example
+
+In the following example, the past cone of block $x$ is highlighted in red, encompassing all the blocks reachable from $x$ by following the directed edges. Similarly, the future cone is highlighted in blue.
+
+
+**Image:** Future and past cones of a block.
+
+#### Block votes for conflicting transaction
+
+A block $b$ and the issuer $b.IssuerID$ vote for a [conflicting transaction](#reality-based-utxo-ledger) $tx$ if the [branch of block](#reality-based-utxo-ledger) $b$ contains $tx$.
+
+#### Block approves slot commitment
+
+A block $b$ approves a slot commitment $C$ if the [slot commitment chain](#slot-commitment-chain) that ends with $b.SlotCommitmentID$ contains $C$. For instance, the block $b$ approves the slot commitment $C$ if $b$ contains $C$, i.e., $b.SlotCommitmentID = C$.
+
+### Block References
+
+Block references in IOTA 2.0 simultaneously serve two purposes:
+
+1. Contributing to the construction of an immutable directed acyclic graph structure on the block set.
+2. Encoding the issuer's perspective on which part of the Tangle is valid and which conflicting transactions are supported by a majority of the network. This means that nodes perform voting directly on the Tangle by including appropriate references in their blocks.
+
+Block references are crucial in the consensus protocol as they guide the [tip selection algorithm](tip-selection-algorithm.md#tip-selection-algorithm).
+
+#### Reference Types
+
+###### Strong
+
+Nodes randomly select strong parents from their tip pool and attach their newly issued blocks to these selected tips. The number of strong parents sets a tradeoff between [confirmation time](consensus-flags.md#confirmation-of-blocks-and-non-conflicting-transactions) and the block size. More strong parents lead to shorter confirmation times and larger block sizes. When [computing the branch](relevant-algorithms.md#algorithm-to-compute-a-blocks-branch) of a new block, the branches of strong parents are directly inherited by the branch of the new block.
+
+###### Shallow Like
+
+Shallow like references are essential for rectifying the preliminary [block's branch](relevant-algorithms.md#algorithm-to-compute-a-blocks-branch) constructed from the strong parents. They align the block's branch with the issuer's [preferred reality](relevant-algorithms.md#algorithm-to-compute-the-preferred-reality).
+
+###### Weak
+
+Weak references serve a different purpose. They come into play when the [branches of certain strong parents](relevant-algorithms.md#algorithm-to-compute-a-blocks-branch) cannot be aligned with a limited number of shallow like references. In such cases, strong parents are moved to the weak tip pool, and a bounded number are selected as weak parents. Weak references attempt to prevent orphaning blocks that may have voted for a large set of conflicts.
+
+### Total and Online Supermajority
+
+To formally define consensus flags, the notion of total and online supermajorities of blocks is introduced. A supermajority of a subset of blocks means that the issuers of these blocks have more than $2/3$ of the total voting weight.
+
+#### Total supermajority
+
+A set of blocks $A$ is called a total supermajority of blocks if the relative weight of the issuers of blocks from $A$ is more than $2/3$ of the [total weight](#epoch-committee). In other words, let $IssuerIDs(A)=\{b.IssuerID: \ b\in A\}$, then
+
+$$
+\sum_{i\in IssuerIDs(A)}W_i > \frac{2}{3} W_{total}.
+$$
+
+#### Online supermajority
+
+A set of blocks $A$ is called an online supermajority of blocks if the relative weight of issuers of blocks from $A$ is more than $2/3$ of the [online weight](#epoch-committee). In other words,
+
+$$
+\sum_{i\in IssuerIDs(A)}W_i > \frac{2}{3} W_{online}.
+$$
+
+### Slot Commitment Chain
+
+Each block in IOTA 2.0 contains a commitment to the content of a certain slot in the past.
+A slot commitment is a hash value that encapsulates all the crucial information about a slot (such as [accepted](consensus-flags.md#acceptance-flag) blocks and transactions, the index of the slot, etc.). A slot commitment is calculated by combining the following pieces of information through hashing:
+
+#### 1. Protocol version
+
+The field denoting the protocol version that will be increased after each protocol upgrade.
+
+#### 2. Slot index
+
+The index of a slot to which a slot content is committed. For a time instant `timeInstant`, the respected slot index is computed as `Floor((timeInstant - genesisUnixTime)/slotDurationSeconds) + 1`, where `genesisUnixTime` is the starting point of the timeline or the timestamp of the genesis block.
+
+#### 3. Previous slot commitment
+
+The slot commitment of the slot with the preceding slot index.
+
+#### 4. Commitment of slot content
+
+The hash root of a Merkle tree that contains all commitment elements at the end of this slot. For simplicity, one can think about this value as the hash of all accepted blocks and transactions issued within the slot.
+
+#### 5. Cumulative weight
+
+The total weight of validators that reference a specific commitment in the past and the cumulative weight of the previous slot commitment.
+
+#### 6. Reference mana cost
+
+The reference Mana cost (RMC) is calculated from the contents of the slot and the previous slot’s RMC.
+
+:::note
+
+A commitment is linked to the commitment of the previous slot. All commitments form a slot commitment tree, where the path between the tree root (the genesis) and any node in the tree determines a slot commitment chain. Nodes that adopt the same slot commitment consequently adopt the same slot commitment chain. So, they agree on the common prefix of the ledger and the Tangle up to the last slot of the chain.
+
+:::
+
+Each node maintains its slot commitment chain based on its understanding of the Tangle. The node tracks the [online committee](#epoch-committee), that adopted the same slot commitment chain as the node. Upon receiving validation blocks, the node identifies which blocks and transactions get [accepted](consensus-flags.md#acceptance-flag) by the online committee and flags them as accepted in turn. The accepted objects will then provide a basis for generating the commitment of slot content in the structure of a slot commitment.
+
+The commitment for a slot that ends at the moment `slotEnd` is produced by the node at some moment in the period `[slotEnd+minCommittableSlotAge*slotDurationSeconds, slotEnd+maxCommittableSlotAge*slotDurationSeconds]`, where `minCommittableSlotAge` and `maxCommittableSlotAge` are specially designed protocol constants measured in slot units.
+
+The actual moment depends on the [accepted Tangle time](tip-selection-algorithm.md#eligible-tips) of the node. More specifically, if one of the conditions holds:
+
+- the [accepted Tangle time](tip-selection-algorithm.md#eligible-tips) is larger than `slotEnd+minCommittableSlotAge*slotDurationSeconds`;
+- the current wall clock is at least `slotEnd+maxCommittableSlotAge*slotDurationSeconds`;
+
+then the node generates the commitment of the required slot.
+
+### Reality-based UTXO ledger
+
+As [Chrysalis](../../../chrysalis/introduction.md) and [Stardust](../../../stardust/introduction.md), IOTA 2.0 uses the Unspent Transaction Output (UTXO) model for transactions. Its parallel processing capability allows independent transactions to be added to the ledger in any order, thus enhancing its scalability potential.
+
+However, the append-only nature of the UTXO ledger can compromise this benefit when conflicting transactions arise. To address this issue, IOTA 2.0 uses an enhanced UTXO ledger model, called the [reality-based UTXO ledger](preliminaries.md#reality-based-utxo-ledger), that optimistically updates the ledger and maintains a record of the dependencies of possible conflicts.
+
+A UTXO transaction should have a list of unique outputs called UTXOs. In addition, each transaction has a list of inputs, which are UTXOs of previous transactions. A transaction is said to spend its inputs.
+
+#### Ledger DAG
+
+The ledger DAG is a DAG whose vertex set consists of all transactions. There is a directed edge between two transactions $tx$ and $ty$ if $tx$ spends the output of $ty$. The ledger DAG's root is the genesis with no outgoing edges.
+
+#### Causal history of a transaction
+
+The causal history of a given transaction $tx$ consists of all transactions that can be reached from the transaction $tx$ by traversing the ledger DAG along the directed edges.
+
+#### Conflict
+
+A transaction $tx$ is a conflict if there is another transaction $ty$ such that $tx$ and $ty$ attempt to spend at least one identical input.
+
+#### Conflicting transactions
+
+Two transactions $tx$ and $ty$ are called conflicting if the causal history of $tx$ and the causal history of $ty$ contain some transaction $tx'$ and $ty'$ which spend at least one identical input.
+
+#### Non-conflicting transaction
+
+A transaction $tx$ is _non-conflicting_ if there is no transaction $ty$ such that $tx$ and $ty$ are conflicting.
+
+#### Rejected transaction
+
+A transaction $tx$ is rejected if there is a transaction $ty$, which is conflicting with $tx$ and has been [accepted](consensus-flags.md#acceptance-of-conflicting-transactions).
+
+In other words, once a transaction gets [accepted](consensus-flags.md#acceptance-flag), all transactions conflicting with it get rejected. Rejected transactions are removed from the reality-based ledger.
+
+### Branches
+
+To understand the voting mechanism on the Tangle, it is essential to introduce the fundamental definition of branches.
+
+#### Branch
+
+A branch is a subset of conflicts $B$ if these two properties hold:
+
+1. Set $B$ does not contain two conflicting transactions.
+2. For any conflict $tx\in B$, all conflicts in the causal history of $tx$ are contained in $B$.
+
+One prominent example of branches is defined using the causal history of transactions.
+
+#### Branch of a transaction
+
+The set of all conflicts in the causal history of a transaction $tx$ is called the branch of $tx$ and denoted as $Branch(tx)$.
+
+
+#### Branch of a block
+
+For a block $b$, there is the branch of $b$, which is encoded through the references. This branch is denoted as $Branch(b)$ and it can be computed using an [algorithm](relevant-algorithms.md#algorithm-to-compute-a-blocks-branch).
+
+#### Vote
+
+A block votes for a conflicting transaction $tx$ if the branch of the block contains $tx$. In such a case, the issuer of the block is also said to vote for $tx$.
+
+The issuer of a block votes for (supports) all conflicts in the branch of that block. Nodes use this simple idea to agree on which conflicting transactions should be accepted and included in the ledger and which should be rejected.
+
+To determine the conflicts supported by a node, you need to understand the concept of the preferred reality.
+
+#### Reality
+
+A maximal branch is called a reality. In other words, for a reality, there is no larger branch containing this reality.
+
+There is an exponential number of realities in the number of conflicts. However, every node at any moment can find its unique preferred reality by following the [algorithm](relevant-algorithms.md#algorithm-to-compute-the-preferred-reality). This algorithm is practical as it has quadratic complexity in the number of conflicts.
+
+The preferred reality represents the complete set of conflicts supported by a node. In principle, when choosing between two conflicting transactions, a node supports the one that has received more votes from the committee, i.e., validation blocks with more voting weight voted for that transaction.
+
+In the actual implementation, the preferred reality is not fully computed at any moment. Instead, the concept of a preferred reality is implicitly used in the [tip selection algorithm](tip-selection-algorithm.md).
+
+When issuing a new block, the node finds the preferred branch (an appropriate subset of the preferred reality), which conflicts can be referenced using [shallow like references](preliminaries.md#shallow-like), consequently aligning the branch of the new block with the preferred reality.
+
+:::info Learn More
+
+You can find more details about the reality-based UTXO ledger in the [Reality-based UTXO Ledger paper](https://arxiv.org/pdf/2205.01345).
+
+:::
diff --git a/docs/learn/protocols/iota2.0/core-concepts/consensus/relevant-algorithms.md b/docs/learn/protocols/iota2.0/core-concepts/consensus/relevant-algorithms.md
new file mode 100644
index 00000000000..0d835a8e504
--- /dev/null
+++ b/docs/learn/protocols/iota2.0/core-concepts/consensus/relevant-algorithms.md
@@ -0,0 +1,57 @@
+# Relevant Algorithms
+
+## Algorithm to Compute a Block’s Branch
+
+This section provides an algorithm to compute the [branch](preliminaries.md#reality-based-utxo-ledger) for a given block $b$.
+
+In the following, the blocks from $b.References$ are considered. There are [three types of references](preliminaries.md#block-references) in IOTA 2.0, which are called strong, weak, and shallow like.
+
+Let $s_1,\ldots,s_{n_s}$ denote the strong parents of block $b$. Let $w_1,\ldots,w_{n_w}$ denote the weak parents of $b$, where each $w_i$ contains transaction $w_i.Tx$. Let $l_1,\ldots,l_{n_l}$ denote the shallow like parents of $b$, where $l_i$ contains transaction $l_i.Tx$.
+
+You can define the conflicts that come from the branches of the strong parents as:
+
+$$
+addStrongBranch \gets \bigcup\limits_{i=1}^{n_s}Branch(s_i).
+$$
+
+Similarly, you can define the sets of conflicts that come from the weak and shallow like parents. Note that in these operations, the [branches of the corresponding payloads (transactions)](preliminaries.md#reality-based-utxo-ledger) are used:
+
+$$
+addWeakBranch \gets \bigcup\limits_{i=1}^{n_w}Branch(w_i.Tx), \\
+addLikeBranch \gets \bigcup\limits_{i=1}^{n_w}Branch(l_i.Tx). \\
+$$
+
+Shallow like references allow for the removal of conflicts from the aggregation of branches that do not belong to the preferred reality:
+
+$$
+removeConflicts \gets ConflictWith(addLikeBranch),
+$$
+
+The function $ConflictWith(S)$ returns the set of all conflicts conflicting with at least one element from $S$. Finally, you can define the branch of the block $b$ in two steps. First:
+
+$$
+Branch(b)\gets \left(addStrongBranch \cup addWeakBranch \cup addLikeBranch\right) \setminus removeConflicts.
+$$
+
+Second, add the branch of the payload of $b$ to the result, i.e. $Branch(b)\gets Branch(b)\cup Branch(b.Tx)$.
+
+:::note
+
+The set $Branch(b)$ is subjective for a node that computes the branch. This is because some new conflicts might appear, or some existing conflicts might be resolved in the perception of this node.
+
+:::
+
+## Algorithm to Compute the Preferred Reality
+
+There could be many realities in the [reality-based UTXO ledger](preliminaries.md#reality-based-utxo-ledger). However, a unique preferred reality for a node identifies all conflicting transactions supported by the node. To find the preferred reality, the node can proceed with the following steps:
+
+1. Calculate the approval weight for each [unaccepted](consensus-flags.md#acceptance-flag) [conflict](preliminaries.md#reality-based-utxo-ledger). The approval weight is determined as the combined weight of the online committee members who have voted in favor of this particular conflict and have not altered their stance in favor of a different conflicting transaction in any subsequent block.
+2. Set $C$ to be the set of all conflicts and $R$ to be the empty set (which will eventually be constructed as a reality).
+3. Find the conflict with the largest approval weight. In the case of many conflicts of equal weight, find the conflict with the largest hash of the conflict id. Include this transaction to $R$.
+4. Remove all transactions that are conflicting with the selected transaction from $C$.
+5. If $C$ is non-empty, proceed with step 3. Otherwise, output $R$.
+
+## Additional Literature
+
+- Sebastian Müller, Andreas Penzkofer, Nikita Polyanskii, Jonas Theis, William Sanders, and Hans Moog. ["Tangle 2.0 Leaderless Nakamoto Consensus on the Heaviest DAG."](https://ieeexplore.ieee.org/iel7/6287639/6514899/09907014.pdf) IEEE Access 10 (2022): 105807-105842.
+- Sebastian Müller, Andreas Penzkofer, Nikita Polyanskii, Jonas Theis, William Sanders, and Hans Moog. ["Reality-based UTXO ledger."](https://arxiv.org/pdf/2205.01345) ACM DLT 2.3 (2023): 1-33.
diff --git a/docs/learn/protocols/iota2.0/core-concepts/consensus/tip-selection-algorithm.md b/docs/learn/protocols/iota2.0/core-concepts/consensus/tip-selection-algorithm.md
new file mode 100644
index 00000000000..b82942f5902
--- /dev/null
+++ b/docs/learn/protocols/iota2.0/core-concepts/consensus/tip-selection-algorithm.md
@@ -0,0 +1,41 @@
+# Tip Selection Algorithm
+
+Selecting blocks to be referenced by newly issued blocks is a critical component of the consensus protocol.
+
+Suppose a node adopts the [slot commitment chain](introduction.md#slot-commitment-chains) $ch=(C_1,\ldots,C_s)$ and maintains the tip pool $\mathcal{T}_{ch}$, which consists of [eligible tips](#eligible-tips). It is impossible to reference all existing blocks in the tip pool as it would lead to a large block size. Instead, the number of references for each reference type is limited by `blockMaxParent` for normal blocks and by `blockTypeValidatorMaxParent` for validation blocks.
+
+## Tip Selection Rules
+
+When a node issues a new block (e.g., committee members must issue their blocks every `frequencyValidationBlock` seconds), it follows these rules to select the list of references $L$ to be included in the new block:
+
+### 1. Strong Parents
+
+The node selects uniformly at random at most `blockMaxParent` (or `blockTypeValidatorMaxParent` for validation blocks) unique tips from the tip pool $\mathcal{T}_{ch}$ as strong parents.
+
+### 2. Shallow-like References
+
+After adding a new strong parent to the list of references $L$, the node attempts to select shallow-like references to align the current [branch of the block](relevant-algorithms.md#algorithm-to-compute-a-blocks-branch) with the [preferred reality](relevant-algorithms.md#algorithm-to-compute-the-preferred-reality).
+
+If `blockMaxParent` (or `blockTypeValidatorMaxParent`) shallow-like references are not sufficient to align the branch, the strong parent is removed from the list of references $L$ and moved to the weak tip pool $\mathcal{W}$, which is initialized as an empty set before running the tip selection algorithm.
+
+### 3. Weak References
+
+The node selects uniformly at random (at most) `blockMaxParent` (or `blockTypeValidatorMaxParent`) unique tips from the weak tip pool $\mathcal{W}$.
+
+Before adding a weak tip to the list of references, the node checks if the transaction included in the weak tip conflicts with the [preferred reality](relevant-algorithms.md#algorithm-to-compute-the-preferred-reality). If the transaction is not conflicting, the weak tip is added to the list of references.
+
+## Eligible Tips
+
+To guarantee consistency for generated slot commitments, nodes need to only keep tips likely to be approved and accepted by the committee in the tip pool. For instance, a tip is bad if it approves an unaccepted block that is issued in an already committed slot.
+
+### Accepted Tangle Time (ATT)
+
+A node's accepted Tangle time (ATT) is the largest timestamp across all accepted blocks (in the local perception of the node).
+
+### Eligible Tips
+
+A block $b$ is called an eligible tip for a node that adopts slot commitment chain $ch=(C_1,\ldots,C_s)$ if the following conditions hold:
+
+- the block $b$ is not yet referenced.
+- the slot commitment included to $b$ is consistent with $ch$, i.e., it is equal to $C_i$ for some $i$.
+- Any [unaccepted](consensus-flags.md#acceptance-flag) block $u$ in the [past cone](preliminaries.md#past-cone-of-a-block) of $b$ is scheduled to gossip and the difference between ATT and the timestamp $u.IssuingTime$ is at most `livenessThreshold`. The value `livenessThreshold` is set to `3*slotDurationSeconds`.
diff --git a/docs/learn/protocols/iota2.0/core-concepts/data-flow.md b/docs/learn/protocols/iota2.0/core-concepts/data-flow.md
index d187c97e3bb..2b0060a8994 100644
--- a/docs/learn/protocols/iota2.0/core-concepts/data-flow.md
+++ b/docs/learn/protocols/iota2.0/core-concepts/data-flow.md
@@ -4,7 +4,7 @@ This article provides a detailed description of the interaction between the IOTA
- A [P2P overlay network](#1-network-layer).
- An immutable [data structure](data-structures.md).
-- A consensus mechanism.
+- A [consensus mechanism](consensus/introduction.md).
In the IOTA 2.0 protocol, these three elements are abstracted into layers, where upper layers build on the functionality of the layers below. The definition of these layers allows for different functionalities to be conveniently separated into modules and addressed individually. This article will describe all the modules and their interactions.
@@ -27,7 +27,7 @@ Since nodes have finite capabilities, the network can process a limited number o
The application layer lives on top of the communication layer. The application layer is mainly related to objects called payloads (e.g., transactions are a type of payload). Anybody can develop applications on this layer, and nodes can choose which applications to run. Of course, these applications can also be dependent on each other.
-Nodes must also run several core applications, such as the engine, which maintains the [ledger state](data-structures.md) and a quantity called [Mana](mana.md). Mana is a scarce resource that serves as a Sybil protection mechanism and spam protection. All nodes must also run the Approval Weight and Finality Gadget application, which provides a protocol that produces consensus between nodes on whether blocks are to be included in the Tangle (instead of being orphaned) and on whether transactions inside included blocks should mutate the ledger (instead of being deemed non-mutating). Lastly, the same gadget enables nodes to reorganize their perception of the Tangle when necessary, using the fork-choice rule.
+Nodes must also run several core applications, such as the engine, which maintains the [ledger state](data-structures.md) and a quantity called [Mana](mana.md). Mana is a scarce resource that serves as a Sybil protection mechanism and spam protection. All nodes must also run the [Approval Weight and Finality Gadget](consensus/introduction.md) application, which provides a protocol that produces consensus between nodes on whether blocks are to be included in the Tangle (instead of being orphaned) and on whether transactions inside included blocks should mutate the ledger (instead of being deemed non-mutating). Lastly, the same gadget enables nodes to reorganize their perception of the Tangle when necessary, using the fork-choice rule.
## 4. Data Flow
@@ -52,7 +52,7 @@ Finally, note that this Data Flow concerns _nodes_ and not _clients_. Clients ge
### 4.1 Block Factory
-The `IssuePayload` function creates a valid payload, provided to the `CreateBlock` method, along with a set of parents chosen with the Tip Selection Algorithm. Then, the block is signed. Notice that block generation should follow the rates imposed by the rate setter, as defined in rate control, and that the block's type of references should be consistent with the preferred reality of the issuer.
+The `IssuePayload` function creates a valid payload, provided to the `CreateBlock` method, along with a set of parents chosen with the Tip Selection Algorithm. Then, the block is signed. Notice that block generation should follow the rates imposed by the rate setter, as defined in rate control, and that the block's type of references should be consistent with the preferred reality of the issuer(see the [consensus article](consensus/introduction.md).
All blocks have a commitment field, which is the hash of a series of information from older slots (see [Data Structures](data-structures.md)), e.g., the Merkle root of the Merkle Tree containing the blocks included in the older slots, ledger state at the end of the slots, or Block Issuance Credits.
@@ -60,7 +60,7 @@ There are certain rules for creating the commitment:
A block must not commit to excessively old slots, for example, the "genesis" slot.
A block must not commit to excessively recent slots. For example, the slot to which the block belongs, since the information the block commits to might still change.
-By comparing these commitments, it becomes straightforward to identify the existence of divergences between the nodes' perceptions of the Tangle. Additionally, these commitments in the blocks enable the creation of Slot Commitment Chains (see [Data Structures](data-structures.md)).
+By comparing these commitments, it becomes straightforward to identify the existence of divergences between the nodes' perceptions of the Tangle. Additionally, these commitments in the blocks enable the creation of Slot Commitment Chains (see [Data Structures](data-structures.md) and the [Finality Gadget](consensus/introduction.md)).
### 4.2 Parser
@@ -105,7 +105,7 @@ This process checks if the block signature is valid. If the block does not pass
Only the blocks that pass the Parser are stored in memory with some metadata as boolean flags set in future points of the data flow. This process takes place in the _Block DAG_ component, where blocks are causally ordered and their dependencies are defined.
-_Solidification_ also takes place in the Block DAG. Solidification is the process of requesting missing blocks. In this step, the node checks if all the past cone of the block is known. If the node realizes that a block in the past cone is missing, it will send a request to its neighbors asking for that missing block. This process is recursively repeated until all of a block's past cone up to the genesis (or snapshot) becomes known to the node.
+_Solidification_ also takes place in the Block DAG. Solidification is the process of requesting missing blocks. In this step, the node checks if all the past cone (see [consensus](consensus/introduction.md)) of the block is known. If the node realizes that a block in the past cone is missing, it will send a request to its neighbors asking for that missing block. This process is recursively repeated until all of a block's past cone up to the genesis (or snapshot) becomes known to the node.
This way, the protocol enables any node to retrieve the entire block history (or at least until the last available snapshot) by processing the newly received blocks, even for nodes that have just joined the network.
@@ -126,7 +126,7 @@ This condition is necessary to guarantee the monotonicity of the Tangle, i.e., t
After solidification, the block moves on to the booker, where transactions are causally ordered, conflicts are identified, and the ledger state is updated.
-Booking a transaction does not mean confirming a transaction. Our protocol optimistically books transactions even when they conflict, tracks these conflicts and their dependencies accordingly, and creates a collection of different realities that are collapsed into a single confirmed reality at the end of the consensus process.
+Booking a transaction does not mean confirming a transaction. Our protocol optimistically books transactions even when they conflict, tracks these conflicts and their dependencies accordingly, and creates a collection of different realities (see [Reality-based UTXO ledger](consensus/introduction.md)) that are collapsed into a single confirmed reality at the end of the consensus process.
The booking step is different between blocks that contain a transaction payload and blocks that do not contain it. In the case of a block without a transaction payload, booking into the Tangle occurs after the block has waited in a buffer until all its parents are booked. In the booking process, all conflicts are inherited from the parents, and a `BlockBooked` event is issued. This step allows the opinion of the block to be constructed. If any of the parents are marked as `invalid`, the block is also marked as `invalid` and a `BlockInvalid` event is issued.
@@ -171,17 +171,17 @@ Blocks that are scheduled by the node can be gossiped and added to the tip pool.
### 4.6 Tip Manager
-A scheduled block is finally added to one of two tip sets, "strong" and "weak" . Additionally, all strong parents of the scheduled block that are still part of the strong tip set are removed from it, whereas any parent in the weak tip is removed regardless of the reference type.
+A scheduled block is finally added to one of two tip sets, "strong" and "weak" (for more details on the Tip Selection and Tip Pools, see [Tip selection](consensus/introduction.md). Additionally, all strong parents of the scheduled block that are still part of the strong tip set are removed from it, whereas any parent in the weak tip is removed regardless of the reference type.
The tip selection mechanism performs a uniform random tip selection from a subset of the tip pool to guarantee good properties of the Tangle. Specifically, it will select tips uniformly at random only from tips that are not excessively old and pass the fishing condition. For that reason, when a block is to be issued and its parents are selected, the tip manager will check if the selected parents respect these conditions and discard them if needed. In that case, the discarded parent is also removed from the tip set and a new parent is selected until the required number of parents is met.
-After selecting parents, the algorithm chooses the type of reference (strong, weak, etc.) it uses for each parent, depending on the opinion the node has about the past cones of these parents.
+After selecting parents, the algorithm chooses the type of reference (strong, weak, etc.) it uses for each parent, depending on the opinion the node has about the past cones of these parents (see [consensus article](consensus/introduction.md)).
-Finally, if the block being issued is a [validation block](mana.md#validation-blocks), the tip selection may differ from the tip selection of regular blocks; specifically, committee members will always try to reference all known blocks from other committee members (in addition to the random tips).
+Finally, if the block being issued is a [validation block](mana.md#validation-blocks), the tip selection may differ from the tip selection of regular blocks; specifically, committee members will always try to reference all known blocks from other committee members (in addition to the random tips). For more details on the validation block tip selection, see the [consensus article](consensus/introduction.md).
### 4.7 Consensus and Notarization
-Booked blocks continue to the consensus and notarization component. In this component, the newly booked blocks will propagate the `Witness Weight` and `Approval Weight` from validation blocks to the blocks in their past cone and transactions they approve.
+Booked blocks continue to the consensus and notarization component. In this component, the newly booked blocks will propagate the `Witness Weight` and `Approval Weight` from validation blocks to the blocks in their past cone and transactions they approve (see [consensus article](consensus/introduction.md)).
This propagation is independent: blocks always propagate Witness Weight but not necessarily Approval Weight, which depends on the type of reference that the block uses.
When blocks and transactions reach a certain Witness and Approval Weight threshold, they are marked as `accepted` and `confirmed` (among other flags). Finally, these flags trigger the Notarization process, creating slot commitments.
diff --git a/docs/learn/protocols/iota2.0/core-concepts/data-structures.md b/docs/learn/protocols/iota2.0/core-concepts/data-structures.md
index 6b733d90756..448201c723d 100644
--- a/docs/learn/protocols/iota2.0/core-concepts/data-structures.md
+++ b/docs/learn/protocols/iota2.0/core-concepts/data-structures.md
@@ -14,7 +14,7 @@ The Tangle is a data structure replicated across a decentralized network of comp
**Image 1:** The Tangle.
One of the key functionalities of the Tangle is to ensure the immutability of the data stored in it. By leveraging its distributed nature, the Tangle provides a resilient and tamper-proof environment for data integrity. This means that once information is added to the Tangle, it becomes nearly impossible to alter or manipulate, enhancing the system's trustworthiness.
-Given that the Tangle is a replicated or distributed data structure, nodes have to reach a consensus on the content of the Tangle.
+Given that the Tangle is a replicated or distributed data structure, nodes have to reach a [consensus](consensus/introduction.md) on the content of the Tangle.
## The Tangle Versus Blockchains
diff --git a/docs/learn/sidebars.ts b/docs/learn/sidebars.ts
index f23a6f9de97..18fae6efcb5 100644
--- a/docs/learn/sidebars.ts
+++ b/docs/learn/sidebars.ts
@@ -66,6 +66,18 @@ module.exports = {
'protocols/iota2.0/core-concepts/data-flow',
'protocols/iota2.0/core-concepts/data-structures',
'protocols/iota2.0/core-concepts/mana',
+ {
+ type: 'category',
+ label: 'Consensus',
+ items: [
+ 'protocols/iota2.0/core-concepts/consensus/introduction',
+ 'protocols/iota2.0/core-concepts/consensus/preliminaries',
+ 'protocols/iota2.0/core-concepts/consensus/tip-selection-algorithm',
+ 'protocols/iota2.0/core-concepts/consensus/consensus-flags',
+ 'protocols/iota2.0/core-concepts/consensus/chain-switching-rule',
+ 'protocols/iota2.0/core-concepts/consensus/relevant-algorithms',
+ ],
+ },
],
},
],
diff --git a/static/img/learn/protocols/iota2.0/core-concepts/consensus/acceptance-of-a-block.png b/static/img/learn/protocols/iota2.0/core-concepts/consensus/acceptance-of-a-block.png
new file mode 100644
index 00000000000..7f8bb7ccf11
Binary files /dev/null and b/static/img/learn/protocols/iota2.0/core-concepts/consensus/acceptance-of-a-block.png differ
diff --git a/static/img/learn/protocols/iota2.0/core-concepts/consensus/acceptance-of-conflicting-transactions.png b/static/img/learn/protocols/iota2.0/core-concepts/consensus/acceptance-of-conflicting-transactions.png
new file mode 100644
index 00000000000..f1d666a738c
Binary files /dev/null and b/static/img/learn/protocols/iota2.0/core-concepts/consensus/acceptance-of-conflicting-transactions.png differ
diff --git a/static/img/learn/protocols/iota2.0/core-concepts/consensus/cones-of-a-block.png b/static/img/learn/protocols/iota2.0/core-concepts/consensus/cones-of-a-block.png
new file mode 100644
index 00000000000..bd80c5a8282
Binary files /dev/null and b/static/img/learn/protocols/iota2.0/core-concepts/consensus/cones-of-a-block.png differ
diff --git a/static/img/learn/protocols/iota2.0/core-concepts/consensus/confirmation-of-a-block.png b/static/img/learn/protocols/iota2.0/core-concepts/consensus/confirmation-of-a-block.png
new file mode 100644
index 00000000000..2e8eb449202
Binary files /dev/null and b/static/img/learn/protocols/iota2.0/core-concepts/consensus/confirmation-of-a-block.png differ
diff --git a/static/img/learn/protocols/iota2.0/core-concepts/consensus/confirmation-of-conflicting-transactions.png b/static/img/learn/protocols/iota2.0/core-concepts/consensus/confirmation-of-conflicting-transactions.png
new file mode 100644
index 00000000000..a14f193628b
Binary files /dev/null and b/static/img/learn/protocols/iota2.0/core-concepts/consensus/confirmation-of-conflicting-transactions.png differ
diff --git a/static/img/learn/protocols/iota2.0/core-concepts/consensus/finalitzation-of-a-slot-commitment.png b/static/img/learn/protocols/iota2.0/core-concepts/consensus/finalitzation-of-a-slot-commitment.png
new file mode 100644
index 00000000000..9986da15d35
Binary files /dev/null and b/static/img/learn/protocols/iota2.0/core-concepts/consensus/finalitzation-of-a-slot-commitment.png differ
diff --git a/static/img/learn/protocols/iota2.0/core-concepts/consensus/flag-hierarchy.png b/static/img/learn/protocols/iota2.0/core-concepts/consensus/flag-hierarchy.png
new file mode 100644
index 00000000000..99d4c892fc3
Binary files /dev/null and b/static/img/learn/protocols/iota2.0/core-concepts/consensus/flag-hierarchy.png differ
diff --git a/static/img/learn/protocols/iota2.0/core-concepts/consensus/pre-acceptance-of-a-block.png b/static/img/learn/protocols/iota2.0/core-concepts/consensus/pre-acceptance-of-a-block.png
new file mode 100644
index 00000000000..ebd701e41c2
Binary files /dev/null and b/static/img/learn/protocols/iota2.0/core-concepts/consensus/pre-acceptance-of-a-block.png differ
diff --git a/static/img/learn/protocols/iota2.0/core-concepts/consensus/pre-confirmation-of-a-block.png b/static/img/learn/protocols/iota2.0/core-concepts/consensus/pre-confirmation-of-a-block.png
new file mode 100644
index 00000000000..cfb6ab629e0
Binary files /dev/null and b/static/img/learn/protocols/iota2.0/core-concepts/consensus/pre-confirmation-of-a-block.png differ
diff --git a/static/img/learn/protocols/iota2.0/core-concepts/consensus/weight-of-a-slot-commitment.png b/static/img/learn/protocols/iota2.0/core-concepts/consensus/weight-of-a-slot-commitment.png
new file mode 100644
index 00000000000..b4985f386aa
Binary files /dev/null and b/static/img/learn/protocols/iota2.0/core-concepts/consensus/weight-of-a-slot-commitment.png differ