From f386946d4cae7da38bd06dc13618c42842f6769f Mon Sep 17 00:00:00 2001 From: Zach Ramsay Date: Fri, 30 Mar 2018 11:30:25 -0700 Subject: [PATCH] docs update part 1 --- docs/old/staking/intro.rst | 171 ++++++++++++++++++++++++++++--------- 1 file changed, 132 insertions(+), 39 deletions(-) diff --git a/docs/old/staking/intro.rst b/docs/old/staking/intro.rst index ca1d002f57..a8f4ea078d 100644 --- a/docs/old/staking/intro.rst +++ b/docs/old/staking/intro.rst @@ -1,77 +1,166 @@ -Using Gaia -========== +Using The Staking Module +======================== -This project is a demonstration of the Cosmos Hub with staking functionality; it is -designed to get validator acquianted with staking concepts and procedure. +This project is a demonstration of the Cosmos Hub staking functionality; it is +designed to get validator acquianted with staking concepts and procedures. Potential validators will be declaring their candidacy, after which users can delegate and, if they so wish, unbond. This can be practiced using a local or public testnet. +This example covers initial setup of a two-node testnet between a server in the cloud and a local machine. Begin this tutorial from a cloud machine that you've ``ssh``'d into. + Install ------- -The ``gaia`` tooling is an extension of the Cosmos-SDK; to install: +The ``basecoind`` and ``basecli`` binaries: :: - go get github.com/cosmos/gaia - cd $GOPATH/src/github.com/cosmos/gaia + go get github.com/cosmos/cosmos-sdk + cd $GOPATH/src/github.com/cosmos/cosmos-sdk make get_vendor_deps make install -It has three primary commands: +Let's jump right into it. First, we initialize some default files: :: - Available Commands: - node The Cosmos Network delegation-game blockchain test - rest-server REST client for gaia commands - client Gaia light client - - version Show version info - help Help about any command + basecoind init -and a handful of flags that are highlighted only as necessary. +which will output: -The ``gaia node`` command is a proxt for running a tendermint node. You'll be using -this command to either initialize a new node, or - using existing files - joining -the testnet. +:: -The ``gaia rest-server`` command is used by the `cosmos UI `__. + I[03-30|11:20:13.365] Found private validator module=main path=/root/.basecoind/config/priv_validator.json + I[03-30|11:20:13.365] Found genesis file module=main path=/root/.basecoind/config/genesis.json + Secret phrase to access coins: + citizen hungry tennis noise park hire glory exercise link glow dolphin labor design grit apple abandon -Lastly, the ``gaia client`` command is the workhorse of the staking module. It allows -for sending various transactions and other types of interaction with a running chain. -that you've setup or joined a testnet. +This tell us we have a ``priv_validator.json`` and ``genesis.json`` in the ``~/.basecoind/config`` directory. A ``config.toml`` was also created in the same directory. It is a good idea to get familiar with those files. Write down the seed. -Generating Keys ---------------- +The next thing we'll need to is add the key from ``priv_validator.json`` to the ``basecli`` key manager. For this we need a seed and a password: -Review the `key management tutorial <../key-management.html>`__ and create one key -if you'll be joining the public testnet, and three keys if you'll be trying out a local -testnet. +:: + + basecli keys add alice --recover + +which will give you three prompts: + +:: + + Enter a passphrase for your key: + Repeat the passphrase: + Enter your recovery seed phrase: + +create a password and copy in your seed phrase. The name and address of the key will be output: + +:: + + alice 67997DD03D527EB439B7193F2B813B05B219CC02 + +You can see all available keys with: + +:: + + basecli keys list + +See the `key management tutorial <../key-management.html>`__ for more information on managing keys. Setup Testnet ------------- -The first thing you'll want to do is either `create a local testnet <./local-testnet.html>`__ or -join a `public testnet <./public-testnet.html>`__. Either step is required before proceeding. +Next, we start the daemon (do this in another window): -The rest of this tutorial will assume a local testnet with three participants: ``alice`` will be -the initial validator, ``bob`` will first receives tokens from ``alice`` then declare candidacy -as a validator, and ``charlie`` will bond then unbond to ``bob``. If you're joining the public -testnet, the token amounts will need to be adjusted. +:: + + basecoind start + +and you'll see blocks start streaming through. + +For this example, we're doing the above on a cloud machine. The next steps should be done on your local machine or another server in the cloud, which will join the running testnet then bond/unbond. + +Accounts +-------- + +We have: + +- ``alice`` the initial validator (in the cloud) +- ``bob`` receives tokens from ``alice`` then declares candidacy (from local machine) +- ``charlie`` will bond and unbond to ``bob`` (from local machine) + +Remember that ``alice`` was already created. On your second machine, install the binaries and create two new keys: + +:: + + basecli keys add bob + basecli keys add charlie + +both of which will prompt you for a password. Now we need to copy the ``genesis.json`` and ``config.toml`` from the first machine (with ``alice``) to the second machine. This is a good time to look at both these files. + +The ``genesis.json`` should look something like: + +:: + + { + "app_hash": "", + "app_state": { + "accounts": [ + { + "address": "1FEADCDC8CCB22244769B9CC93C1F6D7489FC5AF", + "coins": [ + { + "denom": "mycoin", + "amount": 9007199254740992 + } + ] + } + ] + }, + "chain_id": "test-chain-EsYka3", + "genesis_time": "0001-01-01T00:00:00Z", + "validators": [ + { + "pub_key": { + "type": "ed25519", + "data": "57B89D41F18FE3FE69250B44693A7D68DE4E03EC563F54C27F9A86CE8B81A4B7" + }, + "power": 10, + "name": "" + } + ] + } + +To notice is that the ``accounts`` field has a an address and a whole bunch of "mycoin". This is ``alice``'s address (todo: dbl check). Under ``validators`` we see the ``pub_key.data`` field, which will match the same field in the ``priv_validator.json`` file. + +The ``config.toml`` is long so let's focus on one field: + +:: + + # Comma separated list of seed nodes to connect to + seeds = "" + +On the ``alice`` cloud machine, we don't need to do anything here. Instead, we need its IP address. After copying this file (and the ``genesis.json`` to your local machine, you'll want to put the IP in the ``seeds = "138.197.161.74"`` field, in this case, we have a made-up IP. For joining testnets with many nodes, you can add more comma-seperated IPs to the list. + + +Now that your files are all setup, it's time to join the network. On your local machine, run: + +:: + + basecoind start + +and your new node will connect to the running validator (``alice``). Sending Tokens -------------- -We'll have ``alice`` who is currently quite rich, send some ``fermions`` to ``bob``: +We'll have ``alice`` send some ``mycoin`` to ``bob``, who has now joined the network: :: - gaia client tx send --amount=1000fermion --sequence=1 --name=alice --to=5A35E4CC7B7DC0A5CB49CEA91763213A9AE92AD6 + basecli send --amount=1000fermion --seq=0 --name=alice --to=5A35E4CC7B7DC0A5CB49CEA91763213A9AE92AD6 -where the ``--sequence`` flag is to be incremented for each transaction, the ``--name`` flag names the sender, and the ``--to`` flag takes ``bob``'s address. You'll see something like: +where the ``--seq`` flag is to be incremented for each transaction, the ``--name`` flag names the sender, and the ``--to`` flag takes ``bob``'s address. You'll see something like: :: @@ -101,11 +190,13 @@ where the ``--sequence`` flag is to be incremented for each transaction, the ``- "height": 2963 } +TODO: check the above with current actual output. + Check out ``bob``'s account, which should now have 992 fermions: :: - gaia client query account 5A35E4CC7B7DC0A5CB49CEA91763213A9AE92AD6 + basecli account 5A35E4CC7B7DC0A5CB49CEA91763213A9AE92AD6 Adding a Second Validator ------------------------- @@ -114,6 +205,8 @@ Next, let's add the second node as a validator. First, we need the pub_key data: +** need to make bob a priv_Val above! + :: cat $HOME/.gaia2/priv_validator.json @@ -130,7 +223,7 @@ Now ``bob`` can declare candidacy to that pubkey: :: - gaia client tx declare-candidacy --amount=10fermion --name=bob --pubkey= --moniker=bobby + basecli declare-candidacy --amount=10mycoin --name=bob --pubkey= --moniker=bobby with an output like: