From 2738c22798ad2adc078a2562b3cade6677411afe Mon Sep 17 00:00:00 2001 From: Zach Ramsay Date: Fri, 1 Sep 2017 22:44:50 -0400 Subject: [PATCH] docs: edits for rst & other cleanup --- docs/basecoin-basics.rst | 91 +++++++++++++++++++++++++--------------- docs/basecoin-tool.rst | 84 +++++++++++++++++++++++-------------- docs/overview.rst | 23 ++++------ 3 files changed, 117 insertions(+), 81 deletions(-) diff --git a/docs/basecoin-basics.rst b/docs/basecoin-basics.rst index 2922269a0..099b4c4ec 100644 --- a/docs/basecoin-basics.rst +++ b/docs/basecoin-basics.rst @@ -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 `__. +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
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 `__. 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 @@ -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 `__, 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 `__, 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``. diff --git a/docs/basecoin-tool.rst b/docs/basecoin-tool.rst index 898a5069f..020c8bb4b 100644 --- a/docs/basecoin-tool.rst +++ b/docs/basecoin-tool.rst @@ -54,31 +54,33 @@ . $DIR/shunit2 --> -The Basecoin Tool +Basecoin The Tool ================= -In previous tutorials we learned the `basics of the Basecoin -CLI `__ and `how to implement a -plugin `__. 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 `__. +See the `tendermint documentation `__ 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 `__. +``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 `__. +Note we have also left out the details of the Tendermint genesis. See the +`Tendermint documentation `__ 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, diff --git a/docs/overview.rst b/docs/overview.rst index 05934ad0e..22d26c5f8 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -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 `__ and -`glossary `__ documentation. - -For a more interconnected schematics see these -`framework `__ and -`security `__ 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 `__ +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 `__). 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 `__). +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. - -