block subpages

docs/dev/data-model/block-adproofs.md

@@ -0,0 +1,36 @@
+# ADProofs (Authenticated Data Proofs)
+
+ADProofs, short for Authenticated Data Proofs, are a crucial component of Ergo's block structure that allows for efficient and secure validation of transactions without requiring full blockchain download. They are particularly beneficial for "light clients" –  wallets or nodes that don't store the entire blockchain.
+
+**Function:**
+
+* **Efficient Transaction Validation:** ADProofs enable light clients to verify the validity of transactions within a block by proving they are included in the Merkle tree of the UTXO set (the record of unspent transaction outputs). This eliminates the need to download and process the entire UTXO set or the full block.
+* **State Verification:**  Light clients can use ADProofs to calculate the new state root (a cryptographic summary of the UTXO set) after applying the transactions in a block. This allows them to stay synchronized with the blockchain without storing the complete state.
+* **Security:** ADProofs are cryptographically secure, ensuring that any tampering with the transactions or the UTXO set will be detected during validation.
+
+**Structure:**
+
+The `ADProofs` class in [ADProofs.scala](https://github.com/ergoplatform/ergo/blob/master/ergo-core/src/main/scala/org/ergoplatform/modifiers/history/ADProofs.scala) defines the structure of ADProofs. It contains the following key elements:
+
+* **headerId:** The ID of the block header to which these proofs correspond.
+* **proofBytes:** The serialized cryptographic proof that allows for verification of the state changes.
+
+**Verification Process:**
+
+1. **Initialization:** A light client receives the block header, the ADProofs, and the list of transactions.
+2. **Proof Application:** The client uses the `ADProofs` to construct a `BatchAVLVerifier`. This verifier utilizes the provided proof to validate the changes made to the UTXO set by the transactions.
+3. **State Root Calculation:** The verifier calculates the new state root after applying the transactions. This calculated root is then compared against the state root declared in the block header.
+4. **Verification Result:** If the calculated state root matches the one in the header, the transactions and the state transition are considered valid.
+
+**Key Concepts:**
+
+* **Merkle Tree:** A tree-like data structure where each leaf node represents a piece of data (in this case, a transaction or a box) and each non-leaf node is a hash of its child nodes. This structure allows for efficient verification of data inclusion.
+* **AVL+ Tree:** A self-balancing binary search tree used in Ergo to represent the UTXO set. It enables efficient lookups and updates while maintaining a verifiable structure.
+* **Batch Verification:** The process of verifying multiple operations (transaction additions or removals) within the UTXO set simultaneously, optimizing efficiency.
+
+**Benefits:**
+
+* **Reduced Bandwidth:** Light clients can avoid downloading full blocks and the entire UTXO set, saving significant bandwidth.
+* **Increased Efficiency:**  ADProofs streamline the validation process, making it faster and less resource-intensive for light clients.
+* **Enhanced Scalability:** By enabling lightweight participation, ADProofs contribute to the overall scalability of the Ergo blockchain.
+

docs/dev/data-model/block-header.md

@@ -0,0 +1,35 @@
+# Block Header
+
+The block header in Ergo serves as a concise summary of a block's critical information. It plays a vital role in maintaining the integrity and security of the blockchain. 
+
+## Functions
+
+* **Chain Synchronization:**  Headers enable efficient synchronization between nodes on the network. By exchanging and validating headers, nodes can quickly agree on the current state of the blockchain without downloading every full block.
+* **Proof-of-Work Validation:** The header contains information necessary to verify the miner's Proof-of-Work (PoW) solution, ensuring that the block meets the network's difficulty requirements.
+* **Block Integrity:**  Headers include hashes that link to other sections of the block (transactions, proofs, extension), guaranteeing the integrity of the entire block. Any tampering with the block's content would result in a mismatch of these hashes.
+
+## Components
+
+The `Header` class in  [Header.scala](https://github.com/ergoplatform/ergo/blob/master/ergo-core/src/main/scala/org/ergoplatform/modifiers/history/header/Header.scala) defines the structure of the block header. Here's an overview of the key fields:
+
+* **version:**  Indicates the protocol version used to create the block. This allows for future upgrades and changes to the blockchain while maintaining backward compatibility.
+* **parentId:**  The ID of the previous block in the blockchain. This links blocks together, forming a chain.
+* **ADProofsRoot:** A cryptographic digest of the proofs that validate changes to the UTXO set (the record of unspent transaction outputs).
+* **stateRoot:**  A digest representing the root of the Merkle tree that captures the state of the UTXO set after this block is applied.
+* **transactionsRoot:** A digest of the Merkle root of all transactions included in the block.
+* **timestamp:** The time when the block was created, as reported by the miner.
+* **nBits:**  Represents the difficulty target for the block, determining how hard it was to mine.
+* **height:** The block's height in the blockchain (genesis block has height 1).
+* **extensionRoot:**  A digest of the Merkle root of the extension section, which can contain arbitrary data.
+* **powSolution:** The solution to the Proof-of-Work puzzle, demonstrating that the miner expended the necessary computational effort.
+* **votes:**  Votes cast by miners to signal preferences for changes to consensus parameters.
+* **unparsedBytes:**  A field to accommodate future protocol upgrades, allowing for the inclusion of data not yet parsed by current versions.
+* **sizeOpt:** An optional field storing the size of the header to optimize performance.
+
+
+## Key Concepts
+
+* **[Merkle Tree:](merkle-tree.md)** A data structure used extensively in blockchains to efficiently verify data integrity. It allows for quick verification that a particular piece of data is included in a larger set.
+* **UTXO (Unspent Transaction Output) Set:** The record of all unspent transaction outputs on the blockchain, representing the current distribution of the cryptocurrency.
+* **Proof-of-Work (PoW):** A consensus mechanism that requires miners to solve a computationally intensive puzzle to add blocks to the blockchain. This ensures the security and immutability of the chain.
+

docs/dev/data-model/block-transactions.md

@@ -0,0 +1,45 @@
+# Block Transactions
+
+The Transactions section of an Ergo block is the heart of the blockchain's state changes. It contains a list of all the transactions that are included and validated within that specific block. These transactions define how tokens and assets are transferred and how the overall state of the Ergo blockchain evolves.
+
+/// details | In the right place? 
+    {type: info, open: true}
+This page covers the structure of the transactions section of an Ergo block. For more general information on transactions, see [this](transactions.md) page.
+///
+## Function
+
+* **Value Transfer:**  Ergo transactions enable users to transfer ERG (Ergo's native token) and other custom tokens/assets to other users on the network.
+* **State Transition:** Each transaction consumes existing unspent boxes (which hold tokens and assets) and creates new boxes with potentially modified values and ownership. This process updates the state of the UTXO set (the record of all unspent boxes).
+* **Smart Contract Execution:** Transactions can trigger the execution of scripts within boxes, allowing for complex logic and decentralized applications to be implemented on the Ergo blockchain.
+
+## Structure
+
+The core structure of an Ergo transaction is defined by the `ErgoTransaction` class in [ErgoTransaction.scala](https://github.com/ergoplatform/ergo/blob/master/ergo-core/src/main/scala/org/ergoplatform/modifiers/mempool/ErgoTransaction.scala). 
+
+
+Here's a breakdown of its main components:
+
+* **inputs:**  A list of `Input` objects, each referencing an existing box that the transaction will spend. Each input includes a `spendingProof` to prove the spender has the right to consume the box.
+* **dataInputs:** A list of `DataInput` objects referencing boxes that the transaction needs to access for its scripts but won't spend. These provide data to the scripts without requiring ownership.
+* **outputCandidates:** A list of `ErgoBoxCandidate` objects representing the new boxes that the transaction will create. These candidates define the values, assets, and scripts of the new boxes.
+
+## Validation
+
+Ergo transactions undergo rigorous validation to ensure they are legitimate and maintain the integrity of the blockchain:
+
+* **Stateless Validation:**  Checks that don't require accessing the blockchain state, including:
+    *  Ensuring the transaction has inputs and outputs.
+    *  Verifying basic rules (no negative values, unique inputs, etc.).
+* **Stateful Validation:**  Requires accessing the blockchain state to check:
+    *  Whether the inputs refer to valid and unspent boxes.
+    *  Whether the spending proofs are correct.
+    *  Whether the transaction adheres to rules related to assets, fees, and block size limits.
+    *  Whether the scripts in the inputs are satisfied (using the `ErgoInterpreter`).
+
+## Key Concepts
+
+* **[Boxes](boxes.md):** The fundamental building blocks of Ergo's UTXO model. They are containers that hold ERG, other tokens, and scripts (smart contracts).
+* **Scripts:**  Programs written in [ErgoScript](ergoscript.md) (a powerful scripting language) that define the conditions for spending boxes.
+* **Spending Proofs:** Cryptographic proofs that demonstrate the spender has the right to use the funds in a box, often involving signatures or more complex cryptographic protocols.
+* **Context Extension:** A key-value map attached to a spending proof, providing additional data that can be used by scripts during validation.
+

docs/dev/data-model/block.md

@@ -1,45 +1,29 @@
----
-tags:
-  - Blocks
----
-
 # Understanding Blocks in Ergo
 
-Ergo's blockchain operates on a block interval [set at two minutes](difficulty.md). Initially, each block released 75 ERG, which were distributed among miners and the EF Treasury. This setup applied for the first two years of operation. From the second year onwards, the release rate decreased by 3.0 ERGs, with this reduction continuing every three months. This systematic decrease was initially programmed to halt emission eight years post Ergo's launch. However, with the introduction of [EIP-27](eip27.md), the emission period has been extended to approximately the year 2045.
-
-## Ergo Block Structure
-
-Ergo, similar to other blockchains like Bitcoin and Ethereum, segregates blocks into different sections for enhanced functionality. However, Ergo's structure is more complex than Bitcoin's, which only consists of a block header and transactions. Ergo's structure includes additional sections:
-
-1. **Header**: The header contains essential metadata about the block, including information necessary for synchronizing the chain and validating Proof-of-Work (PoW) accuracy. It also includes hashes that link to other sections of the block.
-    - The `Header` class, which defines the structure of the block header, can be explored in the [Header.scala](https://github.com/ergoplatform/ergo/blob/master/ergo-core/src/main/scala/org/ergoplatform/modifiers/history/header/Header.scala) file on GitHub.
+In blockchain technology, a **block** is a fundamental unit of data that groups together a set of transactions. These blocks are linked together chronologically to form a "blockchain," serving as a secure and transparent record of all transactions.
 
-2. **Block Transactions**: This section consists of all the transactions included within the block. It plays a critical role in defining the state changes in the Ergo blockchain.
-    - The transaction data structure is detailed in the [ErgoTransaction.scala](https://github.com/ergoplatform/ergo/blob/master/ergo-core/src/main/scala/org/ergoplatform/modifiers/mempool/ErgoTransaction.scala) file.
+PoW is a consensus mechanism that requires miners to solve complex mathematical problems to add new blocks to the blockchain. This process, known as "mining," involves significant computational effort, ensuring the security and immutability of the blockchain.
 
-3. **ADProofs**: Also known as authenticated data proofs, these are associated with transactions in the corresponding Block Transactions section. ADProofs allow light clients to authenticate all transactions and compute a new root hash without downloading the entire block.
-    - ADProofs are managed and structured within the [ADProofs.scala](https://github.com/ergoplatform/ergo/blob/master/ergo-core/src/main/scala/org/ergoplatform/modifiers/history/ADProofs.scala) file.
+Ergo, like other Proof-of-Work (PoW) blockchains such as Bitcoin, uses blocks to record transactions and ensure the integrity of the network. However, Ergo's block structure is more sophisticated, offering enhanced functionality and efficiency.
 
-4. **Extension**: This section holds additional information that doesn't fit into the previous sections. It includes interlinks and the chain's current parameters when the extension belongs to a block at the end of a voting epoch.
-    - For a detailed look at how the extension data is managed, refer to the [Extension.scala](https://github.com/ergoplatform/ergo/blob/master/ergo-core/src/main/scala/org/ergoplatform/modifiers/history/extension/Extension.scala) file.
+In Ergo, a new block is created approximately every **two minutes**.  Initially, each block rewarded miners with 75 ERG, which were distributed among them and the Ergo Foundation Treasury. This emission schedule applied for the first two years of the network's operation. You can find more details in the [emission section](emission.md).
 
-### The Extension Section in Detail
 
-The 'extension' section of Ergo's block structure contains specific mandatory fields, including NIPoPoWs links (which appear once every 1,024 block epoch) and parameters for [miner voting](governance.md), such as the current block size. The extension section can also include arbitrary fields as required.
+## Ergo Block Structure
 
-The extension section serves as a key-value storage accommodating a diverse range of data. The key is consistently 2 bytes long, and the maximum size of a value is 64 bytes. The overall Extension size should not exceed 16,384 bytes.
+Ergo's blocks are divided into distinct sections to optimize organization and functionality:
 
-Certain keys have predefined meanings:
+1. [**Header**](block-header.md): The header acts as a summary of the block's content. It includes metadata (block version, timestamp, etc.), hashes linking to other block sections, and the Proof-of-Work solution.
 
-- If the first byte of a key equals `0x00`, the second byte identifies the parameter, and the value determines the parameter's value.
-- Another predefined key is used for storing the interlinks vector. In this case, the first byte of the key is `0x01`, the second one matches the index of the link in the vector, and the value contains the actual link (32 bytes) prefixed with the frequency it appears in the vector (1 byte).
+2. [**Block Transactions**](block-transactions.md): This section contains the core data of the block – a list of all transactions included within it. These transactions define how tokens and assets are transferred on the Ergo blockchain.
 
-This intricate design allows various nodes and clients to download only the block sections relevant to them, significantly reducing storage, bandwidth, and CPU usage demands, thereby enhancing system efficiency.
+3. [**ADProofs**](block-adproofs.md):  These cryptographic proofs, short for Authenticated Data Proofs, allow light clients (nodes with limited storage) to verify transactions without downloading the entire block or the full UTXO set (the record of unspent transaction outputs).
 
-### Additional Resources
+4. [**Extension**](extension-section.md): This section provides a flexible space to store additional data that doesn't fit into the other sections. It includes interlinks for NiPoPoWs (efficient proof-of-work verification) and system parameters (e.g., block size).
 
-To further enhance its flexibility and efficiency, Ergo supports [Superblock Clients](log_space.md), providing an additional layer of adaptability to accommodate diverse user needs.
+This structured approach enhances efficiency and allows for greater flexibility in incorporating new features and upgrades into the Ergo blockchain.
 
-## Related Concepts: Ergo Modifiers
+## Related Concepts
 
-In Ergo's P2P protocol, blocks and transactions are referred to as "[Modifiers](modifiers.md)". Modifiers are transmitted between nodes as part of the network synchronization process. The Modifier Exchange process encompasses the protocols and systems in place to exchange this information efficiently and securely across the network.
+* **Ergo Modifiers:** In Ergo's peer-to-peer network protocol, blocks and transactions are referred to as "modifiers." These modifiers are exchanged between nodes to keep the network synchronized. [More details](modifiers.md)
+* **Superblock Clients:** Ergo supports "superblock clients," which provide an additional layer of efficiency and flexibility for specific use cases. [More details](log_space.md).