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