Update block parameter pending and blockHash (#1544)

* Update block parameter `pending` and `blockHash`

Signed-off-by: Alexandra Tran <[email protected]>

* fixes and clarifications

Signed-off-by: Alexandra Tran <[email protected]>

* add pending + notes

Signed-off-by: Alexandra Tran <[email protected]>

---------

Signed-off-by: Alexandra Tran <[email protected]>

docs/private-networks/reference/api/index.md

@@ -1,5 +1,6 @@
 ---
 description: Hyperledger Besu private network JSON-RPC API methods reference
+toc_max_heading_level: 3
 tags:
   - private networks
 ---
@@ -76,7 +77,13 @@ Lists [signers for the specified block].
 
 #### Parameters
 
-`blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
+`blockNumber`: _string_ - hexadecimal or decimal integer representing a block number, or one of the
+string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in
+[block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
+
+:::note
+`pending` returns the same value as `latest`.
+:::
 
 #### Returns
 
@@ -124,9 +131,17 @@ Provides the following validator metrics for the specified range:
 
 #### Parameters
 
-- `fromBlockNumber`: _string_ - hexadecimal or decimal integer representing a block number or the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
+- `fromBlockNumber`: _string_ - hexadecimal or decimal integer representing a block number, or one
+  of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in
+  [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
 
-- `toBlockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
+- `toBlockNumber`: _string_ - hexadecimal or decimal integer representing a block number, or one of
+  the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in
+  [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
+
+:::note
+`pending` returns the same value as `latest`.
+:::
 
 If you specify:
 
@@ -518,9 +533,17 @@ Provides the following validator metrics for the specified range:
 
 #### Parameters
 
-- `fromBlockNumber`: _string_ - hexadecimal or decimal integer representing a block number or the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
+- `fromBlockNumber`: _string_ - hexadecimal or decimal integer representing a block number, or one
+  of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in
+  [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
+
+- `toBlockNumber`: _string_ - hexadecimal or decimal integer representing a block number, or one of
+  the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in
+  [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
 
-- `toBlockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
+:::note
+`pending` returns the same value as `latest`.
+:::
 
 If you specify:
 
@@ -640,7 +663,13 @@ Lists the validators defined in the specified block.
 
 #### Parameters
 
-- `blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
+`blockNumber`: _string_ - hexadecimal or decimal integer representing a block number, or one of the
+string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in
+[block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
+
+:::note
+`pending` returns the same value as `latest`.
+:::
 
 #### Returns
 
@@ -1106,7 +1135,13 @@ For private contracts, `priv_call` is the same as [`eth_call`](../../../public-n
 
 - `call`: _object_ - [transaction call object](../../../public-networks/reference/api/objects.md#transaction-call-object)
 
-- `blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
+- `blockNumber`: _string_ - hexadecimal or decimal integer representing a block number, or one of the
+  string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in
+  [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
+
+  :::note
+  `pending` returns the same value as `latest`.
+  :::
 
 #### Returns
 
@@ -1244,7 +1279,13 @@ Returns the state root of the specified privacy group at the specified block.
 
 - `privacyGroupId`: _string_ - 32-byte [privacy Group ID](../../concepts/privacy/privacy-groups.md)
 
-- `blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
+- `blockNumber`: _string_ - hexadecimal or decimal integer representing a block number, or one of the
+  string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in
+  [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
+
+  :::note
+  `pending` returns the same value as `latest`.
+  :::
 
 #### Returns
 
@@ -1445,7 +1486,13 @@ Returns the code of the private smart contract at the specified address. Compile
 
 - `address`: _string_ - 20-byte contract address
 
-- `blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
+- `blockNumber`: _string_ - hexadecimal or decimal integer representing a block number, or one of the
+  string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in
+  [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
+
+  :::note
+  `pending` returns the same value as `latest`.
+  :::
 
 #### Returns
 
@@ -2195,9 +2242,17 @@ Provides the following validator metrics for the specified range:
 
 #### Parameters
 
-- `fromBlockNumber`: _string_ - hexadecimal or decimal integer representing a block number or the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
+- `fromBlockNumber`: _string_ - hexadecimal or decimal integer representing a block number, or one
+  of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in
+  [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
+
+- `toBlockNumber`: _string_ - hexadecimal or decimal integer representing a block number, or one of
+  the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in
+  [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
 
-- `toBlockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
+:::note
+`pending` returns the same value as `latest`.
+:::
 
 If you specify:
 
@@ -2314,10 +2369,11 @@ curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_getValidatorsByBlockHash","
 ### `qbft_getValidatorsByBlockNumber`
 
 Lists the validators defined in the specified block.
+Use the `pending` tag to get a list of validators that will be used to produce the next block.
 
 #### Parameters
 
-- `blockNumber`: _string_ - hexadecimal or decimal integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
+- `blockNumber`: _string_ - hexadecimal or decimal integer representing a block number, or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in [block parameter](../../../public-networks/how-to/use-besu-api/json-rpc.md#block-parameter)
 
 #### Returns
 

docs/public-networks/how-to/use-besu-api/json-rpc.md

@@ -303,12 +303,19 @@ To enable the `ADMIN`, `CLIQUE`, `DEBUG`, `EEA`, `IBFT`, `MINER`, `PERM`, `PLUGI
 
 ## Block parameter
 
-When you make requests that might have different results depending on the block accessed, the block parameter specifies the block. Methods such as [`eth_getTransactionByBlockNumberAndIndex`](../../reference/api/index.md#eth_gettransactionbyblocknumberandindex) have a block parameter.
+When you make requests that might have different results depending on the block accessed, the block
+parameter specifies the block.
+Methods such as [`eth_getTransactionByBlockNumberAndIndex`](../../reference/api/index.md#eth_gettransactionbyblocknumberandindex)
+have a block parameter.
 
 The block parameter can have one of the following values:
 
-- `blockNumber` : _quantity_ - The block number, specified in hexadecimal or decimal. 0 represents the genesis block.
-- `blockHash` : _string_ or _object_ - 32-byte block hash or JSON object specifying the block hash. If using a JSON object, you can specify `requireCanonical` to indicate whether the block must be a canonical block. See [this example](https://github.com/hyperledger/besu/blob/a2dedb0b2c7980cdc35db8eb4c094f2eb0dc7deb/ethereum/api/src/test/resources/org/hyperledger/besu/ethereum/api/jsonrpc/eth/eth_getBalance_blockHashObjectCanonical.json).
+- `blockNumber` : _quantity_ - The block number, specified in hexadecimal or decimal.
+  `0` represents the genesis block.
+- `blockHash` : _string_ or _object_ - 32-byte block hash or JSON object specifying the block hash.
+  If using a JSON object, you can specify `requireCanonical` to indicate whether the block must be a
+  canonical block.
+  See [this example](https://github.com/hyperledger/besu/blob/a2dedb0b2c7980cdc35db8eb4c094f2eb0dc7deb/ethereum/api/src/test/resources/org/hyperledger/besu/ethereum/api/jsonrpc/eth/eth_getBalance_blockHashObjectCanonical.json).
 
   :::note
 
@@ -325,6 +332,11 @@ The block parameter can have one of the following values:
 
 - `earliest` : _tag_ - The earliest (genesis) block.
 - `latest` : _tag_ - The last block mined.
-- `pending` : _tag_ - The last block mined plus pending transactions. Use only with [`eth_getTransactionCount`](../../reference/api/index.md#eth_gettransactioncount).
-- `finalized` : _tag_ - The most recent crypto-economically secure block. It cannot be reorganized outside manual intervention driven by community coordination.
-- `safe` : _tag_ - The most recent block that is safe from reorganization under honest majority and certain synchronicity assumptions.
+- `pending` : _tag_ - When used with [`eth_getTransactionCount`](../../reference/api/index.md#eth_gettransactioncount),
+  refers to the last block mined plus pending transactions.
+  When used with [`qbft_getValidatorsByBlockNumber`](../../../private-networks/reference/api/index.md#qbft_getvalidatorsbyblocknumber),
+  returns a list of validators that will be used to produce the next block.
+- `finalized` : _tag_ - The most recent crypto-economically secure block.
+  It cannot be reorganized outside manual intervention driven by community coordination.
+- `safe` : _tag_ - The most recent block that is safe from reorganization under honest majority and
+  certain synchronicity assumptions.