Skip to main content

How to run a full node for an Arbitrum or Arbitrum chain

info

If you’re interested in accessing an Arbitrum chain but don’t want to set up your own node, see our Node Providers to get RPC access to fully managed nodes hosted by a third-party provider.

This how-to provides step-by-step instructions for running a full node for Arbitrum on your local machine.

Prerequisites​

In addition to the hardware requirements, the following prerequisites will be necessary when initially setting up your node. It is essential not to skip over these items. You would benefit by copying and pasting them into a notepad or text editor, as you will need to combine them with other commands and configuration/parameter options when you initially run your Arbitrum node.

Minimum hardware configuration​

The following are the minimum hardware requirements to set up a Nitro full node (not archival):

ResourceRecommended
RAM16 GB
CPU4 core CPU (for AWS, a t3 xLarge instance)
Storage typeNVMe SSD drives are recommended
Storage sizeDepends on the chain and its traffic overtime

Please note that:

  • The minimum requirements for RAM and CPU listed here are recommended for nodes that handle a limited number of RPC requests. For nodes that need to process multiple simultaneous requests, both the RAM size and the number of CPU cores should be increased to accommodate higher levels of traffic.
  • Single core performance is important. If the node is falling behind and a single core is 100% busy, the recommendation is to upgrade to a faster processor
  • The minimum storage requirements will change over time as the chain grows. Using more than the minimum requirements to run a robust full node is recommended.
caution

Although there are beta and release candidate versions of the Arbitrum Nitro software, use only the release version when running your node. Running beta or RC versions is not supported and might lead to unexpected behaviors and/or database corruption.

Latest Docker image: offchainlabs/nitro-node:v3.6.5-89cef87

Database snapshots​

Snapshots availability

Database snapshots are available and located in the snapshot explorer for Arbitrum One, Arbitrum Nova, and Arbitrum Sepolia. Database snapshots for other Arbitrum chains may be available at the discretion of the team running the chain. Please get in touch with them if you're interested in using a database snapshot for their chains.

Supplying a database snapshot when starting your node for the first time is required for Arbitrum One (to provide information from the Classic era) but is optional for other chains. Supplying a database snapshot on the first run will provide the state and data for that chain up to a specific block, allowing the node to sync faster to the head of the chain.

We provide a summary of the available parameters here, but we recommend reading the complete guide if you plan to use snapshots.

  • Use the parameter --init.latest <snapshot type> (accepted values: archive, pruned, genesis) to instruct your node to download the corresponding snapshot from the configured URL
  • Optionally, use the parameter --init.latest-base to set the base URL when searching for the latest snapshot
  • Note that these parameters get ignored if a database already exists
  • When running more than one node, it's easier to manually download the different parts of the snapshot, join them into a single archive, and host it locally for your nodes. Please see Downloading the snapshot manually for instructions on how to do that.

Required parameters​

The following list contains all the parameters needed to configure your node. Select the appropriate option depending on the chain you want to run your node for.

1. Parent chain (Ethereum) parameters​

The --parent-chain.connection.url parameter needs to provide a standard RPC endpoint for an Ethereum node, whether self-hosted or obtained from a node service provider:

--parent-chain.connection.url=<Ethereum RPC URL>

Additionally, use the parameter --parent-chain.blob-client.beacon-url to provide a beacon chain RPC endpoint:

--parent-chain.blob-client.beacon-url=<Ethereum beacon chain RPC URL>
Try it out

If you choose to self-host an EVM node, the Prysm client software is a great choice. It's straightforward, efficient, and effective—ensuring your setup runs smoothly!

You can also consult our list of Ethereum beacon chain RPC providers. Note that historical blob data is required for these chains to properly sync up if they are new or have been offline for more than 18 days. The beacon chain RPC endpoint you use may also need to provide historical blob data. Please see Special notes on ArbOS 20: Atlas support for EIP-4844 for more details.

2. Arbitrum chain parameters​

Use the parameter --chain.id to specify the chain you're running this node for. See RPC endpoints and providers to find the IDs of these chains.

--chain.id=<Arbitrum chain ID>

Alternatively, you can use the parameter --chain.name to specify the chain you're running this node for. Use arb1 for Arbitrum One, nova for Arbitrum Nova, or sepolia-rollup for Arbitrum Sepolia.

--chain.name=<Child chain name>

Putting it into practice: run a node​

  • To ensure the database persists across restarts, mount an external volume when running the Docker image. Use the mount point /home/user/.arbitrum within the Docker image.
  • Here is an example of how to run nitro-node:
docker run --rm -it -v /some/local/dir/arbitrum:/home/user/.arbitrum -p 0.0.0.0:8547:8547 -p 0.0.0.0:8548:8548 offchainlabs/nitro-node:v3.6.5-89cef87 --parent-chain.connection.url=<Ethereum RPC URL> --parent-chain.blob-client.beacon-url=<Ethereum beacon chain RPC URL> --chain.id=<Arbitrum chain id> --init.latest=pruned --http.api=net,web3,eth --http.corsdomain=* --http.addr=0.0.0.0 --http.vhosts=*

  • Note that it is important that /some/local/dir/arbitrum already exists; otherwise, the directory might be created with root as owner, and the Docker container won't be able to write to it.

  • Note that if you are running a node for the parent chain (e.g., Ethereum for Arbitrum One or Nova) on localhost, you may need to add --network host right after docker run to use Docker host-based networking

  • When shutting down the Docker image, it is important to allow a graceful shutdown to save the current state to disk. Here is an example of how to do a graceful shutdown of all Docker images currently running

    docker stop --time=1800 $(docker ps -aq)

