Wildcard Indexing & Topic Filtering

Wildcard indexing is a feature that allows you to index all events matching a specified event signature without requiring the contract address from which the event was emitted. This is useful in cases such as indexing contracts deployed through factories, where the factory contract does not emit any events upon contract creation. It also enables indexing events from all contracts implementing a standard (e.g. all ERC20 transfers).

note

Wildcard Indexing is only supported from HyperIndex v2.3 onwards.
Wildcard Indexing is supported for Indexers using HyperSync as data source.
Wildcard indexing is not yet supported for Indexer using RPC as data source.

Example

Say for example we want to index all Transfer events we can use the following config:

name: transefer-indexer
networks:
  - id: 1
    start_block: 0
    contracts:
      - name: ERC20
        handler: ./src/EventHandlers.ts
        events:
          - event: "Transfer(address indexed from, address indexed to, uint256 value)"

We can write the following event handler:

TypeScript

// ./src/EventHandlers.ts
import { ERC20 } from "generated";

ERC20.Transfer.handler(async ({ event, context }) => {
  //... your handler logic
  },
  { wildcard: true },
);

JavaScript

// ./src/EventHandlers.js
const { ERC20 } = require("generated");

ERC20.Transfer.handler(async ({ event, context }) => {
  //... your handler logic
  },
  { wildcard: true },
);

ReScript

// ./src/EventHandlers.res
Handlers.ERC20.Transfer.handler(async ({ event, context }) => {
  //... your handler logic
  },
  ~eventConfig={ wildcard: true },
)

The expected outcome is that all Transfer events will be indexed, regardless of the contract address from which the event was emitted.

Filtering Example

On top of this, you can also add filters to the event handler. A filter field will be provided for each "indexed" parameter on the given event. Say for instance you only want to index "Mint" "Transfer" events where the from address is equal to 0x0000000000000000000000000000000000000000 you can add a filter to the event handler:

TypeScript

// ./src/EventHandlers.ts
import { ERC20 } from "generated";

const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";

ERC20.Transfer.handler(
  async ({ event, context }) => {
    //... your handler logic
  },
  { wildcard: true, eventFilters: { from: ZERO_ADDRESS } },
);

JavaScript

// ./src/EventHandlers.js
const { ERC20 } = require("generated");

const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";

ERC20.Transfer.handler(
  async ({ event, context }) => {
    //... your handler logic
  },
  { wildcard: true, eventFilters: { from: ZERO_ADDRESS } },
);

ReScript

// ./src/EventHandlers.res
open Types.SingleOrMultiple

let zeroAddress = Address.unsafeFromString("0x0000000000000000000000000000000000000000")

Handlers.ERC20.Transfer.handler(
  async ({ event, context }) => {
    //... your handler logic
  },
  ~eventConfig={
    wildcard: true,
    eventFilters: single({ from: single(zeroAddress) }),
  },
)

Multiple Filters Example

Multiple filters are also supported. For example, if you wanted to index all Mint/Burn events for a group of whitelisted addresses you can do the following:

TypeScript

// ./src/EventHandlers.ts
import { ERC20 } from "generated";

const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";

const WHITELISTED_ADDRESSES = [
  "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
  "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
  "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC"
];

ERC20.Transfer.handler(
  async ({ event, context }) => {
    //... your handler logic
  },
  { wildcard: true, 
    eventFilters: [
      { from: ZERO_ADDRESS, to: WHITELISTED_ADDRESSES },
      { from: WHITELISTED_ADDRESSES, to: ZERO_ADDRESS }
    ]
  },
);

JavaScript

// ./src/EventHandlers.js
const { ERC20 } = require("generated");

const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";

const WHITELISTED_ADDRESSES = [
  "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
  "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
  "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC"
];

ERC20.Transfer.handler(
  async ({ event, context }) => {
    //... your handler logic
  },
  { wildcard: true, 
    eventFilters: [
      { from: ZERO_ADDRESS, to: WHITELISTED_ADDRESSES },
      { from: WHITELISTED_ADDRESSES, to: ZERO_ADDRESS }
    ]
  },
);

ReScript

// ./src/EventHandlers.res
open Types.SingleOrMultiple

let zeroAddress = Address.unsafeFromString("0x0000000000000000000000000000000000000000")

let whitelistedAddresses = [
  Address.unsafeFromString("0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"),
  Address.unsafeFromString("0x70997970C51812dc3A010C7d01b50e0d17dc79C8"),
  Address.unsafeFromString("0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC")
]

Handlers.ERC20.Transfer.handler(
  async ({ event, context }) => {
    //... your handler logic
  },
  ~eventConfig={
    wildcard: true,
    eventFilters: multiple([
      { from: single(zeroAddress), to: multiple(whitelistedAddresses) },
      { from: multiple(whitelistedAddresses), to: single(zeroAddress) }
    ]),
  },
)

Contract Register Example

The same can be applied to contractRegister and handlerWithLoader APIs. Here is an example where we only register Uniswap pools that contain DAI token:

TypeScript

// ./src/EventHandlers.ts
import { UniV3Factory } from "generated";

const DAI_ADDRESS = "0x6B175474E89094C44Da98b954EedeAC495271d0F";

UniV3Factory.PoolCreated.contractRegister(
  async ({ event, context }) => {
    const poolAddress = event.params.pool;
    context.UniV3Pool.add(poolAddress);
  },
  { eventFilters: [{ token0: DAI_ADDRESS }, { token1: DAI_ADDRESS }] },
);

JavaScript

// ./src/EventHandlers.js
const { UniV3Factory } = require("generated");

const DAI_ADDRESS = "0x6B175474E89094C44Da98b954EedeAC495271d0F";

UniV3Factory.PoolCreated.contractRegister(
  async ({ event, context }) => {
    const poolAddress = event.params.pool;
    context.UniV3Pool.add(poolAddress);
  },
  { eventFilters: [{ token0: DAI_ADDRESS }, { token1: DAI_ADDRESS }] },
);

ReScript

// ./src/EventHandlers.res
open Types.SingleOrMultiple

let daiAddress = Address.unsafeFromString("0x6B175474E89094C44Da98b954EedeAC495271d0F")

Handlers.UniV3Factory.PoolCreated.contractRegister(
  async ({ event, context }) => {
    let poolAddress = event.params.pool
    context.UniV3Pool.add(poolAddress)
  },
  ~eventConfig={
    eventFilters: multiple([
      { token0: single(daiAddress) },
      { token1: single(daiAddress) }
    ])
  },
)

Handler With Loader Example

For handlerWithLoader API simply add wildcard or eventFilters to the loader function:

ERC20.Transfer.handlerWithLoader({
  loader: async ({ event, context }) => {},
  handler: async ({ event, context }) => {},
  wildcard: ...,
  eventFilters: ...,
});
}

Limitations

• For any given network, only one event of a given signature can be indexed using wildcard indexing. This means that if you have multiple contract definitions in your config that contain the same event signature. Only one of them is allowed to be set to wildcard: true

• Either the contractRegister or the handler function can take an event config object (with wildcard/eventFilters fields) but not both.

• RPC sync is not yet supported for wildcard indexing.