rebase from devel

docs/.gitignore

@@ -1 +1 @@
-/book
+book

docs/book.toml

@@ -1,5 +1,5 @@
-[book]
-authors = ["tinaaaaalee"]
+[book] 
+authors = ["Lee Ting Ting"]
 language = "en"
 multilingual = false
 src = "src"

docs/src/SUMMARY.md

@@ -8,3 +8,4 @@
 - [API](./api.md)
 - [Advanced Usage for Developers](./advanced.md)
 - [FAQs](./faq.md)
+- [Contribute](./contribute.md)

docs/src/advanced.md

@@ -16,22 +16,9 @@ Variables -> Path -> Edit -> New -> C:\mingw-w64\mingw64\bin (it's "C:\mingw-w64
 
 Install [Git for Windows](https://gitforwindows.org/) and use a "Git Bash" shell to clone and build nim-beacon-chain.
 
-Install [CMake](https://cmake.org/) to be able to build libunwind (used for [lightweight stack traces](https://github.com/status-im/nim-libbacktrace)).
-
-When running the tests, you might hit some Windows path length limits. Increase them by editing the Registry in a PowerShell instance with administrator privileges:
-
-```powershell
-Set-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1
-```
-
-and run this in a "Git Bash" terminal:
-
-```bash
-git config --global core.longpaths true
-```
-
 If you don't want to compile PCRE separately, you can fetch pre-compiled DLLs with:
 ```bash
+mingw32-make # this first invocation will update the Git submodules
 mingw32-make fetch-dlls # this will place the right DLLs for your architecture in the "build/" directory
 ```
 
@@ -48,9 +35,9 @@ mingw32-make test # run the test suite
 After cloning the repo:
 
 ```bash
-# The first `make` invocation will update all Git submodules.
-# You'll run `make update` after each `git pull`, in the future, to keep those submodules up to date.
-make
+make # The first `make` invocation will update all Git submodules and prompt you to run `make` again.
+     # It's only required once per Git clone. You'll run `make update` after each `git pull`, in the future,
+     # to keep those submodules up to date.
 
 # Run tests
 make test

docs/src/beacon-chain.md

@@ -1,4 +1,19 @@
 # What is Beacon Chain?
 
-More introduction about beacon chain can be found in the [Ethereum 2.0 blog series](https://our.status.im/two-point-oh-the-beacon-chain/).
- 
+A complete introduction about the beacon chain can be found in the [Ethereum 2.0 blog series](https://our.status.im/two-point-oh-the-beacon-chain/).
+
+In short, the beacon chain is a **new type of blockchain** to help the Ethereum blockchain to smoothly transfer its consensus algorithm from PoW (Proof of Work) to PoS (Proof of Stake), aka Ethereum 2.0. You can also see it as a hybrid PoS + PoW solution.
+
+## Differences Compared to Ethereum 1.0
+
+In traditional PoW, those that propose new blocks are called **_miners_**, whereas in PoS, they are called **_validators_**. In essence, _miners_ rely on actual hardware (such as some specifically manufactured mining machines), while _validators_ rely on just software.
+
+## What it is Like to Be a Validator?
+
+It is obvious that you must have enough computing power or a dedicated hardware in order to be a miner, but how about being a validator? Here is a breif overview:
+
+1. A special smart contract named **_registration contract_** is deployed on the original Ethereum blockchain. Note that in this case, the new beacon chain and the original blockchain co-exists.
+2. To "register" as a validator, you have to first deposit **_32 Etheres_** from your account to this smart contract.
+3. Run the beacon node and wait for the network to sync before your validator is activated.
+4. That's all! Remember to stay connected to the network, or you may lost your deposit. :P
+

docs/src/contribute.md

@@ -0,0 +1,22 @@
+# Contribute
+
+Follow these steps to contribute to this book! <br>
+We use a utility tool called mdBook to create online books from Markdown files.
+
+## Before You Start
+
+1. Install mdBook from [here](https://github.com/rust-lang/mdBook).
+2. Clone the repository by `git clone https://github.com/status-im/nim-beacon-chain.git`.
+3. Go to where the Markdown files are located by `cd docs`.
+
+## Real-Time Update and Preview Changes
+
+1. Run `mdbook serve` in the terminal.
+2. Preview the book at [http://localhost:3000](http://localhost:3000).
+
+## Build and Deploy
+
+1. `mdbook build`
+2. `make publish-book`
+
+Thank you so much for your help to the decentralized and open source community. :)

docs/src/intro.md

@@ -2,20 +2,30 @@
 
 _Documentation for Nimbus Beacon Chain users and developers._
 
-Nimbus beacon chain is a research implementation of the beacon chain component of the upcoming Ethereum Serenity upgrade, aka Eth2. 
+Nimbus beacon chain is a research implementation of the beacon chain component of the upcoming Ethereum Serenity upgrade, aka Eth2.
 
 - Open sourced at [github.com/status-im/nim-beacon-chain/docs](github.com/status-im/nim-beacon-chain/docs).
 - Specification of our implementation can be found at [ethereum/eth2.0-specs](https://github.com/ethereum/eth2.0-specs/tree/v0.11.1#phase-0).
 
 ## Overview
+
 In this book, we will cover:
-1. [What is beacon chain](./beacon-chain.md) and [what is Nimbus](./nimbus.md) to equip you with the basic knowledge. 
-2. How to [become a validator](./validator.md) in Ethereum as a user. 
+
+1. [What is beacon chain](./beacon-chain.md) and [what is Nimbus](./nimbus.md) to equip you with some basic knowledge.
+2. How to [become a validator](./validator.md) in Ethereum as a user.
 3. [Installation steps](./install.md) for nimbus beacon chain.
 4. The [api documentation](./api.md) for interested developers.
-5. [Advanced usage](./advanced.md) for developers.  
-6. Common [questions and answers](./faq.md) to satisfy your curiosity. 
-
+5. [Advanced usage](./advanced.md) for developers.
+6. Common [questions and answers](./faq.md) to satisfy your curiosity.
+7. How to [contribute](./contribute.md) to this book.
 
 Feel free to give us feedback on how to improve as well as contribute to our book on github. :)
 
+## Disclaimer
+
+This documentation is assuming Nimbus is in its ideal state. The project is still under active development. Please submit Github issues if encountered any problem.
+
+<!-- > > > TODO:
+
+1. fill up the gitbook content
+2. write questions in the faq.md page -->

docs/src/validator.md

@@ -1,19 +1,60 @@
 # Become a Validator
 
-To become a validator, you have to first connect to a testnet.
+To become a validator, you have to first connect to a testnet, deposit your Ethers, and sync with the network.
 
-### Connecting to testnets
+## Recommended Testnets
 
-Nimbus connects to any of the testnets published in the [eth2-clients/eth2-testnets repo](https://github.com/eth2-clients/eth2-testnets/tree/master/nimbus).
+Though Nimbus can connect to any of the testnets published in the [eth2-clients/eth2-testnets repo](https://github.com/eth2-clients/eth2-testnets/tree/master/nimbus), below are the recommended ones:
 
-Once the [prerequisites](#prerequisites) are installed you can connect to testnet0 with the following commands:
+- Public Testnet: [witti](https://github.com/goerli/witti) ([explorer](https://witti.beaconcha.in))
+- Local Testnet: testnet0
+
+## Connecting to Testnets
+
+Before we start, we have to obtain 32 Ethers on the Goerli testnet. Then, we can deposit 32 Ethers to the registration smart contract to become a validator.
+
+1. Open your [MetaMask](https://metamask.io/) wallet, switch to the `Goerli Test Network` option from the top right cornor.
+2. Copy your account address by clicking on one of your accounts.
+3. Post your account address on a social media platform (Twitter or Facebook). Copy the url to the post.
+4. Paste your post url on the [Goerli faucet](https://faucet.goerli.mudit.blog/) and select `Give me Ether > 37.5 Ethers` from the top right cornor of the page.
+5. Wait for a few seconds and return to your MetaMask wallet to check if you have successfully received.
+6. Once the [prerequisites](./install.md) are installed, you can connect to testnet0 with the following commands: <br>
+
+- Change `testnet0` to `witti` to connect to the witti testnet.
+- **_Remember to replace `make` with `mingw32-make` if using Windows._**
 
 ```bash
 git clone https://github.com/status-im/nim-beacon-chain
 cd nim-beacon-chain
-make                 # This invocation will bootstrap the build system with additional Makefiles
+git checkout devel
+git pull
+make update
 make testnet0        # This will build Nimbus and all other dependencies
                      # and connect you to testnet0
 ```
 
-The testnets are restarted once per week, usually on Monday evenings (UTC)) and integrate the changes for the past week.
+<img src="./img/connect_testnet.PNG" alt="" style="margin: 0 40 0 40"/>
+
+7. The testnet should now be up and running. Then, you will be prompted to enter your private key of the account you want to deposit the 32 Etheres from. Find your private key from MetaMask as below:
+
+<img src="./img/export_pkey.PNG" alt="" width="200" style="margin: 0 40 0 40"/>
+
+<img src="./img/enter_private_key.PNG" alt="" style="margin: 0 40 0 40"/>
+
+8. Wait for a few seconds until you see your deposit has been sent:
+
+<img src="./img/deposit_sent.PNG" alt="" style="margin: 0 40 0 40"/>
+
+9. Now you should be syncing with the network. It may take a while (may be quite a few hours). You can know that you are synced if you see the following output.
+
+<img src="./img/success.PNG" alt="" style="margin: 0 40 0 40"/>
+
+You can also get a brief estimate of the time remaining until your network gets synced by comparing the output `epoch` value and the one in the blockchain explorer (the [witti explorer](https://witti.beaconcha.in) for example).
+
+## Trouble Shooting
+
+1. The directory that stores the blockchain data of the testnet is `build/data/testnet0` (replace `testnet0` with other testnet names). Delete this folder if you want to start over. For example, you can start over with a fresh storgae if you entered a wrong private key.
+
+2. Currently, you have to switch to the devel branch in order to run the validator node successfully.
+
+3. Everytime you want to update your node to the latest version, run `git pull`, `make update`, and then `make testnet0`.

vendor/go/src/github.com/libp2p/go-libp2p-daemon

@@ -0,0 +1 @@
+Subproject commit cd8b111a1ae4c2bdc02d0cdc3a78cb3d9977849a

vendor/nim-blscurve

@@ -1 +1 @@
-Subproject commit 1a18d0dbea6f1f00409c660be58eb5206060cb3c
+Subproject commit 4f87e747d8c1310be5660d3e61674392206a91ea

vendor/nim-chronicles

@@ -1 +1 @@
-Subproject commit 3d7619b1f559c86b2ef026f386d6d872b9331c82
+Subproject commit fc3f2d3755e035387ebcf20d87a45eb9dcefadbb

vendor/nim-chronos

@@ -1 +1 @@
-Subproject commit bedd1ded5edc3bfb6877f7025ca4b21f62492ffe
+Subproject commit bce0f878d16bea14395dc8944ff8dbdeffe33496

vendor/nim-confutils

@@ -1 +1 @@
-Subproject commit 26667818be48d428892b26be9535c1f0a98d1510
+Subproject commit 6e5d570490989c753d4645ba9173ef9358d302bb

vendor/nim-eth

@@ -1 +1 @@
-Subproject commit 4e31a86533fcb29a40d05b6e497e9165f72f5218
+Subproject commit d53cebcf5dd35728c27088d9c95923d7baad4ac4

vendor/nim-json-rpc

@@ -1 +1 @@
-Subproject commit 271512c161706e08533690fdc8bbbbc54f1dc0ed
+Subproject commit ecf49a06329f49f1993008b0ee08e3f3e13cc422

vendor/nim-json-serialization

@@ -1 +1 @@
-Subproject commit c478b7bbbab6ee298a25c29c7357783d94aaecaa
+Subproject commit aa51f6fed1715a91fd8b58072a1915422a133d4a

vendor/nim-libp2p

@@ -1 +1 @@
-Subproject commit 130c64f33a493074a64d4e2af2ae57091f5a480e
+Subproject commit 7b6e1c06888a831d61d7019a07d2d59d5bd079ea

vendor/nim-protobuf-serialization

@@ -1 +1 @@
-Subproject commit 879421b1216efb66aed5a7f4e14d02ff96db9123
+Subproject commit 08c6db775f3daee35fee098c72c0e36b8ec57833

vendor/nim-serialization

@@ -1 +1 @@
-Subproject commit d8ca3daf3a788f357bf96b8e61b3ffce9a018ea2
+Subproject commit 501f94ad61ae22197d565ac39a00783a6e6f6faa

vendor/nim-snappy

@@ -1 +1 @@
-Subproject commit 676fa656d3a6f4e24691f3f48829c979b1b1bcdd
+Subproject commit b4cd68e27a56dbda2a56d7b90e666b644cfd5be6

vendor/nim-stew

@@ -1 +1 @@
-Subproject commit bb2221ba8c8ea2d3fbbcfdb8d28796f8d3eff348
+Subproject commit a99dafab420bcbbffee35e9bd847a9014eafaffe

vendor/nim-testutils

@@ -1 +1 @@
-Subproject commit 1601894ec1fd1c7095d405eb0c846cac212fb18f
+Subproject commit fcc5aa3a532cf42f9f1074f29df36fd69b3d2920