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 Goerli
can 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:
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:
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 chainTotal SLOT which starts at 8 but can go down when a slashing has taken place
PowerStaking
Metadata
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:
Copy
id
: BLS Public Key of the validatortotalDETHMintedFormatted
: 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.PowerStaking
Metadata
: Data related to the PowerStaking that the validator has joined.id
: ETH Address of the PowerStakingsETH
: ETH Address of sETH tokensETHExchangeRateFormatted
: Exchange rate from SLOT to sETHsETHTicker
: 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:
Copy
Some context:
The
id
is the address of the registry of KNOTssETH
is the house specific sETH token addresssETHPayoffRateFormatted
- more info on this later. This needs to be1
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:
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:
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
Last updated