Important ports​

ProtocolDefault port
RPC/http8547
RPC/websocket8548
Sequencer Feed9642
  • Please note: the RPC/websocket protocol requires some ports to be enabled, you can use the following flags:
    • --ws.port=8548
    • --ws.addr=0.0.0.0
    • --ws.origins=\*

Note on permissions​

  • The Docker image is configured to run as non-root UID 1000. This configuration means if you are running in Linux or OSX and you are getting permission errors when trying to run the Docker image, run this command to allow all users to update the persistent folders:

    mkdir /data/arbitrum
    chmod -fR 777 /data/arbitrum

Watchtower mode​

  • By default, the full node runs in Watchtower mode, meaning that it watches the onchain assertions and, if it disagrees with them, logs an error containing the string found incorrect assertion in watchtower mode. For a BoLD-enabled chain like Arbitrum One or Arbitrum Nova if you are running Nitro before v3.6.0, the --node.bold.enable=true flag should be set to ensure your node can monitor for onchain assertions properly.
  • Setting this flag is not required as your node will continue to operate correctly, validate the Arbitrum One/Nova chain, and serve RPC requests as usual, regardless of this flag.
  • Note that watchtower mode adds a small amount of execution and memory overhead. You can deactivate this mode using the parameter --node.staker.enable=false.

Pruning​

  • Pruning a full node refers to removing older, unnecessary data from the local copy of the blockchain that the node maintains, thereby saving disk space and slightly improving the node's efficiency. Pruning will remove all states from blocks older than the latest 128.
  • You can activate pruning by using the parameter --init.prune and using "full" or "validator" as the value (depending on the type of node you are running). Note that this process occurs when the node starts and will not serve RPC requests during pruning.

Transaction prechecker​

  • Enabling the transaction prechecker will add extra checks before your node forwards eth_sendRawTransaction to the Sequencer endpoint.
  • Below, we list the flags to set up the prechecker:
FlagDescription
--execution.tx-pre-checker.strictnessHow strict to be when checking transactions before forwarding them. 0 = accept anything, 10 = should never reject anything that'd succeed, 20 = likely won't reject anything that'd succeed, 30 = full validation which may reject transactions that would succeed (default 20)
--execution.tx-pre-checker.required-state-ageHow long ago should the storage conditions from eth_SendRawTransactionConditional be true, 0 = don't check old state (default 2)
--execution.tx-pre-checker.required-state-max-blocksMaximum number of blocks to look back while looking for the <required-state-age> seconds old state, 0 = don't limit the search (default 4)

Optional parameters​

Below, we listed the most commonly used parameters when running a node. You can also use the flag --help for a comprehensive list of the available parameters.

FlagDescription
--http.apiOffers APIs over the HTTP-RPC interface. Default: net,web3,eth,arb. Add debug for tracing.
--http.corsdomainAccepts cross-origin requests from these comma-separated domains (browser enforced).
--http.vhostsAccepts requests from these comma-separated virtual hostnames (server enforced). Default: localhost. Accepts *.
--http.addrSets the address to bind RPC to. May require 0.0.0.0 for Docker networking.
--execution.caching.archiveRetains past block state. For archive nodes.
--node.feed.input.url=<feed address>Sets the sequencer feed address to this URL. Default: wss://<chainName>.arbitrum.io/feed. ⚠️ One feed relay per datacenter is advised. See feed relay guide.
--execution.forwarding-target=<RPC>Sets the sequencer endpoint to forward requests to.
--execution.rpc.evm-timeoutDefault: 5s. Timeout for eth_call. (0 == no timeout).
--execution.rpc.gas-capDefault: 50000000. Gas cap for eth_call/estimateGas. (0 = no cap).
--execution.rpc.tx-fee-capDefault: 1. Transaction fee cap (in ether) for RPC APIs. (0 = no cap).
--execution.tx-lookup-limitDefault: 126230400, ~1 year worth of blocks at 250ms/block. Maximum number of blocks from head whose transaction indices are reserved (e.g. eth_getTransactionReceipt and eth_getTransactionByHash will only return results for indexed transactions). Set to 0 to index transactions for all blocks. Changing this parameter will reindex all missing transactions without the need of resyncing the chain.
--execution.rpc.classic-redirect=<RPC>(Arbitrum One only) Redirects archive requests for pre-nitro blocks to this RPC of an Arbitrum Classic node with archive database.
--ipc.pathFilename for IPC socket/pipe within datadir. 🔉 Not supported on macOS. Note the path is within the Docker container.
--init.prunePrunes the database before starting the node. Can be "full" or "validator".
--init.url="<snapshot file>"(Required for Arbitrum One) URL to download the genesis database from. Only required for Arbitrum One nodes, when running them for the first time. See this guide for more information.
--init.download-path="/path/to/dir"Temporarily saves the downloaded database snapshot. Defaults to /tmp/. Used with --init.url.
--init.latestSearches for the latest snapshot of the given kind (accepted values: archive, pruned, genesis)
--init.latest-baseBase url used when searching for the latest snapshot. Default: "https://snapshot.arbitrum.foundation/". If you are running an Arbitrum chain, ask the chain owner for this URL.
--init.then-quitAllows any --init.* parameters to complete, and then the node will automatically quit. It doesn't initiate pruning by itself but works in conjunction with other --init.* parameters, making it easier to script tasks like database backups after initialization processes finish.