github.com/fiagdao/tendermint@v0.32.11-0.20220824195748-2087fcc480c1/docs/app-dev/getting-started.md (about) 1 --- 2 order: 1 3 --- 4 5 # Getting Started 6 7 ## First Tendermint App 8 9 As a general purpose blockchain engine, Tendermint is agnostic to the 10 application you want to run. So, to run a complete blockchain that does 11 something useful, you must start two programs: one is Tendermint Core, 12 the other is your application, which can be written in any programming 13 language. Recall from [the intro to 14 ABCI](../introduction/what-is-tendermint.md#abci-overview) that Tendermint Core handles all the p2p and consensus stuff, and just forwards transactions to the 15 application when they need to be validated, or when they're ready to be 16 committed to a block. 17 18 In this guide, we show you some examples of how to run an application 19 using Tendermint. 20 21 ### Install 22 23 The first apps we will work with are written in Go. To install them, you 24 need to [install Go](https://golang.org/doc/install), put 25 `$GOPATH/bin` in your `$PATH` and enable go modules with these instructions: 26 ```bash 27 echo export GOPATH=\"\$HOME/go\" >> ~/.bash_profile 28 echo export PATH=\"\$PATH:\$GOPATH/bin\" >> ~/.bash_profile 29 echo export GO111MODULE=on >> ~/.bash_profile 30 ``` 31 32 Then run 33 34 ``` 35 go get github.com/tendermint/tendermint 36 cd $GOPATH/src/github.com/tendermint/tendermint 37 make tools 38 make install_abci 39 ``` 40 41 Now you should have the `abci-cli` installed; you'll see a couple of 42 commands (`counter` and `kvstore`) that are example applications written 43 in Go. See below for an application written in JavaScript. 44 45 Now, let's run some apps! 46 47 ## KVStore - A First Example 48 49 The kvstore app is a [Merkle 50 tree](https://en.wikipedia.org/wiki/Merkle_tree) that just stores all 51 transactions. If the transaction contains an `=`, e.g. `key=value`, then 52 the `value` is stored under the `key` in the Merkle tree. Otherwise, the 53 full transaction bytes are stored as the key and the value. 54 55 Let's start a kvstore application. 56 57 ``` 58 abci-cli kvstore 59 ``` 60 61 In another terminal, we can start Tendermint. You should already have the 62 Tendermint binary installed. If not, follow the steps from 63 [here](../introduction/install.md). If you have never run Tendermint 64 before, use: 65 66 ``` 67 tendermint init 68 tendermint node 69 ``` 70 71 If you have used Tendermint, you may want to reset the data for a new 72 blockchain by running `tendermint unsafe_reset_all`. Then you can run 73 `tendermint node` to start Tendermint, and connect to the app. For more 74 details, see [the guide on using Tendermint](../tendermint-core/using-tendermint.md). 75 76 You should see Tendermint making blocks! We can get the status of our 77 Tendermint node as follows: 78 79 ``` 80 curl -s localhost:26657/status 81 ``` 82 83 The `-s` just silences `curl`. For nicer output, pipe the result into a 84 tool like [jq](https://stedolan.github.io/jq/) or `json_pp`. 85 86 Now let's send some transactions to the kvstore. 87 88 ``` 89 curl -s 'localhost:26657/broadcast_tx_commit?tx="abcd"' 90 ``` 91 92 Note the single quote (`'`) around the url, which ensures that the 93 double quotes (`"`) are not escaped by bash. This command sent a 94 transaction with bytes `abcd`, so `abcd` will be stored as both the key 95 and the value in the Merkle tree. The response should look something 96 like: 97 98 ``` 99 { 100 "jsonrpc": "2.0", 101 "id": "", 102 "result": { 103 "check_tx": {}, 104 "deliver_tx": { 105 "tags": [ 106 { 107 "key": "YXBwLmNyZWF0b3I=", 108 "value": "amFl" 109 }, 110 { 111 "key": "YXBwLmtleQ==", 112 "value": "YWJjZA==" 113 } 114 ] 115 }, 116 "hash": "9DF66553F98DE3C26E3C3317A3E4CED54F714E39", 117 "height": 14 118 } 119 } 120 ``` 121 122 We can confirm that our transaction worked and the value got stored by 123 querying the app: 124 125 ``` 126 curl -s 'localhost:26657/abci_query?data="abcd"' 127 ``` 128 129 The result should look like: 130 131 ``` 132 { 133 "jsonrpc": "2.0", 134 "id": "", 135 "result": { 136 "response": { 137 "log": "exists", 138 "index": "-1", 139 "key": "YWJjZA==", 140 "value": "YWJjZA==" 141 } 142 } 143 } 144 ``` 145 146 Note the `value` in the result (`YWJjZA==`); this is the base64-encoding 147 of the ASCII of `abcd`. You can verify this in a python 2 shell by 148 running `"YWJjZA==".decode('base64')` or in python 3 shell by running 149 `import codecs; codecs.decode(b"YWJjZA==", 'base64').decode('ascii')`. 150 Stay tuned for a future release that [makes this output more 151 human-readable](https://github.com/tendermint/tendermint/issues/1794). 152 153 Now let's try setting a different key and value: 154 155 ``` 156 curl -s 'localhost:26657/broadcast_tx_commit?tx="name=satoshi"' 157 ``` 158 159 Now if we query for `name`, we should get `satoshi`, or `c2F0b3NoaQ==` 160 in base64: 161 162 ``` 163 curl -s 'localhost:26657/abci_query?data="name"' 164 ``` 165 166 Try some other transactions and queries to make sure everything is 167 working! 168 169 ## Counter - Another Example 170 171 Now that we've got the hang of it, let's try another application, the 172 `counter` app. 173 174 The counter app doesn't use a Merkle tree, it just counts how many times 175 we've sent a transaction, or committed the state. 176 177 This application has two modes: `serial=off` and `serial=on`. 178 179 When `serial=on`, transactions must be a big-endian encoded incrementing 180 integer, starting at 0. 181 182 If `serial=off`, there are no restrictions on transactions. 183 184 In a live blockchain, transactions collect in memory before they are 185 committed into blocks. To avoid wasting resources on invalid 186 transactions, ABCI provides the `CheckTx` message, which application 187 developers can use to accept or reject transactions, before they are 188 stored in memory or gossipped to other peers. 189 190 In this instance of the counter app, with `serial=on`, `CheckTx` only 191 allows transactions whose integer is greater than the last committed 192 one. 193 194 Let's kill the previous instance of `tendermint` and the `kvstore` 195 application, and start the counter app. We can enable `serial=on` with a 196 flag: 197 198 ``` 199 abci-cli counter --serial 200 ``` 201 202 In another window, reset then start Tendermint: 203 204 ``` 205 tendermint unsafe_reset_all 206 tendermint node 207 ``` 208 209 Once again, you can see the blocks streaming by. Let's send some 210 transactions. Since we have set `serial=on`, the first transaction must 211 be the number `0`: 212 213 ``` 214 curl localhost:26657/broadcast_tx_commit?tx=0x00 215 ``` 216 217 Note the empty (hence successful) response. The next transaction must be 218 the number `1`. If instead, we try to send a `5`, we get an error: 219 220 ``` 221 > curl localhost:26657/broadcast_tx_commit?tx=0x05 222 { 223 "jsonrpc": "2.0", 224 "id": "", 225 "result": { 226 "check_tx": {}, 227 "deliver_tx": { 228 "code": 2, 229 "log": "Invalid nonce. Expected 1, got 5" 230 }, 231 "hash": "33B93DFF98749B0D6996A70F64071347060DC19C", 232 "height": 34 233 } 234 } 235 ``` 236 237 But if we send a `1`, it works again: 238 239 ``` 240 > curl localhost:26657/broadcast_tx_commit?tx=0x01 241 { 242 "jsonrpc": "2.0", 243 "id": "", 244 "result": { 245 "check_tx": {}, 246 "deliver_tx": {}, 247 "hash": "F17854A977F6FA7EEA1BD758E296710B86F72F3D", 248 "height": 60 249 } 250 } 251 ``` 252 253 For more details on the `broadcast_tx` API, see [the guide on using 254 Tendermint](../tendermint-core/using-tendermint.md). 255 256 ## CounterJS - Example in Another Language 257 258 We also want to run applications in another language - in this case, 259 we'll run a Javascript version of the `counter`. To run it, you'll need 260 to [install node](https://nodejs.org/en/download/). 261 262 You'll also need to fetch the relevant repository, from 263 [here](https://github.com/tendermint/js-abci), then install it: 264 265 ``` 266 git clone https://github.com/tendermint/js-abci.git 267 cd js-abci 268 npm install abci 269 ``` 270 271 Kill the previous `counter` and `tendermint` processes. Now run the app: 272 273 ``` 274 node example/counter.js 275 ``` 276 277 In another window, reset and start `tendermint`: 278 279 ``` 280 tendermint unsafe_reset_all 281 tendermint node 282 ``` 283 284 Once again, you should see blocks streaming by - but now, our 285 application is written in Javascript! Try sending some transactions, and 286 like before - the results should be the same: 287 288 ``` 289 # ok 290 curl localhost:26657/broadcast_tx_commit?tx=0x00 291 # invalid nonce 292 curl localhost:26657/broadcast_tx_commit?tx=0x05 293 # ok 294 curl localhost:26657/broadcast_tx_commit?tx=0x01 295 ``` 296 297 Neat, eh?