mirrors/tendermint
1
0
Fork 0
mirror of https://github.com/tendermint/tendermint.git synced 2026-04-25 02:00:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: updates go.md and go-built-in.md as part of issue 9272 (#9688)

Browse Source 
* Updates the go.md and go-built-in.md tutorials. This is heavily based on the latest version of the tutorial from branch v0.35.0-rc0
* Includes section for Prepare and ProcessProposal
* Updates output of abci-cli example
* Removes broken example in JS
* Fixes mentions to 1/3 and 2/3 and other small edits
This commit is contained in:
Lasaro Camargos
2022-11-18 12:06:56 -03:00
committed by GitHub
parent 2b4436d1b4
commit f9bfdf4ce2
5 changed files with 1148 additions and 892 deletions
Download Patch File Download Diff File Expand all files Collapse all files

128
docs/app-dev/abci-cli.md
View File

@@ -27,22 +27,28 @@ Usage:
abci-cli [command] abci-cli [command]
Available Commands: Available Commands:
batch Run a batch of abci commands against an application batch run a batch of abci commands against an application
check_tx Validate a tx check_tx validate a transaction
commit Commit the application state and return the Merkle root hash commit commit the application state and return the Merkle root hash
console Start an interactive abci console for multiple commands completion Generate the autocompletion script for the specified shell
deliver_tx Deliver a new tx to the application console start an interactive ABCI console for multiple commands
kvstore ABCI demo example deliver_tx deliver a new transaction to the application
echo Have the application echo a message echo have the application echo a message
help Help about any command help Help about any command
info Get some info about the application info get some info about the application
query Query the application state kvstore ABCI demo example
prepare_proposal prepare proposal
process_proposal process proposal
query query the application state
test run integration tests
version print ABCI console version
Flags: Flags:
--abci string socket or grpc (default "socket") --abci string either socket or grpc (default "socket")
--address string address of application socket (default "tcp://127.0.0.1:26658") --address string address of application socket (default "tcp://0.0.0.0:26658")
-h, --help help for abci-cli -h, --help help for abci-cli
-v, --verbose print the command and results as if it were a console session --log_level string set the logger level (default "debug")
-v, --verbose print the command and results as if it were a console session
Use "abci-cli [command] --help" for more information about a command. Use "abci-cli [command] --help" for more information about a command.
``` ```
@@ -58,47 +64,51 @@ purposes.
We'll start a kvstore application, which was installed at the same time We'll start a kvstore application, which was installed at the same time
as `abci-cli` above. The kvstore just stores transactions in a merkle as `abci-cli` above. The kvstore just stores transactions in a merkle
tree. tree. Its code can be found
[here](https://github.com/tendermint/tendermint/blob/main/abci/cmd/abci-cli/abci-cli.go)
Its code can be found and looks like the following:
[here](https://github.com/tendermint/tendermint/blob/v0.34.x/abci/cmd/abci-cli/abci-cli.go)
and looks like:
```go ```go
func cmdKVStore(cmd *cobra.Command, args []string) error { func cmdKVStore(cmd *cobra.Command, args []string) error {
logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout)) logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout))
// Create the application - in memory or persisted to disk // Create the application - in memory or persisted to disk
var app types.Application var app types.Application
if flagPersist == "" { if flagPersist == "" {
app = kvstore.NewKVStoreApplication() var err error
} else { flagPersist, err = os.MkdirTemp("", "persistent_kvstore_tmp")
app = kvstore.NewPersistentKVStoreApplication(flagPersist) if err != nil {
app.(*kvstore.PersistentKVStoreApplication).SetLogger(logger.With("module", "kvstore")) return err
} }
}
app = kvstore.NewPersistentKVStoreApplication(flagPersist)
app.(*kvstore.PersistentKVStoreApplication).SetLogger(logger.With("module", "kvstore"))
// Start the listener // Start the listener
srv, err := server.NewServer(flagAddrD, flagAbci, app) srv, err := server.NewServer(flagAddress, flagAbci, app)
if err != nil { if err != nil {
return err return err
} }
srv.SetLogger(logger.With("module", "abci-server")) srv.SetLogger(logger.With("module", "abci-server"))
if err := srv.Start(); err != nil { if err := srv.Start(); err != nil {
return err return err
} }
// Stop upon receiving SIGTERM or CTRL-C. // Stop upon receiving SIGTERM or CTRL-C.
tmos.TrapSignal(logger, func() { tmos.TrapSignal(logger, func() {
// Cleanup // Cleanup
srv.Stop() if err := srv.Stop(); err != nil {
}) logger.Error("Error while stopping server", "err", err)
}
})
// Run forever. // Run forever.
select {} select {}
} }
``` ```
Start by running: Start the application by running:
```sh ```sh
abci-cli kvstore abci-cli kvstore
@@ -170,7 +180,7 @@ Try running these commands:
> prepare_proposal "abc" > prepare_proposal "abc"
-> code: OK -> code: OK
-> log: Succeeded. Tx: abc action: UNMODIFIED -> log: Succeeded. Tx: abc
> process_proposal "abc" > process_proposal "abc"
-> code: OK -> code: OK
@@ -219,11 +229,9 @@ Try running these commands:
> prepare_proposal "preparedef" > prepare_proposal "preparedef"
-> code: OK -> code: OK
-> log: Succeeded. Tx: def action: ADDED -> log: Succeeded. Tx: replacedef
-> code: OK
-> log: Succeeded. Tx: preparedef action: REMOVED
> process_proposal "def" > process_proposal "replacedef"
-> code: OK -> code: OK
-> status: ACCEPT -> status: ACCEPT
@@ -245,21 +253,21 @@ Try running these commands:
Note that if we do `deliver_tx "abc"` it will store `(abc, abc)`, but if Note that if we do `deliver_tx "abc"` it will store `(abc, abc)`, but if
we do `deliver_tx "abc=efg"` it will store `(abc, efg)`. we do `deliver_tx "abc=efg"` it will store `(abc, efg)`.
Similarly, you could put the commands in a file and run You could put the commands in a file and run
`abci-cli --verbose batch < myfile`. `abci-cli --verbose batch < myfile`.
Note that 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 examples of running an ABCI app with Tendermint, see the
[getting started guide](./getting-started.md).
## Bounties ## Bounties
Want to write an app in your favorite language?! We'd be happy Want to write an app in your favorite language?! We'd be happy
to add you to our [ecosystem](https://github.com/tendermint/awesome#ecosystem)! to add you to our [ecosystem](https://github.com/tendermint/awesome#ecosystem)!
See [funding](https://github.com/interchainio/funding) opportunities from the See [funding](https://github.com/interchainio/funding) opportunities from the
[Interchain Foundation](https://interchain.io) for implementations in new languages and more. [Interchain Foundation](https://interchain.io) for implementations in new languages and more.
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 examples of running an ABCI app with
Tendermint, see the [getting started guide](./getting-started.md).
Next is the ABCI specification.

95
docs/app-dev/getting-started.md
View File

@@ -11,9 +11,10 @@ application you want to run. So, to run a complete blockchain that does
something useful, you must start two programs: one is Tendermint Core, something useful, you must start two programs: one is Tendermint Core,
the other is your application, which can be written in any programming the other is your application, which can be written in any programming
language. Recall from [the intro to language. Recall from [the intro to
ABCI](../introduction/what-is-tendermint.md#abci-overview) that Tendermint Core handles all the p2p and consensus stuff, and just forwards transactions to the ABCI](../introduction/what-is-tendermint.md#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 application when they need to be validated, or when they're ready to be
committed to a block. executed and committed.
In this guide, we show you some examples of how to run an application In this guide, we show you some examples of how to run an application
using Tendermint. using Tendermint.
@@ -22,7 +23,8 @@ using Tendermint.
The first apps we will work with are written in Go. To install them, you The first apps we will work with are written in Go. To install them, you
need to [install Go](https://golang.org/doc/install), put need to [install Go](https://golang.org/doc/install), put
`$GOPATH/bin` in your `$PATH` and enable go modules with these instructions: `$GOPATH/bin` in your `$PATH` and enable go modules. If you use `bash`,
follow these instructions:
```bash ```bash
echo export GOPATH=\"\$HOME/go\" >> ~/.bash_profile echo export GOPATH=\"\$HOME/go\" >> ~/.bash_profile
@@ -31,17 +33,48 @@ echo export PATH=\"\$PATH:\$GOPATH/bin\" >> ~/.bash_profile
Then run Then run
```sh ```bash
go get github.com/tendermint/tendermint go get github.com/tendermint/tendermint
cd $GOPATH/src/github.com/tendermint/tendermint cd $GOPATH/src/github.com/tendermint/tendermint
make install_abci make install_abci
``` ```
Now you should have the `abci-cli` installed; you'll notice the `kvstore` Now you should have the `abci-cli` installed; run `abci-cli` to see the list of commands:
command, an example application written
in Go. See below for an application written in JavaScript.
Now, let's run some apps! ```
Usage:
abci-cli [command]
Available Commands:
batch run a batch of abci commands against an application
check_tx validate a transaction
commit commit the application state and return the Merkle root hash
completion Generate the autocompletion script for the specified shell
console start an interactive ABCI console for multiple commands
deliver_tx deliver a new transaction to the application
echo have the application echo a message
help Help about any command
info get some info about the application
kvstore ABCI demo example
prepare_proposal prepare proposal
process_proposal process proposal
query query the application state
test run integration tests
version print ABCI console version
Flags:
--abci string either socket or grpc (default "socket")
--address string address of application socket (default "tcp://0.0.0.0:26658")
-h, --help help for abci-cli
--log_level string set the logger level (default "debug")
-v, --verbose print the command and results as if it were a console session
Use "abci-cli [command] --help" for more information about a command.
```
You'll notice the `kvstore` command, an example application written in Go.
Now, let's run an app!
## KVStore - A First Example ## KVStore - A First Example
@@ -68,7 +101,7 @@ tendermint node
``` ```
If you have used Tendermint, you may want to reset the data for a new 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 blockchain by running `tendermint unsafe-reset-all`. Then you can run
`tendermint node` to start Tendermint, and connect to the app. For more `tendermint node` to start Tendermint, and connect to the app. For more
details, see [the guide on using Tendermint](../tendermint-core/using-tendermint.md). details, see [the guide on using Tendermint](../tendermint-core/using-tendermint.md).
@@ -164,47 +197,3 @@ curl -s 'localhost:26657/abci_query?data="name"'
Try some other transactions and queries to make sure everything is Try some other transactions and queries to make sure everything is
working! working!
## CounterJS - Example in Another Language
We also want to run applications 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
[here](https://github.com/tendermint/js-abci), then install it:
```sh
git clone https://github.com/tendermint/js-abci.git
cd js-abci
npm install abci
```
Kill the previous `counter` and `tendermint` processes. Now run the app:
```sh
node example/counter.js
```
In another window, reset and start `tendermint`:
```sh
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 transactions, and
like before - the results should be the same:
```sh
# ok
curl localhost:26657/broadcast_tx_commit?tx=0x00
# invalid nonce
curl localhost:26657/broadcast_tx_commit?tx=0x05
# ok
curl localhost:26657/broadcast_tx_commit?tx=0x01
```
Neat, eh?

59
docs/introduction/what-is-tendermint.md
View File

@@ -6,7 +6,7 @@ order: 4
Tendermint is software for securely and consistently replicating an Tendermint is software for securely and consistently replicating an
application on many machines. By securely, we mean that Tendermint works application on many machines. By securely, we mean that Tendermint works
even if up to 1/3 of machines fail in arbitrary ways. By consistently, as long as less than 1/3 of machines fail in arbitrary ways. By consistently,
we mean that every non-faulty machine sees the same transaction log and we mean that every non-faulty machine sees the same transaction log and
computes the same state. Secure and consistent replication is a computes the same state. Secure and consistent replication is a
fundamental problem in distributed systems; it plays a critical role in fundamental problem in distributed systems; it plays a critical role in
@@ -22,15 +22,14 @@ reformalization of BFT in a more modern setting, with emphasis on
peer-to-peer networking and cryptographic authentication. The name peer-to-peer networking and cryptographic authentication. The name
derives from the way transactions are batched in blocks, where each derives from the way transactions are batched in blocks, where each
block contains a cryptographic hash of the previous one, forming a block contains a cryptographic hash of the previous one, forming a
chain. In practice, the blockchain data structure actually optimizes BFT chain.
design.
Tendermint consists of two chief technical components: a blockchain Tendermint consists of two chief technical components: a blockchain
consensus engine and a generic application interface. The consensus consensus engine and a generic application interface. The consensus
engine, called Tendermint Core, ensures that the same transactions are engine, called Tendermint Core, ensures that the same transactions are
recorded on every machine in the same order. The application interface, recorded on every machine in the same order. The application interface,
called the Application BlockChain Interface (ABCI), enables the called the Application BlockChain Interface (ABCI), delivers the transactions
transactions to be processed in any programming language. Unlike other to applications for processing. Unlike other
blockchain and consensus solutions, which come pre-packaged with built blockchain and consensus solutions, which come pre-packaged with built
in state machines (like a fancy key-value store, or a quirky scripting in state machines (like a fancy key-value store, or a quirky scripting
language), developers can use Tendermint for BFT state machine language), developers can use Tendermint for BFT state machine
@@ -51,13 +50,13 @@ Hyperledger's Burrow.
### Zookeeper, etcd, consul ### Zookeeper, etcd, consul
Zookeeper, etcd, and consul are all implementations of a key-value store Zookeeper, etcd, and consul are all implementations of key-value stores
atop a classical, non-BFT consensus algorithm. Zookeeper uses a version atop a classical, non-BFT consensus algorithm. Zookeeper uses an
of Paxos called Zookeeper Atomic Broadcast, while etcd and consul use algorithm called Zookeeper Atomic Broadcast, while etcd and consul use
the Raft consensus algorithm, which is much younger and simpler. A the Raft log replication algorithm. A
typical cluster contains 3-5 machines, and can tolerate crash failures typical cluster contains 3-5 machines, and can tolerate crash failures
in up to 1/2 of the machines, but even a single Byzantine fault can in less than 1/2 of the machines (e.g., 1 out of 3 or 2 out of 5),
destroy the system. but even a single Byzantine fault can jeopardize the whole system.
Each offering provides a slightly different implementation of a Each offering provides a slightly different implementation of a
featureful key-value store, but all are generally focused around featureful key-value store, but all are generally focused around
@@ -66,8 +65,8 @@ configuration, service discovery, locking, leader-election, and so on.
Tendermint is in essence similar software, but with two key differences: Tendermint is in essence similar software, but with two key differences:
- It is Byzantine Fault Tolerant, meaning it can only tolerate up to a - It is Byzantine Fault Tolerant, meaning it can only tolerate less than 1/3
1/3 of failures, but those failures can include arbitrary behavior - of machines failing, but those failures can include arbitrary behavior -
including hacking and malicious attacks. - It does not specify a including hacking and malicious attacks. - It does not specify a
particular application, like a fancy key-value store. Instead, it particular application, like a fancy key-value store. Instead, it
focuses on arbitrary state machine replication, so developers can build focuses on arbitrary state machine replication, so developers can build
@@ -106,8 +105,8 @@ docker containers, modules it calls "chaincode". It uses an
implementation of [PBFT](http://pmg.csail.mit.edu/papers/osdi99.pdf). implementation of [PBFT](http://pmg.csail.mit.edu/papers/osdi99.pdf).
from a team at IBM that is [augmented to handle potentially from a team at IBM that is [augmented to handle potentially
non-deterministic non-deterministic
chaincode](https://drops.dagstuhl.de/opus/volltexte/2017/7093/pdf/LIPIcs-OPODIS-2016-24.pdf) It is chaincode](https://drops.dagstuhl.de/opus/volltexte/2017/7093/pdf/LIPIcs-OPODIS-2016-24.pdf).
possible to implement this docker-based behavior as a ABCI app in It is possible to implement this docker-based behavior as an ABCI app in
Tendermint, though extending Tendermint to handle non-determinism Tendermint, though extending Tendermint to handle non-determinism
remains for future work. remains for future work.
@@ -143,24 +142,22 @@ in design and suffers from "spaghetti code".
Another problem with monolithic design is that it limits you to the Another problem with monolithic design is that it limits you to the
language of the blockchain stack (or vice versa). In the case of language of the blockchain stack (or vice versa). In the case of
Ethereum which supports a Turing-complete bytecode virtual-machine, it Ethereum which supports a Turing-complete bytecode virtual-machine, it
limits you to languages that compile down to that bytecode; today, those limits you to languages that compile down to that bytecode; while the
are Serpent and Solidity. [list](https://github.com/pirapira/awesome-ethereum-virtual-machine#programming-languages-that-compile-into-evm)
is growing, it is still very limited.
In contrast, our approach is to decouple the consensus engine and P2P In contrast, our approach is to decouple the consensus engine and P2P
layers from the details of the application state of the particular layers from the details of the state of the particular
blockchain application. We do this by abstracting away the details of blockchain application. We do this by abstracting away the details of
the application to an interface, which is implemented as a socket the application to an interface, which is implemented as a socket
protocol. protocol.
Thus we have an interface, the Application BlockChain Interface (ABCI),
and its primary implementation, the Tendermint Socket Protocol (TSP, or
Teaspoon).
### Intro to ABCI ### Intro to ABCI
[Tendermint Core](https://github.com/tendermint/tendermint) (the [Tendermint Core](https://github.com/tendermint/tendermint), the
"consensus engine") communicates with the application via a socket "consensus engine", communicates with the application via a socket
protocol that satisfies the ABCI. protocol that satisfies the ABCI, the Tendermint Socket Protocol
(TSP, or Teaspoon).
To draw an analogy, lets talk about a well-known cryptocurrency, To draw an analogy, lets talk about a well-known cryptocurrency,
Bitcoin. Bitcoin is a cryptocurrency blockchain where each node Bitcoin. Bitcoin is a cryptocurrency blockchain where each node
@@ -180,7 +177,7 @@ The application will be responsible for
- Allowing clients to query the UTXO database. - Allowing clients to query the UTXO database.
Tendermint is able to decompose the blockchain design by offering a very Tendermint is able to decompose the blockchain design by offering a very
simple API (ie. the ABCI) between the application process and consensus simple API (i.e. the ABCI) between the application process and consensus
process. process.
The ABCI consists of 3 primary message types that get delivered from the The ABCI consists of 3 primary message types that get delivered from the
@@ -239,8 +236,7 @@ Solidity on Ethereum is a great language of choice for blockchain
applications because, among other reasons, it is a completely applications because, among other reasons, it is a completely
deterministic programming language. However, it's also possible to deterministic programming language. However, it's also possible to
create deterministic applications using existing popular languages like create deterministic applications using existing popular languages like
Java, C++, Python, or Go. Game programmers and blockchain developers are Java, C++, Python, or Go, by avoiding
already familiar with creating deterministic programs by avoiding
sources of non-determinism such as: sources of non-determinism such as:
- random number generators (without deterministic seeding) - random number generators (without deterministic seeding)
@@ -271,14 +267,15 @@ committed in a chain, with one block at each **height**. A block may
fail to be committed, in which case the protocol moves to the next fail to be committed, in which case the protocol moves to the next
**round**, and a new validator gets to propose a block for that height. **round**, and a new validator gets to propose a block for that height.
Two stages of voting are required to successfully commit a block; we Two stages of voting are required to successfully commit a block; we
call them **pre-vote** and **pre-commit**. A block is committed when call them **pre-vote** and **pre-commit**.
more than 2/3 of validators pre-commit for the same block in the same
round.
There is a picture of a couple doing the polka because validators are There is a picture of a couple doing the polka because validators are
doing something like a polka dance. When more than two-thirds of the doing something like a polka dance. When more than two-thirds of the
validators pre-vote for the same block, we call that a **polka**. Every validators pre-vote for the same block, we call that a **polka**. Every
pre-commit must be justified by a polka in the same round. pre-commit must be justified by a polka in the same round.
A block is committed when
more than 2/3 of validators pre-commit for the same block in the same
round.
Validators may fail to commit a block for a number of reasons; the Validators may fail to commit a block for a number of reasons; the
current proposer may be offline, or the network may be slow. Tendermint current proposer may be offline, or the network may be slow. Tendermint

966
docs/tutorials/go-built-in.md
View File

File diff suppressed because it is too large Load Diff

782
docs/tutorials/go.md
View File

File diff suppressed because it is too large Load Diff