From e509e8f354731cbc8c92da239169d8034e657796 Mon Sep 17 00:00:00 2001 From: Zach Ramsay Date: Wed, 30 Aug 2017 22:36:16 -0400 Subject: [PATCH] docs: clean a bunch of stuff up --- docs/abci-cli.rst | 16 ++++++++-------- docs/app-architecture.rst | 7 +++---- docs/app-development.rst | 2 +- docs/block-structure.rst | 4 ++-- docs/byzantine-consensus-algorithm.rst | 9 +++------ docs/deploy-testnets.rst | 16 +++------------- docs/genesis.rst | 2 -- docs/getting-started.rst | 15 ++++++++------- docs/index.rst | 4 ++-- docs/install-from-source.rst | 7 +------ docs/light-client-protocol.rst | 8 ++++---- docs/secure-p2p.rst | 4 ++-- docs/specification.rst | 2 +- docs/using-tendermint.rst | 15 +++------------ docs/validators.rst | 10 +++++----- 15 files changed, 46 insertions(+), 75 deletions(-) diff --git a/docs/abci-cli.rst b/docs/abci-cli.rst index 4dc1a7bd7..6821ae6a8 100644 --- a/docs/abci-cli.rst +++ b/docs/abci-cli.rst @@ -48,7 +48,7 @@ Now run ``abci-cli --help`` to see the list of commands: --help, -h show help --version, -v print the version -First Example - Dummy +Dummy - First Example --------------------- The ``abci-cli`` tool lets us send ABCI messages to our application, to @@ -148,7 +148,7 @@ but if we do ``deliver_tx "abc=efg"`` it will store ``(abc, efg)``. Similarly, you could put the commands in a file and run ``abci-cli --verbose batch < myfile``. -Another Example - Counter +Counter - Another Example ------------------------- Now that we've got the hang of it, let's try another application, the @@ -238,20 +238,20 @@ To run the Node JS version, ``cd`` to ``example/js`` and run window, run the console and those previous ABCI commands. You should get the same results as for the Go version. +Bounties +-------- + Want to write the counter app in your favorite language?! We'd be happy to add you to our `ecosystem `__! We're also offering `bounties `__ for implementations in new languages! -Notes ------ - The ``abci-cli`` is designed strictly for testing and debugging. In a real deployment, the role of sending messages is taken by Tendermint, which connects to the app using three separate connections, each with its own pattern of messages. For more information, see the `application developers -guide `__. For examples of running an ABCI -app with Tendermint, see the `introductory -guide `__. +guide <./app-development.html>`__. For examples of running an ABCI +app with Tendermint, see the `getting started +guide <./getting-started.html>`__. diff --git a/docs/app-architecture.rst b/docs/app-architecture.rst index fe4fb517f..c6deec951 100644 --- a/docs/app-architecture.rst +++ b/docs/app-architecture.rst @@ -58,7 +58,7 @@ Tendermint Core RPC The concept is that the ABCI app is completely hidden from the outside world and only communicated through a tested and secured `interface -exposed by the tendermint core `__. This interface +exposed by the tendermint core <./rpc.html>`__. This interface exposes a lot of data on the block header and consensus process, which is quite useful for externally verifying the system. It also includes 3(!) methods to broadcast a transaction (propose it for the blockchain, @@ -122,7 +122,6 @@ the number of validators, one should be able to scale our read performance to quite an extent (until the replication process drains too many resources from the validator nodes). -Example Code ------------- -- `TMChat `__ +`TMChat `__ is an example of an ABCI +application. diff --git a/docs/app-development.rst b/docs/app-development.rst index 8b41857bc..011fb0f39 100644 --- a/docs/app-development.rst +++ b/docs/app-development.rst @@ -110,7 +110,7 @@ TSP If GRPC is not available in your language, or you require higher performance, or otherwise enjoy programming, you may implement your own -ABCI server using the Tendermint Socket Protocol, known affectionaltely +ABCI server using the Tendermint Socket Protocol, known affectionately as Teaspoon. The first step is still to auto-generate the relevant data types and codec in your language using ``protoc``. Messages coming over the socket are Protobuf3 encoded, but additionally length-prefixed to diff --git a/docs/block-structure.rst b/docs/block-structure.rst index 39cc889e6..92cd9d3fd 100644 --- a/docs/block-structure.rst +++ b/docs/block-structure.rst @@ -120,8 +120,8 @@ Vote Sign Bytes ^^^^^^^^^^^^^^^ The ``sign-bytes`` of a vote is produced by taking a -```stable-json`` `__-like -deterministic JSON ```wire`` `__ encoding of +`stable-json `__-like +deterministic JSON `wire <./wire-protocol.html>`__ encoding of the vote (excluding the ``Signature`` field), and wrapping it with ``{"chain_id":"my_chain","vote":...}``. diff --git a/docs/byzantine-consensus-algorithm.rst b/docs/byzantine-consensus-algorithm.rst index 063767279..0551c2766 100644 --- a/docs/byzantine-consensus-algorithm.rst +++ b/docs/byzantine-consensus-algorithm.rst @@ -1,9 +1,6 @@ Byzantine Consensus Algorithm ============================= -*The draft 0.6 whitepaper is outdated. The new algorithm is detailed -below. See `revisions <#revisions>`__* - Terms ----- @@ -23,7 +20,7 @@ Terms for something. - A vote *at* ``(H,R)`` is a vote signed with the bytes for ``H`` and ``R`` included in its - ```sign-bytes`` `__. + `sign-bytes `__. - *+2/3* is short for "more than 2/3" - *1/3+* is short for "1/3 or more" - A set of +2/3 of prevotes for a particular block or ```` at @@ -261,7 +258,7 @@ in the commit-set) are each justified in the JSet with no duplicitous vote signatures (by the committers). - **Lemma**: When a fork is detected by the existence of two - conflicting `commits `__, + conflicting `commits <./validators.html#commiting-a-block>`__, the union of the JSets for both commits (if they can be compiled) must include double-signing by at least 1/3+ of the validator set. **Proof**: The commit cannot be at the same round, because that would @@ -304,7 +301,7 @@ Censorship Attacks ~~~~~~~~~~~~~~~~~~ Due to the definition of a block -`commit `__, any 1/3+ +`commit `__, any 1/3+ coalition of validators can halt the blockchain by not broadcasting their votes. Such a coalition can also censor particular transactions by rejecting blocks that include these transactions, though this would diff --git a/docs/deploy-testnets.rst b/docs/deploy-testnets.rst index e74889700..66cee8cd4 100644 --- a/docs/deploy-testnets.rst +++ b/docs/deploy-testnets.rst @@ -34,7 +34,7 @@ Here are the steps to setting up a testnet manually: After a few seconds, all the nodes should connect to eachother and start making blocks! For more information, see the Tendermint Networks section -of `the guide to using Tendermint `__. +of `the guide to using Tendermint `__. Automated Deployments --------------------- @@ -43,15 +43,5 @@ While the manual deployment is easy enough, an automated deployment is always better. For this, we have the `mintnet-kubernetes tool `__, which allows us to automate the deployment of a Tendermint network on an -already provisioned kubernetes cluster. - -For more details, see the `mintnet-kubernetes -directory `__, -and check out `Google Cloud Platform `__ for -simple provisioning of kubernetes clusters. - -Next Steps ----------- - -Done trying out the testnet? Continue -`onwards `__. +already provisioned kubernetes cluster. And for simple provisioning of kubernetes +cluster, check out the `Google Cloud Platform `__. diff --git a/docs/genesis.rst b/docs/genesis.rst index b767375b7..32dd19632 100644 --- a/docs/genesis.rst +++ b/docs/genesis.rst @@ -30,8 +30,6 @@ Fields Sample genesis.json ~~~~~~~~~~~~~~~~~~~ -This example is from the Basecoin mintnet example: - .. code:: json { diff --git a/docs/getting-started.rst b/docs/getting-started.rst index 807e24717..6745b482a 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -52,7 +52,7 @@ application written in Javascript. Now, let's run some apps! -A First Example - Dummy +Dummy - A First Example ----------------------- The dummy app is a `Merkle @@ -80,7 +80,7 @@ If you have used Tendermint, you may want to reset the data for a new blockchain by running ``tendermint unsafe_reset_all``. Then you can run ``tendermint node`` to start Tendermint, and connect to the app. For more details, see `the guide on using -Tendermint `__. +Tendermint <./using-tendermint.html>`__. You should see Tendermint making blocks! We can get the status of our Tendermint node as follows: @@ -149,7 +149,7 @@ Now if we query for ``name``, we should get ``satoshi``, or Try some other transactions and queries to make sure everything is working! -Another Example - Counter +Counter - Another Example ------------------------- Now that we've got the hang of it, let's try another application, the @@ -214,9 +214,9 @@ But if we send a ``1``, it works again: {"jsonrpc":"2.0","id":"","result":[98,{"check_tx":{},"deliver_tx":{}}],"error":""} For more details on the ``broadcast_tx`` API, see `the guide on using -Tendermint `__. +Tendermint <./using-tendermint.html>`__. -Example in Another Language - CounterJS +CounterJS - Example in Another Language --------------------------------------- We also want to run applications in another language - in this case, @@ -258,7 +258,7 @@ like before - the results should be the same: Neat, eh? -A More Interesting Example - Basecoin +Basecoin - A More Interesting Example ------------------------------------- We saved the best for last; the `Cosmos SDK `__ is a general purpose framework for building cryptocurrencies. Unlike the``dummy`` and ``counter``, which are strictly for example purposes. The reference implementation of Cosmos SDK is ``basecoin``, which demonstrates how to use the building blocks of the Cosmos SDK. @@ -268,7 +268,8 @@ that supports inter-blockchain communication. For more details on how basecoin works and how to use it, see our `basecoin guide `__ -In this tutorial you learned how to run applications using Tendermint on a single node. You saw how applications could be written in different +In this tutorial you learned how to run applications using Tendermint +on a single node. You saw how applications could be written in different languages, and how to send transactions and query for the latest state. But the true power of Tendermint comes from its ability to securely and efficiently run an application across a distributed network of nodes, diff --git a/docs/index.rst b/docs/index.rst index 494096d8d..a219532a8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,7 +11,7 @@ Tendermint 101: .. maxdepth set to 2 for sexiness .. but use 4 to upgrade documentation .. toctree:: - :maxdepth: 4 + :maxdepth: 2 introduction.rst install-from-source.rst @@ -22,7 +22,7 @@ Tendermint 101: Tendermint 102: .. toctree:: - :maxdepth: 4 + :maxdepth: 2 abci-cli.rst app-architecture.rst diff --git a/docs/install-from-source.rst b/docs/install-from-source.rst index 34d348463..b353aba87 100644 --- a/docs/install-from-source.rst +++ b/docs/install-from-source.rst @@ -2,7 +2,7 @@ Install from Source =================== This page provides instructions on installing Tendermint from source. To -download pre-built binaries, see the `Download page `__. +download pre-built binaries, see the `Download page `__. Install Go ---------- @@ -100,8 +100,3 @@ To start a one-node blockchain with a simple in-process application: tendermint init tendermint node --proxy_app=dummy - -See the `App Development `__ guide for -more details on building applications, and the `Using -Tendermint `__ guide for more details -about using the ``tendermint`` program. diff --git a/docs/light-client-protocol.rst b/docs/light-client-protocol.rst index c344a5671..e2d5ea76a 100644 --- a/docs/light-client-protocol.rst +++ b/docs/light-client-protocol.rst @@ -12,18 +12,18 @@ Overview -------- The objective of the light client protocol is to get a -`commit `__ for a recent -`block hash `__ where the commit +`commit <./validators.html#committing-a-block>`__ for a recent +`block hash <./block-structure.html#block-hash>`__ where the commit includes a majority of signatures from the last known validator set. From there, all the application state is verifiable with `merkle -proofs `__. +proofs <./merkle-trees#iavl-tree>`__. Properties ---------- - You get the full collateralized security benefits of Tendermint; No need to wait for confirmations. -- You get the full speed benefits of Tendermint; Transactions commit +- You get the full speed benefits of Tendermint; transactions commit instantly. - You can get the most recent version of the application state non-interactively (without committing anything to the blockchain). diff --git a/docs/secure-p2p.rst b/docs/secure-p2p.rst index 67ce3ea37..c48ddb590 100644 --- a/docs/secure-p2p.rst +++ b/docs/secure-p2p.rst @@ -62,8 +62,8 @@ such as the Web-of-Trust or Certificate Authorities. In our case, we can use the blockchain itself as a certificate authority to ensure that we are connected to at least one validator. -Links ------ +Additional Reading +------------------ - `Implementation `__ - `Original STS paper by Whitfield Diffie, Paul C. van Oorschot and diff --git a/docs/specification.rst b/docs/specification.rst index d2e2b2172..02d84c343 100644 --- a/docs/specification.rst +++ b/docs/specification.rst @@ -2,7 +2,7 @@ Specification ############# -Here you'll details of the Tendermint specification. See `the spec repo `__ for upcoming material. Tendermint's types are produced by `godoc `__ +Here you'll find details of the Tendermint specification. See `the spec repo `__ for upcoming material. Tendermint's types are produced by `godoc `__ .. toctree:: :maxdepth: 2 diff --git a/docs/using-tendermint.rst b/docs/using-tendermint.rst index 5d7f95c90..a4e16a1f7 100644 --- a/docs/using-tendermint.rst +++ b/docs/using-tendermint.rst @@ -2,7 +2,7 @@ Using Tendermint ================ This is a guide to using the ``tendermint`` program from the command -line. It assumes only that you `have tendermint installed `__ +line. It assumes only that you have the ``tendermint`` binary installed and have some rudimentary idea of what Tendermint and ABCI are. You can see the help menu with ``tendermint --help``, and the version @@ -117,7 +117,7 @@ Configuration ------------- Tendermint uses a ``config.toml`` for configutation. For details, see -`the documentation `__. +`the documentation <./configuration.html>`__. Notable options include the socket address of the application (``proxy_app``), the listenting address of the tendermint peer @@ -342,7 +342,7 @@ failing, you need at least four validator nodes (> 2/3). Updating validators in a live network is supported but must be explicitly programmed by the application developer. See the `application -developers guide `__ for more +developers guide <./app-development.html#Handshake>`__ for more details. Local Network @@ -354,12 +354,3 @@ the listening addresses of the various sockets don't conflict. Additionally, you must set ``addrbook_strict=false`` in the ``config.toml``, otherwise Tendermint's p2p library will deny making connections to peers with the same IP address. - -More ----- - -Got a couple nodes talking to each other using the dummy app? Try a more -sophisticated app like -`Ethermint `__, or learn more -about building your own in the `Application Developer's -Guide `__. diff --git a/docs/validators.rst b/docs/validators.rst index 283d54246..528ebab7e 100644 --- a/docs/validators.rst +++ b/docs/validators.rst @@ -25,7 +25,7 @@ Becoming a Validator There are two ways to become validator. 1. They can be pre-established in the `genesis - state `__ + state <./genesis.html>`__ 2. The `ABCI app responds to the EndBlock message `__ with changes to the existing validator set. @@ -36,9 +36,9 @@ Committing a Block *+2/3 is short for "more than 2/3"* A block is committed when +2/3 of the validator set sign `precommit -votes `__ for that block at the same -`round `__. The +2/3 set of precommit votes is -called a `*commit* `__. While any +votes <./block-structure.html#vote>`__ for that block at the same +``round``. The +2/3 set of precommit votes is +called a `*commit* <./block-structure.html#commit>`__. While any +2/3 set of precommits for the same block at the same height&round can serve as validation, the canonical commit is included in the next block -(see `LastCommit `__. +(see `LastCommit <./block-structure.html>`__).