Run an Arc node - Arc Docs

v0.8.0 upgrade required. Testnet operators must upgrade before timestamp 1788447600 (2026-09-03 15:00:00 UTC), when Zero8 activates. Mainnet operators must upgrade before timestamp 1789052400 (2026-09-10 15:00:00 UTC), when Zero7/Zero8 activate. Earlier versions are not supported after those timestamps.This release includes breaking changes. See CHANGELOG.md and BREAKING_CHANGES.md for migration details before upgrading.

An Arc node syncs blocks from the network and serves a local JSON-RPC endpoint so you can independently verify every block and transaction. It runs two processes: the Execution Layer (EL), which executes transactions and maintains state, and the Consensus Layer (CL), which fetches finalized blocks from relay endpoints (trusted HTTP servers that distribute signed block data), verifies their signatures, and passes them to the EL. For a deeper explanation of how these components fit together, see Running a node.

Arc is currently in its testnet phase. During this period, the network may experience instability or unplanned downtime. Throughout this page, all references to Arc refer specifically to the Arc Testnet.

Choose the install path that fits your environment.

arcup
Build from source
Docker

Install pre-built Arc binaries using the arcup script. This is the fastest path and requires no Rust toolchain or build dependencies.

Prerequisites

Before you begin, ensure that you’ve:

Reviewed the node requirements for hardware, software, and network endpoints
Prepared a Linux or macOS machine that meets the minimum system requirements
Installed Foundry (optional, provides the cast command used to verify your node)

Step 1: Install with `arcup`

arcup installs the Arc binaries under $ARC_HOME (default ~/.arc). Export ARC_HOME first if you want to install somewhere else; otherwise the default applies for both the installer and the environment file:

export ARC_HOME="${ARC_HOME:-$HOME/.arc}"
curl -L https://raw.githubusercontent.com/circlefin/arc-node/main/arcup/install | bash

The installer places arc-node-execution, arc-node-consensus, arc-snapshots, and arcup itself into $ARC_HOME/bin. Load the produced environment file so the binaries are on your PATH:

source "$ARC_HOME/env"

Verify the installation:

arc-snapshots --version
arc-node-execution --version
arc-node-consensus --version

Each command prints a version string. To update the binaries later, run arcup.

Step 2: Set environment variables

The remaining steps use a small set of variables to keep paths consistent. Write them to a file and source it:

cat << "EOF" > ~/.arc_env
ARC_HOME="${ARC_HOME:-$HOME/.arc}"

# Linux runtime directory:
ARC_RUN="/run/arc"

# macOS runtime directory (uncomment if on macOS):
#ARC_RUN="$ARC_HOME/run"

ARC_EXECUTION=$ARC_HOME/execution
ARC_CONSENSUS=$ARC_HOME/consensus
EOF

source ~/.arc_env

Step 3: Create data directories

Create the data directories for the EL and CL, plus the runtime directory used for IPC sockets:

mkdir -p "$ARC_EXECUTION" "$ARC_CONSENSUS"
sudo install -d -o $USER "$ARC_RUN"

On macOS, replace the second command with mkdir -p "$ARC_RUN" after uncommenting the macOS line in ~/.arc_env.

When running as a systemd service, the RuntimeDirectory=arc directive creates /run/arc automatically. You can skip the second command in that case.

Step 4: Download blockchain snapshots

Download snapshots so the node starts syncing from a recent block height rather than from genesis:

arc-snapshots download \
  --chain=arc-testnet \
  --execution-path "$ARC_EXECUTION" \
  --consensus-path "$ARC_CONSENSUS"

This command fetches the latest snapshot URLs from https://snapshots.arc.network, downloads the snapshots, and extracts them into $ARC_EXECUTION and $ARC_CONSENSUS.

Snapshots are large. Testnet snapshots are approximately 68 GB EL + 16 GB CL compressed (around 103 GB and 36 GB extracted). The download takes 10–15 minutes on a stable 100 Mbps connection; slower or metered connections can take hours. Ensure you have at least 150 GB of free disk space, a stable network connection, and available CPU. The terminal stops producing output during extraction. This is expected.

