Documentation ¶
Overview ¶
Introduction ¶
Tendermint supports the following RPC protocols:
* URI over HTTP * JSONRPC over HTTP * JSONRPC over websockets
Tendermint RPC is built using our own RPC library which contains its own set of documentation and tests. See it here: https://github.com/tendermint/tendermint/tree/master/rpc/lib
## Configuration
RPC can be configured by tuning parameters under `[rpc]` table in the `$TMHOME/config/config.toml` file or by using the `--rpc.X` command-line flags.
Default rpc listen address is `tcp://0.0.0.0:26657`. To set another address, set the `laddr` config parameter to desired value. CORS (Cross-Origin Resource Sharing) can be enabled by setting `cors_allowed_origins`, `cors_allowed_methods`, `cors_allowed_headers` config parameters.
## Arguments
Arguments which expect strings or byte arrays may be passed as quoted strings, like `"abc"` or as `0x`-prefixed strings, like `0x616263`.
## URI/HTTP
```bash curl 'localhost:26657/broadcast_tx_sync?tx="abc"' ```
> Response:
```json
{ "error": "", "result": { "hash": "2B8EC32BA2579B3B8606E42C06DE2F7AFA2556EF", "log": "", "data": "", "code": "0" }, "id": "", "jsonrpc": "2.0" }
```
## JSONRPC/HTTP
JSONRPC requests can be POST'd to the root RPC endpoint via HTTP (e.g. `http://localhost:26657/`).
```json
{ "method": "broadcast_tx_sync", "jsonrpc": "2.0", "params": [ "abc" ], "id": "dontcare" }
```
## JSONRPC/websockets
JSONRPC requests can be made via websocket. The websocket endpoint is at `/websocket`, e.g. `localhost:26657/websocket`. Asynchronous RPC functions like event `subscribe` and `unsubscribe` are only available via websockets.
## More Examples
See the various bash tests using curl in `test/`, and examples using the `Go` API in `rpc/client/`.
## Get the list
An HTTP Get request to the root RPC endpoint shows a list of available endpoints.
```bash curl 'localhost:26657' ```
> Response:
```plain Available endpoints: /abci_info /dump_consensus_state /genesis /net_info /num_unconfirmed_txs /status /health /unconfirmed_txs /unsafe_flush_mempool /unsafe_stop_cpu_profiler /validators
Endpoints that require arguments: /abci_query?path=_&data=_&prove=_ /block?height=_ /blockchain?minHeight=_&maxHeight=_ /broadcast_tx_async?tx=_ /broadcast_tx_commit?tx=_ /broadcast_tx_sync?tx=_ /commit?height=_ /dial_seeds?seeds=_ /dial_persistent_peers?persistent_peers=_ /subscribe?event=_ /tx?hash=_&prove=_ /unsafe_start_cpu_profiler?filename=_ /unsafe_write_heap_profile?filename=_ /unsubscribe?event=_ ```
Endpoints ¶
Index ¶
- Constants
- Variables
- func ABCIInfo(ctx *rpctypes.Context) (*ctypes.ResultABCIInfo, error)
- func ABCIQuery(ctx *rpctypes.Context, path string, data bytes.HexBytes, height int64, ...) (*ctypes.ResultABCIQuery, error)
- func AddUnsafeRoutes()
- func Block(ctx *rpctypes.Context, heightPtr *int64) (*ctypes.ResultBlock, error)
- func BlockByHash(ctx *rpctypes.Context, hash []byte) (*ctypes.ResultBlock, error)
- func BlockResults(ctx *rpctypes.Context, heightPtr *int64) (*ctypes.ResultBlockResults, error)
- func BlockchainInfo(ctx *rpctypes.Context, minHeight, maxHeight int64) (*ctypes.ResultBlockchainInfo, error)
- func BroadcastEvidence(ctx *rpctypes.Context, ev types.Evidence) (*ctypes.ResultBroadcastEvidence, error)
- func BroadcastTxAsync(ctx *rpctypes.Context, tx types.Tx) (*ctypes.ResultBroadcastTx, error)
- func BroadcastTxCommit(ctx *rpctypes.Context, tx types.Tx) (*ctypes.ResultBroadcastTxCommit, error)
- func BroadcastTxSync(ctx *rpctypes.Context, tx types.Tx) (*ctypes.ResultBroadcastTx, error)
- func Commit(ctx *rpctypes.Context, heightPtr *int64) (*ctypes.ResultCommit, error)
- func ConsensusParams(ctx *rpctypes.Context, heightPtr *int64) (*ctypes.ResultConsensusParams, error)
- func ConsensusState(ctx *rpctypes.Context) (*ctypes.ResultConsensusState, error)
- func DumpConsensusState(ctx *rpctypes.Context) (*ctypes.ResultDumpConsensusState, error)
- func Genesis(ctx *rpctypes.Context) (*ctypes.ResultGenesis, error)
- func Health(ctx *rpctypes.Context) (*ctypes.ResultHealth, error)
- func NetInfo(ctx *rpctypes.Context) (*ctypes.ResultNetInfo, error)
- func NumUnconfirmedTxs(ctx *rpctypes.Context) (*ctypes.ResultUnconfirmedTxs, error)
- func SetBlockStore(bs sm.BlockStore)
- func SetConfig(c cfg.RPCConfig)
- func SetConsensusReactor(conR *consensus.Reactor)
- func SetConsensusState(cs Consensus)
- func SetEventBus(b *types.EventBus)
- func SetEvidencePool(evpool sm.EvidencePool)
- func SetGenesisDoc(doc *types.GenesisDoc)
- func SetLogger(l log.Logger)
- func SetMempool(mem mempl.Mempool)
- func SetP2PPeers(p peers)
- func SetP2PTransport(t transport)
- func SetProxyAppQuery(appConn proxy.AppConnQuery)
- func SetPubKey(pk crypto.PubKey)
- func SetStateDB(db dbm.DB)
- func SetTxIndexer(indexer txindex.TxIndexer)
- func Status(ctx *rpctypes.Context) (*ctypes.ResultStatus, error)
- func Subscribe(ctx *rpctypes.Context, query string) (*ctypes.ResultSubscribe, error)
- func Tx(ctx *rpctypes.Context, hash []byte, prove bool) (*ctypes.ResultTx, error)
- func TxSearch(ctx *rpctypes.Context, query string, prove bool, page, perPage int, ...) (*ctypes.ResultTxSearch, error)
- func UnconfirmedTxs(ctx *rpctypes.Context, limit int) (*ctypes.ResultUnconfirmedTxs, error)
- func UnsafeDialPeers(ctx *rpctypes.Context, peers []string, persistent bool) (*ctypes.ResultDialPeers, error)
- func UnsafeDialSeeds(ctx *rpctypes.Context, seeds []string) (*ctypes.ResultDialSeeds, error)
- func UnsafeFlushMempool(ctx *rpctypes.Context) (*ctypes.ResultUnsafeFlushMempool, error)
- func UnsafeStartCPUProfiler(ctx *rpctypes.Context, filename string) (*ctypes.ResultUnsafeProfile, error)
- func UnsafeStopCPUProfiler(ctx *rpctypes.Context) (*ctypes.ResultUnsafeProfile, error)
- func UnsafeWriteHeapProfile(ctx *rpctypes.Context, filename string) (*ctypes.ResultUnsafeProfile, error)
- func Unsubscribe(ctx *rpctypes.Context, query string) (*ctypes.ResultUnsubscribe, error)
- func UnsubscribeAll(ctx *rpctypes.Context) (*ctypes.ResultUnsubscribe, error)
- func Validators(ctx *rpctypes.Context, heightPtr *int64, page, perPage int) (*ctypes.ResultValidators, error)
- type Consensus
Constants ¶
const ( // SubscribeTimeout is the maximum time we wait to subscribe for an event. // must be less than the server's write timeout (see rpcserver.DefaultConfig) SubscribeTimeout = 5 * time.Second )
Variables ¶
var Routes = map[string]*rpc.RPCFunc{ "subscribe": rpc.NewWSRPCFunc(Subscribe, "query"), "unsubscribe": rpc.NewWSRPCFunc(Unsubscribe, "query"), "unsubscribe_all": rpc.NewWSRPCFunc(UnsubscribeAll, ""), "health": rpc.NewRPCFunc(Health, ""), "status": rpc.NewRPCFunc(Status, ""), "net_info": rpc.NewRPCFunc(NetInfo, ""), "blockchain": rpc.NewRPCFunc(BlockchainInfo, "minHeight,maxHeight"), "genesis": rpc.NewRPCFunc(Genesis, ""), "block": rpc.NewRPCFunc(Block, "height"), "block_by_hash": rpc.NewRPCFunc(BlockByHash, "hash"), "block_results": rpc.NewRPCFunc(BlockResults, "height"), "commit": rpc.NewRPCFunc(Commit, "height"), "tx": rpc.NewRPCFunc(Tx, "hash,prove"), "tx_search": rpc.NewRPCFunc(TxSearch, "query,prove,page,per_page,order_by"), "validators": rpc.NewRPCFunc(Validators, "height,page,per_page"), "dump_consensus_state": rpc.NewRPCFunc(DumpConsensusState, ""), "consensus_state": rpc.NewRPCFunc(ConsensusState, ""), "consensus_params": rpc.NewRPCFunc(ConsensusParams, "height"), "unconfirmed_txs": rpc.NewRPCFunc(UnconfirmedTxs, "limit"), "num_unconfirmed_txs": rpc.NewRPCFunc(NumUnconfirmedTxs, ""), "broadcast_tx_commit": rpc.NewRPCFunc(BroadcastTxCommit, "tx"), "broadcast_tx_sync": rpc.NewRPCFunc(BroadcastTxSync, "tx"), "broadcast_tx_async": rpc.NewRPCFunc(BroadcastTxAsync, "tx"), "abci_query": rpc.NewRPCFunc(ABCIQuery, "path,data,height,prove"), "abci_info": rpc.NewRPCFunc(ABCIInfo, ""), "broadcast_evidence": rpc.NewRPCFunc(BroadcastEvidence, "evidence"), }
TODO: better system than "unsafe" prefix NOTE: Amino is registered in rpc/core/types/codec.go.
Functions ¶
func ABCIInfo ¶
func ABCIInfo(ctx *rpctypes.Context) (*ctypes.ResultABCIInfo, error)
ABCIInfo gets some info about the application. More: https://docs.tendermint.com/master/rpc/#/ABCI/abci_info
func ABCIQuery ¶
func ABCIQuery( ctx *rpctypes.Context, path string, data bytes.HexBytes, height int64, prove bool, ) (*ctypes.ResultABCIQuery, error)
ABCIQuery queries the application for some information. More: https://docs.tendermint.com/master/rpc/#/ABCI/abci_query
func AddUnsafeRoutes ¶
func AddUnsafeRoutes()
func Block ¶
Block gets block at a given height. If no height is provided, it will fetch the latest block. More: https://docs.tendermint.com/master/rpc/#/Info/block
func BlockByHash ¶ added in v0.33.0
BlockByHash gets block by hash. More: https://docs.tendermint.com/master/rpc/#/Info/block_by_hash
func BlockResults ¶
BlockResults gets ABCIResults at a given height. If no height is provided, it will fetch results for the latest block.
Results are for the height of the block containing the txs. Thus response.results.deliver_tx[5] is the results of executing getBlock(h).Txs[5] More: https://docs.tendermint.com/master/rpc/#/Info/block_results
func BlockchainInfo ¶
func BlockchainInfo(ctx *rpctypes.Context, minHeight, maxHeight int64) (*ctypes.ResultBlockchainInfo, error)
BlockchainInfo gets block headers for minHeight <= height <= maxHeight. Block headers are returned in descending order (highest first). More: https://docs.tendermint.com/master/rpc/#/Info/blockchain
func BroadcastEvidence ¶ added in v0.32.2
func BroadcastEvidence(ctx *rpctypes.Context, ev types.Evidence) (*ctypes.ResultBroadcastEvidence, error)
BroadcastEvidence broadcasts evidence of the misbehavior. More: https://docs.tendermint.com/master/rpc/#/Info/broadcast_evidence
func BroadcastTxAsync ¶
BroadcastTxAsync returns right away, with no response. Does not wait for CheckTx nor DeliverTx results. More: https://docs.tendermint.com/master/rpc/#/Tx/broadcast_tx_async
func BroadcastTxCommit ¶
BroadcastTxCommit returns with the responses from CheckTx and DeliverTx. More: https://docs.tendermint.com/master/rpc/#/Tx/broadcast_tx_commit
func BroadcastTxSync ¶
BroadcastTxSync returns with the response from CheckTx. Does not wait for DeliverTx result. More: https://docs.tendermint.com/master/rpc/#/Tx/broadcast_tx_sync
func Commit ¶
Commit gets block commit at a given height. If no height is provided, it will fetch the commit for the latest block. More: https://docs.tendermint.com/master/rpc/#/Info/commit
func ConsensusParams ¶
func ConsensusParams(ctx *rpctypes.Context, heightPtr *int64) (*ctypes.ResultConsensusParams, error)
ConsensusParams gets the consensus parameters at the given block height. If no height is provided, it will fetch the current consensus params. More: https://docs.tendermint.com/master/rpc/#/Info/consensus_params
func ConsensusState ¶
func ConsensusState(ctx *rpctypes.Context) (*ctypes.ResultConsensusState, error)
ConsensusState returns a concise summary of the consensus state. UNSTABLE More: https://docs.tendermint.com/master/rpc/#/Info/consensus_state
func DumpConsensusState ¶
func DumpConsensusState(ctx *rpctypes.Context) (*ctypes.ResultDumpConsensusState, error)
DumpConsensusState dumps consensus state. UNSTABLE More: https://docs.tendermint.com/master/rpc/#/Info/dump_consensus_state
func Genesis ¶
func Genesis(ctx *rpctypes.Context) (*ctypes.ResultGenesis, error)
Genesis returns genesis file. More: https://docs.tendermint.com/master/rpc/#/Info/genesis
func Health ¶
func Health(ctx *rpctypes.Context) (*ctypes.ResultHealth, error)
Health gets node health. Returns empty result (200 OK) on success, no response - in case of an error. More: https://docs.tendermint.com/master/rpc/#/Info/health
func NetInfo ¶
func NetInfo(ctx *rpctypes.Context) (*ctypes.ResultNetInfo, error)
NetInfo returns network info. More: https://docs.tendermint.com/master/rpc/#/Info/net_info
func NumUnconfirmedTxs ¶
func NumUnconfirmedTxs(ctx *rpctypes.Context) (*ctypes.ResultUnconfirmedTxs, error)
NumUnconfirmedTxs gets number of unconfirmed transactions. More: https://docs.tendermint.com/master/rpc/#/Info/num_unconfirmed_txs
func SetBlockStore ¶
func SetBlockStore(bs sm.BlockStore)
func SetConsensusReactor ¶
func SetConsensusState ¶
func SetConsensusState(cs Consensus)
func SetEventBus ¶
func SetEvidencePool ¶
func SetEvidencePool(evpool sm.EvidencePool)
func SetGenesisDoc ¶
func SetGenesisDoc(doc *types.GenesisDoc)
func SetMempool ¶
func SetP2PPeers ¶
func SetP2PPeers(p peers)
func SetP2PTransport ¶
func SetP2PTransport(t transport)
func SetProxyAppQuery ¶
func SetProxyAppQuery(appConn proxy.AppConnQuery)
func SetStateDB ¶
func SetTxIndexer ¶
func Status ¶
func Status(ctx *rpctypes.Context) (*ctypes.ResultStatus, error)
Status returns Tendermint status including node info, pubkey, latest block hash, app hash, block height and time. More: https://docs.tendermint.com/master/rpc/#/Info/status
func Subscribe ¶
Subscribe for events via WebSocket. More: https://docs.tendermint.com/master/rpc/#/Websocket/subscribe
func Tx ¶
Tx allows you to query the transaction results. `nil` could mean the transaction is in the mempool, invalidated, or was not sent in the first place. More: https://docs.tendermint.com/master/rpc/#/Info/tx
func TxSearch ¶
func TxSearch(ctx *rpctypes.Context, query string, prove bool, page, perPage int, orderBy string) ( *ctypes.ResultTxSearch, error)
TxSearch allows you to query for multiple transactions results. It returns a list of transactions (maximum ?per_page entries) and the total count. More: https://docs.tendermint.com/master/rpc/#/Info/tx_search
func UnconfirmedTxs ¶
UnconfirmedTxs gets unconfirmed transactions (maximum ?limit entries) including their number. More: https://docs.tendermint.com/master/rpc/#/Info/unconfirmed_txs
func UnsafeDialPeers ¶
func UnsafeDialPeers(ctx *rpctypes.Context, peers []string, persistent bool) (*ctypes.ResultDialPeers, error)
UnsafeDialPeers dials the given peers (comma-separated id@IP:PORT), optionally making them persistent.
func UnsafeDialSeeds ¶
UnsafeDialSeeds dials the given seeds (comma-separated id@IP:PORT).
func UnsafeFlushMempool ¶
func UnsafeFlushMempool(ctx *rpctypes.Context) (*ctypes.ResultUnsafeFlushMempool, error)
UnsafeFlushMempool removes all transactions from the mempool.
func UnsafeStartCPUProfiler ¶
func UnsafeStartCPUProfiler(ctx *rpctypes.Context, filename string) (*ctypes.ResultUnsafeProfile, error)
UnsafeStartCPUProfiler starts a pprof profiler using the given filename.
func UnsafeStopCPUProfiler ¶
func UnsafeStopCPUProfiler(ctx *rpctypes.Context) (*ctypes.ResultUnsafeProfile, error)
UnsafeStopCPUProfiler stops the running pprof profiler.
func UnsafeWriteHeapProfile ¶
func UnsafeWriteHeapProfile(ctx *rpctypes.Context, filename string) (*ctypes.ResultUnsafeProfile, error)
UnsafeWriteHeapProfile dumps a heap profile to the given filename.
func Unsubscribe ¶
Unsubscribe from events via WebSocket. More: https://docs.tendermint.com/master/rpc/#/Websocket/unsubscribe
func UnsubscribeAll ¶
func UnsubscribeAll(ctx *rpctypes.Context) (*ctypes.ResultUnsubscribe, error)
UnsubscribeAll from all events via WebSocket. More: https://docs.tendermint.com/master/rpc/#/Websocket/unsubscribe_all
func Validators ¶
func Validators(ctx *rpctypes.Context, heightPtr *int64, page, perPage int) (*ctypes.ResultValidators, error)
Validators gets the validator set at the given block height. If no height is provided, it will fetch the current validator set. Note the validators are sorted by their address - this is the canonical order for the validators in the set as used in computing their Merkle root. More: https://docs.tendermint.com/master/rpc/#/Info/validators