A complete installation guide from scratch

---

NOTE: THIS GUIDE IS OUT OF DATE, PLEASE SEE THIS ONE INSTEAD (16/3/23)

---

Pathfinder is the first implementation of a full node on StarkNet, developed by eqlabs. Nethermind and Erigon are two other teams working on various node implementations for StarkNet.

StarkNet

A permissionless & decentralised ZK-Rollup which operates as Layer 2 over Ethereum. StarkNet supports scale, while preserving the security of L1 Ethereum by producing STARK proofs off-chain, and then verifying those proofs on-chain.

Types of Node on StarkNet

Sequencer: The main node of the StarkNet network. It implements the core functionality of sequencing transactions submitted to it. It executes the StarkNet OS Cairo program with the relevant inputs, proves the result using the Proving Service or some internal STARK prover, and eventually updates the network state on the StarkNet Core Contract.

Verifier: A node in the StarkNet network that is used only for querying the current StarkNet state, equivalent to a non validating/mining full node on Ethereum. It can independently (i.e., without/o querying additional nodes) answer queries about the current state of the StarkNet network, including the L1 state. It does not batch transactions or prove batches.

Prover: A separate process (either an online service or internal to the node) that receives the output of Cairo programs and generates STARK proofs to be verified. The Prover submits the STARK proof to the verifier that registers the fact on L1.

Right now we have a full node the equivalent of Ethereum’s non validating (mining) node which verifies the state, this is required for dapps and wallets to point to in order to interact with the chain. A Permissionless Sequencer and Prover will be available in future.

This guide is intended to get you running a StarkNet Pathfinder full node on Mainnet, for beginners with little Linux experience or anyone curious about running StarkNet, assuming a fresh install of Ubuntu 20.04 LTS on a local device, if we have this skip to Part 2.

I recommend running Locally on a Laptop or home computer, we need spare device that we can use as a dedicated server for our node, new SSD of 500G for our Linux OS and storage (unless your happy to use the existing one) and a pen drive of at least 16G. I got this working on old Toshiba laptop with a 250GB SSD and 16G of RAM.

preferably something with a LAN connection. You can run Ubuntu in a shell within your windows system or on a VPS, but I prefer to make a dedicated device and run locally advantages of this are supporting decentralization and reducing surface for error.

Part 1. Preparing a Device with Ubuntu

Getting Ubuntu Ready from windows, we need to make a boot-able USB with an Ubuntu installation image. We can download the image from here download Ubuntu 20.04.4 LTS, this will be an .iso file that we need to write to a USB.

Download Rufus from here this is software we can use to write the .iso file to our pen drive and make it boot-able.

Insert your pen drive into your PC and right click Run as administrator on the Rufus .exe file, select the Ubuntu .iso file as our boot selection and the pen drive as our device, like so

Format our SSD

You may need some adapter such as this. Connect our SSD intended to host our Ubuntu OS to our PC, you should find the drive in ‘this pc’ folder on windows take note of the drive location.

Search ‘disk management’ on your windows search bar, right click ‘format’ on our intended drive

Select the File System (usually NTFS) in the dialogue that appears and enter the Allocation Unit Size (usually 4096) and check Perform a quick format

Boot Ubuntu on our Device

Insert your empty and formatted SSD into your Device and your Pen drive with the Ubuntu image to your device. If you boot we should see something like this

select install Ubuntu and follow the on screen instructions to install.

Part 2. Install Prerequisite Software

Navigate the UI and open the Terminal (usually save to favourites, as we use frequently). Using apt to install most packages, the -y command assumes yes to the any prompts during the install.

Install Git and Curl

sudo apt update
sudo apt install curl git -y

Install Docker

curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

Grant Permissions for docker and confirm it is installed

sudo usermod -aG docker $USER
docker --version

Install Docker Compose

docker-compose is a way of saving the docker run command in a file, so that you can just start/stop/modify it easily. Going to be using this for this guide.

sudo apt install docker-compose -y

docker-compose --version

Install Rust

We need to install Rust as pathfinder is built with this language, the following installs cargo a package manager for Rust and rustc the compiler for Rust.

Rust Needs to be Ver 1.58 or higher, otherwise you get problems Install with the following command to get the latest version.

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

You will see the following, type 1 for default install.

Close the Terminal session and reopen a new one, run the following commands to confirm version and installation.

Install Python

Ubuntu 20.04 LTS comes with Python installed, check that we have version 3.7 or 3.8 currently only these versions are compatible with pathfinder.

