Skip to content

Commit

Permalink
Document starting with an observer node and moving to a maintenance n…
Browse files Browse the repository at this point in the history 
…ode (#163)

* Rework to start in observer and move to operator

* Per discussion, use maintenance mode

* Snapshot  time

* Use my node before moving to maintenance mode
  • Loading branch information
@timothymcmackin
timothymcmackin authored Sep 4, 2024
1 parent 8937329 commit 7fd7fc5
Showing 1 changed file with 87 additions and 96 deletions.
183 changes: 87 additions & 96 deletions docs/network/smart-rollup-nodes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,42 +12,32 @@ The data for the original kernel is stored in separate files called _preimages_.

You can run the Smart Rollup node starting from Etherlink genesis or from a snapshot of a recent Etherlink state.

## References

Make sure that you understand the interaction between different nodes as described in [Etherlink architecture](/network/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.
## Modes

You can run the Etherlink Smart Rollup in many modes, but these instructions cover only the most common modes:

- [Running the Smart Rollup node in operator mode](#running-the-smart-rollup-node-in-operator-mode)
- [Running the Smart Rollup node in observer mode](#running-the-smart-rollup-node-in-observer-mode)

## Running the Smart Rollup node in operator mode

Running the Smart Rollup node in operator mode is the best way to participate in Etherlink because in this mode the node posts commitments about Etherlink's state to layer 1.
Running the Smart Rollup node in operator or maintenance mode is the best way to participate in Etherlink because in these modes the node posts commitments about Etherlink's state to layer 1.
These commitments validate Etherlink's state and ensure that Etherlink is processing blocks and transactions honestly according to its kernel.
As described in [Smart Rollups](https://docs.tezos.com/architecture/smart-rollups) on docs.tezos.com, one honest node is enough to ensure that Etherlink is running correctly, but adding more nodes strengthens its security and allows users to verify for themselves that Etherlink is running as intended.

Running the node in this mode requires these prerequisites:
The best way to run a node that can post commitments is to start with a node in observer mode, verify that it works, and convert it to maintenance mode.
Maintenance mode is similar to operator mode but it does not require settings for batching operations, which are required only for sequencer nodes.

- A Tezos layer 1 node running in archive mode.
For more information on modes, see [Smart Rollup node](https://tezos.gitlab.io/shell/smart_rollup_node.html) in the Octez documentation.

To bootstrap a Smart Rollup node from a snapshot, you need a node that has the full history from the time the snapshot was taken to the current level.
Usually this means connecting to an archive node, but if the snapshot is recent, it can work with a rolling node that keeps enough history.
After the node has started, you can switch to a rolling node.
## References

:::warning Using public nodes
Make sure that you understand the interaction between different nodes as described in [Etherlink architecture](/network/architecture).

You can bootstrap the Smart Rollup node by connecting it to a public layer 1 node, but after the Smart Rollup node bootstraps, you must connect it to a layer 1 node that you control.
Using a public layer 1 node as the basis for a Smart Rollup node in operator mode exposes the Smart Rollup node to security risks.
For example, a malicious layer 1 node can expose the Smart Rollup to an incorrect branch, which can cause the Smart Rollup node to post invalid commitments and lose tez when other operators computing from the correct branch refute them.
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.

:::
## Starting the Smart Rollup node in observer mode

You can start the Smart Rollup node in observer mode to bootstrap it and make sure that it works before you change to maintenance mode.

- An account with at least liquid (unstaked) 10,000 tez, referred to as the _operator account_.
You can use the same account that you use for your layer 1 baker, but for better security, you can use a different account and delegate its tez to the layer 1 account.
- A clean data directory that has not been used for another Smart Rollup node or a node running in a different mode.
To bootstrap a Smart Rollup node from a snapshot, you need a node that has the full history from the time the snapshot was taken to the current level.
Usually this means connecting to an archive node, but if the snapshot is recent, it can work with a rolling node that keeps enough history.
After the node has started, you can switch to a rolling node.

Follow these steps to start the 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.
Expand All @@ -57,138 +47,139 @@ The best place to get the most recent binary files to use with Etherlink is http
1. Set the environment variable `SR_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 and using the address of the Etherlink Smart Rollup, which you can get from the [Network information](/get-started/network-information) page, and the address or Octez client alias for the operator account:
1. Initialize the local context by running this command and passing the address of the Etherlink Smart Rollup and the preimages endpoint.
You can get this information on the [Network information](/get-started/network-information) page.

For example, this command initializes the context for Etherlink Mainnet:

```bash
octez-smart-rollup-node init operator config for sr1Ghq66tYK9y3r8CC1Tf8i8m5nxh8nTvZEf \
with operators \
operating:$OPERATOR_ACCOUNT \
cementing:$OPERATOR_ACCOUNT \
executing_outbox:$OPERATOR_ACCOUNT \
--history-mode archive \
--rpc-addr 0.0.0.0 \
--data-dir $SR_DATA_DIR \
octez-smart-rollup-node init observer config for sr1Ghq66tYK9y3r8CC1Tf8i8m5nxh8nTvZEf \
with operators --data-dir $SR_DATA_DIR \
--pre-images-endpoint https://snapshots.eu.tzinit.org/etherlink-mainnet/wasm_2_0_0
```

This command generates a configuration file (`config.json`) in the local data folder:
For Etherlink testnet, use this command:

```bash
octez-smart-rollup-node init observer config for sr18wx6ezkeRjt1SZSeZ2UQzQN3Uc3YLMLqg \
with operators --data-dir $SR_DATA_DIR \
--pre-images-endpoint https://snapshots.eu.tzinit.org/etherlink-ghostnet/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":
{ "operating": "tz1QCVQinE8iVj1H2fckqx6oiM85CNJSK9Sx",
"cementing": "tz1QCVQinE8iVj1H2fckqx6oiM85CNJSK9Sx",
"executing_outbox": "tz1QCVQinE8iVj1H2fckqx6oiM85CNJSK9Sx" },
"fee-parameters": {}, "mode": "operator",
"smart-rollup-node-operator": {}, "fee-parameters": {}, "mode": "observer",
"pre-images-endpoint":
"https://snapshots.eu.tzinit.org/etherlink-ghostnet/wasm_2_0_0" }
"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".
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](/network/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. To speed up the setup process by loading a snapshot, follow these steps.
If you don't load a snapshot, the node must compute the current state from genesis and that can take a long time.
1. To speed up the setup process by loading a snapshot, follow these steps:
1. Download the latest snapshot.
Mainnet snapshots are available at https://snapshots.eu.tzinit.org/etherlink-mainnet and Testnet snapshots are available at https://snapshots.eu.tzinit.org/etherlink-ghostnet.
1. Download the latest snapshot from https://snapshots.eu.tzinit.org/etherlink-mainnet/:
For example, this command downloads the latest snapshot for Etherlink mainnet:
```bash
wget https://snapshots.eu.tzinit.org/etherlink-mainnet/eth-mainnet.full
```
1. Load the snapshot:
1. Load the snapshot by running the `snapshot import` command:
```bash
octez-smart-rollup-node \
octez-smart-rollup-node --endpoint https://rpc.tzkt.io/mainnet \
snapshot import eth-mainnet.full \
--data-dir $SR_DATA_DIR
```
1. Start the Smart Rollup node by running this command and using the RPC endpoint of the layer 1 node:
1. Start the Smart Rollup node in observer mode with the `run` command:
```bash
octez-smart-rollup-node --endpoint $LAYER_1_NODE run --data-dir $SR_DATA_DIR
octez-smart-rollup-node --endpoint https://rpc.tzkt.io/mainnet run \
--data-dir $SR_DATA_DIR
```
If you did not load a snapshot, the process of starting the node from genesis can take a long time because it must process every block.
If you loaded a snapshot, the node must process every block that has been created since the snapshot was taken, which takes time depending on the age of the snapshot.
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
```
1. Ensure that the node runs persistently.
Look up how to run programs persistently in the documentation for your operating system.
Now the Smart Rollup node is running and tracking the state of Etherlink by receiving information from layer 1.
1. If you started the node with a public layer 1 node, stop it and restart it with a layer 1 node that you control.
## Converting the Smart Rollup node to maintenance mode
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).
Converting the observer node to maintenance mode requires these prerequisites:
## Running the Smart Rollup node in observer mode
- Your own Tezos layer 1 node running in any mode.
Running the Smart Rollup node in observer mode is the simplest way to run an Etherlink Smart Rollup node, but it does not strengthen the security of the system by posting commitments.
In observer mode, the node only monitors the state of Etherlink.
:::warning Use a private layer 1 node
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.
To run the Smart Rollup node in a mode that posts commitments, including maintenance mode and operator mode, you must connect it to a layer 1 node that you control.
Using a public layer 1 node as the basis for a Smart Rollup node in maintenance or operator mode exposes the Smart Rollup node to security risks.
For example, a malicious layer 1 node can expose the Smart Rollup node to an incorrect branch, which can cause the Smart Rollup node to post invalid commitments and lose tez when other node operators computing from the correct branch refute them.
1. Initialize the local context of the node, which is where it stores local data:
1. Set the environment variable `SR_DATA_DIR` to the directory where the node should store its local data.
The default value is `$HOME/.tezos-smart-rollup-node`.
As these steps describe, it is safe to bootstrap a node in observer mode by connecting it to a public node, switch to maintenance or operator mode, and then promptly connect it to a layer 1 node that you control.
1. Initialize the local context by running this command and using the address of the Etherlink Smart Rollup, which you can get from the [Network information](/get-started/network-information) page:
:::
```bash
octez-smart-rollup-node init observer config for sr1Ghq66tYK9y3r8CC1Tf8i8m5nxh8nTvZEf \
with operators --data-dir $SR_DATA_DIR \
--pre-images-endpoint https://snapshots.eu.tzinit.org/etherlink-mainnet/wasm_2_0_0
```
- An account with at least 10,000 liquid (unstaked) tez, referred to as the _operator account_.
You can use the same account that you use for a layer 1 baker, but for better security, you can use a different account and delegate its tez to the layer 1 account.
This command generates a minimal configuration file (`config.json`) in the local data folder:
- An account with a small amount of liquid tez for cementing and outbox operations.
```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" }
```
Follow these steps to convert a Smart Rollup node from observer mode to maintenance mode:
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](/network/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. Set up the two accounts in the Octez client.
1. To speed up the setup process by loading a snapshot, follow these steps:
1. Stop the Smart Rollup node.
1. Download the latest snapshot from https://snapshots.eu.tzinit.org/etherlink-mainnet/:
1. Restart the node with the layer 1 node that you control, represented in this example by the variable `$MY_LAYER_1_NODE`:
```bash
wget https://snapshots.eu.tzinit.org/etherlink-mainnet/eth-mainnet.full
```
```bash
octez-smart-rollup-node --endpoint $MY_LAYER_1_NODE run \
--data-dir $SR_DATA_DIR
```
1. Load the snapshot:
1. Verify that the node continues to run as expected in observer mode.
```bash
octez-smart-rollup-node --endpoint https://rpc.tzkt.io/mainnet \
snapshot import eth-mainnet.full \
--data-dir $SR_DATA_DIR
```
1. Stop the node.
1. Start the Smart Rollup node in observer mode by running this command and using the RPC endpoint of a layer 1 node:
1. Re-initialize the node for maintenance mode by running the `init maintenance config` command and passing the addresses or Octez aliases of the accounts.
This example uses `$OPERATOR_ACCOUNT` for the account with 10,000 liquid tez and `$SECONDARY_ACCOUNT` for the other account:
```bash
octez-smart-rollup-node --endpoint https://rpc.tzkt.io/mainnet run \
--data-dir $SR_DATA_DIR
octez-smart-rollup-node init maintenance config for sr1Ghq66tYK9y3r8CC1Tf8i8m5nxh8nTvZEf \
with operators \
operating:$OPERATOR_ACCOUNT \
cementing:$SECONDARY_ACCOUNT \
executing_outbox:$SECONDARY_ACCOUNT \
--history-mode archive \
--rpc-addr 0.0.0.0 \
--data-dir $SR_DATA_DIR \
--pre-images-endpoint https://snapshots.eu.tzinit.org/etherlink-mainnet/wasm_2_0_0
```
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.
This command generates updates the configuration file to contain the addresses of the accounts that post operations to layer 1, including the node's commitments.
If you did not load a snapshot, the process of starting the node from genesis can take a long time because it must process every block.
1. Restart the node, again with the layer 1 node that you control:
```bash
octez-smart-rollup-node --endpoint $MY_LAYER_1_NODE run \
--data-dir $SR_DATA_DIR
```
1. Verify that the Smart Rollup node is running by querying it.
For example, this query gets the health of the node:
Expand All @@ -197,4 +188,4 @@ For example, this query gets the health of the node:
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).
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](/network/evm-nodes).

0 comments on commit 7fd7fc5

Please sign in to comment.