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 {