Merge branch 'main' into state-management

Consensys · Sep 10, 2024 · 5d93934 · 5d93934
2 parents e8c0962 + e55b992
commit 5d93934
Show file tree

Hide file tree

Showing 5 changed files with 194 additions and 80 deletions.
diff --git a/README.md b/README.md
@@ -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`.

diff --git a/docs/architecture/overview/transaction-lifecycle.mdx b/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).

diff --git a/docs/developers/guides/gas/gas-fees.mdx b/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>
diff --git a/docs/developers/linea-version/index.mdx b/docs/developers/linea-version/index.mdx
@@ -609,8 +609,8 @@ Contracts audit is in progress. This does not reflect final versions.
     </details>
 
   - Contracts
-    - [Transparent Proxy](https://goerli.lineascan.build/address/0xC499a572640B64eA1C8c194c43Bc3E19940719dC/contracts#address-tabs)
-    - [Implementation](https://goerli.lineascan.build/address/0xc0557e2149751e201749b87f86acd91DB22e2662/contracts#address-tabs)
+    - Transparent Proxy: `0xC499a572640B64eA1C8c194c43Bc3E19940719dC` 
+    - Implementation: `0xc0557e2149751e201749b87f86acd91DB22e2662`
 
 - Bridging partners, before sending messages on L2, need to retrieve the service protection fee before sending messages and include it in the value sent.
 
@@ -637,7 +637,7 @@ Major changes are applied to the Canonical Token Bridge as described in our [doc
   </details>
 
   - Contracts
-    - [Transparent Proxy](https://goerli.lineascan.build/address/0xB191E3d98074f92584E5205B99c3F17fB2068927)
-    - [Implementation](https://goerli.lineascan.build/address/0x6081C1392793e22dA39871D4362c1e7045A5bace)
+    - Transparent Proxy: `0xB191E3d98074f92584E5205B99c3F17fB2068927`
+    - Implementation: `0x6081C1392793e22dA39871D4362c1e7045A5bace`
 
 If you have any questions, please reach out in the **Developer Support** channel in our [community forum](https://community.linea.build/c/developer-support)!
diff --git a/docs/developers/reference/api/linea-estimategas.mdx b/docs/developers/reference/api/linea-estimategas.mdx
@@ -83,12 +83,12 @@ You can also call the API using [Infura's supported Linea endpoints](https://doc
 <Tabs>
   <TabItem value="cURL">
 
-   ```bash
-   curl https://rpc.linea.build \
-   -X POST \
-   -H "Content-Type: application/json" \
-   -d '{"jsonrpc": "2.0","method": "linea_estimateGas","params": [{"from": "0x971e727e956690b9957be6d51Ec16E73AcAC83A7","gas":"0x21000"}],"id": 53}'
-   ```
+  ```bash
+  curl https://rpc.linea.build \
+  -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0","method": "linea_estimateGas","params": [{"from": "0x971e727e956690b9957be6d51Ec16E73AcAC83A7","gas":"0x21000"}],"id": 53}'
+  ```
 
   </TabItem>
   <TabItem value="ethers.js">
@@ -126,4 +126,20 @@ You can also call the API using [Infura's supported Linea endpoints](https://doc
     "priorityFeePerGas": "0x43a82a4"
   }
 }
-  ```
+```
+
+Where:
+- `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.
+
+:::note
+
+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).
+
+:::