[P0] Implement Subgraph Indexing Support (The Graph Protocol Compatible)

[BlocksScanIO]

Feature Request: Subgraph Indexing Support

Background

Competitor Analysis Reference: Goldsky, The Graph, Envio

Goldsky and The Graph have established subgraphs as the standard for indexing blockchain data. XDC Gateway lacks this capability, forcing developers to build custom indexing solutions.

Requirements

Core Functionality

• The Graph protocol-compatible subgraph hosting
• GraphQL API for indexed data queries
• Automatic reorg handling and rollback
• IPFS-based subgraph deployment
• CLI tool for subgraph deployment (xdc-subgraph)

Subgraph Features

• Manifest: subgraph.yaml configuration
• Schema: GraphQL schema definition
• Mappings: AssemblyScript/TypeScript event handlers
• Data Sources: XDC Network (EVM-compatible)

Technical Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   XDC Node      │────▶│  Indexer Agent  │────▶│  PostgreSQL     │
│   (RPC/WS)      │     │  (Go/Rust)      │     │  (Entity Store) │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌─────────────────┐
                        │  Graph Node     │
                        │  (Query Engine) │
                        └─────────────────┘
                               │
                               ▼
                        ┌─────────────────┐
                        │  GraphQL API    │
                        │  /subgraphs/    │
                        └─────────────────┘

Implementation Components

1. Indexer Agent (Go)

package indexer

type Indexer struct {
    rpcClient     *ethclient.Client
    subgraphStore *SubgraphStore
    blockCache    *BlockCache
    eventHandlers map[string]EventHandler
    reorgHandler  *ReorgHandler
}

type Subgraph struct {
    ID            string
    Manifest      *Manifest
    Schema        *graphql.Schema
    Mappings      map[string]Mapping
    StartBlock    uint64
    CurrentBlock  uint64
    Status        IndexingStatus
    CreatedAt     time.Time
}

2. GraphQL Query Engine

package graphql

type QueryEngine struct {
    schema    *graphql.Schema
    resolvers map[string]Resolver
    db        *pgx.Pool
}

// Example query
query {
  transfers(first: 10, where: {from: "0x..."}) {
    id
    from
    to
    value
    blockNumber
    timestamp
  }
}

3. Database Schema

-- Subgraphs table
CREATE TABLE subgraphs (
    id VARCHAR(64) PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    manifest JSONB NOT NULL,
    schema TEXT NOT NULL,
    start_block BIGINT NOT NULL,
    current_block BIGINT DEFAULT 0,
    status VARCHAR(20) DEFAULT 'syncing',
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- Indexing progress
CREATE TABLE indexing_status (
    subgraph_id VARCHAR(64) REFERENCES subgraphs(id),
    chain_head_block BIGINT,
    latest_block BIGINT,
    synced BOOLEAN DEFAULT FALSE,
    health VARCHAR(20),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- Dynamic entity tables created per subgraph

CLI Tool: xdc-subgraph

# Install
npm install -g @xdc/subgraph-cli

# Initialize
xdc-subgraph init my-subgraph --protocol xdc

# Codegen
xdc-subgraph codegen

# Build
xdc-subgraph build

# Deploy
xdc-subgraph deploy \
  --node https://gateway.xdc.network/subgraphs \
  --ipfs https://ipfs.xdc.network \
  my-subgraph

# Status
xdc-subgraph status my-subgraph

# Logs
xdc-subgraph logs my-subgraph --tail

Subgraph Manifest Example

specVersion: 0.0.4
schema:
  file: ./schema.graphql
dataSources:
  - kind: ethereum
    name: XRC20Token
    network: xdc
    source:
      address: "0x..."
      abi: XRC20
      startBlock: 50000000
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.6
      language: wasm/assemblyscript
      entities:
        - Transfer
        - Balance
      abis:
        - name: XRC20
          file: ./abis/XRC20.json
      eventHandlers:
        - event: Transfer(indexed address,indexed address,uint256)
          handler: handleTransfer
      file: ./src/mapping.ts

Performance Targets

• Indexing Latency: <2 seconds from block to indexed
• Query Latency: <50ms for simple queries, <200ms for complex
• Throughput: 1000+ indexing operations/sec
• Reorg Handling: Automatic within 50 blocks

Reorg Handling Strategy

func (i *Indexer) handleReorg(newChain []*types.Block) error {
    // 1. Detect reorg by checking block hash continuity
    // 2. Rollback affected entities to last known good block
    // 3. Re-index from fork point
    // 4. Update entity versions for consistency
}

Acceptance Criteria

• Deploy The Graph node compatible with XDC
• CLI tool for subgraph lifecycle management
• GraphQL playground for testing queries
• Support for 100+ concurrent subgraphs
• Automatic reorg handling verified
• Documentation and example subgraphs

Competitor Comparison

Feature	Goldsky	The Graph	Envio	XDC Gateway (Target)
Subgraphs	✅	✅	✅	🔄 Planned
Latency	Sub-second	Seconds	Sub-second	<2s
Reorg Handling	Automatic	Automatic	Manual	Automatic
Self-Hosted	❌	✅	✅	✅
XDC Support	❌	❌	❌	✅

References

• The Graph Documentation
• Goldsky Subgraphs
• Envio Indexer

Priority: P0 - Critical for dApp developer ecosystem
Estimated Effort: 12 weeks
Labels: enhancement, indexing, P0, subgraphs, graphql