Zenchain Staking Indexer

This project indexes the Zenchain staking, fastUnstake, and session pallets, providing a comprehensive GraphQL API for interacting with staking-related data on the Zenchain Network. It utilizes the SubQuery framework for indexing and querying blockchain data.

This project indexes all staking-related events on the Zenchain Network

Description

The Zenchain Staking GraphQL API is designed to index and provide access to all staking-related events on the Zenchain Network. This allows developers to query detailed staking information such as validator preferences, staking rewards, slashing events, and more through a simple GraphQL interface.

Installation

First, install SubQuery CLI globally on your terminal by using NPM: npm install -g @subql/cli

You can either clone this GitHub repo, or use the subql CLI to bootstrap a clean project in the network of your choosing by running subql init and following the prompts.

Don't forget to install dependencies with nvm use && npm install and initialize your local environment variables with cp .env.example .env! They have placeholder values and need to be properly set: CHAIN_ID is the Genesis Block and ENDPOINT is a Websocket API endpoint of an Archive RPC node. The correct CHAIN_ID will be displayed in terminal output after the application fails to startup once when connected to an Archive RPC node.

Project Structure

The project structure includes the following key components:

• project.ts: Defines the key project configuration and mapping handler filters in TypeScript.
• schema.graphql: Defines the shape of the resulting data that you are using SubQuery to index.
• src/mappings/: Contains TypeScript functions that handle transformation logic.

SubQuery supports various layer-1 blockchain networks and provides dedicated quick start guides as well as detailed technical documentation for each of them.

Running Locally

The simplest way to run the project is by running npm run dev. This does all of the following:

1. npm run codegen - Generates types from the GraphQL schema definition and saves them in the /src/types directory. This must be done after each change to the schema.graphql file.
2. npm run build - Builds and packages the SubQuery project into the /dist directory.
3. docker-compose pull && docker-compose up --remove-orphans - Runs a Docker container with an indexer, PostgreSQL DB, and a query service. This requires Docker to be installed and running locally. The configuration for this container is set from your docker-compose.yml.

You can observe the three services start, and once all are running (it may take a few minutes on your first start), please open your browser and head to http://localhost:3000 - you should see a GraphQL playground showing with the schemas ready to query. Read the docs for more information or explore the possible service configuration for running SubQuery.

Example Query

For this project, you can try the following GraphQL query to get a taste of how it works.

Query top 5 nominators by their stake

{
  stashes(first: 5, orderBy: TOTAL_BONDED_DESC, filter: { status: { equalTo: Nominator }}) {
    totalCount
    nodes {
      id
      status
      totalBonded
      totalRewarded
      totalSlashed
    }
  }
}

Query most rewarded top 10 validators for an era

{
  era(id: "era-id") {
    validators(first: 10, orderBy: REWARD_POINTS_DESC) {
      nodes {
        validator
        rewardPoints
        commission
        rewarded {
          amount
        }
      }
    }
  }
}

Query worst performing validators for an era (most slashed)

{
  era(id: "era-id") {
    validators(first: 10, orderBy: SLASHED_DESC) {
      nodes {
        validator
        slashed
        commission
      }
    }
  }
}

Query low performance validators based on earned reward points

{
  era(id: "era-id") {
    validators(first: 10, orderBy: REWARD_POINTS_ASC) {
      nodes {
        validator
        rewardPoints
        commission
      }
    }
  }
}

Query all the nominators kicked by a validator

{
  kickedEvents(filter: { stash: { equalTo: "validator-id" } }, orderBy: TIMESTAMP_DESC) {
    nodes {
      nominator
      stash
      timestamp
    }
  }
}

Query the staking contract details

{
  stakingContract(id: "0x0000000000000000000000000000000000000800") {
    id
    validatorCount
    minValidatorBond
    minNominatorBond
    minActiveStake
    activeEra {
      id
      totalPayout
      validatorPayout
      remainderPayout
    }
  }
}

You can explore the different possible queries and entities to help you with GraphQL using the documentation draw on the right.

Entity Overviews

1) Staking Overview

These entities capture the overall staking details and do not change frequently, only during special events such as bonding, unbonding, etc.

• StakingContract: Overall staking overview, constants, and current state.
• Stash: Details about stashes, including their status, bonded amounts, and rewards.
• Nomination: Relationships between validators and nominators.
• ValidatorKeys: History of session keys for a validator.

