Subgraph Migration

Subgraph to HyperIndex Migration

Migrate from TheGraph subgraphs to Envio HyperIndex. HyperIndex delivers up to 100x faster indexing with a developer-friendly TypeScript API.

Migration Overview

Three major steps:

1. subgraph.yaml → config.yaml
2. Schema migration (near copy-paste)
3. Event handler migration (AssemblyScript → TypeScript)

Step 1: Config Migration

subgraph.yaml → config.yaml

TheGraph:

specVersion: 0.0.4
dataSources:
  - kind: ethereum/contract
    name: Factory
    network: mainnet
    source:
      address: "0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f"
      startBlock: 10000835
      abi: Factory
    mapping:
      eventHandlers:
        - event: PairCreated(indexed address,indexed address,address,uint256)
          handler: handlePairCreated
templates:
  - name: Pair
    source:
      abi: Pair

HyperIndex:

name: my-indexer
networks:
  - id: 1
    start_block: 10000835
    contracts:
      - name: Factory
        address: 0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f
        handler: src/factory.ts
        events:
          - event: PairCreated(address indexed token0, address indexed token1, address pair, uint256)
      - name: Pair
        handler: src/pair.ts  # No address - dynamic
        events:
          - event: Swap(...)

Key differences:

• Remove dataSources, templates, mapping nesting
• Use networks → contracts structure
• Event signatures include parameter names
• Dynamic contracts have no address field

Step 2: Schema Migration

Remove @entity decorator

# TheGraph
type Token @entity {
  id: ID!
  symbol: String!
}

# HyperIndex
type Token {
  id: ID!
  symbol: String!
}

Convert Bytes to String

# TheGraph
address: Bytes!

# HyperIndex
address: String!

Entity Relationships

# TheGraph
type Transfer @entity {
  token: Token!
}

# HyperIndex - use _id suffix
type Transfer {
  token_id: String!
}

Entity Arrays MUST have @derivedFrom

# TheGraph (sometimes implicit)
type Token @entity {
  transfers: [Transfer!]!
}

# HyperIndex - REQUIRED explicit @derivedFrom
type Token {
  transfers: [Transfer!]! @derivedFrom(field: "token")
}

type Transfer {
  token_id: String!  # The field referenced by @derivedFrom
}

Critical: Arrays without @derivedFrom cause codegen error EE211.

Step 3: Handler Migration

Basic Pattern

TheGraph (AssemblyScript):

export function handleTransfer(event: TransferEvent): void {
  let entity = new Transfer(event.transaction.hash.toHexString());
  entity.from = event.params.from;
  entity.to = event.params.to;
  entity.amount = event.params.value;
  entity.save();
}

HyperIndex (TypeScript):

import { MyContract } from "generated";

MyContract.Transfer.handler(async ({ event, context }) => {
  const entity = {
    id: `${event.chainId}-${event.transaction.hash}-${event.logIndex}`,
    from: event.params.from,
    to: event.params.to,
    amount: event.params.value,
    blockNumber: BigInt(event.block.number),
  };

  context.Transfer.set(entity);
});

Entity Loading

TheGraph:

let token = Token.load(id);
if (token == null) {
  token = new Token(id);
}

HyperIndex:

let token = await context.Token.get(id);
if (!token) {
  token = { id, name: "Unknown", /* ... */ };
}

Entity Updates

TheGraph:

token.totalSupply = newSupply;
token.save();

HyperIndex (use spread - entities are immutable):

context.Token.set({
  ...token,
  totalSupply: newSupply,
});

Dynamic Contract Registration

TheGraph:

import { Pair as PairTemplate } from "../generated/templates";
PairTemplate.create(event.params.pair);

HyperIndex:

// Register BEFORE handler
Factory.PairCreated.contractRegister(({ event, context }) => {
  context.addPair(event.params.pair);
});

Factory.PairCreated.handler(async ({ event, context }) => {
  // Handle event...
});

Contract State (RPC Calls)

TheGraph:

let contract = ERC20.bind(address);
let name = contract.name();

HyperIndex (use Effect API):

import { createEffect, S } from "envio";

export const getTokenName = createEffect({
  name: "getTokenName",
  input: S.string,
  output: S.string,
  cache: true,
}, async ({ input: address }) => {
  // Use viem for RPC calls
  const name = await client.readContract({
    address: address as `0x${string}`,
    abi: ERC20_ABI,
    functionName: "name",
  });
  return name;
});

// In handler
const name = await context.effect(getTokenName, address);

Common Migration Issues

Missing async/await

// WRONG - returns {} instead of entity
const token = context.Token.get(id);

// CORRECT
const token = await context.Token.get(id);

Field Selection for Transaction Data

# Add to config.yaml for event.transaction.hash access
events:
  - event: Transfer(...)
    field_selection:
      transaction_fields:
        - hash

Multichain ID Prefixes

// Always prefix with chainId for multichain
const id = `${event.chainId}-${originalId}`;

BigDecimal Precision

Maintain precision from original subgraph:

import { BigDecimal } from "generated";

const ZERO_BD = new BigDecimal(0);
const BigDecimal(1);

// Don't simplify to JavaScript numbers

Migration Checklist

• Convert subgraph.yaml to config.yaml
• Remove @entity decorators from schema
• Change Bytes! to String!
• Use _id suffix for relationships
• Add @derivedFrom to all entity arrays
• Add async to all handlers
• Add await to all context.Entity.get() calls
• Use spread operator for entity updates
• Replace Template.create() with contractRegister
• Add field_selection for transaction data
• Prefix IDs with chainId for multichain
• Convert contract bindings to Effect API

Additional Resources

Reference Files

For detailed migration patterns:

• references/migration-patterns.md - Complete pattern reference
• references/common-mistakes.md - Pitfalls and solutions

External Resources

• Full docs: https://docs.envio.dev/docs/HyperIndex-LLM/hyperindex-complete
• Migration guide: https://docs.envio.dev/docs/migration-guide
• Example indexers:
  • Uniswap v4: https://github.com/enviodev/uniswap-v4-indexer
  • Safe: https://github.com/enviodev/safe-analysis-indexer