fix(rpc): align jsonrpc apis with geth v1.16.3 #599

cloudgray · 2025-09-15T12:25:21Z

Description

Overview

The primary purpose of this PR was to make the return values of the Ethereum APIs compatible with go-ethereum v1.16.3.

However, as I progressed with the work, I found that methods for obtaining the same values had been developed in a disorganized way without clear separation of layers. It was obvious that leaving them as-is would make it very difficult to maintain compatibility with go-ethereum.

Therefore, I refactored the backend methods to be properly separated by layer comet block query → comet-to-eth conversion → eth-to-rpc conversion, making it easier to later migrate the comet block subscription → comet-to-eth conversion & indexing process to the indexer.

Please take this into consideration during the code review.

What is fixed?

1. Add missing apis

eth_getHeaderByNumber
eth_getHeaderByHash

2. Fix return values of `eth` namespace apis

Block Header

Type	Field(s)	Note
Missing field	`withdrawals ([]Withdrawal)`, `header.excessBlobGas (uint64)`, `header.blobGasUsed (common.Hash)`, `header.parentBeaconBlockRoot (common.Hash)`, `requestsHash (common.Hash)`, `header.withdrawalsRoot (common.Hash)`	Add missing fields
Always empty value	`receiptsRoot (*common.Hash)`	Fill with valid value
Invalid field	`transactionsRoot (common.Hash)`, `Time`	`transactionRoot`: Remove cosmos tx from root hash calculation, `Time`: change from local timestamp to UTC timestamp
Extra (not in Geth)	`totalDifficulty (*hexutil.Big)`	Remove

Related APIs

eth_getHeaderByNumber
eth_getHeaderByHash
eth_getBlockByNumber
eth_getBlockByHash

Block Body

Type	Field(s)	Note
Invalid field	`size`	change from comet block size to eth block size

Related APIs

eth_getBlockByNumber
eth_getBlockByHash

Transaction

Type	Field(s)	Note
Missing field	`yParity`	fill with valid value

Related APIs

eth_getBlockByNumber
eth_getBlockByHash
eth_getTransactionByHash
eth_getTransactionByBlockHashAndIndex
eth_getTransactionByBlockNumberAndIndex

3. Fix internal header queries

Before

Internal header queries only used for apis other than eth_getHeaderByNumber & eth_getHeaderByHash returns invalid headers.
It is because this method gets data used for making header only from comet header, it cannot get many fields (transactionRoot, receiptsRoot, bloom, gasUsed, ...) that needs block body.

After

Use common block query method to get all data to make valid header

Limitation

Websocket api still use invalid block headers.
It is because, to get block results and tx data in stream package, additional moification is needed.
This work could be meaningless if indexer were improved and RPCStream does not subscribe cometBlockHeader but ethBlockHeader.
So currently, websocket api will still publish block header that is missing many fields like receiptsRoot.

4. Fix `txpool` apis

Handle EIP-7702 SetCode TxCase using common NewRPCTransaction
Before, the tx converting method existed separately and it does not support EIP-7702 SetCodeType tx case.

5. Fix outdated blockNumber aliases to be aligned with go-ethereum v1.16.3

Before

EthPendingBlockNumber  = BlockNumber(-2)
EthLatestBlockNumber   = BlockNumber(-1)
EthEarliestBlockNumber = BlockNumber(0)

After

EthEarliestBlockNumber  = BlockNumber(-5)
EthSafeBlockNumber      = BlockNumber(-4)
EthFinalizedBlockNumber = BlockNumber(-3)
EthLatestBlockNumber    = BlockNumber(-2)
EthPendingBlockNumber   = BlockNumber(-1)

Author Checklist

All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.

I have...

tackled an existing issue or discussed with a team member
left instructions on how to review the changes
targeted the main branch

- TestGetBlockTransactionCountByHash - TestGetBlockTransactionCountByNumber - TestGetEthBlockFromComet

aljo242 · 2025-09-25T17:31:02Z

