core

package
v1.7.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 24, 2023 License: Apache-2.0, Apache-2.0 Imports: 34 Imported by: 0

README

Tendermint RPC

Pagination

Requests that return multiple items will be paginated to 30 items by default. You can specify further pages with the ?page parameter. You can also set a custom page size up to 100 with the ?per_page parameter.

Subscribing to events

The user can subscribe to events emitted by Tendermint, using /subscribe. If the maximum number of clients is reached or the client has too many subscriptions, an error will be returned. The subscription timeout is 5 sec. Each subscription has a buffer to accommodate short bursts of events or some slowness in clients. If the buffer gets full, the subscription will be canceled ("client is not pulling messages fast enough"). If Tendermint exits, all subscriptions are canceled ("Tendermint exited"). The user can unsubscribe using either /unsubscribe or /unsubscribe_all.

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

View Source 
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

View Source 
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(CM40Block, "height"),
	"cm39_block":               rpc.NewRPCFunc(Block, "height"),
	"block_by_hash":            rpc.NewRPCFunc(BlockByHash, "hash"),
	"block_info":               rpc.NewRPCFunc(BlockInfo, "height"),
	"block_results":            rpc.NewRPCFunc(BlockResults, "height"),
	"commit":                   rpc.NewRPCFunc(CommitIBC, "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, ""),
	"user_unconfirmed_txs":     rpc.NewRPCFunc(UserUnconfirmedTxs, "address,limit"),
	"user_num_unconfirmed_txs": rpc.NewRPCFunc(UserNumUnconfirmedTxs, "address"),
	"get_address_list":         rpc.NewRPCFunc(GetAddressList, ""),
	"block_search":             rpc.NewRPCFunc(BlockSearch, "query,page,per_page,order_by"),

	"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"),

	"tx_simulate_gas": rpc.NewRPCFunc(TxSimulateGasCost, "hash"),

	"get_enable_delete_min_gp_tx": rpc.NewRPCFunc(GetEnableDeleteMinGPTx, ""),
}

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 

func Block(ctx *rpctypes.Context, heightPtr *int64) (*ctypes.ResultBlock, error)

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 

func BlockByHash(ctx *rpctypes.Context, hash []byte) (*ctypes.ResultBlock, error)

BlockByHash gets block by hash. More: https://docs.tendermint.com/master/rpc/#/Info/block_by_hash

func BlockInfo added in v1.6.0 

func BlockInfo(ctx *rpctypes.Context, heightPtr *int64) (*types.BlockMeta, error)

Header gets block header at a given height. If no height is provided, it will fetch the latest header. More: https://docs.tendermint.com/master/rpc/#/Info/header

func BlockResults 

func BlockResults(ctx *rpctypes.Context, heightPtr *int64) (*ctypes.ResultBlockResults, error)

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 BlockSearch added in v1.6.7 

func BlockSearch(
	ctx *rpctypes.Context,
	query string,
	pagePtr, perPagePtr *int,
	orderBy string,
) (*ctypes.ResultBlockSearch, error)

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 

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 

func BroadcastTxAsync(ctx *rpctypes.Context, tx types.Tx) (*ctypes.ResultBroadcastTx, error)

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 

func BroadcastTxCommit(ctx *rpctypes.Context, tx types.Tx) (*ctypes.ResultBroadcastTxCommit, error)

BroadcastTxCommit returns with the responses from CheckTx and DeliverTx. More: https://docs.tendermint.com/master/rpc/#/Tx/broadcast_tx_commit

func BroadcastTxSync 

func BroadcastTxSync(ctx *rpctypes.Context, tx types.Tx) (*ctypes.ResultBroadcastTx, error)

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 CM40Block added in v1.6.2 

func CM40Block(ctx *rpctypes.Context, heightPtr *int64) (*ctypes.CM40ResultBlock, error)

func Commit 

func Commit(ctx *rpctypes.Context, heightPtr *int64) (*ctypes.ResultCommit, error)

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 CommitIBC added in v1.3.0 

func CommitIBC(ctx *rpctypes.Context, heightPtr *int64) (*ctypes.IBCResultCommit, error)

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 latest 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 ConvBlock2CM40Block added in v1.6.2 

func ConvBlock2CM40Block(r *types.Block) *types.CM40Block

func ConvBlockID2CM40BlockID added in v1.6.2 

