Installing and Running Pathfinder (Starknet Full Node)

Pathfinder is a Rust implementation of a Starknet full node developed by Equilibrium Labs.
It provides a complete, locally verifiable view of the Starknet blockchain, allowing you to query contract state, transactions, and historical data.

In this guide, we compile Pathfinder from source rather than using Docker images.
This approach ensures:

  • Maximum performance, thanks to CPU-specific compiler optimizations.
  • Full control over your environment and dependencies.
  • Better stability for long-running validator operations.

Running a full node is the foundation of becoming a validator — it synchronizes with the Starknet network and exposes a local JSON-RPC endpoint for staking and attestation.

Requirements

Before building, make sure your system meets the following requirements:

  • CPU: 4 cores.
  • RAM: 8 GB.
  • Storage: 500 GB SSD

If you plan to operate in archive mode for historical queries or run multiple concurrent JSON-RPC requests, consider increasing CPU and memory.

Install Rust

Rust is required to build Pathfinder from source.
The following commands install Rust, enable it in your environment, and add the rustfmt component (for formatting and compatibility).

curl https://sh.rustup.rs -sSf | sh
source $HOME/.cargo/env
rustup component add rustfmt

Install Build Dependencies

Install the required system packages for compiling Rust code and working with Protocol Buffers:

apt-get install -y protobuf-compiler build-essential

Clone Pathfinder Repository

Download the official Pathfinder source code from the Equilibrium Labs GitHub repository.

cd $HOME
git clone https://github.com/eqlabs/pathfinder.git
cd pathfinder

Select a Release Tag

Define the tag you want to build (replace the value with a real version tag, e.g., v0.11.0):

export TAG=

Checkout the corresponding release:

git checkout $TAG

Build Pathfinder

Compile the Pathfinder binary with CPU optimizations for your machine. This step may take several minutes depending on your hardware.

export RUSTFLAGS='-C target-cpu=native'; cargo build --release --bin pathfinder

Organize the Release Directory

Create the target directory for your Pathfinder release, copy the compiled binary, and create a symlink for the active version.

mkdir -p $HOME/.pathfinder/releases/$TAG/bin
cp $HOME/pathfinder/target/release/pathfinder $HOME/.pathfinder/releases/$TAG/bin
ln -sf $HOME/.pathfinder/releases/$TAG $HOME/.pathfinder/active-release

Download the Latest Database Snapshot

Pathfinder requires a local Starknet state database. You can speed up sync by downloading the latest official snapshot from Equilibrium:

Snapshot URL:

https://rpc.pathfinder.equilibrium.co/snapshots/latest

Create the data directory and download the snapshot:

mkdir -p $HOME/.pathfinder/data
wget -c -o $HOME/.pathfinder/data https://rpc.pathfinder.equilibrium.co/snapshots/latest/mainnet.sqlite.zst

Decompress the snapshot file:

zstd -T0 -d $HOME/.pathfinder/data/mainnet.sqlite.zst -o $HOME/.pathfinder/data/mainnet.sqlite

Configure Environment Variables

Set your Ethereum RPC WebSocet endpoint (used for L1 data):

export ETH_RPC_URL=

Define the HTTP RPC port for Pathfinder:

export PORT=9545

Create a systemd Service

Set up a systemd unit file to manage Pathfinder as a background service. This allows automatic restarts and integration with system logs.

tee /etc/systemd/system/pathfinder.service > /dev/null <<EOF
[Unit]
Description=Starknet Mainnet Pathfinder
After=network-online.target
Wants=network-online.target

[Service]
User=root
Group=root
ExecStart=$HOME/.pathfinder/active-release/bin/pathfinder \
  --network mainnet \ 
  --http-rpc 127.0.0.1:$PORT \
  --ethereum.url=$ETH_RPC_URL\
  --monitor-address 127.0.0.1:9101 \
  --data-directory $HOME/.pathfinder/data \
  --rpc.root-version v09 \
  --rpc.websocket.enabled 

Restart=on-failure
RestartSec=5
StartLimitInterval=60
StartLimitBurst=3
LimitNOFILE=1000000

[Install]
WantedBy=multi-user.target
EOF

Here pathfinder listen to $PORT and has prometheus monitoring endpoint at 127.0.0.1:9101

Start Pathfinder

Enable the service to start on boot and launch it immediately:

systemctl enable pathfinder.service
systemctl start pathfinder.service

Monitor logs to confirm successful startup.

journalctl -o cat -fu pathfinder.service

Check Pathfinder Status

Use /ready to Pathfinder has completed all startup tasks.

curl -i http://localhost:9101/ready
  • 200 OK - The node is fully initialized and ready to serve JSON-RPC requests.
  • 503 Service Unavailable - The node is still starting up or failing a prerequisite task.

/ready/synced ensuring that Pathfinder is within six blocks of the network’s current tip. This guarantees that the node is both ready and nearly fully synced.

curl -i http://localhost:9101/ready/synced
  • 200 OK - The node is ready for requests and closely tracking the chain’s latest blocks.
  • 503 Service Unavailable - The node is still starting or more than six blocks behind the network tip.

Prometheus Metrics

The Prometheus Metrics endpoint /metrics exposes real-time operational data in the Prometheus format. These metrics cover various aspects of Pathfinder performance and can be scraped periodically by Prometheus for monitoring and alerting.

Previous
Intro
Next
Validator Selfstake