Skip to content

Commit

Permalink
Address feedback
Browse files Browse the repository at this point in the history
  • Loading branch information
@TucksonDev
TucksonDev committed Dec 12, 2024
1 parent b795286 commit 1cd6e7b
Show file tree
Hide file tree
Showing 2 changed files with 27 additions and 23 deletions.
44 changes: 23 additions & 21 deletions arbitrum-docs/run-arbitrum-node/more-types/02-run-validator-node.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,17 @@
---
title: 'How to run a validator'
description: Learn how to run an Arbitrum validator node
author: TucksonDev
sme: TucksonDev
sidebar_position: 4
content_type: how-to
---

Validators are nodes that choose to participate in the rollup protocol to advance the state of the chain securely. Since the activation of <a data-quicklook-from="bold">BoLD</a>, chains can now choose to make validation permissionless. You can learn more about BoLD [here](/how-arbitrum-works/bold/gentle-introduction.mdx).
Validators are nodes that choose to participate in the rollup protocol to advance the state of the chain securely. Since the activation of <a data-quicklook-from="bold">BoLD</a>, chains can now choose to make validation permissionless. You can learn more in the [BoLD introduction](/how-arbitrum-works/bold/gentle-introduction.mdx).

This page describes the different strategies that a validator may follow, and provides instructions to run a validator for an Arbitrum chain.
This page describes the different strategies a validator may follow and provides instructions on how to run a validator for an Arbitrum chain.

This how-to assumes that you're familiar with:
This how-to assumes that you're familiar with the following:

- How to run a full node (see instructions [here](/run-arbitrum-node/03-run-full-node.mdx) for DAO-governed chains, and [here](/node-running/how-tos/running-an-orbit-node.mdx) for Orbit chains)
- [How the Rollup protocol works](/how-arbitrum-works/inside-arbitrum-nitro.mdx#arbitrum-rollup-protocol)
Expand All @@ -19,16 +21,16 @@ This how-to assumes that you're familiar with:

Validators can be configured to follow a specific validation strategy. Here we describe what strategies are available in Nitro:

| Strategy | Description | Gas usage |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **`Defensive`** | If the local state disagrees with the on-chain assertion, this validator will post a stake and create a challenge | Only acts if a bad assertions is found |
| **`StakeLatest`** | This validator will stay staked on the latest assertion found, and will challenge any bad assertions that it finds (this strategy is only available in pre-BoLD chains) | Gas used every time a new assertion is created |
| **`ResolveNodes`** | This validator will stay staked on the latest assertion found, resolve any unconfirmed assertions, and it will challenge any bad assertions that it finds | Gas used every time a new assertion is created, and to resolve unconfirmed assertions |
| **`MakeNodes`** | This validator continuously creates new assertions, resolves any unconfirmed assertions, and challenges bad assertions found. Note that if there is more than one `MakeNodes` validator running, they might all try to create a new assertion at same time. In that case, only one will be successful, while the others will have their transactions reverted | Gas used to create new assertions, move the stake to the latest one, and resolve unconfirmed assertions |
| Strategy | Description | Gas usage |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **`Defensive`** | If the local state disagrees with the on-chain assertion, this validator will post a stake and create a challenge | Only acts if a bad assertions is found |
| **`StakeLatest`** | This validator will stay staked on the latest assertion found, and will challenge any bad assertions that it finds (this strategy is only available in pre-BoLD chains) | Gas used every time a new assertion is created |
| **`ResolveNodes`** | This validator will stay staked on the latest assertion found, resolve any unconfirmed assertions, and it will challenge any bad assertions that it finds | Gas used every time a new assertion is created and to resolve unconfirmed assertions |
| **`MakeNodes`** | This validator continuously creates new assertions, resolves any unconfirmed assertions, and challenges bad assertions found. Note that if there is more than one `MakeNodes` validator running, they might all try to create a new assertion simultaneously. In that case, only one will be successful, while the others will have their transactions reverted | Gas used to create new assertions, move the stake to the latest one, and resolve unconfirmed assertions |

### The watchtower strategy

There's one more validation strategy that is available for all types of node: `watchtower`. This strategy is enabled by default in all nodes (full and archive) and it doesn't require a wallet, as it never takes any action on-chain.
One more validation strategy is available for all types of nodes: `watchtower`. This strategy is enabled by default in all nodes (full and archive), and it doesn't require a wallet, as it never takes any action on-chain.

A node in `watchtower` mode will immediately log an error if an on-chain assertion deviates from the locally computed chain state.

Expand All @@ -47,20 +49,20 @@ Additionally, the following logs indicate whether all components are working cor
- The log line `validation succeeded` shows that the node is validating chain blocks successfully
- The log line `found correct assertion` shows that the node is finding assertions on the parent chain successfully

Watchtower mode adds a small amount of execution and memory overhead to your node. You can deactivate this mode by using the parameter `--node.staker.enable=false`.
Watchtower mode adds a small amount of execution and memory overhead to your node. You can deactivate this mode using the parameter `--node.staker.enable=false`.

## How to run a validator node

This section explains how to configure your node to act as a validator.

### Step 0: prerequisites

A validator node is basically a regular full node with validation enabled, so you'll have to know how to configure a full node. You can find instructions [here](/run-arbitrum-node/03-run-full-node.mdx) for DAO-governed chains, and [here](/node-running/how-tos/running-an-orbit-node.mdx) for Orbit chains.
A validator node is a regular full node with validation enabled, so you'll have to know how to configure a full node. You can find instructions [here](/run-arbitrum-node/03-run-full-node.mdx) for DAO-governed chains, and [here](/node-running/how-tos/running-an-orbit-node.mdx) for Orbit chains.

Additionally, you'll need a wallet with enough funds to perform actions on-chain, and enough tokens to stake. Keep in mind that:
Additionally, you'll need a wallet with enough funds to perform actions on-chain and enough tokens to stake. Keep in mind that:

- The token used to perform actions on-chain is the native token of the parent chain (usually `ETH`)
- For chains that have BoLD activated, the token used to stake depends on the configuration of the chain. For Arbitrum One and Arbitrum Nova, the stake token is `WETH`
- For chains with BoLD activated, the token used to stake depends on the chain configuration. For Arbitrum One and Arbitrum Nova, the staking token is `WETH`
- For chains that don't have BoLD activated, the token used to stake is the native token of the parent chain (usually `ETH`)

### Step 1: configure and run your validator
Expand Down Expand Up @@ -90,7 +92,7 @@ To verify that your node is acting as a validator, you can look for the followin
INFO [09-28|18:43:49.367] running as validator txSender=0x... actingAsWallet=0x... whitelisted=true strategy=Defensive
```

Note that `strategy` should be the strategy configured, and `txSender` and `actingAsWallet` should both be present and not `nil`.
Note that `strategy` should be the configured strategy. `txSender` and `actingAsWallet` should both be present and not `nil`.

Furthermore, the following logs will indicate that all components are working as intended:

Expand All @@ -99,19 +101,19 @@ Furthermore, the following logs will indicate that all components are working as

## Run a validator for an Orbit chain

Validation for Orbit chains works the same way as for DAO-governed Arbitrum chains. However, as specified in [How to run a node](/node-running/how-tos/running-an-orbit-node.mdx#2-child-chain-parameters), you need to include the information of the chain when configuring your node, by using `--chain.info-json`.
Validation for Orbit chains works the same way as for DAO-governed Arbitrum chains. However, as specified in [How to run a node](/node-running/how-tos/running-an-orbit-node.mdx#2-child-chain-parameters), you need to include the information of the chain when configuring your node by using `--chain.info-json`.

```shell
--chain.info-json=<Orbit chain's info>
```
Additionally, keep in mind that some chains might not have BoLD activated yet, so BoLD specific parameters will not be needed.
Additionally, keep in mind that some chains might not have BoLD activated yet, so BoLD-specific parameters will not be needed.
## Advanced features
### Use Nitro to create a wallet for your validator
Nitro includes a tool to automatically create a validator wallet for a specific chain. You can access it by using the option `--node.staker.parent-chain-wallet.only-create-key`, and setting a password for the wallet with `--node.staker.parent-chain-wallet.password`.
Nitro includes a tool to create a validator wallet for a specific chain automatically. You can access it by using the option `--node.staker.parent-chain-wallet.only-create-key` and setting a password for the wallet with `--node.staker.parent-chain-wallet.password`.
Here is an example of how to create a validator wallet for Arbitrum One and exit:
Expand All @@ -125,7 +127,7 @@ Once the wallet is created, you can instruct your validator to use it by adding
### Enable the BoLD API
When activating BoLD on a chain, the amount of logs produced by a validator in case a challenge occurs can be overwhelming, and it might be hard to follow the progress of a challenge. To allow for a better visualization of ongoing challenges, as well as querying specific information, Nitro includes an API to capture information about assertions and challenges that the validator observes. You can enable this API by using the following parameters:
When activating BoLD on a chain, the amount of logs produced by a validator in case a challenge occurs can be overwhelming, and it might be hard to follow the progress of a challenge. To allow for better visualization of ongoing challenges, as well as querying specific information, Nitro includes an API to capture information about assertions and challenges that the validator observes. You can enable this API by using the following parameters:
| Parameter | Value | Description |
| ---------------------- | ----- | --------------------------------------- |
Expand All @@ -137,9 +139,9 @@ You can find specific documentation about the methods available on this API in [
### How to add new validators to the allowlist (Orbit chains)
On permissioned validation setups, the set of validators that can act on a given chain are limited to the ones added to the allowlist of validators in the Rollup contract.
On permissioned validation setups, the set of validators that can act on a given chain is limited to the ones added to the allowlist of validators in the Rollup contract.
Follow these instructions to add a new validator address to the allowlist. Keep in mind that you need to be able to perform admin actions to the chain to complete this operation.
Follow these instructions to add a new validator address to the allowlist. Remember that you need to be able to perform admin actions to the chain to complete this operation.
1. Find your `upgradeExecutor` contract address
2. Call the `executeCall` method of the `upgradeExecutor` contract:
Expand Down
6 changes: 4 additions & 2 deletions arbitrum-docs/run-arbitrum-node/more-types/04-bold-validator-api.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,18 @@
---
title: 'BoLD validator API'
description: Describes the API available on BoLD validator nodes
author: TucksonDev
sme: TucksonDev
content_type: concept
---

When <a data-quicklook-from="bold">BoLD</a> is activated, validators have access to an optional API that Nitro provides, which provides information about the assertions being posted and the current challenges going on.

This page describes the rationale behind providing this API, and the different endpoints that are available.
This page describes the rationale behind providing this API and the available endpoints.

## Why do we need an API?

BoLD is a complex protocol that enables validators to defend claims about an Arbitrum chain on its parent chain. By default, uncontested claims are confirmed within 7 days, and contested claims can be confirmed within 14 days. Within that sliding window, there can be a significant amount of challenges and activities of validators making moves to defend their claims. Nitro is equipped to automatically make moves on behalf of honest validators, and logs a lot of information about ongoing challenges.
BoLD is a complex protocol that enables validators to defend claims about an Arbitrum chain on its parent chain. By default, uncontested claims are confirmed within 7 days, and contested claims can be confirmed within 14 days. Within that sliding window, there can be a significant amount of challenges and activities of validators making moves to defend their claims. Nitro is equipped to make moves on behalf of honest validators automatically and logs a lot of information about ongoing challenges.

However, the amount of information logged between a simple Alice vs. Bob dispute is enormous. Each move made in a challenge emits a log, and there are many other things occurring in a validator node's runtime that are also logged in the process. Because BoLD challenges can be concurrent, we can quickly see an explosion of logs if many participants are involved.

Expand Down

0 comments on commit 1cd6e7b

Please sign in to comment.