Starting with v0.8.0, Circle provides snapshots in Reth V2 storage format. A fresh install from these snapshots does not require the V1→V2 data migration described in the Migrate to V2 storage section.

Step 5: Initialize the consensus layer

Generate the CL private key file used for network identity. This is a one-time setup step:

arc-node-consensus init --home "$ARC_CONSENSUS"

Step 6: Start the execution layer

Start the Execution Layer. This creates the IPC sockets that the Consensus Layer connects to.

arc-node-execution node \
  --chain arc-testnet \
  --datadir "$ARC_EXECUTION" \
  --full \
  --disable-discovery \
  --ipcpath "$ARC_RUN/reth.ipc" \
  --auth-ipc \
  --auth-ipc.path "$ARC_RUN/auth.ipc" \
  --http \
  --http.addr 127.0.0.1 \
  --http.port 8545 \
  --http.api eth,net,web3,txpool,trace,debug \
  --metrics 127.0.0.1:9001 \
  --enable-arc-rpc \
  --rpc.forwarder https://rpc.testnet.arc.io/

The EL starts and waits for blocks. Log output shows that the IPC sockets exist at $ARC_RUN/reth.ipc and $ARC_RUN/auth.ipc.

Flag	Required	Description
`--chain arc-testnet`	Yes	Selects the Arc Testnet genesis configuration bundled in the binary
`--datadir`	Yes	Path to the EL data directory
`--full`	First start	Required on the first start from a pruned snapshot; optional after
`--disable-discovery`	Yes	Disables P2P peer discovery (Arc uses relay endpoints instead)
`--ipcpath` / `--auth-ipc`	Yes (IPC mode)	Paths for the IPC sockets the CL connects to
`--http` / `--http.addr`	Yes	Enables the JSON-RPC endpoint on the specified address and port
`--http.api`	Recommended	RPC namespaces to expose
`--metrics`	Recommended	Enables Prometheus metrics on the specified address and port
`--enable-arc-rpc`	Yes	Enables Arc-specific RPC methods
`--rpc.forwarder`	Recommended	Routes submitted transactions to an RPC node for broadcast
`--public-api`	Recommended for public-facing nodes	Hides pending-tx RPCs (a potential MEV vector) and warns if `--http.api` or `--ws.api` exposes namespaces beyond `eth`, `net`, `web3`, `rpc`
`--rpc.max-connections`	Recommended for public-facing nodes	Maximum concurrent RPC connections. Default `250` (lowered from `500` in v0.7.1). Raise only if clients see `MaxConnections` errors
`--rpc.max-subscriptions-per-connection`	Recommended for public-facing nodes	Maximum subscriptions per single WebSocket connection. Default `32` (lowered from `1024` in v0.7.1). Raise only if clients see `TooManySubscriptions` errors

On high-traffic public endpoints, raise --rpc.max-connections (default 250) and --rpc.max-subscriptions-per-connection (default 32) if clients see MaxConnections or TooManySubscriptions errors. The defaults bound WebSocket log-fanout memory growth and should only be raised, not lowered.

The --full flag is required on the first start when bootstrapping from a pruned snapshot. It reconciles internal database tables that would otherwise fail a consistency check. After the initial startup completes, restart without --full if you prefer not to prune. When --full is used, EL pruning runs on a 128-block interval (changed from 5000 in v0.7.3); pass --prune.block-interval=5000 explicitly to retain the previous schedule. --chain arc-testnet uses the bundled genesis configuration; replace with --chain /path/to/genesis.json if you have a custom genesis file. See reth node for additional flags.

Step 7: Start the consensus layer

Open a separate terminal and start the Consensus Layer. The CL connects to the EL through the IPC sockets and begins fetching blocks from the network.

arc-node-consensus start \
  --home "$ARC_CONSENSUS" \
  --full \
  --eth-socket "$ARC_RUN/reth.ipc" \
  --execution-socket "$ARC_RUN/auth.ipc" \
  --rpc.addr 127.0.0.1:31000 \
  --follow \
  --follow.endpoint https://rpc.testnet.arc.io,wss=rpc.testnet.arc.io \
  --follow.endpoint https://rpc.drpc.testnet.arc.io,wss=rpc.drpc.testnet.arc.io \
  --follow.endpoint https://rpc.blockdaemon.testnet.arc.io,wss=rpc.blockdaemon.testnet.arc.io/websocket \
  --execution-persistence-backpressure \
  --execution-persistence-backpressure-threshold=16 \
  --metrics 127.0.0.1:29000

