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.3 KiB

7 years ago
  1. First Tendermint App
  2. ====================
  3. As a general purpose blockchain engine, Tendermint is agnostic to the
  4. application you want to run. So, to run a complete blockchain that does
  5. something useful, you must start two programs: one is Tendermint Core,
  6. the other is your application, which can be written in any programming
  7. language. Recall from `the intro to ABCI <introduction.rst#ABCI-Overview>`__ that
  8. Tendermint Core handles all the p2p and consensus stuff, and just
  9. forwards transactions to the application when they need to be validated,
  10. or when they're ready to be committed to a block.
  11. In this guide, we show you some examples of how to run an application
  12. using Tendermint.
  13. Install
  14. -------
  15. The first apps we will work with are written in Go. To install them, you
  16. need to `install Go <https://golang.org/doc/install>`__ and put
  17. ``$GOPATH/bin`` in your
  18. ``$PATH``; see `here <https://github.com/tendermint/tendermint/wiki/Setting-GOPATH>`__ for more info.
  19. Then run
  20. ::
  21. go get -u github.com/tendermint/abci/cmd/abci-cli
  22. If there is an error, install and run the ``glide`` tool to pin the
  23. dependencies:
  24. ::
  25. go get github.com/Masterminds/glide
  26. cd $GOPATH/src/github.com/tendermint/abci
  27. glide install
  28. go install ./cmd/abci-cli
  29. Now you should have the ``abci-cli`` installed; you'll see
  30. a couple of commands (``counter`` and ``dummy``) that are
  31. example applications written in Go. See below for an application
  32. written in Javascript.
  33. Now, let's run some apps!
  34. Dummy - A First Example
  35. -----------------------
  36. The dummy app is a `Merkle
  37. tree <https://en.wikipedia.org/wiki/Merkle_tree>`__ that just stores all
  38. transactions. If the transaction contains an ``=``, eg. ``key=value``,
  39. then the ``value`` is stored under the ``key`` in the Merkle tree.
  40. Otherwise, the full transaction bytes are stored as the key and the
  41. value.
  42. Let's start a dummy application.
  43. ::
  44. abci-cli dummy
  45. In another terminal, we can start Tendermint. If you have never run
  46. Tendermint before, use:
  47. ::
  48. tendermint init
  49. tendermint node
  50. If you have used Tendermint, you may want to reset the data for a new
  51. blockchain by running ``tendermint unsafe_reset_all``. Then you can run
  52. ``tendermint node`` to start Tendermint, and connect to the app. For
  53. more details, see `the guide on using
  54. Tendermint <./using-tendermint.html>`__.
  55. You should see Tendermint making blocks! We can get the status of our
  56. Tendermint node as follows:
  57. ::
  58. curl -s localhost:46657/status
  59. The ``-s`` just silences ``curl``. For nicer output, pipe the result
  60. into a tool like `jq <https://stedolan.github.io/jq/>`__ or
  61. `jsonpp <https://github.com/jmhodges/jsonpp>`__.
  62. Now let's send some transactions to the dummy.
  63. ::
  64. curl -s 'localhost:46657/broadcast_tx_commit?tx="abcd"'
  65. Note the single quote (``'``) around the url, which ensures that the
  66. double quotes (``"``) are not escaped by bash. This command sent a
  67. transaction with bytes ``abcd``, so ``abcd`` will be stored as both the
  68. key and the value in the Merkle tree. The response should look something
  69. like:
  70. ::
  71. {
  72. "jsonrpc": "2.0",
  73. "id": "",
  74. "result": {
  75. "check_tx": {
  76. "code": 0,
  77. "data": "",
  78. "log": ""
  79. },
  80. "deliver_tx": {
  81. "code": 0,
  82. "data": "",
  83. "log": ""
  84. },
  85. "hash": "2B8EC32BA2579B3B8606E42C06DE2F7AFA2556EF",
  86. "height": 154
  87. }
  88. }
  89. We can confirm that our transaction worked and the value got stored by
  90. querying the app:
  91. ::
  92. curl -s 'localhost:46657/abci_query?data="abcd"'
  93. The result should look like:
  94. ::
  95. {
  96. "jsonrpc": "2.0",
  97. "id": "",
  98. "result": {
  99. "response": {
  100. "code": 0,
  101. "index": 0,
  102. "key": "",
  103. "value": "61626364",
  104. "proof": "",
  105. "height": 0,
  106. "log": "exists"
  107. }
  108. }
  109. }
  110. Note the ``value`` in the result (``61626364``); this is the
  111. hex-encoding of the ASCII of ``abcd``. You can verify this in
  112. a python shell by running ``"61626364".decode('hex')``. Stay
  113. tuned for a future release that `makes this output more human-readable <https://github.com/tendermint/abci/issues/32>`__.
  114. Now let's try setting a different key and value:
  115. ::
  116. curl -s 'localhost:46657/broadcast_tx_commit?tx="name=satoshi"'
  117. Now if we query for ``name``, we should get ``satoshi``, or
  118. ``7361746F736869`` in hex:
  119. ::
  120. curl -s 'localhost:46657/abci_query?data="name"'
  121. Try some other transactions and queries to make sure everything is
  122. working!
  123. Counter - Another Example
  124. -------------------------
  125. Now that we've got the hang of it, let's try another application, the
  126. **counter** app.
  127. The counter app doesn't use a Merkle tree, it just counts how many times
  128. we've sent a transaction, or committed the state.
  129. This application has two modes: ``serial=off`` and ``serial=on``.
  130. When ``serial=on``, transactions must be a big-endian encoded
  131. incrementing integer, starting at 0.
  132. If ``serial=off``, there are no restrictions on transactions.
  133. In a live blockchain, transactions collect in memory before they are
  134. committed into blocks. To avoid wasting resources on invalid
  135. transactions, ABCI provides the ``CheckTx`` message, which application
  136. developers can use to accept or reject transactions, before they are
  137. stored in memory or gossipped to other peers.
  138. In this instance of the counter app, with ``serial=on``, ``CheckTx``
  139. only allows transactions whose integer is greater than the last
  140. committed one.
  141. Let's kill the previous instance of ``tendermint`` and the ``dummy``
  142. application, and start the counter app. We can enable ``serial=on`` with
  143. a flag:
  144. ::
  145. abci-cli counter --serial
  146. In another window, reset then start Tendermint:
  147. ::
  148. tendermint unsafe_reset_all
  149. tendermint node
  150. Once again, you can see the blocks streaming by. Let's send some
  151. transactions. Since we have set ``serial=on``, the first transaction
  152. must be the number ``0``:
  153. ::
  154. curl localhost:46657/broadcast_tx_commit?tx=0x00
  155. Note the empty (hence successful) response. The next transaction must be
  156. the number ``1``. If instead, we try to send a ``5``, we get an error:
  157. ::
  158. > curl localhost:46657/broadcast_tx_commit?tx=0x05
  159. {
  160. "jsonrpc": "2.0",
  161. "id": "",
  162. "result": {
  163. "check_tx": {
  164. "code": 0,
  165. "data": "",
  166. "log": ""
  167. },
  168. "deliver_tx": {
  169. "code": 3,
  170. "data": "",
  171. "log": "Invalid nonce. Expected 1, got 5"
  172. },
  173. "hash": "33B93DFF98749B0D6996A70F64071347060DC19C",
  174. "height": 38
  175. }
  176. }
  177. But if we send a ``1``, it works again:
  178. ::
  179. > curl localhost:46657/broadcast_tx_commit?tx=0x01
  180. {
  181. "jsonrpc": "2.0",
  182. "id": "",
  183. "result": {
  184. "check_tx": {
  185. "code": 0,
  186. "data": "",
  187. "log": ""
  188. },
  189. "deliver_tx": {
  190. "code": 0,
  191. "data": "",
  192. "log": ""
  193. },
  194. "hash": "F17854A977F6FA7EEA1BD758E296710B86F72F3D",
  195. "height": 87
  196. }
  197. }
  198. For more details on the ``broadcast_tx`` API, see `the guide on using
  199. Tendermint <./using-tendermint.html>`__.
  200. CounterJS - Example in Another Language
  201. ---------------------------------------
  202. We also want to run applications in another language - in this case,
  203. we'll run a Javascript version of the ``counter``. To run it, you'll
  204. need to `install node <https://nodejs.org/en/download/>`__.
  205. You'll also need to fetch the relevant repository, from `here <https://github.com/tendermint/js-abci>`__ then install it. As go devs, we
  206. keep all our code under the ``$GOPATH``, so run:
  207. ::
  208. go get github.com/tendermint/js-abci &> /dev/null
  209. cd $GOPATH/src/github.com/tendermint/js-abci/example
  210. npm install
  211. cd ..
  212. Kill the previous ``counter`` and ``tendermint`` processes. Now run the
  213. app:
  214. ::
  215. node example/app.js
  216. In another window, reset and start ``tendermint``:
  217. ::
  218. tendermint unsafe_reset_all
  219. tendermint node
  220. Once again, you should see blocks streaming by - but now, our
  221. application is written in javascript! Try sending some transactions, and
  222. like before - the results should be the same:
  223. ::
  224. curl localhost:46657/broadcast_tx_commit?tx=0x00 # ok
  225. curl localhost:46657/broadcast_tx_commit?tx=0x05 # invalid nonce
  226. curl localhost:46657/broadcast_tx_commit?tx=0x01 # ok
  227. Neat, eh?
  228. Basecoin - A More Interesting Example
  229. -------------------------------------
  230. We saved the best for last; the `Cosmos SDK <https://github.com/cosmos/cosmos-sdk>`__ is a general purpose framework for building cryptocurrencies. Unlike the ``dummy`` and ``counter``, which are strictly for example purposes. The reference implementation of Cosmos SDK is ``basecoin``, which demonstrates how to use the building blocks of the Cosmos SDK.
  231. The default ``basecoin`` application is a multi-asset cryptocurrency
  232. that supports inter-blockchain communication (IBC). For more details on how
  233. basecoin works and how to use it, see our `basecoin
  234. guide <http://cosmos-sdk.readthedocs.io/en/latest/basecoin-basics.html>`__
  235. In this tutorial you learned how to run applications using Tendermint
  236. on a single node. You saw how applications could be written in different
  237. languages, and how to send transactions and query for the latest state.
  238. But the true power of Tendermint comes from its ability to securely and
  239. efficiently run an application across a distributed network of nodes,
  240. while keeping them all in sync using its state-of-the-art consensus
  241. protocol. Next, we show you how to deploy Tendermint testnets.