Skip to main content

Running Etherlink Nodes

info

Etherlink is still in Beta, and so is its software. We are keeping this page up-to-date with the latest development, and one of our focus moving forward is improving the UX and ease to administrate our tools.

Etherlink is a Layer 2 blockchain, powered by the Tezos Smart Rollup technology. Before anything else, it is a permissionless network, with a multitude of roles to assume.

The goal of this documentation page is to provide an overview of Etherlink’s architecture, and straightforward guides to help interested users getting started running nodes and joining the Etherlink network.

As of today, operating an Etherlink node requires some familiarity with the Tezos ecosystem, Smart Rollups, and the Octez testsuite.

Big Picture

In its life cycle, an Etherlink transaction will go through three distinct nodes, responsible for specific aspects of Etherlink’s features set. These three nodes are being developed as part of the Octez software suite.

Users are likely to interact with the octez-evm-node. The octez-evm-node is responsible for maintaining a local copy of Etherlink context, applying new blocks as they are being minted, and exposing a JSON RPC API compliant endpoint.

Etherlink being a Layer 2 blockchain and a Smart Rollup, it is integrated with the Tezos network. This integration and the interactions that come with it are delegated to a general-purpose node called the Smart Rollup node, which listens and reacts to what is happening on the Tezos network by being connected to an octez-node.

The overall lifecycle of a typical operation is as follows:

  1. One user submits their transaction to an octez-evm-node using the eth_sendRawTransaction.
  2. This transaction is eventually forwarded to Etherlink’s sequencer, which includes it in a new block as soon as possible (less than 500ms after receiving it in a nominal scenario).
  3. The sequencer forwards this new block to the Smart Rollup node it is connected to, which is tasked to post this data on the Tezos network. Besides, the sequencer also makes the new block available to other octez-evm-node it is connected to, which can do the same recursively.
  4. The Smart Rollup nodes tracking the state of Etherlink fetch this new Etherlink block and validate it.
  5. This allows the octez-evm-nodes to assert the block they received previously has indeed be faithfully posted by the sequencer.
  6. Eventually, the Smart Rollup nodes assuming the role of “operators” commit the state of Etherlink to the Tezos network.

We can summarize the connections between each component with this diagram.

Getting the Binaries

As mentioned, the three different nodes involved in Etherlink are being developed as part of the Octez software suite. More precisely,

  • Any octez-node compatible with Tezos Mainnet can be used.
  • The Smart Rollup node (octez-smart-rollup-node) requires Octez V20. To start a Smart Rollup node from Etherlink genesis, a more recent build is necessary.
  • The octez-evm-node is still experimental, and not released as part of the Octez software suite yet.

For the Smart Rollup node required to start Etherlink from genesis and the octez-evm-node, it is recommended to use the commit c5ed8f9 from the master branch of the upstream Octez repository.

If you are concerned by the need to use unreleased version of our nodes, we recommend using the static binaries built by our CI if possible. Builds for Linux systems are available for the x86_64 architecture.

More generally, the procedures described in the Octez manual to get started with Octez apply.

Running a Smart Rollup Node

The scope of this section is to provide the most straightforward instructions to get started with running a Smart Rollup node. As a consequence, only the observer mode is covered (not the operator mode).

Note that, as of today, the octez-evm-node needs to have access to the RPCs of a running Smart Rollup node. As a consequence, you most probably need to go through this section even if you are only interested by running an Etherlink node.

From Genesis

Etherlink remains a blockchain (albeit a Layer 2 one), and it is possible to recompute its most recent state from genesis.

That being said, running a Smart Rollup node for Etherlink Mainnet from genesis requires some manual, specific configuration.

The first step is to initialize the local context of the node (its data-dir). To that end, the init command can be used. We assume the shell variable $sr_observer_data_dir has been set to the path of the expected directory.

octez-smart-rollup-node init observer config for sr1Ghq66tYK9y3r8CC1Tf8i8m5nxh8nTvZEf  \
with operators --data-dir $sr_observer_data_dir

This commands generates a minimal configuration file (config.json) in $sr_observer_data_dir.

{ "smart-rollup-address": "sr1Ghq66tYK9y3r8CC1Tf8i8m5nxh8nTvZEf",
"smart-rollup-node-operator": {}, "fee-parameters": {},
"mode": "observer" }

Etherlink requires the activation of an advanced feature of the Smart Rollup node in order to work properly from genesis. More precisely, it is required to overwrite a constant of the Smart Rollup technology normally defined by the Tezos protocol.

info

