docs: edits for rst & other cleanup
This commit is contained in:
Zach Ramsay
parent
e60b311796
commit
2738c22798
|
|
@ -74,24 +74,28 @@ Install
|
|||
|
||||
With go, it's one command:
|
||||
|
||||
.. code:: shelldown[0]
|
||||
.. code:: shelldown[0]
|
||||
|
||||
::
|
||||
|
||||
go get -u github.com/tendermint/basecoin/cmd/...
|
||||
|
||||
If you have trouble, see the `installation guide <install.md>`__.
|
||||
If you have trouble, see the `installation guide <./install.html>`__.
|
||||
|
||||
Note the above command installs two binaries: ``basecoin`` and
|
||||
``basecli``. The former is the running node. The latter is a
|
||||
command-line light-client. This tutorial assumes you have a 'fresh'
|
||||
working environment. See `how to clean up, below <#clean-up>`__.
|
||||
working environment. See how to clean up below.
|
||||
|
||||
Generate some keys
|
||||
------------------
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Let's generate two keys, one to receive an initial allocation of coins,
|
||||
and one to send some coins to later:
|
||||
|
||||
.. code:: shelldown[1]
|
||||
.. code:: shelldown[1]
|
||||
|
||||
::
|
||||
|
||||
basecli keys new cool
|
||||
basecli keys new friend
|
||||
|
|
@ -105,14 +109,18 @@ Initialize Basecoin
|
|||
|
||||
To initialize a new Basecoin blockchain, run:
|
||||
|
||||
.. code:: shelldown[2]
|
||||
.. code:: shelldown[2]
|
||||
|
||||
::
|
||||
|
||||
basecoin init <ADDRESS>
|
||||
|
||||
If you prefer not to copy-paste, you can provide the address
|
||||
programatically:
|
||||
|
||||
.. code:: shelldown[3]
|
||||
.. code:: shelldown[3]
|
||||
|
||||
::
|
||||
|
||||
basecoin init $(basecli keys get cool | awk '{print $2}')
|
||||
|
||||
|
|
@ -124,12 +132,14 @@ Basecoin tool </docs/guide/basecoin-tool.md>`__.
|
|||
If you like, you can manually add some more accounts to the blockchain
|
||||
by generating keys and editing the ``~/.basecoin/genesis.json``.
|
||||
|
||||
Start
|
||||
-----
|
||||
Start Basecoin
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
Now we can start Basecoin:
|
||||
|
||||
.. code:: shelldown[4]
|
||||
.. code:: shelldown[4]
|
||||
|
||||
::
|
||||
|
||||
basecoin start
|
||||
|
||||
|
|
@ -143,7 +153,9 @@ light-client utility. Basecli is used for sending transactions and
|
|||
querying the state. Leave Basecoin running and open a new terminal
|
||||
window. Here run:
|
||||
|
||||
.. code:: shelldown[5]
|
||||
.. code:: shelldown[5]
|
||||
|
||||
::
|
||||
|
||||
basecli init --node=tcp://localhost:46657 --genesis=$HOME/.basecoin/genesis.json
|
||||
|
||||
|
|
@ -153,17 +165,19 @@ some trusted source, so all queries done with ``basecli`` can be
|
|||
cryptographically proven to be correct according to a known validator
|
||||
set.
|
||||
|
||||
Note: that --genesis only works if there have been no validator set
|
||||
Note: that ``--genesis`` only works if there have been no validator set
|
||||
changes since genesis. If there are validator set changes, you need to
|
||||
find the current set through some other method.
|
||||
|
||||
Send transactions
|
||||
-----------------
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
Now we are ready to send some transactions. First Let's check the
|
||||
balance of the two accounts we setup earlier:
|
||||
|
||||
.. code:: shelldown[6]
|
||||
.. code:: shelldown[6]
|
||||
|
||||
::
|
||||
|
||||
ME=$(basecli keys get cool | awk '{print $2}')
|
||||
YOU=$(basecli keys get friend | awk '{print $2}')
|
||||
|
|
@ -173,20 +187,26 @@ balance of the two accounts we setup earlier:
|
|||
The first account is flush with cash, while the second account doesn't
|
||||
exist. Let's send funds from the first account to the second:
|
||||
|
||||
.. code:: shelldown[7]
|
||||
.. code:: shelldown[7]
|
||||
|
||||
::
|
||||
|
||||
basecli tx send --name=cool --amount=1000mycoin --to=$YOU --sequence=1
|
||||
|
||||
Now if we check the second account, it should have ``1000`` 'mycoin'
|
||||
coins!
|
||||
|
||||
.. code:: shelldown[8]
|
||||
.. code:: shelldown[8]
|
||||
|
||||
::
|
||||
|
||||
basecli query account $YOU
|
||||
|
||||
We can send some of these coins back like so:
|
||||
|
||||
.. code:: shelldown[9]
|
||||
.. code:: shelldown[9]
|
||||
|
||||
::
|
||||
|
||||
basecli tx send --name=friend --amount=500mycoin --to=$ME --sequence=1
|
||||
|
||||
|
|
@ -195,20 +215,26 @@ send from.
|
|||
|
||||
If we try to send too much, we'll get an error:
|
||||
|
||||
.. code:: shelldown[10]
|
||||
.. code:: shelldown[10]
|
||||
|
||||
::
|
||||
|
||||
basecli tx send --name=friend --amount=500000mycoin --to=$ME --sequence=2
|
||||
|
||||
Let's send another transaction:
|
||||
|
||||
.. code:: shelldown[11]
|
||||
.. code:: shelldown[11]
|
||||
|
||||
basecli tx send --name=cool --amount=2345mycoin --to=$YOU --sequence=2
|
||||
::
|
||||
|
||||
basecli tx send --name=cool --amount=2345mycoin --to=$YOU --sequence=2
|
||||
|
||||
Note the ``hash`` value in the response - this is the hash of the
|
||||
transaction. We can query for the transaction by this hash:
|
||||
|
||||
.. code:: shelldown[12]
|
||||
.. code:: shelldown[12]
|
||||
|
||||
::
|
||||
|
||||
basecli query tx <HASH>
|
||||
|
||||
|
|
@ -228,9 +254,6 @@ and it is secure to do so. So, if you wonder why the query may take a
|
|||
second... there is a lot of work going on in the background to make sure
|
||||
even a lying full node can't trick your client.
|
||||
|
||||
In a latter `guide on InterBlockchain Communication <ibc.md>`__, we'll
|
||||
use these proofs to post transactions to other chains.
|
||||
|
||||
Accounts and Transactions
|
||||
-------------------------
|
||||
|
||||
|
|
@ -248,7 +271,9 @@ unlike Bitcoin's use of Unspent Transaction Outputs (UTXOs). Note
|
|||
Basecoin is a multi-asset cryptocurrency, so each account can have many
|
||||
different kinds of tokens.
|
||||
|
||||
.. code:: golang
|
||||
.. code:: golang
|
||||
|
||||
::
|
||||
|
||||
type Account struct {
|
||||
PubKey crypto.PubKey `json:"pub_key"` // May be nil, if not known.
|
||||
|
|
@ -285,7 +310,9 @@ a list of outputs, and transfers all the tokens listed in the inputs
|
|||
from their corresponding accounts to the accounts listed in the output.
|
||||
The ``SendTx`` is structured as follows:
|
||||
|
||||
.. code:: golang
|
||||
.. code:: golang
|
||||
|
||||
::
|
||||
|
||||
type SendTx struct {
|
||||
Gas int64 `json:"gas"`
|
||||
|
|
@ -347,19 +374,15 @@ To remove all the files created and refresh your environment (e.g., if
|
|||
starting this tutorial again or trying something new), the following
|
||||
commands are run:
|
||||
|
||||
.. code:: shelldown[end-of-tutorials]
|
||||
.. code:: shelldown[end-of-tutorials]
|
||||
|
||||
::
|
||||
|
||||
basecli reset_all
|
||||
rm -rf ~/.basecoin
|
||||
|
||||
Conclusion
|
||||
----------
|
||||
|
||||
In this guide, we introduced the ``basecoin`` and ``basecli`` tools,
|
||||
demonstrated how to start a new basecoin blockchain and how to send
|
||||
tokens between accounts, and discussed the underlying data types for
|
||||
accounts and transactions, specifically the ``Account`` and the
|
||||
``SendTx``. In the `next guide <basecoin-plugins.md>`__, we introduce
|
||||
the Basecoin plugin system, which uses a new transaction type, the
|
||||
``AppTx``, to extend the functionality of the Basecoin system with
|
||||
arbitrary logic.
|
||||
``SendTx``.
|
||||
|
|
|
|||
|
|
@ -54,31 +54,33 @@
|
|||
. $DIR/shunit2
|
||||
-->
|
||||
|
||||
The Basecoin Tool
|
||||
Basecoin The Tool
|
||||
=================
|
||||
|
||||
In previous tutorials we learned the `basics of the Basecoin
|
||||
CLI </docs/guide/basecoin-basics.md>`__ and `how to implement a
|
||||
plugin </docs/guide/basecoin-plugins.md>`__. In this tutorial, we
|
||||
We previously learned about basecoin basics. In this tutorial, we
|
||||
provide more details on using the Basecoin tool.
|
||||
|
||||
Generate a Key
|
||||
==============
|
||||
--------------
|
||||
|
||||
Generate a key using the ``basecli`` tool:
|
||||
|
||||
.. code:: shelldown[0]
|
||||
.. comment code:: shelldown[0]
|
||||
|
||||
::
|
||||
|
||||
basecli keys new mykey
|
||||
ME=$(basecli keys get mykey | awk '{print $2}')
|
||||
|
||||
Data Directory
|
||||
==============
|
||||
--------------
|
||||
|
||||
By default, ``basecoin`` works out of ``~/.basecoin``. To change this,
|
||||
set the ``BCHOME`` environment variable:
|
||||
|
||||
.. code:: shelldown[1]
|
||||
.. comment code:: shelldown[1]
|
||||
|
||||
::
|
||||
|
||||
export BCHOME=~/.my_basecoin_data
|
||||
basecoin init $ME
|
||||
|
|
@ -86,19 +88,23 @@ set the ``BCHOME`` environment variable:
|
|||
|
||||
or
|
||||
|
||||
.. code:: shelldown[2]
|
||||
.. comment code:: shelldown[2]
|
||||
|
||||
::
|
||||
|
||||
BCHOME=~/.my_basecoin_data basecoin init $ME
|
||||
BCHOME=~/.my_basecoin_data basecoin start
|
||||
|
||||
ABCI Server
|
||||
===========
|
||||
-----------
|
||||
|
||||
So far we have run Basecoin and Tendermint in a single process. However,
|
||||
since we use ABCI, we can actually run them in different processes.
|
||||
First, initialize them:
|
||||
|
||||
.. code:: shelldown[3]
|
||||
.. comment code:: shelldown[3]
|
||||
|
||||
::
|
||||
|
||||
basecoin init $ME
|
||||
|
||||
|
|
@ -107,13 +113,17 @@ the information for both Basecoin and Tendermint.
|
|||
|
||||
Now, In one window, run
|
||||
|
||||
.. code:: shelldown[4]
|
||||
.. comment code:: shelldown[4]
|
||||
|
||||
::
|
||||
|
||||
basecoin start --without-tendermint
|
||||
|
||||
and in another,
|
||||
|
||||
.. code:: shelldown[5]
|
||||
.. comment code:: shelldown[5]
|
||||
|
||||
::
|
||||
|
||||
TMROOT=~/.basecoin tendermint node
|
||||
|
||||
|
|
@ -122,36 +132,40 @@ You should see Tendermint start making blocks!
|
|||
Alternatively, you could ignore the Tendermint details in
|
||||
``~/.basecoin/genesis.json`` and use a separate directory by running:
|
||||
|
||||
.. code:: shelldown[6]
|
||||
.. comment code:: shelldown[6]
|
||||
|
||||
::
|
||||
|
||||
tendermint init
|
||||
tendermint node
|
||||
|
||||
For more details on using ``tendermint``, see `the
|
||||
guide <https://tendermint.com/docs/guides/using-tendermint>`__.
|
||||
See the `tendermint documentation <https://tendermint.readthedocs.io>`__ for more information.
|
||||
|
||||
Keys and Genesis
|
||||
================
|
||||
----------------
|
||||
|
||||
In previous tutorials we used ``basecoin init`` to initialize
|
||||
``~/.basecoin`` with the default configuration. This command creates
|
||||
files both for Tendermint and for Basecoin, and a single
|
||||
``genesis.json`` file for both of them. For more information on these
|
||||
files, see the `guide to using
|
||||
Tendermint <https://tendermint.com/docs/guides/using-tendermint>`__.
|
||||
``genesis.json`` file for both of them. You can read more about these
|
||||
files in the Tendermint documentation.
|
||||
|
||||
Now let's make our own custom Basecoin data.
|
||||
|
||||
First, create a new directory:
|
||||
|
||||
.. code:: shelldown[7]
|
||||
.. comment code:: shelldown[7]
|
||||
|
||||
::
|
||||
|
||||
mkdir example-data
|
||||
|
||||
We can tell ``basecoin`` to use this directory by exporting the
|
||||
``BCHOME`` environment variable:
|
||||
|
||||
.. code:: shelldown[8]
|
||||
.. comment code:: shelldown[8]
|
||||
|
||||
::
|
||||
|
||||
export BCHOME=$(pwd)/example-data
|
||||
|
||||
|
|
@ -160,13 +174,17 @@ this variable to your shell startup scripts (eg. ``~/.bashrc``).
|
|||
|
||||
Now, let's create a new key:
|
||||
|
||||
.. code:: shelldown[9]
|
||||
.. comment code:: shelldown[9]
|
||||
|
||||
::
|
||||
|
||||
basecli keys new foobar
|
||||
|
||||
The key's info can be retrieved with
|
||||
|
||||
.. code:: shelldown[10]
|
||||
.. comment code:: shelldown[10]
|
||||
|
||||
::
|
||||
|
||||
basecli keys get foobar -o=json
|
||||
|
||||
|
|
@ -228,27 +246,31 @@ need this flag because we were using the default chain ID
|
|||
("test\_chain\_id"). Now that we're using a custom chain, we need to
|
||||
specify the chain explicitly on the command line.
|
||||
|
||||
Note we have also left out the details of the Tendermint genesis. These
|
||||
are documented in the `Tendermint
|
||||
guide <https://tendermint.com/docs/guides/using-tendermint>`__.
|
||||
Note we have also left out the details of the Tendermint genesis. See the
|
||||
`Tendermint documentation <https://tendermint.readthedocs.io>`__ for more
|
||||
information.
|
||||
|
||||
Reset
|
||||
=====
|
||||
-----
|
||||
|
||||
You can reset all blockchain data by running:
|
||||
|
||||
.. code:: shelldown[11]
|
||||
.. (comment) code:: shelldown[11]
|
||||
|
||||
::
|
||||
|
||||
basecoin unsafe_reset_all
|
||||
|
||||
Similarly, you can reset client data by running:
|
||||
|
||||
.. code:: shelldown[12]
|
||||
.. (comment) code:: shelldown[12]
|
||||
|
||||
::
|
||||
|
||||
basecli reset_all
|
||||
|
||||
Genesis
|
||||
=======
|
||||
-------
|
||||
|
||||
Any required plugin initialization should be constructed using
|
||||
``SetOption`` on genesis. When starting a new chain for the first time,
|
||||
|
|
|
|||
|
|
@ -1,24 +1,17 @@
|
|||
Quark Overview
|
||||
SDK Overview
|
||||
==============
|
||||
|
||||
The quark middleware design optimizes flexibility and security. The
|
||||
The SDK middleware design optimizes flexibility and security. The
|
||||
framework is designed around a modular execution stack which allows
|
||||
applications to mix and match modular elements as desired. Along side,
|
||||
all modules are permissioned and sandboxed to isolate modules for
|
||||
greater application security.
|
||||
|
||||
For more explanation please see the `standard library <stdlib.md>`__ and
|
||||
`glossary <glossary.md>`__ documentation.
|
||||
|
||||
For a more interconnected schematics see these
|
||||
`framework <graphics/overview-framework.png>`__ and
|
||||
`security <graphics/overview-security.png>`__ overviews.
|
||||
|
||||
Framework Overview
|
||||
------------------
|
||||
|
||||
Transactions (tx)
|
||||
~~~~~~~~~~~~~~~~~
|
||||
Transactions
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Each transaction passes through the middleware stack which can be
|
||||
defined uniquely by each application. From the multiple layers of
|
||||
|
|
@ -32,13 +25,13 @@ Execution Stack
|
|||
|
||||
Middleware components allow for code reusability and integrability. A
|
||||
standard set of middleware are provided and can be mix-and-matched with
|
||||
custom middleware. Some of the `standard library <stdlib.md>`__
|
||||
custom middleware. Some of the `standard library <./stdlib.html>`__
|
||||
middlewares provided in this package include: - Logging - Recovery -
|
||||
Signatures - Chain - Nonce - Fees - Roles -
|
||||
Inter-Blockchain-Communication (IBC)
|
||||
|
||||
As a part of stack execution the state space provided to each middleware
|
||||
is isolated (see `Data Store <overview.md#data-store>`__). When
|
||||
is isolated ``Data Store`` below. When
|
||||
executing the stack, state-recovery checkpoints can be assigned for
|
||||
stack execution of ``CheckTx`` or ``DeliverTx``. This means, that all
|
||||
state changes will be reverted to the checkpoint state on failure when
|
||||
|
|
@ -59,7 +52,7 @@ types must first be registered with the dispatcher. Once registered the
|
|||
middleware stack or any other handler can call the dispatcher to execute
|
||||
a transaction. Similarly to the execution stack, when executing a
|
||||
transaction the dispatcher isolates the state space available to the
|
||||
designated module (see `Data Store <overview.md#data-store>`__).
|
||||
designated module (see ``Data Store`` below).
|
||||
|
||||
Security Overview
|
||||
-----------------
|
||||
|
|
@ -93,5 +86,3 @@ accessible to it under the assigned key ``bar``. This effectively makes
|
|||
app prefixing invisible to each module while preventing each module from
|
||||
affecting each other module. Under this model no two registered modules
|
||||
are permitted to have the same namespace.
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue