Subgraph

Developer documentation for the Rare Protocol Subgraph on The Graph.

Introduction

What is it?

The Graph is a decentralized protocol for indexing and querying data from blockchains. It allows developers to query data that would otherwise be cumbersome or costly to fetch directly from smart contracts. A subgraph defines the specific data The Graph will index from the blockchain and how it will store it. Once deployed, a subgraph provides a convenient GraphQL endpoint for data queries.

This guide outlines how to interact with Rare Protocol's Staking Subgraph, focusing on data indexed from several contracts, including the staking pool creation factory, and reward accumulators.

What is it for?

You should use the Rare Protocol Subgraph to query the current state of on-chain staking activity, such as pools, stakes, and rewards. It is not good for past data, user data, timeseries, analytics, or metadata (how to use the API). It also does not include transactions occurring on the bazaar marketplace or NFT contracts.

Prerequisites

Before you begin, you should have:

• Familiarity with GraphQL and TypeScript.

• Node.js and TypeScript installed on your system.

Accessing the Rare Protocol Subgraph on Mainnet

The following section covers the official Rare Protocol Subgraph, and is best for querying pools, staking events, tokens from SuperRare users, and more. For data on SuperRare marketplace events, please see the SuperRare subgraph below. Details, including schema and available queries on the Rare Protocol Subgraph, are available at the following URL

https://thegraph.com/explorer/subgraphs/Cc4fyxiBkZYdzATQDhTv3zLzfEwRupygp7HB2WWQciw5?view=Playground&chain=arbitrum-one

This next url is your gateway to querying staking data indexed by the Rare Protocol subgraph.

https://gateway-arbitrum.network.thegraph.com/api/[api-key]/subgraphs/id/Cc4fyxiBkZYdzATQDhTv3zLzfEwRupygp7HB2WWQciw5

API keys are required to query data from Subgraphs. You can create/manage API keys after signing up for The Graph's Subgraph Studio. https://thegraph.com/studio/apikeys/

Accessing the Subgraph on Sepolia

Access our testnet subgraph at the following URL

https://api.studio.thegraph.com/query/51818/rare-protocol-sepolia/v0.0.1

Schema Documentation

The schema documents the data structure for queries, emphasizing Pools and Stakes as key entities.

Once you have an api key, explore the schema and test queries using Apollo's environment:

https://studio.apollographql.com/

Getting Started

Step 1: Install Dependencies

First, install Apollo Client and GraphQL: Open your terminal and run the following command in your project directory:

$ npm install @apollo/client graphql

This will install Apollo Client and the GraphQL library, which are recommended to connect and interact with the GraphQL server.

Step 2: Set Up Apollo Client

Create a new TypeScript module named client.ts. This module will set up the Apollo Client. Insert the following code:

import {
  ApolloClient,
  InMemoryCache,
  gql,
  ApolloQueryResult,
} from '@apollo/client'

const client = new ApolloClient({
  uri: `https://gateway-arbitrum.network.thegraph.com/api/${YOUR_API_KEY_HERE}/subgraphs/id/Cc4fyxiBkZYdzATQDhTv3zLzfEwRupygp7HB2WWQciw5`,
  cache: new InMemoryCache(),
})

Replace ${YOUR_API_KEY} with your actual API key.

This code initializes an instance of Apollo Client, pointing to the GraphQL API endpoint and setting up a cache with InMemoryCache.

Step 3: Define the Query and Types Next, define the GraphQL query and the corresponding TypeScript types for the response. This helps with type-safety and autocompletion in TypeScript. Add the following to your client.ts:

type GqlPoolResponse = {
  stakingAddress
  userStakedOn
  totalRareLocked
  totalRewards
}

Step 4: Execute the Query

Now, execute a query using the Apollo Client. We will query for a list of pool data sorted by total $RARE staked. Append this code to your client.ts:

client
  .query({
    query: gql`
      query Pools($orderBy: Pool_orderBy, $orderDirection: OrderDirection) {
        pools(orderBy: $orderBy, orderDirection: $orderDirection) {
          stakingAddress
          userStakedOn
          totalRareLocked
          totalRewards
        }
      }
    `,
    variables: {
      orderBy: 'totalRareLocked',
      orderDirection: 'desc',
    },
  })
  .then((result: ApolloQueryResult<GqlPoolResponse>) =>
    console.log(JSON.stringify(result))
  )

This code sends a query to the subgraph and logs the response. The query method takes an object with two properties: query and variables. The query is defined using the gql template literal tag, and the variables object provides the specific target addresses.

Step 5: Run Your Code

To run your code, simply execute the client.ts script using Node.js or any TypeScript execution environment. You should see the query result output to your console.

$ npx ts-node client.ts

With this you've successfully set up your environment and executed a query to our GraphQL API using Apollo Client in TypeScript. This basic setup can be expanded to include more complex queries as needed for your application.

Accessing the SuperRare Subgraph on Mainnet

Thanks to user ethafrica.eth, a community-built subgraph offering data on marketplace events is available. It is currently only available for mainnet.

https://thegraph.com/explorer/subgraphs/8QaCygBoQ3XsQq8XxF1i6HPYTUHFFhHB9vrF3KvdRXST?view=Playground&chain=mainnet