Skip to main content

Introduction to Subgraph and example queries

This page serves as a guide for getting the most out of the Stakehouse protocol subgraph. The subgraph is currently indexing the smart contract suite deployed on Goerli and Mainnet. Data points available include but are not limited to:

  • Stakehouse Accounts
  • Stakehouses - Validator Club
  • KNOTs - Validators that have minted derivatives
  • savETH Index Data - Groupings of KNOTs
  • Events - for plotting data

An out the box GraphQL playground for Goerlican be found here and for Mainnet can be found here

Any query seen in this document can be copied and pasted into the playground.

The document assumes basic knowledge about core concepts within the Stakehouse protocol. There is extensive documentation available to learn about the protocol but a quick summary:

  • A Stakehouse is a collection of validators tracked in a smart contract registry where a registry is deployed each time a depositor creates a new Stakehouse
  • A KNOT is just a validator that has joined a specific Stakehouse and minted derivative tokens on the execution chain
  • A Stakehouse account tracks the onboarding of a validator within the Stakehouse protocol
  • A savETH index is a user curated group of dETH assets attached to specific KNOTs. Any minted asset can always be traced back to a specific KNOT

Whilst this document is not an exhaustive list of queries, everything that can be possibly queried can be found from the GraphQL schema. Most of the standard GraphQL operations are available such as filtering, paging etc.

Global Universe Metadata

At a global level, the protocol smart contract addresses and performance metrics can be queried.

For example:

universeGlobalValues {

Some insight: This query is fetching the smart contract addresses for: TransactionRouter, DepositContract and dETH and is also fetching global counters for registered validators vs the number of created Stakehouses etc.

Stakehouse Accounts

As mentioned before, the onboarding process of a validator can be tracked via the Stakehouse Account entity. A validator may never create a KNOT and therefore it follows that if there is KNOT data, then there is always an associated account but not necessarily the other way around. Therefore, the Stakehouse Account is always a good place to start when it comes to getting information about a BLS public key registered within the Stakehouse protocol.

During the onboarding process, the validator will go through various lifecycle status:

  • Initials registered - Status 1
  • Deposit sent to Ethereum Deposit Contract - Status 2
  • Derivatives Minted - Status 3
  • Rage Quit - Status 4

Example query:

stakehouseAccounts(where: {
lifecycleStatus_gte: 2
}) {
stakeHouseMetadata {
knotMetadata {

Some context: This query is fetching all of the accounts that have at least done the deposit to the Ethereum Deposit Contract. It also gets:

  • The depositor which is the account that will receive the derivatives
  • Total dETH minted for the KNOT (if status is 3). This goes up as the user reports inflation rewards accrued on the beacon chain
  • Total SLOT which starts at 8 but can go down when a slashing has taken place
  • stakeHouseMetadata is set once a KNOT joins a Stakehouse and contains all of the house specific data. See the house section below.
  • knotMetadata is set once the KNOT transitions from deposited to minted. See the KNOT section below.

Another example query:

stakehouseAccounts(where: { id: "${id}", lifecycleStatus: 3, depositor: "${account}" }) {
stakeHouseMetadata {
  • id: BLS Public Key of the validator
  • totalDETHMintedFormatted: dETH that has been minted for the validator. When a new validator account is created, a total of 24 dETHs are minted in the user's savETH index.
  • totalSLOTFormatted: SLOTs minted for the validator. Exactly 8 SLOTs are minted per validator. 4 SLOTs will be held in the Stakehouse Vault under the user’s name and the other 4 SLOTs are minted as sETH into the user’s wallet.
  • totalCollateralizedSLOTInVaultFormatted: Out of the 8 SLOTs minted, the user will hold 4 SLOTs in the Stakehouse Vault which will bear slashing.
  • sETHMintedFormatted: Total amount of free floating sETH minted to the wallet of the user that registered the validator.
  • sETHCollaterlizedAtMintingFormatted: Total amount of sETH that is held in the Stakehouse Vault under the user's name just after the minting for a newly created validator.
  • stakehouseMetadata: Data related to the stakehouse that the validator has joined.
    • id: ETH Address of the Stakehouse
    • sETH: ETH Address of sETH token
    • sETHExchangeRateFormatted: Exchange rate from SLOT to sETH
    • sETHTicker: Ticker symbol used to identify the Stakehouse.

Stakehouse Metadata

To query specific information about a house such as the sETH token, its ticker, how many knots are in the house and how much is slashed, the following query can be executed:

stakeHouses {

Some context:

  • The id is the address of the registry of KNOTs
  • sETH is the house specific sETH token address
  • sETHPayoffRateFormatted - more info on this later. This needs to be 1 or the house is in trouble (slashings have taken place and the house is on fire)
  • totalAmountOfSlotSlashed Total amount of slashed SLOT that the market needs to top up

See the section on KNOTs for how to query which knots are part of the house.

KNOT metadata

Use this to establish all of the knots within the protocol, all of the knots of a specific house or even index and find out all you need to know about a knot.

For example:

knots(where: {
stakeHouse: "0x20c35a0aefea0cfef534450346545e7ff51aa99d"
}) {

This query fetches all of the KNOTs for a specific house ID but it does not have to. You can see whether it is part of a savETH index accruing high yield and what its coordinates are.

What are coordinates? As an example (9,6) is the coordinate for the 6th KNOT in the 9th house. Coordinates will become ubiquitous with arbitrageurs crawling the protocol for opportunities.


Events are data points created every time something happens within the protocol. Every time a new house is created, a new KNOT is created, dETH minted, SLOT slashed and more, this is the data feed for parsing what happened where.

All events have the following data available:

  • Transaction Hash (as the id field)
  • Who executed the transaction
  • What block number
  • What BLS public key it relates to
  • Key
  • Value

The key is a string to describe the event, the value is some specific data point related to the event.

For example, let's query all of the times dETH was minted from a balance report:

events(where: {
}, orderBy: blockNumber, orderDirection: desc) {

This gives all of the events where dETH inflation rewards were reported ordered from newest to oldest. It's very easy to plot this on a graph. We can also plot the number of houses created per day, the number of validators per day. The data mining possibilities are endless!

Events keys that can be indexed:


And many more added all the time