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.

210 lines
5.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
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: 1
  3. ---
  4. # Getting Started
  5. ## First Tendermint App
  6. As a general purpose blockchain engine, Tendermint is agnostic to the
  7. application you want to run. So, to run a complete blockchain that does
  8. something useful, you must start two programs: one is Tendermint Core,
  9. the other is your application, which can be written in any programming
  10. language. Recall from [the intro to
  11. ABCI](../introduction/what-is-tendermint.md#abci-overview) that Tendermint Core handles all the p2p and consensus stuff, and just forwards transactions to the
  12. application when they need to be validated, or when they're ready to be
  13. committed to a block.
  14. In this guide, we show you some examples of how to run an application
  15. using Tendermint.
  16. ### Install
  17. The first apps we will work with are written in Go. To install them, you
  18. need to [install Go](https://golang.org/doc/install), put
  19. `$GOPATH/bin` in your `$PATH` and enable go modules with these instructions:
  20. ```bash
  21. echo export GOPATH=\"\$HOME/go\" >> ~/.bash_profile
  22. echo export PATH=\"\$PATH:\$GOPATH/bin\" >> ~/.bash_profile
  23. ```
  24. Then run
  25. ```sh
  26. go get github.com/tendermint/tendermint
  27. cd $GOPATH/src/github.com/tendermint/tendermint
  28. make install_abci
  29. ```
  30. Now you should have the `abci-cli` installed; you'll notice the `kvstore`
  31. command, an example application written
  32. in Go. See below for an application written in JavaScript.
  33. Now, let's run some apps!
  34. ## KVStore - A First Example
  35. The kvstore app is a [Merkle
  36. tree](https://en.wikipedia.org/wiki/Merkle_tree) that just stores all
  37. transactions. If the transaction contains an `=`, e.g. `key=value`, then
  38. the `value` is stored under the `key` in the Merkle tree. Otherwise, the
  39. full transaction bytes are stored as the key and the value.
  40. Let's start a kvstore application.
  41. ```sh
  42. abci-cli kvstore
  43. ```
  44. In another terminal, we can start Tendermint. You should already have the
  45. Tendermint binary installed. If not, follow the steps from
  46. [here](../introduction/install.md). If you have never run Tendermint
  47. before, use:
  48. ```sh
  49. tendermint init validator
  50. tendermint start
  51. ```
  52. If you have used Tendermint, you may want to reset the data for a new
  53. blockchain by running `tendermint unsafe_reset_all`. Then you can run
  54. `tendermint start` to start Tendermint, and connect to the app. For more
  55. details, see [the guide on using Tendermint](../tendermint-core/using-tendermint.md).
  56. You should see Tendermint making blocks! We can get the status of our
  57. Tendermint node as follows:
  58. ```sh
  59. curl -s localhost:26657/status
  60. ```
  61. The `-s` just silences `curl`. For nicer output, pipe the result into a
  62. tool like [jq](https://stedolan.github.io/jq/) or `json_pp`.
  63. Now let's send some transactions to the kvstore.
  64. ```sh
  65. curl -s 'localhost:26657/broadcast_tx_commit?tx="abcd"'
  66. ```
  67. Note the single quote (`'`) around the url, which ensures that the
  68. double quotes (`"`) are not escaped by bash. This command sent a
  69. transaction with bytes `abcd`, so `abcd` will be stored as both the key
  70. and the value in the Merkle tree. The response should look something
  71. like:
  72. ```json
  73. {
  74. "jsonrpc": "2.0",
  75. "id": "",
  76. "result": {
  77. "check_tx": {},
  78. "deliver_tx": {
  79. "tags": [
  80. {
  81. "key": "YXBwLmNyZWF0b3I=",
  82. "value": "amFl"
  83. },
  84. {
  85. "key": "YXBwLmtleQ==",
  86. "value": "YWJjZA=="
  87. }
  88. ]
  89. },
  90. "hash": "9DF66553F98DE3C26E3C3317A3E4CED54F714E39",
  91. "height": 14
  92. }
  93. }
  94. ```
  95. We can confirm that our transaction worked and the value got stored by
  96. querying the app:
  97. ```sh
  98. curl -s 'localhost:26657/abci_query?data="abcd"'
  99. ```
  100. The result should look like:
  101. ```json
  102. {
  103. "jsonrpc": "2.0",
  104. "id": "",
  105. "result": {
  106. "response": {
  107. "log": "exists",
  108. "index": "-1",
  109. "key": "YWJjZA==",
  110. "value": "YWJjZA=="
  111. }
  112. }
  113. }
  114. ```
  115. Note the `value` in the result (`YWJjZA==`); this is the base64-encoding
  116. of the ASCII of `abcd`. You can verify this in a python 2 shell by
  117. running `"YWJjZA==".decode('base64')` or in python 3 shell by running
  118. `import codecs; codecs.decode(b"YWJjZA==", 'base64').decode('ascii')`.
  119. Stay tuned for a future release that [makes this output more
  120. human-readable](https://github.com/tendermint/tendermint/issues/1794).
  121. Now let's try setting a different key and value:
  122. ```sh
  123. curl -s 'localhost:26657/broadcast_tx_commit?tx="name=satoshi"'
  124. ```
  125. Now if we query for `name`, we should get `satoshi`, or `c2F0b3NoaQ==`
  126. in base64:
  127. ```sh
  128. curl -s 'localhost:26657/abci_query?data="name"'
  129. ```
  130. Try some other transactions and queries to make sure everything is
  131. working!
  132. ## CounterJS - Example in Another Language
  133. We also want to run applications in another language - in this case,
  134. we'll run a Javascript version of the `counter`. To run it, you'll need
  135. to [install node](https://nodejs.org/en/download/).
  136. You'll also need to fetch the relevant repository, from
  137. [here](https://github.com/tendermint/js-abci), then install it:
  138. ```sh
  139. git clone https://github.com/tendermint/js-abci.git
  140. cd js-abci
  141. npm install abci
  142. ```
  143. Kill the previous `counter` and `tendermint` processes. Now run the app:
  144. ```sh
  145. node example/counter.js
  146. ```
  147. In another window, reset and start `tendermint`:
  148. ```sh
  149. tendermint unsafe_reset_all
  150. tendermint start
  151. ```
  152. Once again, you should see blocks streaming by - but now, our
  153. application is written in Javascript! Try sending some transactions, and
  154. like before - the results should be the same:
  155. ```sh
  156. # ok
  157. curl localhost:26657/broadcast_tx_commit?tx=0x00
  158. # invalid nonce
  159. curl localhost:26657/broadcast_tx_commit?tx=0x05
  160. # ok
  161. curl localhost:26657/broadcast_tx_commit?tx=0x01
  162. ```
  163. Neat, eh?