docs cleanup
This commit is contained in:
Ethan Buchman
committed by
Zach Ramsay
Zach Ramsay
parent
1b9afdab48
commit
266ea5ce82
@@ -1,270 +0,0 @@
|
||||
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 <../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.
|
||||
@@ -1,204 +0,0 @@
|
||||
Key Management
|
||||
==============
|
||||
|
||||
Here we explain a bit how to work with your keys, using the
|
||||
``gaia client keys`` subcommand.
|
||||
|
||||
**Note:** This keys tooling is not considered production ready and is
|
||||
for dev only.
|
||||
|
||||
We'll look at what you can do using the six sub-commands of
|
||||
``gaia client keys``:
|
||||
|
||||
::
|
||||
|
||||
new
|
||||
list
|
||||
get
|
||||
delete
|
||||
recover
|
||||
update
|
||||
|
||||
Create keys
|
||||
-----------
|
||||
|
||||
``gaia client keys new`` has two inputs (name, password) and two outputs
|
||||
(address, seed).
|
||||
|
||||
First, we name our key:
|
||||
|
||||
::
|
||||
|
||||
gaia client keys new alice
|
||||
|
||||
This will prompt (10 character minimum) password entry which must be
|
||||
re-typed. You'll see:
|
||||
|
||||
::
|
||||
|
||||
Enter a passphrase:
|
||||
Repeat the passphrase:
|
||||
alice A159C96AE911F68913E715ED889D211C02EC7D70
|
||||
**Important** write this seed phrase in a safe place.
|
||||
It is the only way to recover your account if you ever forget your password.
|
||||
|
||||
pelican amateur empower assist awkward claim brave process cliff save album pigeon intact asset
|
||||
|
||||
which shows the address of your key named ``alice``, and its recovery
|
||||
seed. We'll use these shortly.
|
||||
|
||||
Adding the ``--output json`` flag to the above command would give this
|
||||
output:
|
||||
|
||||
::
|
||||
|
||||
Enter a passphrase:
|
||||
Repeat the passphrase:
|
||||
{
|
||||
"key": {
|
||||
"name": "alice",
|
||||
"address": "A159C96AE911F68913E715ED889D211C02EC7D70",
|
||||
"pubkey": {
|
||||
"type": "ed25519",
|
||||
"data": "4BF22554B0F0BF2181187E5E5456E3BF3D96DB4C416A91F07F03A9C36F712B77"
|
||||
}
|
||||
},
|
||||
"seed": "pelican amateur empower assist awkward claim brave process cliff save album pigeon intact asset"
|
||||
}
|
||||
|
||||
To avoid the prompt, it's possible to pipe the password into the
|
||||
command, e.g.:
|
||||
|
||||
::
|
||||
|
||||
echo 1234567890 | gaia client keys new fred --output json
|
||||
|
||||
After trying each of the three ways to create a key, look at them, use:
|
||||
|
||||
::
|
||||
|
||||
gaia client keys list
|
||||
|
||||
to list all the keys:
|
||||
|
||||
::
|
||||
|
||||
All keys:
|
||||
alice 6FEA9C99E2565B44FCC3C539A293A1378CDA7609
|
||||
bob A159C96AE911F68913E715ED889D211C02EC7D70
|
||||
charlie 784D623E0C15DE79043C126FA6449B68311339E5
|
||||
|
||||
Again, we can use the ``--output json`` flag:
|
||||
|
||||
::
|
||||
|
||||
[
|
||||
{
|
||||
"name": "alice",
|
||||
"address": "6FEA9C99E2565B44FCC3C539A293A1378CDA7609",
|
||||
"pubkey": {
|
||||
"type": "ed25519",
|
||||
"data": "878B297F1E863CC30CAD71E04A8B3C23DB71C18F449F39E35B954EDB2276D32D"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "bob",
|
||||
"address": "A159C96AE911F68913E715ED889D211C02EC7D70",
|
||||
"pubkey": {
|
||||
"type": "ed25519",
|
||||
"data": "2127CAAB96C08E3042C5B33C8B5A820079AAE8DD50642DCFCC1E8B74821B2BB9"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "charlie",
|
||||
"address": "784D623E0C15DE79043C126FA6449B68311339E5",
|
||||
"pubkey": {
|
||||
"type": "ed25519",
|
||||
"data": "4BF22554B0F0BF2181187E5E5456E3BF3D96DB4C416A91F07F03A9C36F712B77"
|
||||
}
|
||||
},
|
||||
]
|
||||
|
||||
to get machine readable output.
|
||||
|
||||
If we want information about one specific key, then:
|
||||
|
||||
::
|
||||
|
||||
gaia client keys get charlie --output json
|
||||
|
||||
will, for example, return the info for only the "charlie" key returned
|
||||
from the previous ``gaia client keys list`` command.
|
||||
|
||||
The keys tooling can support different types of keys with a flag:
|
||||
|
||||
::
|
||||
|
||||
gaia client keys new bit --type secp256k1
|
||||
|
||||
and you'll see the difference in the ``"type": field from``\ gaia client
|
||||
keys get\`
|
||||
|
||||
Before moving on, let's set an enviroment variable to make
|
||||
``--output json`` the default.
|
||||
|
||||
Either run or put in your ``~/.bash_profile`` the following line:
|
||||
|
||||
::
|
||||
|
||||
export BC_OUTPUT=json
|
||||
|
||||
Recover a key
|
||||
-------------
|
||||
|
||||
Let's say, for whatever reason, you lose a key or forget the password.
|
||||
On creation, you were given a seed. We'll use it to recover a lost key.
|
||||
|
||||
First, let's simulate the loss by deleting a key:
|
||||
|
||||
::
|
||||
|
||||
gaia client keys delete alice
|
||||
|
||||
which prompts for your current password, now rendered obsolete, and
|
||||
gives a warning message. The only way you can recover your key now is
|
||||
using the 12 word seed given on initial creation of the key. Let's try
|
||||
it:
|
||||
|
||||
::
|
||||
|
||||
gaia client keys recover alice-again
|
||||
|
||||
which prompts for a new password then the seed:
|
||||
|
||||
::
|
||||
|
||||
Enter the new passphrase:
|
||||
Enter your recovery seed phrase:
|
||||
strike alien praise vendor term left market practice junior better deputy divert front calm
|
||||
alice-again CBF5D9CE6DDCC32806162979495D07B851C53451
|
||||
|
||||
and voila! You've recovered your key. Note that the seed can be typed
|
||||
out, pasted in, or piped into the command alongside the password.
|
||||
|
||||
To change the password of a key, we can:
|
||||
|
||||
::
|
||||
|
||||
gaia client keys update alice-again
|
||||
|
||||
and follow the prompts.
|
||||
|
||||
That covers most features of the keys sub command.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<!-- use later in a test script, or more advance tutorial?
|
||||
SEED=$(echo 1234567890 | gaia client keys new fred -o json | jq .seed | tr -d \")
|
||||
echo $SEED
|
||||
(echo qwertyuiop; echo $SEED stamp) | gaia client keys recover oops
|
||||
(echo qwertyuiop; echo $SEED) | gaia client keys recover derf
|
||||
gaia client keys get fred -o json
|
||||
gaia client keys get derf -o json
|
||||
```
|
||||
-->
|
||||
@@ -1,83 +0,0 @@
|
||||
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.
|
||||
@@ -1,64 +0,0 @@
|
||||
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 <../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``.
|
||||
Reference in New Issue
Block a user