6 files changed, 64 insertions, 61 deletions

diff --git a/content/JWT.md b/content/JWT.md
index 46da1a2..e77457f 100644
--- a/content/JWT.md
+++ b/content/JWT.md
@@ -7,15 +7,15 @@ weight = 4
 > JSON Web Tokens are representations of claims, or authorization proofs that fit into the `Header` of HTTP requests.
 
 # How?
-
-JWTs are used as the [MAC](https://en.wikipedia.org/wiki/Message_authentication_code) of operations that require authorization:
+JWTs are used as the [MAC](https://en.wikipedia.org/wiki/Message_authentication_code) of operations that require authorization.
+Gradecoin has 2 such operations:
 - block proposal
 - transaction proposal.
 
-They are send alongside the JSON request body in the `Header`;
+They are sent alongside the JSON request body in the `Header`;
 
-```html
-Authorization: Bearer aaaaaa.bbbbbb.ccccc
+```
+Authorization: Bearer <JWT Token here>
 ```
 
 Gradecoin uses 3 fields for the JWTs;
@@ -29,11 +29,13 @@ Gradecoin uses 3 fields for the JWTs;
 ```
 
 - `tha` is explained in [blocks](@/block_docs.md) and [transactions](@/transaction_docs.md) documentations.
-- `iat` when the JWT was created in [Unix Time](https://en.wikipedia.org/wiki/Unix_time) format
-- `exp` when the JWT will expire & be rejected in [Unix Time](https://en.wikipedia.org/wiki/Unix_time)
+- `iat` when the JWT was created in [Unix Time](https://en.wikipedia.org/wiki/Unix_time) format.
+- `exp` when the JWT will expire & be rejected in [Unix Time](https://en.wikipedia.org/wiki/Unix_time).
 
 # Algorithm
-We are using [RS256](https://www.rfc-editor.org/rfc/rfc7518.html#section-3.1), `RSASSA-PKCS1-v1_5 using SHA-256`. The JWTs you encode with your private RSA key will be decoded using the public key you have authenticated with. You can see how the process works [here](https://jwt.io/).
+We are using [RS256](https://www.rfc-editor.org/rfc/rfc7518.html#section-3.1), `RSASSA-PKCS1-v1_5 using SHA-256`.
+The JWTs you encode with your private RSA key will be decoded using the public key you have authenticated with.
+You can see how the process works and create ad hoc tokens [here](https://jwt.io/).
 
 # References
 - [RFC, the ultimate reference](https://tools.ietf.org/html/rfc7519)
diff --git a/content/_index.md b/content/_index.md
index d0be673..3522122 100644
--- a/content/_index.md
+++ b/content/_index.md
@@ -4,7 +4,6 @@ sort_by = "weight"
 +++
 
 # Welcome to Gradecoin!
-
 Blockchains are incredibly simple yet can appear very complicated, we will see how they work and practice programming _production_ cryptography code.
 
 This server is the sandbox for the PA1, it's currently running the Gradecoin application. Gradecoin is the faux currency we will use to simulate a blockchain network. At the end of the simulation, the amount of Gradecoin you hold will be your PA1 grade.
@@ -17,7 +16,7 @@ Blocks need to be _mined_ beforehand using Proof-of-work, or brute force.
 Gradecoin offers 3 endpoints at [/register](/register), [/block](/block) and [/transaction](/transaction). You can only send GET requests to /block and /transaction without authorization.
 The server is programmed in [RESTful](https://www.service-architecture.com/articles/web-services/representational_state_transfer_rest.html) architecture, there are no `DELETE`, `PUT` or `UPDATE` operations, though.
 
-Gradecoin uses a Proof-of-work block accepting mechanism. It uses single round [Blake2s](https://www.blake2.net/) hashing which produces 256-bit (64 hexadecimal characters) output. The [target](https://wiki.bitcoinsv.io/index.php/Target) hash is _24 bits_ or _6 hexadecimal characters_ of 0. During testing, I could mine a block on average around 4-6 minutes.
+Gradecoin uses a Proof-of-work block accepting mechanism. It uses single round [Blake2s](https://www.blake2.net/) hashing which produces 256-bit (64 hexadecimal characters) output. The [target](https://wiki.bitcoinsv.io/index.php/Target) hash is _24 bits_ or _6 hexadecimal characters_ of 0.
 
 > We're expecting you to use existing tools and implementations. Standards are hard. [Don't roll your own crypto](https://www.reddit.com/r/crypto/comments/2coqsy/dont_roll_your_own/). Feel free to ask questions. Collaborate.
 
@@ -25,7 +24,8 @@ You might ask,
 
 > But if nobody has any Gradecoin then how do we have transactions?
 
-There is a bank! Their public key is `31415926535897932384626433832795028841971693993751058209749445923` and they have some amount of Gradecoin preloaded. It's also the only account that you can send transactions requests _to_ yourself.
+You get rewarded for your hard work during the authentication with some Gradecoin to start with!
+Then you can earn block rewards by proposing blocks, create some Gradecoins by generating traffic on the system, or transact with our new highly trained AI bots!
 
 # Coinbase
 The first transactions of a block is called the `coinbase`. They are the **author** of the block proposal and if the block is accepted then they get compensated for their efforts with some Gradecoin.
@@ -39,6 +39,7 @@ Gradecoin uses 2048 bit RSA keypairs.
 - Download `Gradecoin`'s Public Key from [Moodle](https://odtuclass.metu.edu.tr/my/)
 - Encrypt your [JSON](https://www.json.org/json-en.html) wrapped `Public Key`, `Student ID` and one time `passwd` using Gradecoin's Public Key
 - Your public key is now in our database and can be used to sign your JWT's during requests
+- **Don't forget your Public Key**
 - For more information, check the [register](@/register_docs.md) page
 
 ## /transaction
@@ -55,10 +56,10 @@ Gradecoin uses 2048 bit RSA keypairs.
 - Fetch the last accepted `Block` with a GET request
 - For more information, check our [block](@/block_docs.md) page
 
-    `Authorization`: The request header should have Bearer JWT.Token signed with Student Public Key
+> `Authorization`: The request header should have Bearer JWT.Token signed with Student Public Key
 
 ## /user
-- Meant to be used in the browser, you can see the current list of users and their balance here
+- Looking for people to conduct business with? Everyone is listed here! 🤖👋 are bots who are very eager to transact with you. I've trained them personally.
 
 # Questions
 ## This all sound complicated!
@@ -87,12 +88,13 @@ At the end of the _simulation_, your Gradecoin balance will be your grade. I wil
 - perl
 - rust
 - python
+- dart/typescript
 - random assortment of bash scripts
 
 If your favourite programming language is missing please let me know 🤷?
 
 ## Can my friends play?
-Sadly, no. Student's who are enrolled to the class will receive one-time-passwords for authentication.
+Probably not at this point. I've allowed a couple of people during the testnet phase but don't intend to any more.
 
 ## How and or Why?
 - [Built](https://xkcd.com/2314/), [with](https://lofi.cafe/) [Rust](https://xkcd.com/2418/)
diff --git a/content/block_docs.md b/content/block_docs.md
index 92880b6..05bf8ee 100644
--- a/content/block_docs.md
+++ b/content/block_docs.md
@@ -4,11 +4,19 @@ description = "Block Documentation"
 weight = 10
 +++
 
-A block that was proposed to commit Transactions in `transaction_list` to the
-ledger with a nonce that made `hash` valid; 6 zeroes at the left hand side of the
-hash (24 bytes).
+> Blocks commit proposed transactions into the ledger.
+> A transaction that do not appear on a valid block is not accepted by the network.
 
-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.
+Blocks in Gradecoin are proposed to commit [Transactions](@/transaction_docs.md) that were proposed previously to the system.
+`transaction_list` of the Block should be filled with valid transactions to be committed.
+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.
+
+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.
+
+{% tidbit() %}
+We have seen blocks that came in within a minute during the testnet phase!
+{% end %}
 
 # Requests
 
@@ -16,14 +24,13 @@ We are _mining_ using [blake2s](https://www.blake2.net/) algorithm, which produc
 A HTTP `GET` request to [/block](/block) endpoint will return the latest mined block.
 
 ## POST
-
-A HTTP `POST` request with Authorization using JWT will allow you to propose your own blocks.
+A HTTP `POST` request with Authorization using [JWT](@/JWT.md) will allow you to propose your own blocks.
 
 # Fields
 ```
-transaction_list: [array of Fingerprints]
+transaction_list: [array of Transaction IDs]
 nonce: unsigned 32-bit integer
-timestamp: ISO 8601 <date>T<time>
+timestamp: ISO 8601 Timestamp (<date>T<time>)
 hash: String
 ```
 
@@ -36,8 +43,12 @@ The _mining_ process for the hash involves;
 If the resulting hash is valid, then you can create a `Block` JSON object with the found `nonce` and `hash`.
 
 # Hash
+`tha` field in [jwt documentation](@/JWT.md) stands for "The Hash" in the context of blocks.
+Fill this with the `hash` value you found during the mining process.
 
-```tha``` field in [jwt documentation](/jwt) in fact stands for "The Hash", in the case of a post request for a block, you need to use hash field of the block.
-
+# Block Rules
+- Blocks should include some minimum number of transactions.
+- Blocks cannot have duplicate transactions.
 
-[ISO 8601 Reference](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations)
+# References
+- [ISO 8601 Reference](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations)
diff --git a/content/misc_docs.md b/content/misc_docs.md
index 90ea514..695119b 100644
--- a/content/misc_docs.md
+++ b/content/misc_docs.md
@@ -4,14 +4,10 @@ description = "Documentation about everything else"
 weight = 10
 +++
 
-We thought it might be good to explain some concepts you might have questions about.
-
 # Fingerprint
-
 ## Definition
 
 A fingerprint is a 256 bit 64 character hexadecimal user identifier for users. Fingerprints are used in defining users in [transactions](@/transaction_docs.md) and [blocks](@/block_docs.md).
 
 ## Fingerprint Generation
-
 A user's finger print is generated via applying SHA256 sum of the user's public RSA key.
diff --git a/content/register_docs.md b/content/register_docs.md
index 7c405b8..4fde05f 100644
--- a/content/register_docs.md
+++ b/content/register_docs.md
@@ -4,15 +4,12 @@ description = "Register Documentation"
 weight = 3
 +++
 
-POST request to `/register` endpoint
-
-Lets a user to authenticate themselves to the system.
-Only people who are enrolled to the class can open Gradecoin accounts.
-This is enforced with your Student ID (e123456) and a one time password you will receive.
+Here you can authenticate yourself with the system.
+Only people who are enrolled to the class can open Gradecoin accounts, with some exceptions for people who asked nicely.
+This is enforced with your Student ID (e123456) and a one time password you received with your complementary *Welcome to Gradecoin* email.
 
 # Authentication Process
-
-> The bytes you are sending over the network are all Base64 Encoded
+> The cryptographic outputs you are sending over the network are all Base64 Encoded
 
 - Gradecoin's Public Key (`gradecoin_public_key`) is listed on our Moodle page and [here](/gradecoin.pub). Download and load it it to your client.
 - Create a JSON object (`P_AR`) with your `metu_id` ("e"+`6 chars`) and `public key` in base64 (PEM) format (`S_PK`) [reference](https://tls.mbed.org/kb/cryptography/asn1-key-structures-in-der-and-pem)
@@ -25,11 +22,10 @@ This is enforced with your Student ID (e123456) and a one time password you will
 ```
 
 ## Cipher Initialization
-
 > Since we are working with AES-128, both key and IV should be 128 bits (or 32 hexadecimal characters)
 
 - Pick a short temporary key (`k_temp`)
-- Pick a random IV [1](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Initialization_vector_(IV)) [2](https://en.wikipedia.org/wiki/Initialization_vector) (`iv`).
+- Pick a random IV ([1](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Initialization_vector_(IV))) ([2](https://en.wikipedia.org/wiki/Initialization_vector) (`iv`)).
 
 ## Encryption
 - Encrypt the serialized string of `P_AR` with 128 bit block [AES](https://en.wikipedia.org/wiki/Initialization_vector) in [CBC](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#CBC) mode with [Pkcs7 padding](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Padding) using the temporary key (`k_temp`), the result is `C_AR`. Encode this with base64.
@@ -51,4 +47,11 @@ The available tools and libraries might warn you about how using the primitives
 ```
 
 If your authentication process was valid, you will be given access and your public key fingerprint that is your address.
+Please note it down.
 You can now sign [JWTs](@/JWT.md) to send authorized transaction requests.
+After all this, you might want to bask in the glory of having successfully managing your way through a home-made cryptographic system.
+Maybe the Gradecoin you got given as the registration reward will help.
+
+{% tidbit() %}
+Seriously, congratulations
+{% end %}
diff --git a/content/transaction_docs.md b/content/transaction_docs.md
index 05c1534..f9e8947 100644
--- a/content/transaction_docs.md
+++ b/content/transaction_docs.md
@@ -7,17 +7,14 @@ weight = 6
 A transaction request between `source` and `target` to move `amount` Gradecoin.
 
 # Requests
-
 ## GET
 A HTTP `GET` request to [/transaction](/transaction) endpoint will return the current list of pending transactions.
 
 ## POST
-
-A HTTP `POST` request with Authorization using JWT to [/transaction](/transactions) will allow you to propose your own transactions.
+A HTTP `POST` request with Authorization using [JWT](@/JWT.md) to [/transaction](/transaction) will allow you to propose your own transactions.
 
 # Fields
 ```
-by: Fingerprint
 source: Fingerprint
 target: Fingerprint
 amount: unsigned 16 bit integer
@@ -25,28 +22,20 @@ timestamp: ISO 8601 <date>T<time>
 ```
 
 # Hash
-
-`tha` field in [jwt documentation](@/JWT.md) in fact stands for "The Hash", in the case of a post request for a transaction, you need the Md5 hash of the serialized JSON representation of transaction. The resulting JSON string should look something like;
+`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;
 
 ```
-{"by":"foo","source":"bar","target":"baz","amount":2,"timestamp":"2021-04-18T21:49:00"}
+{"source":"bar","target":"baz","amount":2,"timestamp":"2021-04-18T21:49:00"}
 ```
 
 Or; without any whitespace, separated with `:` and `,`.
 
-# Bank
-
-There is a `bank` account with Fingerprint `31415926535897932384626433832795028841971693993751058209749445923`
-
-{% tidbit() %}
-First 64 digits of Pi
-{% end %}
-
-This is the only account that will let you _withdraw_ from them.
-
-```
-by: this has to be your Fingerprint
-source: this can be either you or the bank
-target: this can be a valid fingerprint or yourself if source is the bank
-...
-```
+# Transaction Rules
+- Transactions should be sent from your account (`source`) to any other account (`target`).
+- 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.
+- 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 from the `source` and `target` fields. No two transaction with the same ID can appear on the pending transaction list [/transactions](/transaction)
+- Transactions have an upper amount limit.