Cosmos-sdk: gaia ux and guide improvements proposal

[jbibla]

hello SDK folks!

i have been investigating the gaia user experience and thinking through some of the issues with the testnet / validator documentation. i'd like to share my suggestions for how to improve the ux here.

currently, these are the steps a user has to go through while also avoiding certain sections that don't really belong in the "how to setup a validator on a testnet" guide IMO. let's work on having more guides for specific workflows as opposed to trying to include too much in the same readmes.

current steps:
1. install go
2. set gopath
3. clone sdk, make cmd x 3
4. clone testnets repo
5. move genesis file
6. manually edit config.toml for seeds
7. gaiad init
8. gaiad start
9. gaiacli keys add <your_account_name>
10. find the validator pubkey
11. find some steak (riot chat / faucet)
12. run the command to become a validator 

as an interim improvement, if possible, i'd propose the following changes (some of which has been addressed in @nylira's PR #1212):

steps:
1. user runs a bash script to take care of steps 1-6 (4 is pull/1198, 5 is #1219)
2. gaiad start
3. gaiacli keys add <your_account_name>
4. find some steak (faucet)
5. gaiacli stake <validator_address> <number_of_steaks>

main changes:
- remove wget
- don't make the user gaiad init
- standardize keys, account, address, pubkey
- remove sequence
- remove send section
- reduce number of flags required by the user, instead rely more on defaults
- remove delegate section
- describe what the user is doing at every step and why

if possible, i'd propose a workflow like this as something to aim for for mainnet:

1. docker run cosmos 
2. cosmos fundraiser (enter fundraiser seed on new line)
3. cosmos stake <validator_address> <number_of_atoms> 

- we'll need to alert the user that they understand they are about to stake their atoms and ideally get them to confirm
- use the default account information unless specified
- might be simpler to treat stake as the command and not to distinguish between self staking and staking to others

✌️

looking forward to the feedback!

thanks to @keppel @ebuchman and @zramsay for talking these things through with me and answering my questions

[cwgoes]

Thanks! Definitely in favor of making the testnet experience more seamless. A few notes/questions:

1. Is Docker a dependency we want to introduce into our user flow? It's easy if you already have it installed, but possibly more difficult than Go otherwise.
2. Why is the user entering their fundraiser seed? I don't think we want them to do that on a testnet (too easy to copy into logs by accident) - if we want to test the recover-from-seed process, we could do that with fake seeds.
3. The user will need to choose which testnet they want to join - at various times, zero to multiple may be "up" - if we include the testnets in the SDK repository (planned I think), we could prompt the user to select from a list of options.
4. I'm not quite sure what you mean by "default account information" - that we should generate an account automatically for the user? If they want to password-protect their account or use a Ledger, I don't think that's possible.

I really like the idea of an interactive setup described in https://github.com/cosmos/cosmos-sdk/issues/1177, I wonder if we can merge that with this.

[rigelrozanski]

I think there are some inconsistencies. I suspect that some of the documentation is out of date

Within the "current" steps section:

5. move genesis file

you don't need to do this, you can overwrite the genesis file, or you can copy in a special one if you want to but that's not the standard process, you usually generate it in init

6. manually edit config.toml for seeds

I mean you can - I've never done this in modern testnet setup, handled in init

7. gaiad init

Init should probably not get merged into any kind of initialization script as sometimes you want to run custom options in init. Currently you can create a genesis-tx file (json) with an init-subcommand which you then distribute to the other validators, once you have everyones genesis transaction files you run the init command which compiles the genesis, config.toml locally, you also get to choose the chain-id at this point - so yes, for testnet creation we most certainly want this to be outside of the script as far as I can tell (unless we want to update the script for each testnet)

`9. gaiacli keys add

1. find the validator pubkey
2. find some steak (riot chat / faucet)`

Only if you're not included in genesis you need to run these commands. But yes, also maybe we should refer to it as create/retrieve your validator pubkey

---

Next section:

1. user runs a bash script to take care of steps 1-6 (4 is pull/1198, 5 is #1219)

as I mentioned we don't want init in here

5. gaiacli stake <validator_address> <number_of_steaks>

should stick with create-validator command name instead of stake? There are also additional terms we must include as flags - but hopefully we can eliminate many of those once we introduce a term such as gaiacli init which would set the light client and also maybe other terms such as the chain-id

---

Like the idea of the docker setup for the final mainnet

[jbibla]

@cwgoes

1. Is Docker a dependency we want to introduce into our user flow?

that's not a question i can answer. but i think it should be considered.

1. Why is the user entering their fundraiser seed?

i should have clarified this as a proposal for mainnet

1. The user will need to choose which testnet they want to join

i think letting them specify one other than the latest while defaulting to the latest would be a reasonable approach. letting them pick from a list is nice too - but if we are comfortable assuming they want to join the latest - let's default to it

1. default account information

what i mean is that if the user doesn't specify a moniker (which should be fine IMO) we could use the name from their account (maybe?) - but if a user only has one account we could also "know" their address for them so they don't have to copy and paste it in later. the CLI could also ask which account they would like to use and whether or not they would like to use the same account name for their moniker. i suppose this rolls into the interactive CLI conversation.

how can we get this conversation about a more interactive CLI experience going?

[jbibla]

@rigelrozanski

with the stuff around init - as a user trying to install gaia, connect to the testnet, and become a validator - is there anything essential that requires the user to type gaia init? if we provide them with a genesis file and config file - i think they don't have to use gaia init which might be one less step for them to do. very possible i am misunderstanding something fundamental.

Only if you're not included in genesis you need to run these commands. But yes, also maybe we should refer to it as create/retrieve your validator pubkey

is it safe to assume that most people reading the docs are not going to be in the genesis? regardless, we should mention this in the docs. i find it confusing that there are accounts, pubkeys, and addresses. is the validator pubkey different than the account pubkey?

There are also additional terms we must include as flags - but hopefully we can eliminate many of those once we introduce a term such as gaiacli init

cool. what i'm pushing for is just some consideration around what is absolutely necessary for the user to do and what can be handled by the CLI for them. i'd love to learn more about the gaiacli init command.

[rigelrozanski]

if we provide them with a genesis file and config file - i think they don't have to use gaia init which might be one less step for them to do

partially correct - if you do not want to be a validator at all than this seems reasonable - however, if you're looking to become one, the init command is still used to initialize a unique signing key for your validator. I suppose this last piece can happen as a seperate process from init (ideally on an HSM) however those two pieces of functionality are still linked together atm.

---

yeah i suppose there are really two process flows here and the docs should outline that, folks who are attempting to setup a testnet from scratch, and those who are looking to join the existing testnet. The account is effectively the same as an address is it not? There are standard accounts which can contain money, these have a pubkey, and an address derived from this pubkey. As a validator, there are also tendermint signing pubkey's - we are attempting to clear this distinction up with BECH

[jackzampolin]

A lot has changed in this flow with the recent testnets. This also sounds like the answer here is more documentation (and potentially an officially maintained bash script, problematic because platform support) and not really changes to the CLI. What would be ideal here is if we could ship linux distributions that installed systemd unit files so the flow could be apt install gaiad, make some config changes, and then systemctl start gaiad.

The docker stuff for mainnet outlined here is also great, but I think #postlaunch (it would also require regular docker builds and some scripting to support)

I would like to close this issue and spit it into a couple of sub-issues:

• Outline the process for setting up a testnet from scratch: This should be able to be done locally with gaiad testnet and should demonstrate the process clearly enough where the user could move it to multiple VMs.
• Proposal for the outlined docker based workflow for mainnet: an issue to hammer out implementation.

Some of the other issues raised here (bad ux in parts of the CLI and too many flags) are covered by other issues and will be addressed separately

Thoughts on this @cwgoes, @jbibla and @rigelrozanski ?

[jackzampolin]

Closing this issue in favor of #1932 and #1933. Please continue the discussion there!