Flag	Required	Description
`--home`	Yes	Path to the CL data directory (contains keys and state)
`--full`	Recommended	Enables CL pruning to bound disk growth
`--eth-socket`	Yes (IPC mode)	Path to the Execution Layer ETH RPC IPC socket
`--execution-socket`	Yes (IPC mode)	Path to the Execution Layer Engine API IPC socket
`--rpc.addr`	Recommended	CL RPC listen address and port
`--follow`	Yes	Enables block-following mode through relay endpoints
`--follow.endpoint`	Yes	Relay endpoint URLs. Specify multiple for redundancy. Format: `https://host,wss=host`
`--execution-persistence-backpressure`	Recommended	Throttles execution to match disk-write speed, bounding EL memory growth
`--execution-persistence-backpressure-threshold`	Recommended	Threshold for backpressure. Default `16` (must be `> 0`). Lower if you observe memory pressure
`--metrics`	Recommended	Enables Prometheus metrics on the specified address and port

Step 8: Verify the node is syncing

After both layers start, wait roughly 30 seconds, then query the local JSON-RPC endpoint for the latest block height:

curl -s -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1 }'

The result field is a hexadecimal block number that increases over time. If it stays at 0x0, check the CL logs for errors.If you have Foundry installed, you can run the same check with cast:

cast block-number --rpc-url http://localhost:8545

Run it several times over a few seconds. The block number increases as the node syncs.If the block number stays at 0x0 or the node does not start as expected, check these common causes:

IPC socket files missing. The EL writes sockets at $ARC_RUN/reth.ipc and $ARC_RUN/auth.ipc on startup. If they are missing after 30 seconds, the EL did not start. Review its terminal output for a panic or configuration error.
CL cannot connect to the EL. Start the EL first. If the CL was launched before the EL was ready, restart the CL.
Snapshot extraction incomplete. arc-snapshots download runs silently during extraction. If it was interrupted, $ARC_EXECUTION or $ARC_CONSENSUS may be partially populated. Re-run the download to overwrite the existing files. If you clear the directories first, note that $ARC_CONSENSUS also holds the CL private key written by arc-node-consensus init. Re-run that command after clearing, or your node loses its network identity.
Path mismatch between EL and CL. $ARC_RUN must resolve to the same directory in both shells. Re-source ~/.arc_env in any terminal that lost its environment.

Once your node is syncing steadily, you can deploy it as a systemd service for production use, or set up Prometheus and Grafana to view the pre-built dashboards.

Build Arc binaries from the arc-node repository. Use this path to audit the build, run on an unsupported platform, or pin to a specific commit.

Prerequisites

Before you begin, ensure that you’ve:

Reviewed the node requirements for hardware, software, and network endpoints
Prepared a Linux, macOS, or Windows machine that meets the minimum system requirements
Installed Foundry (optional, provides the cast command used to verify your node)

Step 1: Install build dependencies

Install Rust if you don’t have it:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

Install the platform packages required to build the EL database bindings:

Ubuntu: sudo apt-get install libclang-dev pkg-config build-essential
macOS: brew install llvm pkg-config, then export LIBCLANG_PATH="$(brew --prefix llvm)/lib"
Windows: choco install llvm or winget install LLVM.LLVM

Step 2: Clone the repository

Clone the arc-node repository and check out the version for your target network. See node requirements for the current version:

git clone https://github.com/circlefin/arc-node.git
cd arc-node
git checkout v0.8.0
git submodule update --init --recursive

Step 3: Build and install

The following commands build three Arc node binaries: arc-node-execution, arc-node-consensus, and arc-snapshots:

cargo install --path crates/node
cargo install --path crates/malachite-app
cargo install --path crates/snapshots

cargo install places compiled binaries into ~/.cargo/bin, which is added to PATH by loading ~/.cargo/env. To install elsewhere, add --root $BASE_DIR to each command (for instance, --root /usr/local places them under /usr/local/bin).Verify the installation:

