rpc api: eth_getBlockByNumber "pending" block handling of nullable fields

[meowsbits]

System information

OS & Version: Linux
Commit hash : a7e6418

Expected behaviour

I expect the documentation, go-ethereum, and core-geth to align in their
description and implementation of eth_getBlockByNumber("pending", [true|false]).

The ETH docs I'm looking at (and citing) are here: https://eth.wiki/json-rpc/API.
CoreGeth docs are here: https://etclabscore.github.io/core-geth/JSON-RPC-API/modules/eth/#eth_getblockbynumber.

Rel #332

Actual behaviour

Currently I believe there is no complete agreement (neither between docs nor clients).
I will attempt to describe the divergences.

• nonce

  • Should be null. This value depends on the PoW solution, which is obviously not yet available.
  • Docs: Should be NULL.
  • core-geth: Is omitted. Incorrect.
  • go-ethereum: Is null. OK.

• mixHash

  • Should be null or zero-value. This value depends on the PoW solution, which is obviously not yet available.
  • Docs: Missing entirely.
  • core-geth: Zero-value. OK.
  • go-ethereum: Filled. Incorrect.

• number

  • Should not be null. Should be "latest" + 1.
  • Docs: Should be NULL. Incorrect.
  • core-geth: Is filled. OK.
  • go-ethereum: Is filled. OK.

• hash

  • Should be null. Block cannot be hashed until all other fields are finalized.
  • Docs: Should be NULL. OK.
  • core-geth: Is omitted. Incorrect.
  • go-ethereum: Is null. OK.

• miner

  • Should be null. Miner is not yet known.
  • Docs: Should be filled. Incorrect.
  • core-geth: Is omitted. Incorrect.
  • go-ethereum: Is null. OK.

• totalDifficulty

  • Should not be null. Total difficulty is the inclusive cumulative sum of difficulty values where the difficulty for block n+1 is defined by block n. EDIT: Although the value can always be calculated for all RPC-possible blocks, at ethereum/go-ethereum it is filled when returning Header methods and non-Uncle methods (that is, blocks with transactions).

  The API logic here fills this value only when inclTxs=true, which is false for Uncle methods.

  • Docs: Should be filled. OK, but inaccurate (does not describe pending case).
  • core-geth: Is null.
  • go-ethereum: Is null.

• logsBloom

  • Should not be null. If the receiptsRoot is available, then logsBloom should be provided by the same assumptions.
  • Docs: Should be null. Incorrect.
  • core-geth: Is 0x0000.... OK.
  • go-ethereum: Is 0xd8a54.... OK.

Backtrace

core-geth example response.

http POST :8061 id:=42 json-rpc=2.0 method=web3_clientVersion params:='[]'
HTTP/1.1 200 OK
Content-Encoding: gzip
Content-Length: 105
Content-Type: application/json
Date: Fri, 12 Mar 2021 15:54:33 GMT
Vary: Origin

{
    "id": 42,
    "jsonrpc": "2.0",
    "result": "CoreGeth/v1.11.22-stable/linux-amd64/go1.16"
}

http POST :8061 id:=42 json-rpc=2.0 method=eth_getBlockByNumber params:='["pending", false]'                                                                                                                                                                                       
HTTP/1.1 200 OK                                                                                                                                                                                                                                                                    
Content-Encoding: gzip                                                                                                                                                                                                                                                             
Content-Length: 1824                                                                                                                                                                                                                                                               
Content-Type: application/json                                                                                                                                                                                                                                                     
Date: Fri, 12 Mar 2021 15:59:49 GMT                                                                                                                                                                                                                                                
Vary: Origin                                                                                                                                                                                                                                                                       
                                                                                                                                                                                                                                                                                   
{                                                                                                                                                                                                                                                                                  
    "id": 42,                                                                    
    "jsonrpc": "2.0",                                                            
    "result": {                                                                  
        "difficulty": "0x6cb74ed843b3",                                          
        "extraData": "0xda83010b1688436f72654765746886676f312e3136856c696e7578", 
        "gasLimit": "0x7a1200",                                                  
        "gasUsed": "0xbdb28",                                                    
        "logsBloom": "0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000$
000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
        "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "number": "0xbc5f94",                                                    
        "parentHash": "0x30c6e40c4096b8dceaeebf9cb28fe4c307d3c4aa5e3dd24492b978591bec408c",
        "receiptsRoot": "0xf6aebee7264d3a8a5ffc7f6293f228fa3ec3bcde056bf44a19a9e1cf9fa3725f",
        "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
        "size": "0x127c",                                                        
        "stateRoot": "0x36f88270229ef3a0b6f5eae03bd701ef17d7c876d16d4266ee2d06002b1cd6ec",
        "timestamp": "0x604b8fab",                                               
        "totalDifficulty": null,                                                 
        "transactions": [                                                        
            "0xaa01d04fae21b08387f0ab1b9d807d140f559a453f15e8ba32595d6ab60cdc0f",
            "0x4264c1868c3c357e6e04086e55886b844e91c87ffb5a65191b6a560aa8c4c703",
            "0xc10f57ffc210b31de9c520c1ebab4184e044e9ca8a529d3ef0c08f629dcac2eb",
             ...
            "0xf77a2bf55674bdb6b26cc5e2a8917348fcee94b4a143fc56165f0c86e1382cf0"
        ],
        "transactionsRoot": "0x746191a34af2d31eef6258db5bdef4727c6523092f9a9113abf3e4d7c7a68729"
    }
}

go-ethereum example response.

ethrpc eth_getBlockByNumber "pending" false | jq
{
  "jsonrpc": "2.0",
  "id": 6023,
  "result": {
    "difficulty": "0x38a72",
    "extraData": "0xd883010a02846765746888676f312e31362e32856c696e7578",
    "gasLimit": "0x7a1200",
    "gasUsed": "0x0",
    "hash": null,
    "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "miner": null,
    "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "nonce": null,
    "number": "0x51f",
    "parentHash": "0x8e8dfbabab379f2459d97ac3ec2c0ccfbbe920edc5c19043b89dc94f9ec2f707",
    "receiptsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
    "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
    "size": "0x21a",
    "stateRoot": "0x88c6403969da94bbf52a0c78b6207ee5d8308a4699ff6464819cfe7a0f458dad",
    "timestamp": "0x605b16d1",
    "totalDifficulty": null,
    "transactions": [
      "0x46e8ce64901f889b6f158d28d0b8c6c958ea57643c4ffd3a1b6604fbd30eb4e1"
    ],
    "transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
    "uncles": []
  }
}
etx 03-24 05:39:47 ~/go/src/github.com/ethereum/go-ethereum foundation-master %=
ethrpc web3_
web3_clientVersion  web3_sha3
etx 03-24 05:39:47 ~/go/src/github.com/ethereum/go-ethereum foundation-master %=
ethrpc web3_clientVersion
{"jsonrpc":"2.0","id":6485,"result":"Geth/v1.10.2-unstable-e862cbff-20210323/linux-amd64/go1.16.2"}
...

[meowsbits]

Related issues/comments.

• eth_getblockbynumber should return null for pending blocks ethereum/go-ethereum#19332 (comment)
• eth.getUncle returns 0 for totalDifficulty ethereum/go-ethereum#19024 (comment)
• internal/ethapi: return non-null "number" for pending block ethereum/go-ethereum#20616
• internal/ethapi: fix encoding of uncle headers and pending blocks ethereum/go-ethereum#20460