Skip to main content

How to run an archive node

An Arbitrum archive node is a full node that maintains an archive of historical chain states. This how-to walks you through the process of configuring an archive node on your local machine so that you can query both pre-Nitro and post-Nitro state data.

caution

Most users won't need to configure an archive node. This node type is great for a small number of use cases––for example if you need to process historical data.

Before we begin​

Before the Nitro upgrade, Arbitrum One ran on the Classic stack for about one year (before block height 22207817). Although the Nitro chain uses the latest snapshot of the Classic chain's state as its genesis state, the Nitro stack can serve all but six RPC requests for pre-Nitro blocks. Full details are outlined in Do you need to run a Classic node?.

Running an Arbitrum One full node in archive mode lets you access both pre-Nitro and post-Nitro blocks, but it requires you to run both Classic and Nitro nodes together. You may not need to do this, depending on your use case:

Use caseRequired node type(s)Docs
Access the Arbitrum network without running your own nodeFully managed by third-parties, exposed via RPC endpointsRPC endpoints and providers
Run an archive node for Arbitrum Sepolia (testnet) or Arbitrum NovaFull node (Nitro)How to run a full node (Nitro)
Send post-Nitro archive requestsFull node (Nitro)How to run a full node (Nitro)
Send pre-Nitro archive requestsFull node (Classic)How to run a full node (Classic, pre-Nitro)
Send post-Nitro and pre-Nitro archive requestsFull node (Nitro) and full node (Classic)That's what this how-to is for; you're in the right place.
Archive nodes using PathDB (path-based state scheme)

A Nitro archive node using PathDB is similar to an archive node using HashDB (default), with the exception that a Nitro archive node using PathDB takes significantly less disk space (~4TB for Arbitrum One). During sync and serving RPC calls, an archive node using PathDB should be equivalent to, or slightly better than, one using HashDB.

We recommend using PathDB for archive nodes, but only on Nitro versions >= v3.9.x.

Benefits of PathDB:

  • Lower disk usage: Under ~4 TB for Arbitrum One
  • Configurable retention: users can choose how many historical states to retain (using --execution.caching.state-history)

Limitations:

Block validation is not yet supported with the path-based state scheme. In other words, validators cannot use PathDB yet.

  • Fast, local NVMe SSD storage is required for reasonable sync speed.
  • PathDB snapshot auto-downloads with --init.latest are not yet supported.

To enable PathDB on your archive node, start your node with the following flags:

--execution.caching.state-scheme=path
--execution.caching.state-history=0

System requirements​

The minimum storage requirements will change as the Nitro chains grow (see the growth rates below). We recommend exceeding the minimum requirements as much as you can to minimize risk and maintenance overhead. The disk size for archive nodes is expected to grow over time. Carefully monitor your node's disk requirements and disk growth rates to ensure your node has adequate resources.

ResourceMinimum requirementsRecommended
RAM (DDR5)64 GB128 GB or more
CPU8 core 3rd generation CPUs (for AWS, a i4i.2xlarge instance)16 core CPU or higher and more recent/newer generation of CPUs
Storage typeNVMe SSD drives with locally attached drives strongly recommendedSame
Storage sizeDepends on the chain and its traffic over time, but ideally several terabytes (TB)Same, but higher if possible
  1. Docker images: We'll specify these in the below commands; you don't need to download them manually.
    • Latest Docker image for Arbitrum One Nitro: offchainlabs/nitro-node:v3.9.9-6b0af88
    • Latest Docker image for Arbitrum One Classic: offchainlabs/arb-node:v1.4.6-551a39b3
  2. Database snapshots:

Review and configure ports​

  • RPC: 8547
  • Sequencer Feed: 9642
  • WebSocket: 8548

Review and configure parameters​

