Merge branch 'main' into patch-4

README.md

@@ -37,7 +37,7 @@ In fact, it's part of the PR process.
 ### Contribute to community tutorials
 
 If you've created fleshed-out guides and tutorials, or intend to, we'd love to feature your content
-in our [community tutorials section](developers/guides/community).
+in our [community tutorials section](./docs/developers/guides/community/index.mdx).
 
 First, create an issue describing the content you want to see added or intend to add. If you're
 representing an organization (such as a dapp), please use the ecosystem contribution issue form.
@@ -95,15 +95,15 @@ to manage Node.js versions on your machine.
 
 ### Build
 
-  $ npm run build
+ $ npm run build
 
 This command generates static content into the `build` directory and can be served using any static
 contents hosting service.
 
 ### Adding new words to the dictionary
 
 This repository includes a _linter_, which you can think of as a spell-check that also checks code
-formatting and standards, and a lot more. It's possible that you will use a word in your content
+formatting and standards, and a lot more. It's possible that you might use a word in your content
 that is not known to the linter, and your build, or commit, will fail.
 
 You can run the linter any time with the command `npm run lint`.

docs/architecture/overview/transaction-lifecycle.mdx

@@ -10,9 +10,9 @@ image: /img/socialCards/transaction-lifecycle.jpg
 
 Finality has two definitions on Linea:
 - Soft finality: The transaction is confirmed on Linea. This takes two seconds, i.e Linea's block 
