cryptographic, ergoscript, block

docs/crypto.md

@@ -3,8 +3,183 @@ tags:
   - Sigma Protocols
 ---
 
-# Cryptographic
+$$
+\newcommand{\lst}[1]{#1}
+\newcommand{\Tup}[1]{(#1)}
+\newcommand{\Apply}[2]{#1\langle#2\rangle}
+\newcommand{\MSig}[3]{\text{def}~#1(#2): #3}
+\newcommand{\Ov}[1]{\overline{#1}}
+\newcommand{\TyLam}[3]{\lambda(\Ov{#1:#2}).#3}
+\newcommand{\Trait}[2]{\text{trait}~#1~\{ #2 \}}
+\newcommand{\To}{\mapsto}
+\newcommand{\Low}[1]{\mathcal{L}{[\![#1]\!]}}
+\newcommand{\Lam}[2]{\lambda#1.#2}
+\newcommand{\IfThenElse}[3]{\text{if}~(#1)~#2~\text{else}~#3}
+\newcommand{\False}{\text{false}}
+\newcommand{\True}{\text{true}}
+\newcommand{\langname}{ErgoTree}
+\newcommand{\corelang}{Core-\lambda}
+$$
+
+# Cryptographic Primitives and Structures in Ergo
+
+This document provides an in-depth look at the cryptographic schemes, protocols, and data structures used in the Ergo blockchain. The security and functionality of transactions on the Ergo platform rely heavily on cryptographic signatures and data integrity mechanisms. These ensure that only authorized parties can approve transactions and maintain the integrity of the data. This document outlines the internal workings of these cryptographic schemes, focusing on their implementation within the Ergo ecosystem, particularly in [`sigmastate-interpreter`](https://github.com/ScorexFoundation/sigmastate-interpreter), [`sigma-rust`](https://github.com/ergoplatform/sigma-rust), and [`Scrypto`](https://github.com/input-output-hk/scrypto).
+
+## Overview
+
+Ergo supports a wide range of cryptographic protocols via **composable Sigma protocols** integrated into the core of its blockchain. Cryptographic signature schemes are used to verify that a transaction was created by the owner of the corresponding private key, preventing unauthorized spending and ensuring the security of smart contracts.
+
+### Cryptographic Toolkit
+
+- **Hash Functions**: [SHA-256](https://github.com/input-output-hk/scrypto/blob/master/shared/src/main/scala/scorex/crypto/hash/Sha256.scala) & [Blake2b](https://github.com/input-output-hk/scrypto/blob/master/shared/src/main/scala/scorex/crypto/hash/Blake2b.scala)
+- **Encoding**: `Base58`
+- **Signing Algorithms**: ECDSA (`secp256k1`) and Schnorr
+- **Primitive Secrets**: Schnorr Signature & Diffie-Hellman Tuple
+- **Non-Interactive Proofs**: Proofs for Sigma statements are made non-interactive using the **Fiat-Shamir transformation**.
+
+For more information on cryptographic functions in ErgoScript, refer to [ErgoScript Cryptographic Functions](dev/scs/global-functions.md#cryptographic-functions).
+
+### Data Structures
+
+Ergo employs specialized cryptographic data structures, which are key to its efficiency and security:
+
+- **AVL+ Trees**: Used in Ergo's **Authenticated Dynamic Dictionary (ADD)**, AVL+ trees ensure that the state changes within the UTXO model are efficiently tracked and cryptographically verified. AVL+ trees maintain logarithmic performance for inserts, deletions, and lookups while providing cryptographic proofs of state changes. See the Scrypto implementation: [BatchAVLProver.scala](https://github.com/input-output-hk/scrypto/blob/master/shared/src/main/scala/scorex/crypto/authds/avltree/batch/BatchAVLProver.scala) and [BatchAVLVerifier.scala](https://github.com/input-output-hk/scrypto/blob/master/shared/src/main/scala/scorex/crypto/authds/avltree/batch/BatchAVLVerifier.scala).
+
+- **Merkle Trees**: Merkle trees secure and verify large datasets, such as the transactions within a block. They allow for efficient verification of transaction integrity without needing to download the entire dataset. Learn more about [Merkle Trees](merkle-tree.md).
+
+---
+
+## Schnorr Signatures
+
+Schnorr signatures form a core part of Ergo’s cryptographic framework, known for their simplicity, efficiency, and security. Compared to ECDSA, Schnorr signatures are better suited for complex cryptographic protocols and privacy-preserving transactions in blockchains.
+
+### How Schnorr Signatures Work
+
+The implementation of Schnorr signatures in Ergo is distributed across both the **sigmastate-interpreter** and **sigma-rust** repositories.
+
+```rust
+// Key Generation (sigma-rust)
+let private_key = SecretKey::random();
+let public_key = PublicKey::from(&private_key);
+```
+
+#### Key Generation
+
+A user generates a private key \(x\) and computes the public key \(P = xG\), where \(G\) is the generator point on the elliptic curve (SecP256K1). This is implemented in [`secret_key.rs`](https://github.com/ergoplatform/sigma-rust/blob/develop/ergo-lib/src/wallet/secret_key.rs).
+
+#### Signing
+
+To sign a message \(m\), the user generates a random nonce \(k\), computes \(R = kG\), and generates the signature:
+
+$$
+e = H(R || P || m)
+$$
+
+$$
+s = k + ex
+$$
+
+The signing logic is implemented in [`signing.rs`](https://github.com/ergoplatform/sigma-rust/blob/develop/ergo-lib/src/wallet/signing.rs) and [`DLogProtocol.scala`](https://github.com/ScorexFoundation/sigmastate-interpreter/blob/develop/interpreter/shared/src/main/scala/sigmastate/crypto/DLogProtocol.scala).
+
+#### Verification
+
+To verify the signature, the verifier computes:
+
+$$
+R' = sG - eP
+$$
+
+If \(e = H(R' || P || m)\), the signature is valid.
+
+### Example
+
+Here is an example demonstrating Schnorr signature signing and verification using **sigma-rust**:
+
+```rust
+let message = "sample message";
+let (sig, _) = sign(&private_key, message);
+let is_valid = verify(&public_key, &sig, message);
+assert!(is_valid);
+```
+
+### Use Cases of Schnorr Signatures
+
+- **Multi-Signature Protocols**: Schnorr signatures support **MuSig** (multi-signature aggregation), enabling multiple participants to collaboratively sign a transaction. This is useful for multi-signature wallets and allows trustless coordination.
+
+- **Adaptor Signatures**: These are used for private swaps, allowing conditional transactions (e.g., atomic swaps between different cryptocurrencies) to be executed without revealing sensitive information. Ergo has demonstrated private swaps with Bitcoin Cash using this technique.
+
+---
+
+## Sigma Protocols
+
+Sigma protocols enable privacy-preserving proofs and cryptographic operations in Ergo. They allow a prover to convince a verifier that they possess knowledge of a secret without revealing the secret itself, making them ideal for privacy-focused smart contracts.
+
+### Components of Sigma Protocols
+
+1. **Commitment**: The prover sends a commitment that doesn't reveal the secret.
+2. **Challenge**: The verifier sends a challenge to the prover.
+3. **Response**: The prover responds, demonstrating their knowledge of the secret without revealing it.
+
+Sigma protocols are particularly well-suited for multi-party computations and **zero-knowledge proofs**. Learn more about [Sigma Protocols](sigma.md).
+
+### Example
+
+Here is an example of how Sigma protocols are used to create zero-knowledge proofs:
+
+```scala
+val prover = new SigmaProver(secretKey)
+val proof = prover.prove(challenge)
+```
+
+### Non-Interactive Sigma Protocols
+
+Sigma protocols in blockchains are made **non-interactive** using the **Fiat-Shamir transformation**, allowing their use in decentralized applications. This transformation replaces the interactive challenge with a deterministic process, making the proof verifiable without interaction.
+
+Sigma protocol implementations can be found in:
+
+- [`SigmaPropProver.scala`](https://github.com/ScorexFoundation/sigmastate-interpreter/blob/develop/interpreter/shared/src/main/scala/org/ergoplatform/SigmaPropProver.scala) (Scala)
+- [`prover_result.rs`](https://github.com/ergoplatform/sigma-rust/blob/develop/ergo-lib/src/chain/transaction/input/prover_result.rs) (Rust)
+
+### Use Cases of Sigma Protocols
+
+- **Mixers and Fungibility**: Ergo’s **ZeroJoin** mixer uses ring signatures and Sigma protocols to preserve transaction fungibility. Learn more in [ZeroJoin](zerojoin.md).
+- **Stealth Addresses**: Sigma protocols power **stealth addresses**, allowing users to receive payments privately without exposing their public keys. See more about [Stealth Addresses](stealth-address.md).
+
+---
+
+## ErgoTree and Signature Schemes
+
+**ErgoTree** is Ergo’s smart contract framework. It allows the creation of complex spending conditions using Sigma protocols and Schnorr signatures.
+
+### Signature Scheme Integration in ErgoTree
+
+ErgoTree scripts define conditions under which UTXOs (called "boxes") can be spent. These conditions often require complex cryptographic operations, such as multi-signature verification or Sigma proof evaluations.
+
+- **Complex Spending Conditions**: ErgoTree allows contracts to define sophisticated conditions, including multi-signature schemes, time-based locks, and cryptographic proofs (e.g., Sigma proofs). For more details, refer to [ErgoTree](ergo-tree.md).
+- **Ring and Threshold Signatures**: ErgoTree supports **ring signatures** for privacy-preserving transactions and **threshold signatures** for collaborative smart contracts.
+
+### Example
+
+```scala
+val tree = ErgoTree.multiSig(2, List(pubKey1, pubKey2, pubKey3))
+val spendingCondition = tree.evaluate(tx)
+```
+
+
+## Security Considerations
+
+Ergo’s cryptographic schemes are grounded in the **hardness of the discrete logarithm problem** and other well-established cryptographic assumptions. Proper use of cryptography is critical to ensuring the security of smart contracts. Developers must carefully design their ErgoTree scripts to avoid vulnerabilities like weak randomness or improper validation checks.
+
+For testing and verifying the security of cryptographic schemes, Ergo has robust test coverage in the `sigmastate-interpreter`, such as in the [SigningSpecification](https://github.com/ScorexFoundation/sigmastate-interpreter/blob/develop/interpreter/shared/src/test/scala/sigmastate/crypto/SigningSpecification.scala).
+
+## Conclusion
+
+Ergo's cryptographic framework is built on strong foundations like Schnorr signatures, Sigma protocols, **Scrypto** primitives, and robust data structures like **AVL+ trees** and **Merkle trees**. These cryptographic tools enable flexible, secure, and privacy-preserving transactions, supporting decentralized applications that require advanced security and efficiency. The cryptographic primitives, Sigma protocols, and signature schemes are implemented across the `sigmastate-interpreter` and `sigma-rust` repositories, providing a powerful platform for developers.
+
+For more information, visit the [sigmastate-interpreter repository](https://github.com/ScorexFoundation/sigmastate-interpreter), [sigma-rust repository](https://github.com/ergoplatform/sigma-rust), and [Scrypto](https://github.com/input-output-hk/scrypto).
+
 
+<!--
 Ergo has generic support for variety of cryptographic protocols (via composable sigma-protocols built into core).
 
 ## Crypto Primitives
@@ -96,3 +271,4 @@ You can do basic things in a contract like calculating the hash, but what if you
 ## Scrypto
 
 [Scrypto](scrypto.md) is an open source cryptographic toolkit designed to make it easier and safer for developers to use cryptography in their applications.
+--> 

docs/dev/data-model/block.md

@@ -1,24 +1,45 @@
 ---
 tags:
-  - Data Model
+  - Blocks
 ---
+
 # Understanding Blocks in Ergo
 
-Ergo's blockchain operates on a block interval [set at two minutes](difficulty.md). Initially, each block releases 75 Ergs, which are distributed among miners and the Treasury. This setup is applicable for the first two years of operation. From the second year onwards, the release rate decreases by 3.0 Ergs, and this reduction of an additional 3.0 Ergs continues 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's blockchain operates on a block interval [set at two minutes](difficulty.md). Initially, each block releases 75 Ergs, which are distributed among miners and the Treasury. This setup applies for the first two years of operation. From the second year onwards, the release rate decreases 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: The Extension Section
+## 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:
 
-* Header
-* Transactions
-* Extensions
-* Proofs of UTXO transformation
+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.
+    - **GitHub Reference**: 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.
+
+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.
+    - **GitHub Reference**: 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.
+
+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.
+    - **GitHub Reference**: 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.
+
+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.
+    - **GitHub Reference**: 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.
+
+### 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.
 
+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.
+
+Certain keys have predefined meanings:
+
+- 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).
+
 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.
 
-## Additional Resources
+### Additional Resources
 
 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.
+
+## Related Concepts: Ergo Modifiers
+
+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.

docs/dev/data-model/structures/interlink-vectors.md

@@ -48,7 +48,7 @@ When a new block is mined:
 - The number of leading zeros in the hash determines the block's level in the interlink vector.
 - The block header is added to the vector at the corresponding level.
 
-**Code Reference**: The logic for creating and managing interlink vectors is implemented within the [Scorex repository](https://github.com/ScorexFoundation/scrypto) used by the Ergo blockchain. Specifically, you can find the relevant code in the [BlockHeader.scala](https://github.com/ergoplatform/ergo/blob/master/src/main/scala/org/ergoplatform/modifiers/history/header/Header.scala) file.
+**Code Reference**: The logic for creating and managing interlink vectors is implemented within the [Scorex repository](https://github.com/ScorexFoundation/scrypto) used by the Ergo blockchain. Specifically, you can find the relevant code in the [BlockHeader.scala](https://github.com/ergoplatform/ergo/blob/master/ergo-core/src/main/scala/org/ergoplatform/modifiers/history/header/Header.scala) file.
 
 ### 2. **Updating the Interlink Vector**:
 
@@ -57,7 +57,7 @@ As new blocks are added:
 - The interlink vector is updated by adding references to new block headers.
 - If a block with more leading zeros (indicating a higher level) is found, it replaces the previous block at that level.
 
-**Code Reference**: The interlink vector update mechanism is handled within the [Ergo block header construction process](https://github.com/ergoplatform/ergo/blob/master/src/main/scala/org/ergoplatform/modifiers/history/header/Header.scala).
+**Code Reference**: The interlink vector update mechanism is handled within the [Ergo block header construction process](https://github.com/ergoplatform/ergo/blob/master/ergo-core/src/main/scala/org/ergoplatform/modifiers/history/header/Header.scala).
 
 ### 3. **Verifying the Chain with Interlink Vectors**:
 
@@ -66,7 +66,7 @@ To verify the blockchain:
 - A client checks the blocks referenced in the interlink vector.
 - By verifying that each block in the vector adheres to the required difficulty level, the client confirms that the chain follows the longest chain rule.
 
-**Code Reference**: Chain verification using interlink vectors is integrated into the block validation logic in the [Ergo codebase](https://github.com/ergoplatform/ergo/blob/master/src/main/scala/org/ergoplatform/nodeView/history/ErgoHistory.scala), particularly within the [ErgoHistory.scala](https://github.com/ergoplatform/ergo/blob/master/src/main/scala/org/ergoplatform/nodeView/history/ErgoHistory.scala) file.
+**Code Reference**: Chain verification using interlink vectors is integrated into the block validation logic in the [Ergo codebase](https://github.com/ergoplatform/ergo/blob/master/ergo-core/src/main/scala/org/ergoplatform/nodeView/history/ErgoHistory.scala), particularly within the [ErgoHistory.scala](https://github.com/ergoplatform/ergo/blob/master/ergo-core/src/main/scala/org/ergoplatform/nodeView/history/ErgoHistory.scala) file.
 
 ### 4. **Batch Merkle Proofs and Interlink Vectors**: