# Creating a built-in application in Go
# Guide assumptions
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 a service that provides a Byzantine fault tolerant consensus engine for state-machine replication. The replicated state-machine, or "application", can be written in any language that can send and receive protocol buffer messages.
This tutorial is written for Go and uses Tendermint as a library, but applications not written in Go can use Tendermint to drive state-machine replication in a client-server model.
This tutorial expects some understanding of the Go programming language. If you have never written Go, 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 application called kvstore, a (very) simple distributed BFT key-value store.
Note: please use a released version of Tendermint with this guide. The guides will work with the latest released version. Be aware that they may not apply to unreleased changes on master. We strongly advise against using unreleased commits for your development.
# 1.1 Installing Go
Please refer to the official guide for installing Go (opens new window).
Verify that you have the latest version of Go installed:
Note that the exact patch number may differ as Go releases come out.
# 1.2 Creating a new Go project
We'll start by creating a new Go project.
Inside the example directory create a
main.go file with the following content:
Note: there is no need to clone or fork Tendermint in this tutorial.
When run, this should print "Hello, Tendermint Core" to the standard output.
# 1.3 Writing a Tendermint Core application
Tendermint Core communicates with an application through the Application BlockChain Interface (ABCI) protocol. All of the message types Tendermint uses for communicating with the application can be found in the ABCI protobuf file (opens new window).
We will begin by creating the basic scaffolding for an ABCI application in
app.go file. The first step is to create a new type,
with methods that implement the abci
Create a file called
app.go and add the following contents:
# 1.3.1 Add a persistent data store
Our application will need to write its state out to persistent storage so that it can stop and start without losing all of its data.
For this tutorial, we will use BadgerDB (opens new window). Badger is a fast embedded key-value store.
First, add Badger as a dependency of your go module using the
go get command:
go get github.com/dgraph-io/badger/v3
Next, let's update the application and its constructor to receive a handle to the database.
Update the application struct as follows:
And change the constructor to set the appropriate field when creating the application:
pendingBlock keeps track of the transactions that will update the application's
state when a block is completed. Don't worry about it for now, we'll get to that later.
Finally, update the
import stanza at the top to include the
# 1.3.1 CheckTx
When Tendermint Core receives a new transaction, Tendermint asks the application if the transaction is acceptable. In our new application, let's implement some basic validation for the transactions it will receive.
For our KV store application, a transaction is a string with the form
indicating a key and value to write to the store.
Add the following helper method to
And call it from within your
Any response with a non-zero code will be considered invalid by Tendermint.
CheckTx logic returns
0 to Tendermint when a transaction passes
its validation checks. The specific value of the code is meaningless to Tendermint.
Non-zero codes are logged by Tendermint so applications can provide more specific
information on why the transaction was rejected.
CheckTx does not execute the transaction, it only verifies that that the
transaction could be executed. We do not know yet if the rest of the network has
agreed to accept this transaction into a block.
Finally, make sure to add the
bytes package to the your import stanza
at the top of
CheckTx is simple and only validates that the transaction is well-formed,
it is very common for
CheckTx to make more complex use of the state of an application.
# 1.3.2 BeginBlock -> DeliverTx -> EndBlock -> Commit
When the Tendermint consensus engine has decided on the block, the block is transferred to the
application over three ABCI method calls:
BeginBlock is called once to indicate to the application that it is about to
receive a block.
DeliverTx is called repeatedly, once for each
Tx that was included in the block.
EndBlock is called once to indicate to the application that no more transactions
will be delivered to the application.
To implement these calls in our application we're going to make use of Badger's transaction mechanism. Bagder uses the term transaction in the context of databases, be careful not to confuse it with blockchain transactions.
First, let's create a new Badger
Next, let's modify
DeliverTx to add the
value to the database
Txn every time our application
receives a new
Note that we check the validity of the transaction again during
Transactions are not guaranteed to be valid when they are delivered to an
application. This can happen if the application state is used to determine transaction
validity. Application state may have changed between when the
CheckTx was initially
called and when the transaction was delivered in
DeliverTx in a way that rendered
the transaction no longer valid.
Also note that we don't commit the Badger
Txn we are building during
Other methods, such as
Query, rely on a consistent view of the application's state.
The application should only update its state when the full block has been delivered.
Commit method indicates that the full block has been delivered. During
the application should persist the pending
Let's modify our
Commit method to persist the new state to the database:
Finally, make sure to add the
log library to the
import stanza as well:
You may have noticed that the application we are writing will crash if it receives an
unexpected error from the database during the
This is not an accident. If the application received an error from the database,
there is no deterministic way for it to make progress so the only safe option is to terminate.
# 1.3.3 Query Method
We'll want to be able to determine if a transaction was committed to the state-machine.
To do this, let's implement the
Query method in
# 1.3.4 Additional Methods
You'll notice that we left several methods unchanged. Specifically, we have yet
to implement the
InitChain methods and we did not implement
any of the
*Snapthot methods. These methods are all important for running Tendermint
applications in production but are not required for getting a very simple application
up and running.
To better understand these methods and why they are useful, check out the Tendermint specification on ABCI (opens new window).
# 1.4 Starting an application and a Tendermint Core instance in the same process
Now that we have the basic functionality of our application in place, let's put it
all together inside of our
Add the following code to your
This is a huge blob of code, so let's break down what it's doing.
First, we load in the Tendermint Core configuration files:
Next, we create a database handle and use it to construct our ABCI application:
Then we construct a logger:
Now we have everything setup to run the Tendermint node. We construct a node by passing it the configuration, the logger, a handle to our application and the genesis file:
Finally, we start the node:
The additional logic at the end of the file allows the program to catch
This means that the node can shutdown gracefully when an operator tries to kill the program:
# 1.5 Getting Up and Running
Our application is almost ready to run. Let's install the latest release version of the Tendermint library.
From inside of the project directory, run:
Next, we'll need to populate the Tendermint Core configuration files.
This command will create a
tendermint-home directory in your project and add a basic set of configuration
tendermint-home/config/. For more information on what these files contain
see the configuration documentation (opens new window).
From the root of your project, run:
Next, build the application:
Everything is now in place to run your application.
The application will begin producing blocks and you can see this reflected in the log output.
You now have successfully started running an application using Tendermint Core 🎉🎉.
# 1.6 Using the application
Your application is now running and emitting logs to the terminal. Now it's time to see what this application can do!
Let's try submitting a transaction to our new application.
Open another terminal window and run the following curl command:
If everything went well, you should see a response indicating which height the transaction was included in the blockchain.
Finally, let's make sure that transaction really was persisted by the application.
Run the following command:
Let's examine the response object that this request returns.
The request returns a
json object with a
value field set.
Those values don't look like the
value we sent to Tendermint,
what's going on here?
The response contain a
base64 encoded representation of the data we submitted.
To get the original value out of this data, we can use the
base64 command line utility.
I hope everything went smoothly and your first, but hopefully not the last, Tendermint Core application is up and running. If not, please open an issue on Github (opens new window). To dig deeper, read the docs (opens new window).