Writing Event Handlers

Once the configuration and schema files are in place, run

envio codegen

in the project directory to generate the functions you will use in your handlers.

Each event requires two functions to be registered:

1. loader function
2. handler function

Loader function

Loader functions are called via

Javascript

<ContractName>Contract.<EventName>.loader

Typescript

<ContractName>Contract_<EventName>_loader

Rescript

<ContractName>Contract.<EventName>.loader

Loader functions are used to load the specific entities (defined in the schema.graphql) that should be modified by the event.

Entities with specific IDs can be loaded via context.<entityName>.<label>Load(<id>).

If no label name has been defined in the config.yaml file, then entities can be loaded via context.<entityName>.load(<id>).

A single event can be used to modify single or multiple entities.

Each entity that is to be modified by the event must be defined in the requiredEntities field of the event in the config.yaml file.

Handler function

Handler functions are called via

Javascript

<ContractName>Contract.<EventName>.handler

Typescript

<ContractName>Contract_<EventName>_handler

Rescript

<ContractName>Contract.<EventName>.handler

Handler functions are used to modify the entities which have been loaded by the loader function, and thus should contain all the required logic for updating entities with the raw data emitted by the event.

All of the parameters emitted in each event are accessible via event.params.<parameterName>.

Additional raw event information can also be accessed via event.<rawInfo>.

Below is a list of raw event information that can be accessed:

• blockHash
• blockNumber
• blockTimestamp
• chainId
• eventId
• eventType
• logIndex
• srcAddress
• transactionHash
• transactionIndex

Handler functions can access the loaded entities information via context.<entityName>.<label>Load.

If no label name has been defined in the config.yaml file, handler functions can access the loaded entities information via context.<entityName>.get(<id>).

Handler functions can also provides the following functions per loaded entity, that can be used to interact with that entity:

• set
• delete

which can be used as follows context.<entityName>.set(<entityObject>) and context.<entityName>.delete().

Greeter example

Inspecting the config.yaml of the NewGreeting event, it indicates that there is a defined requiredEntities field of the following:

events:
  - name: "NewGreeting"
    requiredEntities:
      - name: "Greeting"

Example of a Loader function for the NewGreeting event:

Javascript

let { GreeterContract } = require("../generated/src/Handlers.bs.js");

GreeterContract.NewGreeting.loader((event, context) => {
  context.greeting.load(event.params.user.toString());
});

Typescript

import { GreeterContract_NewGreeting_loader } from "../generated/src/Handlers.gen";

import { greetingEntity } from "../generated/src/Types.gen";

GreeterContract_NewGreeting_loader(({ event, context }) => {
  context.greeting.load(event.params.user.toString());
});

Rescript

open Types

Handlers.GreeterContract.NewGreeting.loader((~event, ~context) => {
  context.greeting.load(event.params.user->Ethers.ethAddressToString)
})

• Within the function that is being registered, the user must define the criteria for loading the greeting entity.
• This is made available to the user through the load entity context defined as contextUpdator.
• In the case of the above example, we load a Greeting entity that corresponds to the id passed from the event.

Example of registering a Handler function for the NewGreeting event:

Javascript

let { GreeterContract } = require("../generated/src/Handlers.bs.js");

GreeterContract.NewGreeting.handler((event, context) => {
  let existingGreeter = context.greeting.get(event.params.user.toString());

  if (existingGreeter != undefined) {
    context.greeting.set({
      id: event.params.user.toString(),
      latestGreeting: event.params.greeting,
      numberOfGreetings: existingGreeter.numberOfGreetings + 1,
      greetings: [...existingGreeter.numberOfGreetings, event.params.greeting],
    });
  } else {
    context.greeting.set({
      id: event.params.user.toString(),
      latestGreeting: event.params.greeting,
      numberOfGreetings: 1,
      greetings: [event.params.greeting],
    });
  }
});

Typescript

import { GreeterContract_NewGreeting_handler } from "../generated/src/Handlers.gen";

import { greetingEntity } from "../generated/src/Types.gen";

GreeterContract_NewGreeting_handler(({ event, context }) => {
(({ event, context }) => {
  let currentGreeter = context.greeting.get(event.params.user.toString());

  if (currentGreeter != null) {
    let greetingObject: greetingEntity = {
      id: event.params.user.toString(),
      latestGreeting: event.params.greeting,
      numberOfGreetings: currentGreeter.numberOfGreetings + 1,
      greetings: [...existingGreeter.numberOfGreetings, event.params.greeting],
    };

    context.greeting.set(greetingObject);
  } else {
    let greetingObject: greetingEntity = {
      id: event.params.user.toString(),
      latestGreeting: event.params.greeting,
      numberOfGreetings: 1,
      greetings: [event.params.greeting],
    };
    context.greeting.set(greetingObject);
  }
});

Rescript

open Types

Handlers.GreeterContract.NewGreeting.handler((~event, ~context) => {
  let currentGreeterOpt = context.greeting.get(event.params.user->Ethers.ethAddressToString)

  switch currentGreeterOpt {
  | Some(existingGreeter) => {
      let greetingObject: greetingEntity = {
        id: event.params.user->Ethers.ethAddressToString,
        latestGreeting: event.params.greeting,
        numberOfGreetings: existingGreeter.numberOfGreetings + 1,
        greetings: existingGreeter.greetings->Belt.Array.concat([event.params.greeting]),
      }

      context.greeting.set(greetingObject)
    }

  | None =>
    let greetingObject: greetingEntity = {
      id: event.params.user->Ethers.ethAddressToString,
      latestGreeting: event.params.greeting,
      numberOfGreetings: 1,
      greetings: [event.params.greeting],
    }

    context.greeting.set(greetingObject)
  }
})

• Once the user has defined their loader function, they are then able to retrieve the loaded entity information.
• In the above example, if a Greeting entity is found matching the load criteria in the loader function, it will be available via greetingWithChanges.
• This is made available to the user through the handler context defined simply as context.
• This context is the gateway by which the user can interact with the indexer and the underlying database.
• The user can then modify this retrieved entity and subsequently update the Greeting entity in the database.
• This is done via the context using the function (context.greeting.set(greetingObject)).
• The user has access to a greetingEntity type that has all the fields defined in the schema.

---