This is an advance manipulation, and the naming of the corresponding features in the Smart Rollup node has been choosen accordingly, by prefixing them with unsafe. Similarly to the Rust keyword, unsafe here means to be used with a good understanding of the feature. This is definitely the case for Etherlink and the setup provided in this document is totally safe.

Besides, it can be convenient to set a “preimages endpoint” which allows the Smart Rollup node to retreive the initial kernel of Etherlink from an arbitrary source without any safety risks (since the integrity of said kernel is verified by the Smart Rollup node based on a hash posted onchain during the origination of Etherlink).

{ "smart-rollup-address": "sr1Ghq66tYK9y3r8CC1Tf8i8m5nxh8nTvZEf",
"smart-rollup-node-operator": {}, "fee-parameters": {},
"unsafe-pvm-patches": [
{ "increase_max_nb_tick": "50_000_000_000_000" }
],
"pre-images-endpoint": "https://snapshots.eu.tzinit.org/etherlink-mainnet/wasm_2_0_0",
"mode": "observer" }

With this configuration file, it is now possible to start the Smart Rollup node in observer mode. Note that you will need to be able to access to the RPCs of an Octez node, running in archive mode. For testing purposes, you can rely on public endpoints like the one provided by TzKT for instance.

# for testing purposes
octez-smart-rollup-node --endpoint https://rpc.tzkt.io/mainnet run \
--data-dir $sr_observer_data_dir \
--apply-unsafe-patches

A few remarks.

  • --apply-unsafe-patches is only required the first time you start your node, and can be removed from the command-line afterwards. Similarly, the unsafe-pvm-patches field can be removed from the configuration field.
  • Once the Smart Rollup node has caught up, you can safely connect it to a rolling octez-node.

Once you have the rollup node running, you can confirm that you are able query it; for instance by requesting the latest read tezos block:

curl -s http://localhost:8932/global/block/head

Running octez-evm-node in Observer Mode

From Genesis

In order to run an octez-evm-node in observer mode from Genesis, you need:

  • An access to a Smart Rollup node tracking the state of Etherlink (see the previous section to setup one yourself, which is probably necessary until public nodes become available).
  • The installer.hex file that you can get by following the “Building Etherlink’s Initial Kernel” appendix.
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 \
--initial-kernel observer/installer.hex \
--force

If you do not want to relies on a public preimages endpoint (though it is worth mentioning again it is safe), you can move the wasm_2_0_0/ directory built along the installer.hex file in the directory $evm_observer_dir. Note that this means you will have to provision this directory with the preimages of every kernel voted by the community and deployed on Etherlink after that.

Starting the node is as simple as running this command.

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

By default, the octez-evm-node exposes its JSON RPC API endpoint to localhost:8545. You can test that everything works as expected by running some RPC requests manually or by setting your wallet to use your local node.

Appendix

The kernel of Etherlink is a Rust program compiled in WASM implementing the semantics of Etherlink blocks and transactions. It is used by the octez-evm-node and the Smart Rollup nodes to validate the blocks created by Etherlink’s sequencer.

We are maintaining a file server (a so-called “preimages endpoint”) which makes it optional to build Etherlink’s kernels yourself without sacrificing security. There is one exception, though: if you want to start an octez-evm-node from genesis, without having to trust third-parties artifacts. In that case, you need to follow this step.

Our build process rely on a Docker image to ensure reproducible builds. This means that, as long as you have a working local Docker setup, building the kernel to a WASM binary is as simple as executing the following command from the root of the repository.

./etherlink/scripts/build-wasm.sh

This will create the file etherlink/kernels-<CURRENT COMMIT>/evm_kernel.wasm.

We have used the kernel built from commit b9f6c91.

Etherlink kernel largely exceeds the 32KBytes limit of Tezos manager operations. To overcome this limitation and still be able to deploy Etherlink, we rely on a tool called the smart-rollup-installer program from the Smart Rollups Rust SDK.

This time, the necessary build rules are defined in the kernels.mk Makefile.

make -f kernels.mk build-deps kernel_sdk

The smart-rollup-installer allows to initialize the context of a Smart Rollup (in our case, Etherlink) with an initial kernel and an initial state. The latter is specified using a yaml file which can be generated with the octez-evm-node. We use this state to define several parameters of Etherlink, including its chain ID, the various governance and bridge contracts, etc.

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

To generate the files required to run Etherlink from genesis, you can finally call smart-rollup-installer.

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 this invocation are a file called installer.hex (necessary for running an octez-evm-node from genesis) and the wasm_2_0_0/ directory (which can be used instead of relying on a public preimages endpoint).

The content of installer.hex as built from the “Building Etherlink’s Initial Kernel” section is the following.

