Oikos Queries

This library provides React hooks for retrieving data from the Oikos subgraph with full TypeScript support and real-time updates. It relies on codegen-graph-ts and react-query to provide access to all of the entities on the subgraph, as well as some more advanced queries.

Usage

Install @tanstack/react-query and @synthetixio/queries.

npm i @tanstack/react-query @synthetixio/queries

Add QueryClientProvider and OikosQueryContextProvider in a wrapping component.

import {
  createQueryContext,
  OikosQueryContextProvider,
} from '@synthetixio/queries'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
const queryClient = new QueryClient()

export default function MyApp() {
  return (
      <QueryClientProvider client={queryClient}>
        <OikosQueryContextProvider
          value={createQueryContext({
            networkId: 1 // Options: 1 (Mainnet), 10 (Optimism), 42 (Kovan), 69 (Optimism Kovan),42 (Goerli) and 69 (Optimism Goerli)
          })}
        >
          <Component />
        </OikosQueryContextProvider>
      </QueryClientProvider>
  )
}

In a child component, import hooks from the useOikosQueries() function.

import useOikosQueries from '@synthetixio/queries'

export default function Component() {
  const { subgraph } = useOikosQueries()
  const result = subgraph.useGetDebtStates(
    { first: 1, orderBy: 'timestamp', orderDirection: 'desc' },
    { totalIssuedSynths: true },
  )

  return (
    <div>
      <strong>Value of Total Issued Synths:</strong>{' '}
      {result.isSuccess
        ? result.data[0].totalIssuedSynths.toNumber().toLocaleString('en-US', {
            style: 'currency',
            currency: 'USD',
          })
        : 'Loading...'}
    </div>
  )
}

Subgraph Queries

useOikosQueries().subgraph contains two methods for each entity on the Oikos Subgraph, one for querying individual entities and another for groups. They are generated by the codegen-graph-ts library. For example, you can retrieve the daily candles for any synth with the useOikosQueries().subgraph.useGetDailyCandleById() and useOikosQueries().subgraph.useGetDailyCandles() hooks.

Note that IDs follow different conventions depending on the entity. See the comments in the GraphQL file or the implementation of the mappings for more information.

Each of the functions anticipate 2-3 parameters. The first parameter specifies the arguments for the GraphQL query. The second parameter specifies the fields for the GraphQL query as a JSON object with field names as keys set to true. Optionally, pass react-query options as a third parameter.

See the playground to explore the data available on the subgraph.

Advanced Queries

This library also exports advanced queries that can involve multiple entities and calculations. For example, useOikosQueries().getDebtTimeseries() provides the amount of debt issued by a given wallet address over time in USD and as a proportion of the total network debt at the time.

See the src/queries directory for all of the advanced queries exported by the library.