This guide is designed for beginners who want to get started with a Tendermint
Core application from scratch. It does not assume that you have any prior
experience with Tendermint Core.
Tendermint Core is Byzantine Fault Tolerant (BFT) middleware that takes a state
transition machine - written in any programming language - and securely
replicates it on many machines.
Although Tendermint Core is written in the Golang programming language, prior
knowledge of it is not required for this guide. You can learn it as we go due
to it's simplicity. However, you may want to go through Learn X in Y minutes
Where X=Go(opens new window) first to familiarize
yourself with the syntax.
By following along with this guide, you'll create a Tendermint Core project
called kvstore, a (very) simple distributed BFT key-value store.
Tendermint Core communicates with the application through the Application
BlockChain Interface (ABCI). All message types are defined in the protobuf
file(opens new window).
This allows Tendermint Core to run applications written in any programming
language.
Create a file called app.go with the following content:
When a new transaction is added to the Tendermint Core, it will ask the
application to check it (validate the format, signatures, etc.).
Copy
import"bytes"func(app *KVStoreApplication)isValid(tx []byte)(code uint32){// check format
parts := bytes.Split(tx,[]byte("="))iflen(parts)!=2{return1}
key, value := parts[0], parts[1]// check if the same key=value already exists
err := app.db.View(func(txn *badger.Txn)error{
item, err := txn.Get(key)if err !=nil&& err != badger.ErrKeyNotFound {return err
}if err ==nil{return item.Value(func(val []byte)error{if bytes.Equal(val, value){
code =2}returnnil})}returnnil})if err !=nil{panic(err)}return code
}func(app *KVStoreApplication)CheckTx(req abcitypes.RequestCheckTx) abcitypes.ResponseCheckTx {
code := app.isValid(req.Tx)return abcitypes.ResponseCheckTx{Code: code, GasWanted:1}}
Don't worry if this does not compile yet.
If the transaction does not have a form of {bytes}={bytes}, we return 1
code. When the same key=value already exist (same key and value), we return 2
code. For others, we return a zero code indicating that they are valid.
Note that anything with non-zero code will be considered invalid (-1, 100,
etc.) by Tendermint Core.
Valid transactions will eventually be committed given they are not too big and
have enough gas. To learn more about gas, check out "the
specification"(opens new window).
For the underlying key-value store we'll use
badger(opens new window), which is an embeddable,
persistent and fast key-value (KV) database.
When Tendermint Core has decided on the block, it's transfered to the
application in 3 parts: BeginBlock, one DeliverTx per transaction and
EndBlock in the end. DeliverTx are being transfered asynchronously, but the
responses are expected to come in order.
If the transaction is badly formatted or the same key=value already exist, we
again return the non-zero code. Otherwise, we add it to the current batch.
In the current design, a block can include incorrect transactions (those who
passed CheckTx, but failed DeliverTx or transactions included by the proposer
directly). This is done for performance reasons.
Note we can't commit transactions inside the DeliverTx because in such case
Query, which may be called in parallel, will return inconsistent data (i.e.
it will report that some value already exist even when the actual block was not
yet committed).
Commit instructs the application to persist the new state.
Now, when the client wants to know whenever a particular key/value exist, it
will call Tendermint Core RPC /abci_query endpoint, which in turn will call
the application's Query method.
Applications are free to provide their own APIs. But by using Tendermint Core
as a proxy, clients (including light client
package(opens new window)) can leverage
the unified API across different applications. Plus they won't have to call the
otherwise separate Tendermint Core API for additional proofs.
This is a huge blob of code, so let's break it down into pieces.
First, we initialize the Badger database and create an app instance:
Copy
db, err := badger.Open(badger.DefaultOptions("/tmp/badger"))if err !=nil{
fmt.Fprintf(os.Stderr,"failed to open badger db: %v", err)
os.Exit(1)}defer db.Close()
app :=NewKVStoreApplication(db)
For Windows users, restarting this app will make badger throw an error as it requires value log to be truncated. For more information on this, visit here(opens new window).
This can be avoided by setting the truncate option to true, like this:
We use FilePV, which is a private validator (i.e. thing which signs consensus
messages). Normally, you would use SignerRemote to connect to an external
HSM(opens new window).
Copy
$ go mod init github.com/me/example
$ go build
This should build the binary.
To create a default configuration, nodeKey and private validator files, let's
execute tendermint init. But before we do that, we will need to install
Tendermint Core. Please refer to the official
guide(opens new window). If you're
installing from source, don't forget to checkout the latest release (git checkout vX.Y.Z).