diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index f4bccf3bd3..0000000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# 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 deleted file mode 100644 index 3f7cb19b57..0000000000 --- a/docs/conf.py +++ /dev/null @@ -1,176 +0,0 @@ -# -*- 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: - -from recommonmark.parser import CommonMarkParser - -source_parsers = { - '.md': CommonMarkParser, -} - -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'2018, 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', '_attic', 'spec'] - -# 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/guides/sdk/README.md b/docs/guides/sdk/README.md deleted file mode 100644 index 2986bc4b9c..0000000000 --- a/docs/guides/sdk/README.md +++ /dev/null @@ -1,3 +0,0 @@ -DEPRECATED - -See the [docs](/docs/sdk) diff --git a/docs/guides/sdk/apps.md b/docs/guides/sdk/apps.md deleted file mode 100644 index 442c1c8899..0000000000 --- a/docs/guides/sdk/apps.md +++ /dev/null @@ -1,2 +0,0 @@ -[Moved](/docs/sdk/overview/apps.md) - diff --git a/docs/guides/sdk/install.md b/docs/guides/sdk/install.md deleted file mode 100644 index 9b72e7a96c..0000000000 --- a/docs/guides/sdk/install.md +++ /dev/null @@ -1 +0,0 @@ -[Moved](/docs/sdk/install.md) diff --git a/docs/guides/sdk/key-management.md b/docs/guides/sdk/key-management.md deleted file mode 100644 index 3620760f78..0000000000 --- a/docs/guides/sdk/key-management.md +++ /dev/null @@ -1 +0,0 @@ -[Moved](/docs/sdk/clients/key-management.md) diff --git a/docs/guides/sdk/lcd-rest-api.yaml b/docs/guides/sdk/lcd-rest-api.yaml deleted file mode 100644 index 5af0fa2496..0000000000 --- a/docs/guides/sdk/lcd-rest-api.yaml +++ /dev/null @@ -1 +0,0 @@ -[Moved](/docs/sdk/clients/lcd-rest-api.yaml) diff --git a/docs/guides/sdk/overview.rst b/docs/guides/sdk/overview.rst deleted file mode 100644 index c7a9adc6d5..0000000000 --- a/docs/guides/sdk/overview.rst +++ /dev/null @@ -1 +0,0 @@ -[Moved](/docs/sdk) diff --git a/docs/guides/staking/intro.rst b/docs/guides/staking/intro.rst deleted file mode 100644 index 3ed20852b4..0000000000 --- a/docs/guides/staking/intro.rst +++ /dev/null @@ -1,402 +0,0 @@ -Using The Staking Module -======================== - -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 ``gaiad`` and ``gaiacli`` binaries: - -:: - - go get github.com/cosmos/cosmos-sdk - cd $GOPATH/src/github.com/cosmos/cosmos-sdk - make get_vendor_deps - make install - -Let's jump right into it. First, we initialize some default files: - -:: - - gaiad init - -which will output: - -:: - - 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 - -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. - -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: - -:: - - 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: - -:: - NAME: ADDRESS: PUBKEY: - alice 67997DD03D527EB439B7193F2B813B05B219CC02 1624DE6220BB89786C1D597050438C728202436552C6226AB67453CDB2A4D2703402FB52B6 - -You can see all available keys with: - -:: - - gaiacli keys list - -Setup Testnet -------------- - -Next, we start the daemon (do this in another window): - -:: - - 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": "steak", - "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": "steak" - } - } - }, - "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`` send some ``mycoin`` to ``bob``, who has now joined the network: - -:: - - 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 is the sender (alice), 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 - } - -TODO: check the above with current actual output. - -Check out ``bob``'s account, which should now have 1000 mycoin: - -:: - - 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 - -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 create a validator with that pubkey. - -:: - - gaiacli stake create-validator --amount=10mycoin --name=bob --address-validator=
--pub-key= --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 mycoin: - -:: - - gaiacli account 5D93A6059B6592833CBC8FA3DA90EE0382198985 - -To confirm for certain the new validator is active, ask the tendermint node: - -:: - - curl localhost:26657/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 mycoin 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``: - -:: - - gaiacli send --amount=1000mycoin --sequence=2 --name=alice --to=48F74F48281C89E5E4BE9092F735EA519768E8EF - -Then ``charlie`` will delegate some mycoin to ``bob``: - -:: - - gaiacli stake delegate --amount=10mycoin --address-delegator= --address-validator= --name=charlie - -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 mycoin. - -To get more information about the candidate, try: - -:: - - gaiacli stake validator
- -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: - -:: - - gaiacli stake delegation --address-delegator=
--address-validator=
- -with an output similar to: - -:: - - { - "height": 325782, - "data": { - "PubKey": { - "type": "ed25519", - "data": "52D6FCD8C92A97F7CCB01205ADF310A18411EA8FDCC10E65BF2FCDB05AD1689B" - }, - "Shares": 20 - } - } - - -where the ``--address-delegator`` is ``charlie``'s address and the ``--address-validator`` is ``bob``'s address. - - -Unbonding ---------- - -Finally, to relinquish your voting power, unbond some coins. You should see -your VotingPower reduce and your account balance increase. - -:: - - gaiacli stake unbond --amount=5mycoin --name=charlie --address-delegator=
--address-validator=
- gaiacli account 48F74F48281C89E5E4BE9092F735EA519768E8EF - -See the bond decrease with ``gaiacli stake delegation`` like above. diff --git a/docs/guides/staking/overview.md b/docs/guides/staking/overview.md deleted file mode 100644 index 79033fe1ea..0000000000 --- a/docs/guides/staking/overview.md +++ /dev/null @@ -1,216 +0,0 @@ -//TODO update .rst - -# Staking Module - -## Overview - -The Cosmos Hub is a Tendermint-based Delegated Proof of Stake (DPos) blockchain -system that serves as a backbone of the Cosmos ecosystem. It is operated and -secured by an open and globally decentralized set of validators. Tendermint is -a Byzantine fault-tolerant distributed protocol for consensus among distrusting -parties, in this case the group of validators which produce the blocks for the -Cosmos Hub. To avoid the nothing-at-stake problem, a validator in Tendermint -needs to lock up coins in a bond deposit. Each bond's atoms are illiquid, they -cannot be transferred - in order to become liquid, they must be unbonded, a -process which will take 3 weeks by default at Cosmos Hub launch. Tendermint -protocol messages are signed by the validator's private key and are therefor -attributable. Validators acting outside protocol specifications can be made -accountable through punishing by slashing (burning) their bonded Atoms. On the -other hand, validators are rewarded for their service of securing blockchain -network by the inflationary provisions and transactions fees. This incentivizes -correct behavior of the validators and provides the economic security of the -network. - -The native token of the Cosmos Hub is called the Atom; becoming a validator of the -Cosmos Hub requires holding Atoms. However, not all Atom holders are validators -of the Cosmos Hub. More precisely, there is a selection process that determines -the validator set as a subset of all validators (Atom holders that -want to become a validator). The other option for Atom holders is to delegate -their atoms to validators, i.e., being a delegator. A delegator is an Atom -holder that has put its Atoms at stake by delegating it to a validator. By bonding -Atoms to secure the network (and taking a risk of being slashed in case of -misbehaviour), a user is rewarded with inflationary provisions and transaction -fees proportional to the amount of its bonded Atoms. The Cosmos Hub is -designed to efficiently facilitate a small numbers of validators (hundreds), -and large numbers of delegators (tens of thousands). More precisely, it is the -role of the Staking module of the Cosmos Hub to support various staking -functionality including validator set selection, delegating, bonding and -withdrawing Atoms, and the distribution of inflationary provisions and -transaction fees. - -## Basic Terms and Definitions - -* Cosmsos Hub - a Tendermint-based Delegated Proof of Stake (DPos) - blockchain system -* Atom - native token of the Cosmsos Hub -* Atom holder - an entity that holds some amount of Atoms -* Pool - Global object within the Cosmos Hub which accounts global state - including the total amount of bonded, unbonding, and unbonded atoms -* Validator Share - Share which a validator holds to represent its portion of - bonded, unbonding or unbonded atoms in the pool -* Delegation Share - Shares which a delegation bond holds to represent its - portion of bonded, unbonding or unbonded shares in a validator -* Bond Atoms - a process of locking Atoms in a delegation share which holds them - under protocol control. -* Slash Atoms - the process of burning atoms in the pool and assoiated - validator shares of a misbehaving validator, (not behaving according to the - protocol specification). This process devalues the worth of delegation shares - of the given validator -* Unbond Shares - Process of retrieving atoms from shares. If the shares are - bonded the shares must first remain in an inbetween unbonding state for the - duration of the unbonding period -* Redelegating Shares - Process of redelegating atoms from one validator to - another. This process is instantaneous, but the redelegated atoms are - retrospecively slashable if the old validator is found to misbehave for any - blocks before the redelegation. These atoms are simultaniously slashable - for any new blocks which the new validator misbehavess -* Validator - entity with atoms which is either actively validating the Tendermint - protocol (bonded validator) or vying to validate . -* Bonded Validator - a validator whose atoms are currently bonded and liable to - be slashed. These validators are to be able to sign protocol messages for - Tendermint consensus. At Cosmos Hub genesis there is a maximum of 100 - bonded validator positions. Only Bonded Validators receive atom provisions - and fee rewards. -* Delegator - an Atom holder that has bonded Atoms to a validator -* Unbonding period - time required in the unbonding state when unbonding - shares. Time slashable to old validator after a redelegation. Time for which - validators can be slashed after an infraction. To provide the requisite - cryptoeconomic security guarantees, all of these must be equal. -* Atom provisions - The process of increasing the Atom supply. Atoms are - periodically created on the Cosmos Hub and issued to bonded Atom holders. - The goal of inflation is to incentize most of the Atoms in existence to be - bonded. Atoms are distributed unbonded and using the fee_distribution mechanism -* Transaction fees - transaction fee is a fee that is included in a Cosmsos Hub - transaction. The fees are collected by the current validator set and - distributed among validators and delegators in proportion to their bonded - Atom share -* Commission fee - a fee taken from the transaction fees by a validator for - their service - -## The pool and the share - -At the core of the Staking module is the concept of a pool which denotes a -collection of Atoms contributed by different Atom holders. There are three -pools in the Staking module: the bonded, unbonding, and unbonded pool. Bonded -Atoms are part of the global bonded pool. If a validator or delegator wants to -unbond its shares, these Shares are moved to the the unbonding pool for the -duration of the unbonding period. From here normally Atoms will be moved -directly into the delegators wallet, however under the situation thatn an -entire validator gets unbonded, the Atoms of the delegations will remain with -the validator and moved to the unbonded pool. For each pool, the total amount -of bonded, unbonding, or unbonded Atoms are tracked as well as the current -amount of issued pool-shares, the specific holdings of these shares by -validators are tracked in protocol by the validator object. - -A share is a unit of Atom distribution and the value of the share -(share-to-atom exchange rate) can change during system execution. The -share-to-atom exchange rate can be computed as: - -`share-to-atom-exchange-rate = size of the pool / ammount of issued shares` - -Then for each validator (in a per validator data structure) the protocol keeps -track of the amount of shares the validator owns in a pool. At any point in -time, the exact amount of Atoms a validator has in the pool can be computed as -the number of shares it owns multiplied with the current share-to-atom exchange -rate: - -`validator-coins = validator.Shares * share-to-atom-exchange-rate` - -The benefit of such accounting of the pool resources is the fact that a -modification to the pool from bonding/unbonding/slashing of Atoms affects only -global data (size of the pool and the number of shares) and not the related -validator data structure, i.e., the data structure of other validators do not -need to be modified. This has the advantage that modifying global data is much -cheaper computationally than modifying data of every validator. Let's explain -this further with several small examples: - -XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -XXX TODO make way less verbose lets use bullet points to describe the example -XXX Also need to update to not include bonded atom provisions all atoms are -XXX redistributed with the fee pool now - -We consider initially 4 validators p1, p2, p3 and p4, and that each validator -has bonded 10 Atoms to the bonded pool. Furthermore, let's assume that we have -issued initially 40 shares (note that the initial distribution of the shares, -i.e., share-to-atom exchange rate can be set to any meaningful value), i.e., -share-to-atom-ex-rate = 1 atom per share. Then at the global pool level we -have, the size of the pool is 40 Atoms, and the amount of issued shares is -equal to 40. And for each validator we store in their corresponding data -structure that each has 10 shares of the bonded pool. Now lets assume that the -validator p4 starts process of unbonding of 5 shares. Then the total size of -the pool is decreased and now it will be 35 shares and the amount of Atoms is -35 . Note that the only change in other data structures needed is reducing the -number of shares for a validator p4 from 10 to 5. - -Let's consider now the case where a validator p1 wants to bond 15 more atoms to -the pool. Now the size of the pool is 50, and as the exchange rate hasn't -changed (1 share is still worth 1 Atom), we need to create more shares, i.e. we -now have 50 shares in the pool in total. Validators p2, p3 and p4 still have -(correspondingly) 10, 10 and 5 shares each worth of 1 atom per share, so we -don't need to modify anything in their corresponding data structures. But p1 -now has 25 shares, so we update the amount of shares owned by p1 in its -data structure. Note that apart from the size of the pool that is in Atoms, all -other data structures refer only to shares. - -Finally, let's consider what happens when new Atoms are created and added to -the pool due to inflation. Let's assume that the inflation rate is 10 percent -and that it is applied to the current state of the pool. This means that 5 -Atoms are created and added to the pool and that each validator now -proportionally increase it's Atom count. Let's analyse how this change is -reflected in the data structures. First, the size of the pool is increased and -is now 55 atoms. As a share of each validator in the pool hasn't changed, this -means that the total number of shares stay the same (50) and that the amount of -shares of each validator stays the same (correspondingly 25, 10, 10, 5). But -the exchange rate has changed and each share is now worth 55/50 Atoms per -share, so each validator has effectively increased amount of Atoms it has. So -validators now have (correspondingly) 55/2, 55/5, 55/5 and 55/10 Atoms. - -The concepts of the pool and its shares is at the core of the accounting in the -Staking module. It is used for managing the global pools (such as bonding and -unbonding pool), but also for distribution of Atoms between validator and its -delegators (we will explain this in section X). - -#### Delegator shares - -A validator is, depending on its status, contributing Atoms to either the -unbonding or unbonded pool - the validator in turn holds some amount of pool -shares. Not all of a validator's Atoms (and respective shares) are necessarily -owned by the validator, some may be owned by delegators to that validator. The -mechanism for distribution of Atoms (and shares) between a validator and its -delegators is based on a notion of delegator shares. More precisely, every -validator is issuing (local) delegator shares -(`Validator.IssuedDelegatorShares`) that represents some portion of global -shares managed by the validator (`Validator.GlobalStakeShares`). The principle -behind managing delegator shares is the same as described in [Section](#The -pool and the share). We now illustrate it with an example. - -XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -XXX TODO make way less verbose lets use bullet points to describe the example -XXX Also need to update to not include bonded atom provisions all atoms are -XXX redistributed with the fee pool now - -Let's consider 4 validators p1, p2, p3 and p4, and assume that each validator -has bonded 10 Atoms to the bonded pool. Furthermore, let's assume that we have -issued initially 40 global shares, i.e., that -`share-to-atom-exchange-rate = 1 atom per share`. So we will set -`GlobalState.BondedPool = 40` and `GlobalState.BondedShares = 40` and in the -Validator data structure of each validator `Validator.GlobalStakeShares = 10`. -Furthermore, each validator issued 10 delegator shares which are initially -owned by itself, i.e., `Validator.IssuedDelegatorShares = 10`, where -`delegator-share-to-global-share-ex-rate = 1 global share per delegator share`. -Now lets assume that a delegator d1 delegates 5 atoms to a validator p1 and -consider what are the updates we need to make to the data structures. First, -`GlobalState.BondedPool = 45` and `GlobalState.BondedShares = 45`. Then, for -validator p1 we have `Validator.GlobalStakeShares = 15`, but we also need to -issue also additional delegator shares, i.e., -`Validator.IssuedDelegatorShares = 15` as the delegator d1 now owns 5 delegator -shares of validator p1, where each delegator share is worth 1 global shares, -i.e, 1 Atom. Lets see now what happens after 5 new Atoms are created due to -inflation. In that case, we only need to update `GlobalState.BondedPool` which -is now equal to 50 Atoms as created Atoms are added to the bonded pool. Note -that the amount of global and delegator shares stay the same but they are now -worth more as share-to-atom-exchange-rate is now worth 50/45 Atoms per share. -Therefore, a delegator d1 now owns: - -`delegatorCoins = 5 (delegator shares) * 1 (delegator-share-to-global-share-ex-rate) * 50/45 (share-to-atom-ex-rate) = 5.55 Atoms` - diff --git a/docs/guides/staking/testnet.md b/docs/guides/staking/testnet.md deleted file mode 100644 index b2bbd8f1a3..0000000000 --- a/docs/guides/staking/testnet.md +++ /dev/null @@ -1,94 +0,0 @@ -# Testnet Setup - -**Note:** This document is incomplete and may not be up-to-date with the -state of the code. - -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 couple of genesis transactions to be incorporated into -the genesis file, this will create two keys with the password -`1234567890`: - -``` -gaiad init gen-tx --name=foo --home=$HOME/.gaiad1 -gaiad init gen-tx --name=bar --home=$HOME/.gaiad2 -gaiacli keys list -``` - -**Note:** If you've already run these tests you may need to overwrite -keys using the `--owk` flag When you list the keys you should see two -addresses, we'll need these later so take note. Now let's actually -create the genesis files for both nodes: - -``` -cp -a ~/.gaiad2/config/gentx/. ~/.gaiad1/config/gentx/ -cp -a ~/.gaiad1/config/gentx/. ~/.gaiad2/config/gentx/ -gaiad init --gen-txs --home=$HOME/.gaiad1 --chain-id=test-chain -gaiad init --gen-txs --home=$HOME/.gaiad2 --chain-id=test-chain -``` - -**Note:** If you've already run these tests you may need to overwrite -genesis using the `-o` flag. What we just did is copy the genesis -transactions between each of the nodes so there is a common genesis -transaction set; then we created both genesis files independently from -each home directory. Importantly both nodes have independently created -their `genesis.json` and `config.toml` files, which should be identical -between nodes. - -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 -``` - -Then, we try to transfer some `steak` to another account: - -``` -gaiacli account -gaiacli account -gaiacli send --amount=10steak --to= --name=foo --chain-id=test-chain -``` - -**Note:** We need to be careful with the `chain-id` and `sequence` - -Check the balance & sequence with: - -``` -gaiacli account -``` - -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 --chain-id= --name=test -``` - -That's it! - -**Note:** TODO demonstrate edit-candidacy **Note:** TODO demonstrate -delegation **Note:** TODO demonstrate unbond of delegation **Note:** -TODO demonstrate unbond candidate diff --git a/docs/guides/staking/testnet.rst b/docs/guides/staking/testnet.rst deleted file mode 100644 index 0e86a952d2..0000000000 --- a/docs/guides/staking/testnet.rst +++ /dev/null @@ -1,82 +0,0 @@ -Testnet Setup -============= - -**Note:** This document is incomplete and may not be up-to-date with the state of the code. - -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 couple of genesis transactions to be incorparated into the genesis file, this will create two keys with the password ``1234567890`` - -:: - - gaiad init gen-tx --name=foo --home=$HOME/.gaiad1 - gaiad init gen-tx --name=bar --home=$HOME/.gaiad2 - gaiacli keys list - -**Note:** If you've already run these tests you may need to overwrite keys using the ``--OWK`` flag -When you list the keys you should see two addresses, we'll need these later so take note. -Now let's actually create the genesis files for both nodes: - -:: - - cp -a ~/.gaiad2/config/gentx/. ~/.gaiad1/config/gentx/ - cp -a ~/.gaiad1/config/gentx/. ~/.gaiad2/config/gentx/ - gaiad init --gen-txs --home=$HOME/.gaiad1 --chain-id=test-chain - gaiad init --gen-txs --home=$HOME/.gaiad2 --chain-id=test-chain - -**Note:** If you've already run these tests you may need to overwrite genesis using the ``-o`` flag -What we just did is copy the genesis transactions between each of the nodes so there is a common genesis transaction set; then we created both genesis files independently from each home directory. Importantly both nodes have independently created their ``genesis.json`` and ``config.toml`` files, which should be identical between nodes. - -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 advanced tendermint validator-set - -Then, we try to transfer some ``steak`` to another account: - -:: - - gaiacli account - gaiacli account - gaiacli send --amount=10steak --to= --name=foo --chain-id=test-chain - -**Note:** We need to be careful with the ``chain-id`` and ``sequence`` - -Check the balance & sequence with: - -:: - - gaiacli account - -To confirm for certain the new validator is active, check tendermint: - -:: - - curl localhost:26657/validators - -Finally, to relinquish all your power, unbond some coins. You should see your VotingPower reduce and your account balance increase. - -:: - - gaiacli stake unbond --chain-id= --name=test - -That's it! - -**Note:** TODO demonstrate edit-candidacy -**Note:** TODO demonstrate delegation -**Note:** TODO demonstrate unbond of delegation -**Note:** TODO demonstrate unbond candidate diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 3a2237a3c0..0000000000 --- a/docs/index.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. Cosmos-SDK documentation master file, created by - sphinx-quickstart on Fri Sep 1 21:37:02 2017. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to the Cosmos SDK! -========================== - -.. image:: graphics/cosmos-sdk-image.png - :height: 250px - :width: 500px - :align: center - -SDK ---- - -.. toctree:: - :maxdepth: 1 - - guides/sdk/install.md - guides/sdk/key-management.md - -.. sdk/overview.rst # needs to be updated -.. old/glossary.rst # not completely up to date but has good content - -.. Basecoin -.. -------- - -.. .. toctree:: - :maxdepth: 2 - -.. 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 -.. ---------- - -.. old/basecoin/extensions.rst # probably not worth salvaging - -.. Replay Protection -.. ~~~~~~~~~~~~~~~~~ - -.. old/replay-protection.rst # not sure if worth salvaging - - -Staking -~~~~~~~ - -.. toctree:: - :maxdepth: 1 - - guides/staking/testnet.md -.. staking/intro.rst -.. staking/key-management.rst -.. staking/local-testnet.rst -.. staking/public-testnet.rst - -.. IBC -.. --- - -.. old/ibc.rst # needs to be updated diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 916e57ee79..0000000000 --- a/docs/make.bat +++ /dev/null @@ -1,36 +0,0 @@ -@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