diff --git a/arbitrum-docs/run-arbitrum-node/more-types/02-run-validator-node.mdx b/arbitrum-docs/run-arbitrum-node/more-types/02-run-validator-node.mdx index d709ae78f..c22e2b051 100644 --- a/arbitrum-docs/run-arbitrum-node/more-types/02-run-validator-node.mdx +++ b/arbitrum-docs/run-arbitrum-node/more-types/02-run-validator-node.mdx @@ -1,76 +1,152 @@ --- title: 'How to run a validator' -description: Learn how to run an Arbitrum feed relay on your local machine. +description: Learn how to run an Arbitrum validator node +author: TucksonDev +sme: TucksonDev sidebar_position: 4 content_type: how-to --- -Some Arbitrum nodes will choose to act as validators. This means that they watch the progress of the rollup protocol and perhaps also participate in that protocol to advance the state of the chain securely. -Not all nodes will choose to do this. Because the rollup protocol doesn’t decide what the chain will do but merely confirms the correct behavior that is fully determined by the inbox messages, a node can ignore the rollup protocol and simply compute for itself the correct behavior. -Here we describe different strategies that validators follow and provide instructions on how to run them. - -### Validation strategies - -- Currently, the ability to post assertions on-chain for mainnet Arbitrum chains is allowlisted. -- Here's a full list of validation strategies: - - `Defensive` (allowlist required) - - Post stake and create challenge if local state disagrees with on-chain assertion (wallet required, will only post stake on-chain if bad assertion found) - - `StakeLatest` (allowlist required) - - Stay staked on latest assertion and challenge any bad assertions found (wallet required, always staked, uses some gas every time new assertion created) - - `ResolveNodes` (allowlist required) - - Stay staked on latest assertion, resolve any unconfirmed assertions and challenge any bad assertions found (wallet required, always staked, uses some gas every time unconfirmed assertion resolved or new assertion created) - - `MakeNodes` (allowlist required) - - Continuously create new assertions, challenging any bad assertions found (wallet required, always staked, most expensive node to run) - - 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, and the others will have still spent gas on reverted calls that didn't do anything. -- There's one more validation strategy that is not allowlisted and is available for all types of node: `Watchtower`. A node in `Watchtower` mode will immediately log an error if an on-chain assertion deviates from the locally computed chain state. It doesn't require a wallet, as it never takes any action on-chain. This strategy is enabled by default in all nodes (full and archive). - -### Running a Watchtower validator - -- By default, all nodes (full and archive) will run in `Watchtower` mode. -- If a deviation is detected, a node running in Watchtower mode will log an error containing the string `found incorrect assertion in watchtower mode` -- To verify that the Watchtower mode is enabled, this line should appear in the logs: - ```shell - INFO [09-28|18:43:49.367] running as validator txSender=nil actingAsWallet=nil whitelisted=false strategy=Watchtower - ``` - - `strategy` should be `Watchtower` - - The log line `validation succeeded` shows that the L2 block validator is working - - The log line `found correct assertion` shows that the L1 validator is working -- Watchtower mode adds a small amount of execution and memory overhead. You can deactivate this mode by using the parameter `--node.staker.enable=false`. - -### Creating a wallet for an allowlisted validator - -- Watchtower validators never need a wallet, because they never post on-chain -- Defensive validators need a wallet configured, but the wallet does not need to be funded until it logs that an assertion has been found -- All other validators require a funded wallet to immediately post stake, as well as additional funds that will be spent at regular intervals -- Here is an example of how to tell Nitro to create validator wallet for Arbitrum One and exit: - ```shell - docker run --rm -it -v /some/local/dir/arbitrum:/home/user/.arbitrum @latestNitroNodeImage@ --parent-chain.connection.url=https://l1-mainnet-node:8545 --chain.id=42161 --node.staker.enable --node.staker.parent-chain-wallet.only-create-key --node.staker.parent-chain-wallet.password="SOME SECURE PASSWORD" - ``` -- Wallet file will be created under the mounted directory inside the `arb1/wallet/` directory for Arb1, or `nova/wallet/` directory for Nova. Be sure to backup the wallet, it will be the only way to withdraw stake when desired - -### Running an allowlisted defensive validator - -- A defensive validator requires that a wallet has already been created using the above steps -- Defensive validator wallets do not need to be funded initially -- If a defensive validator detects a deviation, it will log `bringing defensive validator online because of incorrect assertion`, and wait for funds to be added to wallet so stake can be posted and a dispute created -- Here is an example of how to run an allowlisted defensive validator for Arbitrum One: - ```shell - docker run --rm -it -v /some/local/dir/arbitrum:/home/user/.arbitrum @latestNitroNodeImage@ --parent-chain.connection.url=https://l1-mainnet-node:8545 --chain.id=42161 --node.staker.enable --node.staker.strategy=Defensive --node.staker.parent-chain-wallet.password="SOME SECURE PASSWORD" - ``` -- For Orbit chains, you need to set the `--chain.info-json=` flag instead of `--chain.id=` -- To verify validator is working, this log line shows the wallet is setup correctly: - ```shell - INFO [09-28|18:43:49.367] running as validator txSender=0x... actingAsWallet=0x... whitelisted=true strategy=Defensive - ``` - - `whitelisted` should be `true` after your wallet has been added to the allowlist - - `strategy` should be `Defensive` - - `txSender` and `actingAsWallet` should both be present and not `nil` - - The log line `validation succeeded` shows that the L2 block validator is working - - The log line `found correct assertion` shows that the L1 validator is working - -#### Orbit chains: grant whitlelist - -- You need to be the chain owner to include a new validator address in the allowlist: -- Find your `upgradeExecutor` contract address. -- Send transactions to the `executeCall` method of the`upgradeExecutor` contract and set the `target` address to your Rollup contract's address, set the `targetCalldata` to `0xa3ffb772{Your new allowlist validator address}`. (`0xa3ffb772` is the signature of `setValidator(address[],bool[])`) -- Call your Rollup contract's `isValidator(address)` and check the result. +Validators are nodes that choose to participate in the rollup protocol to advance the state of the chain securely. Since the activation of BoLD, 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 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 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) +- [How BoLD works](/bold/concepts/bold-technical-deep-dive.mdx#how-bold-uses-ethereum), if you're running a validator for a chain that has BoLD activated + +## Validation strategies + +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 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 + +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. + +```shell +found incorrect assertion in watchtower mode +``` + +To verify that the watchtower mode is enabled, this line should appear in the logs: + +```shell +INFO [09-28|18:43:49.367] running as validator txSender=nil actingAsWallet=nil whitelisted=false strategy=Watchtower +``` + +Additionally, the following logs indicate whether all components are working correctly: + +- 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 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 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: + +- The token used to perform actions on-chain is the native token of the parent chain (usually `ETH`) +- 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 + +On top of the configuration of a regular full node, you'll need to configure the following parameters for it to act as a validator: + +| Parameter | Value | Description | +| ----------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--node.staker.enable` | `true` | Enables validation | +| `--node.staker.strategy` | `Watchtower`, `Defensive`, `StakeLatest`, `ResolveNodes`, `MakeNodes` | Strategy that your node will use (only needed if BoLD is not enabled) | +| `--node.staker.parent-chain-wallet.private-key` | 0xPrivateKey | Private key of the wallet used to perform the operations on-chain. Use either `private-key` or `password` (below) | +| `--node.staker.parent-chain-wallet.password` | Password | Password of a wallet generated with nitro (see instructions [here](#use-nitro-to-create-a-wallet-for-your-validator)). Use either `private-key` (above) or `password` | +| `--node.bold.enable` | true | Enables validation with BoLD (not needed if BoLD is not activated) | +| `--node.bold.strategy` | `Watchtower`, `Defensive`, `StakeLatest`, `ResolveNodes`, `MakeNodes` | Strategy that your node will use (not needed if BoLD is not activated) | + +Here's an example of how to run a defensive validator for Arbitrum One: + +```shell +docker run --rm -it -v /some/local/dir/arbitrum:/home/user/.arbitrum @latestNitroNodeImage@ --parent-chain.connection.url=https://l1-mainnet-node:8545 --chain.id=42161 --node.staker.enable --node.staker.strategy=Defensive --node.staker.parent-chain-wallet.password="SOME SECURE PASSWORD" --node.bold.enable --node.bold.strategy=Defensive +``` + +### Step 2: verify that your node is running as a validator + +To verify that your node is acting as a validator, you can look for the following log line: + +```shell +INFO [09-28|18:43:49.367] running as validator txSender=0x... actingAsWallet=0x... whitelisted=true strategy=Defensive +``` + +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: + +- 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 + +## 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`. + +```shell +--chain.info-json= +``` + +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 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: + +```shell +docker run --rm -it -v /some/local/dir/arbitrum:/home/user/.arbitrum @latestNitroNodeImage@ --parent-chain.connection.url=https://l1-mainnet-node:8545 --chain.id=42161 --node.staker.enable --node.staker.parent-chain-wallet.only-create-key --node.staker.parent-chain-wallet.password="SOME SECURE PASSWORD" +``` + +The wallet file will be created under the mounted directory inside the `/wallet/` directory (for example, `arb1/wallet/` for Arbitrum One, or `nova/wallet/` for Arbitrum Nova). Be sure to backup the wallet, as it will be the only way to withdraw the stake when desired. + +Once the wallet is created, you can instruct your validator to use it by adding the option `--node.staker.parent-chain-wallet.password="SOME SECURE PASSWORD"` when running your node. + +### 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 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 | +| ---------------------- | ----- | --------------------------------------- | +| `--node.bold.api` | true | Enables the API | +| `--node.bold.api-host` | IP | IP to listen on (defaults to 127.0.0.1) | +| `--node.bold.api-port` | Port | Port to listen on (defaults to 9393) | + +You can find specific documentation about the methods available on this API in [BoLD validator API](/run-arbitrum-node/more-types/04-bold-validator-api.mdx). + +### 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 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. 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: + - set the `target` address to your Rollup contract's address + - set the `targetCalldata` to `0xa3ffb772{Your new allowlist validator address}` (`0xa3ffb772` is the signature of `setValidator(address[],bool[])`). For example, if you want to add the address `0x1234567890123456789012345678901234567890`, your `targetCalldata` should be `0xa3ffb7721234567890123456789012345678901234567890`. +3. Call your Rollup contract's `isValidator(address)` and check the result + +After performing this operation, the new validator will be able to run a validator node to participate in the chain. diff --git a/arbitrum-docs/run-arbitrum-node/more-types/04-bold-validator-api.mdx b/arbitrum-docs/run-arbitrum-node/more-types/04-bold-validator-api.mdx new file mode 100644 index 000000000..32a0e7b35 --- /dev/null +++ b/arbitrum-docs/run-arbitrum-node/more-types/04-bold-validator-api.mdx @@ -0,0 +1,71 @@ +--- +title: 'BoLD validator API' +description: Describes the API available on BoLD validator nodes +author: TucksonDev +sme: TucksonDev +content_type: concept +--- + +When BoLD 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 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 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. + +```go +t=2023-11-03T21:03:08+0000 lvl=info msg="Successfully bisected edge" service=edge-tracker name= challengeType=block_challenge_edge bisectedFrom=16 bisectedFromMerkle=0x87d91006 bisectedTo=8 bisectedToMerkle=0xb3321c66 +t=2023-11-03T21:03:08+0000 lvl=info msg="Tracking edge" service=edge-tracker id=0xc66e7e5d fromBatch=0 toBatch=1 startHeight=0 endHeight=8 endCommit=0xb3321c66 startCommit=0x0107305d validatorName= challengeType=block_challenge_edge +t=2023-11-03T21:03:08+0000 lvl=info msg="Tracking edge" service=edge-tracker startHeight=8 startCommit=0xb3321c66 endHeight=16 endCommit=0x87d91006 id=0xbb16c213 fromBatch=0 toBatch=1 validatorName= challengeType=block_challenge_edge +``` + +Aside from logs, we do not have a good way of understanding if a challenge is going in favor of the honest party. Since we cannot rely solely on logs to understand the progression of a BoLD challenge, Nitro includes an API that provides information to understand ongoing challenges and the health of the honest validators involved. + +## Enabling and configuring the API + +To enable the API, include the following parameters in the configuration of your validator: + +| Parameter | Description | +| ---------------------- | --------------------------------------- | +| `--node.bold.api` | Set to true to enable the API | +| `--node.bold.api-host` | IP to listen on (defaults to 127.0.0.1) | +| `--node.bold.api-port` | Port to listen on (defaults to 9393) | + +## Endpoints available + +The following endpoints are available at the configured host and port to query information from the API. Send a `GET` request to access them: + +### `/api/v1/assertions` + +Lists all assertions up to chain head. + +This request will return an array of objects with information about each assertion. + +### `/api/v1/assertions/` + +Returns information of a specific assertion. + +### `/api/v1/challenge//edges` + +Returns all edges for a challenged assertion. + +This request will return an array of objects with information about each edge. + +### `/api/v1/challenge//edges/history/` + +Returns information about a specific edge, given its history commitment. + +### `/api/v1/challenge//ministakes` + +Returns all the ministakes bonded under a challenged assertion. + +### `/api/v1/tracked/royal-edges` + +Returns the locally-tracked, royal edges kept in-memory by the validator. + +### `/api/v1/healthz` + +Checks if the API server is ready to serve queries. Returns a status of `200` if it is ready. Notice that this request will not return any result. diff --git a/website/sidebars.js b/website/sidebars.js index 2b0967917..33ab8e6f1 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -733,6 +733,11 @@ const sidebars = { id: 'run-arbitrum-node/more-types/run-validator-node', label: 'Run a validator', }, + { + type: 'doc', + id: 'run-arbitrum-node/more-types/bold-validator-api', + label: 'BoLD validator API', + }, { type: 'doc', id: 'run-arbitrum-node/more-types/run-classic-node',