Migration to Hydra v2

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

Versioning

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

Migration

• Install the latest hydra-cli v2

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

• Run yarn

Codegen

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 {
    chainHeight
    head
    hydraVersion
  }
}