# 1559 Cheatsheet for Implementers

- This document is an introduction to some of the concepts that may be important to you when adding support for EIP-1559. Assumes familiarity with the EIP and its mechanisms.
- If you are completely new to EIP-1559, you can find a curated link-list in this [1559 Resources](https://hackmd.io/@timbeiko/1559-resources) guide.
- [Join the ETHR&D Discord](https://discord.gg/bZrptf6Est) for discussion on everything related to this change.

## Reference Implementations
- [MyCrypto's 1559 Strategy](https://github.com/MyCryptoHQ/MyCrypto/blob/master/src/services/ApiService/Gas/eip1559.ts) - See [Discussion here](https://github.com/MyCryptoHQ/MyCrypto/issues/4067)
- [feeHistory API](https://github.com/zsfelfoldi/feehistory)
- [Brave browser's fee oracle](https://github.com/brave/brave-core/blob/master/components/brave_wallet/browser/eth_gas_utils.cc)

## Additional resources

- [How far and fast does the base fee move? A family of curves for the first few days of London.](https://gist.github.com/perama-v/4c6b5088b18dfb928e9675f8aca869a5)
- [Etherscan API Updates](https://twitter.com/etherscan/status/1423089947054002178)
- [Summary: EIP-1559 JSON RPC Changes](https://hackmd.io/@timbeiko/1559-json-rpc)
- [Geth tx replacement logic](https://github.com/ethereum/go-ethereum/blob/master/core/tx_list.go#L279)
- [How quickly BaseFeePerGas Adjusts: gsheet and charts](https://twitter.com/trent_vanepps/status/1416039650393788416?s=20)
- Tx Pool Sorting approaches: [Geth](https://gist.github.com/zsfelfoldi/9607ad248707a925b701f49787904fd6) and [Erigon (fka TurboGeth)](https://github.com/ledgerwatch/erigon/wiki/Transaction-Pool-Design#design-proposal)
- Transaction type 2 examples on [Goerli](https://goerli.etherscan.io/address/0x24ffb8c97ce443f8d3265ba3316defcfc07c659c) and [Ropsten](https://ropsten.etherscan.io/address/0x6177843db3138ae69679A54b95cf345ED759450d)
- [JSON RPC Spec](https://github.com/ethereum/eth1.0-specs/blob/master/json-rpc/spec.json)
- [Ecosystem Tracker](https://github.com/ethereum/execution-specs/blob/master/network-upgrades/london-ecosystem-readiness.md): track where tooling projects in the ecosystem are in their London Readiness

## Previous Coordination Calls
- Aug 13th Breakout #12: Post London 1559 Assessment
- [Agenda](https://github.com/ethereum/pm/issues/369)
- July 30th Breakout #11: General 1559 Coordination
- [Recording](https://youtu.be/r37ShBRdVDg)
- Notes to be added
- Friday, June 4 14:00 UTC : Breakout #10: 1559 Gas APIs
- [Recording](https://youtu.be/SpU6WACP2cM)
- [Agenda](https://github.com/ethereum/pm/issues/328)
- [Notes](https://github.com/ethereum/pm/blob/master/Fee-Market/Meeting%2010.md)
- [Gas API Wishlist](https://hackmd.io/@timbeiko/1559-api-wishlist)
- May 26: Breakout #9: 1559 Wallets
- [Recording](https://www.youtube.com/watch?v=FEgFd7un9q4)
- [Agenda](https://github.com/ethereum/pm/issues/323)
- May 7: Breakout #8: JSON RPC and other topics
- [Recording](https://www.youtube.com/watch?v=qce2M4ot8ls)
- [Agenda](https://github.com/ethereum/pm/issues/308)

## BaseFee burn interfaces

- [Watchtheburn.com](https://watchtheburn.com/): standalone website from Mohamed Mansour
- [Otterscan](https://twitter.com/wmitsuda/status/1421245599500931074): local explorer from Willian Mitsuda
- [fee-feed](https://twitter.com/eth_worm/status/1421761074467000327): visualizer for your terminal from perama
- [Custom graph node and subgraph](https://twitter.com/dmihal/status/1422208176762630146?s=20): from David Mihal

## Implementation Info

Note: transactions seed a `maxPriorityFee` & `maxFee` > 0. Miners may not sort the txn pool directly by `maxPriorityFee` because in cases when `maxFee` - `maxPriorityFee` < `baseFee`, the `maxPriorityFee` will be reduced for the transaction to remain valid. If `maxFee` < `baseFee`, the transaction is invalid.

## 1559 Variables and their functions

| Variable | Definition |
| -------- | -------- |
| `baseFeePerGas` | Generated by the protocol, recorded in each block header. Represents the minimum `gasUsed` multiplier required for a tx to be included in a block. This is the part of the tx fee that is burnt: `baseFeePerGas * gasUsed`. |
|`maxPriorityFeePerGas`| Users set this. Added to transactions, represent the part of the tx fee that goes to the miner. see ⭐ below |
|`maxFeePerGas` | Users set this. Represents the maximum amount that a user is willing to pay for their tx (inclusive of `baseFeePerGas` and `maxPriorityFeePerGas`). The difference between `maxFeePerGas` and `baseFeePerGas + maxPriorityFeePerGas` is "refunded" to the user. |

### Variable Mechanics
- Each block's `baseFeePerGas` can increase/decrease by up to 12.5% depending on how full the block is relative to the previous one: e.g. 100% full -> +12.5%, 50% full -> same, 0% full -> -12.5%.
- When 1559 is activated, the `gasLimit` of blocks will double (e.g. 15m to 30m), so "50% full" blocks post-1559 are equivalent to 100% full blocks pre-1559.
- Note: on the 1559 fork block, the `baseFeePerGas` will be set to 1 gwei. Due to integer math, it cannot go below **7 wei** (0.000000007 gwei).

### ⭐ `maxPriorityFeePerGas` in-depth

`maxPriorityFeePerGas` serves three purposes:

1. 🔀 Compensates miners for the uncle/ommer risk + fixed costs of including transaction in a block;
2. 💰 Allows users with high opportunity costs to pay a premium to miners;
3. 📈 In times where demand exceeds the available block space (i.e. 100% full, 30mm gas), this component allows first price auctions (i.e. the pre-1559 fee model) to happen on the priority fee.

Here's how to think about suggesting user defaults for `maxPriorityFeePerGas`.

> 1. 🔀 Compensates miners for the uncle/ommer risk + fixed costs of including transaction in a block;

The rationale behind this is that if the priority fee was 0, miners would simply mine empty blocks. Therefore, in order for it to be in their economic interest to add transactions to blocks, they must be compensated beyond the marginal uncling risk that adding transactions to their block creates (and for the fixed costs of actually running the transactions, but those are negligible compared to uncle risk).

Uncle risk has two main components: the difference in block reward between being a canonical vs. uncle block and the lost MEV in the block.

[This analysis](https://notes.ethereum.org/@barnabe/rk5ue1WF_) calculates the right `maxPriorityFeePerGas` to set (assuming 15m gas) based on how much MEV there is on average in a block (note: `p=0`, the last graph, uses the most accurate numbers). Flashbots has [a dashboard](https://dashboard.flashbots.net/miners) showing the average MEV per block.

#### Example Values for 20-05-21

Looking at the dashboard today, we see this:

This implies a ballpark 0.2ETH/block in MEV over the last few days.

Looking at Barnabé's diagram we see:


At 0.2ETH/block, the right `maxPriorityFee` to compensate for the uncle risk is 1 gwei. Given this will compensate the _median_ MEV block, we should probably raise it slightly so that it is profitable to include transactions even when MEV is higher than average.

Looking at the MEV distribution on Flashbots, the vast majority of blocks have <1 ETH in MEV, which would represent a 2.5 gwei fee. 2 gwei is probably a very good default "you will get in the next handful of blocks" value. 1 gwei is likely a good "slow" value.

> 2. 💰 Allows users with high opportunity costs to pay a premium to miners;

For this, it should suffice to have an "Advanced" option where users can manually set their `maxPriorityFee` to whatever they want.

> 3. 📈 In times where demand exceeds the available block space, allows first price auctions (i.e. the pre-1559 fee model) to happen on the tip.

In this case, estimating the `maxPriorityFee` becomes the same as estimating the current `gasPrice`. A "smart" implementation could look at how full the last N blocks are to determine whether we are in a high congestion regime.

## Legacy Transaction Support

- Legacy pre-London transactions will still work under 1559: the `gas price` will be interpreted as both the `maxFeePerGas` and `maxPriorityFeePerGas`, meaning that the `baseFeePerGas` is burnt, and any extra goes to the miner. Here are some examples, assuming `baseFeePerGas` is 100 gwei:
> **1559-style tx**: User sends a tx with a `maxFeePerGas` of 250 gwei and `maxPriorityFeePerGas` of 5 gwei. The user will pay 100+5=105 gwei, 100 of which will be burnt and 5 going to the miner.

> **Legacy (Pre-1559) tx**: If the user had a legacy tx with `gasPrice` of 250 gwei, then `maxPriorityFeePerGas` would also have been set to 250 gwei and the user would have paid 250 gwei/gas for their transaction, 100 of which would have been burnt and 250-100=150 going to the miner.
- However, supporting EIP-1559-style txns will be more gas-efficient for users. With 1559 txns, only your `priority fee` goes to the miner, and the difference between the `maxFeePerGas` and `baseFeePerGas + maxPriorityFeePerGas` is refunded to the user.
- 1559-style transactions have `Transaction Type` set to `0x2`

## London Activation Process

When EIP-1559 goes live in the London upgrade (scheduled for August 4), the `baseFeePerGas` will be set to **1 gwei**. This means that, at first, transactions will be competing via a first-price auction on the tip, as the `baseFeePerGas` reaches the rate where there is ~15m gas /100% demand at that price.

If you assume the market price is **250 gwei** on the fork date, this means that `baseFeePerGas` needs to go through ~50 blocks to get there, or slightly less than 15 minutes.

Because of this, it is probably simplest to _not_ make 1559-style transactions the default for at least 15-30 minutes post fork, in order for the `baseFeePerGas` to stabilize.

#### When to default to 1559 txns in a UI

1. `gasUsed` is closer to `gasTarget` (currently 15m) than `gasLimit` (30m post fork): this means that we've found a price for the `baseFeePerGas` that's close to the market price;
2. `baseFeePerGas` of parent +/- 5% from last block's `baseFeePerGas`: this means the `baseFeePerGas` has stopped increasing and is somewhat stable;
3. Ballpark: look at average `gasPrice` right before fork, calculate how many blocks need to be full for the `baseFeePerGas` to reach that amount (+12.5% each full block), add a little buffer

Can perhaps use a combination of the 3, i.e.: 12.5m <`gasUsed` < 17.5m AND `parentBaseFee` +/- 5% from `baseFeePerGas` AND `blocksSinceFork` > 100

## Mockup Resources

We will be adding UI resources as they are worked on by wallet teams:
- [Wallet Interface Brainstorm Thread](https://twitter.com/JHancock/status/1408282853222146049) - James Hancock
- [Wallet Interface Exploration](https://perama-v.github.io/cairo/ethereum/wallet-design) - Perama
- [Status Mockups](https://www.figma.com/file/XK7vrp3pZdQ5gqQVJ7Pqgz/EIP-1559-Presentation?node-id=0%3A1&fuid=684124080871667032)
- [Metamask Mockups](https://www.figma.com/file/2iLPcKhspzstenet56RBL5/1559---Rough-Draft?node-id=1%3A485)
- [UI Thread](https://twitter.com/carlfairclough/status/1392070300313980929) - Carl Fairclough

## Supporting Imagery