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.

369 lines
10 KiB

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