arc-snapshots --version
arc-node-execution --version
arc-node-consensus --version

Step 4: Set environment variables

The remaining steps use a small set of variables to keep paths consistent. Write them to a file and source it:

cat << "EOF" > ~/.arc_env
ARC_HOME="${ARC_HOME:-$HOME/.arc}"

# Linux runtime directory:
ARC_RUN="/run/arc"

# macOS runtime directory (uncomment if on macOS):
#ARC_RUN="$ARC_HOME/run"

ARC_EXECUTION=$ARC_HOME/execution
ARC_CONSENSUS=$ARC_HOME/consensus
EOF

source ~/.arc_env

Step 5: Create data directories

Create the data directories for the EL and CL, plus the runtime directory used for IPC sockets:

mkdir -p "$ARC_EXECUTION" "$ARC_CONSENSUS"
sudo install -d -o $USER "$ARC_RUN"

On macOS, replace the second command with mkdir -p "$ARC_RUN" after uncommenting the macOS line in ~/.arc_env.

When running as a systemd service, the RuntimeDirectory=arc directive creates /run/arc automatically. You can skip the second command in that case.

Step 6: Download blockchain snapshots

Download snapshots so the node starts syncing from a recent block height rather than from genesis:

arc-snapshots download \
  --chain=arc-testnet \
  --execution-path "$ARC_EXECUTION" \
  --consensus-path "$ARC_CONSENSUS"

This command fetches the latest snapshot URLs from https://snapshots.arc.network, downloads the snapshots, and extracts them into $ARC_EXECUTION and $ARC_CONSENSUS.

Step 7: Initialize the consensus layer

Generate the CL private key file used for network identity. This is a one-time setup step:

arc-node-consensus init --home "$ARC_CONSENSUS"

Step 8: Start the execution layer

Start the Execution Layer. This creates the IPC sockets that the Consensus Layer connects to.

arc-node-execution node \
  --chain arc-testnet \
  --datadir "$ARC_EXECUTION" \
  --full \
  --disable-discovery \
  --ipcpath "$ARC_RUN/reth.ipc" \
  --auth-ipc \
  --auth-ipc.path "$ARC_RUN/auth.ipc" \
  --http \
  --http.addr 127.0.0.1 \
  --http.port 8545 \
  --http.api eth,net,web3,txpool,trace,debug \
  --metrics 127.0.0.1:9001 \
  --enable-arc-rpc \
  --rpc.forwarder https://rpc.testnet.arc.io/

The EL starts and waits for blocks. Log output shows that the IPC sockets exist at $ARC_RUN/reth.ipc and $ARC_RUN/auth.ipc.

Flag	Required	Description
`--chain arc-testnet`	Yes	Selects the Arc Testnet genesis configuration bundled in the binary
`--datadir`	Yes	Path to the EL data directory
`--full`	First start	Required on the first start from a pruned snapshot; optional after
`--disable-discovery`	Yes	Disables P2P peer discovery (Arc uses relay endpoints instead)
`--ipcpath` / `--auth-ipc`	Yes (IPC mode)	Paths for the IPC sockets the CL connects to
`--http` / `--http.addr`	Yes	Enables the JSON-RPC endpoint on the specified address and port
`--http.api`	Recommended	RPC namespaces to expose
`--metrics`	Recommended	Enables Prometheus metrics on the specified address and port
`--enable-arc-rpc`	Yes	Enables Arc-specific RPC methods
`--rpc.forwarder`	Recommended	Routes submitted transactions to an RPC node for broadcast
`--public-api`	Recommended for public-facing nodes	Hides pending-tx RPCs (a potential MEV vector) and warns if `--http.api` or `--ws.api` exposes namespaces beyond `eth`, `net`, `web3`, `rpc`
`--rpc.max-connections`	Recommended for public-facing nodes	Maximum concurrent RPC connections. Default `250` (lowered from `500` in v0.7.1). Raise only if clients see `MaxConnections` errors
`--rpc.max-subscriptions-per-connection`	Recommended for public-facing nodes	Maximum subscriptions per single WebSocket connection. Default `32` (lowered from `1024` in v0.7.1). Raise only if clients see `TooManySubscriptions` errors

