HyperIndex Documentation

HyperSync is the underlying data engine for HyperIndex and is enabled by default for all supported networks. Unlike standard RPC calls that fetch data block-by-block, HyperSync retrieves multiple data points per round trip with advanced filtering.

Key benefits:

• Up to 2000x faster sync speeds.
• Lower infrastructure costs.
• No rate limit issues on supported networks.

HyperSync can also be used independently of HyperIndex as a custom data pipeline in Python, Rust, Node.js, and Go.

This template demonstrates three fundamental patterns for building Solana indexers with HyperIndex:

1. Configuration: Declaring a Solana program and its instructions in config.yaml using ecosystem: svm and the experimental.programs[].instructions[] schema.
2. Instruction Handling: Using indexer.onInstruction({program, instruction}, handler) to intercept and process positional accounts and raw instruction data.
3. State Persistence: Persisting per-instruction state to typed entities (e.g., TokenMetadataAccount) and maintaining counters (e.g., ProgramStats).

HyperIndex supports legacy Anchor format (pre-0.30) IDLs. These IDLs contain top-level keys like name, version, instructions, accounts, types, events, and errors.

Key characteristics of legacy IDLs:

• They do not contain a top-level address field.
• They do not contain metadata.spec or per-instruction discriminator byte arrays.
• HyperIndex computes the 8-byte discriminator itself using sha256("global:<snake_case_name>")[..8] during decoding.
• Because legacy IDLs omit the program_id, you must provide the program_id manually in your config.yaml to pair it with the IDL.

A HyperIndex project is defined by three primary files:

1. config.yaml: Defines networks, contracts, events, and specific indexing behavior.
2. schema.graphql: Defines the shape of your indexed data (the GraphQL schema).
3. src/handlers: Contains your custom logic for processing events, written in TypeScript, JavaScript, or ReScript.

Envio uses a licensing model that provides open-source-like benefits but is not OSI-recognized. The model is designed to allow developers to avoid vendor lock-in while protecting Envio's hosted services and HyperSync business model.

To avoid dependency on Envio's hosted services, developers can:

1. Self-host: The licenses permit self-hosting of the indexers.
2. Specify an RPC URL: By specifying an RPC URL in the indexer configuration, you bypass HyperSync and run the indexer independently.

Note that while the generated code is open and public, the code generator itself is under a commercial license.

HyperIndex allows you to index contracts that are deployed dynamically by a factory contract (e.g., Uniswap V3 Pools) without needing to pre-define their addresses.

To implement this, use the indexer.contractRegister handler. This handler listens for the specific event emitted by the factory contract that contains the new contract's address. Inside the handler, you use the context.chain.<contract-name>.add(<address>) method to register the new instance with the indexer.

indexer.contractRegister(
  { contract: "UniswapV3Factory", event: "PoolCreated" },
  async ({ event, context }) => {
    context.chain.UniswapV3Pool.add(event.params.pool);
  },
);

The Effect API allows you to perform external calls (such as RPC calls or API requests) directly from within your indexer handlers. These calls execute in the handler context and support built-in features like caching and rate limiting to optimize performance and prevent hitting external API limits.

To use an effect, you first define it using createEffect and then invoke it within a handler using context.effect(EFFECT_NAME, INPUT_DATA).

indexer.onEvent({ contract: "CONTRACT", event: "EVENT" }, async ({ event, context }) => {
  const effectOutput = await context.effect(YOUR_EFFECT, EFFECT_INPUTS);
});

Before running the template, ensure your environment meets the following requirements:

• Node.js: v22+ (v24 is recommended)
• pnpm: v8 or newer
• Container Runtime: Docker or Podman

To execute the minimal SVM scenario, which demonstrates the indexer.onSlot API and the SVM-specific filter decoder located in packages/envio/src/Main.res, follow these steps in your terminal:

1. Install dependencies using pnpm.
2. Generate the necessary code using the envio codegen command.
3. Execute the tests.

Note: This scenario is designed to test SVM-specific logic within the Envio framework.

pnpm install
pnpm exec envio codegen
pnpm test

To start a new indexing project, use the envio init command. This scaffolds the entire project structure, including configuration, schema, and handler functions. You can generate an indexer from a specific contract address, use pre-defined templates, or start from an existing example.

Requirements:

• Node.js
• Docker (required only for local development)

Command:

pnpx envio init