Introduction to Subgraph and example queries

This page serves as a guide for getting the most out of the PowerStaking 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:

• PowerStaking Accounts

• PowerStakings - 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 PowerStaking protocol. There is extensive documentation available to learn about the protocol but a quick summary:

• A PowerStaking is a collection of validators tracked in a smart contract registry where a registry is deployed each time a depositor creates a new PowerStaking

• A KNOT is just a validator that has joined a specific PowerStaking and minted derivative tokens on the execution chain

• A PowerStaking account tracks the onboarding of a validator within the PowerStaking 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:

Explain{
  universeGlobalValues {
    TransactionRouter
    DepositContract
    dETH
    numberOfRegisteredValidators
    numberOfKnots
    numberOfPowerStakings
  }
}

Copy

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

PowerStaking Accounts​

As mentioned before, the onboarding process of a validator can be tracked via the PowerStaking 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 PowerStaking Account is always a good place to start when it comes to getting information about a BLS public key registered within the PowerStaking 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:

Explain{
  PowerStakingAccounts(where: {
    lifecycleStatus_gte: 2
  }) {
    lifecycleStatus
    depositor
    totalDETHMintedFormatted
    totalSLOT
    powerStakingMetadata {
      sETHTicker
    }
    knotMetadata {
      currentSlashedAmount
    }
  }
}

Copy

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

• PowerStakingMetadata is set once a KNOT joins a PowerStaking 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:

Explain{
  PowerStakingAccounts(where: { id: "${id}", lifecycleStatus: 3, depositor: "${account}" }) {
    id
    totalDETHMintedFormatted
    totalSLOTFormatted
    totalCollateralizedSLOTInVaultFormatted
    sETHMintedFormatted
    sETHCollateralizedAtMintingFormatted
    PowerStakingMetadata {
      id
      sETH
      sETHExchangeRateFormatted
      sETHTicker
    }
  }
}

Copy

• 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 PowerStaking 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 PowerStaking 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 PowerStaking Vault under the user's name just after the minting for a newly created validator.

• PowerStakingMetadata: Data related to the PowerStaking that the validator has joined.

  • id: ETH Address of the PowerStaking

  • sETH: ETH Address of sETH token

  • sETHExchangeRateFormatted: Exchange rate from SLOT to sETH

  • sETHTicker: Ticker symbol used to identify the PowerStaking.

PowerStaking 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:

Explain{
  PowerStakings {
    id
    sETH
    sETHTicker
    sETHPayoffRateFormatted
    numberOfKnots
    totalAmountOfSlotSlashed
  }
}

Copy

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:

Explain{
  knots(where: {
    PowerStaking: "0x20c35a0aefea0cfef534450346545e7ff51aa99d"
  }) {
    id
    isPartOfIndex
    savETHIndexId
    coordinates
  }
}

Copy

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​

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:

Explain{
  events(where: {
    key: "DETH_REWARDS_MINTED"
  }, orderBy: blockNumber, orderDirection: desc) {
    id
    blockNumber
    blsPubKeyForKnot
    key
    value
  }
}

Copy

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:

• 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_POWERSTAKING_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