Docs update #4176

gamarin2 · 2019-04-23T14:15:42Z

Docs update:

Fix gaia to cosmos-hub
Added doc about upgrading
Other little nits

Will open a PR back to develop once merged

Targeted PR against correct branch (see CONTRIBUTING.md)
Linked to github-issue with discussion and accepted design OR link to spec that describes this work.
Wrote tests
Updated relevant documentation (docs/)
Added a relevant changelog entry: sdkch add [section] [stanza] [message]
rereviewed Files changed in the github PR explorer

For Admin Use:

Added appropriate labels to PR (ex. wip, ready-for-review, docs)
Reviewers Assigned
Squashed all commits, uses message "Merge pull request #XYZ: [title]" (coding standards)

codecov · 2019-04-23T14:29:53Z

Codecov Report

Merging #4176 into master will increase coverage by 0.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #4176      +/-   ##
==========================================
+ Coverage      60%   60.01%   +0.01%     
==========================================
  Files         212      212              
  Lines       15127    15127              
==========================================
+ Hits         9077     9079       +2     
+ Misses       5427     5425       -2     
  Partials      623      623

codecov · 2019-04-23T14:29:54Z

Codecov Report

Merging #4176 into master will increase coverage by 0.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #4176      +/-   ##
==========================================
+ Coverage      60%   60.01%   +0.01%     
==========================================
  Files         212      212              
  Lines       15127    15127              
==========================================
+ Hits         9077     9079       +2     
+ Misses       5427     5425       -2     
  Partials      623      623

alexanderbez · 2019-04-23T14:33:25Z

Thanks @gamarin2! In order to avoid the conflict mess we had last time with v0.34.0 and until we have a single canonical git branch, this PR should be targeted towards master and develop.

gamarin2 · 2019-04-23T14:38:01Z

Yep @alexanderbez, indicated it cf "Will open a PR back to develop once merged". I will cherry pick, but want to wait for reviews first

jackzampolin

So this PR has a couple of net new documents as well as typo fixes. It would be better if we could split those up in to separate PRs in the future. That being said, the general app explainer that is here is quite good. I think the upgrade guide needs a refactor.

docs/cosmos-hub/gaiacli.md

jackzampolin · 2019-04-23T15:09:19Z

docs/cosmos-hub/upgrade-node.md