141036a2c000041bf7f4a6a21022003200941046a2209470d000b0b2008450d00200020096a21010340200220012c000041bf7f4a6a2102200141016a21012008417f6a22080d000b0b20020b4a01017f0240024002402002418080c400460d0041012105200020022001280210118180808000000d010b20030d01410021050b20050f0b200020032004200128020c118080808000000b930201027f23808080800041106b2202248080808000200220003602002002200128021441f490c080004111200141186a28020028020c118080808000003a000c20022001360208200241003a000d20024100360204200241046a200241e490c0800010b680808000210120022d000c210002400240200128020022030d00200041ff017141004721010c010b41012101200041ff01710d0020022802082100024020034101470d0020022d000d41ff0171450d0020002d001c4104710d0041012101200028021441d78dc080004101200041186a28020028020c118080808000000d010b200028021441dc8cc080004101200041186a28020028020c1180808080000021010b200241106a24808080800020010be90203027f017e037f23808080800041306b2203248080808000412721040240024020004290ce005a0d00200021050c010b412721040340200341096a20046a2206417c6a200020004290ce008022054290ce007e7da7220741ffff037141e4006e220841017441d88dc080006a2f00003b00002006417e6a2007200841e4006c6b41ffff037141017441d88dc080006a2f00003b00002004417c6a2104200042ffc1d72f5621062005210020060d000b0b02402005a7220641e3004d0d00200341096a2004417e6a22046a2005a72206200641ffff037141e4006e220641e4006c6b41ffff037141017441d88dc080006a2f00003b00000b024002402006410a490d00200341096a2004417e6a22046a200641017441d88dc080006a2f00003b00000c010b200341096a2004417f6a22046a200641306a3a00000b2002200141dc8cc080004100200341096a20046a412720046b10af808080002104200341306a24808080800020040b1200200141c88fc08000410210aa808080000bb50101037f024002402002410f4b0d00200021030c010b2000410020006b41037122046a210502402004450d00200021030340200320013a0000200341016a22032005490d000b0b2005200220046b2204417c7122026a2103024020024101480d00200141ff017141818284086c2102034020052002360200200541046a22052003490d000b0b200441037121020b02402002450d00200320026a21050340200320013a0000200341016a22032005490d000b0b20000b0e0020002001200210c1808080000b0b8f110100418080c0000b851144414320707265696d616765207472656520636f6e7461696e7320746f6f206d616e79206c6576656c732e4661696c656420746f20726574726965766520707265696d616765556e61626c6520746f206465636f64652044414320706167653a204465636f646520696e746f20536c69636550616765206661696c65642f686f6d652f6c74686d732f776f726b2f74657a6f732f7372632f6b65726e656c5f73646b2f656e636f64696e672f7372632f6461632f70616765732e72737d0010003f0000003e0100001f00000047756172616e7465656420746f2062652065786163742e00010000000000000001000000020000007d0010003f0000001f0100002b000000496e636f6d706c657465642070617273696e67436f756c646e277420726561642066726f6d206b65726e656c20626f6f742070617468436f756c646e277420736574206b657920647572696e6720636f6e666967206170706c69636174696f6e496e76616c6964206861736820636f6e76657273696f6e2e436f756c646e2774206d6f7665207061746820647572696e6720636f6e666967206170706c69636174696f6e4661696c656420746f207772697465206b65726e656c20636f6e74656e742070616765617373657274696f6e206661696c65643a206d6964203c3d2073656c662e6c656e28292f6b65726e656c2f656e762f7265626f6f74ee0110001200000000696e7374616c6c65722d6b65726e656c2f7372632f696e7374722e72730000090210001d000000250000001d0000004661696c656420746f2072656164206b65726e656c20626f6f74207061746820696e20726561645f696e737472756374696f6e2f6b65726e656c2f626f6f742e7761736d6578706c696369742070616e6963696e7374616c6c65722d6b65726e656c2f7372632f6c69622e72730000008a0210001b0000003c000000050000002f5f5f696e7374616c6c65725f6b65726e656c2f617578696c696172792f6b65726e656c2f626f6f742e7761736d0000b80210002e0000008a0210001b000000680000002f0000004661696c656420746f20726561642073697a65206f6620636f6e6669672070726f6772616d4661696c656420746f2072656164206b65726e656c20626f6f7420706174682073697a654661696c656420746f20636f7079206b65726e656c20626f6f74206265666f726520636f6e66696720657865637574696f6e436f756c646e2774206465636f646520636f6e66696720696e737472756374696f6e4661696c656420746f2064656c65746520617578696c69617279206b65726e656c20626f6f7420616674657220636f6e66696720657865637574696f6e656e636f64696e672f7372632f6461632f70616765732e727300da03100019000000020100001a000000da03100019000000310100001a00000050617468206d75737420636f6e7461696e206174206c65617374206f6e6520656d70747920737465700000001404100029000000686f73742f7372632f706174682e72734804100010000000c0000000260000005061746820636f6e7461696e656420746f6f206d616e79206279746573000000680410001d0000004804100010000000c10000002800000050617468206d75737420626567696e20776974682061207061746820736570617261746f72000000a0041000250000004804100010000000c20000002900000050617468207374657073206d757374206265206e6f6e20656d707479e00410001c0000004804100010000000c30000002d000000506174682073746570206279746573206d7573742062652061736369695f616c7068616e756d65726963206f720a2020202020202020202020206f6e65206f662074686520666f6c6c6f77696e672073796d626f6c73202262272e2722202c202262275f2722202c202262272d272200140510006f0000004804100010000000c50000000d00000050617468206d757374206e6f74207374617274206279202f726561646f6e6c792c207468697320697320612072657365727665640a2020202020202020202020202020202070617274206f66207468652073746f726167652e20557365732074686520617070726f7072696174652066756e6374696f6e20746f0a202020202020202020202020202020206c6f6f6b2076616c75657320696e20746869732073746f726167652e009c051000a70000004804100010000000cb0000000d00000029696e76616c696420617267730000005d0610000c0000006c6962726172792f636f72652f7372632f666d742f6d6f642e727300070000000000000001000000080000003a2000005c06100000000000a006100002000000090000000c000000040000000a0000000b0000000c000000202020202c202c0a28280a2c30303031303230333034303530363037303830393130313131323133313431353136313731383139323032313232323332343235323632373238323933303331333233333334333533363337333833393430343134323433343434353436343734383439353035313532353335343535353635373538353936303631363236333634363536363637363836393730373137323733373437353736373737383739383038313832383338343835383638373838383939303931393239333934393539363937393839390900000004000000040000000d0000000e0000000f000000740610001b000000350100000d000000282972616e676520737461727420696e64657820206f7574206f662072616e676520666f7220736c696365206f66206c656e677468200000ca07100012000000dc0710002200000072616e676520656e6420696e646578201008100010000000dc07100022000000736c69636520696e64657820737461727473206174202062757420656e647320617420003008100016000000460810000d0000000900000004000000040000001000000054727946726f6d536c6963654572726f7200c00506636f6e6669674200000000210000000021b5a05595104efcbf3d86346ce900040111959087ab4e5a2d222a614dc175ad1b2f696e7374616c6c65722f6b65726e656c2f626f6f742e7761736d2f000000011b2f696e7374616c6c65722f6b65726e656c2f626f6f742e7761736d112f6b65726e656c2f626f6f742e7761736d1b0000000200000000152f65766d2f72656d6f76655f77686974656c697374350000000214000000cf02b9ca488f8f6f4e28e37aa1bdd16b3f1b2ad81b2f65766d2f73657175656e6365725f706f6f6c5f616464726573732b000000020800000040060000000000001d2f65766d2f64656c617965645f696e626f785f6d696e5f6c6576656c73460000000021000000002fc186f3280bfbe53f5046c614c4ece58868f4aacb47be23ae738cce405287c01f2f65766d2f6b65726e656c5f73656375726974795f676f7665726e616e63653d0000000021000000009e144e38f6b681a67cd33aa5273f18954b00f2825b223a3f33ad2b226c58e94e162f65766d2f6b65726e656c5f676f7665726e616e6365400000000021000000009c3403446b48dccf087e1ebcb64770d182b626e4334bf5baf2a55336b110b6b5192f65766d2f73657175656e6365725f676f7665726e616e6365340000000021000000003639f26fa720c14e819be337bef19bf2aaac66cb433bb2653274a0d82019df190d2f65766d2f7469636b657465723a0000000021000000000afa4dd727fd64b51a62c1bad94202a108309b1f0661858dbedb73f7508a8c54132f65766d2f64656c617965645f62726964676535000000002100000000b31626f7ff1a2fa8d70ab1c877cf880c8fa23fe40b13b550f32dffa47a15f4800e2f65766d2f73657175656e63657233000000022000000029a70000000000000000000000000000000000000000000000000000000000000d2f65766d2f636861696e5f6964b5020000

Do take into account that, as of today, the octez-evm-node (which requires this file to initialize its initial state when run from genesis) does not make any safety check. As a consequence, you might want to recompute it yourself.