2) Era Overview

These entities capture details that change with every staking era.

• Era: Overview of each staking era including payouts and total stakes.
• EraValidatorExposure: Exposure details for validators in a given era.
• EraPagedNominationExposure: Paged snapshot of the stake backing a single validator in the system.
• EraNominationExposure: Portions of nominators' stashes exposed to a validator.
• EstimatedValidatorRewardPayout: Estimated reward payout for a validator in an era.

3) Indexed Events

These are the events that the indexer listens to. They are grouped by the pallet that emits them.

Staking Pallet Events

• staking.NewEra: Starts a new staking era, creating an Era entity and ending the previous one.
• staking.EraPaid: Signals that an era has been paid out. Creates an EraPaidEvent entity and updates the corresponding Era entity.
• staking.Rewarded: Signals that rewards have been distributed to a staker. Creates a RewardedEvent entity and updates the Stash and era exposure entities.
• staking.Slashed: A staker has been slashed. Creates a SlashedEvent entity and updates the Stash entity.
• staking.SlashReported: A slash has been reported. Creates a SlashReportedEvent entity.
• staking.OldSlashingReportDiscarded: An old slashing report has been discarded. Creates an OldSlashingReportDiscardedEvent entity.
• staking.StakersElected: A new set of stakers has been elected. Creates a StakersElectedEvent entity.
• staking.Bonded: A stash has bonded some funds. Creates a BondedEvent entity and updates the Stash entity.
• staking.Unbonded: A stash has unbonded some funds. Creates an UnbondedEvent entity and updates the Stash entity.
• staking.Withdrawn: A stash has withdrawn unbonded funds. Creates a WithdrawnEvent entity.
• staking.Kicked: A nominator has been kicked by a validator. Creates a KickedEvent entity.
• staking.StakingElectionFailed: The staking election has failed. Creates a StakingElectionFailedEvent entity.
• staking.Chilled: A staker has been chilled. Creates a ChilledEvent entity and updates the Stash status to Idle.
• staking.PayoutStarted: A payout for a validator has started. Creates a PayoutStartedEvent entity.
• staking.ValidatorPrefsSet: A validator has set their preferences. Creates a ValidatorPrefsSetEvent entity and updates the Stash entity.
• staking.ValidatorCountSet: The validator count has been set. Updates the StakingContract entity.
• staking.InvulnerablesSet: The set of invulnerable validators has been updated. Updates the relevant Stash entities.
• staking.StashKilled: A stash has been killed. Updates the Stash entity.
• staking.Nomination: A nominator has nominated a new set of validators. Creates or updates Nomination entities.
• staking.MinCommissionSet: The minimum commission has been set. Updates the StakingContract entity.
• staking.RewardDestinationSet: The reward destination for a stash has been set. Updates the Stash entity.
• staking.StakingConfigsSet: The staking configurations have been set. Updates the StakingContract entity.
• staking.SnapshotVotersSizeExceeded: The size of snapshot voters has been exceeded. Creates a SnapshotVotersSizeExceededEvent entity.
• staking.SnapshotTargetsSizeExceeded: The size of snapshot targets has been exceeded. Creates a SnapshotTargetsSizeExceededEvent entity.
• staking.ForceEra: The mode of era forcing has been changed. Creates a ForceEraEvent entity and updates the StakingContract.
• staking.ControllerBatchDeprecated: A controller batch has been deprecated. Creates a ControllerBatchDeprecatedEvent entity.

FastUnstake Pallet Events

• fastUnstake.Registered: A stash has registered for fast unstaking. Creates a FastUnstaking_RegisteredEvent entity.
• fastUnstake.Deregistered: A stash has deregistered from fast unstaking. Creates a FastUnstaking_DeregisteredEvent entity.
• fastUnstake.Unstaked: A fast unstake has been completed. Creates a FastUnstaking_UnstakedEvent entity.
• fastUnstake.Slashed: A fast unstaking stash has been slashed. Creates a FastUnstaking_SlashedEvent entity.

Session Pallet Events

• session.KeysSet: Session keys have been set for a validator. Creates a ValidatorKeys entity.
• session.KeysPurged: Session keys have been purged for a validator. Updates a ValidatorKeys entity.

Need Help?

The fastest way to get support is by searching our documentation, or by joining our discord and messaging us in the #technical-support channel.