Step 9: Start the consensus layer

Open a separate terminal and start the Consensus Layer. The CL connects to the EL through the IPC sockets and begins fetching blocks from the network.

arc-node-consensus start \
  --home "$ARC_CONSENSUS" \
  --full \
  --eth-socket "$ARC_RUN/reth.ipc" \
  --execution-socket "$ARC_RUN/auth.ipc" \
  --rpc.addr 127.0.0.1:31000 \
  --follow \
  --follow.endpoint https://rpc.testnet.arc.io,wss=rpc.testnet.arc.io \
  --follow.endpoint https://rpc.drpc.testnet.arc.io,wss=rpc.drpc.testnet.arc.io \
  --follow.endpoint https://rpc.blockdaemon.testnet.arc.io,wss=rpc.blockdaemon.testnet.arc.io/websocket \
  --execution-persistence-backpressure \
  --execution-persistence-backpressure-threshold=16 \
  --metrics 127.0.0.1:29000

Flag	Required	Description
`--home`	Yes	Path to the CL data directory (contains keys and state)
`--full`	Recommended	Enables CL pruning to bound disk growth
`--eth-socket`	Yes (IPC mode)	Path to the Execution Layer ETH RPC IPC socket
`--execution-socket`	Yes (IPC mode)	Path to the Execution Layer Engine API IPC socket
`--rpc.addr`	Recommended	CL RPC listen address and port
`--follow`	Yes	Enables block-following mode through relay endpoints
`--follow.endpoint`	Yes	Relay endpoint URLs. Specify multiple for redundancy. Format: `https://host,wss=host`
`--execution-persistence-backpressure`	Recommended	Throttles execution to match disk-write speed, bounding EL memory growth
`--execution-persistence-backpressure-threshold`	Recommended	Threshold for backpressure. Default `16` (must be `> 0`). Lower if you observe memory pressure
`--metrics`	Recommended	Enables Prometheus metrics on the specified address and port

Step 10: Verify the node is syncing

After both layers start, wait roughly 30 seconds, then query the local JSON-RPC endpoint for the latest block height:

curl -s -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1 }'

The result field is a hexadecimal block number that increases over time. If it stays at 0x0, check the CL logs for errors.If you have Foundry installed, you can run the same check with cast:

cast block-number --rpc-url http://localhost:8545

Run it several times over a few seconds. The block number increases as the node syncs.If the block number stays at 0x0 or the node does not start as expected, check these common causes:

IPC socket files missing. The EL writes sockets at $ARC_RUN/reth.ipc and $ARC_RUN/auth.ipc on startup. If they are missing after 30 seconds, the EL did not start. Review its terminal output for a panic or configuration error.
CL cannot connect to the EL. Start the EL first. If the CL was launched before the EL was ready, restart the CL.
Snapshot extraction incomplete. arc-snapshots download runs silently during extraction. If it was interrupted, $ARC_EXECUTION or $ARC_CONSENSUS may be partially populated. Re-run the download to overwrite the existing files. If you clear the directories first, note that $ARC_CONSENSUS also holds the CL private key written by arc-node-consensus init. Re-run that command after clearing, or your node loses its network identity.
Path mismatch between EL and CL. $ARC_RUN must resolve to the same directory in both shells. Re-source ~/.arc_env in any terminal that lost its environment.

Once your node is syncing steadily, you can deploy it as a systemd service for production use, or set up Prometheus and Grafana to view the pre-built dashboards.

Run the Arc node from pre-built Docker images using Docker Compose. Init containers handle snapshot download and CL initialization on the first run.

Prerequisites

Before you begin, ensure that you’ve:

Reviewed the node requirements for hardware, software, and network endpoints
Prepared a Linux machine that meets the minimum system requirements
Installed Docker Engine 24+ with BuildKit and Docker Compose v2

Step 1: Set environment variables

The Compose file reads images from environment variables. Set the version, data directory, and image references. See node requirements for the current version:

