How to run a full node for an Arbitrum or Orbit chain
This how-to provides step-by-step instructions for running a full node for an Arbitrum or Orbit chain on your local machine.
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):
Resource | Recommended |
---|---|
RAM | 16 GB |
CPU | 4 core CPU (for AWS, a t3 xLarge instance) |
Storage type | NVMe SSD drives are recommended |
Storage size | Depends 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.
Recommended Nitro version
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.5.3-0a9c975
Database snapshots
Database snapshots are available for Arbitrum One, Arbitrum Nova and Arbitrum Sepolia and can be found in the snapshot explorer. Database snapshots for other Orbit 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.
- Arbitrum One, Nova, Sepolia
- Orbit chains
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>
1. Parent chain parameters
The --parent-chain.connection.url
parameter needs to provide a standard RPC endpoint for an EVM node, whether self-hosted or obtained from a node service provider:
--parent-chain.connection.url=<Parent chain RPC URL>
Public Arbitrum RPC endpoints rate-limit connections. To avoid hitting a bottleneck, you can run a local node for the parent chain or rely on third-party RPC providers.
Additionally, if the chain is a Layer-2 (L2) chain on top of Ethereum and uses blobs to post calldata, use the parameter --parent-chain.blob-client.beacon-url
to provide a beacon chain RPC endpoint:
--parent-chain.blob-client.beacon-url=<Parent chain 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. Child chain parameters
The parameter --chain.info-json
specifies a JSON string that contains the information about the Orbit chain required by the node.
--chain.info-json=<Orbit chain's info>
This information should be provided by the chain owner and will look something like the following:
--chain.info-json="[{\"chain-id\":94692861356,\"parent-chain-id\":421614,\"chain-name\":\"My Arbitrum L3 Chain\",\"chain-config\":{\"chainId\":94692861356,\"homesteadBlock\":0,\"daoForkBlock\":null,\"daoForkSupport\":true,\"eip150Block\":0,\"eip150Hash\":\"0x0000000000000000000000000000000000000000000000000000000000000000\",\"eip155Block\":0,\"eip158Block\":0,\"byzantiumBlock\":0,\"constantinopleBlock\":0,\"petersburgBlock\":0,\"istanbulBlock\":0,\"muirGlacierBlock\":0,\"berlinBlock\":0,\"londonBlock\":0,\"clique\":{\"period\":0,\"epoch\":0},\"arbitrum\":{\"EnableArbOS\":true,\"AllowDebugPrecompiles\":false,\"DataAvailabilityCommittee\":false,\"InitialArbOSVersion\":10,\"InitialChainOwner\":\"0xAde4000C87923244f0e95b41f0e45aa3C02f1Bb2\",\"GenesisBlockNum\":0}},\"rollup\":{\"bridge\":\"0xde835286442c6446E36992c036EFe261AcD87F6d\",\"inbox\":\"0x0592d3861Ea929B5d108d915c36f64EE69418049\",\"sequencer-inbox\":\"0xf9d77199288f00440Ed0f494Adc0005f362c17b1\",\"rollup\":\"0xF5A42aDA664E7c2dFE9DDa4459B927261BF90E09\",\"validator-utils\":\"0xB11EB62DD2B352886A4530A9106fE427844D515f\",\"validator-wallet-creator\":\"0xEb9885B6c0e117D339F47585cC06a2765AaE2E0b\",\"deployed-at\":1764099}}]"
Use the parameter --chain.name
to specify the chain you're running this node for. The name of the chain should match the name used in the JSON string used in --chain.info-json
:
--chain.name=<Orbit chain name>
3. Parameters to connect to the sequencer
Use the parameter --node.feed.input.url
to point at the sequencer feed endpoint, which should be provided by the chain owner.
--node.feed.input.url=<Sequencer feed url>
Use the parameter --execution.forwarding-target
to point at the sequencer node of the orbit chain, which should also be provided by the chain owner.
--execution.forwarding-target=<Sequencer node endpoint url>
3. Additional parameters for AnyTrust chains
If you're running a node for an Anytrust chain, you need to specify information about the Data Availability Committee (DAC) in the configuration of your node.
First, enable data-availability
using the following parameters:
--node.data-availability.enable
--node.data-availability.rest-aggregator.enable
Then, choose one of these methods to specify the DAS REST endpoints that your node will read the information from. These endpoints should also be provided by the chain owner.
- Set the DAS REST endpoints directly:
--node.data-availability.rest-aggregator.urls=<A list of DAS REST endpoints, separated by commas>
- Set a URL that returns a list of the DAS REST endpoints:
--node.data-availability.rest-aggregator.online-url-list=<A URL that returns a list of the DAS REST endpoints>
If you are a chain owner, please refer to the DAC setup guide to set it up.
Additionally, for your batch poster to post data to the DAS, follow step 3 of How to configure a DAC to configure your batch poster node.
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
:
- Arbitrum One, Nova, Sepolia
- Orbit chains
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.5.3-0a9c975 --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=*
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.5.3-0a9c975 --parent-chain.connection.url=<Parent chain RPC URL> --chain.info-json=<Orbit chain's info> --chain.name=<Orbit chain name> --node.feed.input.url=<Sequencer feed url> --execution.forwarding-target=<Sequencer node endpoint url> --http.api=net,web3,eth --http.corsdomain=* --http.addr=0.0.0.0 --http.vhosts=*
- You can see an example of
--chain.info-json
in the section above.
-
Note that it is important that
/some/local/dir/arbitrum
already exists; otherwise, the directory might be created withroot
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 afterdocker 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
Protocol | Default port |
---|---|
RPC /http | 8547 |
RPC /websocket | 8548 |
Sequencer Feed | 9642 |
- 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, 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.
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.
Flag | Description |
---|---|
--http.api | Offers APIs over the HTTP-RPC interface. Default: net,web3,eth,arb . Add debug for tracing. |
--http.corsdomain | Accepts cross-origin requests from these comma-separated domains (browser enforced). |
--http.vhosts | Accepts requests from these comma-separated virtual hostnames (server enforced). Default: localhost . Accepts * . |
--http.addr | Sets the address to bind RPC to. May require 0.0.0.0 for Docker networking. |
--execution.caching.archive | Retains 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-timeout | Default: 5s . Timeout for eth_call . (0 == no timeout). |
--execution.rpc.gas-cap | Default: 50000000 . Gas cap for eth_call /estimateGas . (0 = no cap). |
--execution.rpc.tx-fee-cap | Default: 1 . Transaction fee cap (in ether) for RPC APIs. (0 = no cap). |
--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.path | Filename for IPC socket/pipe within datadir. 🔉 Not supported on macOS. Note the path is within the Docker container. |
--init.prune | Prunes 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.latest | Searches for the latest snapshot of the given kind (accepted values: archive , pruned , genesis ) |
--init.latest-base | Base url used when searching for the latest snapshot. Default: "https://snapshot.arbitrum.foundation/". If you are running an Orbit chain, ask the chain owner for this URL. |
--init.then-quit | Allows 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. |