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.

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