fluencelabs/tendermint
1
0
Fork 0
mirror of https://github.com/fluencelabs/tendermint synced 2025-06-23 01:41:31 +00:00
Code Issues Projects Releases Wiki Activity

docs: add docs from website

Browse Source
This commit is contained in:
Zach Ramsay
2017-06-20 15:58:26 -04:00
parent 259111d0e8
commit 6fef4b080e
21 changed files with 2083 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

256
docs/getting-started/#02-first-app.md Normal file
View File

@ -0,0 +1,256 @@
# First Tendermint App
As a general purpose blockchain engine, Tendermint is agnostic to the application you want to run.
So, to run a complete blockchain that does something useful, you must start two programs:
one is Tendermint Core, the other is your application, which can be written in any programming language.
Recall from [the intro to ABCI](/intro/abci-overview) that Tendermint Core handles all the p2p and consensus stuff,
and just forwards transactions to the application when they need to be validated, or when they're ready to be committed to a block.
In this guide, we show you some examples of how to run an application using Tendermint.
## Install
First, make sure you have [installed Tendermint](/download).
The first apps we will work with are written in Go.
To install them, you need to [install Go](https://golang.org/doc/install) and
[put `$GOPATH/bin` in your `$PATH`](https://github.com/tendermint/tendermint/wiki/Setting-GOPATH).
Then run
```
go get -u github.com/tendermint/abci/cmd/...
```
If there is an error, download the `glide` tool to pin the dependencies:
```
go get github.com/Masterminds/glide
cd $GOPATH/src/github.com/tendermint/abci
glide install
go install ./cmd/...
```
Now you should have two apps installed:
```
dummy --help
counter --help
```
Both of these applications are in Go.
But we also want to run an application in another language -
in this case, we'll run a Javascript version of the `counter`.
To run it, you'll need to [install node](https://nodejs.org/en/download/).
You'll also need to fetch the relevant repository, from https://github.com/tendermint/js-abci.
Since I keep all my code under the `$GOPATH`, I just `go get github.com/tendermint/js-abci &> /dev/null`.
Then `cd` into the `example` directory within that repository and run `npm install`.
For instance, if you used `go get`,
```
cd $GOPATH/src/github.com/tendermint/js-abci/example
npm install
```
Now, let's run some apps!
## A First Example - Dummy
The dummy app is a [Merkle tree](https://en.wikipedia.org/wiki/Merkle_tree) that just stores all transactions.
If the transaction contains an `=`, eg. `key=value`,
then the `value` is stored under the `key` in the Merkle tree.
Otherwise, the full transaction bytes are stored as the key and the value.
Let's start a dummy application.
```
dummy
```
In another terminal, we can start Tendermint.
If you have never run Tendermint before, use:
```
tendermint init
tendermint node
```
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](/docs/guides/using-tendermint).
You should see Tendermint making blocks!
We can get the status of our Tendermint node as follows:
```
curl -s localhost:46657/status
```
The `-s` just silences `curl`. For nicer output, pipe the result into a tool like [jq](https://stedolan.github.io/jq/)
or [jsonpp](https://github.com/jmhodges/jsonpp).
Now let's send some transactions to the dummy.
```
curl -s 'localhost:46657/broadcast_tx_commit?tx="abcd"'
```
Note the single quote (`'`) around the url, which ensures that the double quotes (`"`) are not escaped by bash.
This command sent a transaction with bytes `abcd`, so `abcd` will be stored as both the key and the value in the Merkle tree.
The response should look something like:
```
{"jsonrpc":"2.0","id":"","result":[98,{"check_tx":{},"deliver_tx":{}}],"error":""}
```
The `98` is a type-byte, and can be ignored (it's useful for serializing and deserializing arbitrary json).
Otherwise, this result is empty - there's nothing to report on and everything is OK.
We can confirm that our transaction worked and the value got stored by querying the app:
```
curl -s 'localhost:46657/abci_query?data="abcd"&path=""&prove=false'
```
The `path` and `prove` arguments can be ignored for now, and in a future release can be left out.
The result should look like:
```
{"jsonrpc":"2.0","id":"","result":[112,{"response":{"value":"61626364","log":"exists"}}],"error":""}
```
Again, the `112` is the type-byte. Note the `value` in the result (`61626364`); this is the hex-encoding of the ASCII of `abcd`.
You can verify this in a python shell by running `"61626364".decode('hex')`.
Stay tuned for a future release that makes this output more human-readable ;).
Now let's try setting a different key and value:
```
curl -s 'localhost:46657/broadcast_tx_commit?tx="name=satoshi"'
```
Now if we query for `name`, we should get `satoshi`, or `7361746F736869` in hex:
```
curl -s 'localhost:46657/abci_query?data="name"&path=""&prove=false'
```
Try some other transactions and queries to make sure everything is working!
## Another Example - Counter
Now that we've got the hang of it, let's try another application, the "counter" app.
The counter app doesn't use a Merkle tree, it just counts how many times we've sent a transaction,
or committed the state.
This application has two modes: `serial=off` and `serial=on`.
When `serial=on`, transactions must be a big-endian encoded incrementing integer, starting at 0.
If `serial=off`, there are no restrictions on transactions.
In a live blockchain, transactions collect in memory before they are committed into blocks.
To avoid wasting resources on invalid transactions,
ABCI provides the `CheckTx` message,
which application developers can use to accept or reject transactions,
before they are stored in memory or gossipped to other peers.
In this instance of the counter app, with `serial=on`, `CheckTx` only allows transactions whose integer is greater than the last committed one.
Let's kill the previous instance of tendermint and the dummy application, and start the counter app.
We can enable `serial=on` with a flag:
```
counter --serial
```
In another window, reset and start Tendermint:
```
tendermint unsafe_reset_all
tendermint node
```
Once again, you can see the blocks streaming by. Let's send some transactions.
Since we have set `serial=on`, the first transaction must be the number `0`:
```
curl localhost:46657/broadcast_tx_commit?tx=0x00
```
Note the empty, hence successful, response.
The next transaction must be the number `1`. If instead, we try to send a `5`, we get an error:
```
> curl localhost:46657/broadcast_tx_commit?tx=0x05
{"jsonrpc":"2.0","id":"","result":[98,{"check_tx":{},"deliver_tx":{"code":3,"log":"Invalid nonce. Expected 1, got 5"}}],"error":""}
```
But if we send a `1`, it works again:
```
> curl localhost:46657/broadcast_tx_commit?tx=0x01
{"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](/docs/guides/using-tendermint).
## Example in Another Language - CounterJS
The ultimate flexibility in Tendermint comes from being able to easily write the application in any language.
While we already used the implementation written in Go,
let's now try the Counter application written in Javascript!
Kill the previous `counter` and `tendermint` processes.
Change directory to the location of the `github.com/tendermint/js-abci`.
If you fetched the repository with `go get`, it would be
```
cd $GOPATH/src/github.com/tendermint/js-abci
```
Now run the app:
```
node example/app.js
```
In another window, reset and start `tendermint`:
```
tendermint unsafe_reset_all
tendermint node
```
Once again, you should see blocks streaming by - but now, our application is written in javascript!
Try sending some transasctions, like before - the results should be the same:
```
curl localhost:46657/broadcast_tx_commit?tx=0x00 # ok
curl localhost:46657/broadcast_tx_commit?tx=0x05 # invalid nonce
curl localhost:46657/broadcast_tx_commit?tx=0x01 # ok
```
Neat, eh?
## A More Interesting Example - Basecoin
Before concluding, we'd like to introduce you to our star application, [Basecoin](https://github.com/tendermint/basecoin).
Unlike the `dummy` and `counter`, which are strictly for example purposes,
`basecoin` is designed to be actually useful - it's a general purpose framework for building cryptocurrencies.
The default `basecoin` application is a multi-asset cryptocurrency that supports inter-blockchain communication.
For more details on how basecoin works and how to use it, see our [basecoin guide](https://github.com/tendermint/basecoin/blob/develop/docs/guide/basecoin-basics.md)
## Next Step
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, while keeping them all in sync using its state-of-the-art consensus protocol.
This is the subject of the next tutorial, where we show you [how to deploy Tendermint networks](/docs/getting-started/deploy-testnet).

41
docs/getting-started/#03-deploy-testnet.md Normal file
View File

@ -0,0 +1,41 @@
# Deploy a Testnet
Now that we've seen how ABCI works, and even played with a few applications on a single validator node,
it's time to deploy a test network to four validator nodes.
For this deployment, we'll use the `basecoin` application.
## Manual Deployments
It's relatively easy to setup a Tendermint cluster manually.
The only requirements for a particular Tendermint node are a private key for the validator,
stored as `priv_validator.json`, and a list of the public keys of all validators, stored as `genesis.json`.
These files should be stored in `~/.tendermint`, or wherever the `$TMROOT` variable might be set to.
Here are the steps to setting up a testnet manually:
1) Provision nodes on your cloud provider of choice
2) Install Tendermint and the application of interest on all nodes
3) Generate a private key for each validator using `tendermint gen_validator`
4) Compile a list of public keys for each validator into a `genesis.json` file.
5) Run `tendermint node --p2p.seeds=< seed addresses >` on each node, where `< seed addresses >` is a
comma separated list of the IP:PORT combination for each node. The default port for Tendermint is `46656`.
Thus, if the IP addresses of your nodes were `192.168.0.1, 192.168.0.2, 192.168.0.3, 192.168.0.4`,
the command would look like: `tendermint node --p2p.seeds=192.168.0.1:46656,192.168.0.2:46656,192.168.0.3:46656,192.168.0.4:46656`.
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](/docs/guides/using-tendermint).
## Automated Deployments
While the manual deployment is easy enough, an automated deployment is always better.
For this, we have the [mintnet-kubernetes tool](https://github.com/tendermint/mintnet-kubernetes),
which allows us to automate the deployment of a Tendermint network on an already provisioned kubernetes cluster.
For more details, see the [mintnet-kubernetes repo](https://github.com/tendermint/mintnet-kubernetes),
and check out [Google Cloud Platform](https://cloud.google.com/) for simple provisioning of kubernetes clusters.
TODO: a better tutorial here, and Ansible/Terraform.
## Next Steps
Done trying out the testnet? Continue [onwards](/docs/getting-started/next-steps).

21
docs/getting-started/#04-next-steps.md Normal file
View File

@ -0,0 +1,21 @@
# Next Steps
By now you've seen how to run a simple example ABCI application on a local Tendermint node
and on a remote Tendermint cluster.
To learn more about building ABCI applications and integrating with Tendermint, see the [Developer Guides](/docs/guides/app-development).
To learn more about running the Tendermint software, see the [Using Tendermint Guide](/docs/guides/using-tendermint).
To learn more about Tendermint's various pieces, checkout the [Documentation](/docs).
For a deeper dive, see [this thesis](https://atrium.lib.uoguelph.ca/xmlui/handle/10214/9769).
There is also the [original whitepaper](/static/docs/tendermint.pdf), though it is now quite outdated.
The Tendermint [Software Ecosystem](/ecosystem) contains many example applications and related software built by the Tendermint team and others. Check it out for some inspiration!
For details on how the software has changed, and what changes are in store, see the [Changelog](/docs/changelog) and the [Roadmap](/docs/roadmap).
See our [Community](/community) page for more ways to collaborate.
You can also [get in touch with the team](/contact).
Most importantly, enjoy!