export ARC_VERSION=0.8.0
export ARC_HOME=~/.arc
export ARC_EXECUTION_IMAGE=docker.cloudsmith.io/circle/arc-network/arc-execution:$ARC_VERSION
export ARC_CONSENSUS_IMAGE=docker.cloudsmith.io/circle/arc-network/arc-consensus:$ARC_VERSION

To build images locally instead of pulling from Cloudsmith, see Installation: Docker in the arc-node repository.

Step 2: Prepare the data directory

Create $ARC_HOME on the host before starting Docker Compose. If you skip this, Docker creates it as root and the snapshot init container fails with permission errors:

mkdir -p "${ARC_HOME:-$HOME/.arc}"

Step 3: Download the Compose file

Fetch the docker-compose.yml for your release into a working directory:

curl -O https://raw.githubusercontent.com/circlefin/arc-node/v${ARC_VERSION}/deployments/docker-compose.yml

Step 4: Start the node

From the directory containing docker-compose.yml:

docker compose up -d

On the first run, init containers automatically:

Download the latest testnet snapshots (approximately 84 GB compressed; see snapshot download size)
Initialize the consensus layer private key
Prepare the shared IPC socket volume

Subsequent runs detect that initialization is already complete and start immediately. The init container runs as root so it can set file ownership for the EL and CL services (UID 999). No manual chown is needed.

Step 5: Verify the node is syncing

On the first run, wait for the snapshot init container to finish:

docker compose logs -f arc-snapshots

Once the EL and CL containers are up, wait roughly 30 seconds, then query the latest block height:

curl -s -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1 }'

The result field is a hexadecimal block number that increases over time. If it stays at 0x0, check the logs:

docker compose logs -f

The containers expose Prometheus metrics on the host at localhost:9001/ (Execution Layer, root path) and localhost:29000/metrics (Consensus Layer). To scrape these endpoints with a local stack, see Set up Prometheus and Grafana for an Arc node.

Step 6: Stop and reset

To stop the node while preserving data:

docker compose down

Node data persists in ~/.arc/ (or the path set by $ARC_HOME). To remove all data and start fresh:

docker compose down -v
rm -rf ~/.arc

docker compose down -v removes the named sockets volume, and rm -rf ~/.arc permanently deletes the consensus layer private key, which is your node’s network identity and can’t be recovered.

Run on separate hosts

The preceding tabs describe running the Execution Layer and Consensus Layer on the same host, communicating through IPC sockets. To run them on separate hosts, swap IPC for authenticated RPC. This section applies to the binary install paths (arcup and source build); the Docker path is single-host by default.

The RPC/HTTP transport between the Consensus Layer and Execution Layer is deprecated in v0.8.0 and will be removed in v0.9.0. IPC is the recommended transport for single-host deployments. Multi-host deployments should plan to migrate before v0.9.0.

Generate a JWT secret

The EL and CL authenticate to each other with a shared JWT secret. Generate it once, then securely copy it to both hosts:

openssl rand -hex 32 | tr -d "\n" > "$ARC_HOME/jwtsecret"
chmod 600 "$ARC_HOME/jwtsecret"

Execution layer flags for RPC mode

Remove the IPC flags (--ipcpath, --auth-ipc, --auth-ipc.path) from the EL command and add:

--authrpc.addr 0.0.0.0 \
--authrpc.port 8551 \
--authrpc.jwtsecret "$ARC_HOME/jwtsecret"

--authrpc.addr 0.0.0.0 exposes port 8551 on every network interface. Restrict access with a firewall rule or private network—the Engine API controls block production and must not be reachable from the public internet.

Consensus layer flags for RPC mode

Remove --eth-socket and --execution-socket from the CL command, and add:

--eth-rpc-endpoint http://<EL_HOST>:8545 \
--execution-endpoint http://<EL_HOST>:8551 \
--execution-jwt "$ARC_HOME/jwtsecret"

Replace <EL_HOST> with the IP address or hostname of the EL host.

IPC and RPC are mutually exclusive. Use one or the other, not both.

Tune backpressure

The preceding tabs start the Consensus Layer with backpressure enabled at the default threshold (16). Backpressure throttles execution to match the speed of disk writes, bounding Execution Layer memory growth during startup or extended sync when the node is far behind.If you observe sustained memory pressure on a host that meets the node requirements, restart the Consensus Layer with a lower threshold:

