Merge branch 'main' into tx-exclusion-api

docs/developers/guides/run-a-node/index.mdx

@@ -7,16 +7,30 @@ import DocCardList from "@theme/DocCardList";
 
 # Run a Linea node
 
+:::warning Reset Linea Sepolia nodes
+
+Linea's arithmetization will be updated as part of the Beta v1 release, which will be on 
+Linea Sepolia from September 23. 
+
+If you are running a Linea Sepolia node using the `advanced-testnet` profile, please reset your
+node(s) after September 23 to ensure they function correctly.
+
+:::
+
 There are no financial incentives for running a Linea node, but it does allow you to:
 
-- Call the Linea JSON RPC API methods and submit transactions to the mempool without relying on an RPC provider.
-- Have a local copy of the Linea blockchain. This view of the state is "trusted" until the transaction, or the
-    block that transaction is in, has been finalized on L1.
+- Call the Linea JSON RPC API methods and submit transactions to the mempool without relying on an 
+RPC provider. Note that using [Linea-specific API methods](../../reference/api/index.mdx) such as 
+`linea_estimateGas` and the `finalized` tag require using Linea Besu with the necessary plugins 
+enabled. Configuring your node to run with these plugins is covered in our guides. 
+- Have a local copy of the Linea blockchain, also known as a "follower" node. This view of the 
+state is "trusted" until the transaction, or the block that transaction is in, has been finalized 
+on L1.
 
 :::note
 
