Zenchain Staking Indexer

This project indexes the Zenchain staking pallet and provides a comprehensive GraphQL API for interacting with staking-related data on the Zenchain Network, utilizing the SubQuery framework for indexing and querying blockchain data.

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

Description

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.yaml: Defines the key project configuration and mapping handler filters.
• 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-script dev. This does all of the following:

1. npm run codegen - Generates types from the GraphQL schema definition and contract ABIs and saves them in the /src/types directory. This must be done after each change to the schema.graphql file or the contract ABIs.
2. npm run build - Builds and packages the SubQuery project into the /dist directory.
3. docker-compose pull && docker-compose up - 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: 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: REWARDED_DESC) {
      nodes {
        validator
        rewarded
        validatorPrefs {
          commission
        }
      }
    }
  }
}

Query worst performing validators for an era (most slashed)

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

Query low performance validators based on earned reward points

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

Query all the nominators kicked by specific validators

{
  stashes(filter: { status: Validator }) {
    nodes {
      id
      kickedNominators {
        nominator {
          id
        }
        timestamp
      }
    }
  }
}

Query the staking contract details

{
  stakingContract(id: "staking-contract-address") {
    id
    validatorCount
    minValidatorBond
    minNominatorBond
    minActiveStake
    currentEra {
      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.
• ValidatorPrefs: Validator preferences including commission and blocked status.

2) Era Overview

These entities capture details that change with every staking era.

• Era: Overview of each staking era including payouts and total stakes.
• EraPagedValidatorExposure: 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.

3) Event Overview

These entities log various staking events to provide raw details for finer querying of data that couldn't be retrieved via overviews.

• EraPaidEvent: Event when an era is paid out.
• RewardedEvent: Event when rewards are distributed.
• SlashedEvent: Event when slashing occurs.
• SlashReportedEvent: Event when a slash is reported.
• OldSlashingReportDiscardedEvent: Event when an old slashing report is discarded.
• StakersElectedEvent: Event when stakers are elected.
• BondedEvent: Event when bonding occurs.
• UnbondedEvent: Event when unbonding occurs.
• WithdrawnEvent: Event when withdrawals occur.
• KickedEvent: Event when a nominator is kicked.
• StakingElectionFailedEvent: Event when a staking election fails.
• ChilledEvent: Event when a staker chills.
• PayoutStartedEvent: Event when a payout starts.
• ValidatorPrefsSetEvent: Event when validator preferences are set.
• SnapshotVotersSizeExceededEvent: Event when the size of snapshot voters is exceeded.
• SnapshotTargetsSizeExceededEvent: Event when the size of snapshot targets is exceeded.
• ForceEraEvent: Event when the mode of era forcing is changed.
• ControllerBatchDeprecatedEvent: Event when a controller batch is deprecated.

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.