add feeHistory spec #212

zsfelfoldi · 2021-06-13T11:27:04Z

This PR adds the feeHistory API function spec.
See also:

original proposal: https://gist.github.com/zsfelfoldi/9607ad248707a925b701f49787904fd6
implementation in Geth: eth/gasprice: implement feeHistory API go-ethereum#23033

MicahZoltu · 2021-06-13T12:00:23Z

json-rpc/spec.json

+			"params": [
+				{
+					"name": "blockCount",
+					"description": "Number of blocks in the requested range.",


Consider mentioning what a value of 0 does/means. Also, are there any constraints on this (limit to number one can request)?

MicahZoltu · 2021-06-13T12:01:22Z

json-rpc/spec.json

+					"name": "lastBlock",
+					"description": "Last block number of the requested range.",


Consider renaming this to "newest" instead of "last". Depending on your frame of reference, "last" may be closer to genesis than head, or it may be closer to head than genesis.

MicahZoltu · 2021-06-13T12:01:58Z

json-rpc/spec.json

+							{
+								"$ref": "#/components/schemas/BlockNumber"
+							},
+							{
+								"$ref": "#/components/schemas/BlockNumberTag"
+							}


We should create a new type for BlockNumberOrTag since it comes up a lot.

MicahZoltu · 2021-06-13T12:03:14Z

json-rpc/spec.json

+							"title": "firstBlock",
+							"description": "First block number of the returned range.",


Consider "newest" here if you decide to change the above to "newest" so naming is consistent.

you mean oldest I guess :)

Ah, all the more reason to change this wording! I thought by "first" you meant "latest" (most recent, first block counting down from now, etc.). 😁

MicahZoltu · 2021-06-13T12:03:56Z

json-rpc/spec.json

+						},
+						"baseFee": {
+							"title": "baseFeeArray",
+							"description": "An array of block base fees (including the next block after the returned range).",


It seems odd to me that this would return more blocks than requested. If the user wants +1, they can just ask for +1.

This info is derived from the requested blocks (the next base fee always follows from the last block). It makes sense to specify it like this because the pending base fee is basically the most important and it has nothing to do with the pending state that is not supported at all by some backends (so it either couldn't be queried or would be an ugly corner case with only the baseFee returned for the pending block). On the other hand if pending state is supported and the pending block is queried then we can even predict even the after-pending block's base fee because it follows from the pending state and it is a good indicator of congestion in the mempool. There isn't even a way to specify the after-pending block as lastBlock. So I'd strongly like to keep it this way and specify that the function returns info derivable from the requested blocks (hence the extra baseFee value).

MicahZoltu · 2021-06-13T12:04:31Z

json-rpc/spec.json

+						},
+						"gasUsedRatio": {
+							"title": "gasUsedArray",
+							"description": "An array of block gas used ratios.",


Is this a decimal number between 0 and 1? Might be good to provide a bit more description here.

timbeiko · 2021-06-14T15:07:12Z

@MicahZoltu @lightclient does this seem ready to merge to you?

RatanRSur · 2021-06-14T19:34:21Z

json-rpc/spec.json

+						},
+						"baseFee": {
+							"title": "baseFeeArray",
+							"description": "An array of block base fees (including the next block after the newest of the returned range because this value can be derived from the newest block).",


Is this null if the block has no base fee?

alcuadrado · 2021-06-15T02:21:46Z

@MicahZoltu @lightclient does this seem ready to merge to you?

I'm curious about this. What will be the criteria to accept modifications to this spec? Will accepting a new method imply that all the clients and developer networks (e.g. ganache, hardhat, remix) need to implement it?

lightclient

Thanks for making this PR! In general, it would be good to avoid discussing things in parentheses. It would be better to state things explicitly. I'd also like the actual type information to be encoded in the schema.

lightclient · 2021-06-15T02:29:21Z

json-rpc/spec.json

+		{
+			"name": "eth_feeHistory",
+			"summary": "Transaction fee history",
+			"description": "Returns transaction base fee and effective priority fee history for the requested/supported block range.",


What would the behaviour be before EIP-1559 blocks? I think it would be good to mention that upfront in the description.

Also, these should be listed "base fee per gas" and "effective priority fee per gas".

lightclient · 2021-06-15T02:31:31Z

json-rpc/spec.json

+			"params": [
+				{
+					"name": "blockCount",
+					"description": "Number of blocks in the requested range (positive integer; less may be returned if requesting the entire specified range is not supported).",


Suggested change

"description": "Number of blocks in the requested range (positive integer; less may be returned if requesting the entire specified range is not supported).",

"description": "Number of blocks in the requested range (less may be returned if requesting the entire specified range is not supported).",

The schema should denote the type.

It's also not clear to me what "not supported" means?

lightclient · 2021-06-15T02:32:41Z

json-rpc/spec.json

+				},
+				{
+					"name": "newestBlock",
+					"description": "Newest (highest number) block of the requested range (the range between headBlock-4 and headBlock are guaranteed to be supported while the pending block and older history are optional to support).",


Suggested change

"description": "Newest (highest number) block of the requested range (the range between headBlock-4 and headBlock are guaranteed to be supported while the pending block and older history are optional to support).",

"description": "Highest number block of the requested range. The range between headBlock-4 and headBlock are guaranteed to be supported while the pending block and older history are optional to support.",

lightclient · 2021-06-15T02:33:47Z

json-rpc/spec.json

+				},
+				{
+					"name": "rewardPercentiles",
+					"description": "A list of percentile values (0..100 floating point) to sample from each block's miner rewards in ascending order, weighted by gas used.",


Suggested change

"description": "A list of percentile values (0..100 floating point) to sample from each block's miner rewards in ascending order, weighted by gas used.",

"description": "A list of percentile values to sample from each block's miner rewards in ascending order, weighted by gas used.",

Please use the schema field to communicate the type information.

lightclient · 2021-06-15T02:34:20Z

json-rpc/spec.json

+					"properties": {
+						"oldestBlock": {
+							"title": "oldestBlock",
+							"description": "Oldest (lowest number) block of the returned range.",


Suggested change

"description": "Oldest (lowest number) block of the returned range.",

"description": "Lowest number block of the returned range.",

lightclient · 2021-06-15T02:37:24Z

json-rpc/spec.json

+						},
+						"baseFee": {
+							"title": "baseFeeArray",
+							"description": "An array of block base fees (including the next block after the newest of the returned range because this value can be derived from the newest block).",


Suggested change

"description": "An array of block base fees (including the next block after the newest of the returned range because this value can be derived from the newest block).",

"description": "An array of block base fees per gas. This includes the next block after the newest of the returned range, because this value can be derived from the newest block.",

lightclient · 2021-06-15T02:38:36Z

json-rpc/spec.json

+						},
+						"gasUsedRatio": {
+							"title": "gasUsedArray",
+							"description": "An array of block gas used ratios (gasUsed/gasLimit; 0..1 floating point).",


Suggested change

"description": "An array of block gas used ratios (gasUsed/gasLimit; 0..1 floating point).",

"description": "An array of block gas used ratios. This is calculated by dividing the gasUsed by the gasLimit.",

Please use the schema to denote the type.

lightclient · 2021-06-15T02:39:00Z

json-rpc/spec.json

+							"type": "array",
+							"items": {
+								"title": "gasUsedRatio",
+								"description": "The ratio of gas used and gas limit (0..1 floating point).",


Suggested change

"description": "The ratio of gas used and gas limit (0..1 floating point).",

"description": "The ratio of gas used and gas limit.",

Please use the schema to denote the type.

lightclient · 2021-06-15T02:39:53Z

json-rpc/spec.json

+						},
+						"reward": {
+							"title": "rewardArray",
+							"description": "A two-dimensional array of block miner rewards (effective priority fees) at the requested block percentiles.",


Suggested change

"description": "A two-dimensional array of block miner rewards (effective priority fees) at the requested block percentiles.",

"description": "A two-dimensional array of effective priority fees per gas at the requested block percentiles.",

lightclient · 2021-06-15T02:41:21Z

json-rpc/spec.json

@@ -1135,6 +1223,17 @@
 					"pending"
 				]
 			},
+			"BlockNumberOrTag": {


Did you just pull this out to be more explicit?

lightclient · 2021-06-15T02:49:10Z

@MicahZoltu @lightclient does this seem ready to merge to you?

I'm curious about this. What will be the criteria to accept modifications to this spec? Will accepting a new method imply that all the clients and developer networks (e.g. ganache, hardhat, remix) need to implement it?

This is a great question. I think the best way to go about it is have endpoints be discussed and proposed as PRs and then merge those changes into the spec repo as "pre-releases". Every month or so, we would need to have a synchronous call with the stakeholders (like the teams you've mentioned) and client devs to get a thumbs up on the release candidate, then we can release a new version of the spec. It may also be useful to target a date where all major tooling has adapted to support the latest json-rpc spec. If this is the desired path, I would like to see the spec broken out into its own repository. Curious to know what people think of this.

MicahZoltu · 2021-06-15T11:30:10Z

I have a mild preference for having a branch that we merge PRs like this into that is named something like spec-alpha or spec-beta. The reason for this is because in association with the call you mentioned, we can create a Pull Request of spec-alpha into spec-beta or spec-beta into main so that the changeset being discussed on that particular call is very clear and people can leave comments directly on the changeset under discussion.

We could also have a branch for release-candidate that we can merge into while we wait for client implementations, then once we are comfortable asserting "this is the spec" (and we have some implementations) we can merge release-candidate into main. This would make the workflow something like personal_fork -> alpha -> beta -> release-candidate -> main (exact names TBD).

A workflow like this makes it very easy to find out what is the current specification (broadly speaking, implemented by one or more clients) as well as making it easy to see what is currently up for "official" proposal and easy to generate a diff or a PR for discussing current proposals.

timbeiko · 2021-06-15T15:36:36Z

@alcuadrado good question! As @lightclient and @MicahZoltu have pointed out, this process is still new and we haven't figured out the kinks yet. I'm in favor of the general approach of having multiple branch and review periods. I'll try and draft up a proposal today/tomorrow.

As for this specific PR, I'm inclined to merge it for a couple reasons:

We've already merged other London/1559-related endpoints (e.g. Add effectiveGasPrice to eth_getTransactionReceipt #206, Correct baseFee to baseFeePerGas #192) and have pointed people here as the canonical place to follow these changes;
We've discussed adding this API first on the Gas API call a few weeks ago and confirmed it on AllCoreDevs last Friday (London JSON RPC Specification pm#334 (comment))
Geth and Besu already have WIP PRs to support this, see eth/gasprice: implement feeHistory API go-ethereum#23033 & eth_feeHistory hyperledger/besu#2432

Ideally, tooling/infrastructure should support this, but having full 1559 support on Day 1 of the London fork isn't a strict requirement as legacy txns will still be allowed.

lightclient

Looks good, I think just a couple missed per gases and then good to go.

lightclient · 2021-06-15T15:54:28Z

json-rpc/spec.json

+		{
+			"name": "eth_feeHistory",
+			"summary": "Transaction fee history",
+			"description": "Returns base fee and transaction effective priority fee history for the requested block range if available. The range between headBlock-4 and headBlock is guaranteed to be available while retrieving data from the pending block and older history are optional to support. For pre-EIP-1559 blocks the gas prices are returned as rewards and zeroes are returned for the base fee.",


Suggested change

"description": "Returns base fee and transaction effective priority fee history for the requested block range if available. The range between headBlock-4 and headBlock is guaranteed to be available while retrieving data from the pending block and older history are optional to support. For pre-EIP-1559 blocks the gas prices are returned as rewards and zeroes are returned for the base fee.",

"description": "Returns base fee per as and transaction effective priority fee per gas history for the requested block range if available. The range between headBlock-4 and headBlock is guaranteed to be available while retrieving data from the pending block and older history are optional to support. For pre-EIP-1559 blocks the gas prices are returned as rewards and zeroes are returned for the base fee per gas.",

lightclient · 2021-06-15T15:58:24Z

json-rpc/spec.json

+					"description": "Number of blocks in the requested range. Between 1 and 1024 blocks can be requested in a single query. Less than requested may be returned if not all blocks are available.",
+					"required": true,
+					"schema": {
+						"$ref": "#/components/schemas/Integer"


This should be an integer between 1 and 1024. IMO anything we can encode in the schema, we should.

On second thought, I suppose the description is good enough for now. Eventually we'll should encode in the schema though.

zsfelfoldi · 2021-06-15T22:54:06Z

I added the missing "per gas" where requested and squashed my commits. I think it's mergeable now unless there is a further issue :)

fvictorio · 2021-07-19T12:24:00Z

@zsfelfoldi is the gist of the original proposal correct? Shouldn't be this one instead?

timbeiko · 2021-07-19T15:47:57Z

+1. The HackMD link seems wrong.

MicahZoltu reviewed Jun 13, 2021

View reviewed changes

RatanRSur reviewed Jun 14, 2021

View reviewed changes

lightclient requested changes Jun 15, 2021

View reviewed changes

lightclient approved these changes Jun 15, 2021

View reviewed changes

timbeiko mentioned this pull request Jun 15, 2021

Proposal: New Repository and Process for JSON RPC Spec #213

Closed

add feeHistory spec

45d49bf

zsfelfoldi force-pushed the feeHistory branch from 7ae54ff to 45d49bf Compare June 15, 2021 22:49

zsfelfoldi mentioned this pull request Jun 16, 2021

eth/gasprice: implement feeHistory API ethereum/go-ethereum#23033

Merged

lightclient approved these changes Jun 16, 2021

View reviewed changes

timbeiko merged commit 4aa07bf into ethereum:master Jun 16, 2021

sunce86 mentioned this pull request Jun 25, 2021

Implement eth_feeHistory openethereum/openethereum#456

Closed

alcuadrado mentioned this pull request Jun 28, 2021

Implement eth_feeHistory NomicFoundation/hardhat#1606

Closed

aeharvlee mentioned this pull request Jan 24, 2022

Implemented FeeHistory API klaytn/klaytn#1130

Merged

9 tasks

alexdupre mentioned this pull request Mar 14, 2022

Add support for new EIP-1559 RPC methods. hyperledger-web3j/web3j#1651

Merged

lightclient mentioned this pull request Jul 29, 2022

Add fee history method ethereum/execution-apis#29

Merged

		"name": "lastBlock",
		"description": "Last block number of the requested range.",

		"title": "firstBlock",
		"description": "First block number of the returned range.",

	"description": "Number of blocks in the requested range (positive integer; less may be returned if requesting the entire specified range is not supported).",
	"description": "Number of blocks in the requested range (less may be returned if requesting the entire specified range is not supported).",

	"description": "Newest (highest number) block of the requested range (the range between headBlock-4 and headBlock are guaranteed to be supported while the pending block and older history are optional to support).",
	"description": "Highest number block of the requested range. The range between headBlock-4 and headBlock are guaranteed to be supported while the pending block and older history are optional to support.",

	"description": "A list of percentile values (0..100 floating point) to sample from each block's miner rewards in ascending order, weighted by gas used.",
	"description": "A list of percentile values to sample from each block's miner rewards in ascending order, weighted by gas used.",

	"description": "Oldest (lowest number) block of the returned range.",
	"description": "Lowest number block of the returned range.",

	"description": "An array of block base fees (including the next block after the newest of the returned range because this value can be derived from the newest block).",
	"description": "An array of block base fees per gas. This includes the next block after the newest of the returned range, because this value can be derived from the newest block.",

	"description": "An array of block gas used ratios (gasUsed/gasLimit; 0..1 floating point).",
	"description": "An array of block gas used ratios. This is calculated by dividing the gasUsed by the gasLimit.",

	"description": "The ratio of gas used and gas limit (0..1 floating point).",
	"description": "The ratio of gas used and gas limit.",

	"description": "A two-dimensional array of block miner rewards (effective priority fees) at the requested block percentiles.",
	"description": "A two-dimensional array of effective priority fees per gas at the requested block percentiles.",

add feeHistory spec #212

add feeHistory spec #212

Conversation

zsfelfoldi commented Jun 13, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zsfelfoldi Jun 13, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

timbeiko commented Jun 14, 2021

Choose a reason for hiding this comment

alcuadrado commented Jun 15, 2021

lightclient left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lightclient commented Jun 15, 2021

MicahZoltu commented Jun 15, 2021

timbeiko commented Jun 15, 2021

lightclient left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zsfelfoldi commented Jun 15, 2021

fvictorio commented Jul 19, 2021

timbeiko commented Jul 19, 2021

zsfelfoldi Jun 13, 2021 •

edited

Loading