+# Upgrade Your Node
+
+::: warning
+The detailed procedure to upgrade a mainnet node from `cosmoshub-1` to `cosmoshub-2` can be found [here](https://gist.github.com/alexanderbez/5e87886221eb304b9e85ad4b167c99c8). 


This is kinda incorrect. That is the procedure to generate the genesis.json file for cosmoshub-2 from the cosmoshub-1 state-dump at block 500,000. I don't think we need to link to those here.

jackzampolin · 2019-04-23T15:11:03Z

docs/cosmos-hub/upgrade-node.md

@@ -0,0 +1,99 @@
+# Upgrade Your Node


I think this guide needs a rethink and shouldn't block the rest of this PR. This should be a doc that describes the process for upgrading a network generically and explains each of the steps. This guide kinda jumps in at the mainnet upgrade and then has that content in less detail at the bottom of the doc.

jackzampolin · 2019-04-23T15:28:34Z

docs/cosmos-hub/upgrade-node.md

+The first step is to remove your current genesis:
+
+```bash
+rm $HOME/.gaiad/config/addrbook.json $HOME/.gaiad/config/genesis.json


I don't think users will want to remove their addrbook?

oh this should not be there, good catch

alexanderbez · 2019-04-23T15:39:08Z

docs/cosmos-hub/delegator-guide-cli.md

+**Note: These commands need to be run on an online computer. It is more secure to perform them commands using a ledger device. For the offline procedure, click [here](#signing-transactions-from-an-offline-computer).**
+::: 
+
+```bash


Maybe we should just point to the gaiacli.md docs? The develop branch has changed this to now:

$ gaiacli tx send [from_key_or_address] [to_address] [amount] [flags]

I think we should keep it as what it is in mainnet, BUT I will update it when doing the cherry pick to develop (setting a reminder rn)

Did we kill the --from flag?

Yeah but not on v0.34.x yet, which is what the master docs reflect.

docs/cosmos-hub/gaiacli.md

docs/cosmos-hub/delegator-guide-cli.md

docs/cosmos-hub/gaiacli.md

docs/cosmos-hub/upgrade-node.md

fedekunze · 2019-04-23T17:05:53Z

docs/cosmos-hub/upgrade-node.md

+## Reset Data
+
+:::warning 
+If the version <new_version> you are upgrading to is not breaking from the previous one, you should not reset the data. If it is not breaking, you can skip to [Restart](#restart)


Suggested change

If the version <new_version> you are upgrading to is not breaking from the previous one, you should not reset the data. If it is not breaking, you can skip to [Restart](#restart)

If the new version you are upgrading to doesn't have any braking changes, you can skip to the [Restart](#restart) section.

docs/cosmos-hub/upgrade-node.md

fedekunze · 2019-04-23T17:09:19Z

docs/intro/sdk-design.md

 ```
                                      +
                                      |
-                                      |  Transaction relayed from Tendermint
-                                      |  via DeliverTx
+                                      |  Transaction relayed from the full-node's Tendermint engine 


Unrelated, but it'd be cool to have an image here instead

Co-Authored-By: gamarin2 <gautier@tendermint.com>

jackzampolin · 2019-04-23T22:03:28Z

docs/cosmos-hub/upgrade-node.md

+
+To restart your node, just type:
+
+```bash


Do we want to add a link to the systemd example thing?

what's that

rigelrozanski

Here are a few post-merge comments, may want to consider another PR for any corrections

rigelrozanski · 2019-04-26T01:05:53Z

docs/intro/README.md

+
+- `CheckTx`: When a transaction is received by Tendermint Core, it is passed to the application to check if a few basic requirements are met. `CheckTx` is used to protect the mempool of full-nodes against spam. A special handler called the "Ante Handler" is used to execute a series of validation steps such as checking for sufficient fees and validating the signatures. If the check is valid, the transaction is added to the [mempool](https://tendermint.com/docs/spec/reactors/mempool/functionality.html#mempool-functionality) and relayed to peer nodes. Note that transactions are not processed (i.e. no modification of the state occurs) with `CheckTx` since they have not been included in a block yet. 
+- `DeliverTx`: When a [valid block](https://tendermint.com/docs/spec/blockchain/blockchain.html#validation) is received by Tendermint Core, each transaction in the given block is passed to the application via `DeliverTx` to be processed. It is during this stage that the state transitions occur. The "Ante Handler" executes again along with the actual handlers for each message in the transaction.
+ - `BeginBlock`/`EndBlock`: These messages are executed at the beginning and the end of each block, whether the block contains transaction or not. It is useful to trigger automatic execution of logic. Proceed with caution though, as computationally expensive loops could slow down your blockchain, or even freeze it if the loop is infinite. 


we should explain this concept in-terms of the state machine running as a single thread. that way I'm not sure we'd need to mention "or even freeze it .." which is kinda a funny sentence - that is implied.

Ok, I will add a note about single threading

rigelrozanski · 2019-04-26T01:07:20Z

docs/intro/README.md

+
+Here are the most important messages of the ABCI:
+
+- `CheckTx`: When a transaction is received by Tendermint Core, it is passed to the application to check if a few basic requirements are met. `CheckTx` is used to protect the mempool of full-nodes against spam. A special handler called the "Ante Handler" is used to execute a series of validation steps such as checking for sufficient fees and validating the signatures. If the check is valid, the transaction is added to the [mempool](https://tendermint.com/docs/spec/reactors/mempool/functionality.html#mempool-functionality) and relayed to peer nodes. Note that transactions are not processed (i.e. no modification of the state occurs) with `CheckTx` since they have not been included in a block yet. 


It would be good to discuss what happens when CheckTx fails (before or after the signature verification part)

This is just an intro, not the full CheckTx explanation (which will be in another doc). We just want to give a general sense of what CheckTx does at this point

rigelrozanski · 2019-04-26T01:08:48Z

docs/intro/README.md

+
+The main part of a Cosmos SDK application is a blockchain daemon that is run by each node in the network locally. If less than one third of the *validator set* is byzantine (i.e. malicious), then each node should obtain the same result when querying the state at the same time. 
+
+## ABCI


It would be good to expand this acronym here

yes, will update

rigelrozanski · 2019-04-26T01:13:38Z

docs/intro/README.md

+|        |                 |        |
+|   S    +---------------->+   S'   |
+|        |    apply(T)     |        |
+--------+                 +--------+


This (and the next) diagram are maybe a bit superfluous here. I think an clearly written description of determinism as it relates the state machine (without assigning letters ex. T or using diagrams) would be adequate.

I can touch on determinism, but I push back on the idea that the diagrams are superfluous. Remember that all this is intro material. We can assume no prior knowledge from people reading this, and we need to make it as gentle as possible.

A lot of people discovering the SDK come from the Ethereum community and may not even know what a state machine is. Or they may know it, but they may not be accustomed to thinking of a blockchain as a replicated, deterministic state-machine. What is obvious to us is NOT to most people getting started with the SDK.

We will have more advanced and rigorous docs later. The intro docs are high-level and must be as easy to understand as possible.

rigelrozanski · 2019-04-26T01:14:12Z

docs/cosmos-hub/upgrade-node.md

+gaiad unsafe-reset-all
+```
+
+Your node is now in a pristine state while keeping the original `priv_validator.json` and `config.toml`. If you had any sentry nodes or full nodes setup before, your node will still try to connect to them, but may fail if they haven't also been upgraded.


is pristine the best word here?

what do you suggest?

rigelrozanski · 2019-04-26T01:15:15Z

docs/cosmos-hub/upgrade-node.md

+mv new_genesis.json genesis.json
+```
+
+At this point, you might want to run a script to update the exported genesis into a genesis that is compatible with your new version. For example, the attributes of a the `Account` type changed, a script should query encoded account from the account store, unmarshall them, update their type, re-marhsall and re-store them. You can find an example of such script [here](https://github.com/cosmos/cosmos-sdk/blob/develop/contrib/export/v0.33.x-to-v0.34.0.py).


re-marhsall -> re-marshal

will update

gamarin2 added 2 commits April 23, 2019 16:11

docs update

8e92106

few nits

4742e40

gamarin2 requested review from cwgoes, ebuchman, rigelrozanski and zramsay as code owners April 23, 2019 14:15

gamarin2 changed the title ~~Gamarin/docs update~~ Docs update Apr 23, 2019

alexanderbez added T:Docs Changes and features related to documentation. ready-for-review labels Apr 23, 2019

jackzampolin reviewed Apr 23, 2019

View reviewed changes

alexanderbez reviewed Apr 23, 2019

View reviewed changes

fedekunze reviewed Apr 23, 2019

View reviewed changes

fedekunze and others added 4 commits April 23, 2019 19:17

Apply suggestions from code review

0a51d56

Co-Authored-By: gamarin2 <gautier@tendermint.com>

code review

5d10a6f

fix conflicts

d48436f

udate upgrade node doc

dcdd597

jackzampolin reviewed Apr 23, 2019

View reviewed changes

jackzampolin approved these changes Apr 23, 2019

View reviewed changes

fedekunze approved these changes Apr 25, 2019

View reviewed changes

zramsay approved these changes Apr 25, 2019

View reviewed changes

ebuchman approved these changes Apr 25, 2019

View reviewed changes

ebuchman merged commit bfb2b49 into master Apr 25, 2019

ebuchman deleted the gamarin/docs-update branch April 25, 2019 21:11

rigelrozanski reviewed Apr 26, 2019

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs update #4176

Docs update #4176

gamarin2 commented Apr 23, 2019

codecov bot commented Apr 23, 2019 •

edited

Loading

codecov bot commented Apr 23, 2019

alexanderbez commented Apr 23, 2019

gamarin2 commented Apr 23, 2019

jackzampolin left a comment

jackzampolin Apr 23, 2019

jackzampolin Apr 23, 2019

jackzampolin Apr 23, 2019

gamarin2 Apr 23, 2019

alexanderbez Apr 23, 2019

gamarin2 Apr 23, 2019

jackzampolin Apr 23, 2019

alexanderbez Apr 24, 2019

fedekunze Apr 23, 2019

fedekunze Apr 23, 2019

jackzampolin Apr 23, 2019

gamarin2 Apr 24, 2019

rigelrozanski left a comment

rigelrozanski Apr 26, 2019

gamarin2 Apr 26, 2019

rigelrozanski Apr 26, 2019

gamarin2 Apr 26, 2019

rigelrozanski Apr 26, 2019

gamarin2 Apr 26, 2019

rigelrozanski Apr 26, 2019

gamarin2 Apr 26, 2019

rigelrozanski Apr 26, 2019

gamarin2 Apr 26, 2019

rigelrozanski Apr 26, 2019

gamarin2 Apr 26, 2019

	If the version <new_version> you are upgrading to is not breaking from the previous one, you should not reset the data. If it is not breaking, you can skip to [Restart](#restart)
	If the new version you are upgrading to doesn't have any braking changes, you can skip to the [Restart](#restart) section.


		Here are the most important messages of the ABCI:

		- `CheckTx`: When a transaction is received by Tendermint Core, it is passed to the application to check if a few basic requirements are met. `CheckTx` is used to protect the mempool of full-nodes against spam. A special handler called the "Ante Handler" is used to execute a series of validation steps such as checking for sufficient fees and validating the signatures. If the check is valid, the transaction is added to the [mempool](https://tendermint.com/docs/spec/reactors/mempool/functionality.html#mempool-functionality) and relayed to peer nodes. Note that transactions are not processed (i.e. no modification of the state occurs) with `CheckTx` since they have not been included in a block yet.


		The main part of a Cosmos SDK application is a blockchain daemon that is run by each node in the network locally. If less than one third of the validator set is byzantine (i.e. malicious), then each node should obtain the same result when querying the state at the same time.

		## ABCI

Docs update #4176

Docs update #4176

Conversation

gamarin2 commented Apr 23, 2019

codecov bot commented Apr 23, 2019 • edited Loading

Codecov Report

codecov bot commented Apr 23, 2019

Codecov Report

alexanderbez commented Apr 23, 2019

gamarin2 commented Apr 23, 2019

jackzampolin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rigelrozanski left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Apr 23, 2019 •

edited

Loading