--execution-persistence-backpressure \
--execution-persistence-backpressure-threshold=10

Migrate to V2 storage

v0.8.0 upgrades Reth to v2.2.0, which introduces a V2 on-disk storage layout for the Execution Layer. Migration is not required for v0.8.0 but will be required for v0.9.0. Migrating now is recommended so the next upgrade does not require it.Fresh installs bootstrapped from the Circle-provided snapshots are already in V2 format. No migration is needed.Upgrading from v0.7.x requires either restoring from a V2 snapshot (the simplest path) or migrating the existing datadir in place:

Restoring from a V2 snapshot: stop the node, clear $ARC_EXECUTION, and re-run the snapshot download steps in this guide.
Migrating in place: use arc-node-execution db migrate-v2 as described in the following section.

Migrate in place

Stop the CL first, then stop the EL. Note the current head block number.
Run the migration. --datadir must precede migrate-v2:
arc-node-execution db \ --datadir "$ARC_EXECUTION" \ --chain arc-testnet \ migrate-v2
Pass --chain arc-mainnet if your node is on mainnet. A successful run exits with Migration complete. You should now restart the node and let it run the pipeline to rebuild the remaining data.
Restart the EL alone (keep the CL stopped) with the pruning flag that matches your datadir (--full, --minimal, or omit for archive). Using the wrong flag causes a rebuild failure:
arc-node-execution node \ --chain arc-testnet \ --datadir "$ARC_EXECUTION" \ --full \ --disable-discovery \ --http \ --http.api eth,net,web3,txpool,trace,debug
The node rebuilds index tables cleared during migration. Wait until it returns to the head block number you noted in step 1.
Verify the rebuilt node is at tip (eth_syncing returns false) and that re-running migrate-v2 is a no-op (Storage is already v2, nothing to do).
Start the CL and confirm live execution resumes.

If the migration fails and you need to roll back, restore from a v0.7.x snapshot.

​Prerequisites

​Step 1: Install with arcup

​Step 2: Set environment variables

​Step 3: Create data directories

​Step 4: Download blockchain snapshots

​Step 5: Initialize the consensus layer

​Step 6: Start the execution layer

​Step 7: Start the consensus layer

​Step 8: Verify the node is syncing

​Prerequisites

​Step 1: Install build dependencies

​Step 2: Clone the repository

​Step 3: Build and install

​Step 4: Set environment variables

​Step 5: Create data directories

​Step 6: Download blockchain snapshots

​Step 7: Initialize the consensus layer

​Step 8: Start the execution layer

​Step 9: Start the consensus layer

​Step 10: Verify the node is syncing

​Prerequisites

​Step 1: Set environment variables

​Step 2: Prepare the data directory

​Step 3: Download the Compose file

​Step 4: Start the node

​Step 5: Verify the node is syncing

​Step 6: Stop and reset

​Run on separate hosts

​Generate a JWT secret

​Execution layer flags for RPC mode

​Consensus layer flags for RPC mode

​Tune backpressure

​Migrate to V2 storage

​Migrate in place

Prerequisites

Step 1: Install with `arcup`

Step 2: Set environment variables

Step 3: Create data directories

Step 4: Download blockchain snapshots

Step 5: Initialize the consensus layer

Step 6: Start the execution layer

Step 7: Start the consensus layer

Step 8: Verify the node is syncing

Prerequisites

Step 1: Install build dependencies

Step 2: Clone the repository

Step 3: Build and install

Step 4: Set environment variables

Step 5: Create data directories

Step 6: Download blockchain snapshots

Step 7: Initialize the consensus layer

Step 8: Start the execution layer

Step 9: Start the consensus layer

Step 10: Verify the node is syncing

Prerequisites

Step 1: Set environment variables

Step 2: Prepare the data directory

Step 3: Download the Compose file

Step 4: Start the node

Step 5: Verify the node is syncing

Step 6: Stop and reset

Run on separate hosts

Generate a JWT secret

Execution layer flags for RPC mode

Consensus layer flags for RPC mode

Tune backpressure

Migrate to V2 storage

Migrate in place