From fe72491dea7cc6c00e86e3f8dc9a6dde10658554 Mon Sep 17 00:00:00 2001
From: necrashter
Date: Sun, 24 Apr 2022 21:37:51 +0300
Subject: Clarifications on transactions and blocks

---
 content/block_docs.md       | 21 ++++++++++++++++-----
 content/transaction_docs.md | 18 +++++++++++-------
 2 files changed, 27 insertions(+), 12 deletions(-)

(limited to 'content')

diff --git a/content/block_docs.md b/content/block_docs.md
index 2eec2ac..3c47231 100644
--- a/content/block_docs.md
+++ b/content/block_docs.md
@@ -9,7 +9,8 @@ weight = 10
 
 We use Blocks to commit proposed [Transactions](@/transaction_docs.md) to the ledger in order to realize them.
 `transaction_list` of the Block is filled with valid transactions.
-Blocks are valid when they are proposed with a `nonce` that produces a `hash` value with 6 zeroes (24 bits) at the left hand side.
+In order to create a valid block, the proposer must find a suitable `nonce` value that makes the `hash` of the block valid.
+The properties a valid hash should have will be explained in subsequent sections.
 
 We are _mining_ using [blake2s](https://www.blake2.net/) algorithm, which produces 256 bit hashes.
 Hash/second is roughly {{ exp(num="20x10", exponent="3") }} on my machine, a new block can be mined in around 4-6 minutes.
@@ -35,16 +36,24 @@ hash: String
 ```
 
 ## Coinbase
-The proposer of the block is identified by the first transaction in the `transaction_list`.
-This transaction is called the *coinbase* and will get awarded the block mining reward for their work.
+The proposer of the block is identified by the source of the first transaction in `transaction_list`.
+This transaction is called the *coinbase*, and its source will get awarded by the block mining reward for their work.
+The amount of the reward is determined by `block_reward` field of [`/config`](/config).
 
-> Place one of your own transactions as the first item in `transaction_list`
+> Place one of your own transactions as the first item in `transaction_list`.
+> Otherwise, someone else will receive the reward!
 
 # Mining
 The _mining_ process for the hash involves;
-- Creating a temporary JSON object with `transaction_list`, `timestamp` and `nonce` values
+- Creating a temporary JSON object with `transaction_list`, `nonce`, and `timestamp` values
 - Serializing it
+    - **NOTE:** Serialized JSON must comply with the rules explained in hash section of [transaction](@/transaction_docs.md) page.
+    - The order of keys should be as follows: `transaction_list`, `nonce`, `timestamp`.
 - Calculating blake2s hash of the serialized string
+- Checking if the hash is valid
+    - The hash is considered valid if its hexadecimal representation starts with an arbitrary number of zeros.
+    - This number is given by `hash_zeros` field of [`/config`](/config).
+    - For instance, if `hash_zeros` is 6, a valid hash must start with 6 hexadecimal zeros.
 
 If the resulting hash is valid, then you can create a `Block` JSON object with the found `nonce` and `hash`.
 
@@ -54,6 +63,8 @@ Fill this with the `hash` value you found during the mining process.
 
 # Block Rules
 - Blocks have to include a minimum number of transactions.
+    - `block_transaction_count` field of [`/config`](/config) yields this value.
+    - See [misc Page](@/misc_docs.md) for more information about configuration.
 - Blocks cannot have duplicate transactions.
 
 # References
diff --git a/content/transaction_docs.md b/content/transaction_docs.md
index 72c1ef7..a4617a6 100644
--- a/content/transaction_docs.md
+++ b/content/transaction_docs.md
@@ -24,19 +24,23 @@ timestamp: ISO 8601 <date>T<time>
 # Hash
 `tha` field in [jwt documentation](@/JWT.md) in fact stands for "The Hash".
 In the context of a transaction proposal, you need the [Md5](https://en.wikipedia.org/wiki/MD5) hash of the serialized JSON representation of transaction.
-Serializing in this context is a simple JSON to string conversion with key, value pairs enclosed with quotation marks (").
-The resulting JSON string should look something like;
+Since there are many ways to convert an object to JSON, we enforce the following rules (alongside the regular rules of JSON syntax) for consistency:
+- There shouldn't be any whitespace or newlines in the serialized string.
+- The order of fields should be exactly as shown above.
+- All keys and string values must be enclosed with quotation marks (`"`).
 
+Here's an example demostrating how your JSON string should look like:
 ```
 {"source":"bar","target":"baz","amount":2,"timestamp":"2021-04-18T21:49:00"}
 ```
 
-Or; without any whitespace, separated with `:` and `,`.
-
 # Transaction Rules
 - Transactions should be sent from your account (`source`) to any other account (`target`).
-- No two transaction with the same `source`/`target` pair can appear on the pending transaction list [/transactions](/transaction).
-- Transactions generate traffic which is something we desperately need in Gradecoin, so for every transaction you send, some Gradecoin will be generated out of thin air and will appear on the target.
+- You cannot create multiple transactions with the same `source`/`target` pair.
+- Transactions generate traffic which is something we desperately need in Gradecoin, so for every transaction you send, some Gradecoin will be generated out of thin air and will appear on your account.
+    - The amount of Gradecoin that will be generated is given by `tx_traffic_reward` field of [`/config`](/config).
+    - For example, if `tx_traffic_reward` is 1 and you send 2 coins, only 1 coin will be deduced from your account since you will be given 1 coin for generating traffic. The target will receive 2 coins.
 - Don't worry if your transaction goes unaccepted! Transactions do not disappear until they are committed into the ledger with a block.
 - Every transaction has a unique ID generated using the `source`, `target` and `timestamp` fields.
-- Transactions have an upper amount limit.
+- Transactions have a lower and upper amount limit.
+    - These are given by `tx_lower_limit` and `tx_upper_limit` fields of [`/config`](/config). See [misc page](@/misc_docs.md) for more information about configuration.
-- 
cgit v1.2.3-70-g09d2