diff --git a/docs/conf.py b/docs/conf.py index 3af51ef959..73a0220fd5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -47,7 +47,7 @@ master_doc = 'index' # General information about the project. project = u'Cosmos-SDK' -copyright = u'2017, The Authors' +copyright = u'2018, The Authors' author = u'The Authors' # The version info for the project you're documenting, acts as replacement for @@ -69,7 +69,7 @@ language = None # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'old'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' diff --git a/docs/index.rst b/docs/index.rst index 80d5dd48d5..66e3f7cb8c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,14 +14,13 @@ Welcome to the Cosmos SDK! SDK --- -.. One maxdepth for now - .. toctree:: :maxdepth: 1 - sdk/overview.rst sdk/install.rst - sdk/glossary.rst + sdk/key-management.rst +.. sdk/overview.rst # needs to be updated +.. old/glossary.rst # not completely up to date but has good content .. Basecoin .. -------- @@ -29,19 +28,17 @@ SDK .. .. toctree:: :maxdepth: 2 -.. basecoin/basics.rst -.. basecoin/extensions.rst +.. old/basecoin/basics.rst # has a decent getting-start tutorial that's relatively up to date, should be consolidated with the other getting started doc -Extensions ----------- +.. Extensions +.. ---------- -Replay Protection -~~~~~~~~~~~~~~~~~ +.. old/basecoin/extensions.rst # probably not worth salvaging -.. toctree:: - :maxdepth: 1 +.. Replay Protection +.. ~~~~~~~~~~~~~~~~~ - x/replay-protection.rst +.. old/replay-protection.rst # not sure if worth salvaging Staking @@ -50,17 +47,13 @@ Staking .. toctree:: :maxdepth: 1 - staking/intro.rst - staking/key-management.rst - staking/local-testnet.rst - staking/public-testnet.rst + staking/testnet.rst +.. staking/intro.rst +.. staking/key-management.rst +.. staking/local-testnet.rst +.. staking/public-testnet.rst -Extras ------- +.. IBC +.. --- -.. One maxdepth for now - -.. toctree:: - :maxdepth: 1 - - ibc.rst +.. old/ibc.rst # needs to be updated diff --git a/docs/basecoin/basics.rst b/docs/old/basecoin/basics.rst similarity index 100% rename from docs/basecoin/basics.rst rename to docs/old/basecoin/basics.rst diff --git a/docs/basecoin/extensions.rst b/docs/old/basecoin/extensions.rst similarity index 100% rename from docs/basecoin/extensions.rst rename to docs/old/basecoin/extensions.rst diff --git a/docs/sdk/glossary.rst b/docs/old/glossary.rst similarity index 100% rename from docs/sdk/glossary.rst rename to docs/old/glossary.rst diff --git a/docs/ibc.rst b/docs/old/ibc.rst similarity index 100% rename from docs/ibc.rst rename to docs/old/ibc.rst diff --git a/docs/x/replay-protection.rst b/docs/old/replay-protection.rst similarity index 100% rename from docs/x/replay-protection.rst rename to docs/old/replay-protection.rst diff --git a/docs/staking/key-management.rst b/docs/old/staking/key-management.rst similarity index 100% rename from docs/staking/key-management.rst rename to docs/old/staking/key-management.rst diff --git a/docs/staking/local-testnet.rst b/docs/old/staking/local-testnet.rst similarity index 100% rename from docs/staking/local-testnet.rst rename to docs/old/staking/local-testnet.rst diff --git a/docs/staking/public-testnet.rst b/docs/old/staking/public-testnet.rst similarity index 100% rename from docs/staking/public-testnet.rst rename to docs/old/staking/public-testnet.rst diff --git a/docs/apps.md b/docs/sdk/apps.md similarity index 97% rename from docs/apps.md rename to docs/sdk/apps.md index 29fb905cba..01210cb662 100644 --- a/docs/apps.md +++ b/docs/sdk/apps.md @@ -15,7 +15,7 @@ while defining as little about that state machine as possible (staying true to t BaseApp requires stores to be mounted via capabilities keys - handlers can only access stores they're given the key for. The BaseApp ensures all stores are properly loaded, cached, and committed. One mounted store is considered the "main" - it holds the latest block header, from which we can find and load the -most recent state. +most recent state ([TODO](https://github.com/cosmos/cosmos-sdk/issues/522)). BaseApp distinguishes between two handler types - the `AnteHandler` and the `MsgHandler`. The former is a global validity check (checking nonces, sigs and sufficient balances to pay fees, diff --git a/docs/sdk/install.rst b/docs/sdk/install.rst index c5a82475a3..03b219cb5b 100644 --- a/docs/sdk/install.rst +++ b/docs/sdk/install.rst @@ -1,16 +1,12 @@ Install ======= -If you aren't used to compile go programs and just want the released -version of the code, please head to our -`downloads `__ page to get a -pre-compiled binary for your platform. - -Usually, Cosmos SDK can be installed like a normal Go program: +Cosmos SDK can be installed to +``$GOPATH/src/github.com/cosmos/cosmos-sdk`` like a normal Go program: :: - go get -u github.com/cosmos/cosmos-sdk + go get github.com/cosmos/cosmos-sdk If the dependencies have been updated with breaking changes, or if another branch is required, ``dep`` is used for dependency management. @@ -20,16 +16,33 @@ repo, the correct way to install is: :: cd $GOPATH/src/github.com/cosmos/cosmos-sdk - git pull origin master - make all + make get_vendor_deps + make install + make install_examples -This will create the ``basecoin`` binary in ``$GOPATH/bin``. -``make all`` implies ``make get_vendor_deps`` and uses ``dep`` to -install the correct version of all dependencies. It also tests the code, -including some cli tests to make sure your binary behaves properly. +This will install ``gaiad`` and ``gaiacli`` and four example binaries: +``basecoind``, ``basecli``, ``democoind``, and ``democli``. -If you need another branch, make sure to run ``git checkout `` -before ``make all``. And if you switch branches a lot, especially -touching other tendermint repos, you may need to ``make fresh`` -sometimes so dep doesn't get confused with all the branches and -versions lying around. +Verify that everything is OK by running: + +:: + + gaiad version + +you should see: + +:: + + 0.15.0-rc1-9d90c6b + +then with: + +:: + + gaiacli version + +you should see: + +:: + + 0.15.0-rc1-9d90c6b diff --git a/docs/sdk/key-management.rst b/docs/sdk/key-management.rst new file mode 100644 index 0000000000..d2b6577290 --- /dev/null +++ b/docs/sdk/key-management.rst @@ -0,0 +1,18 @@ +Key Management +============== + +Here we cover many aspects of handling keys within the Cosmos SDK framework. + +Pseudo Code +----------- + +Generating an address for an ed25519 public key (in pseudo code): + +:: + + const TypeDistinguisher = HexToBytes("1624de6220") + + // prepend the TypeDistinguisher as Bytes + SerializedBytes = TypeDistinguisher ++ PubKey.asBytes() + + Address = ripemd160(SerializedBytes) diff --git a/docs/staking/intro.rst b/docs/staking/intro.rst index ca1d002f57..68032c5363 100644 --- a/docs/staking/intro.rst +++ b/docs/staking/intro.rst @@ -1,77 +1,205 @@ -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 ``gaiad`` and ``gaiacli`` 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 + gaiad 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/.gaiad/config/priv_validator.json + I[03-30|11:20:13.365] Found genesis file module=main path=/root/.gaiad/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 ``~/.gaiad/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 ``gaiacli`` 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. +:: + + gaiacli 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: + +:: + + gaiacli keys list 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. +:: + + gaiad 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: + +:: + + gaiacli keys add bob + gaiacli 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_state": { + "accounts": [ + { + "address": "1D9B2356CAADF46D3EE3488E3CCE3028B4283DEE", + "coins": [ + { + "denom": "fermion", + "amount": 100000 + } + ] + } + ], + "stake": { + "pool": { + "total_supply": 0, + "bonded_shares": { + "num": 0, + "denom": 1 + }, + "unbonded_shares": { + "num": 0, + "denom": 1 + }, + "bonded_pool": 0, + "unbonded_pool": 0, + "inflation_last_time": 0, + "inflation": { + "num": 7, + "denom": 100 + } + }, + "params": { + "inflation_rate_change": { + "num": 13, + "denom": 100 + }, + "inflation_max": { + "num": 20, + "denom": 100 + }, + "inflation_min": { + "num": 7, + "denom": 100 + }, + "goal_bonded": { + "num": 67, + "denom": 100 + }, + "max_validators": 100, + "bond_denom": "fermion" + } + } + }, + "validators": [ + { + "pub_key": { + "type": "AC26791624DE60", + "value": "rgpc/ctVld6RpSfwN5yxGBF17R1PwMTdhQ9gKVUZp5g=" + }, + "power": 10, + "name": "" + } + ], + "app_hash": "", + "genesis_time": "0001-01-01T00:00:00Z", + "chain_id": "test-chain-Uv1EVU" + } + + +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: + +:: + + gaiad 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 + gaiacli send --amount=1000mycoin --sequence=0 --name=alice --to=5A35E4CC7B7DC0A5CB49CEA91763213A9AE92AD6 --chain-id=test-chain-Uv1EVU -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 ``--sequence`` flag is to be incremented for each transaction, the ``--name`` flag is the sender (alice), and the ``--to`` flag takes ``bob``'s address. You'll see something like: :: @@ -101,19 +229,25 @@ where the ``--sequence`` flag is to be incremented for each transaction, the ``- "height": 2963 } -Check out ``bob``'s account, which should now have 992 fermions: +TODO: check the above with current actual output. + +Check out ``bob``'s account, which should now have 1000 mycoin: :: - gaia client query account 5A35E4CC7B7DC0A5CB49CEA91763213A9AE92AD6 + gaiacli account 5A35E4CC7B7DC0A5CB49CEA91763213A9AE92AD6 Adding a Second Validator ------------------------- +**This section is wrong/needs to be updated** + 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 +264,7 @@ Now ``bob`` can declare candidacy to that pubkey: :: - gaia client tx declare-candidacy --amount=10fermion --name=bob --pubkey= --moniker=bobby + gaiacli declare-candidacy --amount=10mycoin --name=bob --pubkey= --moniker=bobby with an output like: @@ -147,11 +281,11 @@ with an output like: } -We should see ``bob``'s account balance decrease by 10 fermions: +We should see ``bob``'s account balance decrease by 10 mycoin: :: - gaia client query account 5D93A6059B6592833CBC8FA3DA90EE0382198985 + gaiacli account 5D93A6059B6592833CBC8FA3DA90EE0382198985 To confirm for certain the new validator is active, ask the tendermint node: @@ -163,7 +297,7 @@ If you now kill either node, blocks will stop streaming in, because there aren't enough validators online. Turn it back on and they will start streaming again. -Now that ``bob`` has declared candidacy, which essentially bonded 10 fermions and made him a validator, we're going to get ``charlie`` to delegate some coins to ``bob``. +Now that ``bob`` has declared candidacy, which essentially bonded 10 mycoin and made him a validator, we're going to get ``charlie`` to delegate some coins to ``bob``. Delegating ---------- @@ -172,13 +306,13 @@ First let's have ``alice`` send some coins to ``charlie``: :: - gaia client tx send --amount=1000fermion --sequence=2 --name=alice --to=48F74F48281C89E5E4BE9092F735EA519768E8EF + gaiacli tx --amount=1000mycoin --sequence=2 --name=alice --to=48F74F48281C89E5E4BE9092F735EA519768E8EF -Then ``charlie`` will delegate some fermions to ``bob``: +Then ``charlie`` will delegate some mycoin to ``bob``: :: - gaia client tx delegate --amount=10fermion --name=charlie --pubkey= + gaiacli tx delegate --amount=10mycoin --name=charlie --pubkey= You'll see output like: @@ -194,13 +328,13 @@ You'll see output like: "height": 51585 } -And that's it. You can query ``charlie``'s account to see the decrease in fermions. +And that's it. You can query ``charlie``'s account to see the decrease in mycoin. To get more information about the candidate, try: :: - gaia client query candidate --pubkey= + gaiacli query candidate --pubkey= and you'll see output similar to: @@ -233,7 +367,7 @@ It's also possible the query the delegator's bond like so: :: - gaia client query delegator-bond --delegator-address 48F74F48281C89E5E4BE9092F735EA519768E8EF --pubkey 52D6FCD8C92A97F7CCB01205ADF310A18411EA8FDCC10E65BF2FCDB05AD1689B + gaiacli query delegator-bond --delegator-address 48F74F48281C89E5E4BE9092F735EA519768E8EF --pubkey 52D6FCD8C92A97F7CCB01205ADF310A18411EA8FDCC10E65BF2FCDB05AD1689B with an output similar to: @@ -262,9 +396,7 @@ your VotingPower reduce and your account balance increase. :: - gaia client tx unbond --amount=5fermion --name=charlie --pubkey= - gaia client query account 48F74F48281C89E5E4BE9092F735EA519768E8EF + gaiacli unbond --amount=5mycoin --name=charlie --pubkey= + gaiacli account 48F74F48281C89E5E4BE9092F735EA519768E8EF -See the bond decrease with ``gaia client query delegator-bond`` like above. - -That concludes an overview of the ``gaia`` tooling for local testing. +See the bond decrease with ``gaiacli query delegator-bond`` like above. diff --git a/docs/staking/testnet.rst b/docs/staking/testnet.rst new file mode 100644 index 0000000000..484ec3b5d6 --- /dev/null +++ b/docs/staking/testnet.rst @@ -0,0 +1,193 @@ +Testnet Setup +============= + +See the `installation guide <../sdk/install.html>`__ for details on installation. + +Here is a quick example to get you off your feet: + +First, generate a new key with a name, and save the address: + +:: + + MYNAME= + gaiacli keys new $MYNAME + gaiacli keys list + MYADDR= + + +Now initialize a gaia chain: + +:: + + gaiad init --home=$HOME/.gaiad1 + +you should see seed phrase for genesis account in the output & config & data folder in the home directory. + +In the config folder, there will be the following files: ``config.toml``, ``genesis.json``, ``node_key.json``, and ``priv_validator.json``. + +The genesis file should look like this: + +:: + + { + "genesis_time": "0001-01-01T00:00:00Z", + "chain_id": "test-chain-0TRiTa", + "validators": [ + { + "pub_key": { + "type": "AC26791624DE60", + "value": "" + }, + "power": 10, + "name": "" + } + ], + "app_hash": "", + "app_state": { + "accounts": [ + { + "address": "", + "coins": [ + { + "denom": "steak", + "amount": 9007199254740992 + } + ] + } + ] + } + } + +**Note:** We need to change the denomination of token from default to ``steak`` in the genesis file. + +Then, recover the genesis account with ``gaiacli``: + +:: + + gaiacli keys add --recover + +By now, you have set up the first node. This is great! + +We can add a second node on our local machine by initiating a node in a new directory, and copying in the ``genesis.json``: + +:: + + gaiad init --home=$HOME/.gaiad2 + +and replace the ``genesis.json`` and ``config.toml`` files: + +:: + + cp $HOME/.gaiad/config/genesis.json $HOME/.gaiad2/config + cp $HOME/.gaiad/config/config.toml $HOME/.gaiad2/config + +then, get the node id of first node: + +:: + + gaiad show_node_id --home=$HOME/.gaiad1 + +We need to also modify $HOME/.gaiad2/config.toml to set new seeds and ports. It should look like: + +:: + + proxy_app = "tcp://127.0.0.1:46668" + moniker = "anonymous" + fast_sync = true + db_backend = "leveldb" + log_level = "state:info,*:error" + + [rpc] + laddr = "tcp://0.0.0.0:46667" + + [p2p] + laddr = "tcp://0.0.0.0:46666" + persistent_peers = "@0.0.0.0:46656" + + +Great, now that we've initialized the chains, we can start both nodes in the background: + +:: + + gaiad start --home=$HOME/.gaiad1 &> gaia1.log & + NODE1_PID=$! + gaia start --home=$HOME/.gaiad2 &> gaia2.log & + NODE2_PID=$! + +Note that we save the PID so we can later kill the processes. You can peak at your logs with ``tail gaia1.log``, or follow them for a bit with ``tail -f gaia1.log``. + +Nice. We can also lookup the validator set: + +:: + + gaiacli validatorset + +There is only **one** validator now. Let's add another one! + +First, we need to create a new account: + +:: + + gaiacli keys new + +Check that we now have two accounts: + +:: + + gaiacli keys list + +Then, we try to transfer some ``steak`` to another account: + +:: + + gaiacli send --amount=1000steak --to=$MYADDR2 --name=$NAME --chain-id= --node=tcp://localhost:46657 --sequence=0 + +**Note:** We need to be careful with the ``chain-id`` and ``sequence`` + +Check the balance & sequence with: + +:: + + gaiacli account $MYADDR + +We can see the balance of ``$MYADDR2`` is 1000 now. + +Finally, let's bond the validator in ``$HOME/gaiad2``. Get the pubkey first: + +:: + + cat $HOME/.gaiad2/config/priv_validator.json | jq .pub_key.value + +Go to `this website `__ to change pubkey from base64 to Hex. + +Ok, now we can bond some coins to that pubkey: + +:: + + gaiacli bond --stake=1steak --validator= --sequence=0 --chain-id= --name=test + +Nice. We can see there are now two validators: + +:: + + gaiacli validatorset + +Check the balance of ``$MYADDR2`` to see the difference: it has 1 less ``steak``! + +:: + + gaiacli account $MYADDR2 + +To confirm for certain the new validator is active, check tendermint: + +:: + + curl localhost:46657/validators + +Finally, to relinquish all your power, unbond some coins. You should see your VotingPower reduce and your account balance increase. + +:: + + gaiacli unbond --sequence=# --chain-id= --name=test + +That's it!