From 02e66992be29c5c3a9b74121cb2a2c3ed3ecdf5b Mon Sep 17 00:00:00 2001 From: Zach Ramsay Date: Sat, 3 Feb 2018 00:09:08 +0000 Subject: [PATCH] more dumb rebase fixes --- docs/Makefile | 20 +++ docs/conf.py | 170 ++++++++++++++++++++ docs/make.bat | 36 +++++ docs/sdk/install.rst | 35 +++++ docs/staking/intro.rst | 270 ++++++++++++++++++++++++++++++++ docs/staking/local-testnet.rst | 83 ++++++++++ docs/staking/public-testnet.rst | 64 ++++++++ 7 files changed, 678 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/make.bat create mode 100644 docs/sdk/install.rst create mode 100644 docs/staking/intro.rst create mode 100644 docs/staking/local-testnet.rst create mode 100644 docs/staking/public-testnet.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000..f4bccf3bd3 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = python -msphinx +SPHINXPROJ = Cosmos-SDK +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000000..3af51ef959 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,170 @@ +# -*- coding: utf-8 -*- +# +# Cosmos-SDK documentation build configuration file, created by +# sphinx-quickstart on Fri Sep 1 21:37:02 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + +import sphinx_rtd_theme + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Cosmos-SDK' +copyright = u'2017, The Authors' +author = u'The Authors' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = u'' +# The full version, including alpha/beta/rc tags. +release = u'' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +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'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' +# html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# This is required for the alabaster theme +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'relations.html', # needs 'show_related': True theme option to display + 'searchbox.html', + 'donate.html', + ] +} + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Cosmos-SDKdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'Cosmos-SDK.tex', u'Cosmos-SDK Documentation', + u'The Authors', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'cosmos-sdk', u'Cosmos-SDK Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'Cosmos-SDK', u'Cosmos-SDK Documentation', + author, 'Cosmos-SDK', 'One line description of project.', + 'Miscellaneous'), +] diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000000..916e57ee79 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,36 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=python -msphinx +) +set SOURCEDIR=. +set BUILDDIR=_build +set SPHINXPROJ=Cosmos-SDK + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The Sphinx module was not found. Make sure you have Sphinx installed, + echo.then set the SPHINXBUILD environment variable to point to the full + echo.path of the 'sphinx-build' executable. Alternatively you may add the + echo.Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/docs/sdk/install.rst b/docs/sdk/install.rst new file mode 100644 index 0000000000..4857f63e79 --- /dev/null +++ b/docs/sdk/install.rst @@ -0,0 +1,35 @@ +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: + +:: + + go get -u github.com/cosmos/cosmos-sdk + +If the dependencies have been updated with breaking changes, or if +another branch is required, ``glide`` is used for dependency management. +Thus, assuming you've already run ``go get`` or otherwise cloned the +repo, the correct way to install is: + +:: + + cd $GOPATH/src/github.com/cosmos/cosmos-sdk + git pull origin master + make all + +This will create the ``basecoin`` binary in ``$GOPATH/bin``. +``make all`` implies ``make get_vendor_deps`` and uses ``glide`` to +install the correct version of all dependencies. It also tests the code, +including some cli tests to make sure your binary behaves properly. + +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 glide doesn't get confused with all the branches and +versions lying around. diff --git a/docs/staking/intro.rst b/docs/staking/intro.rst new file mode 100644 index 0000000000..786c9c44db --- /dev/null +++ b/docs/staking/intro.rst @@ -0,0 +1,270 @@ +Using Gaia +========== + +This project is a demonstration of the Cosmos Hub with staking functionality; it is +designed to get validator acquianted with staking concepts and procedure. + +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. + +Install +------- + +The ``gaia`` tooling is an extension of the Cosmos-SDK; to install: + +:: + + go get github.com/cosmos/gaia + cd $GOPATH/src/github.com/cosmos/gaia + make get_vendor_deps + make install + +It has three primary commands: + +:: + + 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 + +and a handful of flags that are highlighted only as necessary. + +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 `__. + +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. + +Generating Keys +--------------- + +Review the `key management tutorial <../sdk/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. + +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. + +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. + +Sending Tokens +-------------- + +We'll have ``alice`` who is currently quite rich, send some ``fermions`` to ``bob``: + +:: + + gaia client tx send --amount=1000fermion --sequence=1 --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: + +:: + + Please enter passphrase for alice: + { + "check_tx": { + "gas": 30 + }, + "deliver_tx": { + "tags": [ + { + "key": "height", + "value_type": 1, + "value_int": 2963 + }, + { + "key": "coin.sender", + "value_string": "5D93A6059B6592833CBC8FA3DA90EE0382198985" + }, + { + "key": "coin.receiver", + "value_string": "5A35E4CC7B7DC0A5CB49CEA91763213A9AE92AD6" + } + ] + }, + "hash": "423BD7EA3C4B36AF8AFCCA381C0771F8A698BA77", + "height": 2963 + } + +Check out ``bob``'s account, which should now have 992 fermions: + +:: + + gaia client query account 5A35E4CC7B7DC0A5CB49CEA91763213A9AE92AD6 + +Adding a Second Validator +------------------------- + +Next, let's add the second node as a validator. + +First, we need the pub_key data: + +:: + + cat $HOME/.gaia2/priv_validator.json + +the first part will look like: + +:: + + {"address":"7B78527942C831E16907F10C3263D5ED933F7E99","pub_key":{"type":"ed25519","data":"96864CE7085B2E342B0F96F2E92B54B18C6CC700186238810D5AA7DFDAFDD3B2"}, + +and you want the ``pub_key`` ``data`` that starts with ``96864CE``. + +Now ``bob`` can declare candidacy to that pubkey: + +:: + + gaia client tx declare-candidacy --amount=10fermion --name=bob --pubkey= --moniker=bobby + +with an output like: + +:: + + Please enter passphrase for bob: + { + "check_tx": { + "gas": 30 + }, + "deliver_tx": {}, + "hash": "2A2A61FFBA1D7A59138E0068C82CC830E5103799", + "height": 4075 + } + + +We should see ``bob``'s account balance decrease by 10 fermions: + +:: + + gaia client query account 5D93A6059B6592833CBC8FA3DA90EE0382198985 + +To confirm for certain the new validator is active, ask the tendermint node: + +:: + + curl localhost:46657/validators + +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``. + +Delegating +---------- + +First let's have ``alice`` send some coins to ``charlie``: + +:: + + gaia client tx send --amount=1000fermion --sequence=2 --name=alice --to=48F74F48281C89E5E4BE9092F735EA519768E8EF + +Then ``charlie`` will delegate some fermions to ``bob``: + +:: + + gaia client tx delegate --amount=10fermion --name=charlie --pubkey= + +You'll see output like: + +:: + + Please enter passphrase for charlie: + { + "check_tx": { + "gas": 30 + }, + "deliver_tx": {}, + "hash": "C3443BA30FCCC1F6E3A3D6AAAEE885244F8554F0", + "height": 51585 + } + +And that's it. You can query ``charlie``'s account to see the decrease in fermions. + +To get more information about the candidate, try: + +:: + + gaia client query candidate --pubkey= + +and you'll see output similar to: + +:: + + { + "height": 51899, + "data": { + "pub_key": { + "type": "ed25519", + "data": "52D6FCD8C92A97F7CCB01205ADF310A18411EA8FDCC10E65BF2FCDB05AD1689B" + }, + "owner": { + "chain": "", + "app": "sigs", + "addr": "5A35E4CC7B7DC0A5CB49CEA91763213A9AE92AD6" + }, + "shares": 20, + "voting_power": 20, + "description": { + "moniker": "bobby", + "identity": "", + "website": "", + "details": "" + } + } + } + +It's also possible the query the delegator's bond like so: + +:: + + gaia client query delegator-bond --delegator-address 48F74F48281C89E5E4BE9092F735EA519768E8EF --pubkey 52D6FCD8C92A97F7CCB01205ADF310A18411EA8FDCC10E65BF2FCDB05AD1689B + +with an output similar to: + +:: + + { + "height": 325782, + "data": { + "PubKey": { + "type": "ed25519", + "data": "52D6FCD8C92A97F7CCB01205ADF310A18411EA8FDCC10E65BF2FCDB05AD1689B" + }, + "Shares": 20 + } + } + + +where the ``--delegator-address`` is ``charlie``'s address and the ``-pubkey`` is the same as we've been using. + + +Unbonding +--------- + +Finally, to relinquish your voting power, unbond some coins. You should see +your VotingPower reduce and your account balance increase. + +:: + + gaia client tx unbond --amount=5fermion --name=charlie --pubkey= + gaia client query 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. diff --git a/docs/staking/local-testnet.rst b/docs/staking/local-testnet.rst new file mode 100644 index 0000000000..e3f69bded1 --- /dev/null +++ b/docs/staking/local-testnet.rst @@ -0,0 +1,83 @@ +Local Testnet +============= + +This tutorial demonstrates the basics of setting up a gaia +testnet locally. + +If you haven't already made a key, make one now: + +:: + + gaia client keys new alice + +otherwise, use an existing key. + +Initialize The Chain +-------------------- + +Now initialize a gaia chain, using ``alice``'s address: + +:: + + gaia node init 5D93A6059B6592833CBC8FA3DA90EE0382198985 --home=$HOME/.gaia1 --chain-id=gaia-test + +This will create all the files necessary to run a single node chain in +``$HOME/.gaia1``: a ``priv_validator.json`` file with the validators +private key, and a ``genesis.json`` file with the list of validators and +accounts. + +We'll add a second node on our local machine by initiating a node in a +new directory, with the same address, and copying in the genesis: + +:: + + gaia node init 5D93A6059B6592833CBC8FA3DA90EE0382198985 --home=$HOME/.gaia2 --chain-id=gaia-test + cp $HOME/.gaia1/genesis.json $HOME/.gaia2/genesis.json + +We also need to modify ``$HOME/.gaia2/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" + seeds = "0.0.0.0:46656" + +Start Nodes +----------- + +Now that we've initialized the chains, we can start both nodes: + +NOTE: each command below must be started in seperate terminal windows. Alternatively, to run this testnet across multiple machines, you'd replace the ``seeds = "0.0.0.0"`` in ``~/.gaia2.config.toml`` with the IP of the first node, and could skip the modifications we made to the config file above because port conflicts would be avoided. + +:: + + gaia node start --home=$HOME/.gaia1 + gaia node start --home=$HOME/.gaia2 + +Now we can initialize a client for the first node, and look up our +account: + +:: + + gaia client init --chain-id=gaia-test --node=tcp://localhost:46657 + gaia client query account 5D93A6059B6592833CBC8FA3DA90EE0382198985 + +To see what tendermint considers the validator set is, use: + +:: + + curl localhost:46657/validators + +and compare the information in this file: ``~/.gaia1/priv_validator.json``. The ``address`` and ``pub_key`` fields should match. + +To add a second validator on your testnet, you'll need to bond some tokens be declaring candidacy. diff --git a/docs/staking/public-testnet.rst b/docs/staking/public-testnet.rst new file mode 100644 index 0000000000..1681095c70 --- /dev/null +++ b/docs/staking/public-testnet.rst @@ -0,0 +1,64 @@ +Public Testnets +=============== + +Here we'll cover the basics of joining a public testnet. These testnets +come and go with various names are we release new versions of tendermint +core. This tutorial covers joining the ``gaia-1`` testnet. To join +other testnets, choose different initialization files, described below. + +Get Tokens +---------- + +If you haven't already `created a key <../sdk/key-management.html>`__, +do so now. Copy your key's address and enter it into +`this utility `__ which will send you +some ``fermion`` testnet tokens. + +Get Files +--------- + +Now, to sync with the testnet, we need the genesis file and seeds. The +easiest way to get them is to clone and navigate to the tendermint +testnet repo: + +:: + + git clone https://github.com/tendermint/testnets ~/testnets + cd ~/testnets/gaia-1/gaia + +NOTE: to join a different testnet, change the ``gaia-1/gaia`` filepath +to another directory with testnet inititalization files *and* an +active testnet. + +Start Node +---------- + +Now we can start a new node:it may take awhile to sync with the +existing testnet. + +:: + + gaia node start --home=$HOME/testnets/gaia-1/gaia + +Once blocks slow down to about one per second, you're all caught up. + +The ``gaia node start`` command will automaticaly generate a validator +private key found in ``~/testnets/gaia-1/gaia/priv_validator.json``. + +Finally, let's initialize the gaia client to interact with the testnet: + +:: + + gaia client init --chain-id=gaia-1 --node=tcp://localhost:46657 + +and check our balance: + +:: + + gaia client query account $MYADDR + +Where ``$MYADDR`` is the address originally generated by ``gaia keys new bob``. + +You are now ready to declare candidacy or delegate some fermions. See the +`staking module overview <./staking-module.html>`__ for more information +on using the ``gaia client``.