{"id":13803322,"url":"https://github.com/lambdaclass/stark_compass_explorer","last_synced_at":"2025-05-13T15:33:09.915Z","repository":{"id":178473744,"uuid":"658840243","full_name":"lambdaclass/stark_compass_explorer","owner":"lambdaclass","description":"Stark Compass: the only open source explorer","archived":false,"fork":false,"pushed_at":"2024-08-02T15:04:56.000Z","size":4559,"stargazers_count":67,"open_issues_count":60,"forks_count":23,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-08-04T01:02:16.596Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://starkcompass.com","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lambdaclass.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-26T15:40:54.000Z","updated_at":"2024-08-04T01:02:27.776Z","dependencies_parsed_at":"2023-10-13T03:01:02.053Z","dependency_job_id":"35438002-830e-4f81-9fa6-3ea0dfcbfdf0","html_url":"https://github.com/lambdaclass/stark_compass_explorer","commit_stats":null,"previous_names":["lambdaclass/starknet_explorer","lambdaclass/madara_explorer"],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaclass%2Fstark_compass_explorer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaclass%2Fstark_compass_explorer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaclass%2Fstark_compass_explorer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaclass%2Fstark_compass_explorer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lambdaclass","download_url":"https://codeload.github.com/lambdaclass/stark_compass_explorer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225239738,"owners_count":17442821,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T01:00:28.929Z","updated_at":"2024-11-18T19:31:32.372Z","avatar_url":"https://github.com/lambdaclass.png","language":"Elixir","funding_links":[],"categories":["Resources"],"sub_categories":[],"readme":"# StarkCompass\n![image](./priv/static/images/explorer_preview.png)\n\n- [StarkCompass](#starkcompass)\n  - [Archival Notice](#archival-notice)\n  - [Requirements](#requirements)\n  - [Local development](#local-development)\n    - [Setup](#setup)\n    - [RPC Provider](#rpc-provider)\n    - [RPC with Juno](#rpc-with-juno)\n    - [Up and running](#up-and-running)\n  - [State Synchronization System](#state-synchronization-system)\n    - [WARNING ⚠️](#warning-️)\n  - [Using Stark Compass with PostgreSQL](#using-stark-compass-with-postgresql)\n  - [Remaining Tasks](#remaining-tasks)\n    - [Short/Mid Term Goals:](#shortmid-term-goals)\n    - [Long Term Goals:](#long-term-goals)\n  - [Contributing](#contributing)\n    - [Get in Touch](#get-in-touch)\n\n## Archival Notice\n\n**StarkCompass is now archived.**\nThis 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](https://github.com/lambdaclass/cairo-vm) and [Cairo Native](https://github.com/lambdaclass/cairo_native).\n\n## Requirements\n- SQLite\n- Erlang 25\n- Elixir 1.15, compiled with OTP 25\n- Docker (optional)\n- PostgreSQL (optional)\n\n## Local development\n\nIf you run `make` it will print out the available targets:\n```\n% make\nUsage:\n    run   : Starts the Elixir backend server.\n    setup : Sets up everything necessary to build and run the explorer.\n    deps  : Gets code dependencies.\n    db    : Runs the database creation and migration steps.\n```\n\n### Setup\nOnce you have the requirements installed and set up, you can proceed to building and running the project.\n\n```bash\nmake setup\n```\n\n### RPC Provider and Starknet Specs\n\nYou 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.\n\nTo 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](https://github.com/starkware-libs/starknet-specs/tree/v0.6.0).\n\nIn case your RPC provider only supports [starknet-specs v0.5.0](https://github.com/starkware-libs/starknet-specs/tree/v0.5.0) you can use the [Stark Compass Explorer v0.2.34.3](https://github.com/lambdaclass/stark_compass_explorer/releases/tag/0.2.34.3)\n\n\nTo 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`\n\nSet the following environment variables:\n\n```bash\nexport RPC_API_HOST=your_rpc_hostname\nexport SEPOLIA_RPC_API_HOST=sepolia_rpc_hostname\n```\n\n### RPC with Juno\n\n```bash\ndocker-compose up juno\n```\n\nYou'll need a Mainnet Ethereum RPC provider for this to\nwork, set with the env variable `$ETH_NODE_URL`, mind you\nit must be a websocket url.\n\n### Up and running\nIf you're on MacOS, you already have SQLite.\nOn Linux, your distro's repo will most certainly have a package for it.\nWith a working RPC set and sqlite installed, start the explorer with\n\n```bash\nmake setup run\n```\n\nThis will setup the explorer start it on `localhost:4000`.\n\nFrom now on, if you want to restart the app, you can just do:\n\n```bash\nmake run\n```\n## State Synchronization System\n\nThe 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:\n\n1. **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.\n\n2. **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.\n\n3. **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.\n\nThe synchronization process is activated by default, you can turn it off by configuring the following environment variables before launching the explorer:\n\n```bash\nexport DISABLE_MAINNET_SYNC=true\nexport DISABLE_SEPOLIA_SYNC=true\n```\n\nIt's worth noting that you have the flexibility to select which networks you want to synchronize by adjusting these environment variables.\n\n### WARNING ⚠️\n\nThere are 3 things to keep in mind here:\n1. Amount of requests:\n   If you have any constraint on how many requests you can make: keep an eye on that,\n   because the State Synchronization System can do a lot of requests per second.\n2. Disk Usage: We're still measuring it, but we expect it to be considerable\n   after running it for a couple of days.\n3. 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](#using-stark-compass-with-postgresql).\n\nThe db file will be stored under `/priv/repo`.\n\n## Using Stark Compass with PostgreSQL\n\nIf you want to handle multiple concurrent connections and a more scalable application, you may consider using PostgreSQL.\n\nStark 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`.\n\n```bash\nexport DB_TYPE=postgresql\n```\n\nIf you previously compiled the application without the flag, you need to clean the dependencies and then compile again:\n\n```bash\nmix deps.clean --all\nmix deps.get\n```\n\nA Docker image of PostgreSQL is provided in the `docker-compose.yml` file, you can get the service up and running with the command:\n\n```bash\ndocker-compose up postgres\n```\n\n## Remaining Tasks\n\n### Short/Mid Term Goals:\n\n- **Preserve Leading Zeros in Hash Storage**: Ensure that leading zeros are not removed when storing hashes in the database, or adapt the Search Bar to accommodate missing leading zeros.\n- **Customizable Branding**: Allow for the customization of logos, favicons, and navbar text.\n\n### Long Term Goals:\n\n- **Analytics**: Show statistics like TVL, historical data, plots, etc.\n\n## Contributing\n\nWe appreciate your interest in contributing to the Stark Compass Explorer! Your contributions can help make this project even better.\n\nPRs 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!\n\n### Get in Touch\n\nIf you have any questions, suggestions, or if you'd like to contribute in any way, please feel free to reach out to us:\n\n- **Telegram**: [Lambda Starknet](https://t.me/LambdaStarkNet)\n- **GitHub Issues**: [Open an Issue](https://github.com/lambdaclass/stark_compass_explorer/issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambdaclass%2Fstark_compass_explorer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flambdaclass%2Fstark_compass_explorer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambdaclass%2Fstark_compass_explorer/lists"}