Setup a full Node for StarkNet, for direct access to the StarkNet layer 2 network. Using Docker compose with Pathfinder or Juno clients.

(document last update: 1/8/23)

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

Full Node: a full node, this is the L2 equivalent of a full node on Ethereum, which connects to other full nodes via peer-to-peer networking, stores full blockchain data and verifies all blocks and states. There are a few clients for a full node on StarkNet

Pathfinder: by Eqlabs is a full node implementation written in Rust.

Juno: by Nethermind is a full node implementation written in Golang.

Hardware Requirements: Recommended RAM 8GB, CPU 4core, Storage: 100GB (starting)

Ubuntu 20.04 LTS installed

Access to an Ethereum Full Node

Ports:

Juno: RPC 6060, ws 6061,
Pathfinder: RPC 9545, ws 9546

Method 1: Deployment Script (Easy)

for easy deployment, you can run this script (based of this guide), installs dependencies, select which client and Ethereum endpoint and auto configures the node for you based on client selection

Method 2: Manual Build with Docker

1. Initial Setup

Install Prerequisite software

Update System

sudo apt update && sudo apt upgrade -y

Install Docker & Docker-compose

Remove any existing installation

sudo apt-get remove docker docker-engine docker.io containerd runc

Install Docker & Docker-compose via script

sudo apt install curl -y
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

Remove the script, and add your user to the docker group, for use without sudo

sudo rm -r get-docker.sh 
sudo usermod -aG docker $USER

Requires a Restart to work, then check installed with

docker --version
docker compose version

2. Get an Ethereum L1 endpoint

StarkNet requires a connection to an Ethereum Node, as it is a layer 2 on top of Ethereum. There are a few ways to achieve this

Option 1: Use your own node (recommended)

Set up an Ethereum full node

If you don’t have access to a full node for Ethereum, which consists of and Execution and Consensus client, You can use an easy node deployment tool such as Nethermind Sedge.

Note: it may take a while to sync depending on hardware used (quality of SSD & RAM), from 12 hours to a few days.

Host node on the same device

You shouldn’t have to do anything for ports or on firewall. The following are the arguments and changes to the docker-compose.yml file for later in Step 3.

#for Pathfinder
--ethereum.url 'http://localhost:8545'
or 
--ethereum.url 'ws://localhost:8546'

#For Juno (requires ws)
--eth-node 'ws://localhost:8546'

NOTE: 8545 is the default RPC port, 8546 is the default ws port, if Ethereum node is configured for a different port then change accordingly.

Sedge Users: If you used Sedge to deploy the eth-node the default may be different you can find the port here under /<sedge-working-folder-path>/docker-compose.yml

Networks: If you are using a local node deployed via Sedge, I found in order to get it too work I had to add the following to `docker-compose.yml`, under ` starknet-node:` service

network_mode: "host"

Node on a separate (local) device

Normally: Keep 8545 (or 8000-9000 for CL) closed except for the trusted machines - this is the JSON RPC port which gives admin access to the node.

You are advised to open the port to your StarkNet node IP like so, from your Ethereum Node. were going to allow only to our own IP. What this does is exposes our Ethereum node only to a trusted device hosting the L2 node.

sudo ufw allow <PORT> from <ip of destination device>
sudo ufw enable

If you still have problems connecting, you may need to Port forward from your router. This will vary based on your ISP and router, check the manual.

Option 2: Use a 3rd party service (not recommended)

You can get an L1 endpoint URL from providers such as Alchemy/Infura/ and others, note that these are centralised endpoints where the node is hosted by someone else.

StarkNet calls to L1 node generally exceed the free tier with Infura or similar services, but this is useful for testing deployment and initial syncing, but for production use I would not recommend using unless paying for a higher tier, in which case it would make sense just to host your own node.

This is the to be used in configuration later

NOTE: for Juno Client use the websocket endpoint which will look like this

3. Configure Node

Make a working directory

mkdir -p starknet-node/data

Grant permissions to folder

sudo chown -R 1000:1000 starknet-node/data

Create configuration file for docker compose

nano starknet-node/docker-compose.yml

Now copy the chosen client configuration templates into this file, replace accordingly

Option 1: Configure for Pathfinder client

Find the latest release from here:

version: '3.3'
services:
    starknet-node:
        image: 'eqlabs/pathfinder:v0.6.7'
        user: 1000:1000
        restart: always
        stop_grace_period: 30s
        network_mode: "host"
        volumes:
            - /home/$USER/starknet-node/data:/usr/share/pathfinder/data
        ports:
            - '0.0.0.0:9545:9545'
            - '0.0.0.0:9546:9546'
        command:
            --data-directory "/usr/share/pathfinder/data"
            --ethereum.url "<ETH-NODE-ADDRESS>"
            --network "mainnet"
            --rpc.websocket
            --http-rpc "0.0.0.0:9545"
        environment:
            - RUST_LOG=info
            - PATHFINDER_RPC_WEBSOCKET=0.0.0.0:9546
        logging:
          driver: json-file
          options:
            max-size: 10m
            max-file: "10"

Option 2: Configure for Juno client

Find the latest release from here:

version: '3.3'
services:
    starknet-node:
        image: 'nethermindeth/juno:v0.4.0'
        user: 1000:1000
        restart: always
        stop_grace_period: 30s
        network_mode: "host"
        volumes:
            - /home/$USER/starknet-node/data:/var/lib/juno
        ports:
            - '0.0.0.0:6060:6060'
            - '0.0.0.0:6061:6061'
        command:
            --db-path '/var/lib/juno'
            --eth-node '<ETH-NODE-ADDRESS>'
            --log-level 'info'
            --network 'mainnet'
            --http-port '6060' 
            --ws-port '6061'
        logging:
          driver: json-file
          options:
            max-size: 10m
            max-file: "10"

4. Run the node

cd starknet-node
docker compose up -d

view logs

docker compose logs -f starknet-node

If your node can successfully connect to an L1 endpoint, it will start to sync blocks

Other commands

Check running containers

docker ps -a

Stop the node

docker compose down       #from working dir
# or 
docker stop <container name> && docker rm <container name>

Check space

sudo du -sh starknet-node/data

Additional options

Using --help will display available options:

#for pathfinder
sudo docker run --rm -it eqlabs/pathfinder:latest --help
#for juno
sudo docker run --rm -it nethermindeth/juno:latest --help

Updating Client version

Stop Node

cd starknet-node
docker compose down

Check latest releases for pathfinder or for Juno

Edit the image version with corresponding image tag

Restart node and check logs

docker compose up -d
docker compose logs -f starknet-node

Using Snapshot (optional)

Snapshot: is blockchain data hosted by a provider which can be manually downloaded without having to sync from other peers, this is much faster however it is a trusted option.

Pathfinder client

PENDING

Juno client

Nethermind host snapshots here: NOTE: edit file-name accordingly, based on latest snapshot data file

Edit `docker-compose.yml

          volumes:
            - /home/$USER/starknet-node/data/juno_mainnet/:/var/lib/juno

Download and unpack data (from working directory starknet-node)

cd data
wget https://juno-snapshot.s3.us-east-2.amazonaws.com/mainnet/juno_mainnet_v0.4.0_100713.tar
tar -xvf juno_mainnet_v0.4.0_100713.tar
rm juno_mainnet_v0.4.0_100713.tar