EIP 1559 naming change requests

1559.md

EIP 1559 defines a few new concepts, but focuses more on how they are used in the context of the new functionality and less so on how they integrate into the existing ecosystem. I'd like to request a handful of syntactic changes that don't modify the functionality of the EIP whatsoever, but makes it significantly cleaner to integrate into clients and the Ethereum ecosystem tooling all around.

JSON RPC naming

First up, let's get the bike shed out of the way.

1559 defines two new fields for the new transaction types: maxPriorityFeePerGas and maxFeePerGas. From an implementation perspective it doesn't matter what these are called, however, these do need to bubble out into RPC APIs too.

The canonical names from the EIP are a bit unwieldy in the context of all existing names in a transaction. Implementers (at least in Geth) went with renaming them to feeCap and tip, where the intention was good, but it's dangerously ambiguous as it no longer highlights that it's per gas. A misinterpretation can have very damaging side effect (e.g. instead of 0.01 ETH max fees, you end up paying 21000*0.01=210 ETH fees). tip further lost the semantics that it's the max, not the actual tip.

The EIP also did not explicitly specify what the RPC API should surface. The original Geth PR ended up having an unmarshaller that accepted both the feeCap and maxFeePerGas (and tip and maxPriorityFeePerGas), which seems a very bad idea to have ambiguity even before the feature is released. The marshaller only did tip and feeCap, so again a clash in naming in different directions.

Our proposal here is to have an explicit section in the EIP that states how these fields are exposed over RPC naming wise, and furthermore, to go with a name that's short, but doens't lose the original author's intent. Our best suggestions are:

• maxPriorityFeePerGas -> gasTipCap
• maxFeePerGas -> gasFeeCap

The suggested RPC names also align with the usual suspects: gas, gasLimit, gasUsed, gasPrice.

Header field renaming

The EIP has a clause that renames gasLimit to gasTarget in header fields. This is a similar problem with the one above, but with more consequenses. Consensus wise, RLP drops the names, so it doesn't matter what we call the field. The EIP mostly focused on this aspect, so it didn't surface issues. Renaming this field on the RPC however has far reaching consequences.

From a client implementation perspective, parsing logic gets ambiguous. A user might give us a json blob with the possibility of 4 different combinations of gasLimit and gasTarget being or not being present. All client parsing code would need to add a lot of extra validation just to ensure that either one or the other is used and present and also in sync with the presence of baseFee. This was actually broken in the Geth PR, you could set baseFee and gasLimit (not gasTarget) and the code was happy.

Similarly from a client implementation perspective, if we were to track gasLimit and gasTarget separately, it would blow up code complexity all over the place needing to check if we want to use one or the other, things get messy with types vs. interfaces, etc. The simplest thing to do is to just marshal both these fields into the currently existing gasLimit and just handle it differently like we do with every EIP that modified the EVM.

From an ecosystem perspective, all tooling currently is built to parse gasLimit. Sure, we can require tools to start parsing gasTarget from now on, but there's no clear cut way for tools to say when to parse one and when to parse the other without knowlede about the fork block. They'd end up having to parse both and then multiplext on which is present.

All in all, by the simple renaming of gasLimit to gasTarget at a certain block number, we're introducing a significant burden on every ecosystem participant, clients, explorers and dapps alike, whilst really ganing nothing. The new gasTarget still acts as the gasLimit for the block, with the tiny semantic extension that it can be exceeded.

Our very strong proposal is to not rename existing consensus fields neither in this EIP, nor in any other feature EIP. The goal of this EIP is to extend the functionality of Ethereum, lets keep the focus on that and minimize collateral damange to the APIs that affect everyone. If renaming of a consensus field is truly needed in the future, we'd suggest a dedicated EIP that focuses just on one rename and investigates the fallout that it might cause.

I am a pretty firm believer that descriptive variable names in APIs and specifications are very important, and there is little value gained by having short names. This is especially true in the modern era of computing where auto-complete makes it so you almost never actually type out a full variable name. For that reason I would prefer maxPriorityFeePerGas and maxFeePerGas as those are the most accurate short-phrases we were able to come up with for the concepts represented by those variables.

For the same reason as above, I like the perGas suffix because it makes it very clear to the reader what the units of this number are so they don't make the mistakes you have outlined above.

I'm not a fan of tip because traditionally a tip is optional and paid after the fact, but in this case it isn't optional in reality (even though technically it is). bribe is closer, but this also isn't a bribe because bribes are (by connotation) dishonest and putting value here is very much not a dishonest act.

---

For the header field naming I'm quite conflicted. I agree with the sentiment that there is value in consistency across forks in this field name, but I worry that years from now we'll be dealing with never-ending confusion of new developers around the gasLimit field that isn't a limit at all, but a target. This is one of those situations where a change in name will cause us trouble/problems in the short term (and thus cost us), and not changing the name will cause us trouble/problems in the long term (and thus cost us).

Do we have some plan for eventually fixing the naming (like as part of some future planned work)? If so I would be much more inclined to kick this can down the road. If we have no plan for eventually fixing the naming, then I'm inclined to pay the cost of change today rather than smearing the cost out over the next n years (which I suspect will cost the ecosystem more in aggregate).

I'm in strong favor of updating EIP-1559 to have gasLimit be the the gasTarget * elasticityMultiplier. I think this will make downstream effects much more minimal.

I worry that years from now we'll be dealing with never-ending confusion of new developers around the gasLimit field that isn't a limit at all, but a target.

@holiman made a good proposal on discord to simply remove the notion of gasTarget (I refer to it above), so I think with that change you have no objection @MicahZoltu?

I also prefer the gas prefix to the PerGas suffix on the RPC names. I think it is an important balance of being specific without being overbearing. gasFeeCap seems good to me, it encapsulates what it's doing. I don't have an issue with gasTipCap, but I understand your argument @MicahZoltu that "tip" isn't exactly the best terminology for the transaction. I slightly prefer gasTipCap over other, but mainly just want to not see PerGas as a suffix.

Sharing the latest status on this as per the Eth R&D discord:

1. There seemed to be a rough consensus forming around baseFeePerGas, priorityFeePerGas and feeCapPerGas.
2. A concern was raised that priorityFeePerGas doesn't make it clear it is a maximum fee. We could then switch to maxPriorityFeePerGas. If we do that, we have 2/3rd of terms that match the EIP, so it probably makes sense to also match the third and use maxFeePerGas instead of feeCapPerGas.
3. This brings us back to @karalabe's original suggestion of instead using the shorter names gasFeeCap and gasTipCap.
4. Both Fee and Tip seem to be contested. An alternate suggestion could be gasPriceCap (but this is very close to gasPrice) and gasPriorityCap.