How to run a full node for Xai chain

Note: For steps on how to run a Xai Sentry Node (unrelated to running a full node for Xai chain), go here.

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


Latest Docker Image: offchainlabs/nitro-node:v2.3.3-6a1c1a7

Minimum Hardware Configuration

RAM: 16 GB

CPU: 4 core CPU

Storage: 1 TB

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>


Public Xai RPC endpoints rate-limit connections. To avoid hitting a bottleneck, you can run a local node for the parent chain (Arbitrum) or rely on third-party RPC providers.

2. Child chain parameters

Xai is the child chain and the required parameters are and

1. is a JSON string that contains required information about Xai chain.<Xai Chain's chain info>

An example of is available in the next section.

2. is a mandatory flag that needs to match the chain name used in<My Xai Chain>

3. AnyTrust chains

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

And:<A list of DAS REST endpoints>

Or:<A url that returns a list of the DAS REST endpoints>

3. Important ports






Sequencer Feed


  • Please note: the RPC/websocket protocol requires some ports to be enabled, you can use the following flags:

    • --ws.port=8548

    • --ws.addr=


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 -p offchainlabs/nitro-node:v2.3.3-6a1c1a7 --parent-chain.connection.url=<Parent chain RPC URL><XaiChainId><My Xai Chain> --http.api=net,web3,eth --http.corsdomain=* --http.addr= --http.vhosts=*<Xai Chain's chain info>
    • 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<Xai Chain's chain info>, replace <Xai Chain's chain info> with the specific chain info JSON string of the Xai chain for which you wish to run the node:

  • Example:"[{\"chain-id\":94692861356,\"parent-chain-id\":421614,\"chain-name\":\"My Xai 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 Xai node. You can also use the flag --help for a full comprehensive list of the available parameters.



Redirects archive requests for pre-nitro blocks to this RPC of an Arbitrum Classic node with archive database. Only for Arbitrum One.


Offered APIs over the HTTP-RPC interface. Default: net,web3,eth,arb. Add debug for tracing.


Accepts cross origin requests from these comma-separated domains (browser enforced).


Accepts requests from these comma-separated virtual hostnames (server enforced). Default: localhost. Accepts *.


Address to bind RPC to. May require for Docker networking.


Retains past block state. For archive nodes.

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

Default: wss://<chainName> ⚠️ One feed relay per datacenter is advised. See feed relay guide.


Defaults to the L2 Sequencer RPC based on provided L1 and L2 chain IDs.


Default: 5s. Timeout for eth_call. (0 == no timeout).


Default: 50000000. Gas cap for eth_call/estimateGas. (0 = no cap).


Default: 1. Transaction fee cap (in ether) for RPC APIs. (0 = no cap).


Filename for IPC socket/pipe within datadir. 🔉 Not supported on macOS. Note the path is within the Docker container.


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."/path/to/dir"

(Non-Orbit Nitro nodes only) Temporarily saves the downloaded database snapshot. Defaults to /tmp/. Used with --init.url.

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.


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.

Last updated