Skip to main content

Running an Etherlink EVM node

The Etherlink EVM nodes are responsible for maintaining a copy of the Etherlink context and applying new blocks that process EVM transactions.

Prerequisites​

  • Make sure you understand the interaction between different nodes as described in Etherlink architecture.
  • If you want to verify the blocks that come from the sequencer, run an Etherlink Smart Rollup node as described in Running an Etherlink Smart Rollup node. 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.

System requirements​

The system requirements for the node depend on the History mode:

ModeMinimalRecommended
Rolling16GB memory, 100GB storage32GB memory, 100GB storage
Full16GB memory, 300GB storage32GB memory, 1TB storage
Archive16GB memory, 1TB storage32GB memory, 2TB storage

The recommended disk space allows extra space to accommodate growth.

Quickstart​

If you don't want to see all of the options and settings for the EVM node, you can run the node quickly with these steps:

  1. Download the latest release of the octez-evm-node binary from https://gitlab.com/tezos/tezos/-/releases.

    As of version 6.0, Etherlink requires at least version 0.48 of the octez-evm-node binary.

  2. Run the octez-evm-node run observer command to start the node as an observer:

    Use this command for Etherlink Mainnet:

    octez-evm-node run observer \
      --network mainnet \
      --history rolling:1 \
      --dont-track-rollup-node \
      --init-from-snapshot

    By default, the node stores its data and configuration file in the folder $HOME/.octez-evm-node. You can change these default locations by passing the --data-dir and --config-file arguments or setting the equivalent environment variables as described in Configuring the node.

  3. Wait for the node to download a snapshot and catch up to the current state of the network. See Verifying that the node is running.

Modes​

The EVM node supports these history modes:

  • archive (the default): The node stores a copy of all available Etherlink information.

  • full: The node stores all of the necessary information to construct the current Etherlink state plus the states for a certain number of previous days, known as the retention period.

  • rolling: The node stores the current context plus the complete transaction data for a certain number of previous days, known as the retention period.

The Octez EVM node history modes follow the same semantics as the Octez layer 1 node history modes. For more information about modes, see History modes in the Octez documentation.

To switch modes, see Switching history modes.

Getting the octez-evm-node binary​

The easiest way to get the octez-evm-node binary is to download the binaries distributed as part of its latest release from https://gitlab.com/tezos/tezos/-/releases. The release page provides static binaries for Linux systems (for amd64 and arm64 architectures).

As an alternative, you can use the minimal Docker image tezos/tezos-bare with a tag that includes octez-evm-node. These images contain the correct version of the binary. Docker examples below use tezos/tezos-bare:octez-evm-node-latest which will always be the most recent release.

When you run the Docker image, you must expose the port that the EVM node runs on to the host system. For example, this command runs the EVM node in the Docker container on port 8545 (the default) and uses the Docker -p argument to expose that port as port 8545 on the host system:

docker run -it -p 8545:8545 \
  --rm tezos/tezos-bare:octez-evm-node-latest octez-evm-node run observer \
  --network mainnet --history rolling:1  --dont-track-rollup-node \
  --init-from-snapshot --rpc-addr "0.0.0.0" --rpc-port "8545"

Configuring the node​

The node uses the following main parameters. You can specify these parameters as arguments to most commands or as environment variables:

  • The directory where it stores its data, which you specify in the --data-dir argument or in the EVM_NODE_DATA_DIR environment variable. The default directory is $HOME/.octez-evm-node. The following instructions use the placeholder <EVM_DATA_DIR> to represent this directory.

  • The location of its configuration file, which you specify in the --config-file argument or in the EVM_NODE_CONFIG_FILE environment variable. You can set a different location for the file if you want to separate the data directory from the node configuration, such as often happens in Kubernetes. The default location is the file config.json in the data directory.

  • The network to use, which you specify in the --network argument or the EVM_NODE_NETWORK environment variable.

    • --network mainnet for Etherlink Mainnet
    • --network testnet for Etherlink Ghostnet
    • --network shadownet for Etherlink Shadownet

    Choosing a network sets the node to use preimages that the Tezos Foundation hosts on a file server on a so-called "preimages endpoint". It also sets the relay endpoint that the node uses to connect to other nodes on the network. In this way, setting the --network argument implies these arguments:

    --preimages-endpoint https://snapshots.tzinit.org/etherlink-mainnet/wasm_2_0_0 \
    --evm-node-endpoint https://relay.mainnet.etherlink.com

    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. 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.

