Revise Fundamentals

Author: AlvinHon

docs/fundamentals/accounts.md

@@ -11,8 +11,8 @@ tags:
 
 In Parallelchain Mainnet, accounts are divided into two types:
 
-- __Externally Owned Accounts (EOA)__: The address of an EOA is the public key of the keypair that is compatible with `ed25519_dalek`.
-- __Contract Accounts__: A contract account is created from contract deployment. The address is the hash of the concatenation of a contract's bytecode and the nonce of the EOA that deploys the contract. 
+- __Externally Owned Accounts (EOA)__: The address of an EOA is the public key of the keypair that is compatible with [ed25519-dalek](https://github.com/dalek-cryptography/curve25519-dalek/).
+- __Contract Accounts__: A contract account is created from contract deployment. The address is the [SHA256](https://en.wikipedia.org/wiki/SHA-2) hash of the concatenation of a contract's bytecode and the nonce of the **EOA** that deploys the contract. 
 
 Elements inside an account include:
 
@@ -25,10 +25,33 @@ The followings are elements that only apply to Contract Accounts:
 - **CBI Version**: The version of the Contract Binary Interface.
 - **Storage Hash**: The 32-byte SHA256 root hash of its Storage Trie. This is empty for an External.
 
+## How Account Works
+
+You can create **EOA** account by **ed25519-dalek** key generation algorithm. The account is composed of a 32-byte public key and a 32-byte private key. This public key is the **Address** which can be known to others. While your private key, which is used for signing [transactions](transactions.md), **MUST** be kept in secret.
+
+Address is usually displayed in [Base64url](https://datatracker.ietf.org/doc/html/rfc4648#section-5) format in ParallelChain Mainnet ecosystem. Here is an example:
+
+```text
+Tc0bU2oS0A0_GrjPKsDLSyVa3gc7PvzwWIAGRk-_SmA
+```
+
+If you want to transfer [XPLL](../introduction.md#what-is-xpll) to Alice's account, first you need to know her address. Then, you create a transaction with Alice's address as [recipient](transactions.md#account-commands), and sign it by using your private key. The **Balance** of your and Alice's account will be updated when this signed transaction is made to blockchain successfully. The **Nonce** of your account will be increased by 1.
+
+On the other hand, a **Contract Account** is not made up of cryptographic keys. Its address is a 32-byte hash. It is not able to sign a transaction. But similar to **EOA**, it has its own balance, and can receive XPLL from other accounts. See [Smart Contract](../for_developers/smart_contracts/introduction.md) for details.
+
 !!! Note
-    These accounts cannot be distinguished from each other just by looking at the address format.
+    The type of account cannot be distinguished from each other just by looking at the address format.
+
+See also:
+
+- [Create Account by CLI](../for_users/pchain_client_cli/manage_account.md)
+- [Create Account by Web Wallet](../for_users/web_wallet/create_account.md)
+- [Create Account by Xperience Browser Extension](../for_users/xperience_browser_extension/create_account.md)
+
+
+## Network Account
 
-A **Network Account** is a single identified network-wide account that maintains the state of ParallelChain Mainnet. This account is not associated with Ed25519 material. The network-significant data that the Network Account stores are composed of various fields:
+A **Network Account** is a single identified network-wide account that maintains the [state](nodes.md#world-state) of ParallelChain Mainnet. The purpose of this state is to implement the [staking](staking.md) related protocol. This account is not associated with Ed25519 material. The network-significant data that the Network Account stores are composed of various fields:
 
 - **Previous Validator Set**: The set of pools that form the validator set in the previous epoch. The stake in this validator set is locked until the next epoch.
 - **Current Validator Set**: The set of pools that form the validator set in the current epoch.

docs/fundamentals/blocks.md

@@ -5,9 +5,9 @@ tags:
 
 # Blocks
 
-**Block** is a data structure that describes and authorizes the execution of a batch of transactions (state transitions) on the blockchain.
+**Block** is a fundamental data structure in a blockchain. It describes execution of a batch of [transactions](transactions.md). Blocks are "chained" by attaching a cryptographic hash of an earlier block. The hash is the proof of the data integrity of the earlier blocks because if their content have been changed, the hash will not be the same. This is how blockchain provides data immutability.
 
-Elements inside a block include:
+Summary of the elements inside a block:
 
 - `Hash` - the unique identifier for the block
 - `Height` - a number that represents the position of the block on the blockchain
@@ -16,23 +16,116 @@ Elements inside a block include:
 - `Chain ID` - a number that identifies a particular Parallelchain Mainnet-based blockchain
 - `Proposer` - the public address of the block producer
 - `Timestamp` - the time the block was created, measured in seconds since 1970-01-01
-- `Base Fee Per Gas` - the minimum number of grays that a transaction must pay for every gas used to be included in the block
+- [Base Fee Per Gas](nodes.md#base-fee-per-gas-in-parallelchain-mainnet) - the minimum number of grays that a transaction must pay for every gas used to be included in the block
 - `Gas Used` - the amount of [gas](gas.md) used in a block, which is the total sum of the gas used in executing the included transactions
 - `Transactions Hash` - the root hash of the Merkle Tree that contains the transactions included in the block
 - `Receipt Hash` - the root hash of the Merkle Tree that contains the execution results of the transactions included in the block
 - `State Hash` - the root hash of the Merkle Tree that represents the current world state
 - `Log Bloom` - a 256-byte block-level [Bloom Filter](https://en.wikipedia.org/wiki/Bloom_filter) that combines all the Bloom Filters of each Log topic from the block's receipts
-- `Transactions` - the [transactions](transactions.md) that are included in the block
-- `Receipts` - the execution results of the transactions that are included in the block
+- [Transactions](transactions.md) - the transactions that are included in the block
+- [Receipts](transactions.md#receipt-and-logs) - the execution results of the transactions that are included in the block
 
-A block is a fundamental data structure in a blockchain system that serves as a container for a batch of transactions. It plays a critical role in maintaining the integrity and immutability of the blockchain.
+## Inside a Block
 
 Each block contains a unique identifier known as the `block hash`, which is calculated based on the contents of the block. The block hash acts as a fingerprint for the block, making it tamper-evident. Any change to the block's contents would alter its hash, making it easily detectable by network participants.
 
 The block header contains important metadata about the block, including the block's `height`, `timestamp`, and the `address of the block producer`, among others. It also includes Merkle Patricia Tree root hashes for transactions, receipts, and the current state of the blockchain.
 
-Transactions contained within the block are executed by the blockchain system, with the results recorded in `receipts`. These receipts contain information about the execution status of each transaction and are stored in a Merkle Patricia Tree, with the root hash included in the block header.
+Transactions contained within the block are executed by the blockchain system, with the results recorded in receipts. These receipts contain information about the execution status of each transaction and are stored in a Merkle Patricia Tree, with the root hash included in the block header.
 
 In addition to transactions and receipts, the block also contains a Bloom filter, which is a probabilistic data structure used to efficiently query logs associated with the transactions contained in the block.
 
-Overall, block is an essential component of a blockchain system, providing a secure and reliable means of recording and validating transactions while ensuring the immutability and integrity of the blockchain.
+Example of a block queried by [ParallelChain Client CLI](../for_users/pchain_client_cli/introduction.md):
+
+```json
+{
+  "header": {
+    "chain_id": 10000,
+    "block_hash": "Yn0SAN6KDA3v2uDjN_j1P_tFCCqgqCbak1g7zvHwr9Q",
+    "height": 2844080,
+    "justify": {
+      "chain_id": 10000,
+      "view": 2844930,
+      "block": "zT3iUT2sCmD80ztBDScBlAvUXhbzba7RTLtSiBLsvRg",
+      "phase": "Generic",
+      "signatures": {
+        "signatures": [
+          "hin8bfLnbuuUBRVB7GbClI0g1Ad0rfM_oDfvYILhwKPG_eqqZEDVyNj1c1VZeeRuUW94pqEQzAqbz4zQuTz0Dg",
+          "5usLkVtsEsFCIHQOKi8X_LjvMxzBd4xxJJz7QSbl1pGLimFUkpV5MCBi1SGRY9jVHCArxu6v3B_jn3xCZfhrCg",
+          null,
+          null,
+          "XqLSsQP6YkvtbBpPo7NX4o2Q7GvjAU-5dHfKPiDrdIBZPzTric_LvqJCgZLemUmzKkELkUl9BCBtFLth61qhAg",
+          null,
+          null,
+          null,
+          "PWhCgGM_SQpEf3NTZIdEIHecaFEd9MHptZqUyM4l7J4oR5aMrxkPYLRQ89msWfRtCF6fSvYVLZhTR-FjcIJqBg",
+          "lLnEWWKxoToD-URLN7PDWFBQTyC1waS9KHBAskgdXdn_bZIyr3XYoqxIbTcHW6f0m6qozQGkZTXQukGbi08fCA"
+        ]
+      }
+    },
+    "data_hash": "Tr4Z99mUiaHGVuzW5eyZ73bKqEXUcYPV1C5RkUVCP2U",
+    "timestamp": 1711515120,
+    "base_fee": 8,
+    "txs_hash": "wDUDiSjWumCmyEu_Fz0H8zqs3jSlpCMxN2NnST7fieM",
+    "state_hash": "rU3ilPOG1Lr-4fYtGTHpSXsMvZM8v0l5JX3PgK-wauc",
+    "receipts_hash": "uXRT1micHUt7orVPifaFg5BvOQJLd9K4mNAFo0zW0x4",
+    "proposer": "TY0vjFcDm681NupNBVSU9DKNunP6JlwNNhc7lDJ2uU0"
+  },
+  "transactions": [
+    {
+      "commands": [
+        {
+          "Transfer": {
+            "recipient": "kxrCl32WEzr7gr4Awb3jAMQtoh5zY8grabqlu-x42jY",
+            "amount": 2000000000
+          }
+        }
+      ],
+      "signer": "qPReY5x_DPKAx1v30UrU1x1RI61Wd2OxeZo2eSWcjMU",
+      "priority_fee_per_gas": 0,
+      "gas_limit": 67500000,
+      "max_base_fee_per_gas": 8,
+      "nonce": 428,
+      "hash": "dOrjtT7o5Y97mlLJFaCvdNUq6UgVQItVYGXHPoDw5n4",
+      "signature": "RLM3k5VDDzBqkQ7ios4TMP9LwL50n8hNQ7OjH-wcTE0Ts6F3uWDaA5J52sCyYr3aGGGElXKiIatqH15qVwMUAA"
+    }
+  ],
+  "receipts": [
+    [
+      {
+        "status_code": "Success",
+        "gas_used": 32820,
+        "return_values": "",
+        "logs": []
+      }
+    ]
+  ]
+}
+```
+
+## How Block Works
+
+Blocks are produced by validator [Nodes](nodes.md). To produce a block, the node executes transactions and creates receipts as a result of execution. The transactions and receipts become the content of a block, and the node will then compute the metadata such as `block height`, `timestamp`, hashes, etc. in the block header.
+
+When a block is created by a node, the validator nodes will validate it and then agree on the block content through a [consensus mechanism](consensus_mechanism.md). An agreed block is said to be **committed**. If the block is invalid, it will not be part of the blockchain. Nodes will keep producing new blocks, and this process repeats within a time interval (i.e. block time). As a result, the blockchain grows with more and more blocks.
+
+## Epoch Block
+
+**Epoch Block** is a special block created by executing a transaction with [Next Epoch Command](transactions.md#protocol-commands). This special block signifies the last block in an **Epoch**.
+
+Epoch is a protocol-defined period for measuring the performance of operators on the blockchain network. 
+
+The primary purpose of epochs in a blockchain is to facilitate various network functionalities and maintain consensus among network participants by defining a common reference point, which could be utilized to validate transactions. During one epoch, there would be block creation and block addition to the blockchain.
+
+In the ParallelChain Mainnet ecosystem, an `epoch` is defined by a predetermined block height or the number of blocks added to the blockchain, which is 8640. When a specific block height is reached or another 8640 blocks are added to the blockchain, the blockchain network would move from the current epoch to the next. The epoch transition could trigger critical events:
+
+- Reward stakes in Current Validator Set
+    - *Increase deposits* of owner and operator
+    - *Update stakes* if auto-stake-rewards is enabled
+    
+- Replacing Previous Validator Set with Current Validator Set
+- Replacing Current Validator Set with Next Validator Set
+- Returning Next Validator Set for the next leader selection
+
+Epoch transition ensures that only one set of validators is active on the blockchain network at any given time, which makes the information on the blockchain tamper-proof.
+

docs/fundamentals/consensus_mechanism.md

@@ -18,7 +18,7 @@ HotStuff guarantees that committed Blocks are *immutable*. That is, they can nev
 
 ![A graphic depicting a Tree (DAG) of Blocks. Blocks are coloured depending on how many confirmations they have.](../img/BlockTree%20Structure%20Diagram.png)
 
-A Block becomes *committed* the instant its third confirmation is written into the BlockTree. Confirmation for a Block `A` is another Block `B` such that there is a path between `B` to `A`.
+A Block becomes **committed** the instant its third confirmation is written into the BlockTree. Confirmation for a Block `A` is another Block `B` such that there is a path between `B` to `A`.
 
 The choice of third confirmation to define commitment--as opposed to first or second--is not arbitrary. HotStuff's safety and liveness properties hinge upon this condition. You can read this [paper](https://github.com/parallelchain-io/hotstuff_rs/blob/master/readme_assets/HotStuff%20paper.pdf) to learn more about it. To summarize:
 

docs/fundamentals/epoch.md

@@ -11,10 +11,10 @@ tags:
 
 There are different categories of gas cost in the ParallelChain Mainnet ecosystem:
 
-- WASM opcode execution inside a contract call
+- WASM opcode execution inside a contract [call](transactions.md#account-commands)
 - Reading and writing WASM memory from host functions inside a contract call
 - Transaction-related data storage
-- World state storage and access
+- [World state](nodes.md#world-state) storage and access
 - Cryptographic operations
 
 Details about gas can be found in [ParallelChain Mainnet Protocol](https://github.com/parallelchain-io/parallelchain-protocol/blob/master/Gas.md).

docs/fundamentals/gas.md

@@ -14,15 +14,14 @@ tags:
 
 **ParallelChain Mainnet** is a high-performance blockchain designed for enterprise-level use cases. It provides a platform for developers to build decentralised applications (dApps) with its efficient smart contract execution engine.
 
-It is designed to balance high performance and genuine decentralization. It is protected by the ParallelBFT consensus protocol, which adopts a sophisticated class-based node system to ensure fast and accountable consensus.
+It is designed to balance high performance and genuine decentralization. It is protected by the a Byzantine Fault Tolerant (BFT) consensus protocol, which adopts a sophisticated class-based node system to ensure fast and accountable consensus.
 
 For more information about the consensus protocol, please read the section [Consensus Mechanism](./consensus_mechanism.md).
 
 ## ParallelChain Testnet
 
 To ensure the new features in ParallelChain Mainnet have what it takes to survive decentralised deployment, they must first be battle-tested. This is where ParallelChain Testnet comes into play by allowing developers, or simply users, to develop and run smart contracts or transactions on ParallelChain and experiment with the blockchain, at no cost.
 
-The current testnet iteration delivers on Byzantine Fault Tolerant (BFT) consensus, the cornerstone of security in ParallelChain's proof-of-stake network. Besides this, Testnet 4 delivers big leaps in the contract SDK and developer experience, as well as a web Wallet.
 Both Mainnet and Testnet are accessible through [Explorer](#parallelchain-explorer). But only onTestnet, a service called [Faucet Service](#faucet-service) provides free tokens to users.
 
 ## Accessing the Networks
@@ -50,13 +49,13 @@ What you can do:
 
 ### Xperience Browser Extension
 
-**Xperience Browser Extension** is a browser extension that allows you to integrate your [dApp](../../for_developers/xperience_browser_provider_apis/introduction) with ParallelChain Wallet.
+**Xperience Browser Extension** is a browser extension that allows you to integrate your [dApp](../for_developers/xperience_browser_provider_apis/introduction.md) with ParallelChain Wallet.
 
 This enables your dapp to interact with your dapp users' XPLL accounts, to:
 
 - Send [transactions](transactions.md)
   - [Stake](staking.md) XPLL
-- Trigger confirmation for [smart contract](../../for_developers/smart_contracts/introduction) calls 
+- Trigger confirmation for [smart contract](../for_developers/smart_contracts/introduction.md) calls 
 
 **The browser extension is available on the [Chrome Web Store](https://chromewebstore.google.com/detail/xperience-browser-extensi/gpfllmjckejjhmmdmgbgmclmhopekjpf) now.**