update docs with andromeda

docs/learn/consensus.md

@@ -3,18 +3,116 @@ id: consensus
 title: Consensus
 ---
 
-MultiversX's approach for consensus is called Secure Proof of Stake (SPoS). It innovates in the manner in which validator nodes are selected for consensus out of a shard and also in the steps taken by the validators to complete the consensus process as efficiently as possible. Let's take a look.
+# Consensus (Secure Proof‑of‑Stake – SPoS)
 
-At the beginning of each round, SPoS selects validators for consensus using a **randomness source** that can be neither predicted, nor influenced. It is surprisingly simple, requiring only to be calculated from the previous block and to be signed by the consensus leader of the current round (also known as the _block proposer_). The resulting signature will be the randomness source for the next round, and due to its reliance on the immediately preceding block, it cannot be known more than a round in advance.
+## 1.  How Consensus Works in MultiversX (post-Andromeda)
 
-In each round, a new consensus group is selected to propose a block. But only one validator in the group will be the **block proposer**. This is the validator in the consensus group which has the hash of the public key and randomness source is the smallest, numerically. The block proposer will produce the block for the round, and the rest of the consensus group will validate and sign it.
+Consensus is the protocol that keeps every shard and the Metachain in lock‑step, ensuring all honest participants share **one canonical history**. MultiversX uses a bespoke scheme called **Secure Proof‑of‑Stake (SPoS)**, a blend of stake‑weighted validator selection, VRF‑style randomness, and a high‑speed BLS multisignature algorithm that guarantees _single‑block finality_.
 
-The time necessary for random selection of the consensus group is exceptionally short (around 100 ms, often less). This efficiency is a consequence of the fact that consensus selection is deterministic once the randomness source is known, thus there is no communication requirement. This allows total round times on the order of mere seconds.
+Below is a step‑by‑step walk‑through of *one* six‑second block cycle (round `r`). The same engine runs independently in **every execution shard** and in the **Metachain**.
 
-There is a security advantage to having rounds this short: SPoS is built on the premise that a malevolent actor cannot adapt faster than the timeframe allowed by a round in order to influence the block that will be proposed.
+### 1.1  Validator set and epochs
 
-Like other Proof of Stake methods, SPoS selects validator nodes for consensus based on the amount of EGLD tokens staked by their operators. Additionally, each validator has an individual **rating score** that is taken into account - stake alone may only influence, but not completely determine the selection for consensus. Rating expresses the past behavior of the specific validator and is taken into account during consensus selection: validators with a higher rating are more likely to be selected. The rating of a validator is recalculated at the end of each epoch, with a few specific exceptions when rating is adjusted immediately. This way, SPoS promotes meritocracy among validators, encouraging their operators to keep them running smoothly.
+* **Validators.** Nodes that stake a minimum of 2500EGLD and run the MultiversX node client software. Each validator holds a long‑lived BLS key that is rotated only when they unbond/unstake, anyway the keys are shuffled among shards each epoch.
+* **Epoch.** A period of 24 hours (≈ 14 400 blocks on a 6 s cadence-round). At the start of every epoch the 400 validators in each shard are reshuffled using a deterministic permutation seeded with verifiable randomness. The composition of a shard remains fixed for the whole epoch.
 
-A modified BLS multisignature scheme with 2 communication rounds is used by the consensus group for signing the block produced by the block proposer. Refer to the animation below for a step-by-step description of this process:
+### 1.2  Round randomness
 
-![img](https://gblobscdn.gitbook.com/assets%2F-LhHlNldCYgbyqXEGXUS%2F-LiMxIign95mclxNqYGx%2F-LiMxWSVhwOjpz3wB71V%2Fspos.gif?alt=media&token=734c6439-d245-4e83-9a81-a72e6e27ce32)
+Randomness must be unpredictable yet verifiable. For round `r` the seed is:
+
+```
+rand_r = BLS_sign(prev_block_hash, proposer_{r-1})
+```
+
+Because the identity of the previous proposer is only revealed at the end of round `r – 1`, no one can bias or predict `rand_r` ahead of time.
+
+### 1.3  Proposer election
+
+Each validator hashes together its public key and `rand_r`:
+
+```
+score_i = Hash(PK_i ‖ rand_r)
+```
+
+The lowest score wins and becomes the **proposer** for round `r`. Ties are astronomically unlikely.
+
+### 1.4  Two‑phase BLS consensus
+
+Once chosen, the proposer assembles a block and broadcasts it to the other 399 validators. Consensus then runs in **two BLS rounds**—`prepare` and `commit`—similar to PBFT but with aggregated signatures:
+
+1. **Prepare.** Validators check the block (state root, signatures, gas limits). If valid they sign its hash and return a 96‑byte BLS share.
+2. **Commit.** The proposer (or any validator) aggregates ≥ ⅔ of the shares into a single 96‑byte signature and broadcasts a **commit message**.
+
+Because **all 400 validators** participate (post‑Andromeda), a share threshold of 268 guarantees Byzantine safety.
+
+### 1.5  Equivalent Consensus Proof (ECP)
+
+The final artefact attached to the block header is an **ECP**:
+
+```
+ECP = (agg_signature, bitmap_400)
+```
+
+* `agg_signature` – aggregated BLS signature from ≥ 268 validators.
+* `bitmap_400` – 400‑bit field indicating which keys took part.
+
+Any validator can perform the aggregation; there is no single point of failure. Because the validator set and aggregation order are deterministic inside the epoch, *exactly one* valid ECP can exist for a given block—making equivocation impossible.
+
+### 1.6  Notarisation and finality
+
+* **Execution shards**: A block is **final the moment its ECP is broadcast**. No confirmation block is needed.
+* **Metachain**: Collects hashes of all shard blocks plus their ECPs, notarises them in the metablock of the next round, and itself reaches finality via the same BLS protocol.
+
+**Latency:** ~6 s for intra‑shard txs, ~18 s for cross‑shard (three‑block path).
+
+## 2.  Consensus group size: 63 → 400
+
+| Era | Execution‑shard consensus group | Metachain |
+|-----|---------------------------------|-----------|
+| **Pre‑Andromeda** | 63 of 400 eligible validators, shuffled _every round_ | 400 validators |
+| **Andromeda** | **All 400 validators** every round (fixed for the whole epoch) | **Unchanged** (400) |
+
+Using the full validator set removes the need for a confirmation block; a single consensus proves majority acceptance.
+
+## 3.  Consensus flow (post‑Andromeda)
+
+```mermaid
+sequenceDiagram
+    participant P as Proposer
+    participant V as Validators (399)
+    participant M as Metachain
+
+    %% Round r
+    P->>V: ① Block proposal (header + txs)
+    V->>P: ② Prepare signatures (first BLS round)
+    P->>V: ③ Commit message (aggregated sig ≥ ⅔)
+    V->>M: ④ Broadcast final block + ECP
+    M--)P: ⑤ Block notarised (instant finality)
+```
+
+**Equivalent Consensus Proof (ECP)**  
+Any validator can aggregate ≥ ⅔ BLS shares into an ECP. Because aggregation order is fixed and the validator set is constant across the epoch, the proof is uniquely determined – _equivocation is impossible_.
+
+## 4.  Confirmation blocks removed
+
+*Pre‑Andromeda*: each execution shard produced a **block** and, one round later, a **confirmation block** to seal it. The Metachain applied the same pattern to eliminate double‑spend risk.  
+*Andromeda*: one block is enough; once its ECP is broadcast the block is final, so no confirmation blocks are produced. This halves average time‑to‑finality.
+
+## 5.  Validator rating & selection
+
+* **Rating** still measures historical performance and influences shard assignment probability at the **epoch shuffle** step.  
+* Because every validator now participates in every round, rating no longer affects _per‑round_ selection but continues to impact rewards via uptime and signature participation.
+
+## 6.  Security considerations
+
+* **Byzantine tolerance**: With 400 signatures per block the network tolerates up to 133 malicious validators per shard (≈ ⅓).  
+* **Rogue‑key protection**: Implemented via KOSK and deterministic aggregation order – enabling fast verification of 400‑party BLS signatures.  
+* **Proposer failure**: Because ECP finalisation is permissionless, the network is no longer sensitive to a single proposer going offline.
+
+## TL;DR
+
+* **400/400 validators** now sign every shard block.
+* **Equivalent Consensus Proofs (ECP)** replace leader‑only finalisation – _any_ validator can finalise.
+* **Confirmation blocks are gone**: a block is final the moment ≥ ⅔ signatures are aggregated.
+* Randomness & proposer selection remain **per‑round** and still depend on the previous block hash.
+* Validator **rating** and **stake** continue to influence shard assignment and rewards – unchanged.

docs/learn/transactions.md

@@ -41,35 +41,104 @@ A ready-to-broadcast transaction is structured as follows:
 }
 ```
 
-## **Cross-Shard Transactions**
+## Cross‑Shard Transactions
 
-### **Prerequisites**
-:::note
-To help you better understand this section, we recommend you first read [Sharding](/learn/sharding) and our [introduction to MultiversX](/welcome/welcome-to-multiversx).
-:::
+### Prerequisites
 
-For an in depth example of how the cross-shard transactions are being executed and how the communication between shards and the metachain occurs, we are simplifying the entire process to just two shards and the metachain. Assuming that a user generates a transaction from his wallet, which has an address in shard 0 and wants to send EGLD to another user that has a wallet with an address in shard 1, the steps depicted in the figure below are required for processing the cross-shard transaction.
+> **Note**
+> To get the most out of this chapter we recommend reading **[Sharding](https://docs.multiversx.com/learn/sharding)** and our **[Introduction to MultiversX](https://docs.multiversx.com/learn/multiversx-ecosystem)** first.
 
-The block’s structure is represented by a block Header that contains information about the block (block nonce, round, proposer, validators timestamp etc.), and a list of miniblocks for each shard that contain the actual transactions inside. Every miniblock contains all transactions that have either the sender in the current shard and the receiver in another shard or the sender in a different shard and the destination in the current shard. In our case, for a block in shard 0, there will normally be 3 miniblocks:
+### Overview
 
-- miniblock 0: containing the intrashard transactions for shard 0
-- miniblock 1: containing cross-shard transactions with the sender in shard 0 and destination in shard 1
-- miniblock 2: containing cross-shard transactions with sender in shard 1 and destination in shard 0. These transactions were already processed in the sender shard 1 and will be finalized after the processing in the current shard.
+With the **Andromeda (v1.9.6)** upgrade, cross‑shard execution has been streamlined:
 
-There is no limitation on the number of miniblocks with the same sender and receiver in one block. Meaning multiple miniblocks with the same sender and receiver can appear in the same block.
+* **Confirmation blocks have been removed** – every shard block is final as soon as it is signed by ≥ 2⁄3 of the 400‑validator consensus group.
+* The end‑to‑end path for a cross‑shard transaction is now **three blocks (≈ 18 s on mainnet)**, down from six.
+* The underlying data structures – blocks, miniblocks and metablocks – remain unchanged, so no SDK or API schema adjustments are required.
 
-[comment]: # (mx-context-auto)
+To illustrate the new flow we reduce the network to **two execution shards** (`shard 0`, `shard 1`) and the **Metachain**. A user in `shard 0` sends EGLD to another user in `shard 1`.
 
-### **Processing a Cross-Shard Transaction**
+### Block structure recap
 
-Currently, the atomic unit of processing in cross-shard execution is a miniblock: either all the transactions of the miniblock are processed at once or none and the miniblock’s execution will be retried in the next round.
+Each shard block contains:
 
-Our cross-shard transaction strategy uses an asynchronous model. Validation and processing is done first in sender’s shard and then in receivers' shard. Transactions are first dispatched in the sender’s shard, as it can fully validate any transaction initiated from the account in this shard – mainly the current balance. Afterwards, in the receivers' shard, the nodes only need proof of execution offered by metachain, do signature verification and check for replay attack and finally update the balance for the receiver, adding the amount from the transaction.
+| Component | Description |
+|-----------|-------------|
+| **Header** | nonce, round, proposer, timestamp, gas summary, Merkle roots, etc. |
+| **Miniblocks** | ordered lists of transactions, grouped by `(sender shard → receiver shard)` pair. |
 
-Shard 0 processes both intra-shard transactions in miniblock 0 and a set of cross-shard transactions that have addresses from shard 1 as a receiver in miniblock 1. The block header and miniblocks are sent to the metachain. The metachain notarizes the block from shard 0, by creating a new metachain block (metablock) that contains the following information about each miniblock: sender shard ID, receiver shard ID, miniblock hash.
+In `shard 0` a typical block might include three miniblocks:
 
-Shard 1 fetches the hash of miniblock 1 from metablock, requests the miniblock from shard 0, parses the transaction list, requests missing transactions (if any), executes the same miniblock 1 in shard 1 and sends to the metachain resulting block. After notarization the cross transaction set can be considered finalized.
+| Miniblock | Contents |
+|-----------|----------|
+| **0** | Intra‑shard txs (`shard 0 → shard 0`). |
+| **1** | Cross‑shard txs **from `shard 0` to `shard 1`** (our example). |
+| **2** | Cross‑shard txs **from `shard 1` to `shard 0`** that were already executed in `shard 1`; they will be finalised here. |
 
-The next diagram shows the number of rounds required for a transaction to be finalized. The rounds are considered between the first inclusion in a miniblock until the last miniblock is notarised.
+> There is no limit to how many miniblocks with the same sender/receiver pair can appear in one block.
 
-![img](/technology/cross-shard-txs.png)
+### Processing a cross‑shard transaction (post‑Andromeda)
+
+The atomic unit of cross‑shard execution remains the **miniblock**: either the entire miniblock is processed, or none of its transactions are applied and it is retried in the next round.
+
+MultiversX continues to use an **asynchronous model**:
+
+1. **Validation & execution in the sender’s shard.**  
+   `shard 0` fully verifies the transaction (nonce, signatures, balance, etc.) and places it in miniblock 1. The block is produced and immediately final (single‑block finality).
+2. **Notarisation by the Metachain.**  
+   The Metachain includes the header & miniblock hashes of the new `shard 0` block in metablock `n + 1`, together with an **Equivalent Consensus Proof (ECP)** – a compressed BLS aggregate signature from ≥ 2⁄3 of the validator set.
+3. **Execution in the receiver’s shard.**  
+   Nodes in `shard 1` read the metablock, fetch miniblock 1 from `shard 0`, verify the ECP, check for replay, and apply the state changes (credit the destination address). The resulting `shard 1` block (nonce `n + 2`) is finalised with its own consensus proof and notarised in the next metablock.
+
+The sequence diagram below highlights the three‑round flow:
+
+```mermaid
+sequenceDiagram
+    participant S0 as Shard 0
+    participant MC as Metachain
+    participant S1 as Shard 1
+
+    S0->>MC: Block n (miniblock 1)
+    MC-->>S0: Notarisation + ECP
+    MC->>S1: Proven miniblock header
+    S1->>MC: Block n+2 (exec miniblock 1)
+```
+
+#### Rounds required
+
+The transaction is considered **final** once miniblock 1 is executed and notarised in `shard 1`.
+
+| Round | Block location | Event |
+|-------|----------------|-------|
+| `n` | `shard 0` | Tx validated & executed (miniblock 1). |
+| `n + 1` | Metachain | Notarises `shard 0` block (`ECP`). |
+| `n + 2` | `shard 1` | Executes & finalises the mirrored miniblock. |
+
+Total latency ≈ 18 seconds on the actual 6 s‑block‑time mainnet.
+
+### Why did cross‑shard execution need six rounds before Andromeda?
+
+Before v1.9.6 a cross‑shard transfer had to survive **at least six separate blocks** to guarantee it could never be reverted elsewhere:
+
+| Step | Round | Chain | Purpose |
+|------|-------|-------|---------|
+| 1 | `k` | Source shard | Produce block **B<sub>k</sub>** containing the cross‑shard tx. |
+| 2 | `k + 1` | Source shard | **Confirmation block** C<sub>k+1</sub> proving B<sub>k</sub>. |
+| 3 | `k + 2` | Metachain | Notarise B<sub>k</sub> (only after it sees C<sub>k+1</sub>). |
+| 4 | `k + 3` | Metachain | Confirmation metablock M<sub>k+3</sub> proving M<sub>k+2</sub>. |
+| 5 | `k + 4` | Destination shard | Execute mirrored miniblock, produce D<sub>k+4</sub>. |
+| 6 | `k + 5` | Destination shard | Confirmation block D<sub>k+5</sub>; metachain can now notarise D<sub>k+4</sub>. |
+
+These guard‑rails were essential while only **63 of 400 validators** signed each shard block—an equivocating proposer could, in theory, create conflicting blocks until the confirmation arrived.
+
+With **Andromeda**, every block reaches finality immediately (400 signatures, fixed order), so the two confirmation stages are obsolete and the path collapses to three blocks.
+
+### Cross‑chain proof verification made simpler
+
+| Pre‑Andromeda | Post‑Andromeda |
+|---------------|----------------|
+| **63 / 400 validators** per block; membership shuffled each round. | **400 / 400 validators** sign every block for the entire epoch. |
+| Verifier had to reconstruct the 63‑node subset and their signature order for every proof. | Verifier only needs the epoch‑wide validator list once; proofs are a single aggregated BLS signature. |
+| Large metadata overhead in every cross‑chain proof. | Proofs are smaller, easier to verify, cheaper to transmit. |
+
+> **Effect:** Cross‑chain proofs are now lighter and faster to validate while preserving the same security guarantees.