func ConvBlockID2CM40BlockID(r types.BlockID) types.IBCBlockID

func ConvCommitToIBCCommit added in v1.3.0 

func ConvCommitToIBCCommit(hh *types.Header, h *types.Commit) *types.IBCCommit

func ConvEventBlock2CM40Event added in v1.6.7 

func ConvEventBlock2CM40Event(block types.EventDataNewBlock) types.CM40EventDataNewBlock

func ConvHeadersToIbcHeader added in v1.3.0 

func ConvHeadersToIbcHeader(h *types.Header) *types.IBCHeader

func ConvResultCommitTOIBC added in v1.3.0 

func ConvResultCommitTOIBC(r *coretypes.ResultCommit) *coretypes.IBCResultCommit

func ConvSignheaderToIBCSignHeader added in v1.3.0 

func ConvSignheaderToIBCSignHeader(h *types.SignedHeader) *types.IBCSignedHeader

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 GetAddressList 

func GetAddressList() (*ctypes.ResultUnconfirmedAddresses, error)

func GetEnableDeleteMinGPTx added in v1.6.7 

func GetEnableDeleteMinGPTx(ctx *rpctypes.Context) (*ctypes.ResultEnableDeleteMinGPTx, error)

func GetPendingNonce added in v1.1.7 

func GetPendingNonce(address string) (*ctypes.ResultPendingNonce, bool)

func GetUnconfirmedTxByHash 

func GetUnconfirmedTxByHash(hash [sha256.Size]byte) (types.Tx, error)

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 LatestBlockNumber added in v1.6.0 

func LatestBlockNumber() (int64, error)

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 SetEnvironment 

func SetEnvironment(e *Environment)

SetEnvironment sets up the given Environment. It will race if multiple Node call SetEnvironment.

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 

func Subscribe(ctx *rpctypes.Context, query string) (*ctypes.ResultSubscribe, error)

Subscribe for events via WebSocket. More: https://docs.tendermint.com/master/rpc/#/Websocket/subscribe

func Tx 

func Tx(ctx *rpctypes.Context, hash []byte, prove bool) (*ctypes.ResultTx, error)

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 TxSimulateGasCost added in v1.6.6 

func TxSimulateGasCost(ctx *rpctypes.Context, hash string) (*ctypes.ResponseTxSimulateGas, error)

func UnconfirmedTxs 

func UnconfirmedTxs(ctx *rpctypes.Context, limit int) (*ctypes.ResultUnconfirmedTxs, error)

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 

func UnsafeDialSeeds(ctx *rpctypes.Context, seeds []string) (*ctypes.ResultDialSeeds, error)

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 

func Unsubscribe(ctx *rpctypes.Context, query string) (*ctypes.ResultUnsubscribe, error)

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 UserNumUnconfirmedTxs 

func UserNumUnconfirmedTxs(address string) (*ctypes.ResultUserUnconfirmedTxs, error)

func UserUnconfirmedTxs 

func UserUnconfirmedTxs(address string, limit int) (*ctypes.ResultUserUnconfirmedTxs, error)

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 latest validator set. Note the validators are sorted by their voting power - 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

Types

type Consensus 

type Consensus interface {
	GetState() sm.State
	GetValidators() (int64, []*types.Validator)
	GetLastHeight() int64
	GetRoundStateJSON() ([]byte, error)
	GetRoundStateSimpleJSON() ([]byte, error)
}

type Environment 

type Environment struct {
	// external, thread safe interfaces
	ProxyAppQuery proxy.AppConnQuery

	// interfaces defined in types and above
	StateDB        dbm.DB
	BlockStore     sm.BlockStore
	EvidencePool   sm.EvidencePool
	ConsensusState Consensus
	P2PPeers       peers
	P2PTransport   transport

	// objects
	PubKey           crypto.PubKey
	GenDoc           *types.GenesisDoc // cache the genesis structure
	TxIndexer        txindex.TxIndexer
	BlockIndexer     blockindex.BlockIndexer
	ConsensusReactor *consensus.Reactor
	EventBus         *types.EventBus // thread safe
	Mempool          mempl.Mempool

	Logger log.Logger

	Config cfg.RPCConfig
}

---------------------------------------------- Environment contains objects and interfaces used by the RPC. It is expected to be setup once during startup.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.