-time. See [step 3](#step-3-transaction-data-sent-to-the-state-manager). For simplicity, Linea does 
-not reorg—remove competing versions of blockchain history in favor of a canonical one—when there 
-are reorgs on L1. 
+time. See [step 3](#step-3-transaction-data-sent-to-the-state-manager). For simplicity, Linea is 
+guaranteed to not reorg—remove competing versions of blockchain history in favor of a canonical 
+one—when there are reorgs on L1. 
 - Hard finality: The proof submitted to L1 has been verified, and two epochs have elapsed. The 
 typical time before hard finality is 8-32 hours, although the 8-hour minimum will be reduced to
 zero in a future release. See [step 6](#step-6-batch-finalization).

docs/developers/guides/finalized-block.mdx

@@ -6,24 +6,34 @@ image: /img/socialCards/retrieve-finalized-l2-blocks.jpg
 A finalized L2 block is a block on an L2 blockchain (Linea) that has been confirmed and validated
 by the L1 blockchain (Ethereum), ensuring its immutability and security.
 
-Linea doesn't currently support the Ethereum-standard `finalized` block parameter tag, meaning you
-cannot use the tag in JSON-RPC API calls to retrieve blocks that have been confirmed by the L1
-network. This includes, for example, methods where you can specify a block parameter, such as
-[`linea_estimateGas`](../reference/api/linea-estimategas.mdx).
+There are two methods to obtain the current finalized block:
 
-:::note
-Support for the `finalized` block parameter is planned in a future Linea release.
-:::
+- [Use the `finalized` block parameter tag](#use-the-finalized-tag) in JSON-RPC API calls.
+- [Query the Linea L1 rollup contract](#query-the-rollup-contract).
 
-This limitation requires you to query the [Linea L1 rollup contract](https://etherscan.io/address/0xd19d4b5d358258f05d7b411e21a1460d11b0876f#readProxyContract)
-to retrieve the value of the current finalized L2 block number stored in the `currentL2BlockNumber`
-variable.
+## Use the `finalized` tag
 
-## Prerequisites
+Use the `finalized` tag in API calls to specify a block that has been confirmed by the L1
+network. For example, here the `eth_getBlockByNumber` method returns information about the current
+finalized block:
+
+```bash
+curl https://rpc.linea.build \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["finalized",false],"id":1}'
+```
+
+## Query the rollup contract
+
+Query the [Linea L1 rollup contract](https://etherscan.io/address/0xd19d4b5d358258f05d7b411e21a1460d11b0876f#readProxyContract)
+to retrieve the value of the current finalized L2 block number stored in the `currentL2BlockNumber` variable.
+
+### Prerequisites
 
 - [Download and install Node.js](https://nodejs.org/en)
 
-## Create the script
+### Create the script
 
 1. In your project folder, initialize the project and install the `web3` package:
 

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

@@ -10,97 +10,195 @@ 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.
-
-There are minor differences in the way Linea handles gas calculations when compared with Ethereum:
+Linea supports the [Ethereum EIP-1559 gas price model](https://ethereum.org/developers/docs/gas):
+```
+total fee = units of gas used * (base fee + priority fee)
+```
 
-- **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.
+- **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.
 
-## Estimating transaction costs
+These two resource costs are abstracted by the rollup and covered by the recommended L2 gas price
+and gas used.
 
-Use the [`linea_estimateGas`](../../reference/api/linea-estimategas.mdx) API method to estimate the 
-gas cost for sending a transaction. The method returns the recommended gas limit, the base fee per 
-gas, and the priority fee per gas.
+Learn more about [gas on Linea](./gas-on-linea.mdx).
 
-The `linea_estimateGas` endpoint is currently unavailable. For more information, see 
-our [reference page](../../reference/api/linea-estimategas.mdx).
+:::info
+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. 
 
-:::info important
+If you intend to use `linea_estimateGas` once it is available, you want to find out more, or you 
+have further questions, please get in touch on [Discord](https://discord.gg/linea).
+:::
 
-Linea also supports [`eth_estimateGas`](https://docs.infura.io/api/networks/linea/json-rpc-methods/eth_estimategas),
+Linea supports [`eth_estimateGas`](https://docs.infura.io/api/networks/linea/json-rpc-methods/eth_estimategas),
 [`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), but 
-they usually return a higher (and less accurate) estimate than `linea_estimateGas`. 
+[`eth_feeHistory`](https://docs.infura.io/api/networks/linea/json-rpc-methods/eth_feehistory).
 
-We recommend you use `linea_estimateGas` where possible to maximize the accuracy of the gas 
-estimate.
+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, whereas
+`linea_estimateGas` will return `gasLimit`, `baseFeePerGas`, and `priorityFeePerGas` once available,
+providing a more precise estimate.
 :::
 
-The following example executes `linea_estimateGas` on the Linea testnet using the public RPC URL.
+## `eth_gasPrice`
 
-:::tip
+### Parameters
 
-You can also call the API using [Infura's supported Linea endpoints](https://docs.infura.io/api/networks/linea/choose-a-network).
-:::
+None.
+
+### Returns
+
+A hexadecimal equivalent of an integer representing the current gas price in wei.
 
-<Tabs className="my-tabs">
- <TabItem value="curl" label="curl" default>
+### Example
 
-```bash
-curl https://rpc.sepolia.linea.build \
+#### Request
+
+<Tabs>
+ <TabItem value="cURL">
+ ```bash
+ curl https://rpc.sepolia.linea.build \
  -X POST \
  -H "Content-Type: application/json" \
- -d '{"jsonrpc": "2.0","method": "linea_estimateGas","params": [{"from": "0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73","gasPrice":"0x100000000","gas":"0x21000"}],"id": 53}'
-```
+ -d '{"jsonrpc": "2.0","method": "eth_gasPrice","params": [],"id": 1}'
+ ```
+ </TabItem>
+</Tabs>
 
-</TabItem>
-<TabItem value="result" label="Result">
-
-```json
-{
- "jsonrpc": "2.0",
- "id": 53,
- "result": {
- "baseFeePerGas": "0x7",
- "gasLimit": "0xcf08",
- "priorityFeePerGas": "0x43a82a4"
- }
-}
-```
+#### Response
+
+<Tabs>
+ <TabItem value="JSON">
+ ```json
+ {
+ "jsonrpc":"2.0",
+ "id":1,
+ "result":"0x12eb10e0c"
+ }
+ ```
+ </TabItem>
+</Tabs>
 
+## `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>
 
-The `linea_estimateGas` API calculates gas fees as follows:
+#### Response
+
+<Tabs>
+ <TabItem value="JSON">
+ ```json
+ {
+ "jsonrpc":"2.0",
+ "id":1,
+ "result":{
+ "baseFeePerGas":[
+ "0x7",
+ "0x7"
+ ],
+ "gasUsedRatio":[0.0030745737704918033],
+ "oldestBlock":"0x396334",
+ "reward":[
+ ["0x1427509c5"]
+ ]
+ }
+ }
+ ```
+ </TabItem>
+</Tabs>
 
-- `baseFeePerGas` - Uses the Linea base fee which is set at 7 wei.
-- `gasLimit` - Uses the standard `eth_estimateGas` API calculation.
-- `priorityFeePerGas` - Calculates the fee required to prioritize a transaction by considering factors such as the
- compressed transaction size, layer 1 verification costs and capacity, gas price ratio between layer 1 and
- layer 2, the transaction's gas usage, the minimum gas price on layer 2, and a minimum
- margin (for error) for gas price estimation.
+## `eth_estimateGas`
 
-:::note
+### Parameters
 
-The result of the request returns hexadecimal equivalent integers of gas prices in wei. Convert the hexadecimal value into
-decimals to get the wei value. You can use any hexadecimal to decimal converter such as
-[RapidTables](https://www.rapidtables.com/convert/number/hex-to-decimal.html).
+- `TRANSACTION CALL OBJECT` [required]
+ - `from`: [optional] 20 Bytes - The address the transaction is sent from.
+ - `to`: 20 Bytes - The address the transaction is directed to.
+ - `gas`: [optional] Hexadecimal value of the gas provided for the transaction execution. `eth_estimateGas` consumes zero gas, but this parameter may be needed by some executions.
+ - `gasPrice`: [optional] Hexadecimal value of the gas price used for each paid gas.
+ - `maxPriorityFeePerGas`: [optional] Maximum fee, in wei, the sender is willing to pay per gas above the base fee. 
+ - `maxFeePerGas`: [optional] Maximum total fee (base fee + priority fee), in wei, the sender is willing to pay per gas. 
+ - `value`: [optional] Hexadecimal value of the value sent with this transaction.
+ - `data`: [optional] Hash of the method signature and encoded parameters. See the [Ethereum contract ABI specification](https://docs.soliditylang.org/en/latest/abi-spec.html).
+ - `block number`: [required] A string representing a block number, or one of the string tags `latest`, `earliest`, `pending`, `safe`, or `finalized`. See the [default block parameter](https://ethereum.org/en/developers/docs/apis/json-rpc/#default-block).
 
-:::
+### Returns
+
+A hexadecimal of the estimate of the gas required for the given transaction.
+
+### Example
+
+#### Request
+
+<Tabs>
+ <TabItem value="cURL">
+ ```bash
+ curl https://rpc.sepolia.linea.build \
+ -X POST \
+ -H "Content-Type: application/json" \
+ -d '{"jsonrpc":"2.0","method":"eth_estimateGas","params": [{"to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567","gasPrice": "0x12eb10e0c","value": "0x9184e72a"}],"id":1}'
+ ```
+ </TabItem>
+</Tabs>
+
+#### Response
+
+<Tabs>
+ <TabItem value="JSON">
+ ```json
+ {
+ "jsonrpc":"2.0",
+ "id":1,
+ "result":"0x5208"
+ }
+ ```
+ </TabItem>
+</Tabs>