certusone
/
cosmos-sdk
mirror of https://github.com/certusone/cosmos-sdk.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

more dumb rebase fixes

This commit is contained in:
Zach Ramsay 2018-02-03 00:09:08 +00:00 committed by Ethan Buchman
parent 860cf229b0
commit 02e66992be
7 changed files with 678 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
docs/Makefile Normal file
View File

@ -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)

170
docs/conf.py Normal file
View File

@ -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'),
]

36
docs/make.bat Normal file
View File

@ -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

35
docs/sdk/install.rst Normal file
View File

@ -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 <https://tendermint.com/download>`__ 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 <branch>``
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.

270
docs/staking/intro.rst Normal file
View File

@ -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 <https://github.com/cosmos/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=<pub_key data> --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=<pub_key data>
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=<pub_key data>
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=<pub_key data>
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.

83
docs/staking/local-testnet.rst Normal file
View File

@ -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.

64
docs/staking/public-testnet.rst Normal file
View File

@ -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 <http://www.cosmosvalidators.com/>`__ 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``.