Ubuntu 20.04.0 LTS contains python 3.8.2 which is working if your distribution has a newer version you may run into problems and need to revert back.

python3 --version

if for some reason we don’t have this we can install with

sudo apt install python3=v3.8.2

Install the following

sudo apt install python3-venv -y				
sudo apt install python3-dev -y

Install build dependencies

sudo apt install build-essential
sudo apt install libgmp-dev
sudo apt install pkg-config
sudo apt install libssl-dev

Part 3. Get an ETH 1 Endpoint

StarkNet’s Pathfinder node is a full node implementation and requires a full archival node on ETH 1 to validate against (at least for now). Why this is the case; StarkNet is a Layer 2 that ‘checkpoints’ to the Layer 1 chain to inherit Ethereum’s security, from the docs

StarkNet L1 Core Contract: This L1 contract defines the state of the system by storing the commitment to the L2 state. The contract also stores the StarkNet OS program hash – effectively defining the version of StarkNet the network is running. The committed state on the L1 core contract acts as provides as the consensus mechanism of StarkNet, i.e., the system is secured by the L1 Ethereum consensus. In addition to maintaining the state, the StarkNet L1 Core Contract is the main hub of operations for StarkNet on L1. Specifically:

1. It stores the list of allowed verifiers (contracts) that can verify state update transactions

2. It facilitates L1 ↔ L2 interaction

Options for this are use an Infura endpoint or Pokt Network (i’m looking into adding using this as an option to the guide).

Using Infura

simply sign up for Infura service here navigate to sign up and create an account, once done click on ‘create new project’

Take note of the Endpoints, Project ID and Secret and click save changes once done.

Part 4. Download and Run Pathfinder Node

Using Docker Compose

First we want to create a directory to place our docker-compose.yml this is the run command for docker, also a our config file. I placed a folder called pathfinder in my home folder like so, you would replace glc with your username.

mkdir /home/glc/pathfinder	

Create a folder for our data

mkdir /home/glc/pathfinder/data	

Create our config file.

nano /home/glc/pathfinder/docker-compose.yml

This will open the text editor on our terminal, and we can paste the following text into the terminal. Use CTRL + o to write out, then exit with CTRL + x

version: "3.7"
services:

  pathfinder:
    hostname: pathfinder
    container_name: pathfinder
    image: eqlabs/pathfinder:v0.2.1-alpha
    restart: always
    stop_grace_period: 1m
    networks:
      - net
    ports:
      - 9545:9545
    volumes:
      - /home/glc/pathfinder/data:/usr/share/pathfinder/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    environment:
      - RUST_LOG=info
      - PATHFINDER_ETHEREUM_API_URL=<PLACE YOUR ENDPOINT HERE>
    logging:
      driver: "json-file"

networks:
  net:
    external: false

IMPORTANT: spacing is really important here, I’ve got this to be easily copy and pasted into a .txt file with the right syntax then pasted into our terminal on our Ubuntu device.

commented out some unneeded lines, unnecessary for this build such as Ethereum password which we don’t have or need, and Networks part is for connecting other containers.

Image: the current working image is “eqlabs/pathfinder:v0.1.6-alpha” you may find that latest will have errors, as it’s a work in progress, should this change, you can update to a newer version by replacing this. check the discord for the latest working version.

Restart: this is to ensure your container is set to restart should your device restart, so it’s always running the background unless stopped

Ports: defines our container ports, can change this should you have another container on the same port.

Logs: more info https://docs.docker.com/config/containers/logging/local/

Ethereum Endpoint url: place your Ethereum url here from Step 3.

Volumes: persistent storage, points to the folder we created earlier. This is to keep the chain state/data so we don’t have to sync from start again should we update or stop our node.

Starting the docker container and logs

from the directory of our docker-compose.yml file, change according to your working directory.

cd /home/glc/pathfinder

Start the container with

docker-compose up -d

Check running containers with

docker ps -a

To output the Logs run

 docker logs -f <container name>

If its the first time run, it will pull the image from the git repository, your logs should look something like this if functioning correctly.

You should see calls to your Infura node on your account dashboard like so, after a few hours

Updating Pathfinder Version

To update your container to the latest version, check the discord and GitHub for the latest.

stop and remove running container, which is pathfinder

docker stop <container name> && docker rm <container name>

you shouldn’t see anything running if you check running containers

docker ps -a

Delete older versions

docker system prune -a

open your config and replace the version with the latest image or ‘latest’

sudo nano /home/glc/pathfinder/docker-compose.yml

go back to working directory and start the container again

cd /home/glc/pathfinder
docker-compose up -d