Zach Ramsay
7 years ago
5 changed files with 399 additions and 431 deletions
Unified View
Diff Options
-
+329 -0docs/abci-cli.md
-
+0 -371docs/abci-cli.rst
-
+50 -0docs/app-architecture.md
-
+0 -42docs/app-architecture.rst
-
+20 -18docs/index.rst
+ 329
- 0
docs/abci-cli.md
View File
| @ -0,0 +1,329 @@ | |||||
| # Using ABCI-CLI | |||||
| To facilitate testing and debugging of ABCI servers and simple apps, we | |||||
| built a CLI, the `abci-cli`, for sending ABCI messages from the command | |||||
| line. | |||||
| ## Install | |||||
| Make sure you [have Go installed](https://golang.org/doc/install). | |||||
| Next, install the `abci-cli` tool and example applications: | |||||
| go get -u github.com/tendermint/abci/cmd/abci-cli | |||||
| If this fails, you may need to use [dep](https://github.com/golang/dep) | |||||
| to get vendored dependencies: | |||||
| cd $GOPATH/src/github.com/tendermint/abci | |||||
| make get_tools | |||||
| make get_vendor_deps | |||||
| make install | |||||
| Now run `abci-cli` to see the list of commands: | |||||
| Usage: | |||||
| abci-cli [command] | |||||
| Available Commands: | |||||
| batch Run a batch of abci commands against an application | |||||
| check_tx Validate a tx | |||||
| commit Commit the application state and return the Merkle root hash | |||||
| console Start an interactive abci console for multiple commands | |||||
| counter ABCI demo example | |||||
| deliver_tx Deliver a new tx to the application | |||||
| kvstore ABCI demo example | |||||
| echo Have the application echo a message | |||||
| help Help about any command | |||||
| info Get some info about the application | |||||
| query Query the application state | |||||
| set_option Set an options on the application | |||||
| Flags: | |||||
| --abci string socket or grpc (default "socket") | |||||
| --address string address of application socket (default "tcp://127.0.0.1:46658") | |||||
| -h, --help help for abci-cli | |||||
| -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. | |||||
| ## KVStore - First Example | |||||
| The `abci-cli` tool lets us send ABCI messages to our application, to | |||||
| help build and debug them. | |||||
| The most important messages are `deliver_tx`, `check_tx`, and `commit`, | |||||
| but there are others for convenience, configuration, and information | |||||
| purposes. | |||||
| 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 | |||||
| tree. | |||||
| Its code can be found | |||||
| [here](https://github.com/tendermint/abci/blob/master/cmd/abci-cli/abci-cli.go) | |||||
| and looks like: | |||||
| func cmdKVStore(cmd *cobra.Command, args []string) error { | |||||
| logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout)) | |||||
| // Create the application - in memory or persisted to disk | |||||
| var app types.Application | |||||
| if flagPersist == "" { | |||||
| app = kvstore.NewKVStoreApplication() | |||||
| } else { | |||||
| app = kvstore.NewPersistentKVStoreApplication(flagPersist) | |||||
| app.(*kvstore.PersistentKVStoreApplication).SetLogger(logger.With("module", "kvstore")) | |||||
| } | |||||
| // Start the listener | |||||
| srv, err := server.NewServer(flagAddrD, flagAbci, app) | |||||
| if err != nil { | |||||
| return err | |||||
| } | |||||
| srv.SetLogger(logger.With("module", "abci-server")) | |||||
| if err := srv.Start(); err != nil { | |||||
| return err | |||||
| } | |||||
| // Wait forever | |||||
| cmn.TrapSignal(func() { | |||||
| // Cleanup | |||||
| srv.Stop() | |||||
| }) | |||||
| return nil | |||||
| } | |||||
| Start by running: | |||||
| abci-cli kvstore | |||||
| And in another terminal, run | |||||
| abci-cli echo hello | |||||
| abci-cli info | |||||
| You'll see something like: | |||||
| -> data: hello | |||||
| -> data.hex: 68656C6C6F | |||||
| and: | |||||
| -> data: {"size":0} | |||||
| -> data.hex: 7B2273697A65223A307D | |||||
| An ABCI application must provide two things: | |||||
| - a socket server | |||||
| - a handler for ABCI messages | |||||
| When we run the `abci-cli` tool we open a new connection to the | |||||
| application's socket server, send the given ABCI message, and wait for a | |||||
| response. | |||||
| The server may be generic for a particular language, and we provide a | |||||
| [reference implementation in | |||||
| Golang](https://github.com/tendermint/abci/tree/master/server). See the | |||||
| [list of other ABCI implementations](./ecosystem.html) for servers in | |||||
| other languages. | |||||
| The handler is specific to the application, and may be arbitrary, so | |||||
| long as it is deterministic and conforms to the ABCI interface | |||||
| specification. | |||||
| So when we run `abci-cli info`, we open a new connection to the ABCI | |||||
| server, which calls the `Info()` method on the application, which tells | |||||
| us the number of transactions in our Merkle tree. | |||||
| Now, since every command opens a new connection, we provide the | |||||
| `abci-cli console` and `abci-cli batch` commands, to allow multiple ABCI | |||||
| messages to be sent over a single connection. | |||||
| Running `abci-cli console` should drop you in an interactive console for | |||||
| speaking ABCI messages to your application. | |||||
| Try running these commands: | |||||
| > echo hello | |||||
| -> code: OK | |||||
| -> data: hello | |||||
| -> data.hex: 0x68656C6C6F | |||||
| > info | |||||
| -> code: OK | |||||
| -> data: {"size":0} | |||||
| -> data.hex: 0x7B2273697A65223A307D | |||||
| > commit | |||||
| -> code: OK | |||||
| -> data.hex: 0x0000000000000000 | |||||
| > deliver_tx "abc" | |||||
| -> code: OK | |||||
| > info | |||||
| -> code: OK | |||||
| -> data: {"size":1} | |||||
| -> data.hex: 0x7B2273697A65223A317D | |||||
| > commit | |||||
| -> code: OK | |||||
| -> data.hex: 0x0200000000000000 | |||||
| > query "abc" | |||||
| -> code: OK | |||||
| -> log: exists | |||||
| -> height: 0 | |||||
| -> value: abc | |||||
| -> value.hex: 616263 | |||||
| > deliver_tx "def=xyz" | |||||
| -> code: OK | |||||
| > commit | |||||
| -> code: OK | |||||
| -> data.hex: 0x0400000000000000 | |||||
| > query "def" | |||||
| -> code: OK | |||||
| -> log: exists | |||||
| -> height: 0 | |||||
| -> value: xyz | |||||
| -> value.hex: 78797A | |||||
| 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)`. | |||||
| Similarly, you could put the commands in a file and run | |||||
| `abci-cli --verbose batch < myfile`. | |||||
| ## Counter - Another Example | |||||
| Now that we've got the hang of it, let's try another application, the | |||||
| "counter" app. | |||||
| Like the kvstore app, its code can be found | |||||
| [here](https://github.com/tendermint/abci/blob/master/cmd/abci-cli/abci-cli.go) | |||||
| and looks like: | |||||
| func cmdCounter(cmd *cobra.Command, args []string) error { | |||||
| app := counter.NewCounterApplication(flagSerial) | |||||
| logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout)) | |||||
| // Start the listener | |||||
| srv, err := server.NewServer(flagAddrC, flagAbci, app) | |||||
| if err != nil { | |||||
| return err | |||||
| } | |||||
| srv.SetLogger(logger.With("module", "abci-server")) | |||||
| if err := srv.Start(); err != nil { | |||||
| return err | |||||
| } | |||||
| // Wait forever | |||||
| cmn.TrapSignal(func() { | |||||
| // Cleanup | |||||
| srv.Stop() | |||||
| }) | |||||
| return nil | |||||
| } | |||||
| The counter app doesn't use a Merkle tree, it just counts how many times | |||||
| we've sent a transaction, asked for a hash, or committed the state. The | |||||
| result of `commit` is just the number of transactions sent. | |||||
| 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. | |||||
| We can toggle the value of `serial` using the `set_option` ABCI message. | |||||
| When `serial=on`, some transactions are invalid. In a live blockchain, | |||||
| transactions collect in memory before they are committed into blocks. To | |||||
| avoid wasting resources on invalid transactions, ABCI provides the | |||||
| `check_tx` 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, `check_tx` only allows transactions | |||||
| whose integer is greater than the last committed one. | |||||
| Let's kill the console and the kvstore application, and start the | |||||
| counter app: | |||||
| abci-cli counter | |||||
| In another window, start the `abci-cli console`: | |||||
| > set_option serial on | |||||
| -> code: OK | |||||
| -> log: OK (SetOption doesn't return anything.) | |||||
| > check_tx 0x00 | |||||
| -> code: OK | |||||
| > check_tx 0xff | |||||
| -> code: OK | |||||
| > deliver_tx 0x00 | |||||
| -> code: OK | |||||
| > check_tx 0x00 | |||||
| -> code: BadNonce | |||||
| -> log: Invalid nonce. Expected >= 1, got 0 | |||||
| > deliver_tx 0x01 | |||||
| -> code: OK | |||||
| > deliver_tx 0x04 | |||||
| -> code: BadNonce | |||||
| -> log: Invalid nonce. Expected 2, got 4 | |||||
| > info | |||||
| -> code: OK | |||||
| -> data: {"hashes":0,"txs":2} | |||||
| -> data.hex: 0x7B22686173686573223A302C22747873223A327D | |||||
| This is a very simple application, but between `counter` and `kvstore`, | |||||
| its easy to see how you can build out arbitrary application states on | |||||
| top of the ABCI. [Hyperledger's | |||||
| Burrow](https://github.com/hyperledger/burrow) also runs atop ABCI, | |||||
| bringing with it Ethereum-like accounts, the Ethereum virtual-machine, | |||||
| Monax's permissioning scheme, and native contracts extensions. | |||||
| But the ultimate flexibility comes from being able to write the | |||||
| application easily in any language. | |||||
| We have implemented the counter in a number of languages (see the | |||||
| example directory <https://github.com/tendermint/abci/tree/master/example\_\_). | |||||
| To run the Node JS version, `cd` to `example/js` and run | |||||
| node app.js | |||||
| (you'll have to kill the other counter application process). In another | |||||
| 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](https://tendermint.com/ecosystem)! We're | |||||
| also offering [bounties](https://hackerone.com/tendermint/) for | |||||
| implementations in new languages! | |||||
| 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](./app-development.html). For examples of running an ABCI app with | |||||
| Tendermint, see the [getting started guide](./getting-started.html). | |||||
| Next is the ABCI specification. | |||||
+ 0
- 371
docs/abci-cli.rst
View File
| @ -1,371 +0,0 @@ | |||||
| Using ABCI-CLI | |||||
| ============== | |||||
| To facilitate testing and debugging of ABCI servers and simple apps, we | |||||
| built a CLI, the ``abci-cli``, for sending ABCI messages from the | |||||
| command line. | |||||
| Install | |||||
| ------- | |||||
| Make sure you `have Go installed <https://golang.org/doc/install>`__. | |||||
| Next, install the ``abci-cli`` tool and example applications: | |||||
| :: | |||||
| go get -u github.com/tendermint/abci/cmd/abci-cli | |||||
| If this fails, you may need to use `dep <https://github.com/golang/dep>`__ to get vendored | |||||
| dependencies: | |||||
| :: | |||||
| cd $GOPATH/src/github.com/tendermint/abci | |||||
| make get_tools | |||||
| make get_vendor_deps | |||||
| make install | |||||
| Now run ``abci-cli`` to see the list of commands: | |||||
| :: | |||||
| Usage: | |||||
| abci-cli [command] | |||||
| Available Commands: | |||||
| batch Run a batch of abci commands against an application | |||||
| check_tx Validate a tx | |||||
| commit Commit the application state and return the Merkle root hash | |||||
| console Start an interactive abci console for multiple commands | |||||
| counter ABCI demo example | |||||
| deliver_tx Deliver a new tx to the application | |||||
| kvstore ABCI demo example | |||||
| echo Have the application echo a message | |||||
| help Help about any command | |||||
| info Get some info about the application | |||||
| query Query the application state | |||||
| set_option Set an options on the application | |||||
| Flags: | |||||
| --abci string socket or grpc (default "socket") | |||||
| --address string address of application socket (default "tcp://127.0.0.1:46658") | |||||
| -h, --help help for abci-cli | |||||
| -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. | |||||
| KVStore - First Example | |||||
| ----------------------- | |||||
| The ``abci-cli`` tool lets us send ABCI messages to our application, to | |||||
| help build and debug them. | |||||
| The most important messages are ``deliver_tx``, ``check_tx``, and | |||||
| ``commit``, but there are others for convenience, configuration, and | |||||
| information purposes. | |||||
| 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 tree. | |||||
| Its code can be found `here <https://github.com/tendermint/abci/blob/master/cmd/abci-cli/abci-cli.go>`__ and looks like: | |||||
| .. container:: toggle | |||||
| .. container:: header | |||||
| **Show/Hide KVStore Example** | |||||
| .. code-block:: go | |||||
| func cmdKVStore(cmd *cobra.Command, args []string) error { | |||||
| logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout)) | |||||
| // Create the application - in memory or persisted to disk | |||||
| var app types.Application | |||||
| if flagPersist == "" { | |||||
| app = kvstore.NewKVStoreApplication() | |||||
| } else { | |||||
| app = kvstore.NewPersistentKVStoreApplication(flagPersist) | |||||
| app.(*kvstore.PersistentKVStoreApplication).SetLogger(logger.With("module", "kvstore")) | |||||
| } | |||||
| // Start the listener | |||||
| srv, err := server.NewServer(flagAddrD, flagAbci, app) | |||||
| if err != nil { | |||||
| return err | |||||
| } | |||||
| srv.SetLogger(logger.With("module", "abci-server")) | |||||
| if err := srv.Start(); err != nil { | |||||
| return err | |||||
| } | |||||
| // Wait forever | |||||
| cmn.TrapSignal(func() { | |||||
| // Cleanup | |||||
| srv.Stop() | |||||
| }) | |||||
| return nil | |||||
| } | |||||
| Start by running: | |||||
| :: | |||||
| abci-cli kvstore | |||||
| And in another terminal, run | |||||
| :: | |||||
| abci-cli echo hello | |||||
| abci-cli info | |||||
| You'll see something like: | |||||
| :: | |||||
| -> data: hello | |||||
| -> data.hex: 68656C6C6F | |||||
| and: | |||||
| :: | |||||
| -> data: {"size":0} | |||||
| -> data.hex: 7B2273697A65223A307D | |||||
| An ABCI application must provide two things: | |||||
| - a socket server | |||||
| - a handler for ABCI messages | |||||
| When we run the ``abci-cli`` tool we open a new connection to the | |||||
| application's socket server, send the given ABCI message, and wait for a | |||||
| response. | |||||
| The server may be generic for a particular language, and we provide a | |||||
| `reference implementation in | |||||
| Golang <https://github.com/tendermint/abci/tree/master/server>`__. See | |||||
| the `list of other ABCI | |||||
| implementations <./ecosystem.html>`__ for servers in | |||||
| other languages. | |||||
| The handler is specific to the application, and may be arbitrary, so | |||||
| long as it is deterministic and conforms to the ABCI interface | |||||
| specification. | |||||
| So when we run ``abci-cli info``, we open a new connection to the ABCI | |||||
| server, which calls the ``Info()`` method on the application, which | |||||
| tells us the number of transactions in our Merkle tree. | |||||
| Now, since every command opens a new connection, we provide the | |||||
| ``abci-cli console`` and ``abci-cli batch`` commands, to allow multiple | |||||
| ABCI messages to be sent over a single connection. | |||||
| Running ``abci-cli console`` should drop you in an interactive console | |||||
| for speaking ABCI messages to your application. | |||||
| Try running these commands: | |||||
| :: | |||||
| > echo hello | |||||
| -> code: OK | |||||
| -> data: hello | |||||
| -> data.hex: 0x68656C6C6F | |||||
| > info | |||||
| -> code: OK | |||||
| -> data: {"size":0} | |||||
| -> data.hex: 0x7B2273697A65223A307D | |||||
| > commit | |||||
| -> code: OK | |||||
| -> data.hex: 0x0000000000000000 | |||||
| > deliver_tx "abc" | |||||
| -> code: OK | |||||
| > info | |||||
| -> code: OK | |||||
| -> data: {"size":1} | |||||
| -> data.hex: 0x7B2273697A65223A317D | |||||
| > commit | |||||
| -> code: OK | |||||
| -> data.hex: 0x0200000000000000 | |||||
| > query "abc" | |||||
| -> code: OK | |||||
| -> log: exists | |||||
| -> height: 0 | |||||
| -> value: abc | |||||
| -> value.hex: 616263 | |||||
| > deliver_tx "def=xyz" | |||||
| -> code: OK | |||||
| > commit | |||||
| -> code: OK | |||||
| -> data.hex: 0x0400000000000000 | |||||
| > query "def" | |||||
| -> code: OK | |||||
| -> log: exists | |||||
| -> height: 0 | |||||
| -> value: xyz | |||||
| -> value.hex: 78797A | |||||
| 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)``. | |||||
| Similarly, you could put the commands in a file and run | |||||
| ``abci-cli --verbose batch < myfile``. | |||||
| Counter - Another Example | |||||
| ------------------------- | |||||
| Now that we've got the hang of it, let's try another application, the | |||||
| "counter" app. | |||||
| Like the kvstore app, its code can be found `here <https://github.com/tendermint/abci/blob/master/cmd/abci-cli/abci-cli.go>`__ and looks like: | |||||
| .. container:: toggle | |||||
| .. container:: header | |||||
| **Show/Hide Counter Example** | |||||
| .. code-block:: go | |||||
| func cmdCounter(cmd *cobra.Command, args []string) error { | |||||
| app := counter.NewCounterApplication(flagSerial) | |||||
| logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout)) | |||||
| // Start the listener | |||||
| srv, err := server.NewServer(flagAddrC, flagAbci, app) | |||||
| if err != nil { | |||||
| return err | |||||
| } | |||||
| srv.SetLogger(logger.With("module", "abci-server")) | |||||
| if err := srv.Start(); err != nil { | |||||
| return err | |||||
| } | |||||
| // Wait forever | |||||
| cmn.TrapSignal(func() { | |||||
| // Cleanup | |||||
| srv.Stop() | |||||
| }) | |||||
| return nil | |||||
| } | |||||
| The counter app doesn't use a Merkle tree, it just counts how many times | |||||
| we've sent a transaction, asked for a hash, or committed the state. The | |||||
| result of ``commit`` is just the number of transactions sent. | |||||
| 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. | |||||
| We can toggle the value of ``serial`` using the ``set_option`` ABCI | |||||
| message. | |||||
| When ``serial=on``, some transactions are invalid. In a live blockchain, | |||||
| transactions collect in memory before they are committed into blocks. To | |||||
| avoid wasting resources on invalid transactions, ABCI provides the | |||||
| ``check_tx`` 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, ``check_tx`` only allows | |||||
| transactions whose integer is greater than the last committed one. | |||||
| Let's kill the console and the kvstore application, and start the counter | |||||
| app: | |||||
| :: | |||||
| abci-cli counter | |||||
| In another window, start the ``abci-cli console``: | |||||
| :: | |||||
| > set_option serial on | |||||
| -> code: OK | |||||
| -> log: OK (SetOption doesn't return anything.) | |||||
| > check_tx 0x00 | |||||
| -> code: OK | |||||
| > check_tx 0xff | |||||
| -> code: OK | |||||
| > deliver_tx 0x00 | |||||
| -> code: OK | |||||
| > check_tx 0x00 | |||||
| -> code: BadNonce | |||||
| -> log: Invalid nonce. Expected >= 1, got 0 | |||||
| > deliver_tx 0x01 | |||||
| -> code: OK | |||||
| > deliver_tx 0x04 | |||||
| -> code: BadNonce | |||||
| -> log: Invalid nonce. Expected 2, got 4 | |||||
| > info | |||||
| -> code: OK | |||||
| -> data: {"hashes":0,"txs":2} | |||||
| -> data.hex: 0x7B22686173686573223A302C22747873223A327D | |||||
| This is a very simple application, but between ``counter`` and | |||||
| ``kvstore``, its easy to see how you can build out arbitrary application | |||||
| states on top of the ABCI. `Hyperledger's | |||||
| Burrow <https://github.com/hyperledger/burrow>`__ also runs atop ABCI, | |||||
| bringing with it Ethereum-like accounts, the Ethereum virtual-machine, | |||||
| Monax's permissioning scheme, and native contracts extensions. | |||||
| But the ultimate flexibility comes from being able to write the | |||||
| application easily in any language. | |||||
| We have implemented the counter in a number of languages (see the | |||||
| `example directory <https://github.com/tendermint/abci/tree/master/example`__). | |||||
| To run the Node JS version, ``cd`` to ``example/js`` and run | |||||
| :: | |||||
| node app.js | |||||
| (you'll have to kill the other counter application process). In another | |||||
| 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 <https://tendermint.com/ecosystem>`__! | |||||
| We're also offering `bounties <https://tendermint.com/bounties>`__ for | |||||
| implementations in new languages! | |||||
| 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 <./app-development.html>`__. For examples of running an ABCI | |||||
| app with Tendermint, see the `getting started | |||||
| guide <./getting-started.html>`__. Next is the ABCI specification. | |||||
+ 50
- 0
docs/app-architecture.md
View File
| @ -0,0 +1,50 @@ | |||||
| # Application Architecture Guide | |||||
| Here we provide a brief guide on the recommended architecture of a | |||||
| Tendermint blockchain application. | |||||
| The following diagram provides a superb example: | |||||
| <https://drive.google.com/open?id=1yR2XpRi9YCY9H9uMfcw8-RMJpvDyvjz9> | |||||
| The end-user application here is the Cosmos Voyager, at the bottom left. | |||||
| Voyager communicates with a REST API exposed by a local Light-Client | |||||
| Daemon. The Light-Client Daemon is an application specific program that | |||||
| communicates with Tendermint nodes and verifies Tendermint light-client | |||||
| proofs through the Tendermint Core RPC. The Tendermint Core process | |||||
| communicates with a local ABCI application, where the user query or | |||||
| transaction is actually processed. | |||||
| The ABCI application must be a deterministic result of the Tendermint | |||||
| consensus - any external influence on the application state that didn't | |||||
| come through Tendermint could cause a consensus failure. Thus *nothing* | |||||
| should communicate with the application except Tendermint via ABCI. | |||||
| If the application is written in Go, it can be compiled into the | |||||
| Tendermint binary. Otherwise, it should use a unix socket to communicate | |||||
| with Tendermint. If it's necessary to use TCP, extra care must be taken | |||||
| to encrypt and authenticate the connection. | |||||
| All reads from the app happen through the Tendermint `/abci_query` | |||||
| endpoint. All writes to the app happen through the Tendermint | |||||
| `/broadcast_tx_*` endpoints. | |||||
| The Light-Client Daemon is what provides light clients (end users) with | |||||
| nearly all the security of a full node. It formats and broadcasts | |||||
| transactions, and verifies proofs of queries and transaction results. | |||||
| Note that it need not be a daemon - the Light-Client logic could instead | |||||
| be implemented in the same process as the end-user application. | |||||
| Note for those ABCI applications with weaker security requirements, the | |||||
| functionality of the Light-Client Daemon can be moved into the ABCI | |||||
| application process itself. That said, exposing the application process | |||||
| to anything besides Tendermint over ABCI requires extreme caution, as | |||||
| all transactions, and possibly all queries, should still pass through | |||||
| Tendermint. | |||||
| See the following for more extensive documentation: | |||||
| - [Interchain Standard for the Light-Client REST API](https://github.com/cosmos/cosmos-sdk/pull/1028) | |||||
| - [Tendermint RPC Docs](https://tendermint.github.io/slate/) | |||||
| - [Tendermint in Production](https://github.com/tendermint/tendermint/pull/1618) | |||||
| - [Tendermint Basics](https://tendermint.readthedocs.io/en/master/using-tendermint.html) | |||||
| - [ABCI spec](https://github.com/tendermint/abci/blob/master/specification.rst) | |||||
+ 0
- 42
docs/app-architecture.rst
View File
| @ -1,42 +0,0 @@ | |||||
| Application Architecture Guide | |||||
| ============================== | |||||
| Here we provide a brief guide on the recommended architecture of a Tendermint blockchain | |||||
| application. | |||||
| The following diagram provides a superb example: | |||||
| https://drive.google.com/open?id=1yR2XpRi9YCY9H9uMfcw8-RMJpvDyvjz9 | |||||
| The end-user application here is the Cosmos Voyager, at the bottom left. | |||||
| Voyager communicates with a REST API exposed by a local Light-Client Daemon. | |||||
| The Light-Client Daemon is an application specific program that communicates with | |||||
| Tendermint nodes and verifies Tendermint light-client proofs through the Tendermint Core RPC. | |||||
| The Tendermint Core process communicates with a local ABCI application, where the | |||||
| user query or transaction is actually processed. | |||||
| The ABCI application must be a deterministic result of the Tendermint consensus - any external influence | |||||
| on the application state that didn't come through Tendermint could cause a | |||||
| consensus failure. Thus *nothing* should communicate with the application except Tendermint via ABCI. | |||||
| If the application is written in Go, it can be compiled into the Tendermint binary. | |||||
| Otherwise, it should use a unix socket to communicate with Tendermint. | |||||
| If it's necessary to use TCP, extra care must be taken to encrypt and authenticate the connection. | |||||
| All reads from the app happen through the Tendermint `/abci_query` endpoint. | |||||
| All writes to the app happen through the Tendermint `/broadcast_tx_*` endpoints. | |||||
| The Light-Client Daemon is what provides light clients (end users) with nearly all the security of a full node. | |||||
| It formats and broadcasts transactions, and verifies proofs of queries and transaction results. | |||||
| Note that it need not be a daemon - the Light-Client logic could instead be implemented in the same process as the end-user application. | |||||
| Note for those ABCI applications with weaker security requirements, the functionality of the Light-Client Daemon can be moved | |||||
| into the ABCI application process itself. That said, exposing the application process to anything besides Tendermint over ABCI | |||||
| requires extreme caution, as all transactions, and possibly all queries, should still pass through Tendermint. | |||||
| See the following for more extensive documentation: | |||||
| - [Interchain Standard for the Light-Client REST API](https://github.com/cosmos/cosmos-sdk/pull/1028) | |||||
| - [Tendermint RPC Docs](https://tendermint.github.io/slate/) | |||||
| - [Tendermint in Production](https://github.com/tendermint/tendermint/pull/1618) | |||||
| - [Tendermint Basics](https://tendermint.readthedocs.io/en/master/using-tendermint.html) | |||||
| - [ABCI spec](https://github.com/tendermint/abci/blob/master/specification.rst) | |||||