Overhaul

docs/developers/guides/gas/gas-fees.mdx

@@ -10,46 +10,35 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
 
 ## How gas works on Linea
 
-Linea supports the [Ethereum EIP-1559 gas price model](https://ethereum.org/developers/docs/gas). 
-However, as a layer 2 blockchain, Linea provides a more stable and cost-effective solution 
-for transaction fees. The EIP-1559 model formula is:
+Linea supports the [Ethereum EIP-1559 gas price model](https://ethereum.org/developers/docs/gas):
 ```
-units of gas used * (base fee + priority fee)
+total fee = units of gas used * (base fee + priority fee)
 ```
 
 Using parameters in the [Linea source code](https://github.com/Consensys/linea-monorepo/blob/a001342170768a22988a29b2dca8601199c6e205/sdk/src/clients/blockchain/gas/LineaGasProvider.ts), 
 the formula can be rendered as:
 ```
-gasLimit * (maxBaseFeePerGas + maxPriorityFeePerGas)
+total fee = gasLimit * (maxBaseFeePerGas + maxPriorityFeePerGas)
 ```
 
-However, there are minor differences in the way Linea handles gas calculations when compared with 
-Ethereum:
-
-- **The base fee uses a set price of 7 wei.** Blocks created by Linea use up to 24 million gas
-    (less than 50% of the maximum Linea block size of 61 million gas), and the fee decreases by 
-    12.5% per block, effectively keeping it at a stable 7 wei.
-- **Transactions won't be sequenced if the `gasPrice` or `maxPriorityFeePerGas` falls below a 
-    certain threshold.** This threshold is not static; it adjusts over time and varies depending 
-    on the specifics of each transaction. Instead, transactions are added to the pending queue 
-    until the gas price on the network drops sufficiently for the transactions to be included.
+Linea fundamentally works exactly the same as Ethereum. The one difference is that **the base fee 
+is constant at 7 wei.** Blocks created by Linea use up to 24 million gas (less than 50% of the 
+maximum Linea block size of 61 million gas), and the fee decreases by 12.5% per block, effectively 
+keeping it at a stable 7 wei.
 
 The gas cost to submit your transaction and include it on Ethereum involves the following fee 
 components:
 
-- **Layer 2 fee** - The L2 fee (execution fee) is the cost to include your transaction on the Linea
-    sequencer and is calculated using a similar formula to Ethereum. 
-- **Layer 1 fee** - The L1 fee is the cost to publish your L2 transaction onto Ethereum and can 
-    vary based on the blob fee market.
-
-To read more about how gas works on Linea, see [_Gas on Linea_](./gas-on-linea.mdx).
+- **Layer 2 cost**: The execution fee; the cost of including your transaction on the Linea 
+  sequencer, and calculated using a similar formula to Ethereum (as described above). 
+- **Layer 1 cost**: The cost of publishing your L2 transaction on Ethereum, which varies 
+  based on the blob fee market, and is covered by the gas you pay on Linea.
 
-## Estimating transaction costs
+Learn more about [gas on Linea](./gas-on-linea.mdx).
 
 :::info
-The best method for estimating gas on Linea, `linea_estimateGas`, is currently unavailable, and will
-be activated soon. See our [reference page](../../reference/api/linea-estimategas.mdx) for more
-information. 
+A new API for estimating gas on Linea, `linea_estimateGas`, will be activated soon. See our 
+[reference page](../../reference/api/linea-estimategas.mdx) for more information. 
 
 Please get in touch via the [Linea Discord](https://discord.gg/linea) if you intend to use 
 `linea_estimateGas` once it is available.
@@ -59,14 +48,16 @@ Linea supports [`eth_estimateGas`](https://docs.infura.io/api/networks/linea/jso
 [`eth_gasPrice`](https://docs.infura.io/api/networks/linea/json-rpc-methods/eth_gasprice), and
 [`eth_feeHistory`](https://docs.infura.io/api/networks/linea/json-rpc-methods/eth_feehistory).
 
-We suggest you first use `eth_gasPrice` to get the gas price, in wei, and then use this value in 
-`eth_estimateGas`. 
+You can use `eth_gasPrice` or `eth_feeHistory` to get the gas price, in wei, and you can use 
+`eth_estimateGas` to find out how many units of gas a specific transaction will need. 
 
+:::note
 `eth_estimateGas` returns a total quantity of gas estimated for the transaction, contrasting with
 `linea_estimateGas`, which also will return `baseFeePerGas` and `priorityFeePerGas` once available. 
 `eth_estimateGas` is therefore less precise and generally provides a higher estimate.
+:::
 
-## Step 1: `eth_gasPrice`
+## Use `eth_gasPrice`
 
 ### Parameters
 
@@ -105,7 +96,69 @@ A hexadecimal equivalent of an integer representing the current gas price in wei
   </TabItem>
 </Tabs>
 
-## Step 2: `eth_estimateGas`
+## Use `eth_feeHistory`
+
+### Parameters 
+
+- `blockCount`: (integer) Number of blocks in the requested range. Between 1 and 1024 blocks can be 
+  requested in a single query. If blocks in the specified block range are not available, then only the 
+  fee history for available blocks is returned.
+- `newestBlock`: (string) Integer representing the highest number block of the requested range, or 
+  one of the string tags `latest`, `earliest`, or `pending`.
+- `array` of `integers`: (optional) A monotonically increasing list of percentile values to sample 
+  from each block's effective priority fees per gas in ascending order, weighted by gas used.
+
+### Returns 
+
+- `oldestBlock`: Lowest number block of the returned range expressed as a hexadecimal number.
+- `baseFeePerGas`: An array of block base fees per gas, including an extra block value. The extra 
+  value is the next block after the newest block in the returned range. Returns zeroes for blocks 
+  created before EIP-1559.
+- `gasUsedRatio`: An array of block gas used ratios. These are calculated as the ratio of `gasUsed` 
+  and `gasLimit`.
+- `reward`: An array of effective priority fee per gas data points from a single block. All zeroes 
+  are returned if the block is empty.
+
+### Example 
+
+#### Request
+
+<Tabs>
+  <TabItem value="cURL">
+    ```bash
+    curl https://rpc.sepolia.linea.build \
+        -X POST \
+        -H "Content-Type: application/json" \
+        -d '{"id": 1, "jsonrpc": "2.0", "method": "eth_feeHistory", "params": ["0x1", "latest", [20]]}'
+    ```
+  </TabItem>
+</Tabs>
+
+#### Response
+
+<Tabs>
+  <TabItem value="JSON">
+    ```json
+    {
+      "jsonrpc":"2.0",
+      "id":1,
+      "result":{
+        "baseFeePerGas":[
+          "0x7",
+          "0x7"
+          ],
+        "gasUsedRatio":[0.0030745737704918033],
+        "oldestBlock":"0x396334",
+        "reward":[
+          ["0x1427509c5"]
+          ]
+        }
+    }
+    ```
+  </TabItem>
+</Tabs>
+
+## Use `eth_estimateGas`
 
 ### Parameters