Pathfinder Node

Install and synchronize Pathfinder on Starknet Mainnet.

Mainnet · SN_MAIN · Pathfinder v0.24.2

Run each command separately in the same shell. The configuration below uses a persistent data directory and a private local RPC endpoint.

Install Docker

On a fresh Ubuntu 24.04 server, use the following package installation. For a server with an existing container runtime, check Docker’s compatibility instructions first.

Refresh packages

Refresh APT metadata.

sudo apt update

Install basic tools

Install download and JSON tools.

sudo apt install -y ca-certificates curl jq

Create the key directory

Prepare Docker’s signing-key location.

sudo install -m 0755 -d /etc/apt/keyrings

Download the signing key

Get the Docker repository key.

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc

Set key permissions

Allow APT to read the public key.

sudo chmod a+r /etc/apt/keyrings/docker.asc

Add the package repository

Configure the official stable Ubuntu repository.

sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

Refresh the new repository

Load Docker’s package list.

sudo apt update

Install Docker

Install Engine and Compose from the configured repository.

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Enable Docker

Start the runtime and enable it on boot.

sudo systemctl enable --now docker

Configure Pathfinder

Create the project directory

Keep configuration and persistent data together.

mkdir -p "$HOME/pathfinder-mainnet/data"

Open the directory

Run Compose commands from this directory.

cd "$HOME/pathfinder-mainnet"

Store your Ethereum WebSocket URL

Enter your private Mainnet wss:// endpoint at the prompt; it will not be echoed.

read -rsp "Ethereum WebSocket URL: " ETHEREUM_URL; printf "\n"

Write the private environment file

Store the endpoint with permissions restricted to your Linux account.

(umask 077; printf 'PATHFINDER_ETHEREUM_API_URL=%s\n' "$ETHEREUM_URL" > pathfinder.env)

Clear the shell variable

Remove the temporary copy from the shell.

unset ETHEREUM_URL

Write the Compose configuration

Pin the image and keep the database outside the container.

cat > compose.yaml <<EOF
services:
  pathfinder:
    image: swmansion/pathfinder:v0.24.2
    container_name: pathfinder-mainnet
    user: "$(id -u):$(id -g)"
    restart: unless-stopped
    stop_grace_period: 2m
    env_file:
      - pathfinder.env
    environment:
      RUST_LOG: info
    ports:
      - "127.0.0.1:9545:9545"
    volumes:
      - ./data:/usr/share/pathfinder/data
    command:
      - --network=mainnet
      - --http-rpc=0.0.0.0:9545
      - --storage.state-tries=100
    logging:
      driver: json-file
      options:
        max-size: "20m"
        max-file: "5"
EOF

This configuration retains recent state tries while keeping block history. For historical storage proofs, choose --storage.state-tries=archive before creating the database and provision extra storage. Use a snapshot with a matching mode.

Download the image

Fetch the pinned release.

sudo docker compose pull pathfinder

Optional: start from a snapshot

Follow Snapshots before first startup. Otherwise Pathfinder synchronizes from the network.

Start the node

Create the container and begin synchronization.

sudo docker compose up -d pathfinder

Follow logs

Check network selection and progressing blocks.

sudo docker compose logs --tail 100 -f pathfinder

Verify chain ID

Expected result: 0x534e5f4d41494e (SN_MAIN).

curl -fsS http://127.0.0.1:9545/rpc/v0_10 -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","method":"starknet_chainId","params":[],"id":1}' | jq

Check sync

An object reports progress; false means the node has caught up. Confirm block height also advances.

curl -fsS http://127.0.0.1:9545/rpc/v0_10 -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","method":"starknet_syncing","params":[],"id":1}' | jq

Check block height

Repeat after a short interval to confirm new blocks arrive.

curl -fsS http://127.0.0.1:9545/rpc/v0_10 -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","method":"starknet_blockNumber","params":[],"id":1}' | jq

Setup reference · Configuration reference.