Skip to main content

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

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

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.

Minimum hardware configuration​

The following is the minimum hardware configuration required 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:

  • These minimum requirements for RAM and CPU are recommended for nodes that process a small amount of RPC requests. For nodes that require processing multiple simultaneous requests, both RAM and number of CPU cores will need to be scaled with the amount of traffic being served.
  • Single core performance is important. If the node is falling behind and a single core is 100% busy, it is recommended to update 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

Even though there are alpha and beta versions of the Arbitrum Nitro software, only release versions should be used when running your node. Running alpha or beta versions is not supported and might lead to unexpected behaviors.

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

Database snapshots​

Snapshots availability

Database snapshots are available for Arbitrum One, Arbitrum Nova and Arbitrum Sepolia and can be found in the snapshot explorer. Database snapshots for other Arbitrum chains may be available at the discretion of the team running the chain. Please contact 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 supply the information from the Classic era), but optional for other chains. Supplying a database snapshot on the first run will provide the state and data for that chain up to a certain block, so the node will be able to sync faster to the head of the chain.

We provide here a summary of the parameters available, but we recommend reading the full guide if you plan on using snapshots.

  • Use the parameter --init.latest <snapshot type> (accepted values: archive, pruned, genesis) to instruct your node to download the correspondant 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 are 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>

You can find a list of Ethereum beacon chain RPC providers here. 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. This means that 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 all together​

  • When running the Docker image, an external volume should be mounted to persist the database across restarts. The mount point inside the Docker image should be /home/user/.arbitrum
  • 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 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 will run in Watchtower mode. This means that the node watches the onchain assertions, and if it disagrees with them, it will log 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 properly, 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 to save disk space and slightly improve 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). Remember that this process will happen upon starting the node and will not serve RPC requests while pruning.

Transaction prechecker​

  • Enabling the transaction prechecker will add extra checks before your node forward 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.