Clarify running nodes (#49)

* Move this Beta note to the landing page

* Move this general stuff to the landing page

* Clarify the three node types

* Clarify lifecycle

* Clarify running the Smart Rollup node

* Starting an Etherlink node

* Move building installer kernel up

* Clarify hoq to build installer kernel

* Put the kernel build instructions back into the appendix

* This is for production use

* Don't need the installer kernel

* This param no longer exists

* Got to have the installer.hex file

* Updated installer kernel from Sylvain

* Get the file name right

* Not necessary to refer to nodes as "octez nodes"

Co-authored-by: Sylvain Ribstein <[email protected]>

* octez smart rollup node in observer mode

Co-authored-by: Sylvain Ribstein <[email protected]>

* The commit that works is b9f6c91

* Docker builds

* Clarify connection to archive/rolling node

* Example of URL to SR node

* health of node

* Remove force

* This command uses preimages hosted online

* Set preimages endpoint in the config command

* Can use a specific docker image for the Etherlink node

* numbering

* Clarify

* Clarify

* Clarify

* Correct commits from Sylvain

* Refactor into a network section

* Per Sylvain, use latest commit for EVM node

* Rework into architecture section

* Clarify that if you start from genesis you get an archive node

* Sequencer sends blocks to SR node, which sends to layer 1 node

* extra space

* use MD

* Rework based on conversation with Joel

* unsafe patches are required only for old octez builds

* TriliTech

* How to start the Smart Rollup node from a snapshot

* Make snapshot the default

* Simplify where to get the binary

* Won't be in Octez v20

* Blueprints are like unvalidated, unfinalized blocks; the transactions in them are not final until they are published on Tezos layer 1.

* Smart Rollup nodes store the true state of the Etherlink blockchain.

* Clarify what final means

* verify that these blueprints make it to Tezos layer 1.

Co-authored-by: Sylvain Ribstein <[email protected]>

* that node publishes those blueprints on Tezos layer 1.

Co-authored-by: Sylvain Ribstein <[email protected]>

* Theses operations are included in layer 1 blocks.

Co-authored-by: Sylvain Ribstein <[email protected]>

* typos

* Diagram update from review

* Remove "validate it"

Co-authored-by: Sylvain Ribstein <[email protected]>

* typos

* and applying new blueprints that process EVM transactions.

Co-authored-by: Sylvain Ribstein <[email protected]>

* Remove part about validation and verification

* Default value is `$HOME/.tezos-smart-rollup-node`.

Co-authored-by: Sylvain Ribstein <[email protected]>

* style

* you must manually update this directory

Co-authored-by: Sylvain Ribstein <[email protected]>

* This command uses preimages hosted online.

Co-authored-by: Sylvain Ribstein <[email protected]>

* Default is `$HOME/.octez-evm-node`.

Co-authored-by: Sylvain Ribstein <[email protected]>

* style

* Remove "fair"

* Remove duplicate sentence

* Show specific commit

Co-authored-by: Sylvain Ribstein <[email protected]>

* indentation

* Public SR nodes not yet available

* Set the parameters for the etherlink kernel

Co-authored-by: Sylvain Ribstein <[email protected]>

* Capitalize Etherlink

* Move building instructions to a different page

* Hide the internal detail that the sequencer uses an SR node

* Simplify description of layer 1 nodes

* Remove this for now until we agree on how to discuss finality

* Remove mention of blueprints and clarify the sequencer

* Emojis at the right now

* Review comments from Sylvain

* Clarify use of prebuilt preimages

* The Tezos Foundation

---------

Co-authored-by: Sylvain Ribstein <[email protected]>

docs/index.mdx

@@ -4,12 +4,17 @@ title: 'What is Etherlink?'
 
 import Figure from '@site/src/components/Figure';
 
-Etherlink is an EVM-compatible, non-custodial Layer 2 blockchain powered by [Tezos Smart Rollup](https://tezos.com/developers/smart-rollups/) technology.
+Etherlink is an EVM-compatible, non-custodial Layer 2 blockchain powered by Tezos Smart Rollup technology.
 It supports Ethereum's ecosystem tools, including wallets and indexers, facilitating seamless integration and the capability to transfer assets to and from other EVM-compatible chains.
 
 Built upon the secure foundation of Tezos layer 1, Etherlink delivers a fast, fair, and (nearly) free experience.
 This permissionless and censorship-resistant environment empowers developers to build and participate in the next generation of decentralized applications.
 
+:::info
+Etherlink is in Beta.
+Its development team keeps this page up-to-date with the latest development as they improve the user experience and tools.
+:::
+
 ### It's fast
 
 Etherlink is low latency, with sub-second (< 500ms) confirmation times, delivered by the sequencer.

docs/network/architecture.md

@@ -0,0 +1,50 @@
+---
+title: Etherlink architecture
+---
+
+Etherlink's main components are its nodes and the sequencer.
+
+## Sequencer
+
+Etherlink relies on a sequencer to publish transactions.
+It receives transactions from EVM nodes, puts them in order, and publishes them in two ways:
+
+- It publishes transactions to EVM nodes, which can consider them final as long as they trust that the sequencer will publish them to layer 1.
+- It publishes transactions to Tezos layer 1, which finalizes them.
+
+## Nodes
+
+In its life cycle, an Etherlink transaction goes through three distinct types of nodes.
+These three nodes are being developed as part of the [Octez software suite](https://tezos.gitlab.io/introduction/tezos.html):
+
+- EVM nodes (`octez-evm-node`): The EVM nodes maintain a local copy of the Etherlink context and expose a [JSON RPC API](https://ethereum.org/en/developers/docs/apis/json-rpc/)-compliant endpoint for clients to submit transactions to.
+They forward these transactions to the sequencer and receive transactions from the sequencer, which they use to update their state.
+They also check Smart Rollup nodes to verify that these transactions make it to Tezos layer 1.
+- Smart Rollup nodes (`octez-smart-rollup-node`): Smart Rollup nodes store the state of the Etherlink blockchain from the perspective of Tezos layer 1.
+  They monitor the Tezos layer 1 Smart Rollup inbox, filter the inbox to Etherlink-related messages, process them, and update their states.
+
+  Importantly, the Smart Rollup nodes store the state of Etherlink based on the information that they get from layer 1, not on information from EVM nodes or the sequencer.
+
+  For more information about Smart Rollup nodes in general, see [Smart Rollups](https://docs.tezos.com/architecture/smart-rollups) on docs.tezos.com and [Smart Rollup Node](https://tezos.gitlab.io/shell/smart_rollup_node.html) in the Octez documentation.
+- Tezos layer 1 nodes (`octez-node`): Layer 1 nodes are responsible for the state of layer 1.
+In addition to ordinary layer 1 transactions, they receive Etherlink transactions from the sequencer.
+Then the baking nodes publish the Etherlink transactions in the Smart Rollup inbox in layer 1 blocks.
+For more information about Tezos layer 1 and its nodes, see [Architecture](https://docs.tezos.com/architecture) on docs.tezos.com.
+
+## Diagram
+
+This diagram summarizes the interaction between the nodes and the sequencer:
+
+![A high-level diagram of Etherlink architecture, showing the interaction between the nodes and the sequencer](/img/architecture.png)
+
+## Transaction lifecycle
+
+The overall lifecycle of a typical operation is as follows:
+
+1. A user submits a transaction to an EVM node.
+1. The EVM node forwards the transaction to the sequencer.
+1. The sequencer puts the transaction in its queue as soon as possible (less than 500ms after receiving it in a nominal scenario).
+1. The sequencer publishes the transaction to the EVM nodes.
+1. The sequencer publishes the transaction to layer 1.
+1. The Smart Rollup nodes tracking the state of Etherlink fetch the new Etherlink transactions from layer 1 and update their states.
+1. The EVM nodes check the state of the Smart Rollup nodes to verify that transactions have successfully and faithfully been finalized on layer 1.

docs/network/building-kernel.md

@@ -0,0 +1,60 @@
+---
+title: Building the Etherlink kernel
+---
+
+It's not necessary to build Etherlink's kernel.
+You can set the `pre-images-endpoint` field in the Smart Rollup node's configuration file as described in [Running an Etherlink Smart Rollup node](./smart-rollup-nodes).
+You can also download the installer kernel here: [installer.hex](/files/installer.hex).
+
+However, if you want to build the kernel yourself, you can use these instructions.
+
+This build process creates the installer kernel, which is a compressed version of the kernel that provides only enough information to install the original kernel.
+The data for the original kernel is stored in separate files called preimages.
+For more information about installer kernels and preimages, see the tutorial [Deploy a Smart Rollup](https://docs.tezos.com/tutorials/smart-rollup) on docs.tezos.com.
+
+The Etherlink build process relies on a Docker image to ensure reproducible builds, so you must have Docker installed.
+
+Follow these steps to build the installer kernel:
+
+1. Clone the repository at https://gitlab.com/tezos/tezos.
+1. Check out the commit with the hash `b9f6c9138719220db83086f0548e49c5c4c8421f`.
+1. Build the kernel by running this command from the root directory:
+
+   ```bash
+   ./etherlink/scripts/build-wasm.sh
+   ```
+
+   This command creates the file `etherlink/kernels-b9f6c9138719220db83086f0548e49c5c4c8421f/evm_kernel.wasm`.
+
+1. Run this command to install the installer kernel build dependencies:
+
+   ```bash
+   make -f kernels.mk build-deps kernel_sdk
+   ```
+
+1. Set the parameters for the Etherlink kernel by running this command, which sets the chain ID, governance and bridge contracts, and other values:
+
+   ```bash
+   octez-evm-node make kernel installer config setup_file.yml --chain-id 42793 \
+     --sequencer edpktufVZGs2JmEwHSFLdA7XHXotmnkD2Nwr75ACpxUr1iKUWzYFHJ      \
+     --delayed-bridge KT1AZeXH8qUdLMfwN2g7iwiYYSZYG4RrwhCj                   \
+     --ticketer KT1CeFqjJRJPNVvhvznQrWfHad2jCiDZ6Lyj                         \
+     --sequencer-governance KT1NcZQ3y9Wv32BGiUfD2ZciSUz9cY1DBDGF             \
+     --kernel-governance KT1H5pCmFuhAwRExzNNrPQFKpunJx1yEVa6J                \
+     --kernel-security-governance KT1N5MHQW5fkqXkW9GPjRYfn5KwbuYrvsY1g       \
+     --sequencer-pool-address 0xCF02B9Ca488f8F6F4E28e37AA1bDD16b3F1b2aD8     \
+     --delayed-inbox-min-levels 1600 --remove-whitelist
+   ```
+
+1. Run this command to build the installer kernel:
+
+   ```bash
+   smart-rollup-installer get-reveal-installer \
+     -u etherlink/kernels-b9f6c9138719220db83086f0548e49c5c4c8421f/evm_kernel.wasm \
+     -o installer.hex \
+     -P wasm_2_0_0 \
+     -S setup_file.yml \
+     -d
+   ```
+
+The output of the build process is the installer kernel itself, named `installer.hex`, and the preimages for the kernel, in the `wasm_2_0_0` directory.

docs/network/evm-nodes.md

@@ -0,0 +1,45 @@
+---
+title: Running an Etherlink EVM node
+---
+
+The Etherlink EVM nodes are responsible for maintaining a copy of the Etherlink context and applying new blueprints that process EVM transactions.
+
+## Prerequisites
+
+- Make sure you understand the interaction between different nodes as described in [Etherlink architecture](./architecture).
+- Run an Etherlink Smart Rollup node as described in [Running an Etherlink Smart Rollup node](./smart-rollup-nodes).
+Public Smart Rollup nodes for Etherlink are not yet available, so you must run your own if you want to participate in the Etherlink network.
+- Get the Etherlink installer kernel (`installer.hex` file), which you can build yourself as described in [Building the Etherlink kernel](./building-kernel) or download here: [installer.hex](/files/installer.hex).
+
+## Running an Etherlink EVM node
+
+Follow these steps to run the EVM node:
+
+1. Get a built version of the EVM node binary, named `octez-evm-node`.
+Octez does not yet provide a binary build of the EVM node as part of its binary distribution or in the `tezos/tezos` docker image, so you must build it yourself from the latest commit from the Octez source code.
+See [Installing Octez](https://tezos.gitlab.io/introduction/howtoget.html).
+1. Set the `sr_node_observer_rpc` environment variable to the URL to the Smart Rollup node you set up in the previous section, such as `http://localhost:8932`.
+1. Set the `evm_observer_dir` environment variable to the directory where the node should store its local data.
+The default is `$HOME/.octez-evm-node`.
+1. Initialize the node by running this command:
+
+   ```bash
+   octez-evm-node init config --devmode \
+     --data-dir $evm_observer_dir --rollup-node-endpoint $sr_node_observer_rpc \
+     --preimages-endpoint https://snapshots.eu.tzinit.org/etherlink-mainnet/wasm_2_0_0 \
+     --evm-node-endpoint https://node.mainnet.etherlink.com
+   ```
+
+   This command uses preimages hosted online.
+   It's safe to use these preimages because the node verifies them.
+   If you don't want to use third-party preimages, you can build the kernel yourself and move the contents of the `wasm_2_0_0/` directory to the local data directory; see [Building the Etherlink kernel](./building-kernel).
+   However, in this case, you must manually update this directory with the preimages of every kernel voted by the community and deployed on Etherlink after that.
+
+1. Run this command to start the node with the Etherlink installer kernel that you built or downloaded; change the name of the `installer.hex` file in the command accordingly:
+
+   ```bash
+   octez-evm-node run observer --data-dir $evm_observer_dir --initial-kernel installer.hex
+   ```
+
+By default, the EVM node exposes its JSON RPC API endpoint to `localhost:8545`.
+You can test that everything works as expected by running RPC requests manually or by setting your wallet to use your local node.

docs/network/smart-rollup-nodes.md

@@ -0,0 +1,84 @@
+---
+title: Running an Etherlink Smart Rollup node
+---
+
+Etherlink uses Smart Rollup nodes as a bridge between the EVM transactions on the EVM nodes and Tezos layer 1.
+Public Smart Rollup nodes for Etherlink are not yet available, so you must run your own if you want to participate in the Etherlink network.
+
+The Smart Rollup node runs the _kernel_, which is a Rust program compiled in WASM implementing the semantics of Etherlink blocks and transactions.
+
+To start, the node uses the _installer kernel_, which is a compressed version of the kernel that provides only enough information to install the original kernel.
+The data for the original kernel is stored in separate files called _preimages_.
+
+## References
+
+Make sure that you understand the interaction between different nodes as described in [Etherlink architecture](./architecture).
+
+For more information about Smart Rollup nodes in general, see [Smart Rollups](https://docs.tezos.com/architecture/smart-rollups) on docs.tezos.com and [Smart Rollup Node](https://tezos.gitlab.io/shell/smart_rollup_node.html) in the Octez documentation.
+
+## Running the Smart Rollup node from a snapshot
+
+You can start the Smart Rollup node with a snapshot of the Etherlink state to prevent it from having to compute the state from Etherlink genesis.
+
+For simplicity, these steps show how to run the smart rollup node in observer mode:
+
+1. Get a built version of the Smart Rollup node binary, named `octez-smart-rollup-node`.
+The best place to get the most recent binary files to use with Etherlink is https://gitlab.com/tezos/tezos/-/releases.
+
+1. Initialize the local context of the node, which is where it stores local data:
+
+   1. Set the environment variable `sr_observer_data_dir` to the directory where the node should store its local data.
+   The default value is `$HOME/.tezos-smart-rollup-node`.
+   1. Initialize the local context by running this command:
+
+      ```bash
+      octez-smart-rollup-node init observer config for sr1Ghq66tYK9y3r8CC1Tf8i8m5nxh8nTvZEf \
+        with operators --data-dir $sr_observer_data_dir \
+        --pre-images-endpoint https://snapshots.eu.tzinit.org/etherlink-mainnet/wasm_2_0_0
+      ```
+
+      This command generates a minimal configuration file (`config.json`) in the local data folder:
+
+      ```json
+      { "smart-rollup-address": "sr1Ghq66tYK9y3r8CC1Tf8i8m5nxh8nTvZEf",
+        "smart-rollup-node-operator": {}, "fee-parameters": {}, "mode": "observer",
+        "pre-images-endpoint":
+          "https://snapshots.eu.tzinit.org/etherlink-mainnet/wasm_2_0_0" }
+      ```
+
+      This configuration uses the preimages that the Tezos Foundation hosts on a file server on a so-called "preimages endpoint".
+      To build the preimages yourself, see [Building the Etherlink kernel](./building-kernel).
+
+1. Download the latest snapshot from https://snapshots.eu.tzinit.org/etherlink-mainnet/, which is named `eth-mainnet.snapshot`:
+
+   ```bash
+   wget https://snapshots.eu.tzinit.org/etherlink-mainnet/eth-mainnet.snapshot
+   ```
+
+1. Load the snapshot:
+
+   ```bash
+   octez-smart-rollup-node --endpoint https://rpc.tzkt.io/mainnet \
+     snapshot import eth-mainnet.snapshot \
+     --data-dir $sr_observer_data_dir
+   ```
+
+1. Start the Smart Rollup node in observer mode by running this command and using the RPC endpoint of a layer 1 node that is running in archive mode:
+
+   ```bash
+   octez-smart-rollup-node --endpoint https://rpc.tzkt.io/mainnet run \
+     --data-dir $sr_observer_data_dir
+   ```
+
+   As in this example, you can use a public layer 1 RPC node for initial setup, or you can connect it to a layer 1 node that you are running for a more stable connection.
+   A rolling node is sufficient if you are using a recent snapshot; if the snapshot is old, the Smart Rollup node needs a connection to an archive node.
+   After that you can connect it to a rolling node.
+
+1. Verify that the Smart Rollup node is running by querying it.
+For example, this query gets the health of the node:
+
+   ```bash
+   curl -s http://localhost:8932/health
+   ```
+
+Now that you have a Smart Rollup node configured for Etherlink, you can run an Etherlink EVM node, as described in [Running an Etherlink EVM node](./evm-nodes).

sidebars.js

@@ -34,7 +34,6 @@ const sidebars = {
           href: 'https://explorer.etherlink.com',
           label: 'Block Explorer',
         },
-        'get-started/running-nodes',
       ],
     },
     {
@@ -51,7 +50,19 @@ const sidebars = {
     },
     {
       type: 'category',
-      label: 'Tools 🔨',
+      label: 'The Etherlink network 🛜',
+      collapsed: false,
+      collapsible: false,
+      items: [
+        'network/architecture',
+        'network/smart-rollup-nodes',
+        'network/evm-nodes',
+        'network/building-kernel',
+      ],
+    },
+    {
+      type: 'category',
+      label: '🔨 Tools',
       collapsed: false,
       collapsible: false,
       items: [