https://github.com/eigerco/beerus
A stateless trustless Starknet light client in Rust 🦀
https://github.com/eigerco/beerus
ethereum library lightclient starknet storage-proof
Last synced: 5 days ago
JSON representation
A stateless trustless Starknet light client in Rust 🦀
- Host: GitHub
- URL: https://github.com/eigerco/beerus
- Owner: eigerco
- License: mit
- Created: 2022-11-09T13:59:01.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-01T17:12:47.000Z (22 days ago)
- Last Synced: 2025-04-14T07:05:37.145Z (9 days ago)
- Topics: ethereum, library, lightclient, starknet, storage-proof
- Language: Rust
- Homepage:
- Size: 14.6 MB
- Stars: 260
- Watchers: 6
- Forks: 88
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-rust - beerus - Beerus is a trustless StarkNet Light Client, âš¡blazing fast âš¡ [](https://github.com/eigerco/beerus/actions/workflows/test.yml) (Applications / Blockchain)
- awesome-ccamel - eigerco/beerus - A stateless trustless Starknet light client in Rust 🦀 (Rust)
- awesome-rust - beerus - Beerus is a trustless StarkNet Light Client, âš¡blazing fast âš¡ [](https://github.com/eigerco/beerus/actions/workflows/check.yml) (Applications / Blockchain)
- fucking-awesome-rust - beerus - Beerus is a trustless StarkNet Light Client, âš¡blazing fast âš¡ [](https://github.com/eigerco/beerus/actions/workflows/check.yml) (Applications / Blockchain)
- fucking-awesome-rust - beerus - Beerus is a trustless StarkNet Light Client, âš¡blazing fast âš¡ [](https://github.com/eigerco/beerus/actions/workflows/test.yml) (Applications / Blockchain)
README
### UPDATE: 2025-02-07
*Hey everyone,*
*We wanted to share that the team at Eiger will be putting development on Beerus on hold for now.*
*With Starknet’s work on consensus and zk proof verification still in progress, we believe it’s best to pause Beerus until the specs are finalized.
We’ve truly enjoyed working on Beerus and are incredibly grateful to everyone who’s been part of the journey so far. Thank you for your support, insights, and contributions! We’re excited for what’s ahead.*---
[](https://github.com/eigerco/beerus/actions/workflows/check.yml)
Beerus
Beerus is a stateless and (soon to be completely) trustless Starknet Light Client.
## Project updates
At the beginning of 2024 [Eiger](https://www.eiger.co/) 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](https://t.me/BeerusStarknet)
* 2025-JAN-21: Switch to L2 network (instead of L1) and release [v0.7.0](https://github.com/eigerco/beerus/releases/tag/v0.7.0).
* 2024-AUG-28: Migrate to the [Starknet v0.7.1 OpenRpc spec](https://github.com/starkware-libs/starknet-specs/tree/v0.7.1).
* 2024-JUN-18: "Beerus Reborn": brand new Beerus with RPC Codegen, Stateless Execution, State Proof Verification, release [v0.5.0](https://github.com/eigerco/beerus/releases/tag/v0.5.0)
* 2024-FEB-29: Migrate to the [Starknet v0.6.0 OpenRPC spec](https://github.com/starkware-libs/starknet-specs/tree/v0.6.0)
* 2024-JAN-17: [Blog: Eiger takes responsibility over Beerus](https://www.eiger.co/blog/eiger-taking-over-ownership-for-beerus-working-on-starknet-light-clients)## 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](#rpc-providers)Then run:
```bash
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](https://github.com/starkware-libs/starknet-specs/tree/v0.7.1).Starknet RPC provider must also support the [Pathfinder's extension API](https://github.com/eqlabs/pathfinder#pathfinder-extension-api) `pathfinder_getProof` endpoint.
You can check if the provider is compatible by running this command:
```bash
# 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](https://docs.alchemy.com/reference/starknet-api-faq#what-versions-of-starknet-api-are-supported)
- [Chainstack](https://docs.chainstack.com/docs/starknet-tooling)
- [Reddio](https://docs.reddio.com/guide/node/starknet.html#grab-starknet-sepolia-endpoint)More API providers can be found [here](https://docs.starknet.io/documentation/tools/api-services/).
## Development
#### Build
```bash
cargo build --release
```#### Test
```bash
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
```bash
docker build . -t beerus
``````bash
docker run -e STARKNET_RPC= -it beerus
```#### Examples
```bash
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.