You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

230 lines
5.9 KiB

6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
  1. ---
  2. order: 2
  3. ---
  4. # Using ABCI-CLI
  5. To facilitate testing and debugging of ABCI servers and simple apps, we
  6. built a CLI, the `abci-cli`, for sending ABCI messages from the command
  7. line.
  8. ## Install
  9. Make sure you [have Go installed](https://golang.org/doc/install).
  10. Next, install the `abci-cli` tool and example applications:
  11. ```sh
  12. git clone https://github.com/tendermint/tendermint.git
  13. cd tendermint
  14. make install_abci
  15. ```
  16. Now run `abci-cli` to see the list of commands:
  17. ```sh
  18. Usage:
  19. abci-cli [command]
  20. Available Commands:
  21. batch Run a batch of abci commands against an application
  22. check_tx Validate a tx
  23. commit Commit the application state and return the Merkle root hash
  24. console Start an interactive abci console for multiple commands
  25. deliver_tx Deliver a new tx to the application
  26. kvstore ABCI demo example
  27. echo Have the application echo a message
  28. help Help about any command
  29. info Get some info about the application
  30. query Query the application state
  31. set_option Set an options on the application
  32. Flags:
  33. --abci string socket or grpc (default "socket")
  34. --address string address of application socket (default "tcp://127.0.0.1:26658")
  35. -h, --help help for abci-cli
  36. -v, --verbose print the command and results as if it were a console session
  37. Use "abci-cli [command] --help" for more information about a command.
  38. ```
  39. ## KVStore - First Example
  40. The `abci-cli` tool lets us send ABCI messages to our application, to
  41. help build and debug them.
  42. The most important messages are `deliver_tx`, `check_tx`, and `commit`,
  43. but there are others for convenience, configuration, and information
  44. purposes.
  45. We'll start a kvstore application, which was installed at the same time
  46. as `abci-cli` above. The kvstore just stores transactions in a merkle
  47. tree.
  48. Its code can be found
  49. [here](https://github.com/tendermint/tendermint/blob/master/abci/cmd/abci-cli/abci-cli.go)
  50. and looks like:
  51. ```go
  52. func cmdKVStore(cmd *cobra.Command, args []string) error {
  53. logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout))
  54. // Create the application - in memory or persisted to disk
  55. var app types.Application
  56. if flagPersist == "" {
  57. app = kvstore.NewKVStoreApplication()
  58. } else {
  59. app = kvstore.NewPersistentKVStoreApplication(flagPersist)
  60. app.(*kvstore.PersistentKVStoreApplication).SetLogger(logger.With("module", "kvstore"))
  61. }
  62. // Start the listener
  63. srv, err := server.NewServer(flagAddrD, flagAbci, app)
  64. if err != nil {
  65. return err
  66. }
  67. // Stop upon receiving SIGTERM or CTRL-C.
  68. ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
  69. defer cancel()
  70. srv.SetLogger(logger.With("module", "abci-server"))
  71. if err := srv.Start(ctx); err != nil {
  72. return err
  73. }
  74. // Run until shutdown.
  75. <-ctx.Done()
  76. srv.Wait()
  77. }
  78. ```
  79. Start by running:
  80. ```sh
  81. abci-cli kvstore
  82. ```
  83. And in another terminal, run
  84. ```sh
  85. abci-cli echo hello
  86. abci-cli info
  87. ```
  88. You'll see something like:
  89. ```sh
  90. -> data: hello
  91. -> data.hex: 68656C6C6F
  92. ```
  93. and:
  94. ```sh
  95. -> data: {"size":0}
  96. -> data.hex: 7B2273697A65223A307D
  97. ```
  98. An ABCI application must provide two things:
  99. - a socket server
  100. - a handler for ABCI messages
  101. When we run the `abci-cli` tool we open a new connection to the
  102. application's socket server, send the given ABCI message, and wait for a
  103. response.
  104. The server may be generic for a particular language, and we provide a
  105. [reference implementation in
  106. Golang](https://github.com/tendermint/tendermint/tree/master/abci/server). See the
  107. [list of other ABCI implementations](https://github.com/tendermint/awesome#ecosystem) for servers in
  108. other languages.
  109. The handler is specific to the application, and may be arbitrary, so
  110. long as it is deterministic and conforms to the ABCI interface
  111. specification.
  112. So when we run `abci-cli info`, we open a new connection to the ABCI
  113. server, which calls the `Info()` method on the application, which tells
  114. us the number of transactions in our Merkle tree.
  115. Now, since every command opens a new connection, we provide the
  116. `abci-cli console` and `abci-cli batch` commands, to allow multiple ABCI
  117. messages to be sent over a single connection.
  118. Running `abci-cli console` should drop you in an interactive console for
  119. speaking ABCI messages to your application.
  120. Try running these commands:
  121. ```sh
  122. > echo hello
  123. -> code: OK
  124. -> data: hello
  125. -> data.hex: 0x68656C6C6F
  126. > info
  127. -> code: OK
  128. -> data: {"size":0}
  129. -> data.hex: 0x7B2273697A65223A307D
  130. > commit
  131. -> code: OK
  132. -> data.hex: 0x0000000000000000
  133. > deliver_tx "abc"
  134. -> code: OK
  135. > info
  136. -> code: OK
  137. -> data: {"size":1}
  138. -> data.hex: 0x7B2273697A65223A317D
  139. > commit
  140. -> code: OK
  141. -> data.hex: 0x0200000000000000
  142. > query "abc"
  143. -> code: OK
  144. -> log: exists
  145. -> height: 2
  146. -> value: abc
  147. -> value.hex: 616263
  148. > deliver_tx "def=xyz"
  149. -> code: OK
  150. > commit
  151. -> code: OK
  152. -> data.hex: 0x0400000000000000
  153. > query "def"
  154. -> code: OK
  155. -> log: exists
  156. -> height: 3
  157. -> value: xyz
  158. -> value.hex: 78797A
  159. ```
  160. Note that if we do `deliver_tx "abc"` it will store `(abc, abc)`, but if
  161. we do `deliver_tx "abc=efg"` it will store `(abc, efg)`.
  162. Similarly, you could put the commands in a file and run
  163. `abci-cli --verbose batch < myfile`.
  164. ## Bounties
  165. Want to write an app in your favorite language?! We'd be happy
  166. to add you to our [ecosystem](https://github.com/tendermint/awesome#ecosystem)!
  167. See [funding](https://github.com/interchainio/funding) opportunities from the
  168. [Interchain Foundation](https://interchain.io/) for implementations in new languages and more.
  169. The `abci-cli` is designed strictly for testing and debugging. In a real
  170. deployment, the role of sending messages is taken by Tendermint, which
  171. connects to the app using three separate connections, each with its own
  172. pattern of messages.
  173. For examples of running an ABCI app with
  174. Tendermint, see the [getting started guide](./getting-started.md).
  175. Next is the ABCI specification.