When you have the information for these parameters, follow these steps to generate the configuration file:

  1. If you want your EVM node to check the correctness of the blocks it receives via a Smart Rollup node, get the RPC URL of that Etherlink Smart Rollup node, such as http://localhost:8932. The following instructions use the placeholder <SR_NODE_OBSERVER_RPC> to represent this URL. You can use a Smart Rollup node that is running in any mode and history mode as long as it is up to date with the current state of Etherlink.

  2. Create a directory for the node to store its data in.

  3. Create the configuration file by setting the parameters in the environment variables or passing the arguments to the octez-evm-node init config command.

    If you are not running an Etherlink Smart Rollup node and are trusting incoming blocks, use the --dont-track-rollup-node flag, as in this mainnet example:

    octez-evm-node init config \
      --network mainnet \
      --data-dir <EVM_DATA_DIR> \
      --dont-track-rollup-node

    If you set the EVM_NODE_DATA_DIR and EVM_NODE_NETWORK environment variables, you can omit the --network and --data-dir arguments, as in this mainnet example:

    export EVM_NODE_DATA_DIR="<EVM_DATA_DIR>"
    export EVM_NODE_NETWORK=mainnet
    octez-evm-node init config --dont-track-rollup-node

    If you want to rely on a Smart Rollup node to check the correctness of blocks coming from the sequencer, pass the address of the Smart Rollup node to the --rollup-node-endpoint argument, as in this mainnet example:

    octez-evm-node init config \
      --network mainnet \
      --data-dir <EVM_DATA_DIR> \
      --rollup-node-endpoint <SR_NODE_OBSERVER_RPC>

The EVM node generates a configuration file and puts it in the location that you specified in the command.

Running the node​

You can initialize and start the node in several ways:

For a faster way of running a node locally for a short time, see Running a local sandbox.

In each case, you can specify the --network, --data-dir, and --config-file arguments or set the equivalent environment variables as described in Configuring the node.

From an automatic snapshot​

To automatically download and import a snapshot, start the node with the --init-from-snapshot switch and the network and mode to use, as in this example:

octez-evm-node run observer \
  --network mainnet \
  --history rolling:1 \
  --data-dir <EVM_DATA_DIR> \
  --dont-track-rollup-node \
  --init-from-snapshot

If you set the EVM_NODE_DATA_DIR and EVM_NODE_NETWORK environment variables, you can omit the --network and --data-dir arguments, as in this example:

export EVM_NODE_DATA_DIR="<EVM_DATA_DIR>"
export EVM_NODE_NETWORK=mainnet
octez-evm-node run observer \
  --history rolling:1 \
  --dont-track-rollup-node \
  --init-from-snapshot

The --history argument is required in this case to tell the node which snapshot to download. An appropriate snapshot must be available on the Nomadic Labs snapshot site.

The node can take time to download and import the snapshot.

From a manual snapshot​

You can manually select a snapshot and provide the URL of the snapshot to the node or download the file yourself.

You must select the appropriate snapshot for the network and history mode. Rolling and full snapshots provided on the Nomadic Labs snapshot site include 1 day of complete data. These snapshots are equivalent to the mode rolling:1 or full:1.

If you want a mode with a longer retention period, you can:

  • Use an older snapshot and allow the EVM node to compute the data since the snapshot was taken.
  • Start with a node in a mode that has the necessary data and switch to another history mode with the retention period that you want.
  • Create your own snapshot with the appropriate retention period from another EVM node.

EVM node snapshots are available at http://snapshotter-sandbox.nomadic-labs.eu.

To import the snapshot, pass the URL of the snapshot or the path to the downloaded snapshot file (represented here by the placeholder <SNAPSHOT_URL_OR_FILE>) to the octez-evm-node snapshot import command, as in this example:

octez-evm-node snapshot import <SNAPSHOT_URL_OR_FILE> \
  --data-dir <EVM_DATA_DIR>

If you provided the URL of the snapshot, the node downloads and imports it automatically. If you downloaded the snapshot manually, you can delete the snapshot file after the octez-evm-node snapshot import command completes.

Then, run this command to start the node, passing the data directory and the network and mode to use:

octez-evm-node run observer \
  --network mainnet \
  --history rolling:1 \
  --data-dir <EVM_DATA_DIR>

If you set the EVM_NODE_DATA_DIR and EVM_NODE_NETWORK environment variables, you can omit the --network and --data-dir arguments, as in this mainnet example:

export EVM_NODE_DATA_DIR="<EVM_DATA_DIR>"
export EVM_NODE_NETWORK=mainnet
octez-evm-node run observer \
  --history rolling:1 \
  --dont-track-rollup-node \
  --init-from-snapshot

If you have configured the data directory and imported a snapshot, you can omit the --history argument from the octez-evm-node run command. Including this argument allows you to verify that the node is configured for the mode and retention period that you want to run the node in. The node throws an error if you try to run it in a mode that it is not configured for.

