Beerus

Beerus is a Starknet Light Client inspired by and using helios.

News

29/02/24: Migrate to the Starknet v0.6.0 OpenRPC spec, release Beerus v0.4.0
17/01/24: Eiger is taking over Beerus!

Getting Started

Running Beerus for the first time

Copy the configuration file from etc/conf/beerus.toml and set up the RPC provider URLs in the copy. Make sure that providers are compatible. Read more about providers here

Then run:

cargo run --release -- -c ./path/to/config.toml

Once Beerus has started to verify that everything is working correctly, run this command:

hurl etc/rpc/starknet_getStateRoot.hurl

Configuration

field	example	description
network	MAINNET or SEPOLIA	network to query
eth_execution_rpc	https://eth-mainnet.g.alchemy.com/v2/{YOUR_API_KEY}	untrusted l1 node provider url
starknet_rpc	https://starknet-mainnet.g.alchemy.com/starknet/version/rpc/v0.6/{YOUR_API_KEY}	untrusted l2 node provider url
data_dir	tmp	`OPTIONAL` location to store both l1 and l2 data
poll_secs	5	`OPTIONAL` seconds to wait for querying sn state
rpc_addr	127.0.0.1:3030	`OPTIONAL` local address to listen for rpc reqs
fee_token_addr	0x049d36...e004dc7	`OPTIONAL` fee token to check for `getBalance`

When you select a network, check that eth_execution_rpc and starknet_rpc urls also point to their corresponding networks. For example:

MAINNET

eth_execution_rpc = "https://eth-mainnet.g.alchemy.com/v2/{YOUR_API_KEY}"
starknet_rpc = "https://starknet-mainnet.g.alchemy.com/starknet/version/rpc/v0.6/{YOUR_API_KEY}"

SEPOLIA

eth_execution_rpc = "https://eth-sepolia.g.alchemy.com/v2/{YOUR_API_KEY}"
starknet_rpc = "https://starknet-sepolia.g.alchemy.com/starknet/version/rpc/v0.6/{YOUR_API_KEY}"

RPC providers

Beerus relies on TWO untrusted RPC endpoints, one for L1 (Ethereum), and one for L2 (Starknet). As these are untrusted they will typically not be nodes run on your local host or your local network.

Starknet RPC endpoint

Beerus requires the v0.6.0 of the Starknet OpenRPC specs.

Starknet RPC provider must also support the Pathfinder's extension API pathfinder_getProof endpoint.

You can check if the provider is compatible by running this command:

# This is an example RPC url. Use your RPC provider url to check if the node is compatible.
STARKNET_RPC_URL="https://starknet-sepolia.g.alchemy.com/starknet/version/rpc/v0.6/{YOUR_API_KEY}"
curl --request POST \
     --url $STARKNET_RPC_URL \
     --header 'content-type: application/json' \
     --data '
{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "pathfinder_getProof",
  "params": [
    {
      "block_number": 56072
    },
    "0x07cb0dca5767f238b056665d2f8350e83a2dee7eac8ec65e66bbc790a4fece8a",
    [
        "0x01d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470"
    ]
  ]
}
'

If you get a response similar to the one below, then the provider is not compatible.

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "method 'pathfinder_getProof' not found"
  }
}

We recommend using one of these providers:

More API providers can be found here.

Ethereum RPC endpoint

For the Ethereum RPC provider, there are no special requirements. The provider must support Ethereum JSON-RPC Specification

NOTE: we rely on helios for both valid checkpoint values and consensus rpc urls

Development

Build

cargo build --all --release

Test

cargo test --all

Docker

docker build . -t beerus

docker run -e NETWORK=<arg> -e ETH_EXECUTION_RPC=<arg> -e STARKNET_RPC=<arg> -it beerus

Examples

ALCHEMY_API_KEY='YOURAPIKEY' cargo run --example basic
ALCHEMY_API_KEY='YOURAPIKEY' cargo run --example call

Beerus JS (wasm demo)

Dependencies:

npm
CORS bypass
local pathfinder node at http://localhost:9545
execution env var - ETH_EXECUTION_RPC

cd etc/wasm

# 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

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.

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 💻
_{Godspower-eze} 💻	_{somthn0somthn} 💻	_tonypony220 💻
Add your contributions