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.

329 lines
9.6 KiB

  1. # Using ABCI-CLI
  2. To facilitate testing and debugging of ABCI servers and simple apps, we
  3. built a CLI, the `abci-cli`, for sending ABCI messages from the command
  4. line.
  5. ## Install
  6. Make sure you [have Go installed](https://golang.org/doc/install).
  7. Next, install the `abci-cli` tool and example applications:
  8. go get -u github.com/tendermint/abci/cmd/abci-cli
  9. If this fails, you may need to use [dep](https://github.com/golang/dep)
  10. to get vendored dependencies:
  11. cd $GOPATH/src/github.com/tendermint/abci
  12. make get_tools
  13. make get_vendor_deps
  14. make install
  15. Now run `abci-cli` to see the list of commands:
  16. Usage:
  17. abci-cli [command]
  18. Available Commands:
  19. batch Run a batch of abci commands against an application
  20. check_tx Validate a tx
  21. commit Commit the application state and return the Merkle root hash
  22. console Start an interactive abci console for multiple commands
  23. counter ABCI demo example
  24. deliver_tx Deliver a new tx to the application
  25. kvstore ABCI demo example
  26. echo Have the application echo a message
  27. help Help about any command
  28. info Get some info about the application
  29. query Query the application state
  30. set_option Set an options on the application
  31. Flags:
  32. --abci string socket or grpc (default "socket")
  33. --address string address of application socket (default "tcp://127.0.0.1:46658")
  34. -h, --help help for abci-cli
  35. -v, --verbose print the command and results as if it were a console session
  36. Use "abci-cli [command] --help" for more information about a command.
  37. ## KVStore - First Example
  38. The `abci-cli` tool lets us send ABCI messages to our application, to
  39. help build and debug them.
  40. The most important messages are `deliver_tx`, `check_tx`, and `commit`,
  41. but there are others for convenience, configuration, and information
  42. purposes.
  43. We'll start a kvstore application, which was installed at the same time
  44. as `abci-cli` above. The kvstore just stores transactions in a merkle
  45. tree.
  46. Its code can be found
  47. [here](https://github.com/tendermint/abci/blob/master/cmd/abci-cli/abci-cli.go)
  48. and looks like:
  49. func cmdKVStore(cmd *cobra.Command, args []string) error {
  50. logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout))
  51. // Create the application - in memory or persisted to disk
  52. var app types.Application
  53. if flagPersist == "" {
  54. app = kvstore.NewKVStoreApplication()
  55. } else {
  56. app = kvstore.NewPersistentKVStoreApplication(flagPersist)
  57. app.(*kvstore.PersistentKVStoreApplication).SetLogger(logger.With("module", "kvstore"))
  58. }
  59. // Start the listener
  60. srv, err := server.NewServer(flagAddrD, flagAbci, app)
  61. if err != nil {
  62. return err
  63. }
  64. srv.SetLogger(logger.With("module", "abci-server"))
  65. if err := srv.Start(); err != nil {
  66. return err
  67. }
  68. // Wait forever
  69. cmn.TrapSignal(func() {
  70. // Cleanup
  71. srv.Stop()
  72. })
  73. return nil
  74. }
  75. Start by running:
  76. abci-cli kvstore
  77. And in another terminal, run
  78. abci-cli echo hello
  79. abci-cli info
  80. You'll see something like:
  81. -> data: hello
  82. -> data.hex: 68656C6C6F
  83. and:
  84. -> data: {"size":0}
  85. -> data.hex: 7B2273697A65223A307D
  86. An ABCI application must provide two things:
  87. - a socket server
  88. - a handler for ABCI messages
  89. When we run the `abci-cli` tool we open a new connection to the
  90. application's socket server, send the given ABCI message, and wait for a
  91. response.
  92. The server may be generic for a particular language, and we provide a
  93. [reference implementation in
  94. Golang](https://github.com/tendermint/abci/tree/master/server). See the
  95. [list of other ABCI implementations](./ecosystem.html) for servers in
  96. other languages.
  97. The handler is specific to the application, and may be arbitrary, so
  98. long as it is deterministic and conforms to the ABCI interface
  99. specification.
  100. So when we run `abci-cli info`, we open a new connection to the ABCI
  101. server, which calls the `Info()` method on the application, which tells
  102. us the number of transactions in our Merkle tree.
  103. Now, since every command opens a new connection, we provide the
  104. `abci-cli console` and `abci-cli batch` commands, to allow multiple ABCI
  105. messages to be sent over a single connection.
  106. Running `abci-cli console` should drop you in an interactive console for
  107. speaking ABCI messages to your application.
  108. Try running these commands:
  109. > echo hello
  110. -> code: OK
  111. -> data: hello
  112. -> data.hex: 0x68656C6C6F
  113. > info
  114. -> code: OK
  115. -> data: {"size":0}
  116. -> data.hex: 0x7B2273697A65223A307D
  117. > commit
  118. -> code: OK
  119. -> data.hex: 0x0000000000000000
  120. > deliver_tx "abc"
  121. -> code: OK
  122. > info
  123. -> code: OK
  124. -> data: {"size":1}
  125. -> data.hex: 0x7B2273697A65223A317D
  126. > commit
  127. -> code: OK
  128. -> data.hex: 0x0200000000000000
  129. > query "abc"
  130. -> code: OK
  131. -> log: exists
  132. -> height: 0
  133. -> value: abc
  134. -> value.hex: 616263
  135. > deliver_tx "def=xyz"
  136. -> code: OK
  137. > commit
  138. -> code: OK
  139. -> data.hex: 0x0400000000000000
  140. > query "def"
  141. -> code: OK
  142. -> log: exists
  143. -> height: 0
  144. -> value: xyz
  145. -> value.hex: 78797A
  146. Note that if we do `deliver_tx "abc"` it will store `(abc, abc)`, but if
  147. we do `deliver_tx "abc=efg"` it will store `(abc, efg)`.
  148. Similarly, you could put the commands in a file and run
  149. `abci-cli --verbose batch < myfile`.
  150. ## Counter - Another Example
  151. Now that we've got the hang of it, let's try another application, the
  152. "counter" app.
  153. Like the kvstore app, its code can be found
  154. [here](https://github.com/tendermint/abci/blob/master/cmd/abci-cli/abci-cli.go)
  155. and looks like:
  156. func cmdCounter(cmd *cobra.Command, args []string) error {
  157. app := counter.NewCounterApplication(flagSerial)
  158. logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout))
  159. // Start the listener
  160. srv, err := server.NewServer(flagAddrC, flagAbci, app)
  161. if err != nil {
  162. return err
  163. }
  164. srv.SetLogger(logger.With("module", "abci-server"))
  165. if err := srv.Start(); err != nil {
  166. return err
  167. }
  168. // Wait forever
  169. cmn.TrapSignal(func() {
  170. // Cleanup
  171. srv.Stop()
  172. })
  173. return nil
  174. }
  175. The counter app doesn't use a Merkle tree, it just counts how many times
  176. we've sent a transaction, asked for a hash, or committed the state. The
  177. result of `commit` is just the number of transactions sent.
  178. This application has two modes: `serial=off` and `serial=on`.
  179. When `serial=on`, transactions must be a big-endian encoded incrementing
  180. integer, starting at 0.
  181. If `serial=off`, there are no restrictions on transactions.
  182. We can toggle the value of `serial` using the `set_option` ABCI message.
  183. When `serial=on`, some transactions are invalid. In a live blockchain,
  184. transactions collect in memory before they are committed into blocks. To
  185. avoid wasting resources on invalid transactions, ABCI provides the
  186. `check_tx` message, which application developers can use to accept or
  187. reject transactions, before they are stored in memory or gossipped to
  188. other peers.
  189. In this instance of the counter app, `check_tx` only allows transactions
  190. whose integer is greater than the last committed one.
  191. Let's kill the console and the kvstore application, and start the
  192. counter app:
  193. abci-cli counter
  194. In another window, start the `abci-cli console`:
  195. > set_option serial on
  196. -> code: OK
  197. -> log: OK (SetOption doesn't return anything.)
  198. > check_tx 0x00
  199. -> code: OK
  200. > check_tx 0xff
  201. -> code: OK
  202. > deliver_tx 0x00
  203. -> code: OK
  204. > check_tx 0x00
  205. -> code: BadNonce
  206. -> log: Invalid nonce. Expected >= 1, got 0
  207. > deliver_tx 0x01
  208. -> code: OK
  209. > deliver_tx 0x04
  210. -> code: BadNonce
  211. -> log: Invalid nonce. Expected 2, got 4
  212. > info
  213. -> code: OK
  214. -> data: {"hashes":0,"txs":2}
  215. -> data.hex: 0x7B22686173686573223A302C22747873223A327D
  216. This is a very simple application, but between `counter` and `kvstore`,
  217. its easy to see how you can build out arbitrary application states on
  218. top of the ABCI. [Hyperledger's
  219. Burrow](https://github.com/hyperledger/burrow) also runs atop ABCI,
  220. bringing with it Ethereum-like accounts, the Ethereum virtual-machine,
  221. Monax's permissioning scheme, and native contracts extensions.
  222. But the ultimate flexibility comes from being able to write the
  223. application easily in any language.
  224. We have implemented the counter in a number of languages (see the
  225. example directory &lt;https://github.com/tendermint/abci/tree/master/example\_\_).
  226. To run the Node JS version, `cd` to `example/js` and run
  227. node app.js
  228. (you'll have to kill the other counter application process). In another
  229. window, run the console and those previous ABCI commands. You should get
  230. the same results as for the Go version.
  231. ## Bounties
  232. Want to write the counter app in your favorite language?! We'd be happy
  233. to add you to our [ecosystem](https://tendermint.com/ecosystem)! We're
  234. also offering [bounties](https://hackerone.com/tendermint/) for
  235. implementations in new languages!
  236. The `abci-cli` is designed strictly for testing and debugging. In a real
  237. deployment, the role of sending messages is taken by Tendermint, which
  238. connects to the app using three separate connections, each with its own
  239. pattern of messages.
  240. For more information, see the [application developers
  241. guide](./app-development.html). For examples of running an ABCI app with
  242. Tendermint, see the [getting started guide](./getting-started.html).
  243. Next is the ABCI specification.