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.

495 lines
17 KiB

7 years ago
7 years ago
6 years ago
7 years ago
7 years ago
7 years ago
6 years ago
7 years ago
6 years ago
7 years ago
6 years ago
6 years ago
6 years ago
7 years ago
6 years ago
7 years ago
6 years ago
7 years ago
6 years ago
6 years ago
6 years ago
7 years ago
6 years ago
7 years ago
6 years ago
7 years ago
6 years ago
7 years ago
6 years ago
6 years ago
6 years ago
7 years ago
6 years ago
6 years ago
7 years ago
6 years ago
6 years ago
6 years ago
6 years ago
7 years ago
7 years ago
6 years ago
7 years ago
6 years ago
6 years ago
6 years ago
7 years ago
7 years ago
6 years ago
7 years ago
6 years ago
7 years ago
6 years ago
7 years ago
6 years ago
6 years ago
7 years ago
6 years ago
7 years ago
6 years ago
6 years ago
7 years ago
6 years ago
7 years ago
6 years ago
7 years ago
6 years ago
7 years ago
6 years ago
6 years ago
6 years ago
6 years ago
  1. # Application Development Guide
  2. ## XXX
  3. This page is undergoing deprecation. All content is being moved to the new [home
  4. of the ABCI specification](../spec/abci/README.md).
  5. ## ABCI Design
  6. The purpose of ABCI is to provide a clean interface between state
  7. transition machines on one computer and the mechanics of their
  8. replication across multiple computers. The former we call 'application
  9. logic' and the latter the 'consensus engine'. Application logic
  10. validates transactions and optionally executes transactions against some
  11. persistent state. A consensus engine ensures all transactions are
  12. replicated in the same order on every machine. We call each machine in a
  13. consensus engine a 'validator', and each validator runs the same
  14. transactions through the same application logic. In particular, we are
  15. interested in blockchain-style consensus engines, where transactions are
  16. committed in hash-linked blocks.
  17. The ABCI design has a few distinct components:
  18. - message protocol
  19. - pairs of request and response messages
  20. - consensus makes requests, application responds
  21. - defined using protobuf
  22. - server/client
  23. - consensus engine runs the client
  24. - application runs the server
  25. - two implementations:
  26. - async raw bytes
  27. - grpc
  28. - blockchain protocol
  29. - abci is connection oriented
  30. - Tendermint Core maintains three connections:
  31. - [mempool connection](#mempool-connection): for checking if
  32. transactions should be relayed before they are committed;
  33. only uses `CheckTx`
  34. - [consensus connection](#consensus-connection): for executing
  35. transactions that have been committed. Message sequence is
  36. -for every block -`BeginBlock, [DeliverTx, ...], EndBlock, Commit`
  37. - [query connection](#query-connection): for querying the
  38. application state; only uses Query and Info
  39. The mempool and consensus logic act as clients, and each maintains an
  40. open ABCI connection with the application, which hosts an ABCI server.
  41. Shown are the request and response types sent on each connection.
  42. Most of the examples below are from [kvstore
  43. application](https://github.com/tendermint/tendermint/blob/develop/abci/example/kvstore/kvstore.go),
  44. which is a part of the abci repo. [persistent_kvstore
  45. application](https://github.com/tendermint/tendermint/blob/develop/abci/example/kvstore/persistent_kvstore.go)
  46. is used to show `BeginBlock`, `EndBlock` and `InitChain` example
  47. implementations.
  48. ## Blockchain Protocol
  49. In ABCI, a transaction is simply an arbitrary length byte-array. It is
  50. the application's responsibility to define the transaction codec as they
  51. please, and to use it for both CheckTx and DeliverTx.
  52. Note that there are two distinct means for running transactions,
  53. corresponding to stages of 'awareness' of the transaction in the
  54. network. The first stage is when a transaction is received by a
  55. validator from a client into the so-called mempool or transaction pool
  56. -this is where we use CheckTx. The second is when the transaction is
  57. successfully committed on more than 2/3 of validators - where we use
  58. DeliverTx. In the former case, it may not be necessary to run all the
  59. state transitions associated with the transaction, as the transaction
  60. may not ultimately be committed until some much later time, when the
  61. result of its execution will be different. For instance, an Ethereum
  62. ABCI app would check signatures and amounts in CheckTx, but would not
  63. actually execute any contract code until the DeliverTx, so as to avoid
  64. executing state transitions that have not been finalized.
  65. To formalize the distinction further, two explicit ABCI connections are
  66. made between Tendermint Core and the application: the mempool connection
  67. and the consensus connection. We also make a third connection, the query
  68. connection, to query the local state of the app.
  69. ### Mempool Connection
  70. The mempool connection is used _only_ for CheckTx requests. Transactions
  71. are run using CheckTx in the same order they were received by the
  72. validator. If the CheckTx returns `OK`, the transaction is kept in
  73. memory and relayed to other peers in the same order it was received.
  74. Otherwise, it is discarded.
  75. CheckTx requests run concurrently with block processing; so they should
  76. run against a copy of the main application state which is reset after
  77. every block. This copy is necessary to track transitions made by a
  78. sequence of CheckTx requests before they are included in a block. When a
  79. block is committed, the application must ensure to reset the mempool
  80. state to the latest committed state. Tendermint Core will then filter
  81. through all transactions in the mempool, removing any that were included
  82. in the block, and re-run the rest using CheckTx against the post-Commit
  83. mempool state (this behaviour can be turned off with
  84. `[mempool] recheck = false`).
  85. In go:
  86. ```
  87. func (app *KVStoreApplication) CheckTx(tx []byte) types.Result {
  88. return types.OK
  89. }
  90. ```
  91. In Java:
  92. ```
  93. ResponseCheckTx requestCheckTx(RequestCheckTx req) {
  94. byte[] transaction = req.getTx().toByteArray();
  95. // validate transaction
  96. if (notValid) {
  97. return ResponseCheckTx.newBuilder().setCode(CodeType.BadNonce).setLog("invalid tx").build();
  98. } else {
  99. return ResponseCheckTx.newBuilder().setCode(CodeType.OK).build();
  100. }
  101. }
  102. ```
  103. ### Replay Protection
  104. To prevent old transactions from being replayed, CheckTx must implement
  105. replay protection.
  106. Tendermint provides the first defence layer by keeping a lightweight
  107. in-memory cache of 100k (`[mempool] cache_size`) last transactions in
  108. the mempool. If Tendermint is just started or the clients sent more than
  109. 100k transactions, old transactions may be sent to the application. So
  110. it is important CheckTx implements some logic to handle them.
  111. There are cases where a transaction will (or may) become valid in some
  112. future state, in which case you probably want to disable Tendermint's
  113. cache. You can do that by setting `[mempool] cache_size = 0` in the
  114. config.
  115. ### Consensus Connection
  116. The consensus connection is used only when a new block is committed, and
  117. communicates all information from the block in a series of requests:
  118. `BeginBlock, [DeliverTx, ...], EndBlock, Commit`. That is, when a block
  119. is committed in the consensus, we send a list of DeliverTx requests (one
  120. for each transaction) sandwiched by BeginBlock and EndBlock requests,
  121. and followed by a Commit.
  122. ### DeliverTx
  123. DeliverTx is the workhorse of the blockchain. Tendermint sends the
  124. DeliverTx requests asynchronously but in order, and relies on the
  125. underlying socket protocol (ie. TCP) to ensure they are received by the
  126. app in order. They have already been ordered in the global consensus by
  127. the Tendermint protocol.
  128. DeliverTx returns a abci.Result, which includes a Code, Data, and Log.
  129. The code may be non-zero (non-OK), meaning the corresponding transaction
  130. should have been rejected by the mempool, but may have been included in
  131. a block by a Byzantine proposer.
  132. The block header will be updated (TODO) to include some commitment to
  133. the results of DeliverTx, be it a bitarray of non-OK transactions, or a
  134. merkle root of the data returned by the DeliverTx requests, or both.
  135. In go:
  136. ```
  137. // tx is either "key=value" or just arbitrary bytes
  138. func (app *KVStoreApplication) DeliverTx(tx []byte) types.Result {
  139. parts := strings.Split(string(tx), "=")
  140. if len(parts) == 2 {
  141. app.state.Set([]byte(parts[0]), []byte(parts[1]))
  142. } else {
  143. app.state.Set(tx, tx)
  144. }
  145. return types.OK
  146. }
  147. ```
  148. In Java:
  149. ```
  150. /**
  151. * Using Protobuf types from the protoc compiler, we always start with a byte[]
  152. */
  153. ResponseDeliverTx deliverTx(RequestDeliverTx request) {
  154. byte[] transaction = request.getTx().toByteArray();
  155. // validate your transaction
  156. if (notValid) {
  157. return ResponseDeliverTx.newBuilder().setCode(CodeType.BadNonce).setLog("transaction was invalid").build();
  158. } else {
  159. ResponseDeliverTx.newBuilder().setCode(CodeType.OK).build();
  160. }
  161. }
  162. ```
  163. ### Commit
  164. Once all processing of the block is complete, Tendermint sends the
  165. Commit request and blocks waiting for a response. While the mempool may
  166. run concurrently with block processing (the BeginBlock, DeliverTxs, and
  167. EndBlock), it is locked for the Commit request so that its state can be
  168. safely reset during Commit. This means the app _MUST NOT_ do any
  169. blocking communication with the mempool (ie. broadcast_tx) during
  170. Commit, or there will be deadlock. Note also that all remaining
  171. transactions in the mempool are replayed on the mempool connection
  172. (CheckTx) following a commit.
  173. The app should respond to the Commit request with a byte array, which is
  174. the deterministic state root of the application. It is included in the
  175. header of the next block. It can be used to provide easily verified
  176. Merkle-proofs of the state of the application.
  177. It is expected that the app will persist state to disk on Commit. The
  178. option to have all transactions replayed from some previous block is the
  179. job of the [Handshake](#handshake).
  180. In go:
  181. ```
  182. func (app *KVStoreApplication) Commit() types.Result {
  183. hash := app.state.Hash()
  184. return types.NewResultOK(hash, "")
  185. }
  186. ```
  187. In Java:
  188. ```
  189. ResponseCommit requestCommit(RequestCommit requestCommit) {
  190. // update the internal app-state
  191. byte[] newAppState = calculateAppState();
  192. // and return it to the node
  193. return ResponseCommit.newBuilder().setCode(CodeType.OK).setData(ByteString.copyFrom(newAppState)).build();
  194. }
  195. ```
  196. ### BeginBlock
  197. The BeginBlock request can be used to run some code at the beginning of
  198. every block. It also allows Tendermint to send the current block hash
  199. and header to the application, before it sends any of the transactions.
  200. The app should remember the latest height and header (ie. from which it
  201. has run a successful Commit) so that it can tell Tendermint where to
  202. pick up from when it restarts. See information on the Handshake, below.
  203. In go:
  204. ```
  205. // Track the block hash and header information
  206. func (app *PersistentKVStoreApplication) BeginBlock(params types.RequestBeginBlock) {
  207. // update latest block info
  208. app.blockHeader = params.Header
  209. // reset valset changes
  210. app.changes = make([]*types.Validator, 0)
  211. }
  212. ```
  213. In Java:
  214. ```
  215. /*
  216. * all types come from protobuf definition
  217. */
  218. ResponseBeginBlock requestBeginBlock(RequestBeginBlock req) {
  219. Header header = req.getHeader();
  220. byte[] prevAppHash = header.getAppHash().toByteArray();
  221. long prevHeight = header.getHeight();
  222. long numTxs = header.getNumTxs();
  223. // run your pre-block logic. Maybe prepare a state snapshot, message components, etc
  224. return ResponseBeginBlock.newBuilder().build();
  225. }
  226. ```
  227. ### EndBlock
  228. The EndBlock request can be used to run some code at the end of every block.
  229. Additionally, the response may contain a list of validators, which can be used
  230. to update the validator set. To add a new validator or update an existing one,
  231. simply include them in the list returned in the EndBlock response. To remove
  232. one, include it in the list with a `power` equal to `0`. Validator's `address`
  233. field can be left empty. Tendermint core will take care of updating the
  234. validator set. Note the change in voting power must be strictly less than 1/3
  235. per block if you want a light client to be able to prove the transition
  236. externally. See the [light client
  237. docs](https://godoc.org/github.com/tendermint/tendermint/lite#hdr-How_We_Track_Validators)
  238. for details on how it tracks validators.
  239. In go:
  240. ```
  241. // Update the validator set
  242. func (app *PersistentKVStoreApplication) EndBlock(req types.RequestEndBlock) types.ResponseEndBlock {
  243. return types.ResponseEndBlock{ValidatorUpdates: app.ValUpdates}
  244. }
  245. ```
  246. In Java:
  247. ```
  248. /*
  249. * Assume that one validator changes. The new validator has a power of 10
  250. */
  251. ResponseEndBlock requestEndBlock(RequestEndBlock req) {
  252. final long currentHeight = req.getHeight();
  253. final byte[] validatorPubKey = getValPubKey();
  254. ResponseEndBlock.Builder builder = ResponseEndBlock.newBuilder();
  255. builder.addDiffs(1, Types.Validator.newBuilder().setPower(10L).setPubKey(ByteString.copyFrom(validatorPubKey)).build());
  256. return builder.build();
  257. }
  258. ```
  259. ### Query Connection
  260. This connection is used to query the application without engaging
  261. consensus. It's exposed over the tendermint core rpc, so clients can
  262. query the app without exposing a server on the app itself, but they must
  263. serialize each query as a single byte array. Additionally, certain
  264. "standardized" queries may be used to inform local decisions, for
  265. instance about which peers to connect to.
  266. Tendermint Core currently uses the Query connection to filter peers upon
  267. connecting, according to IP address or node ID. For instance,
  268. returning non-OK ABCI response to either of the following queries will
  269. cause Tendermint to not connect to the corresponding peer:
  270. - `p2p/filter/addr/<ip addr>`, where `<ip addr>` is an IP address.
  271. - `p2p/filter/id/<id>`, where `<is>` is the hex-encoded node ID (the hash of
  272. the node's p2p pubkey).
  273. Note: these query formats are subject to change!
  274. In go:
  275. ```
  276. func (app *KVStoreApplication) Query(reqQuery types.RequestQuery) (resQuery types.ResponseQuery) {
  277. if reqQuery.Prove {
  278. value, proof, exists := app.state.GetWithProof(reqQuery.Data)
  279. resQuery.Index = -1 // TODO make Proof return index
  280. resQuery.Key = reqQuery.Data
  281. resQuery.Value = value
  282. resQuery.Proof = proof
  283. if exists {
  284. resQuery.Log = "exists"
  285. } else {
  286. resQuery.Log = "does not exist"
  287. }
  288. return
  289. } else {
  290. index, value, exists := app.state.Get(reqQuery.Data)
  291. resQuery.Index = int64(index)
  292. resQuery.Value = value
  293. if exists {
  294. resQuery.Log = "exists"
  295. } else {
  296. resQuery.Log = "does not exist"
  297. }
  298. return
  299. }
  300. }
  301. return
  302. } else {
  303. index, value, exists := app.state.Get(reqQuery.Data)
  304. resQuery.Index = int64(index)
  305. resQuery.Value = value
  306. if exists {
  307. resQuery.Log = "exists"
  308. } else {
  309. resQuery.Log = "does not exist"
  310. }
  311. return
  312. }
  313. }
  314. ```
  315. In Java:
  316. ```
  317. ResponseQuery requestQuery(RequestQuery req) {
  318. final boolean isProveQuery = req.getProve();
  319. final ResponseQuery.Builder responseBuilder = ResponseQuery.newBuilder();
  320. byte[] queryData = req.getData().toByteArray();
  321. if (isProveQuery) {
  322. com.app.example.QueryResultWithProof result = generateQueryResultWithProof(queryData);
  323. responseBuilder.setIndex(result.getLeftIndex());
  324. responseBuilder.setKey(req.getData());
  325. responseBuilder.setValue(result.getValueOrNull(0));
  326. responseBuilder.setHeight(result.getHeight());
  327. responseBuilder.setProof(result.getProof());
  328. responseBuilder.setLog(result.getLogValue());
  329. } else {
  330. com.app.example.QueryResult result = generateQueryResult(queryData);
  331. responseBuilder.setIndex(result.getIndex());
  332. responseBuilder.setValue(result.getValue());
  333. responseBuilder.setLog(result.getLogValue());
  334. }
  335. responseBuilder.setIndex(result.getIndex());
  336. responseBuilder.setValue(ByteString.copyFrom(result.getValue()));
  337. responseBuilder.setLog(result.getLogValue());
  338. }
  339. return responseBuilder.build();
  340. }
  341. ```
  342. ### Handshake
  343. When the app or tendermint restarts, they need to sync to a common
  344. height. When an ABCI connection is first established, Tendermint will
  345. call `Info` on the Query connection. The response should contain the
  346. LastBlockHeight and LastBlockAppHash - the former is the last block for
  347. which the app ran Commit successfully, the latter is the response from
  348. that Commit.
  349. Using this information, Tendermint will determine what needs to be
  350. replayed, if anything, against the app, to ensure both Tendermint and
  351. the app are synced to the latest block height.
  352. If the app returns a LastBlockHeight of 0, Tendermint will just replay
  353. all blocks.
  354. In go:
  355. ```
  356. func (app *KVStoreApplication) Info(req types.RequestInfo) (resInfo types.ResponseInfo) {
  357. return types.ResponseInfo{Data: fmt.Sprintf("{\"size\":%v}", app.state.Size())}
  358. }
  359. ```
  360. In Java:
  361. ```
  362. ResponseInfo requestInfo(RequestInfo req) {
  363. final byte[] lastAppHash = getLastAppHash();
  364. final long lastHeight = getLastHeight();
  365. return ResponseInfo.newBuilder().setLastBlockAppHash(ByteString.copyFrom(lastAppHash)).setLastBlockHeight(lastHeight).build();
  366. }
  367. ```
  368. ### Genesis
  369. `InitChain` will be called once upon the genesis. `params` includes the
  370. initial validator set. Later on, it may be extended to take parts of the
  371. consensus params.
  372. In go:
  373. ```
  374. // Save the validators in the merkle tree
  375. func (app *PersistentKVStoreApplication) InitChain(params types.RequestInitChain) {
  376. for _, v := range params.Validators {
  377. r := app.updateValidator(v)
  378. if r.IsErr() {
  379. app.logger.Error("Error updating validators", "r", r)
  380. }
  381. }
  382. }
  383. ```
  384. In Java:
  385. ```
  386. /*
  387. * all types come from protobuf definition
  388. */
  389. ResponseInitChain requestInitChain(RequestInitChain req) {
  390. final int validatorsCount = req.getValidatorsCount();
  391. final List<Types.Validator> validatorsList = req.getValidatorsList();
  392. validatorsList.forEach((validator) -> {
  393. long power = validator.getPower();
  394. byte[] validatorPubKey = validator.getPubKey().toByteArray();
  395. // do somehing for validator setup in app
  396. });
  397. return ResponseInitChain.newBuilder().build();
  398. }
  399. ```