This is a guide on how to run a Berachain 🐻 ⛓️ node for the bArtio testnet.

Berachain nodes consist of a consensus client and an execution client. The consensus client is called beacon-kit and the execution client can be any of the ethereum clients (go-ethereum, reth, nethermind, etc). At Ghost, we run both go-ethereum and reth nodes, and for this guide we'll use reth.

You can run a node that syncs from genesis if you want, or you can use a snapshot that we created that'll help you sync much faster.

Install dependencies​

Make sure you your machine has go and rust installed because we'll be compiling beacon-kit and reth

1. Install go (minimum version v1.22.4)
2. Install rust (minimum version v1.79.0)

Download snapshot​

The Ghost team has created a snapshot you can use. The snapshot has both the consensus layer state (for beacon-kit) and the execution layer state (for reth)

sudo apt-get install lz4

mkdir bera
cd bera

wget 'https://public-snapshots.ghostgraph.xyz/bera-testnet-20240815.tar.lz4'

tar --use-compress-program=lz4 -xvf bera-testnet-20240815.tar.lz4

ls bera-snapshot
## you should see:
## beacond-data reth-data

Build the clients​

Now lets build the consensus client (beacon-kit) and the execution client (we'll use reth)

## still in bera dir

git clone https://github.com/berachain/beacon-kit/
git clone https://github.com/paradigmxyz/reth

## build beacon-kit which will serve as the consensus client
cd beacon-kit
git checkout v0.2.0-alpha.2
make

## build reth which will serve as the execution client
cd ../reth
git checkout v1.0.1
cargo build --release

Run Reth​

cd ~/bera/reth/
./target/release/reth node \
	--datadir ../bera-snapshot/reth-data \
	--chain ../bera-snapshot/beacond-data/config/eth-genesis.json \
	--instance 2 \
	--http \
	--ws

If you have cast installed you can confirm the node is using the snapshot data

$ cast bn -r 'http://localhost:8544'
1517942

Run Beacon-kit​

cd ~/bera/beacon-kit

## generate priv_validator_key.json and priv_validator_state.json files
## we'll use the beacon-kit init command
## in a temp location and extract just these files

./build/bin/beacond init --home tmp-bera --chain-id 80084 tmp-bartio
cp tmp-bera/config/priv_validator_key.json ../bera-snapshot/beacond-data/config/
cp tmp-bera/data/priv_validator_state.json ../bera-snapshot/beacond-data/data/

## now let's run the consensus client

export [email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656,c28827cb96c14c905b127b92065a3fb4cd77d7f6@testnet-seeds.whispernode.com:25456,8a0fbd4a06050519b6bce88c03932bd0a57060bd@beacond-testnet.blacknodes.net:26656,d9903c2f9902243c88f2758fe2e81e305e737fb3@bera-testnet-seeds.nodeinfra.com:26656,[email protected]:26656,cf44af098820f50a1e96d51b7af6861bc961e706@berav2-seeds.staketab.org:5001,6b5040a0e1b29a2cca224b64829d8f3d8796a3e3@berachain-testnet-v2-2.seed.l0vd.com:21656,4f93da5553f0dfaafb620532901e082255ec3ad3@berachain-testnet-v2-1.seed.l0vd.com:61656,[email protected]:26656

./build/bin/beacond start \
  --home ../bera-snapshot/beacond-data \
  --beacon-kit.engine.jwt-secret-path ../bera-snapshot/reth-data/jwt.hex \
  --beacon-kit.engine.rpc-dial-url http://127.0.0.1:8651 \
  --p2p.seeds $P2P_SEEDS \
  --p2p.seed_mode

Disclaimer​

This guide is being provided as is. The codebases (beacon-kit, reth) that it references are open source but are not written by this author. They may have bugs. The guide also may have bugs and may not work on your system. No guarantee, representation or warranty is being made, express or implied, as to the safety or correctness. It has not been audited and as such there can be no assurance it will work as intended, and users may experience delays, failures, errors, omissions or loss of transmitted information. Nothing in these docs should be construed as investment advice or legal advice for any particular facts or circumstances and is not meant to replace competent counsel. It is strongly advised for you to contact a reputable attorney in your jurisdiction for any questions or concerns with respect thereto. Author is not liable for any use of the foregoing, and users should proceed with caution and use at their own risk.

Smart contracts store and make visible their onchain state. How can we read this state?

We can, of course, use an RPC endpoint to call the contract's view methods directly, and for many use-cases this is sufficient.

But in some cases we need to read some kind of derived state that isn't explicitly stored onchain. For example, let's say we wanted to create a leaderboard UI for an onchain app and rank by user PnL. A global sorted leaderboard isn't typically stored onchain but we can derive it by creating an indexer (using GhostGraph for example).

At a high level, the indexer ingests event data from smart contracts, transforms it, and stores it into a database that you can query. GhostGraph makes this super easy.

In this tutorial, we'll leverage GhostGraph to build an indexer that automatically ingests and transforms contract events and then we'll hook it up to a frontend UI.

Project Context​

For this tutorial we'll reference SuperBlurBattlerz which is an onchain app that runs on Blast L2.

Pre-requisites​

If you haven't already, sign up for a new GhostGraph account here.

Need Help?​

If you are stuck at any time, feel free to join our Telegram for help.

Visual learner?​

Check out our YouTube video that walks you through the steps in less than 3 minutes!

All Set? Let's Go!​

Log in to GhostGraph. Once logged in, navigate to the Library tab. Here, you'll see existing community graphs that you can fork into your workspace as templates.

Click on the fork button to create a copy of this GhostGraph in your own workspace.

Go to the Indexes tab and click on the box to navigate to the code editor.

Code Editor​

Events.sol​

Smart contracts emit events for users to consume. Here, we define the events we want to track.

Schema.sol​

The schema file allows us to define entities as Solidity structs. Here, we have User, Race, and Bet entities. Think of an entity as an object with many properties. Entities are the things that we'll create and keep updated (we'll see how exactly in the next section). Entities are what we can query after deployment. So for example, by storing users and their PnL we'll be able to use GraphQL to sort all users by descending PnL.

Indexer.sol​

Once you've reviewed the events and schema, we can move on to indexer.sol where the core indexing logic will reside. In this file, we register the contract addresses that we want to listen to events from. Take a look at the registerHandles function.

We also write transformations that are called for each different type of event (remember we defined events in events.sol). Inside these functions we can get an entity, update it based on the values from the event and then save the entity.

Go ahead and review the transformations to understand them.

Compile and Deploy​

After reviewing every file, compile and deploy your GhostGraph. After a few seconds, your GhostGraph should be fully deployed and synchronized with the chain. You'll see how many entities are stored in your graph and have access to various buttons for further exploration.

Next, click on the playground button to launch your GraphQL playground.

GraphQL Playground​

Copy and paste the query below into your playground and click on the big pink play button to query your graph.

If you'd like, explore more and change queries to query different entities stored in the graph.

query GetAllUsers {
  users(
    orderBy: "winningAmount",
    orderDirection:"desc",
    limit: 100
  ) {
    items {
      totalBetAmount
      winningAmount
      id
    }
  }
}

Now that we have our backend set up with our indexer/graph ready, let's hook it up with our frontend.

Frontend Setup​

• Download the frontend repo on GitHub
• Open the command line and run git clone https://github.com/chrischang/gg-graphql-template.git
• Follow the README.md to install the dependencies and clone the environment

Environment Variables​

There are two environmental variables that you need:

1. REACT_APP_GHOST_GRAPH_URL
2. REACT_APP_GHOST_GRAPH_KEY

REACT_APP_GHOST_GRAPH_URL​

In the code editor, after the indexer has been deployed and synced, click on the Query button to get your query URL.

REACT_APP_GHOST_GRAPH_KEY​

Generate your key on the main GhostGraph dashboard.

All Together​

Your .env file should look like this:

REACT_APP_GHOST_GRAPH_URL=`https://api.ghostlogs.xyz/gg/pub/<queryUrl>/ghostgraph`
REACT_APP_GHOST_GRAPH_KEY=`<apiKey>`

(Optional) If You Made Modifications to Your GhostGraph, Follow These Steps​

Copy schema.graphql​

In the GhostGraph code editor, find the schema.graphql file. Copy the entire file and replace the content of the schema.graphql file in your frontend repository.

Regenerate queries.tsx​

Generate the queries.tsx file by running npm run codegen. This will generate a queries.tsx file in the graphql/generated folder, which includes:

• Typings
• React hooks

You can use these to build your frontend.

Let's run the app​

Run PORT=3001 npm run start in the command line of the frontend repo. This should automatically open a browser tab and navigate to http://localhost:3001. If not, manually open a tab and navigate there.

Voila​

Congratulations! You've successfully created an application connecting GhostGraph to your frontend, showcasing the PNL Leaderboard.

Closing Comments​

What other features or improvements would you like to see on this leaderboard?

Join our Telegram and share your ideas with us!.

Welcome to Ghost! We are rebuilding the indexing stack including two products:

1. GhostGraph: Our blazingly fast way to spin up an index (subgraph) for smart contracts. All in Solidity!

2. GhostLogs: Permissionless edit mode that enables anyone to define and emit custom gasless events even after contract deployment.

We are glad that you found us because you are still early