rpc/namespaces/ethereum/eth/filters/api.go

 	GetLogs(blockHash common.Hash) ([][]*ethtypes.Log, error)
 	GetLogsByHeight(*int64) ([][]*ethtypes.Log, error)
-	BlockBloom(blockRes *coretypes.ResultBlockResults) (ethtypes.Bloom, error)
+	BlockBloomFromCometBlock(blockRes *coretypes.ResultBlockResults) (ethtypes.Bloom, error)


why did we need to change this name?

I wanted to separate data conversion functions and real rpc backend query functions.

In case of BlockBloom, there is no api like eth_getBlockBloom and it is just util function that converse cometbft block result to ethereum block bloom.

It should be removed from Backend interface. But now, to avoid confusion, I just rename function.

I think we need to discuss how we can store ethereum backend data like block header, transactionRoots, receiptsRoot, blockBlooms, ... at indexer level after v0.5.0. Then I think this conversion function can be located in indexer/utils.

aljo242 · 2025-09-25T17:31:58Z

rpc/namespaces/ethereum/eth/api.go

+// GetHeaderByNumber returns the requested canonical block header.
+//   - When blockNr is -1 the chain pending header is returned.
+//   - When blockNr is -2 the chain latest header is returned.
+//   - When blockNr is -3 the chain finalized header is returned.
+//   - When blockNr is -4 the chain safe header is returned.
+func (e *PublicAPI) GetHeaderByNumber(ethBlockNum rpctypes.BlockNumber) (map[string]interface{}, error) {
+	e.logger.Debug("eth_getHeaderByNumber", "number", ethBlockNum)
+	return e.backend.GetHeaderByNumber(ethBlockNum)
+}
+
+// GetHeaderByHash returns the requested header by hash.
+func (e *PublicAPI) GetHeaderByHash(hash common.Hash) (map[string]interface{}, error) {
+	e.logger.Debug("eth_getHeaderByHash", "hash", hash.Hex())
+	return e.backend.GetHeaderByHash(hash)
+}


should we define type Header = map[string]any to be used here?

I don't think so.

I think the effect of defining a type is that it forces other packages or clients to import and use that type, while also allowing the use of interfaces like Validate, Marshal/Unmarshal, and Encode/Decode.

However, headers, blocks, and other data returned by the Ethereum RPC server can vary in their fields depending on the ChainConfig (hardfork config), and even when the fields are the same, as with transactions, the representation may differ (e.g., common.Hash or a full Tx struct) depending on the query parameters (e.g. fullTx). Because of this, I don’t think we can enforce a type here, nor would it provide much benefit.

This design is consistent with the current go-ethereum implementation, and I don’t see a reason to implement it differently.

aljo242 · 2025-09-25T17:34:27Z

tests/jsonrpc/README.md

+- **WebSocket**: <LOCAL_HOST>:8546  
+- **Cosmos REST**: <LOCAL_HOST>:1317
+- **Tendermint RPC**:<LOCAL_HOST>:26657
 - **gRPC**: localhost:9090


why not update this too?

It is because ci (markdown link check) fails (ref)

It says this link is not available in github-ci instance.

I don't know the reason why it did not fail in past but fail currently...

aljo242 · 2025-09-25T17:34:31Z

tests/jsonrpc/README.md


- **JSON-RPC**: http://localhost:8547
+- **JSON-RPC**: <LOCAL_HOST>:8547
 - **WebSocket**: ws://localhost:8548


