Skip to content

Latest commit

 

History

History
349 lines (253 loc) · 14.4 KB

README.md

File metadata and controls

349 lines (253 loc) · 14.4 KB

GitHub Workflow Status Project license Pull Requests welcome

Table of Contents

Report a bug

If you find a bug, please open a GitHub issue!

Request a feature

To request a new feature, please open an issue following this template.

About

Beerus is a StarkNet Light Client inspired by and using helios. The goal is to provide a simple and easy to use client to query StarkNet state and interact with contracts.

Screenshots
Screenshot 1 Screenshot 2

Built With

Architecture

Here is a high level overview of the architecture of Beerus.

Beerus architecture

Simple usage overview

Here is a simple overview of how Beerus work. The example is for querying a storage value of a StarkNet contract.

Beerus Query Contract Storage

Getting Started

Prerequisites

Installation

Beerusup

To install with beerusup run (beerusup requires nightly rustup):

curl -sL https://raw.githubusercontent.com/keep-starknet-strange/beerus/main/beerusup | sh

Environment variables

The project requires an Ethereum node and a Starknet node. For Ethereum nodes you can use Alchemy (not Infura since it does not support getProof endpoint).

For StarkNet node for the moment you can use Infura but soon verify proof will be implemented in Pathfinder nodes, and so will these nodes be working as well.

Copy the .env.example file to a .env file and populate each variable (they are all mandatory except for ETHEREUM_NETWORK which defaults to "goerli":

cp examples/.env.example .env

Meanwhile you can just use unit tests to dev.

cargo test --all

Build from source:

cargo build --all --release

The binaries will be located in target/release/. Specifically, the binary for the CLI is target/release/beerus_cli and the binary for the API is target/release/beerus_rest_api.

Specify the environment variables and run the binary.

For example to query the state root of the StarkNet network using the CLI:

source .env && ./target/release/beerus_cli starknet query-state-root
# Should output something like:
# 3018024614248707887030376849268409283849258987090518998455999582305744756580

To do the same using the API:

source .env && ./target/release/beerus_rest_api
# Then go to http://127.0.0.1:8000/starknet/state/root
# Should output something like:
{
  "state_root": "3018024614248707887030376849268409283849258987090518998455999582305744756580"
}

Configuration

Beerus is configurable through environment variables.

Here is the list of all the available environment variables:

Name Default value Description
ETHEREUM_NETWORK goerli The Ethereum network to use. Can be one of mainnet, goerli.
ETHEREUM_EXECUTION_RPC_URL No Ethereum execution layer RPC URL (must be an Ethereum provider that supports the eth_getProof endpoint)
ETHEREUM_CONSENSUS_RPC_URL No Ethereum consensus layer RPC URL (must be a consensus node that supports the light client beacon chain api)
STARKNET_RPC_URL No StarkNet RPC URL

Usage

CLI

Usage: beerus_cli [OPTIONS] <COMMAND>

Commands:
  ethereum  Ethereum related subcommands
  help      Print this message or the help of the given subcommand(s)

Options:
  -c, --config <FILE>  Sets a custom config file
  -h, --help           Print help information
  -V, --version        Print version information

Ethereum

Query balance
beerus_cli ethereum query-balance --address 0x00000000219ab540356cBB839Cbe05303d7705Fa
# 2011.286832686010020640 ETH

StarkNet

Query contract view
beerus_cli starknet query-contract --address 0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7 --selector 0x1e888a1026b19c8c0b57c72d63ed1737106aa10034105b980ba117bd0c29fe1 --calldata 0x00,0x01
[FieldElement { inner: 0x0000000000000000000000000000000000000000000000000000000000000000 }, FieldElement { inner: 0x0000000000000000000000000000000000000000000000000000000000000000 }]
Query get storage at
beerus_cli starknet query-get-storage-at --address 0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7 --key 0x341c1bdfd89f69748aa00b5742b03adbffd79b8e80cab5c50d91cd8c2a79be1
298305742194

API

[TODO]

Roadmap

See the open issues for a list of proposed features (and known issues).

Support

Reach out to the maintainer at one of the following places:

Project assistance

If you want to say thank you or/and support active development of Beerus:

  • Add a GitHub Star to the project.
  • Tweet about the Beerus.
  • Write interesting articles about the project on Dev.to, Medium or your personal blog.

Together, we can make Beerus better!

Contributing

First off, thanks for taking the time to contribute! Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated.

Please read our contribution guidelines, and thank you for being involved!

Authors & contributors

For a full list of all authors and contributors, see the contributors page.

Security

Beerus follows good practices of security, but 100% security cannot be assured. Beerus is provided "as is" without any warranty. Use at your own risk.

For more information and to report security issues, please refer to our security documentation.

License

This project is licensed under the MIT license.

See LICENSE for more information.

Acknowledgements

  • Huge props to A16z for their work on helios.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Abdel @ StarkWare
Abdel @ StarkWare

⚠️ 💻
Lucas @ StarkWare
Lucas @ StarkWare

💻
danilowhk
danilowhk

💻
Clément Walter
Clément Walter

💻
Elias Tazartes
Elias Tazartes

💻
drspacemn
drspacemn

💻
Mathieu
Mathieu

💻
TurcFort07
TurcFort07

📖
Florian Bellotti
Florian Bellotti

💻
Add your contributions

This project follows the all-contributors specification. Contributions of any kind welcome!