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.

189 lines
4.9 KiB

  1. RPC
  2. ===
  3. Coming soon: RPC docs powered by `slate <https://github.com/lord/slate>`__. Until then, read on.
  4. Tendermint supports the following RPC protocols:
  5. - URI over HTTP
  6. - JSONRPC over HTTP
  7. - JSONRPC over websockets
  8. Tendermint RPC is build using `our own RPC
  9. library <https://github.com/tendermint/tendermint/tree/master/rpc/lib>`__.
  10. Documentation and tests for that library could be found at
  11. ``tendermint/rpc/lib`` directory.
  12. Configuration
  13. ~~~~~~~~~~~~~
  14. Set the ``laddr`` config parameter under ``[rpc]`` table in the
  15. $TMHOME/config/config.toml file or the ``--rpc.laddr`` command-line flag to the
  16. desired protocol://host:port setting. Default: ``tcp://0.0.0.0:46657``.
  17. Arguments
  18. ~~~~~~~~~
  19. Arguments which expect strings or byte arrays may be passed as quoted
  20. strings, like ``"abc"`` or as ``0x``-prefixed strings, like
  21. ``0x616263``.
  22. URI/HTTP
  23. ~~~~~~~~
  24. Example request:
  25. .. code:: bash
  26. curl -s 'http://localhost:46657/broadcast_tx_sync?tx="abc"' | jq .
  27. Response:
  28. .. code:: json
  29. {
  30. "error": "",
  31. "result": {
  32. "hash": "2B8EC32BA2579B3B8606E42C06DE2F7AFA2556EF",
  33. "log": "",
  34. "data": "",
  35. "code": 0
  36. },
  37. "id": "",
  38. "jsonrpc": "2.0"
  39. }
  40. The first entry in the result-array (``96``) is the method this response
  41. correlates with. ``96`` refers to "ResultTypeBroadcastTx", see
  42. `responses.go <https://github.com/tendermint/tendermint/blob/master/rpc/core/types/responses.go>`__
  43. for a complete overview.
  44. JSONRPC/HTTP
  45. ~~~~~~~~~~~~
  46. JSONRPC requests can be POST'd to the root RPC endpoint via HTTP (e.g.
  47. ``http://localhost:46657/``).
  48. Example request:
  49. .. code:: json
  50. {
  51. "method": "broadcast_tx_sync",
  52. "jsonrpc": "2.0",
  53. "params": [ "abc" ],
  54. "id": "dontcare"
  55. }
  56. JSONRPC/websockets
  57. ~~~~~~~~~~~~~~~~~~
  58. JSONRPC requests can be made via websocket. The websocket endpoint is at
  59. ``/websocket``, e.g. ``http://localhost:46657/websocket``. Asynchronous
  60. RPC functions like event ``subscribe`` and ``unsubscribe`` are only
  61. available via websockets.
  62. Endpoints
  63. ~~~~~~~~~
  64. An HTTP Get request to the root RPC endpoint (e.g.
  65. ``http://localhost:46657``) shows a list of available endpoints.
  66. ::
  67. Available endpoints:
  68. http://localhost:46657/abci_info
  69. http://localhost:46657/dump_consensus_state
  70. http://localhost:46657/genesis
  71. http://localhost:46657/net_info
  72. http://localhost:46657/num_unconfirmed_txs
  73. http://localhost:46657/status
  74. http://localhost:46657/unconfirmed_txs
  75. http://localhost:46657/unsafe_flush_mempool
  76. http://localhost:46657/unsafe_stop_cpu_profiler
  77. http://localhost:46657/validators
  78. Endpoints that require arguments:
  79. http://localhost:46657/abci_query?path=_&data=_&prove=_
  80. http://localhost:46657/block?height=_
  81. http://localhost:46657/blockchain?minHeight=_&maxHeight=_
  82. http://localhost:46657/broadcast_tx_async?tx=_
  83. http://localhost:46657/broadcast_tx_commit?tx=_
  84. http://localhost:46657/broadcast_tx_sync?tx=_
  85. http://localhost:46657/commit?height=_
  86. http://localhost:46657/dial_seeds?seeds=_
  87. http://localhost:46657/dial_peers?peers=_&persistent=_
  88. http://localhost:46657/subscribe?event=_
  89. http://localhost:46657/tx?hash=_&prove=_
  90. http://localhost:46657/unsafe_start_cpu_profiler?filename=_
  91. http://localhost:46657/unsafe_write_heap_profile?filename=_
  92. http://localhost:46657/unsubscribe?event=_
  93. tx
  94. ~~
  95. Returns a transaction matching the given transaction hash.
  96. **Parameters**
  97. 1. hash - the transaction hash
  98. 2. prove - include a proof of the transaction inclusion in the block in
  99. the result (optional, default: false)
  100. **Returns**
  101. - ``proof``: the ``types.TxProof`` object
  102. - ``tx``: ``[]byte`` - the transaction
  103. - ``tx_result``: the ``abci.Result`` object
  104. - ``index``: ``int`` - index of the transaction
  105. - ``height``: ``int`` - height of the block where this transaction was
  106. in
  107. **Example**
  108. .. code:: bash
  109. curl -s 'http://localhost:46657/broadcast_tx_commit?tx="abc"' | jq .
  110. # {
  111. # "error": "",
  112. # "result": {
  113. # "hash": "2B8EC32BA2579B3B8606E42C06DE2F7AFA2556EF",
  114. # "log": "",
  115. # "data": "",
  116. # "code": 0
  117. # },
  118. # "id": "",
  119. # "jsonrpc": "2.0"
  120. # }
  121. curl -s 'http://localhost:46657/tx?hash=0x2B8EC32BA2579B3B8606E42C06DE2F7AFA2556EF' | jq .
  122. # {
  123. # "error": "",
  124. # "result": {
  125. # "proof": {
  126. # "Proof": {
  127. # "aunts": []
  128. # },
  129. # "Data": "YWJjZA==",
  130. # "RootHash": "2B8EC32BA2579B3B8606E42C06DE2F7AFA2556EF",
  131. # "Total": 1,
  132. # "Index": 0
  133. # },
  134. # "tx": "YWJjZA==",
  135. # "tx_result": {
  136. # "log": "",
  137. # "data": "",
  138. # "code": 0
  139. # },
  140. # "index": 0,
  141. # "height": 52
  142. # },
  143. # "id": "",
  144. # "jsonrpc": "2.0"
  145. # }
  146. More Examples
  147. ~~~~~~~~~~~~~
  148. See the various bash tests using curl in ``test/``, and examples using
  149. the ``Go`` API in ``rpc/client/``.