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.

116 lines
4.4 KiB

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
9 years ago
  1. # Tendermint Socket Protocol (TMSP)
  2. Blockchains are a system for creating shared multi-master application state.
  3. **TMSP** is a socket protocol enabling a blockchain consensus engine, running in one process,
  4. to manage a blockchain application state, running in another.
  5. For more information on TMSP, motivations, and tutorials, please visit [our blog post](http://tendermint.com/posts/tendermint-socket-protocol/).
  6. ## Message types
  7. TMSP requests/responses are simple Protobuf messages. Check out the [schema file](https://github.com/tendermint/tmsp/blob/master/types/types.proto).
  8. #### AppendTx
  9. * __Arguments__:
  10. * `Data ([]byte)`: The request transaction bytes
  11. * __Returns__:
  12. * `Code (uint32)`: Response code
  13. * `Data ([]byte)`: Result bytes, if any
  14. * `Log (string)`: Debug or error message
  15. * __Usage__:<br/>
  16. Append and run a transaction. If the transaction is valid, returns CodeType.OK
  17. #### CheckTx
  18. * __Arguments__:
  19. * `Data ([]byte)`: The request transaction bytes
  20. * __Returns__:
  21. * `Code (uint32)`: Response code
  22. * `Data ([]byte)`: Result bytes, if any
  23. * `Log (string)`: Debug or error message
  24. * __Usage__:<br/>
  25. Validate a transaction. This message should not mutate the state.
  26. Transactions are first run through CheckTx before broadcast to peers in the mempool layer.
  27. You can make CheckTx semi-stateful and clear the state upon `Commit`, to ensure that all txs in the blockchain are valid.
  28. #### Commit
  29. * __Returns__:
  30. * `Data ([]byte)`: The Merkle root hash
  31. * `Log (string)`: Debug or error message
  32. * __Usage__:<br/>
  33. Return a Merkle root hash of the application state.
  34. #### Query
  35. * __Arguments__:
  36. * `Data ([]byte)`: The query request bytes
  37. * __Returns__:
  38. * `Code (uint32)`: Response code
  39. * `Data ([]byte)`: The query response bytes
  40. * `Log (string)`: Debug or error message
  41. #### Flush
  42. * __Usage__:<br/>
  43. Flush the response queue. Applications that implement `types.Application` need not implement this message -- it's handled by the project.
  44. #### Info
  45. * __Returns__:
  46. * `Data ([]byte)`: The info bytes
  47. * __Usage__:<br/>
  48. Return information about the application state. Application specific.
  49. #### SetOption
  50. * __Arguments__:
  51. * `Key (string)`: Key to set
  52. * `Value (string)`: Value to set for key
  53. * __Returns__:
  54. * `Log (string)`: Debug or error message
  55. * __Usage__:<br/>
  56. Set application options. E.g. Key="mode", Value="mempool" for a mempool connection, or Key="mode", Value="consensus" for a consensus connection.
  57. Other options are application specific.
  58. #### InitChain
  59. * __Arguments__:
  60. * `Validators ([]Validator)`: Initial genesis validators
  61. * __Usage__:<br/>
  62. Called once upon genesis
  63. #### EndBlock
  64. * __Arguments__:
  65. * `Height (uint64)`: The block height that ended
  66. * __Returns__:
  67. * `Validators ([]Validator)`: Changed validators with new voting powers (0 to remove)
  68. * __Usage__:<br/>
  69. Signals the end of a block. Called prior to each Commit after all transactions
  70. ## Changelog
  71. ### Mar 6th, 2016
  72. * Added InitChain, EndBlock
  73. ### Feb 14th, 2016
  74. * s/GetHash/Commit/g
  75. * Document Protobuf request/response fields
  76. ### Jan 23th, 2016
  77. * Added CheckTx/Query TMSP message types
  78. * Added Result/Log fields to AppendTx/CheckTx/SetOption
  79. * Removed Listener messages
  80. * Removed Code from ResponseSetOption and ResponseGetHash
  81. * Made examples BigEndian
  82. ### Jan 12th, 2016
  83. * Added "RetCodeBadNonce = 0x06" return code
  84. ### Jan 8th, 2016
  85. Tendermint/TMSP now comes to consensus on the order first before AppendTx.
  86. This means that we no longer need the Commit/Rollback TMSP messages.
  87. Instead, there’s a “CheckTx” message for mempool to check the validity of a message.
  88. One consequence is that txs in blocks now may include invalid txs that are ignored.
  89. In the future, we can include a bitarray or merkle structure in the block so anyone can see which txs were valid.
  90. To prevent spam, applications can implement their “CheckTx” messages to deduct some balance, so at least spam txs will cost something. This isn’t any more work that what we already needed to do, so it’s not any worse.
  91. You can see the new changes in the tendermint/tendermint “order_first” branch, and tendermint/tmsp “order_first” branch. If you your TMSP apps to me I can help with the transition.
  92. Please take a look at how the examples in TMSP changed, e.g. how AppContext was removed, CheckTx was added, how the TMSP msg bytes changed, and how commit/rollback messages were removed.