Arbitrum NitroArbitrum ClassicDescription
--parent-chain.connection.url=<Layer 1 Ethereum RPC URL>--l1.url=<Layer 1 Ethereum RPC URL>Provide an standard L1 node RPC endpoint that you run yourself or from a third-party node provider (see RPC endpoints and providers)
--chain.id=<L2 chain ID>--l2.chain-id=<L2 Chain ID>See RPC endpoints and providers for a list of Arbitrum chains and the respective child chain IDs
--execution.caching.archive--node.caching.archiveRequired for running an Arbitrum One Nitro archival node and retains past block state
--execution.caching.state-schemeDefault: hash. This flag sets the schema used in Nitro's state trie, inherited from Geth. You can set this to path to enable PathDB, but note that PathDB isn't yet supported for validators.
--execution.caching.state-historyDefault: 345600 blocks, calculated as 24 hours worth of blocks at the default block speed of 250ms. Number of recent blocks of state history to retain on disk. Set to 0 for unlimited (i.e. Archive nodes). Only available for PathDB enabled nodes
--execution.caching.pathdb-max-diff-layersDefault: 128 layers. Maximum number of diff layers kept in the node's memory before flushing to disk. Increasing the number of diff layers may cause the node to fall behind the chain head during busy periods since doing so slows down block processing speed and reduces sync speed. This configuration is primarily used to improve performance of shallow re-orgs (which are a concern on Ethereum but not on Arbitrum chains) and for efficient access to recent state.
---node.cache.allow-slow-lookupRequired for running an Arbitrum One Classic archival node. When this option is present, it will load old blocks from disk if not in memory cache.
---core.checkpoint-gas-frequency=156250000Required for running an Arbitrum One Classic archival node.

Run the Docker image(s)​

When running a Docker image, an external volume should be mounted to persist the database across restarts. The mount point should be /home/user/.arbitrum/mainnet.

To run both Arbitrum Nitro and/or Arbitrum Classic in archive mode, follow one or more of the below examples:

  • Arbitrum One Nitro archive 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.9.9-6b0af88 --parent-chain.connection.url https://l1-node:8545 --chain.id=42161 --http.api=net,web3,eth --http.corsdomain=* --http.addr=0.0.0.0 --http.vhosts=* --execution.caching.archive
  • Arbitrum One Classic archive node: 
    docker run --rm -it -v /some/local/dir/arbitrum-mainnet/:/home/user/.arbitrum/mainnet -p 0.0.0.0:8547:8547 -p 0.0.0.0:8548:8548 offchainlabs/arb-node:v1.4.6-551a39b3 --l1.url=https://l1-node:8545/ --node.chain-id=42161 --l2.disable-upstream --node.cache.allow-slow-lookup --core.checkpoint-gas-frequency=156250000 --core.lazy-load-core-machine
  • Arbitrum One Nitro archive node with forwarding classic execution support: 
    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.9.9-6b0af88 --parent-chain.connection.url https://l1-node:8545 --chain.id=42161 --execution.rpc.classic-redirect=<classic node RPC> --http.api=net,web3,eth --http.corsdomain=* --http.addr=0.0.0.0 --http.vhosts=* --execution.caching.archive

Note that the above commands both map to port 8547 on their hosts. To run both on the same host, you should edit those mapping to different ports and specify your Classic node RPC URL as <classic node RPC> in your Nitro start command. To verify the connection health of your node(s), see Docker network between containers - Docker Networking Example.

A note on permissions​

The Docker image is configured to run as non-root UID 1000. If you're running in Linux and you're getting permission errors when trying to run the Docker image, run this command to allow all users to update the persistent folders, replacing arbitrum-mainnet as needed:

mkdir /some/local/dir/arbitrum-mainnet
chmod -fR 777 /some/local/dir/arbitrum-mainnet

Optional parameters​

Both Nitro and Classic have multiple other parameters that can be used to configure your node. For a full comprehensive list of the available parameters, use the flag --help.

Archive-path node configuration details​

  • execution.caching.state-scheme=path - sets state scheme → chooses TrieDB implementation
    • path state scheme is not compatible with hash state scheme - the node can only be started from a snapshot that was created with the same state scheme
    • to use path scheme, you need to either sync from genesis or use a public snapshot
  • execution.caching.state-history - specifies number of blocks from the chain head for which state histories are retained
    • state-history=0 means “entire chain”
    • state history is preserved in form of reverse-diffs and those are stored in cold database (also called state freezer, or ancients)
    • state history allows recovery of the historical state—that should allow reorg to historical block (not tested)
    • important: on its own, state history doesn’t allow retrieving historical state by RPC calls (see: execution.caching.archive )
    • historical state is state older then pathdb-max-diff-layers+1 (by default 129) blocks from current head block of the node
    • before nitro 3.10 state-history defaults to 24 hours of blocks at configured block speed
    • after nitro 3.10, defaults are chosen based on archive flag:
      • if execution.caching.archive is set, state-history defaults to 0, otherwise state-history defaults to 24 hours of blocks at configured block speed
  • execution.caching.archive - if set to true enables archive mode; in case of path state scheme:
    • archive mode enables state history indexing:
      • state history index is an extra data that needs to be persisted in hot database (pebble)
      • the state history index allows accessing historical state → RPC calls can access state from older blocks then pathdb-max-diff-layers+1

Troubleshooting​

If you run into any issues, visit the node-running troubleshooting guide.