Quai Subgraph Integration

A subgraph is fundamentally three promises: structured access to chain data, event-driven transformation, and a GraphQL surface your app can query. Quai delivers the first promise natively — go-quai nodes ship with a built-in GraphQL API, exposed for mainnet at graph.quai.network, covering blocks, transactions, and state without any indexing infrastructure of your own.

For the second and third promises, Quai's answer today is custom indexers built on the quais SDK. A WebSocketProvider with usePathing subscribes to logs and blocks across zone chains as they land — roughly every five seconds — and contract event listeners transform and persist exactly the entities your app needs. Backfills use queryFilter over historical ranges, mirroring how subgraph handlers replay past events. Quaiscan, the network's Blockscout-style explorer, adds a second ready-made dataset for transactions, addresses, and verified contracts.

The Graph's hosted service and graph-node do not yet index Quai — graph-node expects the eth_ RPC namespace, while Quai nodes serve quai_ methods across a hierarchy of chains. Teams that structure their indexer as event handlers writing to a database keep a clean migration path for whenever that compatibility lands.

1. 1

   Start with the node's GraphQL API

   For blocks, transactions, and account state, query the built-in GraphQL endpoint before building anything — it may already answer your question.

   {
     block {
       number
       hash
       transactions {
         hash
         from { address }
         to { address }
         value
       }
     }
   }

2. 2

   Subscribe to live events

   Open a WebSocket provider and attach contract event listeners. Each zone produces blocks about every five seconds, so data freshness is high.

   import { WebSocketProvider, Contract } from "quais";
   
   const provider = new WebSocketProvider("wss://rpc.quai.network", undefined, {
     usePathing: true,
   });
   const token = new Contract(TOKEN_ADDRESS, TOKEN_ABI, provider);
   
   token.on("Transfer", (from, to, value, payload) => {
     saveTransfer({ from, to, value, block: payload.log.blockNumber });
   });

3. 3

   Backfill history

   Replay past events in bounded ranges with queryFilter — the same pattern subgraph handlers use when syncing from a start block.

   const BATCH = 10_000;
   for (let from = START_BLOCK; from <= latest; from += BATCH) {
     const to = Math.min(from + BATCH - 1, latest);
     const events = await token.queryFilter("Transfer", from, to);
     await persist(events);
   }

4. 4

   Persist into your own schema

   Write transformed entities to Postgres (or your store of choice) and expose them to your app through your API layer — the part of a subgraph you fully control here.

5. 5

   Cross-check against Quaiscan

   Use quaiscan.io as the reference dataset to validate indexer completeness, and orchard.quaiscan.io while developing against testnet.

• Protocol dashboards

  TVL, volumes, and holder distributions aggregated from event streams — the classic subgraph workload, served from your own store.

• Wallet activity feeds

  Per-address transfer histories assembled from indexed Transfer events across the tokens your app cares about.

• DeFi position tracking

  Reconstruct positions from deposit, borrow, and liquidation events with five-second freshness from zone chains.

• Explorer-style products

  Purpose-built views over the node's GraphQL API and Quaiscan data — NFT galleries, token pages, governance trackers.

Live subscription plus historical backfill — the two halves of every subgraph, in one self-contained script on the quais SDK.

import { WebSocketProvider, Contract } from "quais";
import { db } from "./db.js";

const provider = new WebSocketProvider("wss://rpc.quai.network", undefined, {
  usePathing: true,
});
const token = new Contract(TOKEN_ADDRESS, TOKEN_ABI, provider);

// 1. Backfill — replay history in bounded ranges
const latest = await provider.getBlockNumber();
for (let from = START_BLOCK; from <= latest; from += 10_000) {
  const to = Math.min(from + 9_999, latest);
  for (const e of await token.queryFilter("Transfer", from, to)) {
    await db.transfers.upsert(serialize(e));
  }
}

// 2. Stream — handle new events as zone blocks land (~5s)
token.on("Transfer", async (from, to, value, payload) => {
  await db.transfers.upsert({
    from,
    to,
    value: value.toString(),
    block: payload.log.blockNumber,
  });
});