How to run a full node for an Orbit chain

This how-to provides step-by-step instructions for running an Orbit node on your local machine.

Prerequisites

Latest Docker Image: offchainlabs/nitro-node:v3.2.1-d81324d

Minimum Hardware Configuration
RAM: 8-16 GB
CPU: 2-4 core CPU (For AWS: t3 xLarge
Storage: Depends on the Orbit chain and its traffic overtime

Required parameters

1. Parent chain parameters

The parent-chain argument 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>

note

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.

2. Child chain parameters

In the Arbitrum Orbit context, the child chain is an L2 or an L3 Orbit chain, and the required parameters are chain.info-json and chain.name

1. chain.info-json

--chain.info-json is a JSON string that contains required information about the Orbit chain.

--chain.info-json=<Orbit Chain's chain info>

An example of chain.info-json is available in the next section.

2. chain.name

--chain.name is a mandatory flag that needs to match the chain name used in --chain.info-json:

--chain.name=<My Arbitrum L3 Chain>

3. execution.forwarding-target

You need to set the --execution.forwarding-target flag if you are running a regular full node (Not sequencer).

--execution.forwarding-target=<Your Sequencer node endpoint url>

4. AnyTrust chains

For Anytrust chains, you need to to add the following flags to the command or configuration:

--node.data-availability.enable

And:

--node.data-availability.rest-aggregator.urls=<A list of DAS REST endpoints>

Or:

--node.data-availability.rest-aggregator.online-url-list=<A url that returns a list of the DAS REST endpoints>

3.Important ports

Protocol	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=\*

4. Putting it all together

• When running a 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

• Example:

  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.2.1-d81324d --parent-chain.connection.url=<Parent chain RPC URL> --chain.id=<OrbitChainId> --chain.name=<My Arbitrum Orbit Chain> --http.api=net,web3,eth --http.corsdomain=* --http.addr=0.0.0.0 --http.vhosts=* --chain.info-json=<Orbit Chain's chain info> --execution.forwarding-targe=<Your Sequencer node endpoint url>

  • Ensure 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

  • When using the flag --chain.info-json=<Orbit Chain's chain info>, replace <Orbit Chain's chain info> with the specific chain info JSON string of the Orbit chain for which you wish to run the node:

• Example:

  --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}}]"

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

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

Note on permissions

• The Docker image is configured to run as non-root UID 1000. If you are running Linux or macOS 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

Note on Sequencer feed

Nitro nodes can be configured to receive real time ordered transactions from the sequencer feed. If you don't set the feed input url, your node will listen to the parent chain's inbox contract to get the ordered transactions, which will cause your node to be unable to synchronize the latest state.

Set the following configurations to your fullnode to make it can receive the sequencer feed:

--node.feed.input.url=<Sequencer feed url>

After that, your node can synchronize the latest state from the sequencer feed.

(Chain owners only) In order for a node to read the sequencer feed, the chain's sequencer needs to be configured with the following parameters:

--node.feed.output.enable=true --node.feed.output.addr=<Sequencer feed url> --node.feed.output.port=<Sequencer feed port>

Optional parameters

We show here a list of the parameters that are most commonly used when running your Orbit node. You can also use the flag --help for a full comprehensive list of the available parameters.

Flag	Description
--execution.rpc.classic-redirect=<RPC>	Redirects archive requests for pre-nitro blocks to this RPC of an Arbitrum Classic node with archive database. Only for Arbitrum One.
--http.api	Offered 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	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>	Default: wss://<chainName>.arbitrum.io/feed. ⚠️ One feed relay per datacenter is advised. See feed relay guide.
--execution.forwarding-target=<RPC>	Defaults to the L2 Sequencer RPC based on provided L1 and L2 chain IDs.
--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).
--ipc.path	Filename for IPC socket/pipe within datadir. 🔉 Not supported on macOS. Note the path is within the Docker container.
--init.prune	Prunes database before starting the node. Can be "full" or "validator".
--init.url="<snapshot file>"	(Non-Orbit Nitro nodes only) URL to download the genesis database from. Required only for the first startup of an Arbitrum One node. Reference to snapshots and archive node guide.
--init.download-path="/path/to/dir"	(Non-Orbit Nitro nodes only) Temporarily saves the downloaded database snapshot. Defaults to /tmp/. Used with --init.url.
--node.batch-poster.post-4844-blobs	Boolean. Default: false. Used to enable or disable the posting of transaction data using Blobs to L1 Ethereum. If using calldata is more expensive and if the parent chain supports EIP4844 blobs, the batch poster will use blobs when this flag is set to true. Can be true or false.
--node.batch-poster.ignore-blob-price	Boolean. Default: false. If the parent chain supports EIP4844 blobs and ignore-blob-price is set to true, the batch poster will use EIP4844 blobs even if using calldata is cheaper. Can be true or false.
--init.latest	string. if set, searches for the latest snapshot of the given kind (accepted values: "archive" , "pruned" , "genesis")
--init.latest-base	string. Default: "https://snapshot.arbitrum.foundation/". Base url used when searching for the latest. (If you are running orbit chains you might need to check with orbit chain team to get the 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.