Skip to content

Beerus is a trustless StarkNet Light Client, ⚡blazing fast ⚡ and powered by Rust 🦀

License

Notifications You must be signed in to change notification settings

Godspower-Eze/beerus

 
 

Repository files navigation


GitHub Workflow Status Project license Pull Requests welcome

Table of Contents

Roadmap

We have big plans for Beerus. Check out the Roadmap!

Beerus Roadmap

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.

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

Endpoint support

Here are all the endpoints supported by Beerus in tag v0.2.0

Starknet endpoints (20) (in compliance with Starknet specs):

Endpoint Supported
starknet_getBlockWithTxHashes
starknet_getBlockWithTxs
starknet_getStateUpdate
starknet_getStorageAt
starknet_getTransactionByHash
starknet_getTransactionByBlockIdAndIndex
starknet_getTransactionReceipt
starknet_getClass
starknet_getClassHashAt
starknet_getClassAt
starknet_getBlockTransactionCount
starknet_call
starknet_estimateFee
starknet_blockNumber
starknet_blockHashAndNumber
starknet_chainId
starknet_pendingTransactions
starknet_syncing
starknet_getEvents
starknet_getNonce

Ethereum endpoints (21) (in compliance with Helios specs):

Endpoint Supported
eth_getBalance
eth_getTransactionCount
eth_getCode
eth_call
eth_estimateGas
eth_getChainId
eth_gasPrice
eth_maxPriorityFeePerGas
eth_blockNumber
eth_getBlockByNumber
eth_getBlockByHash
eth_sendRawTransaction
eth_getTransactionReceipt
eth_getLogs
eth_getStorageAt
eth_getBlockTransactionCountByHash
eth_getBlockTransactionCountByNumber
eth_coinbase
eth_syncing
eth_getTransactionByHash
eth_getTransactionByBlockHashAndIndex

Additional endpoints (8):

Endpoint Supported
starknet_l1_to_l2_messages
starknet_l1_to_l2_message_nonce
starknet_l1_to_l2_message_cancellations
starknet_l2_to_l1_messages
starknet_addDeclareTransaction
starknet_addDeployAccountTransaction
starknet_getContractStorageProof
starknet_addInvokeTransaction

Getting Started

Installation

Beerusup

To install with beerusup:

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

Build

cargo build --all --release

Build beerus-core for WASM:

cargo build -p beerus-core --no-default-features --target wasm32-unknown-unknown --release

Test

cargo test --all

Config

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).

Ethereum execution layer RPC URL (must be an Ethereum provider that supports the eth_getProof endpoint).

Ethereum consensus layer RPC URL (must be a consensus node that supports the light client beacon chain api)

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.

Env Var TOML Mainnet Goerli
ETHEREUM_NETWORK ethereum_network mainnet goerli(default)
ETHEREUM_EXECUTION_RPC_URL ethereum_consensus_rpc https://eth-mainnet.g.alchemy.com/v2/XXXXX https://eth-goerli.g.alchemy.com/v2/XXXXX
ETHEREUM_CONSENSUS_RPC_URL ethereum_execution_rpc https://www.lightclientdata.org http://testing.prater.beacon-api.nimbus.team
STARKNET_RPC_URL starknet_rpc https://starknet-mainnet.infura.io/v3/XXXXX https://starknet-goerli.infura.io/v3/XXXXX

To speed up the launch of the Ethereum client, it is recommended to set a more recent checkpoint. You can find one, for example, at this link: https://sync.invis.tools/.

Env Var TOML Mainnet
ETHEREUM_CHECKPOINT ethereum_checkpoint 0x419347336a423e0ad7ef3a1e8c0ca95f8b4f525122eea0178a11f1527ba38c0f
Config File

Beerus is configurable via a config toml. If you have set the env var BEERUS_CONFIG = path/to/config this will override all other environment variables and take configuration from values defined herein. Also the the cli can be directed via beerus --config <path/to/config>

goerli.toml

mainnet.toml

Environment Variables

Beerus is configurable through environment variables.

cp examples/.env.example .env
source .env

Examples

cargo run -p beerus-core --example basic

Using config from .toml file

BEERUS_CONFIG=path/to/config.toml cargo run -p beerus-core --example basic

Using Beerus as a Library

Beerus can be imported into any Rust project.

use beerus_core::{config::Config, lightclient::beerus::BeerusLightClient};
use env_logger::Env;
use eyre::Result;

#[tokio::main]
async fn main() -> Result<()> {
  env_logger::Builder::from_env(Env::default().default_filter_or("info")).init();
  let config = Config::from_env();

  let mut beerus = BeerusLightClient::new(config.clone()).await?;
  beerus.start().await?;

  let current_starknet_block = beerus.starknet_lightclient.block_number().await?;
  println!("{:?}", current_starknet_block);

  let current_ethereum_block = beerus
          .ethereum_lightclient
          .lock()
          .await
          .get_block_number()
          .await?;
  println!("{:?}", current_ethereum_block);
  Ok(())
}
Beerus RPC
cargo run --bin beerus-rpc
Beerus JS(wasm demo)

Dependencies:

  • npm
  • CORS bypass
  • local pathfinder node at http://localhost:9545
  • execution env var - ETHEREUM_EXECUTION_RPC_URL
cd crates/beerus-js

# install node deps
npm i

# build webpack & wasm modules
npm run build

# run example
./run.sh

# navigate browser to http://localhost:8080
# open developer console

Work in progress

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!

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.

Acknowledgements

  • Huge props to A16z for their work on helios.

Contributors ✨

The contributors page.

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

💻
Tom Brand
Tom Brand

💻
ftupas
ftupas

💻
pscott
pscott

💻
Robin Straub
Robin Straub

💻
Francisco Krause Arnim
Francisco Krause Arnim

📖
joshualyguessennd
joshualyguessennd

📖
Santiago Galván (Dub)
Santiago Galván (Dub)

💻
chirag-bgh
chirag-bgh

💻
greged93
greged93

💻
bigherc18
bigherc18

💻
Lakhdar Slaim
Lakhdar Slaim

💻
Lance N. Davis
Lance N. Davis

💻
Tino Huynh
Tino Huynh

💻
Iris
Iris

💻
Alex Ponce
Alex Ponce

💻
glihm
glihm

💻
Paul-Henry Kajfasz
Paul-Henry Kajfasz

💻
Damián Piñones
Damián Piñones

💻
Betacodd
Betacodd

💻
Add your contributions

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

About

Beerus is a trustless StarkNet Light Client, ⚡blazing fast ⚡ and powered by Rust 🦀

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Rust 93.6%
  • Handlebars 3.7%
  • Shell 2.1%
  • Other 0.6%