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.
• If you want to verify the blueprints 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.

The EVM node runs Etherlink's kernel. You can get the kernel by importing it from a running Etherlink Smart Rollup node or by providing the installer kernel.

System requirements

Running an Etherlink EVM node on Etherlink Mainnet requires a computer with 500GB of disk space and at least 16GB RAM.

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.

Initializing the data directory

1. If you want your EVM node to check the correctness of the blueprints it receives via a Smart Rollup node, set the sr_node_observer_rpc environment variable to the URL of that Etherlink Smart Rollup node, such as http://localhost:8932.

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

3. Initialize the node. To trust incoming blueprints, use --dont-track-rollup-node:

   octez-evm-node init config \
     --data-dir $evm_observer_dir --dont-track-rollup-node \
     --preimages-endpoint https://snapshots.eu.tzinit.org/etherlink-mainnet/wasm_2_0_0 \
     --evm-node-endpoint https://relay.mainnet.etherlink.com

   Alternatively, if you want to rely on a Smart Rollup node to check the correctness of blueprints coming from the sequencer, use --rollup-node-endpoint:

   octez-evm-node init config \
     --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://relay.mainnet.etherlink.com

   This configuration uses the preimages that the Tezos Foundation hosts on a file server on a so-called "preimages endpoint". 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.

Running the node

You can initialize the node from a snapshot or allow it to compute the Etherlink state from genesis, which can take a long time.

From a snapshot

1. Download an Etherlink snapshot, and use the octez-evm-node to import it. Assuming you have set $latest_snapshot to the name of the latest snapshot,

   wget http://vps-58f6d7fc.vps.ovh.net/snapshots/$latest_snapshot -O snapshot.gz
   octez-evm-node snapshot import snapshot.gz --data-dir $evm_observer_dir

2. Run this command to start the node:

   octez-evm-node run observer --data-dir $evm_observer_dir

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

From an existing Etherlink Smart Rollup node

1. Download an Etherlink Smart Rollup node snapshot, and use the octez-smart-rollup-node binary to import it in a temporary directory.

   wget https://snapshots.eu.tzinit.org/etherlink-mainnet/eth-mainnet.full
   octez-smart-rollup-node --endpoint https://rpc.tzkt.io/mainnet \
     snapshot import eth-mainnet.full \
     --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.

2. Set the sr_observer_data_dir environment variable to the location of the data directory you got from the previous step.

3. Run this command to import the kernel from the Smart Rollup node:

   octez-evm-node init from rollup node $sr_observer_data_dir --data-dir $evm_observer_dir

4. Run this command to start the node:

   octez-evm-node run observer --data-dir $evm_observer_dir

   The EVM node runs in archive mode.

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

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_observer_dir --initial-kernel installer.hex

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

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. For example, you can call the node's RPC API with this command, putting the URL to your EVM node at the end:

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