From 3a2bdcc332e5cbc68dfcc39936f0a396ec8838b8 Mon Sep 17 00:00:00 2001 From: Dave Collins Date: Mon, 15 Oct 2018 01:06:51 -0500 Subject: [PATCH] multi: Cleanup getblock and getblockheader RPCs. This modifies the getblock and getblockheader RPC results to be a little more consistent in their ordering, to include the extra data field in the getblockheader results, and to update the JSON-RPC API documentation for both to match reality. The documentation was missing several fields and had some typos. --- dcrjson/chainsvrresults.go | 5 +++-- docs/json_rpc_api.md | 14 +++++++------- rpcserver.go | 3 ++- rpcserverhelp.go | 12 +++++------- 4 files changed, 17 insertions(+), 17 deletions(-) diff --git a/dcrjson/chainsvrresults.go b/dcrjson/chainsvrresults.go index e9826b28..d7b594d6 100644 --- a/dcrjson/chainsvrresults.go +++ b/dcrjson/chainsvrresults.go @@ -82,9 +82,9 @@ type GetBlockVerboseResult struct { PoolSize uint32 `json:"poolsize"` Bits string `json:"bits"` SBits float64 `json:"sbits"` - Difficulty float64 `json:"difficulty"` ExtraData string `json:"extradata"` StakeVersion uint32 `json:"stakeversion"` + Difficulty float64 `json:"difficulty"` PreviousHash string `json:"previousblockhash"` NextHash string `json:"nextblockhash,omitempty"` } @@ -120,7 +120,6 @@ type GetBlockHeaderVerboseResult struct { Hash string `json:"hash"` Confirmations int64 `json:"confirmations"` Version int32 `json:"version"` - PreviousHash string `json:"previousblockhash,omitempty"` MerkleRoot string `json:"merkleroot"` StakeRoot string `json:"stakeroot"` VoteBits uint16 `json:"votebits"` @@ -135,8 +134,10 @@ type GetBlockHeaderVerboseResult struct { Size uint32 `json:"size"` Time int64 `json:"time"` Nonce uint32 `json:"nonce"` + ExtraData string `json:"extradata"` StakeVersion uint32 `json:"stakeversion"` Difficulty float64 `json:"difficulty"` + PreviousHash string `json:"previousblockhash,omitempty"` NextHash string `json:"nextblockhash,omitempty"` } diff --git a/docs/json_rpc_api.md b/docs/json_rpc_api.md index 6e86dde6..315430c3 100644 --- a/docs/json_rpc_api.md +++ b/docs/json_rpc_api.md @@ -280,10 +280,9 @@ the method name for further details such as parameter and return information. |Parameters|1. `block hash`: `(string, required)` the hash of the block.
2. `verbose`: `(boolean, optional, default=true)` specifies the block is returned as a JSON object instead of hex-encoded string.
3. `verbosetx`: `(boolean, optional, default=false)` specifies that each transaction is returned as a JSON object and only applies if the `verbose` flag is true.| |Description|Returns information about a block given its hash.| |Returns (verbose=false)|`"data" (string) hex-encoded bytes of the serialized block`| -|Returns (verbose=true, verbosetx=false)| `(json object)`
`hash`: `(string)` the hash of the block (same as provided).
`confirmations`: `(numeric)` the number of confirmations.
`size`: `(numeric)` the size of the block.
`height`: `(numeric)` the height of the block in the block chain.
`version`: `(numeric)` the block version.
`merkleroot`: (string) root hash of the merkle tree.
`stakeroot`: `(string)` root hash of the stake tree.
`tx`: `(json array of string)` the transaction hashes.
`stx`: `(json array of string)` the stake transaction hashes.
`transactionhash`: `(string)` hash of the parent transaction.
`time`: `(numeric)` the block time in seconds since 1 Jan 1970 GMT.
`nonce`: `(numeric)` the block nonce.
`bits`: `(numeric)` the bits which represent the block difficulty.
`sbits`: `(numeric)` the bits which represent the stake difficulty
`revocations`: `(numeric)` the number of nullified tickets.
`difficulty`: `(numeric)` the proof-of-work difficulty as a multiple of the minimum difficulty.
`previousblockhash`: `(string)` the hash of the previous block.
`nextblockhash`: `(string)` the hash of the next block.

`{"hash": "blockhash","confirmations": n, "size": n, "height": n,"version": n, "merkleroot": "hash","tx": ["transactionhash", ...],"stx": ["transactionhash", ...],"time": n, "revocations": n, "nonce": n, "bits": n, "difficulty": n.nn, "previousblockhash": "hash", "nextblockhash": "hash", ...}` -|Returns (verbose=true, verbosetx=true)|`(json object)`
`hash`: (string) the hash of the block (same as provided)
`confirmations`: `(numeric)` the number of confirmations.
`size`: `(numeric)` the size of the block.
`height`: `(numeric)` the height of the block in the block chain.
`version`: `(numeric)` the block version.
`merkleroot`: `(string)` root hash of the merkle tree.
`rawtx`: `(array of json objects)` the transactions as json objects.
`tx`: `(json array of string)` the transaction hashes.
`stx`: `(json array of string)` the stake transaction hashes.
`transactionhash`: `(string)` hash of the parent transaction.
`time`: `(numeric)` the block time in seconds since 1 Jan 1970 GMT.
`nonce`: `(numeric)` the block nonce.
`bits`: `(numeric)` the bits which represent the block difficulty.
`revocations`: `(numeric)` the number of nullified tickets.
`difficulty`: `(numeric)` the proof-of-work difficulty as a multiple of the minimum difficulty.
`previousblockhash`: `(string)` the hash of the previous block.
`nextblockhash`: `(string)` the hash of the next block.

`{"hash": "blockhash","confirmations": n, "size": n, "height": n,"version": n, "merkleroot": "hash", "rawtx":[...], "tx": ["transactionhash", ...], "tx": ["transactionhash", ...],"time": n, "revocations": n, "nonce": n, "bits": n, "difficulty": n.nn, "previousblockhash": "hash", "nextblockhash": "hash", ...}`| -|Example Return (verbose=false)|Newlines added for display purposes. The actual return does not contain newlines.
`"010000000000000000000000000000000000000000000000000000000000000000000000`
`3ba3edfd7a7b12b27ac72c3e67768f617fc81bc3888a51323a9fb8aa4b1e5e4a29ab5f49`
`ffff001d1dac2b7c01010000000100000000000000000000000000000000000000000000`
`00000000000000000000ffffffff4d04ffff001d0104455468652054696d65732030332f`
`4a616e2f32303039204368616e63656c6c6f72206f6e206272696e6b206f66207365636f`
`6e64206261696c6f757420666f722062616e6b73ffffffff0100f2052a01000000434104`
`678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb649f6bc3f`
`4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5fac00000000"`
| -|Example Return (verbose=true, verbosetx=false)|`"hash": "000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f", "confirmations": 277113,"size": 285, "height": 0, "version": 1, "merkleroot": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b", "tx": ["4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b", ...], "stx": ["4a616e2f32303039204368616e63656c6c6f72206f6e206272696e6b206f66207365636f", ...], "time": 1231006505, "nonce": 2083236893, "bits": "1d00ffff", "difficulty": 1, "previousblockhash": "0000000000000000000000000000000000000000000000000000000000000000", "nextblockhash": "00000000839a8e6886ab5951d76f411475428afc90947ee320161bbf18eb6048", ...}`| +|Returns (verbose=true, verbosetx=false)|`(json object)`
`hash`: `(string)` the hash of the block (same as provided).
`confirmations`: `(numeric)` the number of confirmations.
`size`: `(numeric)` the size of the block.
`height`: `(numeric)` the height of the block in the block chain.
`version`: `(numeric)` the block version.
`merkleroot`: `(string)` root hash of the merkle tree.
`stakeroot`: `(string)` root hash of the stake tree.
`tx`: `(json array of string)` the transaction hashes.
`stx`: `(json array of string)` the stake transaction hashes.
`time`: `(numeric)` the block time in seconds since 1 Jan 1970 GMT.
`nonce`: `(numeric)` the block nonce.
`votebits`: `(numeric)` the block voting results.
`finalstate`: `(string)` the final lottery state.
`voters`: `(numeric)` the number of votes.
`freshstake`: `(numeric)` the number of ticket purchases.
`revocations`: `(numeric)` the number of ticket revocations.
`poolsize`: `(numeric)` the total number of valid spendble tickets as of the block.
`bits`: `(numeric)` the bits which represent the block difficulty.
`sbits`: `(numeric)` the bits which represent the stake difficulty.
`difficulty`: `(numeric)` the proof-of-work difficulty as a multiple of the minimum difficulty.
`extradata`: `(string)` extra data for the block including the extra nonce used by proof-of-work miners.
`stakeversion`: `(string)` block stake version.
`previousblockhash`: `(string)` the hash of the previous block.
`nextblockhash`: `(string)` the hash of the next block (only if there is one).

`{"hash": "blockhash", "confirmations": n, "size": n, "height": n, "version": n, "merkleroot": "hash", "stakeroot": "hash", "tx": ["transactionhash", ...], "stx": ["transactionhash", ...], "time": n, "nonce": n, "votebits": n, "finalstate": "state", "voters": n, "freshstake": n, "revocations": n, "poolsize": n, "bits": n, "sbits": n.nn, "difficulty": n.nn, "extradata": "data", "stakeversion": n, previousblockhash": "hash", "nextblockhash": "hash"}`| +|Example Return (verbose=false)|Newlines added for display purposes. The actual return does not contain newlines.
`"01000000b926d1870d6f88760a8b10db0d4439e5cd74f3827fd4b6827443000000000000`
`35cade3c4cd99e7547d1dffe8474855dd363dff69b395428810466c985d067c800000000`
`000000000000000000000000000000000000000000000000000000000100000000000000`
`0000000000000000ffff011b00c2eb0b00000000020000007e01000080d8b856bac0f231`
`c84e3a6b6ad536d301000000000000000000000000000000000000000000000000000000`
`010100000001000000000000000000000000000000000000000000000000000000000000`
`0000ffffffff00ffffffff03fa1a981200000000000017a914f5916158e3e2c4551c1796`
`708db8367207ed13bb8700000000000000000000266a2402000000000000000000000000`
`000000000000000000000000000000ffa310d9a6a9588edea1906f0000000000001976a9`
`148ffe7a49ecf0f4858e7a52155302177398d2296988ac000000000000000001d8bc2882`
`0000000000000000ffffffff0800002f646372642f00"`
| +|Example Return (verbose=true, verbosetx=false)|`"hash": "000000000000c41019872ff7db8fd2e9bfa05f42d3f8fee8e895e8c1e5b8dcba", "confirmations": 283285,"size": 382, "height": 2, "version": 1, "merkleroot": "c867d085c96604812854399bf6df63d35d857484fedfd147759ed94c3cdeca35", "stakeroot": "000000000000000000000000000000000000000000000000000000000000000", tx": ["ba8d2fcb5c705a1e5cbeda0db9dd30a521e360efd3aef75e862b2b69e0a673af", ...], "time": 1454954624, "nonce": 837992634, "votebits": 1, "finalstate": "000000000000", "voters": 0, "freshstake": 0, "revocations": 0, "poolsize": 0, "bits": "1d00ffff", "sbits": 2, "difficulty": 32767.74999809, "extradata": "c84e3a6b6ad536d3010000000000000000000000000000000000000000000000", "stakeversion": 0, "previousblockhash": "000000000000437482b6d47f82f374cde539440ddb108b0a76886f0d87d126b9", "nextblockhash": "00000000000108ac3e3f51a0f4424dd757a3b0485da0ec96592f637f27bd1cf5"}`| [Return to Overview](#MethodOverview)
*** @@ -319,9 +318,10 @@ the method name for further details such as parameter and return information. |Parameters|1. `block hash`: `(string, required)` the hash of the block.
2. `verbose`: `(boolean, optional, default=true)` specifies the block header is returned as a JSON object instead of a hex-encoded string.| |Description|Returns hex-encoded bytes of the serialized block header.| |Returns (verbose=false)|`"data" (string) hex-encoded bytes of the serialized block`| -|Returns (verbose=true)|`(json object)`
`hash`: `(string)` the hash of the block (same as provided).
`confirmations`: `(numeric)` the number of confirmations.
`height`: `(numeric)` the height of the block in the block chain.
`version`: `(numeric)` the block version.
`merkleroot`: `(string)` root hash of the merkle tree.
`stakeroot`: `(string)` root hash of the stake tree.
`time`: `(numeric)` the block time in seconds since 1 Jan 1970 GMT
`nonce`: (numeric) the block nonce.
`bits`: `(numeric)` the bits which represent the block difficulty.
`sbits`: `(numeric)` the bits which represent the stake difficulty.
`difficulty`: `(numeric)` the proof-of-work difficulty as a multiple of the minimum difficulty.
`previousblockhash`: `(string)` the hash of the previous block.
`nextblockhash`: `(string)` the hash of the next block (only if there is one).

`{"hash": "blockhash", "confirmations": n, "height": n, "version": n, "merkleroot": "hash", "stakeroot": "hash", "time": n, "nonce": n, "bits": n, "sbits": n, "difficulty": n.nn, "previousblockhash": "hash", "nextblockhash": "hash"}`| -|Example Return (verbose=false)|Newlines added for display purposes. The actual return does not contain newlines.
`"0200000035ab154183570282ce9afc0b494c9fc6a3cfea05aa8c1add2ecc564900000000`
`38ba3d78e4500a5a7570dbe61960398add4410d278b21cd9708e6d9743f374d544fc0552`
`27f1001c29c1ea3b"`| -|Example Return (verbose=true)|`{"hash": "00000000009e2958c15ff9290d571bf9459e93b19765c6801ddeccadbb160a1e", "confirmations": 392076, "height": 100000, "version": 2, "merkleroot": "d574f343976d8e70d91cb278d21044dd8a396019e6db70755a0a50e4783dba38", "stakeroot":"b4765ae7d5bf4768ff7c4372d55abb7894b2bd9d3f48f7437115502b0bcc47e7", "time": 1376123972, "nonce": 1005240617, "bits": "1c00f127", "sbits": 68, "difficulty": 271.75767393, "previousblockhash": "000000004956cc2edd1a8caa05eacfa3c69f4c490bfc9ace820257834115ab35", "nextblockhash": "0000000000629d100db387f37d0f37c51118f250fb0946310a8c37316cbc4028", ...}`| +|Returns (verbose=true)|`(json object)`
`hash`: `(string)` the hash of the block (same as provided).
`confirmations`: `(numeric)` the number of confirmations.
`version`: `(numeric)` the block version.
`merkleroot`: `(string)` root hash of the merkle tree.
`stakeroot`: `(string)` root hash of the stake tree.
`votebits`: `(numeric)` the block voting results.
`finalstate`: `(string)` the final lottery state.
`voters`: `(numeric)` the number of votes.
`freshstake`: `(numeric)` the number of ticket purchases.
`revocations`: `(numeric)` the number of ticket revocations.
`poolsize`: `(numeric)` the total number of valid spendble tickets as of the block.
`bits`: `(numeric)` the bits which represent the block difficulty.
`sbits`: `(numeric)` the bits which represent the stake difficulty.
`height`: `(numeric)` the height of the block in the block chain.
`size`: `(numeric)` the size of the block.
`time`: `(numeric)` the block time in seconds since 1 Jan 1970 GMT.
`nonce`: `(numeric)` the block nonce.
`extradata`: `(string)` extra data for the block including the extra nonce used by proof-of-work miners.
`stakeversion`: `(string)` block stake version.
`difficulty`: `(numeric)` the proof-of-work difficulty as a multiple of the minimum difficulty.
`previousblockhash`: `(string)` the hash of the previous block.
`nextblockhash`: `(string)` the hash of the next block (only if there is one).

`{"hash": "blockhash", "confirmations": n, "version": n, "merkleroot": "hash", "stakeroot": "hash", "votebits": n, "finalstate": "state", "voters": n, "freshstake": n, "revocations": n, "poolsize": n, "bits": n, "sbits": n.nn, "height": n, "size": n, "time": n, "nonce": n, "extradata": "data", "stakeversion": n, "difficulty": n.nn, "previousblockhash": "hash", "nextblockhash": "hash"}` +| +|Example Return (verbose=false)|Newlines added for display purposes. The actual return does not contain newlines.
`"0100000094f455952f88b4ff019c6673f3f01541b76e700e0c8a2ab9da00000000000000`
`266b9d4672f099e2b36c7adcede6564ee7326ac02b757b065e4a7c69efa44925825ccc8e`
`9602af73d03e54ea1ac717f712c869440a1762375f64b9fe3ae2409f01008b736885bab7`
`0500000047a60000b494111a6688f80402000000a0860100600c000000a081585ab58b03`
`360000000024680140d1ec18000000000000000000000000000000000000000000000000"`| +|Example Return (verbose=true)|`{"hash": "00000000000004289d9a7b0f7a332fb60a1c221faae89a107ce3ab93eead2f93", "confirmations": 183291, "version": 1, "merkleroot": "2549a4ef697c4a5e067b752bc06a32e74e56e6eddc7a6cb3e299f072469d6b26", "stakeroot":"9f40e23afeb9645f3762170a4469c812f717c71aea543ed073af02968ecc5c82", "votebits": 1, "finalstate": "8b736885bab7", "voters": 5, "freshstake": 0, "revocations": 0, "poolsize": 42567, "bits": "1a1194b4", "sbits": 86.73331302, "height": 100000, "size": 3168, "time": 1484890112, "nonce": 59487578, "stakeversion": 0, "difficulty": 954273.50809769, "previousblockhash": "00000000000000dab92a8a0c0e706eb74115f0f373669c01ffb4882f9555f494", "nextblockhash": "0000000000000578b08f22fd2bdf5f7fe5b0af1bb4928de5053a3f906b3c8f6b"}`| [Return to Overview](#MethodOverview)
*** diff --git a/rpcserver.go b/rpcserver.go index 4a4ce4f9..c760c4a2 100644 --- a/rpcserver.go +++ b/rpcserver.go @@ -2054,7 +2054,6 @@ func handleGetBlockHeader(s *rpcServer, cmd interface{}, closeChan <-chan struct Hash: c.Hash, Confirmations: confirmations, Version: blockHeader.Version, - PreviousHash: blockHeader.PrevBlock.String(), MerkleRoot: blockHeader.MerkleRoot.String(), StakeRoot: blockHeader.StakeRoot.String(), VoteBits: blockHeader.VoteBits, @@ -2069,8 +2068,10 @@ func handleGetBlockHeader(s *rpcServer, cmd interface{}, closeChan <-chan struct Size: blockHeader.Size, Time: blockHeader.Timestamp.Unix(), Nonce: blockHeader.Nonce, + ExtraData: hex.EncodeToString(blockHeader.ExtraData[:]), StakeVersion: blockHeader.StakeVersion, Difficulty: getDifficultyRatio(blockHeader.Bits), + PreviousHash: blockHeader.PrevBlock.String(), NextHash: nextHashString, } diff --git a/rpcserverhelp.go b/rpcserverhelp.go index 8d1a8958..61452d82 100644 --- a/rpcserverhelp.go +++ b/rpcserverhelp.go @@ -307,13 +307,10 @@ var helpDescsEnUS = map[string]string{ "getblockverboseresult-previousblockhash": "The hash of the previous block", "getblockverboseresult-nextblockhash": "The hash of the next block (only if there is one)", "getblockverboseresult-sbits": "The stake difficulty of theblock", - "getblockverboseresult-poolsize": "The total number of valid, spendable sstx (tickets) in the chain", - "getblockverboseresult-revocations": "The number of new ssrtx (tickets) of the given block", - "getblockverboseresult-freshstake": "The number of new sstx (tickets) of the given block", - "getblockverboseresult-voters": "The number of stake voters (ssgen) of the previous block", - "getblockverboseresult-potential": "The number of potential", - "getblockverboseresult-overflow": "The number of overflow", - "getblockverboseresult-winner": "The winning bucket to determine ssgen", + "getblockverboseresult-poolsize": "The size of the live ticket pool", + "getblockverboseresult-revocations": "The number of revocations in the block", + "getblockverboseresult-freshstake": "The number of new tickets in the block", + "getblockverboseresult-voters": "The number votes in the block", "getblockverboseresult-votebits": "The block's voting results", "getblockverboseresult-rawstx": "The block's raw sstx hashes the were included", "getblockverboseresult-stx": "The block's sstx hashes the were included", @@ -360,6 +357,7 @@ var helpDescsEnUS = map[string]string{ "getblockheaderverboseresult-finalstate": "The final state value of the ticket pool", "getblockheaderverboseresult-votebits": "The vote bits", "getblockheaderverboseresult-stakeroot": "The merkle root of the stake transaction tree", + "getblockheaderverboseresult-extradata": "Extra data field for the requested block", "getblockheaderverboseresult-stakeversion": "The stake version of the block", // GetBlockSubsidyCmd help.