# StarkNet Pathfinder Node with Docker

By [GLCstaked](https://paragraph.com/@glcstaked) · 2022-03-22

---

**A complete installation guide from scratch**

* * *

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

[https://mirror.xyz/0xf3bF9DDbA413825E5DdF92D15b09C2AbD8d190dd/lpKUpNTbRHgqFV28My563Hgohe0trtdqaAvpozILx1s](https://mirror.xyz/0xf3bF9DDbA413825E5DdF92D15b09C2AbD8d190dd/lpKUpNTbRHgqFV28My563Hgohe0trtdqaAvpozILx1s)

* * *

Pathfinder is the first implementation of a full node on StarkNet, developed by [eqlabs](https://equilibrium.co/). [Nethermind](https://nethermind.io/) and [Erigon](https://github.com/ledgerwatch/erigon) are two other teams working on various node implementations for StarkNet.

[**StarkNet**](https://starkware.co/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.

![https://medium.com/starkware/on-the-road-to-starknet-a-permissionless-stark-powered-l2-zk-rollup-83be53640880](https://storage.googleapis.com/papyrus_images/08e032cc789550f4ec8387db8f08c269c78518702c9355162326523948253f17.png)

https://medium.com/starkware/on-the-road-to-starknet-a-permissionless-stark-powered-l2-zk-rollup-83be53640880

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](https://ubuntu.com/download/desktop) download Ubuntu 20.04.4 LTS, this will be an .iso file that we need to write to a USB.

Download Rufus from [here](https://rufus.ie/en/) 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

![Once set up click Start, will take about 5-10 mins](https://storage.googleapis.com/papyrus_images/931584cb84a143bb0df8d0110b3dbb67de51fbae6f05cd19de301545b3150807.png)

Once set up click Start, will take about 5-10 mins

**Format our SSD**

You may need some adapter such as [this](https://www.amazon.co.uk/Sabrent-2-5-Inch-Adapter-Optimized-EC-SSHD-USB-3-0-SSD-SATA-2-5/dp/B011M8YACM). 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

![](https://storage.googleapis.com/papyrus_images/e93f7bb27ef7e8ee104e716cb653b16cc60fa4c893b89022e61b19405f5cbc96.png)

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

![](https://storage.googleapis.com/papyrus_images/78885a54c7f2bca50b6ac91cbe42ad89ced7178e0012d54513dcdd9fb966fd8a.png)

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.

![](https://storage.googleapis.com/papyrus_images/c9cc28155ba22c2d1d754c546d05db8bccfca46d5b0ed632853d6db2bbf68a4a.png)

![you should see this at the end if installed successfully ](https://storage.googleapis.com/papyrus_images/dc48203a1dd925a8b2ae26a53c19889ed38a93fcfa21d09862398e11a58fbb69.png)

you should see this at the end if installed successfully

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

![](https://storage.googleapis.com/papyrus_images/81a747bae7bafab7ba28eea7572e535609f87a733184ca187a86129872b32fe6.png)

**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](https://infura.io/) navigate to sign up and create an account, once done click on ‘create new project’

![Select Ethereum but name whatever you want](https://storage.googleapis.com/papyrus_images/bb7dba8475f036a93bfecd232c18d3cc0e73bac847547ef61ccd51efaa98af57.png)

Select Ethereum but name whatever you want

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

![](https://storage.googleapis.com/papyrus_images/b57a29ae150741b424776960492652995a3eb980c6659891e823974524d4924b.png)

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/](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.

![](https://storage.googleapis.com/papyrus_images/c55bd11f64df6d0e8c5a0f9d32fbfc484d5f48d580bc3b617aee2e372ba01fff.png)

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

![](https://storage.googleapis.com/papyrus_images/f06ad986085dd5eb8839121925030ce1b670437214ed637072c943f672d1fe8c.png)

![Pathfinder Node Syncing](https://storage.googleapis.com/papyrus_images/0d84cc5ca35e048672a449808461c9f3aa64a1933139657f888def1195138016.png)

Pathfinder Node Syncing

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
    

![you can put the exact version here or 'latest'  ](https://storage.googleapis.com/papyrus_images/8eb2cd0634eb9fde3886234df0bfc11fbc1aea371a752817667fd84859f9ecff.png)

you can put the exact version here or 'latest'

go back to working directory and start the container again

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

---

*Originally published on [GLCstaked](https://paragraph.com/@glcstaked/starknet-pathfinder-node-with-docker)*