dpinones / beerus

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

Beerus

Report a Bug - Request a Feature - Ask a Question

Table of Contents

• Report a Bug
• Request a Feature
• Roadmap
• About
  • Built With
• Architecture
  • Simple usage overview
• Endpoint support
• Getting Started
  • Installation
    • Beerusup
    • Build
    • Test
    • Config
      • Config File
      • Environment Variables
    • Beerus RPC
      • Beerus RPC
      • Beerus JS(wasm demo)
• Work in progress
• Support
• Project assistance
• Contributing
• Security
• Acknowledgements
• Contributors ✨

---

Roadmap

We have big plans for Beerus. Check out the 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

• Rust
• helios
• ethers-rs

Architecture

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

Simple usage overview

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

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

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

• Top Feature Requests (Add your votes using the 👍 reaction)
• Top Bugs (Add your votes using the 👍 reaction)
• Newest Bugs

Support

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

• GitHub Discussions
• Contact options listed on this GitHub profile

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 ⚠️ 💻	Lucas @ StarkWare 💻	danilowhk 💻	Clément Walter 💻	Elias Tazartes 💻	drspacemn 💻	Mathieu 💻
TurcFort07 📖	Florian Bellotti 💻	Tom Brand 💻	ftupas 💻	pscott 💻	Robin Straub 💻	Francisco Krause Arnim 📖
joshualyguessennd 📖	Santiago Galván (Dub) 💻	chirag-bgh 💻	greged93 💻	bigherc18 💻	Lakhdar Slaim 💻	Lance N. Davis 💻
Tino Huynh 💻	Iris 💻	Alex Ponce 💻	glihm 💻	Paul-Henry Kajfasz 💻	Damián Piñones 💻	Betacodd 💻
Add your contributions

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