Migration to Hydra v2

A guide for migrating your mapping from Hydra v1 to Hydra v2


All 0.x Hydra packages (a bit counter-intuitively) are considered Hydra v1. Since Hydra v2 (that is, versions 2.x) all Hydra packages (hydra-cli, hydra-common, hydra-typegen etc) recieve the same version on each release. So, say, Hydra version 2.0.1 means that all the packages together with the Docker images hydra-indexer and hydra-indexer-gateway are taged 2.0.1

What's new in Hydra v2

The key differences to keep in mind while migrating from v1 to v2:

  • Hydra Processor is NOT generated by hydra-cli in v2

  • Hydra Processor is run against a manifest file manifest.yml

  • Mappings should be transpiled into a JS module

  • hydra-indexer and hydra-indexer-gateway should be updated to v2

See examples of Hydra v2 in action here


  • Install the latest hydra-cli v2

  • Run hydra-cli scaffold --silent to generate a stub of a v2 Hydra project

  • Run yarn


Nothing new here. Simply run yarn codegen

Typegen for events

Update typegen section in manifest.yml

  • List events and calls to which the types should be generated

  • Add customTypes if needed:

    • lib: from where the generated classes should import additional substrate types

    • typedefsLoc: path the type definitions

Install the types library: cd mappings && yarn add <type library>

Run yarn typegen

Mapping files

Change mappings arguments: DB should be converted to DatabaseManager imported from @dzlzv/hydra-db-utils

Replace event: SubstrateEvent with a typed class generated by typegen in the previous step. The event data is now available at event.data

Whenever the corresponding extrinsic data is needed, use event.ctx.extrinsic and create a type-safe Call class out of it. Here is an example:

import { DatabaseManager } from '@dzlzv/hydra-db-utils'
import { Post } from '../generated/graphql-server/src/modules/post/post.model'
import { Posts } from './generated/types'
export async function postCreated(
db: DatabaseManager,
event: Posts.PostCreatedEvent
) {
const post = new Post()
post.author = event.data.accountId.toHex()
post.id = event.data.postId.toString()
if (event.ctx.extrinsic === undefined) {
throw new Error(`No extrinsic has been provided`)
// get type-safe call data out of the untyped extrinsic data
const call = new Posts.CreatePostCall(event.ctx)
post.content = call.args.content.toString()
await db.save<Post>(post)

Add and install all the necessary dependencies for the mappings (e.g. the types library) and build the mappings:

yarn workspace sample-mappings add ...
yarn workspace sample-mappings install
yarn mappings:build

Manifest file

Inspect and update the default manifest.yml

  • (Optional) Update dataSource.chain

  • For each mapping, update the function name and the event it is handling

  • Add extrinsicHandlers if needed

Indexer and Indexer-Gateway

Use the latest v2.x Docker images (2.0.1-beta.9 at the time of writing). Check the indexer status by running the following GraphQL query:

query {
indexerStatus {