Run Full Node

Get step by step instructions on how to run a full-node on Onyx

How to Run a Full Node for Onyx

This guide provides step-by-step instructions for running an Onyx node on your local machine.

Prerequisites

Latest Docker Image

offchainlabs/nitro-node:v3.4.0-d896e9c

Minimum Hardware Configuration

• RAM: 8-16 GB

• CPU: 2-4 core CPU (For AWS: t3 xLarge)

• Storage: 50GB

Required Parameters

1. Parent Chain Parameters

The parent-chain argument must provide a standard RPC endpoint for an EVM node, either self-hosted or obtained from a node service provider:

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

Note: Public Arbitrum RPC endpoints have rate limits. To avoid bottlenecks, consider running a local node for the parent chain or using third-party RPC providers.

2. Child Chain Parameters

The child chain in an Arbitrum Orbit context is an L2 or an L3 Orbit chain. The required parameters are:

1. chain.info-json

This parameter contains necessary information about the Orbit chain:

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

An example JSON format is provided in the next section.

2. chain.name

This mandatory flag must match the chain name specified in --chain.info-json:

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

3. execution.forwarding-target

If running a regular full node (not a sequencer), set this flag:

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

4. AnyTrust Chains

For AnyTrust chains, additional flags are required:

--node.data-availability.enable
--node.data-availability.rest-aggregator.enable

Additionally, specify either:

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

Or:

--node.data-availability.rest-aggregator.online-url-list=<A URL returning a list of DAS REST endpoints>

Important Ports

Protocol	Port
RPC/http	8547
RPC/websocket	8548
Sequencer Feed	9642

For RPC/websocket protocol, enable the required ports using:

--ws.port=8548
--ws.addr=0.0.0.0
--ws.origins=*

Putting It All Together

When running a Docker image, mount an external volume to persist the database across restarts. The mount point inside the Docker image should be:

/home/user/.arbitrum

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.4.0-d896e9c \
  --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-target=<Your Sequencer node endpoint URL>

Example Command:

Important: Ensure /some/local/dir/arbitrum exists before running the command to avoid permission issues.

Example --chain.info-json Format:

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

Graceful Shutdown

Ensure a graceful shutdown to save the current state:

docker stop --time=300 $(docker ps -aq)
Fixing Permission Errors
If you encounter permission errors on Linux/macOS, run:
mkdir /data/arbitrum
chmod -fR 777 /data/arbitrum

Sequencer Feed

Nitro nodes can receive real-time ordered transactions from the sequencer feed. If the feed input URL is not set, the node will listen to the parent chain's inbox contract, which may prevent synchronization with the latest state.

Enable Sequencer Feed Synchronization

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

For chain owners, ensure the sequencer is configured with:

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

Optional Parameters

Flag	Description
--execution.rpc.classic-redirect=<RPC>	Redirects archive requests for pre-nitro blocks to an Arbitrum Classic node.
--http.api	Offered APIs over HTTP-RPC. Default: net,web3,eth,arb. Add debug for tracing.
--execution.forwarding-target=<RPC>	Defaults to L2 Sequencer RPC based on provided L1 and L2 chain IDs.

For a full list of parameters, use:

--help