You can use the Etherlink Smart Rollup node to initialize a data directory for the EVM node without having to actually start the Smart Rollup node. The octez-smart-rollup-node binary sets up a data directory that the EVM node can use as a starting point. You can use a Smart Rollup node that is running in any mode and history mode as long as it is up to date with the current state of Etherlink.

  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.

  2. Get the URL of the Etherlink Smart Rollup node snapshot for the appropriate Etherlink network or download the file manually:

    The full history snapshot is appropriate for most use cases. The EVM node can run in any history mode starting from a Smart Rollup node that starts from these snapshots.

  3. Use the octez-smart-rollup-node binary to import the snapshot into a temporary directory. The following mainnet examples use <SR_OBSERVER_DATA_DIR> as the location of this temporary directory and <SNAPSHOT_URL_OR_FILE> as the snapshot URL or file name.

    octez-smart-rollup-node --endpoint https://rpc.tzkt.io/mainnet \
      snapshot import <SNAPSHOT_URL_OR_FILE> \
      --data-dir <SR_OBSERVER_DATA_DIR>

    If you are running a Smart Rollup node on the same machine, you can skip this step because you can reuse its data directory.

  4. Run this command to import the kernel from the Smart Rollup node into the EVM node:

    octez-evm-node init from rollup node <SR_OBSERVER_DATA_DIR> --data-dir <EVM_DATA_DIR>

  5. Run this command to start the node:

    octez-evm-node run observer --data-dir <EVM_DATA_DIR>

    The EVM node runs in archive mode. You can switch history modes with the command octez-evm-node switch history to <MODE>.

From genesis​

  1. Get the Etherlink installer kernel (installer.hex file), which you can build yourself as described in Building the Etherlink kernel or download here: installer.hex.

  2. 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:

    octez-evm-node run observer --data-dir <EVM_DATA_DIR> --initial-kernel installer.hex

    The --initial-kernel argument is needed only the first time that you start the node.

Switching history modes​

After the node is running in one mode you can switch to another history mode:

  1. Stop the node.
  2. Switch to the new mode with the command octez-evm-node switch history to <MODE>, where <MODE> is the new mode.
  3. Start the node as usual with the command octez-evm-node run.

For example, you can switch to rolling mode with the command octez-evm-node switch history to rolling:<DAYS>, where <DAYS> is the number of days of compete data to keep. Then when you restart the node, run octez-evm-node run observer --network <NETWORK> --history rolling:<DAYS> --data-dir <EVM_DATA_DIR>.

Because the node cannot reconstruct data that it does not have, you can switch from only some modes to some other modes:

  • The node can go from archive mode to rolling or full mode.
  • The node can go from full mode to rolling mode or full mode with a different retention period.
  • The node can go from rolling mode to rolling mode with a different retention period.

When you switch from full or rolling mode and change the retention period, the node can increase the retention period, but it does not immediately retrieve the new data. For example, you can switch from rolling:1 mode to rolling:5 mode, but the node does not immediately download the previous 5 days of data. Instead, it begins storing more data as time passes until it has enough for 5 days of history. You can also start a node in rolling:5 mode by downloading a rolling snapshot that is 5 days old or by switching from archive mode.

Switching modes can increase the size of the data directory, so be sure that the node has enough disk space before switching. For example, switching from another mode to rolling mode requires more space than starting a new node in rolling mode from a new data directory with the same retention period.

If you switch the node from archive mode to full mode, it reduces the size of the data directory the next time that the node runs internal garbage collection, within 24 hours. Switching between other modes does not immediately reduce the size of the data directory.

Verifying that the node is running​

The node is ready when the log shows new block numbers, as in this example:

Mar 14 11:04:04.155 NOTICE │ head is now 7523759, applied in 11.422ms

By default, the EVM node exposes its JSON RPC API endpoint to localhost:8545. To set the host name or port that the node listens on, use the --rpc-addr or --rpc-port arguments of the octez-evm-node run command.

You can test that everything works as expected by running RPC requests manually or by setting your wallet to use your local node. For example, this command gets the number of the most recent block in hexadecimal:

curl -X POST -H 'Content-Type: application/json' --data '{"jsonrpc":"2.0","method":"eth_blockNumber"}' http://localhost:8545

Stopping the node​

The EVM node respects SIGTERM and exits cleanly when stopped, so you can stop it in any way that you would ordinarily stop a program on your system.

Last updated on
arrow icon

Prev

Running an Etherlink Smart Rollup node

Next

arrow icon
Building the Etherlink kernel
outline iconPage Outline