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.

163 lines
6.1 KiB

8 years ago
9 years ago
8 years ago
8 years ago
9 years ago
8 years ago
8 years ago
8 years ago
8 years ago
9 years ago
8 years ago
9 years ago
9 years ago
8 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
8 years ago
9 years ago
9 years ago
9 years ago
9 years ago
8 years ago
  1. # Tendermint Socket Protocol (ABCI)
  2. [![CircleCI](https://circleci.com/gh/tendermint/abci.svg?style=svg)](https://circleci.com/gh/tendermint/abci)
  3. Blockchains are a system for creating shared multi-master application state.
  4. **ABCI** is a socket protocol enabling a blockchain consensus engine, running in one process,
  5. to manage a blockchain application state, running in another.
  6. For more information on ABCI, motivations, and tutorials, please visit [our blog post](https://tendermint.com/blog/abci-the-tendermint-socket-protocol).
  7. Other implementations:
  8. * [cpp-abci](https://github.com/mdyring/cpp-abci) by Martin Dyring-Andersen
  9. * [js-abci](https://github.com/tendermint/js-abci)
  10. * [jABCI](https://github.com/jABCI/) for Java
  11. ## Contents
  12. This repository holds a number of important pieces:
  13. - `types/types.proto`
  14. - the protobuf file defining ABCI message types, and the optional grpc interface.
  15. - to build, run `make protoc`
  16. - see `protoc --help` and [the grpc docs](https://www.grpc.io/docs) for examples and details of other languages
  17. - golang implementation of ABCI client and server
  18. - two implementations:
  19. - asynchronous, ordered message passing over unix or tcp;
  20. - messages are serialized using protobuf and length prefixed
  21. - grpc
  22. - TendermintCore runs a client, and the application runs a server
  23. - `cmd/abci-cli`
  24. - command line tool wrapping the client for probing/testing a ABCI application
  25. - use `abci-cli --version` to get the ABCI version
  26. - examples:
  27. - the `cmd/counter` application, which illustrates nonce checking in txs
  28. - the `cmd/dummy` application, which illustrates a simple key-value merkle tree
  29. ## Message format
  30. Since this is a streaming protocol, all messages are encoded with a length-prefix followed by the message encoded in Protobuf3. Protobuf3 doesn't have an official length-prefix standard, so we use our own. The first byte represents the length of the big-endian encoded length.
  31. For example, if the Protobuf3 encoded ABCI message is `0xDEADBEEF` (4 bytes), the length-prefixed message is `0x0104DEADBEEF`. If the Protobuf3 encoded ABCI message is 65535 bytes long, the length-prefixed message would be like `0x02FFFF...`.
  32. Note this prefixing does not apply for grpc.
  33. ## Message types
  34. ABCI requests/responses are simple Protobuf messages. Check out the [schema file](https://github.com/tendermint/abci/blob/master/types/types.proto).
  35. #### DeliverTx
  36. * __Arguments__:
  37. * `Data ([]byte)`: The request transaction bytes
  38. * __Returns__:
  39. * `Code (uint32)`: Response code
  40. * `Data ([]byte)`: Result bytes, if any
  41. * `Log (string)`: Debug or error message
  42. * __Usage__:<br/>
  43. Append and run a transaction. If the transaction is valid, returns CodeType.OK
  44. #### CheckTx
  45. * __Arguments__:
  46. * `Data ([]byte)`: The request transaction bytes
  47. * __Returns__:
  48. * `Code (uint32)`: Response code
  49. * `Data ([]byte)`: Result bytes, if any
  50. * `Log (string)`: Debug or error message
  51. * __Usage__:<br/>
  52. Validate a mempool transaction, prior to broadcasting or proposing. This message should not mutate the main state, but application
  53. developers may want to keep a separate CheckTx state that gets reset upon Commit.
  54. CheckTx can happen interspersed with DeliverTx, but they happen on different connections - CheckTx from the mempool connection, and DeliverTx from the consensus connection. During Commit, the mempool is locked, so you can reset the mempool state to the latest state after running all those delivertxs, and then the mempool will re run whatever txs it has against that latest mempool stte
  55. Transactions are first run through CheckTx before broadcast to peers in the mempool layer.
  56. You can make CheckTx semi-stateful and clear the state upon `Commit` or `BeginBlock`,
  57. to allow for dependent sequences of transactions in the same block.
  58. #### Commit
  59. * __Returns__:
  60. * `Data ([]byte)`: The Merkle root hash
  61. * `Log (string)`: Debug or error message
  62. * __Usage__:<br/>
  63. Return a Merkle root hash of the application state.
  64. #### Query
  65. * __Arguments__:
  66. * `Data ([]byte)`: The query request bytes
  67. * __Returns__:
  68. * `Code (uint32)`: Response code
  69. * `Data ([]byte)`: The query response bytes
  70. * `Log (string)`: Debug or error message
  71. #### Flush
  72. * __Usage__:<br/>
  73. Flush the response queue. Applications that implement `types.Application` need not implement this message -- it's handled by the project.
  74. #### Info
  75. * __Returns__:
  76. * `Data ([]byte)`: The info bytes
  77. * __Usage__:<br/>
  78. Return information about the application state. Application specific.
  79. #### SetOption
  80. * __Arguments__:
  81. * `Key (string)`: Key to set
  82. * `Value (string)`: Value to set for key
  83. * __Returns__:
  84. * `Log (string)`: Debug or error message
  85. * __Usage__:<br/>
  86. Set application options. E.g. Key="mode", Value="mempool" for a mempool connection, or Key="mode", Value="consensus" for a consensus connection.
  87. Other options are application specific.
  88. #### InitChain
  89. * __Arguments__:
  90. * `Validators ([]Validator)`: Initial genesis validators
  91. * __Usage__:<br/>
  92. Called once upon genesis
  93. #### BeginBlock
  94. * __Arguments__:
  95. * `Height (uint64)`: The block height that is starting
  96. * __Usage__:<br/>
  97. Signals the beginning of a new block. Called prior to any DeliverTxs.
  98. #### EndBlock
  99. * __Arguments__:
  100. * `Height (uint64)`: The block height that ended
  101. * __Returns__:
  102. * `Validators ([]Validator)`: Changed validators with new voting powers (0 to remove)
  103. * __Usage__:<br/>
  104. Signals the end of a block. Called prior to each Commit after all transactions
  105. ## Changelog
  106. ##### Mar 26h, 2016
  107. * Introduce BeginBlock
  108. ##### Mar 6th, 2016
  109. * Added InitChain, EndBlock
  110. ##### Feb 14th, 2016
  111. * s/GetHash/Commit/g
  112. * Document Protobuf request/response fields
  113. ##### Jan 23th, 2016
  114. * Added CheckTx/Query ABCI message types
  115. * Added Result/Log fields to DeliverTx/CheckTx/SetOption
  116. * Removed Listener messages
  117. * Removed Code from ResponseSetOption and ResponseGetHash
  118. * Made examples BigEndian
  119. ##### Jan 12th, 2016
  120. * Added "RetCodeBadNonce = 0x06" return code
  121. ##### Jan 8th, 2016
  122. * Tendermint/ABCI now comes to consensus on the order first before DeliverTx.