hydra
Search…
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:
1
import { DatabaseManager } from '@dzlzv/hydra-db-utils'
2
import { Post } from '../generated/graphql-server/src/modules/post/post.model'
3
4
import { Posts } from './generated/types'
5
export async function postCreated(
6
db: DatabaseManager,
7
event: Posts.PostCreatedEvent
8
) {
9
const post = new Post()
10
post.author = event.data.accountId.toHex()
11
post.id = event.data.postId.toString()
12
if (event.ctx.extrinsic === undefined) {
13
throw new Error(`No extrinsic has been provided`)
14
}
15
// get type-safe call data out of the untyped extrinsic data
16
const call = new Posts.CreatePostCall(event.ctx)
17
post.content = call.args.content.toString()
18
await db.save<Post>(post)
19
}
Copied!
Add and install all the necessary dependencies for the mappings (e.g. the types library) and build the mappings:
1
yarn workspace sample-mappings add ...
2
yarn workspace sample-mappings install
3
yarn mappings:build
Copied!

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:
1
query {
2
indexerStatus {
3
chainHeight
4
head
5
hydraVersion
6
}
7
}
Copied!
Last modified 8mo ago