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. 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 can be found here:

https://thegraph.com/hosted-service/subgraph/bswap-eng/stakehouse-protocol

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 {
    TransactionRouter
    DepositContract
    dETH
    numberOfRegisteredValidators
    numberOfKnots
    numberOfStakeHouses
  }
}

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 number of created houses 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 registerd 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
  }) {
    lifecycleStatus
    depositor
    totalDETHMintedFormatted
    totalSLOT
    stakeHouseMetadata {
      sETHTicker
    }
    knotMetadata {
      currentSlashedAmount
    }
  }
}

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}" }) {
    id
    totalDETHMintedFormatted
    totalSLOTFormatted
    totalCollateralizedSLOTInVaultFormatted
    sETHMintedFormatted
    sETHCollateralizedAtMintingFormatted
    stakeHouseMetadata {
      id
      sETH
      sETHExchangeRateFormatted
      sETHTicker
    }
  }
}

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 users 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

In order to query specific information about a house such as the sETH token, it's ticker, how many knots are in the house, how much is slashed, the following query can be executed:

{
  stakeHouses {
    id
    sETH
    sETHTicker
    sETHPayoffRateFormatted
    numberOfKnots
    totalAmountOfSlotSlashed
  }
}

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 in order 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"
  }) {
    id
    isPartOfIndex
    savETHIndexId
    coordinates
  }
}

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 acruing 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

Events are data points created every time something happens within the protocol. Every time a new house is created, a new KNOT created, dETH minted, SLOT slashed and more, this is the data feed for parsing what happned 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: {
    key: "DETH_REWARDS_MINTED"
  }, orderBy: blockNumber, orderDirection: desc) {
    id
    blockNumber
    blsPubKeyForKnot
    key
    value
  }
}

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

Events keys that can be indexed:

KNOT_TRANSFERRED_FROM_INDEX
DETH_REWARDS_MINTED
DETH_REWARDS_MINTED_IN_OPEN_INDEX
DETH_WITHDRAWN_INTO_OPEN_MARKET
KNOT_ADDED_INTO_OPEN_MARKET
KNOT_INSERTED_INTO_INDEX
INDEX_CREATED
INDEX_OWNERSHIP_TRANSFERRED
INITIALS_REGISTERED
DEPOSIT_REGISTERED
NEW_STAKEHOUSE_REGISTRY_DEPLOYED
NEW_HOUSE_MEMBER
NEW_HOUSE_MEMBER_AND_BRAND_CREATED
SLOT_SLASHED
SLOT_TOPPED_UP
RAGE_QUIT
RAGE_QUIT_BEFORE_CHECKPOINT_B

And many more added all the time

Global Universe Metadata​

Stakehouse Accounts​

Stakehouse Metadata​

KNOT metadata​

Events​

Global Universe Metadata

Stakehouse Accounts

Stakehouse Metadata

KNOT metadata

Events