-Running a sequencer node is currently not possible and there is no option to vote on blocks as part of the consensus
-mechanism or [fork-choice](https://eth2book.info/capella/part3/forkchoice/#whats-a-fork-choice) like on Ethereum.
+There is currently no option to vote on blocks as part of the consensus mechanism or [fork-choice](https://eth2book.info/capella/part3/forkchoice/#whats-a-fork-choice) 
+like on Ethereum.
 
 :::
 

docs/developers/guides/run-a-node/use-binary.mdx

@@ -1,16 +1,21 @@
 ---
+title: Use a binary distribution
 description: Install the Besu or Geth client to run a Linea node.
-image: /img/socialCards/install-the-besu-or-geth-client-to-run-a-linea-node.jpg
+image: /img/socialCards/use-a-binary-distribution.jpg
 ---
 
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
 import VolumeCreation from "./volume-creation.mdx";
 
-# Use a binary distribution
-
 You can install the Hyperledger Besu or Geth client to run a Linea node from a binary distribution.
+For Besu nodes, you have a choice between: 
+- Using standard Besu software to run a follower node, which keeps a local copy of the blockchain, 
+or;
+- Using Linea Besu if you intend to use the node to interact with the blockchain, or provide it to
+others to do so. Linea Besu extends Besu's functionality with plugins and is recommended for 
+infrastructure providers.
 
 ## Prerequisites
 
@@ -19,8 +24,11 @@ official documentation:
 
 - [Hyperledger Besu](https://besu.hyperledger.org/public-networks/get-started/system-requirements)
 - [Geth](https://geth.ethereum.org/docs/getting-started/hardware-requirements).
+- Linea Besu: Download the latest version of `linea-besu-package` from its [releases page](https://github.com/Consensys/linea-besu-package/releases). 
+Find the "Assets" subheading on the latest release and download the zip file named 
+`linea-besu-package-<version>.tar.gz`. 
 
-## Run the Besu client
+## Run a standard Besu client
 
 ### Step 1. Install Besu
 
@@ -56,7 +64,7 @@ Download the genesis file and Besu configuration file.
 
 </Tabs>
 
-### Step 3. Define disk space volume (optional) {#disk-space-besu}
+### Step 3. Define disk space volume (optional) \{#disk-space-besu}
 
 Define a volume size appropriate to your expected usage. As of March 20 2024, Besu nodes use:
 
@@ -103,6 +111,81 @@ Run the Besu client with the location of your configuration file. For example:
 
 The Besu node will attempt to find peers to begin synchronizing and to download the world state. 
 
+## Run a Linea Besu node
+
+:::warning
+
+Please note that the `advanced` profile option does not currently support macOS/ARM. Please use 
+Linux/ARM or Windows/X86_64. 
+
+:::
+
+Linea Besu is an implementation of the Hyperledger Besu client that extends its functionality. 
+
+We recommend using Linea Besu over standard Besu if you intend to run a node and use it to interact 
+with the blockchain, rather than just following it. 
+
+Linea Besu enables you to use plugins adapted specifically for Linea, such as the [Linea Sequencer 
+plugin](https://github.com/Consensys/linea-sequencer).
+
+These plugins are necessary, in different ways, to enable full functionality for the node. 
+Linea-specific API endpoints like `linea_estimateGas`, for example, require the `linea-sequencer` 
+plugin. You can pick a plugin by selecting a profile in [step 2](#step-2-select-a-profile).
+
+This guide is for infrastructure providers and operators who intend to run a Linea node. This is 
+relevant to you if:
+- You are responsible for operating nodes as a service for others to use
+- You want to use Linea with a personal, private RPC endpoint.
+
+### Step 1. Unzip the folder
+
+The `linea-besu-package-<version>.tar.gz` is a zip file; move it to the directory of your choice 
+and unzip it. 
+
+### Step 2. Select a profile
+
+In the unzipped directory, find `profiles`. The `.toml` configuration files in this folder define 
+the parameters for each possible profile you can select for your Linea Besu node. 
+
+<Tabs groupId="networks" className="my-tabs">
+  <TabItem value="mainnet" label="Mainnet">
+    Select one according to your preferences:
+    - `basic-mainnet`: Creates a basic follower node on Linea Mainnet with no plugins enabled.
+    - `advanced-mainnet`: Creates an advanced node on Linea Mainnet with plugins that enable support for
+    `linea_estimateGas` and the `finalized` block parameter tag.
+  </TabItem>
+  <TabItem value="Linea Sepolia" label="Linea Sepolia">
+    Select one according to your preferences:
+    - `basic-testnet`: Creates a basic follower node on Linea Sepolia with no plugins enabled.
+    - `advanced-testnet`: Creates an advanced node on Linea Sepolia with plugins that enable support for
+    `linea_estimateGas` and the `finalized` block parameter tag.
+  </TabItem>
+</Tabs>
+
+### Step 3. Start the Linea Besu client
+
+In a terminal, navigate to the `linea-besu-package-<version>` directory, where the `bin`, `genesis`, 
+`profiles` etc. directories are. 
+
+Now run Linea Besu, specifying your preferred profile. The `--plugin-linea-l1-rpc-endpoint` must 
+only be defined if you are running an `advanced` node, since this is needed to query finalization
+on L1.
+
+<Tabs groupId="networks" className="my-tabs">
+    <TabItem value="mainnet" label="Mainnet">
+    ```bash
+    bin/besu --profile=advanced-mainnet --plugin-linea-l1-rpc-endpoint=<endpoint> 
+    ```
+    </TabItem>
+    <TabItem value="Linea Sepolia" label="Linea Sepolia">
+    ```bash
+    bin/besu --profile=advanced-testnet --plugin-linea-l1-rpc-endpoint=<endpoint> 
+    ```
+    </TabItem>
+</Tabs>
+
+The node will attempt to find peers to begin synchronizing and to download the world state. 
+
 ## Run the Geth client
 
 ### Step 1. Install Geth
@@ -134,7 +217,7 @@ Download the genesis file for the relevant network.
   </TabItem>
 </Tabs>
 
-### Step 3. Define disk space volume (optional) {#disk-space-geth}
+### Step 3. Define disk space volume (optional) \{#disk-space-geth}
 
 Define a volume size appropriate to your expected usage. As of March 20 2024, Geth nodes use:
 - Full nodes: 170GB, growing ~2.6GB per day.

docs/developers/guides/run-a-node/use-docker.mdx

@@ -1,21 +1,20 @@
 ---
+title: Use Docker
 description: Use Docker to run a Besu or Geth client as a Linea node.
-image: /img/socialCards/use-docker-to-run-a-besu-or-geth-client-as-a-linea-node.jpg
+image: /img/socialCards/use-docker.jpg
 ---
 
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-# Use Docker
-
-You can use Docker to run [Hyperledger Besu](https://besu.hyperledger.org/) or [Geth](https://geth.ethereum.org/) as
-a Linea node on the mainnet or testnets.
+You can use Docker to run [Hyperledger Besu](https://besu.hyperledger.org/), [Linea Besu](https://github.com/Consensys/linea-besu-package/tree/main),
+ or [Geth](https://geth.ethereum.org/) as a Linea node on Mainnet or Linea Sepolia.
 
 ## Prerequisites
 
 Download and install [Docker](https://www.docker.com/products/docker-desktop/).
 
-## Run a Besu node
+## Run a standard Besu node
 
 :::warning Important
 
@@ -76,6 +75,111 @@ for help if you experience peering issues.
 
 :::
 
+## Run a Linea Besu node
+
+Linea Besu is an implementation of the Hyperledger Besu client that extends its functionality. 
+
+We recommend using Linea Besu over standard Besu if you intend to run a node and use it to interact 
+with the blockchain, rather than just following it. 
+
+Linea Besu enables you to use plugins adapted specifically for Linea, such as the [Linea Sequencer 
+plugin](https://github.com/Consensys/linea-sequencer).
+
+These plugins are necessary, in different ways, to enable full functionality for the node. 
+Linea-specific API endpoints like `linea_estimateGas`, for example, require the `linea-sequencer` 
+plugin. You can pick a plugin by selecting a profile in step 1.
+
+This guide is for infrastructure providers and operators who intend to run a Linea node. This is 
+relevant to you if:
+- You are responsible for operating nodes as a service for others to use
+- You want to use Linea with a personal, private RPC endpoint.
+
+### Step 1. Download the relevant `docker-compose.yaml` file
+
+Access the [`/docker` directory](https://github.com/Consensys/linea-besu-package/tree/main/docker) 
+in the Linea Besu repository. There are several `.yaml` files here corresponding to Besu profiles. 
+Each profile enables you to run a node with different Linea Besu plugin configurations depending on
+your use case.
+
+<Tabs groupId="networks" className="my-tabs">
+  <TabItem value="mainnet" label="Mainnet">
+    Download the appropriate `.yaml` file for your use case:
+    - `basic-mainnet`: Creates a basic follower node on Linea Mainnet with no plugins enabled.
+    - `advanced-mainnet`: Creates an advanced node on Linea Mainnet with plugins that enable support 
+    for `linea_estimateGas` and the `finalized` block parameter tag.
+  </TabItem>
+  <TabItem value="Linea Sepolia" label="Linea Sepolia">
+    Download the appropriate `.yaml` file for your use case:
+    - `basic-testnet`: Creates a basic follower node on Linea Sepolia with no plugins enabled.
+    - `advanced-testnet`: Creates an advanced node on Linea Sepolia with plugins that enable support 
+    for `linea_estimateGas` and the `finalized` block parameter tag.
+  </TabItem>
+</Tabs>
+
+### Step 2. Update IP address
+
+In the `.yaml` file you downloaded, adjust the `--p2p-host` command with your public IP address:
+
+```yaml
+--p2p-host=103.10.10.10
+```
+
+:::tip
+
+You can use [this page](https://www.whatismyip.com/) to find your public IP address.
+
+:::
+
+### Step 3. Configure your L1 RPC endpoint
+
+If you're using an `advanced` profile, insert your preferred L1 RPC endpoint in the 
+`docker-compose.yaml` file:
+
+```yaml
+--plugin-linea-l1-rpc-endpoint=YOUR_L1_RPC_ENDPOINT
+```
+
+If you only intend to run a `basic` profile, go straight to the next step.
+
+### Step 4. Start the Linea Besu node
+
+<Tabs groupId="networks" className="my-tabs">
+  <TabItem value="mainnet" label="Mainnet">
+    In a terminal, navigate to your `.yaml` file's directory. Then start the node by running 
+    `docker compose`: 
+
+    ```bash
+    docker compose -f ./your-file-path/docker-compose-advanced-mainnet.yaml up
+    ```
+
+    Alternatively, you can run a node without downloading a `.yaml` file with a `docker run` command. 
+    For example:
+
+    ```bash
+    docker run -e BESU_PROFILE=advanced-mainnet consensys/linea-besu-package:latest
+    ```
+
+    Adjust the `BESU_PROFILE` to match one of the profiles listed in step 1. 
+  </TabItem>
+  <TabItem value="Linea Sepolia" label="Linea Sepolia">
+      In a terminal, navigate to your `.yaml` file's directory. Then start the node by running 
+      `docker compose`: 
+
+      ```bash
+      docker compose -f ./your-file-path/docker-compose-advanced-testnet.yaml up
+      ```
+
+      Alternatively, you can run a node without downloading a `.yaml` file with a `docker run` command. 
+      For example:
+
+      ```bash
+      docker run -e BESU_PROFILE=advanced-testnet consensys/linea-besu-package:latest
+      ```
+
+      Adjust the `BESU_PROFILE` to match one of the profiles listed in step 1. 
+    </TabItem>
+</Tabs>
+
 ## Run a Geth node
 
 ### Step 1. Download configuration files

docs/developers/reference/api/linea-estimategas.mdx

@@ -9,24 +9,14 @@ import TabItem from '@theme/TabItem';
 
 # `linea_estimateGas`
 
-:::warning
+:::info Compatibility mode
 
-`linea_estimateGas` is currently unavailable, but we will provide activation dates soon. In the 
-meantime, please get in touch via the [Linea Discord](https://discord.gg/linea) if you intend to 
-use `linea_estimateGas` once it is available.
+`linea_estimateGas` is currently only available on Linea Sepolia fully activated and on Mainnet in compatibility mode, which means it 
+returns the same results as `eth_gasPrice` on mainnet. 
 
-:::
-
-:::info
-
-`linea_estimateGas` is only fully compatible with endpoints using the Besu client with the 
-[`linea-sequencer`](https://github.com/Consensys/linea-sequencer/tree/main) plugin enabled. If it 
-is unavailable, try updating Besu. If you prefer to use Geth, `linea_estimateGas` is only available 
-if you redirect your request through an Infura endpoint.
-
-We recommend using `linea_estimateGas` rather than alternatives, such as `eth_gasPrice`. 
-`linea_estimateGas` returns estimates with greater accuracy, minimizing the risk of transactions
-being priced incorrectly and failing as a result. 
+`linea_estimateGas` will be fully activated on Mainnet on September 30. Infrastructure providers 
+must adjust their node configurations to ensure compatibility mode is deactivated and `linea_estimateGas` 
+functions fully. See our [guide](#compatibility-mode).
 
 :::
 
@@ -146,3 +136,55 @@ decimals to get the wei value. You can use any hexadecimal to decimal converter
 [RapidTables](https://www.rapidtables.com/convert/number/hex-to-decimal.html).
 
 :::
+
+## Compatibility mode
+
+When `linea_estimateGas` is activated on Mainnet on September 30, infrastructure providers and those
+using their own nodes to submit transactions must adjust their configuration files to disable 
+compatibility mode.
+
+No action is required for Linea Sepolia nodes using the `advanced-testnet` profile from the 
+[`linea-besu-package` repository](https://github.com/Consensys/linea-besu-package/tree/main), since 
+`linea_estimateGas` is already activated on Linea Sepolia.
+
+### Effects 
+
+`linea_estimateGas` in compatibility mode returns the same gas price as `eth_gasPrice`. This means
+gas price is applied consistently regardless of the relative complexity of the transaction 
+(measured through its `calldata` size). As a result, transactions can be underpriced and risk 
+getting stuck, or be overpriced and result in the user overpaying in fees.
+
+### Benefits of disabling
+
+With compatibility mode disabled, `linea_estimateGas` is able to function as designed and return a 
+more accurate gas price, better suited to the transaction. The gas price scales with the amount of
+`calldata` a transaction contains. As a result, Linea can more effectively ensure the gas price
+reflects L1 costs and prover costs, which rise with transaction complexity/`calldata` size.
+
+### How to disable
+
+For most people running an `advanced` Linea Besu node —a prerequisite for using `linea_estimateGas`—
+compatibility mode will already be disabled in the files you downloaded from the [`linea-besu-package`
+repository](https://github.com/Consensys/linea-besu-package/tree/main). 
+
+:::note
+
+See our run a node guides for information on running a Linea Besu node [with Docker](../../guides/run-a-node/use-docker.mdx#run-a-linea-besu-node) 
+and [using the binary distribution](../../guides/run-a-node/use-binary.mdx#run-a-linea-besu-node).
+
+:::
+
+### Binary distribution
+
+To ensure compatibility is not running, check your `.toml` configuration file for the following
+setting, and ensure it is `false`:
+```
+plugin-linea-estimate-gas-compatibility-mode-enabled=false
+```
+
+This configuration may be `true` if you downloaded the files before September 30.
+
+### Docker
+
+The Docker image accessed via the `compose` files in the [`linea-besu-package` repository](https://github.com/Consensys/linea-besu-package/blob/main/linea-besu/profiles/advanced-sepolia.toml)
+will be updated via image update to ensure compatibility mode is disabled after September 30.