same (#599 (comment))

cloudgray added 5 commits September 11, 2025 15:44

deps(tests/jsonrpc): bump geth client version to v1.16.3

8384038

WIP: enhance(rpc): eth apis

e20265f

fix(rpc): fix handling PendingBlockNumber

b0d6538

fix(rpc):fix NewRPCTransaction method

28904fe

refactor(rpc): refactor eth apis

dc14555

cloudgray changed the title ~~enhance(rpc): align jsonrpc with geth v1.16.3~~ fix(rpc): align jsonrpc with geth v1.16.3 Sep 15, 2025

vladjdk mentioned this pull request Sep 16, 2025

Investigate enabling indexer by default #621

Open

cloudgray added 23 commits September 19, 2025 19:44

WIP: fix(rpc): test code

a178104

WIP: record working history

c300582

Merge branch 'main' into enhance/jsonrpc-compat-eth

a851b46

WIP: test(rpc) fix test code

c806a76

WIP: test(rpc) fix test code

4f7f7e6

WIP: test(rpc) fix test code

3eea8d9

WIP: test(rpc) fix test code: TestGetBlockByHash

027efe7

WIP: test(rpc) fix test code

e9fca06

- TestGetBlockTransactionCountByHash - TestGetBlockTransactionCountByNumber - TestGetEthBlockFromComet

WIP: test(rpc) fix test code - TestHeaderByNumber

78624dd

WIP: test(rpc) fix test code - TestHeaderByHash

ad35886

WIP: test(rpc) fix test code - TestEthBlockByNumber

0542bdd

WIP: test(rpc) fix test code - TestGetTransactionReceipt

989643f

WIP: test(rpc) fix test code - GetPrice

cb9dc46

test(rpc): fix tx_pool apis

cb2ab01

chore: remove LLM helper files

8a92c03

chore: remove LLM helper files

056a612

chore: add defense code to util function

7d3e4d7

chore(rpc): refine code

41e733e

chore(systemtests): modify error msg

31d2a5f

chore(rpc): add comment

d285427

Merge branch 'main' into enhance/jsonrpc-compat-eth

c56778c

chore: fix lint

f70f717

chore(rpc): refine code

8ae7518

cloudgray mentioned this pull request Sep 24, 2025

Align JSON-RPC API responses/arguments with Geth #446

Open

cloudgray added 2 commits September 24, 2025 14:52

chore(rpc): modify comment

8315985

chore(rpc): modify comment

b9033be

cloudgray marked this pull request as ready for review September 24, 2025 07:04

cloudgray requested a review from vladjdk September 24, 2025 07:04

cloudgray changed the title ~~fix(rpc): align jsonrpc with geth v1.16.3~~ fix(rpc): align jsonrpc apis with geth v1.16.3 Sep 24, 2025

chore: update CHANGELOG.md

e0c3570

cloudgray requested a review from aljo242 September 24, 2025 07:08

cloudgray self-assigned this Sep 24, 2025

cloudgray and others added 3 commits September 24, 2025 16:33

chore: fix lint

0c3f0de

Merge branch 'main' into enhance/jsonrpc-compat-eth

f1d1ab2

Merge branch 'main' into enhance/jsonrpc-compat-eth

c78cbdb

aljo242 reviewed Sep 25, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(rpc): align jsonrpc apis with geth v1.16.3 #599

fix(rpc): align jsonrpc apis with geth v1.16.3 #599

Uh oh!

cloudgray commented Sep 15, 2025 •

edited

Loading

Uh oh!

aljo242 Sep 25, 2025

Uh oh!

cloudgray Sep 29, 2025

Uh oh!

aljo242 Sep 25, 2025

Uh oh!

cloudgray Sep 29, 2025

Uh oh!

aljo242 Sep 25, 2025

Uh oh!

cloudgray Sep 29, 2025

Uh oh!

aljo242 Sep 25, 2025

Uh oh!

cloudgray Sep 29, 2025

Uh oh!

Uh oh!

fix(rpc): align jsonrpc apis with geth v1.16.3 #599

Are you sure you want to change the base?

fix(rpc): align jsonrpc apis with geth v1.16.3 #599

Uh oh!

Conversation

cloudgray commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Overview

What is fixed?

1. Add missing apis

2. Fix return values of eth namespace apis

Block Header

Block Body

Transaction

3. Fix internal header queries

Before

After

4. Fix txpool apis

5. Fix outdated blockNumber aliases to be aligned with go-ethereum v1.16.3

Before

After

Author Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cloudgray commented Sep 15, 2025 •

edited

Loading

2. Fix return values of `eth` namespace apis

4. Fix `txpool` apis