Beerus

Beerus is a stateless and (soon to be completely) trustless Starknet Light Client.

Project updates

At the beginning of 2024 Eiger took over the ownership of the Beerus repository and leadership of the project. Beerus was started by the Starkware Exploration Team and we are grateful for their trust and the excellent work they have done.

One of our goals is to integrate Beerus into web-based wallets, enabling users to switch seamlessly to a light client mode. This transition is crucial for those who prefer not to rely on untrusted RPC providers, a critical step to trustless operation.

We post development updates on the Telegram channel

• 2025-JAN-21: Switch to L2 network (instead of L1) and release v0.7.0.
• 2024-AUG-28: Migrate to the Starknet v0.7.1 OpenRpc spec.
• 2024-JUN-18: "Beerus Reborn": brand new Beerus with RPC Codegen, Stateless Execution, State Proof Verification, release v0.5.0
• 2024-FEB-29: Migrate to the Starknet v0.6.0 OpenRPC spec
• 2024-JAN-17: Blog: Eiger takes responsibility 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 it is up and running, try this request:

curl -H 'Content-type: application/json' -d'{
    "jsonrpc": "2.0",
    "method": "starknet_getStateRoot",
    "params": [],
    "id": 1
}' http://127.0.0.1:3030

The successful result should look similar to the one below:

{"jsonrpc":"2.0","result":"0x539895aff28be4958188c1d4e8e68ee6772bdd49dd9362a4fbb189e61c54ff1","id":1}

Configuration

field	example	description
starknet_rpc	https://starknet-mainnet.g.alchemy.com/starknet/version/rpc/v0_7/{YOUR_API_KEY}	Starknet service provider URL
gateway_url	https://alpha-mainnet.starknet.io	OPTIONAL Feeder Gateway base URL
data_dir	tmp	OPTIONAL location to store both L1 and L2 data
poll_secs	5	OPTIONAL seconds to wait for querying sn state, min = 1 and max = 3600
rpc_addr	127.0.0.1:3030	OPTIONAL local address to listen for rpc reqs

RPC provider

Beerus relies on Starknet RPC service provider and on Feeder Gateway URL.

Starknet RPC endpoint

Beerus expects serving the v0.7.1 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_7/{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:

• Alchemy
• Chainstack
• Reddio

More API providers can be found here.

Development

Build

cargo build --release

Test

cargo test

## Run integration tests against live endpoint
export STARKNET_MAINNET_URL=https://starknet-mainnet.g.alchemy.com/starknet/version/rpc/v0_7/${ALCHEMY_API_KEY}
export STARKNET_SEPOLIA_URL=https://starknet-sepolia.g.alchemy.com/starknet/version/rpc/v0_7/${ALCHEMY_API_KEY}
BEERUS_TEST_RUN=1 cargo test

Docker

docker build . -t beerus

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

Examples

ALCHEMY_API_KEY='YOURAPIKEY' cargo run --release --example call
ALCHEMY_API_KEY='YOURAPIKEY' cargo run --release --example state

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.