document eth_feeHistory option

[sambacha]

see https://sourcegraph.com/github.com/MetaMask/core@80ff2fbb1fb38f577b4a5c7e3778550c4682202d/-/blob/packages/gas-fee-controller/src/fetchBlockFeeHistory.ts

/**

• Uses eth_feeHistory (an EIP-1559 feature) to obtain information about gas fees from a range of
• blocks that have occurred recently on a network.
• To learn more, see these resources:
• • https://infura.io/docs/ethereum#operation/eth_feeHistory
• • https://github.com/zsfelfoldi/feehistory/blob/main/docs/feeHistory.md
• • https://github.com/ethereum/go-ethereum/blob/57a3fab8a75eeb9c2f4fab770b73b51b9fe672c5/eth/gasprice/feehistory.go#L180
• • https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1559.md
• • https://gas-api.metaswap.codefi.network/testFeeHistory
• @param args - The arguments to this function.
• @param args.ethQuery - An EthQuery instance that wraps a provider for the network in question.
• @param args.endBlock - The desired end of the requested block range. Can be "latest" if you want
• to start from the latest successful block or the number of a known past block.
• @param args.numberOfBlocks - How many total blocks to fetch. Note that if this is more than 1024,
• multiple calls to eth_feeHistory will be made.
• @param args.percentiles - A set of numbers between 1 and 100 which will dictate how
• priorityFeesByPercentile in each returned block will be formed. When Ethereum runs the
• eth_feeHistory method, for each block it is considering, it will first sort all transactions by
• the priority fee. It will then go through each transaction and add the total amount of gas paid
• for that transaction to a bucket which maxes out at the total gas used for the whole block. As
• the bucket fills, it will cross percentages which correspond to the percentiles specified here,
• and the priority fees of the first transactions which cause it to reach those percentages will be
• recorded. Hence, priorityFeesByPercentile represents the priority fees of transactions at key
• gas used contribution levels, where earlier levels have smaller contributions and later levels
• have higher contributions.
• @param args.includeNextBlock - Whether to include an extra block that represents the next
• block after the latest one. Only the baseFeePerGas will be filled in for this block (which is
• estimated).
• @returns The list of blocks and their fee data, sorted from oldest to newest.
  */

[sambacha]

It fetches historical gas fee data for a range of blocks using the eth_feeHistory JSON-RPC method added in EIP-1559.

The @params documentation describes the arguments:

ethQuery - An EthQuery instance to make JSON-RPC calls
endBlock - The end block number, or 'latest' for the latest block
numberOfBlocks - The number of blocks to fetch data for
percentiles - The percentiles to calculate priority fees for
includeNextBlock - Whether to estimate data for the next block
The @returns documentation describes the return value - an array of FeeHistoryBlock objects sorted from oldest to newest.

The function is exported as the default export.

It first handles the percentiles argument - converting it to a sorted unique array.

It gets the final end block number, handling 'latest' by querying the current block number.

It calls determineRequestChunkSpecifiers to break up the block range into chunks of max 1024 blocks.

It makes a Promise.all call to fetch each chunk in parallel.

Each chunk fetches data by calling makeRequestForChunk. The last chunk sets includeNextBlock to true.

The results are concatenated together and returned.