Home

Awesome

StarkCompass

image

Archival Notice

StarkCompass is now archived. This repository has been archived and is no longer actively maintained. StarkCompass remains functional and supports Starknet up to version 0.13.2. However, maintaining and updating this project requires significant effort, and we no longer have the time to dedicate to it. We have chosen to prioritize other Starknet-related projects, such as Cairo VM and Cairo Native.

Requirements

Local development

If you run make it will print out the available targets:

% make
Usage:
    run   : Starts the Elixir backend server.
    setup : Sets up everything necessary to build and run the explorer.
    deps  : Gets code dependencies.
    db    : Runs the database creation and migration steps.

Setup

Once you have the requirements installed and set up, you can proceed to building and running the project.

make setup

RPC Provider and Starknet Specs

You now have the choice of connecting the explorer to an RPC API provider of your choice, e.g. Infura with an API key, or by running your own Juno node.

To fully utilize the capabilities of the explorer, it is crucial to connect it to an RPC provider that is compatible with the starknet-specs v0.6.0.

In case your RPC provider only supports starknet-specs v0.5.0 you can use the Stark Compass Explorer v0.2.34.3

To run it locally, you'll need to set the RPC API url of the network. If you're using a provider like Infura, this will look something like this: https://starknet-mainnet.infura.io/v3/your_api_key

Set the following environment variables:

export RPC_API_HOST=your_rpc_hostname
export SEPOLIA_RPC_API_HOST=sepolia_rpc_hostname

RPC with Juno

docker-compose up juno

You'll need a Mainnet Ethereum RPC provider for this to work, set with the env variable $ETH_NODE_URL, mind you it must be a websocket url.

Up and running

If you're on MacOS, you already have SQLite. On Linux, your distro's repo will most certainly have a package for it. With a working RPC set and sqlite installed, start the explorer with

make setup run

This will setup the explorer start it on localhost:4000.

From now on, if you want to restart the app, you can just do:

make run

State Synchronization System

The State Synchronization System facilitates the population of the database with data obtained through RPC. This system is accompanied by a utility tool known as the StateSyncSystem, which serves three fundamental tasks:

  1. Listening for New Blocks: Upon application initialization, the StateSyncSystem constantly monitors the RPC for the latest block. At regular intervals, it attempts to retrieve any newly available blocks from the RPC. If a block is not already stored in the database, the system will insert it.

  2. Fetching Previous Blocks: Upon application startup, the system identifies the lowest block number currently stored in the database (if any) or, alternatively, uses the latest block from the RPC as a starting point. It then initiates a process that, at regular intervals, retrieves earlier blocks in a reverse chronological order, continuing until it reaches block 0.

  3. Updating Unfinished Blocks and Transactions: If the finality status of a block or a transaction remains unattained, the system periodically attempts to update the database by checking for any available updates.

The synchronization process is activated by default, you can turn it off by configuring the following environment variables before launching the explorer:

export DISABLE_MAINNET_SYNC=true
export DISABLE_SEPOLIA_SYNC=true

It's worth noting that you have the flexibility to select which networks you want to synchronize by adjusting these environment variables.

WARNING ⚠️

There are 3 things to keep in mind here:

  1. Amount of requests: If you have any constraint on how many requests you can make: keep an eye on that, because the State Synchronization System can do a lot of requests per second.
  2. Disk Usage: We're still measuring it, but we expect it to be considerable after running it for a couple of days.
  3. If you are going to sync a large amount of blocks, we strongly suggest to use PostgreSQL instead of SQLite. You can check how to swap the DB in this section.

The db file will be stored under /priv/repo.

Using Stark Compass with PostgreSQL

If you want to handle multiple concurrent connections and a more scalable application, you may consider using PostgreSQL.

Stark Compass provides support for that, you can set the credentials to the PostgreSQL DB in the runtime.exs and set the environment variable DB_TYPE to postgresql.

export DB_TYPE=postgresql

If you previously compiled the application without the flag, you need to clean the dependencies and then compile again:

mix deps.clean --all
mix deps.get

A Docker image of PostgreSQL is provided in the docker-compose.yml file, you can get the service up and running with the command:

docker-compose up postgres

Remaining Tasks

Short/Mid Term Goals:

Long Term Goals:

Contributing

We appreciate your interest in contributing to the Stark Compass Explorer! Your contributions can help make this project even better.

PRs are more than welcome if you want to collaborate to the project. If you don't know how to implement a feature, you are still welcome to create an issue!

Get in Touch

If you have any questions, suggestions, or if you'd like to contribute in any way, please feel free to reach out to us: