From 79bfbebfff2be69252cf7a620f5cdc6274fcaa6d Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Fri, 27 Apr 2018 23:19:40 -0400 Subject: [PATCH] rpc: docs/comments --- CHANGELOG.md | 2 +- rpc/core/consensus.go | 113 +++++++++++++++++++++++++++++++++--- rpc/core/status.go | 73 +++++++++++------------ rpc/core/types/responses.go | 42 +++++++++++--- 4 files changed, 175 insertions(+), 55 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0a5a7081..facc6963 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -45,7 +45,7 @@ Some of these are breaking in the RPC response, but they're really bugs! - [spec] Document address format and pubkey encoding pre and post Amino - [rpc] Lower case JSON field names -- [rpc] Fix missing entries and lower case the fields in `/dump_consensus_state` +- [rpc] Fix missing entries, improve, and lower case the fields in `/dump_consensus_state` - [rpc] Fix NodeInfo.Channels format to hex - [rpc] Add Validator address to `/status` - [rpc] Fix `prove` in ABCIQuery diff --git a/rpc/core/consensus.go b/rpc/core/consensus.go index 191b658f..98b0699d 100644 --- a/rpc/core/consensus.go +++ b/rpc/core/consensus.go @@ -71,16 +71,111 @@ func Validators(heightPtr *int64) (*ctypes.ResultValidators, error) { // > The above command returns JSON structured like this: // // ```json -// { -// "error": "", -// "result": { -// "peer_round_states": [], -// "round_state": "RoundState{\n H:3537 R:0 S:RoundStepNewHeight\n StartTime: 2017-05-31 12:32:31.178653883 +0000 UTC\n CommitTime: 2017-05-31 12:32:30.178653883 +0000 UTC\n Validators: ValidatorSet{\n Proposer: Validator{E89A51D60F68385E09E716D353373B11F8FACD62 {PubKeyEd25519{68DFDA7E50F82946E7E8546BED37944A422CD1B831E70DF66BA3B8430593944D}} VP:10 A:0}\n Validators:\n Validator{E89A51D60F68385E09E716D353373B11F8FACD62 {PubKeyEd25519{68DFDA7E50F82946E7E8546BED37944A422CD1B831E70DF66BA3B8430593944D}} VP:10 A:0}\n }\n Proposal: \n ProposalBlock: nil-PartSet nil-Block\n LockedRound: 0\n LockedBlock: nil-PartSet nil-Block\n Votes: HeightVoteSet{H:3537 R:0~0\n VoteSet{H:3537 R:0 T:1 +2/3: BA{1:_} map[]}\n VoteSet{H:3537 R:0 T:2 +2/3: BA{1:_} map[]}\n }\n LastCommit: VoteSet{H:3536 R:0 T:2 +2/3:B7F988FBCDC68F9320E346EECAA76E32F6054654:1:673BE7C01F74 BA{1:X} map[]}\n LastValidators: ValidatorSet{\n Proposer: Validator{E89A51D60F68385E09E716D353373B11F8FACD62 {PubKeyEd25519{68DFDA7E50F82946E7E8546BED37944A422CD1B831E70DF66BA3B8430593944D}} VP:10 A:0}\n Validators:\n Validator{E89A51D60F68385E09E716D353373B11F8FACD62 {PubKeyEd25519{68DFDA7E50F82946E7E8546BED37944A422CD1B831E70DF66BA3B8430593944D}} VP:10 A:0}\n }\n}" -// }, -// "id": "", -// "jsonrpc": "2.0" -// } +//{ +// "jsonrpc": "2.0", +// "id": "", +// "result": { +// "round_state": { +// "height": 138, +// "round": 0, +// "step": 1, +// "start_time": "2018-04-27T23:16:34.472087096-04:00", +// "commit_time": "2018-04-27T23:16:33.472087096-04:00", +// "validators": { +// "validators": [ +// { +// "address": "5875562FF0FFDECC895C20E32FC14988952E99E7", +// "pub_key": { +// "type": "AC26791624DE60", +// "value": "PpDJRUrLG2RgFqYYjawfn/AcAgacSXpLFrmfYYQnuzE=" +// }, +// "voting_power": 10, +// "accum": 0 +// } +// ], +// "proposer": { +// "address": "5875562FF0FFDECC895C20E32FC14988952E99E7", +// "pub_key": { +// "type": "AC26791624DE60", +// "value": "PpDJRUrLG2RgFqYYjawfn/AcAgacSXpLFrmfYYQnuzE=" +// }, +// "voting_power": 10, +// "accum": 0 +// } +// }, +// "proposal": null, +// "proposal_block": null, +// "proposal_block_parts": null, +// "locked_round": 0, +// "locked_block": null, +// "locked_block_parts": null, +// "valid_round": 0, +// "valid_block": null, +// "valid_block_parts": null, +// "votes": [ +// { +// "round": 0, +// "prevotes": "_", +// "precommits": "_" +// } +// ], +// "commit_round": -1, +// "last_commit": { +// "votes": [ +// "Vote{0:5875562FF0FF 137/00/2(Precommit) 5701C93659EA /ED3588D7AF29.../ @ 2018-04-28T03:16:33.469Z}" +// ], +// "votes_bit_array": "x", +// "peer_maj_23s": {} +// }, +// "last_validators": { +// "validators": [ +// { +// "address": "5875562FF0FFDECC895C20E32FC14988952E99E7", +// "pub_key": { +// "type": "AC26791624DE60", +// "value": "PpDJRUrLG2RgFqYYjawfn/AcAgacSXpLFrmfYYQnuzE=" +// }, +// "voting_power": 10, +// "accum": 0 +// } +// ], +// "proposer": { +// "address": "5875562FF0FFDECC895C20E32FC14988952E99E7", +// "pub_key": { +// "type": "AC26791624DE60", +// "value": "PpDJRUrLG2RgFqYYjawfn/AcAgacSXpLFrmfYYQnuzE=" +// }, +// "voting_power": 10, +// "accum": 0 +// } +// } +// }, +// "peer_round_states": { +// "d4bf26bfa5e390b94d98106ab858abf64db26d48": { +// "Height": 136, +// "Round": 0, +// "Step": 1, +// "StartTime": "2018-04-27T23:16:33.841163812-04:00", +// "Proposal": false, +// "ProposalBlockPartsHeader": { +// "total": 1, +// "hash": "E27F2D13298F7CB14090EE60CD9AB214D2F5161F" +// }, +// "ProposalBlockParts": "x", +// "ProposalPOLRound": -1, +// "ProposalPOL": "_", +// "Prevotes": "_", +// "Precommits": "x", +// "LastCommitRound": 0, +// "LastCommit": null, +// "CatchupCommitRound": 0, +// "CatchupCommit": "_" +// } +// } +// } +//} // ``` +// UNSTABLE func DumpConsensusState() (*ctypes.ResultDumpConsensusState, error) { peers := p2pSwitch.Peers().List() peerRoundStates := make([]ctypes.PeerRoundState, len(peers)) diff --git a/rpc/core/status.go b/rpc/core/status.go index 32647add..4b2ceca2 100644 --- a/rpc/core/status.go +++ b/rpc/core/status.go @@ -25,42 +25,43 @@ import ( // > The above command returns JSON structured like this: // // ```json -// { -// "result": { -// "sync_info": { -// "syncing": false, -// "latest_block_time": "2017-12-07T18:19:47.617Z", -// "latest_block_height": 6, -// "latest_app_hash": "", -// "latest_block_hash": "A63D0C3307DEDCCFCC82ED411AE9108B70B29E02", -// } -// "validator_info": { -// "pub_key": { -// "data": "8C9A68070CBE33F9C445862BA1E9D96A75CEB68C0CF6ADD3652D07DCAC5D0380", -// "type": "ed25519" -// }, -// "voting_power": 10 -// } -// "node_info": { -// "other": [ -// "wire_version=0.7.2", -// "p2p_version=0.5.0", -// "consensus_version=v1/0.2.2", -// "rpc_version=0.7.0/3", -// "tx_index=on", -// "rpc_addr=tcp://0.0.0.0:46657" -// ], -// "version": "0.13.0-14ccc8b", -// "listen_addr": "10.0.2.15:46656", -// "remote_addr": "", -// "network": "test-chain-qhVCa2", -// "moniker": "vagrant-ubuntu-trusty-64", -// "pub_key": "844981FE99ABB19F7816F2D5E94E8A74276AB1153760A7799E925C75401856C6", -// } -// }, -// "id": "", -// "jsonrpc": "2.0" -// } +//{ +// "jsonrpc": "2.0", +// "id": "", +// "result": { +// "node_info": { +// "id": "562dd7f579f0ecee8c94a11a3c1e378c1876f433", +// "listen_addr": "192.168.1.2:46656", +// "network": "test-chain-I6zScH", +// "version": "0.19.0", +// "channels": "4020212223303800", +// "moniker": "Ethans-MacBook-Pro.local", +// "other": [ +// "amino_version=0.9.8", +// "p2p_version=0.5.0", +// "consensus_version=v1/0.2.2", +// "rpc_version=0.7.0/3", +// "tx_index=on", +// "rpc_addr=tcp://0.0.0.0:46657" +// ] +// }, +// "sync_info": { +// "latest_block_hash": "2D4D7055BE685E3CB2410603C92AD37AE557AC59", +// "latest_app_hash": "0000000000000000", +// "latest_block_height": 231, +// "latest_block_time": "2018-04-27T23:18:08.459766485-04:00", +// "syncing": false +// }, +// "validator_info": { +// "address": "5875562FF0FFDECC895C20E32FC14988952E99E7", +// "pub_key": { +// "type": "AC26791624DE60", +// "value": "PpDJRUrLG2RgFqYYjawfn/AcAgacSXpLFrmfYYQnuzE=" +// }, +// "voting_power": 10 +// } +// } +//} // ``` func Status() (*ctypes.ResultStatus, error) { latestHeight := blockStore.Height() diff --git a/rpc/core/types/responses.go b/rpc/core/types/responses.go index 3a60be82..be7d51f2 100644 --- a/rpc/core/types/responses.go +++ b/rpc/core/types/responses.go @@ -14,20 +14,24 @@ import ( "github.com/tendermint/tendermint/types" ) +// List of blocks type ResultBlockchainInfo struct { LastHeight int64 `json:"last_height"` BlockMetas []*types.BlockMeta `json:"block_metas"` } +// Genesis file type ResultGenesis struct { Genesis *types.GenesisDoc `json:"genesis"` } +// Single block (with meta) type ResultBlock struct { BlockMeta *types.BlockMeta `json:"block_meta"` Block *types.Block `json:"block"` } +// Commit and Header type ResultCommit struct { // SignedHeader is header and commit, embedded so we only have // one level in the json output @@ -35,6 +39,7 @@ type ResultCommit struct { CanonicalCommit bool `json:"canonical"` } +// ABCI results from a block type ResultBlockResults struct { Height int64 `json:"height"` Results *state.ABCIResponses `json:"results"` @@ -54,6 +59,7 @@ func NewResultCommit(header *types.Header, commit *types.Commit, } } +// Info about the node's syncing state type SyncInfo struct { LatestBlockHash cmn.HexBytes `json:"latest_block_hash"` LatestAppHash cmn.HexBytes `json:"latest_app_hash"` @@ -62,18 +68,21 @@ type SyncInfo struct { Syncing bool `json:"syncing"` } +// Info about the node's validator type ValidatorInfo struct { Address cmn.HexBytes `json:"address"` PubKey crypto.PubKey `json:"pub_key"` VotingPower int64 `json:"voting_power"` } +// Node Status type ResultStatus struct { NodeInfo p2p.NodeInfo `json:"node_info"` SyncInfo SyncInfo `json:"sync_info"` ValidatorInfo ValidatorInfo `json:"validator_info"` } +// Is TxIndexing enabled func (s *ResultStatus) TxIndexEnabled() bool { if s == nil { return false @@ -87,41 +96,51 @@ func (s *ResultStatus) TxIndexEnabled() bool { return false } +// Info about peer connections type ResultNetInfo struct { Listening bool `json:"listening"` Listeners []string `json:"listeners"` Peers []Peer `json:"peers"` } +// Log from dialing seeds type ResultDialSeeds struct { Log string `json:"log"` } +// Log from dialing peers type ResultDialPeers struct { Log string `json:"log"` } +// A peer type Peer struct { p2p.NodeInfo `json:"node_info"` IsOutbound bool `json:"is_outbound"` ConnectionStatus p2p.ConnectionStatus `json:"connection_status"` } +// Validators for a height type ResultValidators struct { BlockHeight int64 `json:"block_height"` Validators []*types.Validator `json:"validators"` } +// Info about the consensus state. +// Unstable type ResultDumpConsensusState struct { RoundState json.RawMessage `json:"round_state"` PeerRoundStates []PeerRoundState `json:"peer_round_states"` } +// Raw JSON for the PeerRoundState +// Unstable type PeerRoundState struct { NodeAddress string `json:"node_address"` PeerRoundState json.RawMessage `json:"peer_round_state"` } +// CheckTx result type ResultBroadcastTx struct { Code uint32 `json:"code"` Data cmn.HexBytes `json:"data"` @@ -130,6 +149,7 @@ type ResultBroadcastTx struct { Hash cmn.HexBytes `json:"hash"` } +// CheckTx and DeliverTx results type ResultBroadcastTxCommit struct { CheckTx abci.ResponseCheckTx `json:"check_tx"` DeliverTx abci.ResponseDeliverTx `json:"deliver_tx"` @@ -137,6 +157,7 @@ type ResultBroadcastTxCommit struct { Height int64 `json:"height"` } +// Result of querying for a tx type ResultTx struct { Hash cmn.HexBytes `json:"hash"` Height int64 `json:"height"` @@ -146,30 +167,33 @@ type ResultTx struct { Proof types.TxProof `json:"proof,omitempty"` } +// List of mempool txs type ResultUnconfirmedTxs struct { N int `json:"n_txs"` Txs []types.Tx `json:"txs"` } +// Info abci msg type ResultABCIInfo struct { Response abci.ResponseInfo `json:"response"` } +// Query abci msg type ResultABCIQuery struct { Response abci.ResponseQuery `json:"response"` } -type ResultUnsafeFlushMempool struct{} - -type ResultUnsafeProfile struct{} - -type ResultSubscribe struct{} - -type ResultUnsubscribe struct{} +// empty results +type ( + ResultUnsafeFlushMempool struct{} + ResultUnsafeProfile struct{} + ResultSubscribe struct{} + ResultUnsubscribe struct{} + ResultHealth struct{} +) +// Event data from a subscription type ResultEvent struct { Query string `json:"query"` Data types.TMEventData `json:"data"` } - -type ResultHealth struct{}